@useinvio/nfse-sdk 3.0.0 → 3.1.0

package/README.md

@@ -40,11 +40,11 @@ O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações
 - [Enviar evento](#enviar-evento-ex-cancelamento)
 - [Série e número da DPS](#série-e-número-da-dps)
 - [Ambientes](#ambientes)
+- [Agentes de IA e MCP](#agentes-de-ia-e-mcp)
 - [Referência da API](#referência-da-api)
 - [Desenvolvimento](#desenvolvimento)
 - [Publicação no npm](#publicação-no-npm)
-- [Divulgação e exemplos](#divulgação-e-exemplos)
-- [Assistente GPT](#assistente-gpt)
+- [Exemplos](#exemplos)
 
 ---
 
@@ -54,7 +54,7 @@ O SDK cuida da camada protocolar: certificado A1, montagem de DPS, validações
 npm install @useinvio/nfse-sdk
 ```
 
-> Node.js ≥ 20 é obrigatório.
+> Node.js ≥ 20 é obrigatório. Não precisa de `xmllint` nem de binários nativos: a validação XSD roda em WebAssembly.
 
 ---
 
@@ -63,9 +63,10 @@ npm install @useinvio/nfse-sdk
 O caminho mais comum: emitir uma nota a partir de JSON declarativo.
 
 ```ts
-import { emitirNfse, loadPfx, EmitirNotaError } from '@useinvio/nfse-sdk';
+import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+// NFSE_CERT_PATH=./certificado.pfx e NFSE_CERT_PASSWORD=... (veja Certificado A1)
+const certificado = NfseCertificate.fromEnv();
 
 const nota = {
   ambiente: 'restrita' as const,
@@ -103,7 +104,7 @@ const nota = {
 };
 
 try {
-  const resultado = await emitirNfse(nota, pfx);
+  const resultado = await emitirNfse(nota, certificado);
   console.log(resultado.chaveAcesso); // chave de 50 dígitos
   console.log(resultado.nfseXml);    // XML autorizado pela SEFIN
 } catch (error) {
@@ -133,8 +134,8 @@ try {
 | Situação | O que usar |
 |---|---|
 | Quer uma API de cliente com `client.invoices.create(...)` | `new NfseClient(...)` |
-| Outro sistema já gera o XML da DPS | `emitirNfse(xmlString, pfx)` |
-| Você monta os dados e quer que a SDK construa o XML | `emitirNfse(notaJson, pfx)` |
+| Outro sistema já gera o XML da DPS | `emitirNfse(xmlString, certificado)` |
+| Você monta os dados e quer que a SDK construa o XML | `emitirNfse(notaJson, certificado)` |
 | Precisa inspecionar ou salvar o XML antes de enviar | `buildDpsFromJson(nota)` |
 | Fluxo customizado (assinar, compactar ou enviar separadamente) | funções de baixo nível |
 
@@ -150,14 +151,11 @@ O cliente usa os mesmos campos do JSON declarativo (`prestador`, `servico` e
 cada chamada.
 
 ```ts
-import { NfseClient } from '@useinvio/nfse-sdk';
+import { NfseCertificate, NfseClient } from '@useinvio/nfse-sdk';
 
 const client = new NfseClient({
   environment: 'sandbox',
-  certificate: {
-    content: process.env.NFSE_CERTIFICATE!, // PFX em base64
-    password: process.env.NFSE_CERTIFICATE_PASSWORD!,
-  },
+  certificate: NfseCertificate.fromEnv(),
   defaults: {
     prestador: {
       cnpj: '12345678000195',
@@ -206,9 +204,8 @@ console.log(invoice.nfseXml);
 ```
 
 `environment: 'sandbox'` é alias de `restrita`, e `production` é alias de
-`producao`. O campo `certificate.content` aceita o conteúdo binário do PFX em
-`Buffer` ou o PFX codificado em base64, formato comum para variáveis de
-ambiente.
+`producao`. `certificate` aceita um `NfseCertificate` ou, por compatibilidade,
+`{ content, password }` com o PFX em `Buffer` ou base64.
 
 Para inspecionar a DPS gerada sem assinar nem enviar:
 
@@ -235,7 +232,7 @@ const dps = client.invoices.buildDpsJson({
 
 Divergencias entre `vServ` e a conversao cambial geram avisos, preservando o valor explicito. O mesmo vale para o valor estrangeiro do bloco de comercio exterior. Todos os valores monetarios sao arredondados para duas casas, inclusive `comExt.vServMoeda`; valores de servico que arredondam para zero sao rejeitados. Leia `warnings` antes da emissao quando quiser apresentar esses avisos ao usuario.
 
-`prepararNota` verifica a vigencia do certificado antes de assinar; `transmitirNotaPreparada` verifica novamente antes do envio. `assertCertificateValidity(pfx, now?)` expoe essa verificacao. A checagem de titularidade continua explicita via `assertCertificateForProvider(pfx, documento, now?)`; o SDK nao resolve representacao fiscal.
+`prepararNota` verifica a vigencia do certificado antes de assinar; `transmitirNotaPreparada` verifica novamente antes do envio. `assertCertificateValidity(certificado, now?)` expoe essa verificacao. A checagem de titularidade continua explicita via `assertCertificateForProvider(certificado, documento, now?)`; o SDK nao resolve representacao fiscal.
 
 O ambiente para JSON segue `options.ambiente` → `request.ambiente` → `restrita`, tanto no XML quanto no destino. XML externo usa `tpAmb` e rejeita uma opcao divergente. Notas preparadas tambem precisam ter o mesmo ambiente no XML assinado e no envio.
 
@@ -249,23 +246,66 @@ Veja [as correcoes e mudancas de comportamento](docs/CORRECOES_EMISSAO.md) e os
 
 ## Certificado A1
 
-### A partir de arquivo
+Use `NfseCertificate`. Ele lê o `.pfx`/`.p12` uma vez, mantém a chave privada fora do objeto e descarta a senha e os bytes do arquivo. `console.log(certificado)` e `JSON.stringify(certificado)` mostram só CNPJ/CPF, validade e fingerprint.
+
+### Variáveis de ambiente (recomendado)
+
+```bash
+NFSE_CERT_PATH=./certificado.pfx   # ou NFSE_CERT_BASE64=<PFX em base64>
+NFSE_CERT_PASSWORD=sua-senha       # ou NFSE_CERT_PASSWORD_FILE=/run/secrets/nfse_cert_password
+```
 
 ```ts
-import { loadPfx } from '@useinvio/nfse-sdk';
+import { NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+const certificado = NfseCertificate.fromEnv();
+console.log(certificado.cnpj, certificado.notAfter, certificado.daysUntilExpiry());
 ```
 
-### A partir de buffer (ex.: certificado descriptografado do banco)
+`NFSE_CERT_PASSWORD_FILE` lê a senha de um arquivo, o formato de secrets do Docker e do Kubernetes. Nunca versione o `.pfx` nem a senha.
+
+### Outras origens
 
 ```ts
-import { loadPfxFromBuffer } from '@useinvio/nfse-sdk';
+NfseCertificate.fromFile('./certificado.pfx', senha);
+NfseCertificate.fromBase64(pfxBase64, senha);        // aceita quebras de linha e data: URLs
+NfseCertificate.fromPfx(pfxBuffer, senha);           // ex.: PFX vindo do seu cofre de segredos
+NfseCertificate.fromPem({ key, cert, passphrase });  // par extraído com openssl
+```
+
+### Vários emitentes (multi-tenant)
+
+Crie um `NfseCertificate` por emitente e reaproveite-o. Cada certificado tem o próprio agente mTLS, então conexões nunca são compartilhadas entre emitentes. Guarde o PFX cifrado (KMS, Vault, Secrets Manager) e a senha em um segredo separado, e descriptografe só ao criar o objeto.
 
-const pfx = loadPfxFromBuffer(pfxBuffer, password);
+```ts
+import { assertCertificateForProvider, NfseCertificate } from '@useinvio/nfse-sdk';
+
+const cache = new Map<string, NfseCertificate>();
+
+async function certificadoDoEmitente(cnpj: string): Promise<NfseCertificate> {
+  const cached = cache.get(cnpj);
+  if (cached?.isValidAt()) return cached;
+  const { pfx, senha } = await cofre.buscarCertificado(cnpj); // seu secret manager
+  const certificado = NfseCertificate.fromPfx(pfx, senha);
+  assertCertificateForProvider(certificado, cnpj);
+  cache.set(cnpj, certificado);
+  return certificado;
+}
 ```
 
-O objeto `pfx` retornado contém chave privada e certificado em PEM, pronto para assinar e fazer mTLS.
+### Erros de certificado
+
+Todos lançam `CertificateValidationError` com um `code` estável:
+
+| `code` | Quando |
+|---|---|
+| `CERTIFICATE_INVALID_PASSWORD` | Senha incorreta. |
+| `CERTIFICATE_UNREADABLE` | O conteúdo não é um PFX/PEM válido. |
+| `CERTIFICATE_MISSING`, `CERTIFICATE_PASSWORD_MISSING` | Variáveis de ambiente ausentes em `fromEnv`. |
+| `CERTIFICATE_NOT_YET_VALID`, `CERTIFICATE_EXPIRED` | Fora da vigência. Verificado antes de assinar e antes de enviar. |
+| `CERTIFICATE_HOLDER_MISMATCH` | `assertCertificateForProvider` com CPF/CNPJ diferente do titular. |
+
+> `loadPfx` e `loadPfxFromBuffer` continuam funcionando, mas retornam a chave privada em PEM dentro de um objeto comum. Prefira `NfseCertificate`.
 
 ---
 
@@ -274,11 +314,11 @@ O objeto `pfx` retornado contém chave privada e certificado em PEM, pronto para
 Use quando outro sistema (ERP, sistema legado) já gera o XML da DPS no layout nacional.
 
 ```ts
-import { emitirNfse, loadPfx } from '@useinvio/nfse-sdk';
+import { emitirNfse, NfseCertificate } from '@useinvio/nfse-sdk';
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
+const certificado = NfseCertificate.fromEnv();
 
-const resultado = await emitirNfse(dpsXml, pfx, { ambiente: 'restrita' });
+const resultado = await emitirNfse(dpsXml, certificado, { ambiente: 'restrita' });
 
 console.log(resultado.chaveAcesso);
 console.log(resultado.nfseXml);
@@ -296,7 +336,7 @@ Para a referência completa de campos aceitos no JSON, consulte [JSON_MAPPING.md
 O builder valida formatos e combinações mínimas antes de gerar XML, mas não escolhe códigos fiscais por você. Campos como `tributacaoMunicipal` e `totTrib` precisam ser informados explicita[...]
 
 ```ts
-import { emitirNfse, loadPfx, type DpsJsonRequest } from '@useinvio/nfse-sdk';
+import { emitirNfse, NfseCertificate, type DpsJsonRequest } from '@useinvio/nfse-sdk';
 
 const nota: DpsJsonRequest = {
   ambiente: 'restrita',
@@ -333,8 +373,8 @@ const nota: DpsJsonRequest = {
   },
 };
 
-const pfx = loadPfx('./certificado.pfx', process.env.PFX_PASSWORD!);
-const resultado = await emitirNfse(nota, pfx);
+const certificado = NfseCertificate.fromEnv();
+const resultado = await emitirNfse(nota, certificado);
 ```
 
 > `pTotTribFed`, `pTotTribEst` e `pTotTribMun` são percentuais com duas casas decimais (ex.: `"5.00"`), diferentes das alíquotas com quatro casas (`pAliq`).
@@ -365,7 +405,7 @@ console.log(xml); // XML não assinado da DPS
 import { EmitirNotaError, emitirNfse } from '@useinvio/nfse-sdk';
 
 try {
-  await emitirNfse(nota, pfx);
+  await emitirNfse(nota, certificado);
 } catch (error) {
   if (!(error instanceof EmitirNotaError)) throw error;
 
@@ -387,7 +427,7 @@ try {
 ```ts
 import { consultarNfse } from '@useinvio/nfse-sdk';
 
-const resposta = await consultarNfse(chaveAcesso, pfx, 'restrita');
+const resposta = await consultarNfse(chaveAcesso, certificado, 'restrita');
 
 if (resposta.status === 200) {
   console.log(resposta.body);
@@ -403,10 +443,10 @@ if (resposta.status === 200) {
 ```ts
 import { enviarEvento, gzipBase64, signEnveloped } from '@useinvio/nfse-sdk';
 
-const signedEventXml = signEnveloped(pedRegXml, pedRegId, 'infPedReg', pfx);
+const signedEventXml = signEnveloped(pedRegXml, pedRegId, 'infPedReg', certificado);
 const pedRegXmlGZipB64 = gzipBase64(signedEventXml);
 
-const resposta = await enviarEvento(pedRegXmlGZipB64, pfx, chaveAcesso, 'restrita');
+const resposta = await enviarEvento(pedRegXmlGZipB64, certificado, chaveAcesso, 'restrita');
 ```
 
 ---
@@ -463,6 +503,34 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 
 ---
 
+## Agentes de IA e MCP
+
+O subpath `@useinvio/nfse-sdk/agent` expõe ferramentas neutras de framework para servidores MCP e agentes (OpenAI, LangChain, Vercel AI SDK). Cada ferramenta traz `name`, `description`, `inputSchema`/`outputSchema` em JSON Schema, `annotations` no formato MCP e um handler `run`.
+
+| Ferramenta | Efeito | Certificado |
+| --- | --- | --- |
+| `validate_dps` | Valida a requisição; nenhum efeito colateral. | Não |
+| `build_dps_xml` | Gera o XML não assinado e confere contra o XSD v1.01. | Não |
+| `get_nfse` | Consulta uma NFS-e pela chave de acesso. | Sim |
+
+```ts
+import { nfseAgentTools } from '@useinvio/nfse-sdk/agent';
+
+const context = { pfx: certificado, ambiente: 'restrita' as const }; // configuração do host
+for (const tool of nfseAgentTools) {
+  // registre tool.name, tool.description, tool.inputSchema e tool.annotations no seu framework
+  // e chame tool.run(argumentos, context) quando o modelo usar a ferramenta
+}
+```
+
+Certificado e ambiente ficam no `context` do host, nunca na entrada da ferramenta: o modelo não escolhe `producao` nem vê material de chave. Uma requisição com `ambiente` diferente do configurado gera `AMBIENTE_NOT_ALLOWED`. Falhas esperadas retornam `issues` com `code`, `path`, `severity`, `source` e `suggestion`; falhas de infraestrutura (rede, motor XSD) rejeitam a promise. `toAgentIssues(error)` converte erros do SDK (`DpsFiscalValidationError`, `DpsXsdValidationError`, `CertificateValidationError`, `EmitirNotaError`) para esse mesmo formato.
+
+`DPS_JSON_REQUEST_SCHEMA`, exportado também pela raiz do pacote, descreve o `DpsJsonRequest` canônico em JSON Schema 2020-12 com um subconjunto portável de palavras-chave. Ele cobre formatos e domínios de códigos, mas não as regras entre campos (regime × `totTrib`, nacional × exportação); `validateDpsJsonRequest` continua sendo a autoridade. Atalhos legados (`emissao.vServ`, `comExt`) e campos rejeitados pela validação ficam fora do schema; `validate_dps` aponta campos desconhecidos como `UNSUPPORTED_FIELD` em vez de ignorá-los.
+
+A emissão ainda não é exposta como ferramenta: ela exigirá confirmação explícita antes do envio.
+
+---
+
 ## Referência da API
 
 ### Funções principais
@@ -470,9 +538,9 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 | Função | Descrição |
 |---|---|
 | `new NfseClient(options)` | Cria cliente com ambiente, certificado e defaults no mesmo formato do JSON declarativo. |
-| `emitirNfse(input, pfx, options?)` | Emite uma NFS-e a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
-| `consultarNfse(chaveAcesso, pfx, ambiente?)` | Consulta uma NFS-e pela chave de acesso. |
-| `enviarEvento(xmlGzipB64, pfx, chaveAcesso, ambiente?)` | Envia evento fiscal (cancelamento, etc.). |
+| `emitirNfse(input, certificado, options?)` | Emite uma NFS-e a partir de XML ou JSON. Retorna `ResultadoEmissaoNota`. |
+| `consultarNfse(chaveAcesso, certificado, ambiente?)` | Consulta uma NFS-e pela chave de acesso. |
+| `enviarEvento(xmlGzipB64, certificado, chaveAcesso, ambiente?)` | Envia evento fiscal (cancelamento, etc.). |
 | `buildDpsFromJson(nota)` | Monta o XML da DPS sem assinar nem enviar. |
 | `setSefinRequestObserver(observer)` | Registra um hook para observar latência/status das chamadas à SEFIN. |
 | `createSefinLatencyTracker(options?)` | Agrega amostras recentes e pode calcular percentis quando `includePercentiles` estiver habilitado. |
@@ -481,17 +549,18 @@ Leia o guia completo em [docs/METRICS.md](./docs/METRICS.md).
 
 | Função | Descrição |
 |---|---|
-| `assertCertificateValidity(pfx, now?)` | Verifica vigencia do certificado; aplicada na preparacao e no envio. |
-| `assertCertificateForProvider(pfx, documento, now?)` | Verifica explicitamente vigencia e correspondencia do titular. |
-| `loadPfx(path, password)` | Carrega certificado A1 a partir de arquivo. |
-| `loadPfxFromBuffer(buffer, password)` | Carrega certificado A1 a partir de buffer. |
+| `assertCertificateValidity(certificado, now?)` | Verifica vigencia do certificado; aplicada na preparacao e no envio. |
+| `assertCertificateForProvider(certificado, documento, now?)` | Verifica explicitamente vigencia e correspondencia do titular. |
+| `NfseCertificate.fromEnv()` / `fromFile()` / `fromBase64()` / `fromPfx()` / `fromPem()` | Carrega o certificado A1 sem expor a chave privada. |
+| `loadPfx(path, password)` | Legado: retorna a chave em PEM. Prefira `NfseCertificate`. |
+| `loadPfxFromBuffer(buffer, password)` | Legado: retorna a chave em PEM. Prefira `NfseCertificate`. |
 
 ### Funções de baixo nível
 
 | Função | Descrição |
 |---|---|
-| `signDps(xml, dpsId, pfx)` | Assina XML de DPS com XMLDSIG. |
-| `signEnveloped(xml, id, ref, pfx)` | Assina XML genérico (eventos). |
+| `signDps(xml, dpsId, certificado)` | Assina XML de DPS com XMLDSIG. |
+| `signEnveloped(xml, id, ref, certificado)` | Assina XML genérico (eventos). |
 | `verifyDps(xml, certPem)` | Verifica assinatura de uma DPS. |
 | `gzipBase64(xml)` | Compacta XML em GZip e codifica em Base64. |
 | `gunzipBase64(b64)` | Descompacta resposta GZip/Base64. |
@@ -537,7 +606,7 @@ npm run build       # compila para dist/
 npm test            # build + tipos + testes unitários
 ```
 
-`npm test` também valida uma DPS gerada contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01`. Para compatibilidade com `xmllint`, o teste corrige em uma cópia temporária a âncora regex[...]
+`npm test` também valida as DPS geradas contra os XSD oficiais em `schemas/nfse/v1.01/Schemas/1.01` com o motor embutido (libxml2 em WebAssembly). Se o `xmllint` estiver instalado, como no CI, os testes também o usam como verificação cruzada.
 
 ### Uso local em outro projeto
 
@@ -567,19 +636,9 @@ O pacote usa `publishConfig.access = public`, necessário para publicar um pacot
 
 ---
 
-## Divulgação e exemplos
-
-- Exemplos copiáveis ficam em [`examples/`](./examples).
-- Material de lançamento, mensagens para redes e prompt de landing page ficam em [`docs/launch.md`](./docs/launch.md).
-
----
-
-## Assistente GPT
-
-Para criar um GPT que ajude outros devs a implementar e documentar esta SDK, use:
+## Exemplos
 
-- [`docs/gpt-assistant.md`](./docs/gpt-assistant.md): configuracao completa do GPT, instrucoes copiaveis, starters e testes de preview.
-- [`docs/gpt-knowledge.md`](./docs/gpt-knowledge.md): resumo compacto para subir como arquivo de Knowledge.
+Exemplos copiáveis ficam em [`examples/`](./examples).
 
 ---
 

package/dist/agent.d.ts

@@ -0,0 +1,86 @@
+import { type JsonSchema } from './dpsJsonSchema.js';
+import type { Ambiente } from './config.js';
+import type { DpsJsonRequest } from './dpsJson.js';
+import type { CertificateInput } from './certificate.js';
+export { DPS_JSON_REQUEST_SCHEMA } from './dpsJsonSchema.js';
+export type { JsonSchema } from './dpsJsonSchema.js';
+export type NfseAgentIssueSource = 'sdk' | 'invio' | 'schema' | 'xsd' | 'sefin' | 'certificate' | 'environment';
+/** One shape for validation, XSD, certificate and SEFIN problems. */
+export interface NfseAgentIssue {
+    code: string;
+    /** Dotted path inside the request (`emissao.` omitted, as in `DpsValidationIssue`); `$` when global. */
+    path: string;
+    severity: 'error' | 'warning';
+    source: NfseAgentIssueSource;
+    message: string;
+    suggestion?: string;
+}
+export interface NfseAgentContext {
+    /** Host-owned A1 certificate (`NfseCertificate` recommended). Required only by tools that talk to SEFIN. */
+    pfx?: CertificateInput;
+    /** Host-owned environment. Defaults to `restrita`; tool input cannot override it. */
+    ambiente?: Ambiente;
+}
+/** Same hints as MCP `ToolAnnotations`. */
+export interface NfseAgentToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+export interface NfseAgentTool<Input = any, Output = any> {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema: JsonSchema;
+    annotations: NfseAgentToolAnnotations;
+    requiresCertificate: boolean;
+    /**
+     * Expected failures (invalid input, rejection, missing certificate) resolve
+     * with `issues`. Infrastructure failures (XSD engine, network) reject.
+     */
+    run(input: Input, context?: NfseAgentContext): Promise<Output>;
+}
+export interface DpsRequestToolInput {
+    request: Omit<DpsJsonRequest, 'ambiente'>;
+}
+export interface ValidateDpsToolOutput {
+    valid: boolean;
+    schemaVersion: string;
+    ambiente: Ambiente;
+    issues: NfseAgentIssue[];
+    warnings: NfseAgentIssue[];
+}
+export interface BuildDpsXmlToolOutput {
+    ok: boolean;
+    ambiente: Ambiente;
+    dpsId?: string;
+    xml?: string;
+    issues: NfseAgentIssue[];
+    warnings: NfseAgentIssue[];
+}
+export interface GetNfseToolInput {
+    chaveAcesso: string;
+}
+export interface GetNfseToolOutput {
+    ok: boolean;
+    ambiente: Ambiente;
+    chaveAcesso: string;
+    status?: number;
+    nfseXml?: string;
+    body?: unknown;
+    issues: NfseAgentIssue[];
+}
+/**
+ * Converts known SDK errors to `NfseAgentIssue[]`. Returns `undefined` for
+ * anything else (transport, XSD engine, programming errors) so the caller can rethrow.
+ */
+export declare function toAgentIssues(error: unknown): NfseAgentIssue[] | undefined;
+/** `DPS_JSON_REQUEST_SCHEMA` without `ambiente`, which belongs to the host. */
+export declare const DPS_AGENT_REQUEST_SCHEMA: JsonSchema;
+export declare const validateDpsTool: NfseAgentTool<DpsRequestToolInput, ValidateDpsToolOutput>;
+export declare const buildDpsXmlTool: NfseAgentTool<DpsRequestToolInput, BuildDpsXmlToolOutput>;
+export declare const getNfseTool: NfseAgentTool<GetNfseToolInput, GetNfseToolOutput>;
+/** All tools, in the order an agent typically needs them. */
+export declare const nfseAgentTools: readonly NfseAgentTool[];

package/dist/agent.js

@@ -0,0 +1,235 @@
+/**
+ * Framework-neutral tool definitions for MCP servers and LLM agents.
+ *
+ * Each tool carries a JSON Schema for input and output, MCP-style annotations
+ * and a `run` handler. Adapters (MCP, OpenAI, LangChain, Vercel AI SDK) only
+ * need to map these fields. Certificate and environment are host
+ * configuration passed in `NfseAgentContext`, never tool input, so a model
+ * cannot select production or see key material.
+ */
+import { CertificateValidationError } from './certificateValidation.js';
+import { DEFAULT_AMBIENTE } from './config.js';
+import { buildDpsFromJson } from './dpsJson.js';
+import { DPS_JSON_REQUEST_SCHEMA } from './dpsJsonSchema.js';
+import { EmitirNotaError } from './emissaoNota.js';
+import { DpsFiscalValidationError, validateDpsJsonRequest } from './fiscalValidation.js';
+import { gunzipBase64 } from './gzipB64.js';
+import { checkJsonSchema } from './jsonSchemaCheck.js';
+import { consultarNfse, extrairErros } from './sefinClient.js';
+import { DpsXsdValidationError, validateDpsXmlAgainstXsd } from './xsdValidation.js';
+export { DPS_JSON_REQUEST_SCHEMA } from './dpsJsonSchema.js';
+function fromValidationIssue(issue) {
+    return { ...issue };
+}
+function sefinIssue(erro) {
+    const authorization = erro.Codigo === 'INVALID_AUTHORIZATION_RESPONSE';
+    return {
+        code: erro.Codigo,
+        path: '$',
+        severity: 'error',
+        source: authorization ? 'sdk' : 'sefin',
+        message: erro.Complemento ? `${erro.Descricao} (${erro.Complemento})` : erro.Descricao,
+        ...(authorization ? { suggestion: 'Consulte a nota pela chave ou concilie a DPS antes de reenviar.' } : {}),
+    };
+}
+/**
+ * Converts known SDK errors to `NfseAgentIssue[]`. Returns `undefined` for
+ * anything else (transport, XSD engine, programming errors) so the caller can rethrow.
+ */
+export function toAgentIssues(error) {
+    if (error instanceof DpsFiscalValidationError)
+        return error.issues.map(fromValidationIssue);
+    if (error instanceof DpsXsdValidationError) {
+        return error.details.map((message) => ({ code: 'XSD_INVALID', path: '$', severity: 'error', source: 'xsd', message }));
+    }
+    if (error instanceof CertificateValidationError) {
+        return [{ code: error.code, path: '$', severity: 'error', source: 'certificate', message: error.message }];
+    }
+    if (error instanceof EmitirNotaError) {
+        const issues = error.erros.map(sefinIssue);
+        return issues.length ? issues : [{ code: 'SEFIN_REJECTED', path: '$', severity: 'error', source: 'sefin', message: error.message }];
+    }
+    return undefined;
+}
+function resolveAmbiente(context) {
+    return context?.ambiente ?? DEFAULT_AMBIENTE;
+}
+function stripEmissao(path) {
+    return path.replace(/^emissao\./, '');
+}
+/** Fields the schema does not accept are reported instead of silently ignored by the builder. */
+function unsupportedFieldIssues(request) {
+    return checkJsonSchema(DPS_JSON_REQUEST_SCHEMA, request)
+        .filter(({ keyword }) => keyword === 'additionalProperties')
+        .map(({ path }) => ({
+        code: 'UNSUPPORTED_FIELD',
+        path: stripEmissao(path),
+        severity: 'error',
+        source: 'schema',
+        message: `${path} nao e um campo suportado pelo schema da DPS`,
+        suggestion: 'Remova o campo ou use o nome canonico descrito no schema.',
+    }));
+}
+function environmentIssue(request, ambiente) {
+    const requested = request?.ambiente;
+    if (requested === undefined || requested === ambiente)
+        return [];
+    return [{
+            code: 'AMBIENTE_NOT_ALLOWED',
+            path: 'ambiente',
+            severity: 'error',
+            source: 'environment',
+            message: `O ambiente e definido pelo host (${ambiente}); a requisicao pediu ${String(requested)}.`,
+            suggestion: 'Remova o campo ambiente da requisicao.',
+        }];
+}
+function validateForAgent(input, context) {
+    const ambiente = resolveAmbiente(context);
+    const request = input?.request;
+    const hostIssues = environmentIssue(request, ambiente);
+    const withAmbiente = request && typeof request === 'object' && !Array.isArray(request) ? { ...request, ambiente } : request;
+    const report = validateDpsJsonRequest(withAmbiente);
+    const structural = report.issues.some((issue) => issue.code === 'INVALID_STRUCTURE');
+    const issues = [
+        ...hostIssues,
+        ...(structural ? [] : unsupportedFieldIssues(withAmbiente)),
+        ...report.issues.map(fromValidationIssue),
+    ];
+    return { ambiente, report, issues, warnings: report.warnings.map(fromValidationIssue), request: withAmbiente };
+}
+const { $schema: _draft, ...requestSchema } = DPS_JSON_REQUEST_SCHEMA;
+const { ambiente: _ambiente, ...requestProperties } = requestSchema.properties;
+/** `DPS_JSON_REQUEST_SCHEMA` without `ambiente`, which belongs to the host. */
+export const DPS_AGENT_REQUEST_SCHEMA = { ...requestSchema, properties: requestProperties };
+const DPS_REQUEST_INPUT_SCHEMA = {
+    type: 'object',
+    properties: { request: DPS_AGENT_REQUEST_SCHEMA },
+    required: ['request'],
+    additionalProperties: false,
+};
+const ISSUE_SCHEMA = {
+    type: 'object',
+    properties: {
+        code: { type: 'string', description: 'Codigo estavel do problema, ex.: TOT_TRIB_REQUIRED ou codigo SEFIN.' },
+        path: { type: 'string', description: 'Campo afetado; $ quando global.' },
+        severity: { type: 'string', enum: ['error', 'warning'] },
+        source: { type: 'string', enum: ['sdk', 'invio', 'schema', 'xsd', 'sefin', 'certificate', 'environment'] },
+        message: { type: 'string' },
+        suggestion: { type: 'string' },
+    },
+    required: ['code', 'path', 'severity', 'source', 'message'],
+    additionalProperties: false,
+};
+const ISSUES = { type: 'array', items: ISSUE_SCHEMA };
+const AMBIENTE = { type: 'string', enum: ['restrita', 'producao'] };
+export const validateDpsTool = {
+    name: 'validate_dps',
+    title: 'Validar DPS da NFS-e',
+    description: 'Valida uma requisicao de DPS (NFS-e Nacional) sem certificado, sem rede e sem efeitos colaterais. ' +
+        'Retorna issues com code, path, message e suggestion; corrija os campos indicados e valide novamente ate valid=true. ' +
+        'Nao invente codigos fiscais (cTribNac, regime, tributacao): pergunte ao usuario quando faltarem.',
+    inputSchema: DPS_REQUEST_INPUT_SCHEMA,
+    outputSchema: {
+        type: 'object',
+        properties: { valid: { type: 'boolean' }, schemaVersion: { type: 'string' }, ambiente: AMBIENTE, issues: ISSUES, warnings: ISSUES },
+        required: ['valid', 'schemaVersion', 'ambiente', 'issues', 'warnings'],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiresCertificate: false,
+    async run(input, context) {
+        const { ambiente, report, issues, warnings } = validateForAgent(input, context);
+        return { valid: issues.length === 0, schemaVersion: report.schemaVersion, ambiente, issues, warnings };
+    },
+};
+export const buildDpsXmlTool = {
+    name: 'build_dps_xml',
+    title: 'Gerar XML da DPS',
+    description: 'Valida a requisicao e gera o XML nao assinado da DPS, conferido contra o XSD oficial v1.01. ' +
+        'Nao assina nem transmite. Use para revisar a nota antes de pedir a emissao ao usuario.',
+    inputSchema: DPS_REQUEST_INPUT_SCHEMA,
+    outputSchema: {
+        type: 'object',
+        properties: {
+            ok: { type: 'boolean' },
+            ambiente: AMBIENTE,
+            dpsId: { type: 'string', description: 'Id de 45 caracteres da DPS.' },
+            xml: { type: 'string', description: 'XML da DPS nao assinado.' },
+            issues: ISSUES,
+            warnings: ISSUES,
+        },
+        required: ['ok', 'ambiente', 'issues', 'warnings'],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    requiresCertificate: false,
+    async run(input, context) {
+        const { ambiente, issues, warnings, request } = validateForAgent(input, context);
+        if (issues.length)
+            return { ok: false, ambiente, issues, warnings };
+        try {
+            const built = buildDpsFromJson(request);
+            validateDpsXmlAgainstXsd(built.xml);
+            return { ok: true, ambiente, dpsId: built.id, xml: built.xml, issues: [], warnings };
+        }
+        catch (error) {
+            const mapped = toAgentIssues(error);
+            if (!mapped)
+                throw error;
+            return { ok: false, ambiente, issues: mapped, warnings };
+        }
+    },
+};
+export const getNfseTool = {
+    name: 'get_nfse',
+    title: 'Consultar NFS-e',
+    description: 'Consulta uma NFS-e na SEFIN pela chave de acesso de 50 digitos, no ambiente configurado pelo host. ' +
+        'Use tambem para conciliar uma emissao com resposta ambigua antes de qualquer reenvio.',
+    inputSchema: {
+        type: 'object',
+        properties: { chaveAcesso: { type: 'string', pattern: '^\\d{50}$', description: 'Chave de acesso da NFS-e, 50 digitos.' } },
+        required: ['chaveAcesso'],
+        additionalProperties: false,
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            ok: { type: 'boolean' },
+            ambiente: AMBIENTE,
+            chaveAcesso: { type: 'string' },
+            status: { type: 'number', description: 'Status HTTP da SEFIN.' },
+            nfseXml: { type: 'string', description: 'XML da NFS-e quando retornado.' },
+            body: { description: 'Corpo da resposta da SEFIN, sem o XML compactado.' },
+            issues: ISSUES,
+        },
+        required: ['ok', 'ambiente', 'chaveAcesso', 'issues'],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    requiresCertificate: true,
+    async run(input, context) {
+        const ambiente = resolveAmbiente(context);
+        const chaveAcesso = String(input?.chaveAcesso ?? '');
+        const fail = (issue) => ({ ok: false, ambiente, chaveAcesso, issues: [issue] });
+        if (!/^\d{50}$/.test(chaveAcesso)) {
+            return fail({ code: 'CHAVE_ACESSO_INVALID_FORMAT', path: 'chaveAcesso', severity: 'error', source: 'sdk', message: 'chaveAcesso deve ter 50 digitos numericos.' });
+        }
+        if (!context?.pfx) {
+            return fail({ code: 'CERTIFICATE_REQUIRED', path: '$', severity: 'error', source: 'certificate', message: 'O host nao configurou um certificado A1 para consultar a SEFIN.' });
+        }
+        const { status, body } = await consultarNfse(chaveAcesso, context.pfx, ambiente);
+        const { nfseXmlGZipB64, NfseXmlGZipB64, ...rest } = (body && typeof body === 'object' && !Array.isArray(body) ? body : { value: body });
+        const compressed = nfseXmlGZipB64 ?? NfseXmlGZipB64;
+        if (status < 200 || status >= 300) {
+            const issues = extrairErros(body).map(sefinIssue);
+            return { ok: false, ambiente, chaveAcesso, status, body: rest, issues: issues.length ? issues : [
+                    { code: `HTTP_${status}`, path: '$', severity: 'error', source: 'sefin', message: `A SEFIN respondeu HTTP ${status}.` },
+                ] };
+        }
+        const nfseXml = typeof compressed === 'string' ? gunzipBase64(compressed) : undefined;
+        return { ok: true, ambiente, chaveAcesso, status, ...(nfseXml ? { nfseXml } : {}), body: rest, issues: [] };
+    },
+};
+/** All tools, in the order an agent typically needs them. */
+export const nfseAgentTools = [validateDpsTool, buildDpsXmlTool, getNfseTool];
+//# sourceMappingURL=agent.js.map