sgp-sdk 1.1.3 → 2.0.0-beta.1

package/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/); versionamento
+[SemVer](https://semver.org/lang/pt-BR/). `experimental.*` é a exceção declarada: pode mudar de forma
+incompatível em uma versão menor.
+
+## 2.0.0-beta.1 (2026-11-06)
+
+Redesenho completo como gateway de integração do SGP. Quebra de contrato sem aliases:
+veja o [guia de migração](MIGRATION.md). Publicada na tag `next` do npm; `latest` continua na 1.2.0
+até a 2.0.0 estável.
+
+### Mudanças incompatíveis
+
+- **Superfície nova, em inglês e agrupada por conceito do SGP**: `customers`, `crm.customers`,
+  `crm.contracts`, `preRegistrations`, `contracts`, `services`, `plans`, `occurrences`, `workOrders`,
+  `invoices`, `documents`, `coverage`, `catalogs`, `experimental.annotations` e `request()`. Os
+  namespaces `ura`, `os`, `precadastro`, `crm.*` antigos e `suporte` foram removidos; os campos dos
+  dados mantêm os nomes do SGP. Parâmetros posicionais (`clienteId`, `file`) viraram campos da
+  entrada.
+- **Configuração**: `createSgpClient({ baseUrl, credentials: { kind: "token", token, app }, ... })`.
+  Configuração inválida **lança** `InvalidConfigurationError` na criação; `baseUrl` precisa ser uma
+  origem (sem caminho).
+- **Modelo de resultado**: `{ ok, data, response, attempts, warnings? }` ou
+  `{ ok: false, error, response, attempts }`, no lugar de `success`/`error.status`/`error.detail`/
+  `error.endpoint`. `response` traz status, headers (credenciais redigidas) e corpo (`json`, `text`,
+  `empty`, `unavailable` ou `withheld`), ou `null` quando não houve resposta.
+- **Códigos de erro**: `INVALID_INPUT`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMITED`,
+  `ROUTE_NOT_ALLOWED` (restrição local do SDK: `request()` na rota de anotações), `NOT_FOUND`, `REJECTED`, `UPSTREAM`, `NETWORK`, `TIMEOUT`,
+  `ABORTED`, `INVALID_RESPONSE`. Saem `VALIDATION`, `METHOD_NOT_ALLOWED`, `SCHEMA_MISMATCH` e
+  `UNKNOWN`; o antigo `ROUTE_NOT_ALLOWED` virou `FORBIDDEN` com `reason: "TOKEN_ROUTE_NOT_ALLOWED"`.
+- **Efeito de escritas**: `outcome` (`not_applied`/`unknown`) virou `error.effect` (`none`/`unknown`),
+  presente em toda escrita. `"none"` agora exige evidência (recusa local, cancelamento antes do envio,
+  erro de campo ou de negócio do SGP, ou recusa conhecida da operação); um 4xx de formato não
+  reconhecido é `"unknown"`.
+- **Fidelidade**: chaves desconhecidas são preservadas em todos os níveis (o 1.x as descartava) e os
+  arrays que chegavam como `[{}]` agora chegam inteiros. Um item que não pode ser interpretado é
+  `INVALID_RESPONSE`. Campos secundários com tipo inesperado saem de `data` com `warnings`; o original
+  fica em `response.body`.
+- **`coverage.check` não converte mais** `lat`, `lng` e `distancia` para número.
+- **Entradas estritas**: chaves desconhecidas são recusadas localmente (`INVALID_INPUT`). Só os campos
+  que o fornecedor marca como obrigatórios são obrigatórios.
+- **IDs com marca**: `CustomerId`, `PlanId` e `PreRegistrationPlanId` (tipos de compilação); os dois
+  catálogos de planos não se misturam.
+- **Dados sensíveis**: `omitSensitive` e as tuplas `*SecretKeys`/`*PersonalKeys` foram substituídos por
+  `getSensitivity`, `pick` (allowlist) e `toSafeLog`.
+- **Constantes renomeadas**: `formaCobrancaCodigo` para `BILLING_METHOD`, `modoAquisicao` para
+  `ACQUISITION_MODE`, `crmStatus` para `CRM_STATUS`.
+- **Anotações**: `ura.listAnnotations` virou `experimental.annotations.list`. O corpo da resposta é
+  retido (`withheld`), cada anotação traz `raw`, identidade de outro cliente em qualquer profundidade
+  falha a chamada, e `request()` recusa a rota.
+- Todos os exports `*Definition`, `*KeyFields` e `*ItemPath` foram removidos (a definição de uma
+  operação é interna).
+
+### Adicionado
+
+- Operações novas: `preRegistrations.create` (PF/PJ, endereço em campos soltos com os nomes do SGP) e `preRegistrations.listPlans`,
+  `contracts.update`, `contracts.updateStatus`, `contracts.listStatusReasons`, `services.changePlan`,
+  `services.addTv`, `services.removeTv`, `crm.contracts.createByCpfCnpj` e `crm.contracts.list`.
+- `request()`: chamada bruta a uma rota que nenhum método cobre, com a mesma autenticação, prazo,
+  cancelamento e hooks (só caminhos sob `/api/`, sem redirecionamento, sem retry, `effect: "unknown"`
+  depois do envio).
+- Por chamada: `abortSignal`, `timeoutMs` (um orçamento de tempo por chamada lógica) e `maxRetries`.
+  `TIMEOUT` (prazo do SDK) distinto de `ABORTED` (seu sinal).
+- Retry opt-in para leituras (`maxRetries`, padrão 0), só em falhas transitórias, com backoff,
+  jitter e `Retry-After`. Escritas e `request()` nunca são repetidos. `attempts` em todo resultado.
+- Hooks opcionais e síncronos (`onRequest`, `onResponse`, `onError`) só com metadados; um hook que
+  falha não altera o resultado (registro em `diagnostics`).
+- `error.reason` por operação com evidência (`DOCUMENT_ALREADY_REGISTERED`, `STATUS_NOT_CHANGED`,
+  `CUSTOMER_NOT_IN_CRM`, `CONTRACT_NOT_ACTIVE`, `TOKEN_ROUTE_NOT_ALLOWED`) e `error.sgp` com os campos de
+  erro do SGP como vieram.
+- Constantes `CONTRACT_STATUS` e `SERVICE_TYPE`; `ACQUISITION_MODE` compartilhada entre CRM e
+  pré-cadastro.
+- Documentação em português: README, [MIGRATION.md](MIGRATION.md),
+  [COMPATIBILITY.md](COMPATIBILITY.md) e exemplos (`examples/` do repositório) compilados e executados na CI.
+- CI no GitHub Actions e verificações do pacote construído (tipos de consumidor em NodeNext e Bundler,
+  smoke em Node e Bun, conteúdo do `npm pack`).
+
+### Em aberto antes da 2.0.0 estável
+
+- Testes unitários também no Node (hoje no Bun; o Node é coberto pelo smoke do pacote construído).
+- Rotas e recusas ainda reconstruídas ou não observadas: veja [COMPATIBILITY.md](COMPATIBILITY.md).
+
+## 1.x
+
+Congelada. A última versão é a 1.2.0; as versões 1.0.0 a 1.2.0 estão nas tags `v1.0.0` a `v1.2.0` do
+repositório.

package/COMPATIBILITY.md

@@ -0,0 +1,151 @@
+# Matriz de compatibilidade
+
+O que foi **provado**, e como, para cada operação do sgp-sdk 2.0. Serve para saber até onde confiar
+no contrato de uma operação antes de usá-la em produção.
+
+- **Instância:** uma instância de produção de um provedor. Nenhuma outra foi usada.
+- **Versão do SGP:** **desconhecida**. Nenhuma observação foi associada a uma versão do SGP, e
+  comportamento pode mudar entre versões.
+- **Dados:** as escritas observadas usaram clientes, contratos e serviços de teste sintéticos criados
+  para a verificação. Esta matriz não traz hosts, credenciais nem identificadores reais, e omite ids.
+- **Datas:** `AAAA-MM-DD` (UTC, a data do identificador da execução de verificação). Capturas feitas
+  para a série 1.x aparecem como "1.x" com a data em que a fixture entrou no repositório
+  (2026-10-30 a 2026-10-31); a data exata da captura não foi registrada (não verificado).
+
+## Níveis de evidência
+
+| Nível                 | Significa                                                                                                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Observado (bruta)** | Resposta real da instância, com status, headers e corpo registrados como foram recebidos.                                                            |
+| **Observado (corpo)** | Resposta real da instância, mas só o corpo foi registrado (mascarado); os headers da fixture são reconstruídos.                                      |
+| **Documentado**       | Descrito pelo fornecedor (coleção de requisições ou suporte), **nunca visto** numa resposta real.                                                    |
+| **Reconstruído**      | Corpo ou texto reconstruído de relatos (prosa de verificações), do contrato da série 1.x ou de testes, **sem captura**. O formato real pode diferir. |
+
+Quando a resposta real difere do esperado, o SDK falha de forma segura: `INVALID_RESPONSE`, e numa
+escrita `effect: "unknown"`. Um nível "Observado" prova **um** comportamento, uma vez ou poucas;
+não é uma garantia de contrato do SGP. A prova de "nada foi aplicado" é uma releitura do estado, não
+uma garantia.
+
+As fixtures que alimentam os testes estão em `fixtures/` do repositório (fora do pacote npm), cada uma
+com a fonte (`source`) e o nível de evidência (`evidence`) no próprio arquivo. A data da execução de
+verificação aparece na fonte quando existe; as fixtures derivadas da série 1.x não têm data, e o
+cenário é o caminho do arquivo (`<grupo>/<operação>/<caso>`).
+
+## Matriz por operação
+
+Cada linha é um cenário. As colunas "Data" e "Evidência" valem para aquele cenário.
+
+### `customers`
+
+| Operação           | Cenário                                                           | Evidência         | Data       | Observação                                    |
+| ------------------ | ----------------------------------------------------------------- | ----------------- | ---------- | --------------------------------------------- |
+| `customers.list`   | Página de um cliente de teste, com contratos e serviços aninhados | Observado (corpo) | 2026-11-05 | Os aninhados chegam inteiros (nada de `[{}]`) |
+| `customers.search` | Busca por contrato, um candidato                                  | Observado (corpo) | 1.x        | Corpo mascarado                               |
+| `customers.search` | Sem resultado (`contratos: []`)                                   | Reconstruído      | n/d        | Vem de um teste da 1.x                        |
+
+### `crm`
+
+| Operação                        | Cenário                                                             | Evidência               | Data       | Observação                                                                                                           |
+| ------------------------------- | ------------------------------------------------------------------- | ----------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
+| `crm.customers.create`          | PF (`/F`): 200 com `cliente_id` e `message`                         | Observado (bruta)       | 2026-11-05 | Com um CPF que já existia, o SGP criou **outro** cliente com o mesmo documento (ambos listados por `customers.list`) |
+| `crm.customers.create`          | PF: 400 de validação de campo (nome com dígitos)                    | Observado (bruta)       | 2026-11-05 | Releitura: nada foi criado                                                                                           |
+| `crm.customers.create`          | PJ (`/J`)                                                           | Documentado             | n/d        | Nunca exercitado                                                                                                     |
+| `crm.customers.updateStatus`    | Status 6 ("Contrato realizado no SGP"): 200                         | Observado (bruta)       | 2026-11-06 | Os demais códigos de `CRM_STATUS` nunca foram enviados                                                               |
+| `crm.customers.updateStatus`    | Cliente que já saiu do CRM: 404 `{error:"Cadastro não encontrado"}` | Reconstruído            | 1.x        | `NOT_FOUND`, `effect: "none"`                                                                                        |
+| `crm.contracts.create`          | Por id: 200 com `clientecontrato`, `message`, `cliente`             | Observado (bruta)       | 2026-11-06 | O contrato apareceu em `contracts.list` depois                                                                       |
+| `crm.contracts.create`          | Por id: 400 por falta de `nas`                                      | Observado (bruta)       | 2026-11-06 | Nada foi criado                                                                                                      |
+| `crm.contracts.create`          | Por id: 400 "Não encontrado cliente CRM" (`CUSTOMER_NOT_IN_CRM`)    | Reconstruído            | 2026-11-05 | Texto vindo da prosa do relato; a releitura mostrou nenhum contrato adicionado                                       |
+| `crm.contracts.create`          | `modoaquisicao` 2 recusado                                          | Observado (sem fixture) | 2026-10-31 | A documentação do fornecedor lista 1 e 2; o SDK aceita só 0 e 1                                                      |
+| `crm.contracts.create`          | `login`, `senha`, `modoaquisicao` exigidos para serviço de Internet | Documentado             | n/d        | Só a falta de `nas` foi observada                                                                                    |
+| `crm.contracts.createByCpfCnpj` | Sucesso (200)                                                       | Documentado             | n/d        | **Nenhum sucesso foi observado nesta rota**; assume-se o formato da rota por id                                      |
+| `crm.contracts.createByCpfCnpj` | 400 "Não encontrado cliente CRM" (`CUSTOMER_NOT_IN_CRM`)            | Observado (bruta)       | 2026-11-05 | Releitura: nada foi adicionado. Só CPF foi exercitado (CNPJ não)                                                     |
+| `crm.contracts.list`            | 200 com contratos                                                   | Observado (bruta)       | 2026-11-06 | Valores pessoais mascarados                                                                                          |
+| `crm.contracts.list`            | 200 sem contratos                                                   | Observado (bruta)       | 2026-11-05 |                                                                                                                      |
+| `crm.contracts.list`            | 400 para documento que não é cliente CRM                            | Observado (bruta)       | 2026-11-05 | `REJECTED`, sem `reason`                                                                                             |
+
+### `preRegistrations`
+
+| Operação                       | Cenário                                            | Evidência         | Data       | Observação                                                                                           |
+| ------------------------------ | -------------------------------------------------- | ----------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `preRegistrations.create`      | Sucesso (`/F`): 200 `{ message }`                  | Documentado       | 2026-11-05 | O texto do corpo é o exemplo do fornecedor; ao vivo só o status 200 e a chave `message` foram vistos |
+| `preRegistrations.create`      | CPF existente: 402 (`DOCUMENT_ALREADY_REGISTERED`) | Observado (bruta) | 2026-11-05 | Releitura: nenhum cliente nem contrato adicionado                                                    |
+| `preRegistrations.create`      | PJ (`/J`)                                          | Documentado       | n/d        | Nunca exercitado; CNPJ não testado                                                                   |
+| `preRegistrations.listPlans`   | Lista de planos do pré-cadastro                    | Observado (corpo) | 2026-11-05 | Requisição multipart, sem barra final                                                                |
+| `preRegistrations.listDueDays` | Lista de vencimentos                               | Observado (corpo) | 1.x        |                                                                                                      |
+| `preRegistrations.listSellers` | Lista de vendedores                                | Observado (corpo) | 1.x        |                                                                                                      |
+
+### `contracts`
+
+| Operação                      | Cenário                                                                                     | Evidência                      | Data       | Observação                                                                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `contracts.list`              | Filtro por contrato: array com um resumo                                                    | Observado (corpo)              | 1.x        |                                                                                                                                      |
+| `contracts.updateStatus`      | Suspenso para Ativo: 200 com `resposta`                                                     | Observado (bruta)              | 2026-11-05 | A releitura confirmou Ativo                                                                                                          |
+| `contracts.updateStatus`      | Ativo para Suspenso: 200 com `resposta`                                                     | Observado (bruta)              | 2026-11-05 | A releitura confirmou Suspenso                                                                                                       |
+| `contracts.updateStatus`      | Inativo para Ativo: 200                                                                     | Observado, corpo não capturado | n/d        | Confirmado por releitura                                                                                                             |
+| `contracts.updateStatus`      | Ativo para Inativo: 400 `{error:"Status de Contrato não alterado."}` (`STATUS_NOT_CHANGED`) | Reconstruído                   | 2026-11-05 | Status e texto vêm do relato do suporte; a releitura mostrou o contrato ainda Ativo (o painel não oferece Inativo a partir de Ativo) |
+| `contracts.updateStatus`      | Status 6 ("Novo")                                                                           | Documentado                    | n/d        | Nunca observado; significado e transições desconhecidos                                                                              |
+| `contracts.updateStatus`      | Status 3, 5 e 7                                                                             | Documentado                    | n/d        | Vêm do painel do SGP; nunca enviados                                                                                                 |
+| `contracts.update`            | `forma_cobranca`: 200 com `resposta.alterados`                                              | Observado (bruta)              | 2026-11-05 | A leitura seguinte mostrou a nova forma. Os demais campos documentados pelo fornecedor não são aceitos pelo SDK                      |
+| `contracts.listStatusReasons` | Lista de motivos (`[{ id, motivo }]`)                                                       | Reconstruído                   | 2026-11-05 | Lista conhecida por prosa do suporte; formato do mapa de rotas validadas; sem captura                                                |
+
+### `services`
+
+| Operação              | Cenário                                                          | Evidência         | Data       | Observação                                                                                                                            |
+| --------------------- | ---------------------------------------------------------------- | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `services.changePlan` | 200 `{ msg }` (ida e volta de plano)                             | Observado (bruta) | 2026-11-05 | Observado duas vezes, corpo idêntico; só `servico_tipo` 1 enviado                                                                     |
+| `services.addTv`      | 201 com `servico_id`                                             | Observado (bruta) | 2026-11-05 |                                                                                                                                       |
+| `services.addTv`      | 400 contrato não ativo (`CONTRACT_NOT_ACTIVE`)                   | Reconstruído      | 2026-11-05 | Texto vindo da prosa do relato (o formato `errors` como array não está provado em captura bruta); a releitura mostrou nada adicionado |
+| `services.removeTv`   | 200 `{ msg, clientecontrato_id, servico_id }` (DELETE multipart) | Observado (bruta) | 2026-11-05 | Remoção do serviço criado na mesma execução                                                                                           |
+
+### `plans`, `invoices`, `workOrders`, `occurrences`
+
+| Operação                  | Cenário                                                            | Evidência         | Data       | Observação                                                                                                    |
+| ------------------------- | ------------------------------------------------------------------ | ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `plans.list`              | Catálogo de planos                                                 | Observado (corpo) | 2026-11-05 |                                                                                                               |
+| `invoices.list`           | Página vazia de um cliente sem títulos                             | Observado (corpo) | 2026-11-05 |                                                                                                               |
+| `invoices.list`           | Página com títulos                                                 | Reconstruído      | n/d        | Nunca houve captura de uma página populada: chaves e tipos seguem a fixture da 1.x, os valores são inventados |
+| `workOrders.list`         | Filtro por contrato                                                | Observado (corpo) | 2026-11-05 |                                                                                                               |
+| `workOrders.list`         | Primeira página de várias (`limit` 1, `total` maior que `parcial`) | Observado (corpo) | 1.x        |                                                                                                               |
+| `workOrders.listReasons`  | Lista de motivos                                                   | Observado (corpo) | 1.x        | `id` e `codigo` distintos                                                                                     |
+| `occurrences.create`      | Sucesso: `status` 1, `id`, `protocolo`                             | Observado (corpo) | 1.x        | Corpo mascarado; a data da resposta não foi registrada                                                        |
+| `occurrences.create`      | Recusa: HTTP 200 com `status` 0 e `msg`                            | Reconstruído      | n/d        | Vem do contrato da 1.x; sem captura nem releitura, por isso `effect: "unknown"`                               |
+| `occurrences.create`      | Ligação ocorrência para OS pelo `protocolo`                        | Observado uma vez | n/d        | **Não confirmada**: confira a OS antes de confiar nela                                                        |
+| `occurrences.listTypes`   | Lista de tipos                                                     | Observado (corpo) | 1.x        | `classificacoes` e `setores` sempre vazios nas capturas                                                       |
+| `occurrences.listMethods` | Lista de métodos                                                   | Observado (corpo) | 1.x        |                                                                                                               |
+
+### `documents`, `coverage`, `catalogs`, `experimental`
+
+| Operação                        | Cenário                                   | Evidência         | Data | Observação                                                                                                                                                                                                                                     |
+| ------------------------------- | ----------------------------------------- | ----------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `documents.add`                 | Sucesso: 2xx com corpo vazio              | Reconstruído      | n/d  | Vem do contrato da 1.x e de seus testes; sem captura dos headers                                                                                                                                                                               |
+| `documents.list`                | Lista de documentos                       | Observado (corpo) | 1.x  |                                                                                                                                                                                                                                                |
+| `coverage.check`                | Gateway SGPMaps; Geogrid; sem CTO no raio | Observado (corpo) | 1.x  | Geogrid manda números como texto                                                                                                                                                                                                               |
+| `catalogs.listPops`             | Lista de POPs                             | Observado (corpo) | 1.x  |                                                                                                                                                                                                                                                |
+| `catalogs.listNas`              | Lista de NAS                              | Observado (corpo) | 1.x  |                                                                                                                                                                                                                                                |
+| `catalogs.listBillingProfiles`  | Lista de portadores                       | Observado (corpo) | 1.x  |                                                                                                                                                                                                                                                |
+| `experimental.annotations.list` | Resposta com anotações de vários clientes | Reconstruído      | n/d  | Corpo sintético no formato observado; os tipos dos campos foram contados ao vivo, sem persistir nenhuma anotação. Que o SGP ignora os filtros `cliente_id` e `contrato_id` foi observado ao vivo, mas sem captura positiva do cliente de teste |
+
+### Comportamentos transversais
+
+| Comportamento                                                                                                          | Evidência                                              | Observação                                                                  |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------- |
+| 403 "credenciais ... não foram fornecidas" (rota fora do token, barra final errada) e 403/401 "credenciais incorretas" | Observado (registro de decisão do projeto, 2026-11-05) | Corpo bruto não anexado ao repositório (não verificado)                     |
+| Erros `errors` como array ("Ocorreu um erro: ...") são o invólucro genérico do SGP                                     | Observado (registro de decisão do projeto)             | Por isso ficam em `effect: "unknown"` salvo recusa conhecida da operação    |
+| `RATE_LIMITED` (429), limites de taxa do SGP                                                                           | Nunca observado                                        | O ajuste de retry é estimativa                                              |
+| 502 com corpo HTML como `UPSTREAM`                                                                                     | Coberto por teste                                      | Se foi visto numa resposta real: não verificado                             |
+| `request()`                                                                                                            | Sem evidência própria                                  | Depende da rota chamada: nenhum sucesso ou recusa de negócio é interpretado |
+
+## Lacunas conhecidas
+
+- Só PF e CPF foram exercitados em `preRegistrations.create` e `crm.customers.create`. PJ, CNPJ e os
+  tipos `E`/`EJ` não foram provados (`E`/`EJ` só via `request()`).
+- O sucesso de `crm.contracts.createByCpfCnpj` nunca foi visto.
+- Recusas que são apenas reconstruídas: `STATUS_NOT_CHANGED`, `CUSTOMER_NOT_IN_CRM` por id,
+  `CONTRACT_NOT_ACTIVE`, o 404 de `crm.customers.updateStatus` (só o corpo veio de uma captura da
+  1.x), a recusa `status: 0` de `occurrences.create` e o corpo vazio de `documents.add`. Se o SGP mandar outra forma, o efeito cai em `"unknown"`.
+- Não se conhece rota de API para um segundo contrato de um cliente definitivo nem para extras de
+  serviço (roteador, multimídia, telefonia): hoje, só pelo painel do SGP.
+- `experimental.annotations.list` depende do SGP corrigir o filtro no lado dele, e o isolamento local
+  é uma heurística por padrão de chave: dados de outro cliente sob chaves que não são de identidade
+  não seriam detectados.
+- Limites de taxa do SGP e a ligação ocorrência para OS por `protocolo` não foram confirmados.

package/MIGRATION.md

@@ -0,0 +1,283 @@
+# Migração do 1.x para o 2.0
+
+A 2.0 é uma quebra de contrato deliberada: novos nomes, novo modelo de resultado, novos códigos de
+erro e mais fidelidade aos dados do SGP. **Não há aliases**: nenhum método ou export do 1.x
+permanece. A série 1.x (última: 1.2.0) está congelada e não recebe mais mudanças; quem não puder
+migrar já deve fixar essa versão.
+
+O guia está na ordem em que a migração costuma acontecer: [cliente](#1-criação-do-cliente),
+[métodos](#2-mapa-de-métodos), [resultado](#3-modelo-de-resultado),
+[erros](#4-códigos-de-erro), [escritas](#5-escritas-outcome-vira-effect),
+[comportamento](#6-mudanças-de-comportamento), [exports](#7-exports-removidos-e-renomeados).
+
+## 1. Criação do cliente
+
+```ts
+// 1.x
+const sgp = createSgpClient({ baseUrl, token, app, timeoutMs, fetch });
+
+// 2.0
+const sgp = createSgpClient({
+  baseUrl, // somente a origem: sem caminho, query ou credenciais
+  credentials: { kind: "token", token, app },
+  timeoutMs, // agora é o padrão por chamada (20 000 ms se omitido)
+  maxRetries, // novo, opcional (padrão 0)
+  hooks, // novo, opcional
+  fetch,
+});
+```
+
+- `token` e `app` soltos deixam de existir: vão em `credentials`.
+- `createSgpClient` **lança** `InvalidConfigurationError` para configuração inválida (URL que não é uma
+  origem `http(s)`, token ou app vazios, `timeoutMs` ou `maxRetries` fora do domínio, hooks que não
+  são funções). No 1.x a configuração não era validada. Um `baseUrl` com prefixo de caminho (que o
+  1.x concatenava às rotas) agora é recusado.
+- As chamadas aceitam um último argumento `options` com `abortSignal`, `timeoutMs` e `maxRetries`.
+
+## 2. Mapa de métodos
+
+Parâmetros posicionais (`clienteId`, `file`) passaram a campos do objeto de entrada, com os nomes do
+SGP.
+
+| 1.x                                                     | 2.0                                                                     |
+| ------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `ura.listClients(params?)`                              | `customers.list(input?)`                                                |
+| `ura.lookupCustomer(params)`                            | `customers.search(input)`                                               |
+| `ura.listContracts(params?)`                            | `contracts.list(input?)`                                                |
+| `ura.listServiceOrders(params?)`                        | `workOrders.list(input?)`                                               |
+| `ura.listInvoices(params?)`                             | `invoices.list(input?)`                                                 |
+| `ura.listPlans()`                                       | `plans.list()`                                                          |
+| `ura.listPops()`                                        | `catalogs.listPops()`                                                   |
+| `ura.listNas()`                                         | `catalogs.listNas()`                                                    |
+| `ura.listPaymentCarriers()`                             | `catalogs.listBillingProfiles()`                                        |
+| `ura.checkCoverage(params)`                             | `coverage.check(input)`                                                 |
+| `ura.listOccurrenceMethods()`                           | `occurrences.listMethods()`                                             |
+| `ura.openTicket(params)`                                | `occurrences.create(input)`                                             |
+| `ura.listAnnotations(params)` (experimental)            | `experimental.annotations.list(input)` (continua experimental)          |
+| `os.listOccurrenceTypes()`                              | `occurrences.listTypes()`                                               |
+| `os.listOccurrenceReasons()`                            | `workOrders.listReasons()`                                              |
+| `precadastro.listDueDays()`                             | `preRegistrations.listDueDays()`                                        |
+| `precadastro.listSellers()`                             | `preRegistrations.listSellers()`                                        |
+| `crm.createIndividualCustomer(params)`                  | `crm.customers.create({ personType: "F", ... })`                        |
+| `crm.createCompanyCustomer(params)`                     | `crm.customers.create({ personType: "J", ... })`                        |
+| `crm.createContract(clienteId, params)`                 | `crm.contracts.create({ cliente_id: clienteId, ... })`                  |
+| `crm.updateCustomerStatus(clienteId, params)`           | `crm.customers.updateStatus({ cliente_id: clienteId, status_id, ... })` |
+| `suporte.addCustomerDocument(clienteId, file, params?)` | `documents.add({ cliente_id: clienteId, file, descricao? })`            |
+| `suporte.listCustomerDocuments(clienteId)`              | `documents.list({ cliente_id: clienteId })`                             |
+
+Nada do 1.x foi removido sem equivalente: os 23 métodos acima têm destino.
+
+Operações que **não existiam** no 1.x: `preRegistrations.create`, `preRegistrations.listPlans`,
+`contracts.update`, `contracts.updateStatus`, `contracts.listStatusReasons`, `services.changePlan`,
+`services.addTv`, `services.removeTv`, `crm.contracts.createByCpfCnpj`, `crm.contracts.list` e
+`request()`. Veja o [README](README.md#referência-de-operações).
+
+Mudanças de forma na entrada, além da posição dos argumentos:
+
+- Os endereços mantêm os nomes do SGP: `crm.customers.create` segue com `endereco` e
+  `crm.contracts.create` com `endereco_instalacao` e `endereco_cobranca`. `preRegistrations.create`
+  (nova no 2.0) recebe o endereço em campos soltos no topo da entrada (`logradouro`, `numero`,
+  `bairro`, `cidade`, `cep`, `uf`, ...), sem agrupamento.
+- O arquivo de `documents.add` mantém o formato `{ data, filename, contentType? }` (o tipo se chama
+  agora `DocumentFile`).
+- Toda entrada é verificada localmente e **chaves desconhecidas são recusadas** (`INVALID_INPUT`).
+  Para um campo que a operação ainda não cobre, use `request()`.
+
+## 3. Modelo de resultado
+
+```ts
+// 1.x
+if (result.success) {
+  result.data;
+  result.warnings;
+} else {
+  result.error.status;
+  result.error.code;
+  result.error.detail;
+  result.error.endpoint;
+}
+
+// 2.0
+if (result.ok) {
+  result.data;
+  result.warnings;
+  result.response;
+  result.attempts;
+} else {
+  result.error.code;
+  result.error.sgp;
+  result.error.operation;
+  result.response;
+  result.attempts;
+}
+```
+
+| 1.x                                          | 2.0                                                                                                            |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `success: boolean`                           | `ok: boolean`                                                                                                  |
+| `error.status` (0 sem resposta)              | `response?.status`; `response` é `null` quando não houve resposta HTTP (inclui recusa local)                   |
+| `error.detail` (texto único)                 | `error.sgp`: `detail`, `msg`, `error` e `errors` **com os valores como vieram**; compor um texto é com você    |
+| `error.endpoint` (caminho)                   | `error.operation` (nome da operação, ex.: `customers.list`); o caminho não faz mais parte do erro              |
+| `error.message`                              | igual: escrita pelo SDK, em inglês                                                                             |
+| (não havia)                                  | `error.reason` (por operação), `error.issues` (caminhos de `INVALID_RESPONSE`), `attempts`, `diagnostics`      |
+| (corpo bruto nunca disponível)               | `response.status`, `response.headers` (credenciais redigidas) e `response.body` em todo resultado com resposta |
+| `SchemaWarning { path, expected, received }` | acrescenta `dropped`: o campo que de fato ficou fora de `data`                                                 |
+
+`SgpResult` e `SgpWriteResult` viraram um tipo só, `SgpResult<T>`. Veja o
+[modelo de resultado](README.md#o-modelo-de-resultado).
+
+## 4. Códigos de erro
+
+| 1.x                                            | 2.0                                                                                                                                                                                                                                                                   |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `UNAUTHORIZED`                                 | `UNAUTHORIZED` (HTTP 401 sempre; 403 com credenciais incorretas)                                                                                                                                                                                                      |
+| `ROUTE_NOT_ALLOWED`                            | `FORBIDDEN` com `reason: "TOKEN_ROUTE_NOT_ALLOWED"` (403 "credenciais não foram fornecidas"). Um 401 com esse texto é `UNAUTHORIZED`. `ROUTE_NOT_ALLOWED` ainda existe como código, para a restrição local do SDK: hoje só `request()` na rota de anotações o devolve |
+| `NOT_FOUND`                                    | `NOT_FOUND`                                                                                                                                                                                                                                                           |
+| `METHOD_NOT_ALLOWED`                           | `REJECTED` (o 405 não tem código próprio)                                                                                                                                                                                                                             |
+| `VALIDATION` (status 0, recusa local)          | `INVALID_INPUT` (`attempts: 0`, `response: null`)                                                                                                                                                                                                                     |
+| `VALIDATION` (4xx do SGP)                      | `REJECTED`, ou `RATE_LIMITED` no 429                                                                                                                                                                                                                                  |
+| `VALIDATION` (2xx de escrita que não confirma) | `INVALID_RESPONSE`                                                                                                                                                                                                                                                    |
+| `SCHEMA_MISMATCH`                              | `INVALID_RESPONSE`, com `error.issues` apontando os caminhos (sem valores)                                                                                                                                                                                            |
+| `UPSTREAM`                                     | `UPSTREAM` (5xx)                                                                                                                                                                                                                                                      |
+| `TIMEOUT`                                      | `TIMEOUT` para o prazo do SDK; **`ABORTED`** para o seu `abortSignal` (que o 1.x não tinha)                                                                                                                                                                           |
+| `NETWORK`                                      | `NETWORK`                                                                                                                                                                                                                                                             |
+| `UNKNOWN`                                      | deixa de existir: 401/403 de outro tipo viram `UNAUTHORIZED`/`FORBIDDEN`; 3xx e demais status fora do contrato viram `INVALID_RESPONSE`                                                                                                                               |
+
+Novo: `INVALID_INPUT`, `FORBIDDEN`, `RATE_LIMITED` (nunca observado), `REJECTED`, `ABORTED`,
+`INVALID_RESPONSE`. A classificação agora se faz pelo **status HTTP**, e o corpo só refina o 403
+(o 1.x lia o texto também para decidir 401).
+
+## 5. Escritas: `outcome` vira `effect`
+
+| 1.x                                                  | 2.0                                  |
+| ---------------------------------------------------- | ------------------------------------ |
+| `error.outcome === "not_applied"`                    | `error.effect === "none"`            |
+| `error.outcome === "unknown"`                        | `error.effect === "unknown"`         |
+| `SgpWriteResult<T>`, `SgpWriteError`, `WriteOutcome` | `SgpResult<T>`, `SgpError`, `Effect` |
+
+A regra mudou, e é mais conservadora:
+
+- 1.x: qualquer 4xx era `not_applied`, exceto o invólucro genérico do SGP (`errors` como array).
+- 2.0: `"none"` exige evidência: recusa local, cancelamento antes do envio, 4xx com formato de erro de
+  campo ou de negócio (`errors` como objeto, `error` ou `detail` como texto) ou uma recusa que a
+  operação declara como conhecida. Um 4xx com corpo ilegível ou de formato não reconhecido é
+  `"unknown"`.
+- O 1.x só dava `outcome` em `crm.*`, `ura.openTicket` e `suporte.addCustomerDocument`. No 2.0
+  **toda escrita** tem `effect`, incluindo as novas, e `request()` (sempre `"unknown"` depois do envio).
+- A recusa de `ura.openTicket` com HTTP 200 e `status: 0` era `VALIDATION`/`unknown`; agora é
+  `REJECTED` com `effect: "unknown"`.
+
+Os `reason`s conhecidos e o que fazer diante de `"unknown"` estão no README.
+
+## 6. Mudanças de comportamento
+
+**Fidelidade.** O 1.x descartava chaves desconhecidas em todos os níveis e declarava como `[{}]` os
+arrays sem amostra, o que fazia `ura.listClients` devolver `contratos: [{}]` como se estivesse certo.
+A 2.0 preserva toda chave que recebe, em todos os níveis, e tipa o que conhece:
+
+- Acabaram os arrays-placeholder do 1.x (`clientes[].contratos`/`titulos`, `contratos[].telefones_cargos`,
+  `outros`, `anotacoes`, `ordens_servicos[].tecnicos_auxiliares`/`classificacoes`, `planos[].combo`,
+  `classificacoes`/`setores` de tipos e motivos, `acordados`/`cobrados` de títulos): chegam como o SGP
+  mandou.
+- Ausente, `null` e `""` são preservados. Um item que o SDK não consegue interpretar é
+  `INVALID_RESPONSE`, nunca um objeto vazio.
+- Campos estruturais (ids e o que a navegação exige) têm validação estrita (`INVALID_RESPONSE`); campos
+  secundários com tipo inesperado saem de `data` com um `warning`, e o original fica em `response.body`.
+- `coverage.check` **não converte** mais nada: `lat`, `lng` e `distancia` que o Geogrid manda como
+  texto continuam texto. Confira o tipo antes de calcular.
+- As listas que o SGP pagina (`customers.list`, `workOrders.list`, `invoices.list`) devolvem uma
+  página com a `paginacao` do SGP; `total` nunca é calculado. As sem paginação mantêm o formato do SGP.
+
+**IDs com marca.** `CustomerId`, `PlanId` e `PreRegistrationPlanId` são tipos de compilação: um número
+solto não é aceito onde um id é esperado, nem um id de plano onde cabe um de cliente. Marque um
+número em que você confia com `as CustomerId`. Os dois catálogos de planos (`plans.list` e
+`preRegistrations.listPlans`) têm espaços de ids diferentes e nunca se misturam.
+
+**Obrigatoriedade.** Só os campos que o fornecedor marca como obrigatórios são obrigatórios; regras do
+painel do SGP não são validadas localmente. A decisão de aceitar ou não vem do SGP.
+
+**Tempo, cancelamento e retry.** Um orçamento de tempo por chamada (tentativas, esperas e leitura do
+corpo), `timeoutMs` e `abortSignal` por chamada. O 1.x não tinha retry e continua sem retry por padrão:
+`maxRetries` (padrão 0) é opt-in e vale só para leituras, em falhas transitórias. **Escritas nunca são
+repetidas** (como no 1.x), e `request()` também não.
+
+**Hooks.** `onRequest`, `onResponse` e `onError`, síncronos, só com metadados. Um hook que falha
+nunca muda o resultado.
+
+**Redirecionamentos.** Continuam sem ser seguidos; a diferença é que um 3xx agora é `INVALID_RESPONSE`
+(no 1.x era `UNKNOWN`).
+
+**Anotações (`experimental.annotations.list`).** Chaves desconhecidas deixam de ser descartadas, e cada
+anotação traz `raw`. O corpo da resposta é retido (`{ kind: "withheld" }`) em qualquer status, e uma
+anotação com identidade indecidível ou de outro cliente, em qualquer profundidade, falha a chamada
+inteira com `INVALID_RESPONSE`. `request()` recusa essa rota.
+
+**Cobrança, status e aquisição.** Os códigos agora são constantes em inglês (veja abaixo). O valor 2 de
+`modoaquisicao` continua não aceito (recusado ao vivo).
+
+**Dados sensíveis.** `omitSensitive` e as tuplas por endpoint (`clientPersonalKeys` etc.) foram
+substituídos por três ferramentas (denylist deu lugar a allowlist):
+
+| 1.x                                                 | 2.0                                                                                                  |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| tuplas `*SecretKeys` / `*PersonalKeys` por endpoint | `getSensitivity("customers.list")`: chaves secretas e pessoais da entrada e da resposta, por caminho |
+| `omitSensitive(item, chaves)` (remove as listadas)  | `pick(origem, allowlist)` (só sai o que for nomeado)                                                 |
+| (não havia)                                         | `toSafeLog(result)`: versão de um resultado própria para log                                         |
+
+Os corpos em `response.body` **não** são redigidos (os headers são): podem repetir credenciais ou
+dados pessoais. Nunca registre o resultado cru.
+
+## 7. Exports removidos e renomeados
+
+**Removidos sem substituto:** as `*Definition`, `*KeyFields`, `*ItemPath`, `*SecretKeys`,
+`*PersonalKeys`, `listAnnotationsSchema`, `omitSensitive`. A definição de uma operação é interna.
+
+**Constantes e tipos:**
+
+| 1.x                                                                                        | 2.0                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `formaCobrancaCodigo` (`boleto`, `debitoAutomatico`, `carne`, `cobrancaRecorrente`, `pix`) | `BILLING_METHOD` (`boleto`, `automaticDebit`, `booklet`, `recurringCharge`, `pix`)                                                                                                                                         |
+| `modoAquisicao` (`proprio`, `comodato`)                                                    | `ACQUISITION_MODE` (`owned`, `loan`)                                                                                                                                                                                       |
+| `crmStatus` (`emAnalise` ... `analiseViabilidadeTecnica`)                                  | `CRM_STATUS` (`underAnalysis`, `approved`, `rejected`, `awaitingContact`, `tryingContact`, `contractMadeInSgp`, `technicalInfeasibility`, `contractInProspecting`, `rejectedCreditBureau`, `technicalFeasibilityAnalysis`) |
+| (não havia)                                                                                | `CONTRACT_STATUS`, `SERVICE_TYPE`                                                                                                                                                                                          |
+| `FormaCobrancaCodigo`, `ModoAquisicao`, `CrmStatusId`                                      | `BillingMethod`, `AcquisitionMode`, `CrmStatus`                                                                                                                                                                            |
+| `SgpClientConfig`                                                                          | `ClientOptions`                                                                                                                                                                                                            |
+| `SgpFile`                                                                                  | `DocumentFile`                                                                                                                                                                                                             |
+| `SgpWriteResult`, `SgpWriteError`, `WriteOutcome`                                          | `SgpResult`, `SgpError`, `Effect`                                                                                                                                                                                          |
+| `UraClient`, `OsClient`, `PrecadastroClient`, `SuporteClient`                              | clientes por grupo (`CustomersClient`, `ContractsClient`, ...) dentro de `SgpClient`                                                                                                                                       |
+
+**Tipos de entrada e resposta** (`*Params`/`*Response` viraram `*Input`/`*Data`):
+
+| 1.x                                                                                             | 2.0                                                                                                                            |
+| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `ListClientsParams` / `ListClientsResponse`                                                     | `CustomersListInput` / `CustomersListData`                                                                                     |
+| `LookupCustomerParams` / `LookupCustomerResponse`                                               | `CustomersSearchInput` / `CustomersSearchData`                                                                                 |
+| `ListContractsParams` / `ListContractsResponse`                                                 | `ContractsListInput` / `ContractsListData`                                                                                     |
+| `ListServiceOrdersParams` / `ListServiceOrdersResponse`                                         | `WorkOrdersListInput` / `WorkOrdersListData`                                                                                   |
+| `ListInvoicesParams` / `ListInvoicesResponse`                                                   | `InvoicesListInput` / `InvoicesListData`                                                                                       |
+| `ListPlansResponse`                                                                             | `PlansListData` (e `PlanId`)                                                                                                   |
+| `ListPopsResponse`, `ListNasResponse`, `ListPaymentCarriersResponse`                            | `CatalogsListPopsData`, `CatalogsListNasData`, `CatalogsListBillingProfilesData`                                               |
+| `CheckCoverageParams` / `CheckCoverageResponse`                                                 | `CoverageCheckInput` / `CoverageCheckData`                                                                                     |
+| `ListOccurrenceMethodsResponse`, `ListOccurrenceTypesResponse`, `ListOccurrenceReasonsResponse` | `OccurrencesListMethodsData`, `OccurrencesListTypesData`, `WorkOrdersListReasonsData`                                          |
+| `OpenTicketParams` / `OpenTicketResponse`                                                       | `OccurrenceCreateInput` / `OccurrenceCreateData`                                                                               |
+| `ListDueDaysResponse`, `ListSellersResponse`                                                    | `PreRegistrationsListDueDaysData`, `PreRegistrationsListSellersData`                                                           |
+| `CreateIndividualCustomerParams`, `CreateCompanyCustomerParams`, `CreateCustomerResponse`       | `CrmCustomerCreateIndividualInput`, `CrmCustomerCreateCompanyInput` (união: `CrmCustomerCreateInput`), `CrmCustomerCreateData` |
+| `CreateContractParams` / `CreateContractResponse`                                               | `CrmContractCreateInput` / `CrmContractCreateData`                                                                             |
+| `UpdateCustomerStatusParams` / `UpdateCustomerStatusResponse`                                   | `CrmCustomerUpdateStatusInput` / `CrmCustomerUpdateStatusData`                                                                 |
+| `AddCustomerDocumentParams` (a resposta era `data: null`)                                       | `DocumentAddInput` (inclui `cliente_id` e `file`); a resposta continua `null`                                                  |
+| `ListCustomerDocumentsResponse`                                                                 | `DocumentsListData`                                                                                                            |
+| `ListAnnotationsParams` / `ListAnnotationsResponse`                                             | `ExperimentalAnnotationsListInput` / `ExperimentalAnnotationsListData`                                                         |
+
+`SgpAddress` continua exportado. `SgpResult`, `SgpError`, `SgpErrorCode` e `SchemaWarning` mantêm o
+nome, com o formato novo descrito acima.
+
+## Roteiro sugerido
+
+1. Troque a criação do cliente (`credentials`) e trate `InvalidConfigurationError` na inicialização.
+2. Renomeie os métodos pela tabela e passe os argumentos posicionais para o objeto de entrada.
+3. Troque `success` por `ok`, `error.status` por `response?.status`, `error.detail` por `error.sgp` e os
+   `switch` de `error.code` pelos códigos novos.
+4. Nas escritas, troque `outcome` por `effect` e releia o estado antes de reenviar após `"unknown"`.
+5. Substitua `omitSensitive` e as tuplas por `pick`/`toSafeLog`/`getSensitivity`.
+6. Rode a verificação de tipos: ids com marca e chaves desconhecidas aparecem como erros de
+   compilação ou como `INVALID_INPUT`.