Description
LEADr PMS Memory
Pacote n8n-nodes-leadr-pms: sub-node de memória para agentes n8n que lê e grava
mensagens pela API de um sistema de gestão de hospedagens (PMS). Usa
BufferWindowMemory com chat_history,
input, output e returnMessages: true.
O código do node é independente do projeto da API PMS. Este repositório contém
somente o pacote, seus testes e ferramentas de build.
Requisitos
- Node.js 22.13.0 ou superior.
- n8n com
n8n-workflow >=2.28.0 <3disponível no ambiente do pacote. - Uma chave de API do seu ambiente, com as permissões
conversations:read, conversations:write e guests:contact.
O pacote foi compilado com n8n-workflow 2.28.0, @langchain/classic 1.0.32
e @langchain/core 1.2.8. A versão do SDK n8n-workflow difere da versão do
aplicativo n8n; confira a compatibilidade do ambiente antes da instalação.
Configuração no n8n
1. Instale n8n-nodes-leadr-pms no ambiente do n8n.
2. Adicione LEADr PMS Memory e conecte sua saída Memory à entrada de
memória do agente.
3. Configure uma credencial do tipo Header Auth no n8n, usando o cabeçalho
Authorization e o valor Bearer . Selecione essa credencial
no node. O nome escolhido para ela é livre.
4. Informe o telefone do contato com código do país e da região. Use uma string
com 8–15 dígitos, opcionalmente precedida por um único +.
5. Ajuste Opções → Janela de Contexto se necessário. O padrão é 15 interações,
equivalente às últimas 30 mensagens.
A conta atendida é determinada pela chave de API, mantendo históricos separados
entre contas. Como em outros sub-nodes n8n, expressões podem resolver apenas o
primeiro item; processe um contato por execução do agente.
A comunicação usa HTTPS com TLS validado, redirecionamentos desativados e o
helper autenticado do n8n. O endpoint da API é definido pelo pacote; não há campo
para configurar outra URL. Não é necessário informar SQL, tabela ou identificador
da conta no node.
Comportamento
| Ação | API e resultado |
| --- | --- |
| Abrir memória | GET /contacts?phone=...; cria somente o contato mínimo com POST /contacts quando ausente. Preserva campos existentes. |
| Ler | GET /message-history?phone=...&limit=100&after=..., percorrendo páginas em ordem crescente. |
| Gravar | POST /message-history, com telefone e mensagem LangChain completa; usuário e resposta são gravados em sequência. |
| Limpar memória | Lista o histórico e executa DELETE /message-history/{id} com a versão de cada registro. Preserva contato e outros telefones. |
O histórico completo permanece disponível ao Chat Memory Manager. A janela afeta
somente o contexto do agente, sem expiração, resumo automático ou exclusão por
limite de contexto.
Consultas GET /contacts?phone=... e GET /message-history?phone=... aceitam
HTTP 200 com [] na raiz quando não há dados, além do formato existente
{data:{items:[],next_cursor:null}}. Contato ausente segue para a criação mínima;
histórico vazio fornece contexto vazio, e a limpeza sem mensagens não exclui nada.
Uma página final [] encerra a paginação preservando as mensagens já lidas.
Respostas inválidas, arrays não vazios na raiz, erros HTTP e respostas vazias de
escrita continuam gerando erro explícito.
Os serializadores LangChain preservam mensagens humanas, IA, sistema, ferramentas,
multimídia e metadados. São aceitos {type,data}, o legado {type,text} e o formato
plano {type,content,...}. A leitura normaliza o formato plano sem regravar o
histórico. Novas mensagens são gravadas em {type,data}. Registros incompatíveis
geram erro explícito, sem descartar mensagens silenciosamente.
Cada escrita recebe uma chave de idempotência. Falhas transitórias de rede ou
HTTP 500/502/503/504 permitem uma repetição com a mesma chave e corpo. Reexecutar
um workflow cria novas operações; mensagens iguais em eventos distintos continuam
sendo mensagens distintas.
Compatibilidade de telefones — 1.15.6
Entrada e respostas com ou sem um único + inicial identificam o mesmo telefone.
As quatro validações de identidade de GET /contacts, POST /contacts,
GET /message-history e POST /message-history comparam uma representação
normalizada comum. Telefones diferentes continuam sendo rejeitados.
O telefone deve ter 8–15 dígitos, sem zero inicial. A entrada também aceita
espaços, parênteses, pontos e hífens; os campos de identidade das respostas da API
aceitam somente dígitos e um + opcional no início.
A representação interna e os telefones enviados pelo node continuam sem +,
preservando as chaves existentes. Parâmetros de telefone usam encodeURIComponent
nas URLs (+ seria %2B); corpos JSON não usam essa codificação. A correção não
migra contatos ou históricos nem altera autenticação, isolamento, IDs, versões,
ordenação, serialização ou idempotência.
Desenvolvimento e testes
git clone https://github.com/LEADr-COMPANY/n8n-nodes-leadr-pms.git
cd n8n-nodes-leadr-pms
npm ci --ignore-scripts
npm test
npm pack
npm run test:install
npm test compila o pacote e executa testes com respostas HTTP simuladas, sem
acessar o n8n ou a API PMS. A suíte cobre contatos novos/existentes, histórico
vazio/preenchido, leitura, gravação e limpeza; combinações independentes de
telefone com/sem + nos quatro endpoints; entradas inválidas e identidade
divergente; paginação, IDs, versões, ordenação, isolamento por transporte
autenticado, corrida na criação e repetição após resposta perdida.
O teste integrado opcional (npm run test:integration) requer o código-fonte da
API e suas dependências em um ambiente de desenvolvimento separado. Usa handlers
reais e um banco PGlite isolado. Não é necessário para executar a suíte local
deste pacote.
Instalação por artefato
npm pack gera n8n-nodes-leadr-pms-. No ambiente do n8n, com o
usuário que executa o serviço:
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install /caminho/n8n-nodes-leadr-pms-.tgz
Reinicie o n8n após instalar. Em modo fila, disponibilize a mesma versão e suas
dependências no processo principal e nos workers. Em Docker, use a imagem ou um
local persistente de community nodes. Não copie apenas o arquivo .node.js.
O tipo do node é n8n-nodes-leadr-pms.pmsMemory. O build valida o nome do pacote:
escopos npm com ponto podem impedir que o carregador n8n resolva o tipo do node.
Para publicar no npm, com a conta autorizada para o pacote:
npm publish --access public
Publicar o repositório no GitHub não publica o pacote no npm nem instala o node
no n8n.
Publicação automática no npm
O workflow .github/workflows/publish.yml executa a cada push na branch main
e também pode ser iniciado manualmente na aba Actions. Ele instala as dependências,
calcula uma versão inédita, compila, executa os testes e prepara o pacote.
Antes de publicar, verifica a instalação do tarball e a atualização com o cache
de módulos ativo, usando a estratégia de instalação do n8n.
Com a autorização npm ativada, publica automaticamente como latest.
Atualizações de outras branches não publicam.
Se a versão do package.json for maior que todas as versões estáveis no npm,
essa versão será usada. Caso contrário, o workflow incrementa o patch da maior
versão estável publicada. Para uma mudança major/minor, altere a versão no projeto
antes do push. A versão de publicação é aplicada ao manifesto e lockfile no runner;
a automação não cria commits de versão em main. Reexecutar um commit já publicado
não cria uma versão duplicada. Execuções antigas não substituem um commit
descendente já publicado. Publicações são serializadas em uma fila de até
100 execuções pendentes; falhas de testes ou consulta ao registry interrompem o fluxo.
Após enviar o pacote, o workflow aguarda até 10 minutos pela validação assíncrona
do npm e confirma o commit da versão disponibilizada. Se o npm ainda mostrar
Validating após esse prazo, confira o status antes de repetir a publicação.
Autorização inicial
Para configurar a automação em um repositório sob sua administração, acesse as
configurações do pacote no npm com uma conta mantenedora e cadastre um
Trusted Publisher → GitHub Actions. Informe os dados do repositório que
executará a publicação:
publish.ymlnpm publishDepois, defina a variável de repositório NPMPUBLISHENABLED como true em
GitHub → Settings → Secrets and variables → Actions → Variables, e inicie
Publish to npm manualmente para validar a primeira publicação. Sem essa
variável, o workflow verifica o pacote e informa que a publicação está pendente;
não anuncia que publicou.
O workflow deste projeto restringe a execução ao repositório de origem. Em um
fork, ajuste essa condição e os metadados de repositório do package.json antes
de configurar a publicação de um pacote que você administra.
A autenticação usa OIDC, sem token npm permanente nos secrets. É necessário
concluir a primeira publicação dentro do prazo da configuração informado pelo npm.
Documentação: https://docs.npmjs.com/trusted-publishers/.
Limites
e limita-se a 1.000 páginas de 100 registros; exceder esse limite gera erro.
truncamento; binários grandes devem permanecer fora da memória.
a primeira mensagem.
interrompe a operação, preservando a versão alterada; registros anteriores
podem já ter sido removidos. Um 404 de registro já removido é tolerado.
Reset e recriação concorrente do mesmo telefone exigem coordenação externa;
a leitura paginada não é um snapshot transacional.
Limpar a memória não desfaz esses efeitos.
2 × k mensagens, inclusive mensagens de ferramentas.
