AGENTS.md

# AGENTS.md

## Commands

- Use `corepack pnpm@11.10.0 ...` when you need the repo-pinned package manager explicitly.
- Install: `pnpm install`.
- Full local validation: `pnpm format && pnpm test && pnpm build && pnpm lint`.
- Single Jest file: `pnpm test -- __tests__/src/<name>.test.ts`.
- Build runs `prebuild` first, deleting `dist/`, then `tsc --emitDeclarationOnly && node esbuild.mjs`.
- `prepare` runs `pnpm run build`; GitHub installs of this package build from source.
- `pnpm-workspace.yaml` intentionally allows `esbuild` build scripts for pnpm 11 git/package preparation.

## Package Shape

- v3 is a breaking major: `NfseCampinas` exports `NfseCampinasV3`; consumers needing ABRASF/SOAP must stay on
  `@4success/nfse-campinas@^2`.
- Public API is exported from `src/index.ts`; implementation is flat under
  `src/{classes,client,certificate,dps,errors,eventos,signature,utils}`. Do not reintroduce a `src/v3` namespace just
  because older docs/specs mention it.
- `dist/` is generated and ignored. Source package contents are limited by `files: ["dist/**/*"]` for packed/published
  artifacts.
- Tests live under `__tests__/src`; shared valid DPS input is `test-support/fixtures.ts`.

## Campinas v3 Behavior

- Target protocol is DPS v1.01 / Padrão Nacional, not ABRASF 2.03, RPS, SOAP, or WSDL.
- Em homologação, envio, consulta de NFSe e eventos usam a base
  `https://preprod-nfseapi.ima.sp.gov.br/notafiscal-ws/nfse`.
- Em produção, a base é `https://nfseapi.campinas.sp.gov.br/notafiscal-ws/nfse`, com ativação em 21/09/2026 conforme
  o guia oficial atualizado em 18/09/2026; consulte `docs/references/v3/README.md` para fontes e divergências da
  página técnica.
- A consulta de DPS exige mTLS e usa `GET /notafiscal-ws/nfse/dps/{idDps}`. A resolução prioriza
  `endpoints.consultaDps`, depois `endpoints.dps` explícito por compatibilidade e, por fim, a constante própria do
  ambiente. Ao sobrescrever o envio para um endereço diferente da consulta, informe também `consultaDps`.
- The Campinas endpoint expects `Content-Type: application/json` with `{ dpsXmlGZipB64 }`; raw XML with
  `application/xml` returned `HTTP 415`.
- Consulta de NFSe por chave de acesso está disponível via `GET /notafiscal-ws/nfse/{chaveAcesso}`. O retorno
  é JSON com `nfseXmlGZipB64` e `alertas`; preserve a resposta bruta e os alertas em erros HTTP.
- Cancelamento de NFSe está disponível em homologação e produção via
  `POST /notafiscal-ws/nfse/{chaveAcesso}/eventos`. Envie JSON com `{ pedidoRegistroEventoXmlGZipB64 }`, contendo o XML
  `pedRegEvento` do código `101101` já assinado, compactado com GZip e codificado em Base64.
- A fachada `cancelarNfse` gera e assina o `pedRegEvento` a partir de dados tipados; `signedXml` permanece como escape
  hatch para XML externo e deve ser transmitido sem alteração nem reassinatura.
- Eventos em produção usam `PRODUCAO_EVENTOS_ENDPOINT` por padrão; `endpoints.eventos` continua disponível como
  override. `MissingProductionEndpointError` permanece exportado apenas por compatibilidade. Substituição e os
  demais eventos continuam não implementados.
- As quatro chamadas HTTP usam `maxRedirects: 0`: um redirecionamento deve preservar o status e o cabeçalho `Location`
  no erro, sem converter silenciosamente o POST em GET.
- `debug=true` deliberately logs signed XML and raw response without redaction. Do not add partial redaction unless
  product requirements change.

## Certificates And Transport

- Input certificate is A1 `.pfx/.p12`; `PfxCertificate` converts it to PEM for signing and mTLS.
- Preserve the matching leaf certificate plus intermediates in PEM output; TLS can require the client cert chain.
- `CampinasDpsClient` prefers PEM `key`/`cert` for `https.Agent`, with PFX fallback only when PEM is absent.
- Never commit real certificates, passwords, XML with client data, or raw municipal responses.

## Validation Rules That Are Easy To Break

- Do not turn the SDK into a full DPS/XSD validator. Local validation should be limited to fields the SDK needs to
  build IDs, sign/send requests, avoid runtime errors, or avoid silently changing user input during normalization.
- Do not add local checks solely because the official XSD or municipal service would reject missing domain/structural
  fields. Let the Prefeitura/NFS-e service be the source of truth for those rejections unless a product requirement says
  otherwise.
- Do not sanitize, strip, truncate, or "fix" fiscal/declarative text silently before signing. Preserve caller-provided
  values and let the Prefeitura/NFS-e service validate them.
- Normalization is allowed only for explicitly accepted input formats, such as punctuation removal from CPF/CNPJ/CEP
  when the original value matches one of the documented formats. Arbitrary text must not be cleaned into a different
  fiscal value.
- Monetary/decimal strings and fiscal/declarative codes such as `codigoTributacaoNacional`,
  `codigoTributacaoMunicipal`, and `codigoNbs` should be serialized exactly as supplied; use warnings if helpful, but do
  not reformat, pad, strip punctuation, round, or otherwise canonicalize them before signing.
- `validationMode: 'warn'` still blocks `severity: 'error'`; only `off` bypasses local validation.
- Dates must be real ISO dates/date-times accepted by Luxon; validation uses Luxon to reject impossible values and invalid
  `Date` objects without imposing a local timezone requirement.
- `serie` and `numeroDps` accept only digits before padding because they are used to build the DPS ID; do not silently
  strip letters/signs.
- CNPJ may be alphanumeric (`[A-Z0-9]{12}` + 2 numeric check digits); preserve uppercase letters in XML and DPS IDs.
- `idDps` override must match the DPS structure, allowing alphanumeric CNPJ in the 14-character federal-inscription block.
- Validate optional `tomador`/`destinatario` CPF/CNPJ and address municipality when supplied, but do not make optional
  parties mandatory.
- `servico.codigoNbs` is only a warning when it does not look like 9 digits or the documented dotted format; serialize it
  exactly as supplied.
- Do not validate or normalize IBS/CBS domain codes locally; emit `cIndOp` and `cClassTrib` exactly as supplied.

## Docs And Examples

- High-signal docs: `README.md`, `docs/v3/homologacao.md`, `docs/v3/mapeamento-campos.md`, `docs/v3/assinatura-dps.md`,
  and `docs/v3/reforma-tributaria.md`.
- `docs/SPEC_V3_NFSE_CAMPINAS.md` is useful historical context but contains proposed paths that no longer match the
  flattened `src/` layout.
- Example scripts under `exemplos` import from `../src`; they are for local source usage, not published package
  examples.