npm

Visão geral

O npm é o gerenciador de pacotes padrão do JavaScript e do Node.js, facilitando o compartilhamento e reuso de código, o gerenciamento de dependências e a automação de fluxos de trabalho em projetos de desenvolvimento. Com a integração npm no SquadOS, seus agentes podem consultar metadados de pacotes, verificar vulnerabilidades de segurança, acompanhar estatísticas de download e interagir com o registro npm de forma programática.

• Site oficial: https://www.npmjs.com/
• Documentação na Composio: docs.composio.dev/toolkits/npm

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
api_key	Sim	Token de autenticação gerado no painel da sua conta npmjs.com, usado para autenticar requisições ao registro npm.

Como obter a credencial

1. Acesse npmjs.com e faça login (ou crie uma conta gratuita).
2. Clique no seu avatar no canto superior direito e selecione Access Tokens.
3. Clique em Generate New Token e escolha o tipo Automation (recomendado para integrações) ou Read-only conforme o nível de acesso necessário.
4. Defina um nome descritivo para o token (ex.: squados-integration) e confirme a criação.
5. Copie o token exibido — ele só será mostrado uma vez.

Dica

Use um token do tipo Automation para integrações de CI/CD e agentes, pois ele ignora a solicitação de OTP em operações automatizadas. Guarde o token com segurança e revogue-o caso seja comprometido.

Como conectar no SquadOS

1. Acesse Ferramentas no menu lateral (/admin/tools).
2. Abra a aba Disponíveis e procure por npm.
3. Clique no card para abrir o modal de detalhes e em Conectar.
4. Você é levado para a página de conexão segura hospedada pela Composio, onde informa o token de autenticação obtido acima.
5. Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Excluir token de usuário (legado)

NPM_DELETE_USER_TOKEN_LEGACY

Exclui um token de autenticação de usuário usando o endpoint legado. Use quando precisar revogar ou remover um token específico do registro npm.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
token	string	Sim	UUID/chave do token a excluir (ex.: a1df1599-b022-4f1b-86c5-ee7a1df48f48). Este é o identificador do token retornado pelo endpoint de listagem de tokens.
npm_otp	string	Não	Senha de uso único para autenticação de dois fatores, se exigida pela conta do usuário.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter contagem de downloads de todos os pacotes (ponto)

NPM_GET_ALL_PACKAGES_DOWNLOAD_POINT

Obtém as estatísticas agregadas de download do registro npm para todos os pacotes em um período especificado. Retorna a contagem total de downloads de todo o registro com as datas de início e fim. Suporta períodos predefinidos (last-day, last-week, last-month, last-year) ou intervalos de datas customizados (YYYY-MM-DD:YYYY-MM-DD).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
period	string	Sim	Período de tempo para os downloads. Formatos suportados: (1) Períodos predefinidos: last-day, last-week, last-month, last-year. (2) Intervalo de datas explícito: YYYY-MM-DD:YYYY-MM-DD (máx. 365 dias). Dados disponíveis a partir de 2015-01-10.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter contagem de downloads de pacote npm (ponto)

NPM_GET_DOWNLOAD_COUNTS_POINT

Obtém as estatísticas de download de um pacote npm para um período especificado. Retorna a contagem total de downloads com as datas de início e fim para pacotes únicos, pacotes com escopo ou consultas em lote (até 128 pacotes). Suporta períodos predefinidos (last-day, last-week, last-month, last-year) ou intervalos de datas customizados (YYYY-MM-DD:YYYY-MM-DD).

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
period	string	Sim	Período de tempo para os downloads. Formatos suportados: (1) Períodos predefinidos: last-day, last-week, last-month, last-year. (2) Intervalo de datas explícito: YYYY-MM-DD:YYYY-MM-DD (máx. 365 dias para consultas em lote, 18 meses nos demais casos). Dados disponíveis a partir de 2015-01-10.
package	string	Sim	Nome do pacote npm para buscar as contagens de download. Suporta pacotes únicos (ex.: express) e pacotes com escopo (ex.: @babel/core). Para múltiplos pacotes, consulte-os individualmente, pois o formato de consulta em lote retorna uma estrutura de resposta diferente.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter contagem de downloads de pacote npm por intervalo de datas

NPM_GET_DOWNLOAD_COUNTS_RANGE_PACKAGE

Obtém as contagens de download de um pacote npm ao longo de um intervalo de datas especificado. Use quando precisar de dados históricos de download diário.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
end	string	Sim	Data final (inclusiva) no formato YYYY-MM-DD; deve ser igual ou posterior à data de início.
start	string	Sim	Data inicial (inclusiva) no formato YYYY-MM-DD.
package	string	Sim	Nome do pacote npm, incluindo escopo opcional (ex.: @babel/core).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter contagens de download de todos os pacotes npm por período

NPM_GET_DOWNLOAD_RANGE_ALL

Obtém as contagens de download diário de todos os pacotes npm ao longo de um período especificado. Use quando precisar de estatísticas agregadas de download de todo o registro npm.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
period	string	Sim	Período de tempo para os downloads. Formatos suportados: (1) Períodos predefinidos: last-day, last-week, last-month, last-year. (2) Intervalo de datas explícito: YYYY-MM-DD:YYYY-MM-DD (ex.: 2023-01-01:2023-01-31). Dados disponíveis a partir de 2015-01-10.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter feed de alterações do registro

NPM_GET_REGISTRY_CHANGES

Obtém um fluxo de alterações do registro para fins de replicação. Retorna um feed de alterações no estilo CouchDB para acompanhar atualizações do registro.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
limit	integer	Não	Número máximo de alterações a retornar. Padrão: 1000; máximo: 10000.
since	integer	Não	Número de sequência a partir do qual recuperar alterações. Use para continuar a partir de uma posição anterior no feed.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter metadados do registro npm

NPM_GET_REGISTRY_META

Recupera metadados do registro npm via endpoints meta. Use ping para verificar a conectividade com o registro ou whoami para obter o nome de usuário autenticado.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
endpoint	string (ping | whoami)	Sim	Subcaminho meta a chamar: ping (verificar conectividade com o registro) ou whoami (obter nome de usuário autenticado).

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter downloads de versões de pacote npm (últimos 7 dias)

NPM_GET_VERSION_DOWNLOADS

Obtém as contagens de download de versões específicas de um pacote nos últimos 7 dias. Use quando precisar entender quais versões são mais populares.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
package	string	Sim	Nome do pacote npm, incluindo escopo opcional (ex.: @babel/core). Para pacotes com escopo, a / será codificada automaticamente.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Consultar avisos de segurança em lote

NPM_QUERY_BULK_SECURITY_ADVISORIES

Consulta avisos de segurança em lote para múltiplos pacotes npm. Use quando precisar verificar informações de vulnerabilidade de múltiplos pacotes e versões de uma vez.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
packages	object	Sim	Objeto JSON mapeando nomes de pacotes para arrays de strings de versão. Exemplo: {"express": ["4.17.1"], "lodash": ["4.17.20"]}

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter metadados de pacote npm

NPM_REGISTRY_GET_PACKAGE

Busca metadados de um pacote npm especificado. Use após confirmar o nome exato do pacote, incluindo o escopo. As respostas podem ser grandes; prefira ler os campos de nível superior como dist-tags, description e license em vez de varrer o objeto inteiro.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
package	string	Sim	Nome do pacote npm a buscar, incluindo escopo opcional (ex.: @babel/core).
version	string	Não	Versão específica ou dist-tag a buscar (ex.: latest, 1.2.3). Se omitido, retorna metadados resumidos de todas as versões. Use dist-tags.latest como a versão estável autoritativa; não infira a partir dos mapas versions ou time, que podem incluir pré-lançamentos ou entradas obsoletas.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Obter metadados raiz do registro npm

NPM_REGISTRY_GET_ROOT

Busca metadados raiz do registro npm, incluindo a contagem total de pacotes e a sequência de atualização. Retorna estatísticas do banco de dados a partir do serviço de replicação do npm. Nenhum parâmetro é necessário. Use para obter estatísticas atuais do registro, como o número total de pacotes disponíveis.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.

Pesquisar pacotes npm

NPM_REGISTRY_SEARCH_PACKAGES

Pesquisa pacotes no registro npm. Use quando precisar encontrar pacotes que correspondam a um termo de busca. Os resultados são retornados em um array objects; cada elemento contém metadados do pacote no campo package e estimativas de downloads semanais em downloads.weekly.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
size	integer	Não	Número de resultados a retornar (1–250). Padrão: 20.
text	string	Sim	Consulta de busca para pacotes (nome, palavras-chave ou descrição). Combine palavras-chave específicas (ex.: react cli, testing framework) para evitar resultados vagamente relacionados em consultas amplas.
offset	integer	Não	Deslocamento para paginação. Padrão: 0.
quality	number	Não	Peso de qualidade (0.0–1.0). Padrão: 1.0.
popularity	number	Não	Peso de popularidade (0.0–1.0). Padrão: 1.0.
maintenance	number	Não	Peso de manutenção (0.0–1.0). Padrão: 1.0.

Saída

Nome	Tipo	Obrigatório	Descrição
data	string	Sim	Dados retornados pela execução da ação.
error	string	Não	Mensagem de erro caso a execução tenha falhado.
successful	boolean	Sim	Indica se a ação foi executada com sucesso.