npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

kalvi-nfse

v0.1.1

Published

SDK TypeScript para a API Kalvi: classificação e pré-validação de NFS-e para IBS/CBS (CST, cClassTrib, alíquotas, rejeições). Plano gratuito de 200 chamadas/mês, sem cartão.

Readme

kalvi-nfse

CST, cClassTrib, alíquotas e pré-validação de NFS-e para IBS/CBS, em cinco linhas.

import { Kalvi } from "kalvi-nfse";

const nfse = new Kalvi({ apiKey: process.env.KALVI_API_KEY });
const r = await nfse.classify({
  service_code: "04.01",
  tax_regime: "LUCRO_PRESUMIDO",
  municipality_code: "4113700",
  competence_date: "2026-11-10",
});
console.log(r.candidates[0].cClassTrib, r.candidates[0].cst, r.tables_version);
// 200029 200 2026-10-11

Crie sua chave grátis: 200 chamadas por mês, sem cartão. Criar chave · Documentação

Sem programar? Cole ou envie as notas (.xml, .json ou .zip) no verificador: 3 por dia sem cadastro, 20 por mês com a conta grátis.

npm i kalvi-nfse

Node 18 ou mais novo. Sem dependências. Use no servidor: a chave não deve ir para o navegador.

O que ele faz

| Método | Para quê | | -------------------------------------- | -------------------------------------------------------------------------------------- | | classify(input) | candidatos de CST e cClassTrib com justificativa, cIndOp, alíquotas, reduções e fontes | | validate(xmlOuObjeto) | confere uma DPS antes de transmitir e devolve os problemas por severidade | | validateMany(notas) | o mesmo para um lote de até 50 notas | | tables.list() · tables.changelog() | versões de tabela servidas e o que mudou em cada uma | | account.usage() | extrato do mês: quantas contaram e quantas não foram cobradas |

O SDK não tem regra tributária dentro: tudo vem da API, e toda resposta traz tables_version, a data de vigência da tabela usada. Quando as tabelas oficiais mudam, seu código não muda.

Validar antes de transmitir

const r = await nfse.validate(xmlDaDps);
for (const issue of r.issues) {
  console.log(issue.severity, issue.code, issue.message, "→", issue.fix);
}
// blocking E0958 cClassTrib para IBS/CBS incorreto... → Use /v1/classify para o candidato do seu item.

severity é blocking (a nota não passa), likely_rejection (deve ser rejeitada) ou warning. code é o código oficial da NFS-e nacional quando existe (issue.official === true).

Erros

import { KalviError, KalviNetworkError } from "kalvi-nfse";

try {
  await nfse.classify(entrada);
} catch (e) {
  if (e instanceof KalviError && e.isQuotaExceeded) {
    console.log("Limite do mês:", e.upgradeUrl, "zera em", e.resetsAt);
  } else if (e instanceof KalviError) {
    console.log(e.code, e.message, "request_id:", e.requestId);
  } else if (e instanceof KalviNetworkError) {
    console.log("A API não respondeu depois de", e.attempts, "tentativas");
  }
}

Guarde o request_id: ele identifica a chamada nos nossos registros. Códigos usados com frequência: UNAUTHORIZED, INVALID_INPUT, PARSE_ERROR, PAYLOAD_TOO_LARGE, RATE_LIMITED, QUOTA_EXCEEDED.

Repetição automática

Falha nossa (5xx), rajada (RATE_LIMITED) e erro de rede são repetidos sozinhos, com espera crescente e respeitando o Retry-After. Erro de entrada (4xx) e limite do mês (QUOTA_EXCEEDED) não são repetidos: repetir não ajudaria. Ajuste com maxRetries no construtor ou por chamada.

Quanto já foi do plano

const nfse = new Kalvi({
  onPlanUsage: (u) => console.warn(`${u.used}/${u.limit} chamadas; zera em ${u.resets}`),
});

A API manda o aviso a partir de 80% do limite; o último valor fica em nfse.lastPlanUsage. Só classify, validate e validateMany consomem o plano, e só a chamada que devolveu resultado ou erro de entrada conta. Falha nossa não conta e aparece em account.usage() numa coluna separada.

Opções

| Opção | Padrão | Para quê | | ------------- | ---------------- | --------------------------------------------- | | apiKey | KALVI_API_KEY | sua chave | | baseUrl | KALVI_BASE_URL | outra instância da API (staging, por exemplo) | | timeoutMs | 20000 | tempo máximo por tentativa | | maxRetries | 2 | tentativas extras | | fetch | o fetch global | proxy ou cliente HTTP próprio | | onPlanUsage | — | aviso de consumo do plano | | userAgent | — | identifica sua aplicação nos nossos logs |

Tipos

ClassifyInput, ClassifyResult, Candidate, ValidateResult, Issue, ValidateManyResult, TablesListResult, ChangelogResult, UsageResult, PlanUsage, TaxRegime, OperationNature, Severity, Confidence, SourceRef — todos exportados. Campos próprios em snake_case; campos oficiais do padrão nacional mantêm o nome oficial (cClassTrib, cst, cIndOp, opSimpNac).

Aviso

Apoio técnico, não consultoria tributária. A responsabilidade pela nota é do emissor. Confira o resultado com seu contador ou departamento fiscal.

MIT.