sgp-sdk 1.2.0 → 2.0.0-beta.2

package/README.md

@@ -1,304 +1,503 @@
 # sgp-sdk
 
-Unofficial TypeScript client for the HTTP API of SGP, the ISP ERP by TSMX. Not affiliated with
-TSMX. It is a _dumb_ SDK: typed inputs and outputs, normalized errors, no business rules. Your
-application decides what to do with the data.
+Cliente TypeScript não oficial para a API HTTP do SGP, o ERP de provedores de internet da TSMX.
+Sem vínculo com a TSMX.
 
-- Reads, plus writes on `crm`, `ura.openTicket` and `suporte.addCustomerDocument` (see
-  [Writes](#writes)).
-- ESM package with types, Node >= 22 (also runs on Bun). The only runtime dependency is `zod`.
-- Methods never throw for network, HTTP or schema failures; they return a result object.
+> **Versão 2.0 (beta).** Esta documentação descreve a 2.0, publicada em beta na tag `next` do npm
+> (`npm install sgp-sdk@next`); a `latest` continua na 1.x até a 2.0.0 estável. A série 1.x está
+> congelada: não recebe mais mudanças. Para migrar, leia [MIGRATION.md](MIGRATION.md).
 
-## Install
+## O que é e o que não é
+
+O sgp-sdk é um **gateway de integração**: encapsula o transporte e a semântica conhecida de cada
+operação do SGP, preserva todos os dados que recebe, devolve falhas com códigos estáveis e diz
+explicitamente o que sabe, e o que não sabe, sobre o efeito de uma escrita.
+
+Ele **não é** uma camada de política. Quem decide autorização, orquestração de vários passos,
+recuperação e o que chega a um usuário ou a um agente é a sua aplicação. O SDK também não
+renomeia campos (`cpfcnpj`, `planobase_id` e os demais chegam e saem com os nomes do SGP) e não
+inventa valores: ausente, `null` e `""` chegam como o SGP mandou.
+
+- **Somente servidor.** O cliente carrega o token do SGP; navegadores não são suportados.
+- **ESM**, Node >= 22 e Bun. A única dependência de runtime é `zod`. Os testes unitários rodam no
+  Bun; o Node é coberto pelo teste de fumaça do pacote construído.
+- Nenhum método lança exceção por falha esperada (input inválido, rede, timeout, cancelamento,
+  recusa do SGP, resposta incompatível): tudo volta no resultado. Só `createSgpClient` lança, para
+  configuração inválida (`InvalidConfigurationError`), além de bugs internos.
+- Tudo fora de `experimental.*` segue SemVer.
+
+Instância de SGP: a versão do SGP em que cada operação foi comprovada é **desconhecida**. O que foi
+provado, onde e quando está em [COMPATIBILITY.md](COMPATIBILITY.md).
+
+## Instalação
 
 ```sh
 bun add sgp-sdk
-# or
+# ou
 npm install sgp-sdk
 ```
 
-Types resolve under `"moduleResolution": "bundler"` (Bun, Next.js, tsx, Vite, esbuild) and under
-`node16` / `nodenext`: the emitted `.d.ts` files carry explicit `.js` extensions.
+Os tipos resolvem com `moduleResolution` `bundler` e `node16`/`nodenext`.
 
-## Usage
+## Quickstart
 
 ```ts
-import { clientPersonalKeys, createSgpClient, omitSensitive } from "sgp-sdk";
+import { CONTRACT_STATUS, createSgpClient } from "sgp-sdk";
 
 const sgp = createSgpClient({
-  baseUrl: "https://sgp.example.com",
-  token: "<token of your app>",
-  app: "<app name>",
-  // timeoutMs: 20_000,  // default
-  // fetch: fakeFetch,   // default: the global fetch (inject a fake in tests)
+  baseUrl: "https://sgp.example.com", // origem da instância, sem caminho
+  credentials: { kind: "token", token: "<token>", app: "<nome do app>" }, // carregue como preferir
 });
 
-const plans = await sgp.ura.listPlans();
-if (plans.success) {
+// Uma leitura: `ok` estreita o resultado.
+const plans = await sgp.plans.list();
+if (plans.ok) {
   console.log(plans.data.planos.length, plans.warnings ?? []);
 } else {
-  console.error(plans.error.code, plans.error.status, plans.error.endpoint);
+  console.error(plans.error.code, plans.response?.status);
 }
 
-const clients = await sgp.ura.listClients({ cpfcnpj: "00000000000", limit: 1 });
-if (clients.success) {
-  for (const client of clients.data.clientes) {
-    const safe = omitSensitive(client, clientPersonalKeys); // no name, CPF/CNPJ, address, contacts
-    console.log(safe.id);
-  }
+// Uma escrita: em caso de falha, `error.effect` diz o que fazer.
+const change = await sgp.contracts.updateStatus({ contrato: 1001, status: CONTRACT_STATUS.active });
+if (change.ok) {
+  console.log(change.data.resposta.contrato_status);
+} else if (change.error.effect === "none") {
+  // Nada foi aplicado: corrigir a entrada e chamar de novo não duplica nada.
+  console.error(change.error.code, change.error.reason);
+} else {
+  // "unknown": o SGP pode ter aplicado. Leia o estado (contracts.list) antes de enviar de novo.
 }
 ```
 
-The SDK never reads the environment: load the credentials your way and pass them in.
-
-### Methods
-
-Field names in params and responses are exactly what SGP sends. Each method's JSDoc cites the HTTP
-method and path.
-
-| Method                                                  | SGP route                                               |
-| ------------------------------------------------------- | ------------------------------------------------------- |
-| `ura.listClients(params?)`                              | `POST /api/ura/clientes/`                               |
-| `ura.lookupCustomer(params)`                            | `POST /api/ura/consultacliente/`                        |
-| `ura.listContracts(params?)`                            | `POST /api/ura/listacontrato/`                          |
-| `ura.listAnnotations(params)` **experimental**          | `GET /api/ura/cliente/anotacao/list/`                   |
-| `ura.listServiceOrders(params?)`                        | `POST /api/ura/ordemservico/list/`                      |
-| `ura.listInvoices(params?)`                             | `POST /api/ura/titulos/`                                |
-| `ura.listPops()`                                        | `POST /api/ura/pops/`                                   |
-| `ura.listNas()`                                         | `POST /api/ura/nas/list/`                               |
-| `ura.listPaymentCarriers()`                             | `GET /api/ura/portador/`                                |
-| `ura.checkCoverage(params)`                             | `GET /api/ura/viabilidadeinstalacao`                    |
-| `ura.listPlans()`                                       | `GET /api/ura/consultaplano/`                           |
-| `ura.listOccurrenceMethods()`                           | `GET /api/ura/ocorrencia/metodo/list/`                  |
-| `ura.openTicket(params)`                                | `POST /api/ura/chamado/`                                |
-| `os.listOccurrenceTypes()`                              | `GET /api/os/ocorrencia/tipo/list/`                     |
-| `os.listOccurrenceReasons()`                            | `GET /api/os/ocorrencia/motivo/list/`                   |
-| `precadastro.listDueDays()`                             | `POST /api/precadastro/vencimento/list`                 |
-| `precadastro.listSellers()`                             | `POST /api/precadastro/vendedor/list`                   |
-| `crm.createIndividualCustomer(params)`                  | `POST /api/crm/cliente/F`                               |
-| `crm.createCompanyCustomer(params)`                     | `POST /api/crm/cliente/J`                               |
-| `crm.createContract(clienteId, params)`                 | `POST /api/crm/cliente/{cliente_id}/contratos/`         |
-| `crm.updateCustomerStatus(clienteId, params)`           | `POST /api/crm/cliente/{cliente_id}/status/`            |
-| `suporte.addCustomerDocument(clienteId, file, params?)` | `PUT /api/suporte/cliente/{cliente_id}/documento/add/`  |
-| `suporte.listCustomerDocuments(clienteId)`              | `GET /api/suporte/cliente/{cliente_id}/documento/list/` |
-
-Every route must be allowed on the consumer's token in SGP (System > Tools > Admin Panel >
-Tokens). A route outside the whitelist returns `ROUTE_NOT_ALLOWED`. Paging is the API's own:
-`offset` and `limit`; the SDK never pages for you.
-
-`ura.checkCoverage({ gateway, raio, coordenada })` checks installation viability: the answer is keyed
-by the gateway's name (data-defined, e.g. `SGPMaps`) and holds the CTOs within `raio` meters or the
-message `"Localização inviável"`. The coordinate (`"lat,lng"`) comes from the consumer; the SDK does
-not geocode. `lat`, `lng` and `distancia` are always numbers (Geogrid sends them as numeric strings
-and the SDK converts them). A malformed gateway answer, such as a CTO with a non-numeric `lat`, is
-`SCHEMA_MISMATCH`.
-
-### Experimental annotation listing
+O SDK nunca lê o ambiente: as credenciais vêm de você. Exemplos completos e executados no CI, contra
+um `fetch` falso, estão em `examples/` do repositório: `quickstart.ts`,
+`write-with-effect.ts`,
+`sensitive-logging.ts` e `request-raw.ts` (fora do pacote npm).
+Para rodar um deles: `SGP_BASE_URL=... SGP_TOKEN=... SGP_APP=... bun examples/quickstart.ts`.
 
-```ts
-const notes = await sgp.ura.listAnnotations({ cliente_id: 10, contrato_id: 100 });
-```
+Cada rota precisa estar liberada no token do SGP, e a barra final conta (as rotas da
+[referência](#referência-de-operações) estão exatamente como o SDK as chama). Rota fora da lista do
+token volta como `FORBIDDEN` com `reason: "TOKEN_ROUTE_NOT_ALLOWED"`.
 
-`ura.listAnnotations` requires at least one of `cliente_id` / `contrato_id`, each a positive safe-integer
-number. Missing filters, nulls, numeric strings and invalid numbers return `VALIDATION` with status 0
-without fetching. Customer-only includes notes with a null contract; contract-only selects that
-contract; both filters mean **AND**, never OR or fallback. No match is a successful empty array.
-
-SGP currently ignores these upstream filters (vendor defect reported, not claimed fixed). The SDK
-still sends canonical filters in one authenticated GET and selects raw identities **before** parsing
-selected notes. A definite mismatch excludes a row even if unrelated content is malformed. If a
-needed identity is missing or malformed and no definite mismatch excludes it, the call fails with
-`SCHEMA_MISMATCH`, not partial data. Source identity strings are not coerced. Selected core fields
-are strict; optional-field drift produces ordinary, selected-only schema warnings. Source order and
-duplicates are preserved; unknown fields are stripped.
-
-Returns matching notes present in one SGP response; source completeness is not guaranteed while this method is experimental.
-No documented pagination contract proves completeness; there is no automatic paging, retry, polling,
-cache, completeness flag or operational warning. The method, snake_case params and array-shaped
-`SgpResult<ListAnnotationsResponse>` remain usable after the vendor fix; local selection and
-validation remain as defense. Removing the experimental label requires evidence of corrected behavior.
-
-The nine declared fields are required numeric `id` / `cliente`, required number-or-null
-`clientecontrato`, required string `anotacao`, optional/nullable numeric `usuario` / `tipo` /
-`alerta_modo`, and optional/nullable string `data_cadastro` / `data_alteracao`. Text and dates are
-preserved verbatim, without HTML rendering, trimming or date parsing. `annotationPersonalKeys`
-classifies note text and staff identity (`anotacao`, `usuario`); `annotationSecretKeys` is empty.
-Use `omitSensitive(note, annotationPersonalKeys)` before logging or forwarding: free text may contain
-user-entered sensitive content even though no credential field is declared.
-
-**Trusted server only:** the multi-customer upstream body enters SDK memory, but the SDK never
-returns, logs or caches the bulk array. Injected fetch, tracing and other instrumentation see the
-body **before** SDK selection and MUST NOT capture it. Local selection is not an authorization
-boundary: the application must authorize requested IDs and keep credentials and execution trusted.
-SDK-generated diagnostics contain paths/types, not source values. Existing upstream error details
-are unchanged and may echo request values; treat them as sensitive too. This special filtered read
-is deliberately excluded from the generic filterless probe registry.
-
-## Result and error contract
-
-Every method returns `SgpResult<T>`:
+Nas rotas `GET`, `token` e `app` vão na query string; nas demais, no corpo. Uma camada de `fetch`,
+proxy ou tracing que você injete enxerga isso.
+
+## O modelo de resultado
+
+Toda operação devolve `SgpResult<T>`:
 
 ```ts
 type SgpResult<T> =
-  | { success: true; data: T; warnings?: SchemaWarning[] }
-  | { success: false; error: SgpError };
+  | {
+      ok: true;
+      data: T;
+      response: CapturedResponse;
+      attempts: number;
+      warnings?: SchemaWarning[];
+      diagnostics?: Diagnostic[];
+    }
+  | {
+      ok: false;
+      error: SgpError;
+      response: CapturedResponse | null;
+      attempts: number;
+      diagnostics?: Diagnostic[];
+    };
 
 interface SgpError {
-  status: number; // HTTP status, 0 when no response arrived
-  code: SgpErrorCode;
-  message: string; // written by the SDK, in English
-  detail?: string; // SGP's own error text (`detail`, `msg`, `errors` or `error`), copied verbatim
-  endpoint: string; // path only, never the query string
+  code: SgpErrorCode; // estável: ramifique por ele, nunca por `message`
+  message: string; // escrita pelo SDK, em inglês
+  operation: string; // ex.: "customers.list"
+  reason?: string; // código específico da operação, só com evidência
+  effect?: "none" | "unknown"; // só em escritas
+  sgp?: { detail?: unknown; msg?: unknown; error?: unknown; errors?: unknown }; // campos de erro do SGP, como vieram
+  issues?: readonly string[]; // em INVALID_RESPONSE: caminhos que quebraram o contrato, nunca valores
 }
+```
 
-interface SchemaWarning {
-  path: string; // e.g. "contratos[0].cobIsento"
-  expected: string; // type names only, never values
-  received: string;
-}
+### Códigos
+
+| Código              | Quando                                                                                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `INVALID_INPUT`     | Entrada local inválida (campos, chaves desconhecidas, parâmetros de caminho, opções da chamada). Nada é enviado: `attempts: 0`, `response: null`                         |
+| `UNAUTHORIZED`      | HTTP 401, ou 403 cujo `detail` diz que as credenciais estão incorretas                                                                                                   |
+| `FORBIDDEN`         | Demais 403. Com `reason: "TOKEN_ROUTE_NOT_ALLOWED"` quando o `detail` diz que as credenciais "não foram fornecidas" (rota fora da lista do token, ou barra final errada) |
+| `RATE_LIMITED`      | HTTP 429 (nunca observado na instância)                                                                                                                                  |
+| `ROUTE_NOT_ALLOWED` | Restrição local do SDK: hoje só `request()` na rota de anotações (use `experimental.annotations.list`). Nada é enviado; nunca mapeia o 405 do HTTP                       |
+| `NOT_FOUND`         | HTTP 404 (rota ou recurso; o significado específico, só via `reason`)                                                                                                    |
+| `REJECTED`          | Demais 4xx (400, 402, 405, 409, 422...), inclusive validação de campo do SGP, e recusas conhecidas que o SGP devolve com HTTP 200                                        |
+| `UPSTREAM`          | HTTP 5xx                                                                                                                                                                 |
+| `NETWORK`           | Falha de transporte (DNS, conexão, TLS, corpo interrompido)                                                                                                              |
+| `TIMEOUT`           | O prazo do SDK expirou (`timeoutMs`)                                                                                                                                     |
+| `ABORTED`           | O seu `abortSignal` cancelou                                                                                                                                             |
+| `INVALID_RESPONSE`  | 2xx fora do contrato do método, ou status que o método não aceita (3xx: redirecionamentos nunca são seguidos)                                                            |
+
+O status HTTP recebido sempre decide o código; um corpo ilegível não apaga um status já recebido
+(vira `response.body.kind === "unavailable"`).
+
+### `reason`
+
+Código específico de uma operação, **só** onde há evidência por operação; nunca um mapa global de
+status. Os existentes:
+
+| `reason`                      | Operação                                   | Situação                               |
+| ----------------------------- | ------------------------------------------ | -------------------------------------- |
+| `TOKEN_ROUTE_NOT_ALLOWED`     | qualquer (com `FORBIDDEN`)                 | 403 "credenciais não foram fornecidas" |
+| `DOCUMENT_ALREADY_REGISTERED` | `preRegistrations.create`                  | 402, CPF já cadastrado                 |
+| `DOCUMENT_ALREADY_REGISTERED` | `crm.customers.create`                     | 400 `errors.cpfcnpj`, CPF já no CRM    |
+| `DOCUMENT_INVALID`            | `crm.customers.create`                     | 400 `errors.cpfcnpj` "CPF inválido."   |
+| `DOCUMENT_INVALID`            | `preRegistrations.create`                  | 400 `message` "CPF inválido"           |
+| `LOGIN_ALREADY_REGISTERED`    | `preRegistrations.create`                  | 400 `message` "Login ... já existe"    |
+| `INVALID_SCHEDULE`            | `occurrences.create`                       | 200 `status: 0`, agendamento inválido  |
+| `STATUS_NOT_CHANGED`          | `contracts.updateStatus`                   | 400 "Status de Contrato não alterado." |
+| `CUSTOMER_NOT_IN_CRM`         | `crm.contracts.create`, `.createByCpfCnpj` | 400 "Não encontrado cliente CRM ..."   |
+| `CONTRACT_NOT_ACTIVE`         | `services.addTv`                           | 400, contrato não ativo                |
+| `PLAN_NOT_GENERIC`            | `services.addGeneric`                      | 400, plano não é do tipo genérico      |
+
+Sem `reason`, a falha continua útil: `code`, `effect`, `sgp` e `response.body` dizem tudo o que o
+SGP disse.
+
+### `effect`: o que se sabe sobre uma escrita
+
+Só escritas têm `error.effect`; leituras não têm. O código sozinho não determina o efeito (e "leitura"
+é propriedade da operação conhecida, nunca do verbo HTTP).
+
+- **`"none"`**: o SDK consegue afirmar que a mudança pedida **não** foi aplicada. Acontece em recusa
+  local (`INVALID_INPUT`), cancelamento antes do envio, recusa conhecida da operação (tabela de
+  `reason` acima) e 4xx do SGP com formato de erro de campo ou de negócio (`errors` como objeto,
+  `error` ou `detail` como texto). Corrigir a entrada e chamar de novo é seguro.
+- **`"unknown"`**: o SGP pode ter aplicado. Vale para timeout, falha de rede, cancelamento depois do
+  envio, 5xx, 3xx, 2xx fora do contrato, 4xx com corpo ilegível ou de formato não reconhecido, a
+  recusa com HTTP 200 de `occurrences.create` (`status: 0`, salvo a do formato do agendamento, de
+  `reason` `INVALID_SCHEDULE`, que é `"none"`) e o "invólucro genérico" do SGP
+  (`errors` como **array**, "Ocorreu um erro: ..."), salvo quando a operação o declara como
+  recusa conhecida.
+
+Uma observação de "nada foi aplicado" é registrada como observação com seu método de verificação
+(releitura), não como garantia.
+
+**Diante de `"unknown"`, não reenvie às cegas.** Releia o estado e só então decida:
+
+| Escrita que ficou em `unknown`                                                                                | Leitura que verifica                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crm.customers.create`                                                                                        | `customers.search` ou `customers.list` pelo documento                                                                                                 |
+| `crm.contracts.create`, `crm.contracts.createByCpfCnpj`                                                       | `crm.contracts.list` (por documento)                                                                                                                  |
+| `crm.customers.updateStatus`                                                                                  | ler o cliente antes de reenviar                                                                                                                       |
+| `contracts.updateStatus`, `contracts.update`                                                                  | `contracts.list({ contrato })`                                                                                                                        |
+| `preRegistrations.create`                                                                                     | `customers.list({ cpfcnpj })` (só quando a resposta de sucesso não traz `new_cliente_id`)                                                             |
+| `contracts.checkConnection`                                                                                   | `occurrences.list({ contrato })` (uma ocorrência pode ter sido aberta em manutenção)                                                                  |
+| `occurrences.create`                                                                                          | `occurrences.list({ contrato })` (traz a OS em `ordens_servicos[]`) ou `workOrders.list({ contrato })`; com `desativa_os: 1` não há OS para consultar |
+| `services.changePlan`, `services.addTv`, `services.removeTv`, `services.addGeneric`, `services.removeGeneric` | `customers.list` (serviços do contrato)                                                                                                               |
+| `documents.add`                                                                                               | `documents.list`                                                                                                                                      |
+
+### `sgp`, `response`, `warnings`, `attempts`
+
+- **`error.sgp`** projeta os campos de erro do SGP (`detail`, `msg`, `error`, `errors`) com os
+  valores como vieram. O corpo inteiro continua em `response.body`.
+- **`response`** é a resposta HTTP bruta: `{ status, headers, body }`, com nomes de header em
+  minúsculas. `body` é um valor discriminado: `{ kind: "json", value }` (o valor pode ser `null`),
+  `{ kind: "text", text }`, `{ kind: "empty" }`, `{ kind: "unavailable", reason }` (o corpo começou e
+  não foi lido até o fim) ou `{ kind: "withheld" }` (veja [leituras com escopo](#leituras-com-escopo)).
+  É o corpo já decodificado, não os bytes. `response` é `null` quando nenhuma resposta HTTP existiu.
+- **`warnings`** aparece quando um campo **secundário** veio com tipo inesperado: o campo sai de
+  `data`, e `{ path, dropped, expected, received }` registra o caminho e os nomes dos tipos (nunca
+  valores). O valor original continua intacto em `response.body`. Os campos **estruturais** de cada
+  operação (ids e o que a navegação precisa) são validados com rigor: se falharem, o resultado é
+  `INVALID_RESPONSE`.
+- **`attempts`** conta as requisições que o SDK iniciou: 0 quando recusou localmente, 1 na primeira.
+- **Fidelidade.** Campos conhecidos são tipados; os desconhecidos chegam em `data` em todos os níveis
+  (raiz, aninhados, arrays), sem serem descartados. Um item que o SDK não consegue interpretar faz a
+  resposta falhar com `INVALID_RESPONSE`; nunca vira `{}` nem `[]`.
+- **Paginação.** `customers.list`, `workOrders.list`, `occurrences.list` e `invoices.list` devolvem **uma página**, com
+  a `paginacao` do SGP como veio (`total` nunca é calculado pelo SDK). Para a próxima página, passe
+  `offset`. Listas sem paginação mantêm o formato do SGP (array ou objeto), sem envelope.
+- **Credenciais nos headers.** Os headers capturados nunca carregam o token nem o app: o valor de
+  qualquer parâmetro `token`/`app` é trocado por `<redacted>`, e o valor exato das credenciais (puro
+  ou codificado) também é trocado quando tem 8 caracteres ou mais. **Corpos não são alterados.**
+
+## Tempo, cancelamento e retry
+
+```ts
+const controller = new AbortController();
+const result = await sgp.customers.list(
+  { limit: 20 },
+  {
+    timeoutMs: 5_000, // prazo desta chamada (padrão do cliente: 20 000 ms)
+    abortSignal: controller.signal,
+    maxRetries: 2, // só leituras
+  },
+);
 ```
 
-| Code                 | When                                                                                                                                                                                 |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `UNAUTHORIZED`       | 401/403 with `detail` (or `msg`) `"Credenciais de autenticação incorretas."` (wrong token or app)                                                                                    |
-| `ROUTE_NOT_ALLOWED`  | 401/403 with `detail` (or `msg`) `"As credenciais de autenticação não foram fornecidas."`. The SDK always sends credentials, so this means the route is not on the token's whitelist |
-| `NOT_FOUND`          | 404                                                                                                                                                                                  |
-| `METHOD_NOT_ALLOWED` | 405                                                                                                                                                                                  |
-| `VALIDATION`         | any other 4xx: SGP refused the input                                                                                                                                                 |
-| `SCHEMA_MISMATCH`    | 2xx whose body is not JSON, or whose key fields are missing or have the wrong type (`detail` then lists the failing paths)                                                           |
-| `UPSTREAM`           | 5xx                                                                                                                                                                                  |
-| `TIMEOUT`            | the request exceeded `timeoutMs`                                                                                                                                                     |
-| `NETWORK`            | `fetch` failed before a response (DNS, connection, TLS)                                                                                                                              |
-| `UNKNOWN`            | 401/403 with any other `detail` or `msg`, or a status the rows above do not cover                                                                                                    |
-
-SGP answers errors in four formats: `{"detail": "..."}`, `{"msg": "..."}`, `{"errors": ...}` (an
-array of messages or an object of field messages, on CRM routes) and `{"error": "..."}` (e.g. a 404
-`Cadastro não encontrado` on CRM routes). `error.detail` holds, in this order: a string `detail`
-(even empty), a non-empty `msg`, the text of `errors`, a non-empty `error`.
-
-Guarantees:
-
-- The SDK never puts the token, the app, a URL with query string, a raw response body or the
-  original message of a `fetch` exception in anything it returns (`data`, `warnings`, `error`).
-- `error.detail` is SGP's text copied verbatim: it may echo values from your request (for example
-  a contract ID or a CPF in a `msg`). The SDK adds nothing to it, so treat it like the request
-  itself before logging or showing it.
-- 401/403 are classified by that exact `detail` string, not by status (SGP uses either status for
-  the same message). If SGP rewords those messages the code falls to `UNKNOWN`.
-- No retry, no cache, no logging, no automatic paging.
-- Redirects are never followed, so the token and payload are not re-sent to another host: a 3xx
-  answer is an `UNKNOWN` error carrying its status (`outcome: "unknown"` on a write).
-- Unknown keys are dropped at every level (`strip`): everything that reaches you was declared and
-  classified. Required key fields that fail validation are `SCHEMA_MISMATCH`; any other field with
-  an unexpected type becomes `undefined` and is reported in `warnings`.
-
-## Writes
-
-Write methods (`crm.*`, `ura.openTicket` and `suporte.addCustomerDocument`) return
-`SgpWriteResult<T>`: the same as `SgpResult<T>`, but `error` also carries an `outcome` that says
-whether SGP applied the write.
-
-- `"not_applied"`: SGP refused the request (4xx) or the SDK rejected it before sending it. SGP did
-  not apply the write; fix the input and call again.
-- `"unknown"`: no answer (`TIMEOUT`, `NETWORK`), a 5xx, a 3xx (`UNKNOWN`: redirects are never
-  followed), or a 2xx whose body does not confirm the write (`VALIDATION` with the real HTTP
-  status). The write may have happened: check the state in SGP before repeating it.
-- A 4xx whose body has `errors` as an array (e.g. a 400 with `{"errors": ["Ocorreu um erro: ..."]}`)
-  is SGP's generic exception wrapper: it can fail after applying part of the write, so it is
-  `"unknown"`, even when `detail` or `msg` come with it. The `code` stays `VALIDATION` and the
-  `message` reads "SGP reported an error while processing the write; it may have been applied."
-  401/403/404/405/422 stay `"not_applied"` whatever the body, and so does a 4xx whose `errors` is an
-  object of field messages or that carries only `detail` or `msg`.
-
-After `outcome: "unknown"`, read the state back before repeating the write:
-
-| Write                                                       | Read that verifies it                                                                                                        |
-| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `crm.createIndividualCustomer`, `crm.createCompanyCustomer` | `ura.listClients({ cpfcnpj })`                                                                                               |
-| `crm.createContract`                                        | `ura.lookupCustomer` or `ura.listContracts`                                                                                  |
-| `ura.openTicket`                                            | `ura.listServiceOrders({ contrato })`; a ticket with `desativa_os: 1` opens no service order, so there is nothing to look up |
-| `suporte.addCustomerDocument`                               | `suporte.listCustomerDocuments`                                                                                              |
-| `crm.updateCustomerStatus`                                  | run it again; for status 6 on an existing CRM customer, a 404 `NOT_FOUND` means it was applied (it leaves the CRM)           |
-
-A write only succeeds on a 2xx whose body carries the key fields (for example `cliente_id`). The one
-exception is `suporte.addCustomerDocument`: SGP answers an empty 2xx, which succeeds with
-`data: null`. Success there does not prove the file was stored; verify it with
-`suporte.listCustomerDocuments`. The SDK never retries a write.
-
-Sales flow: create the customer (`crm.createIndividualCustomer` or `crm.createCompanyCustomer`),
-create the contract on it (`crm.createContract(clienteId, params)`), then call
-`crm.updateCustomerStatus(clienteId, { status_id: crmStatus.contratoRealizadoNoSgp })` (status 6).
-Without that last step SGP's screen keeps the customer as a CRM customer and blocks contract status
-changes.
-
-`crm.createContract` sends the installation address nested (`endereco_instalacao`) and also as the
-loose fields (`logradouro`, `numero`, ...), and the billing address only nested
-(`endereco_cobranca`). The loose fields carry the installation address; a billing address that
-differs from the installation one has not been verified live, so check it on SGP before sending
-divergent addresses.
-
-Scheduling an installation goes through `ura.openTicket` with `data_hora_agendamento`
-(`"AAAA-MM-DD HH:MM"`); `os_instalacao` in `crm.createContract` opens the order without a date.
-
-The token whitelist accepts regular expressions and the trailing slash counts: release each path
-exactly as in the table above, so `/api/crm/cliente/F` has no final `/` and
-`/api/crm/cliente/{cliente_id}/status/` has one (the `{cliente_id}` routes need a pattern that
-matches any ID).
-
-## Sensitive fields
-
-SGP responses carry credentials and personal data. The SDK transcribes them (the consumer decides
-what to show) and marks them: each endpoint exports `as const` tuples with the keys of one response
-item.
-
-- `secret`: Central password, PPPoE login and password, Wi-Fi passwords and SSIDs, MACs, links with
-  an embedded token.
-- `personal`: CPF/CNPJ, phone, e-mail, address, birth date, customer name, free text typed by
-  operators.
-
-Tuple names follow the item: `clientSecretKeys` / `clientPersonalKeys`,
-`customerContractSecretKeys` / `customerContractPersonalKeys`, and so on (see the package exports).
-`omitSensitive(item, keys)` returns a shallow copy without those keys and removes them from the
-type, so a leak becomes a compile error:
+- **Um único orçamento de tempo por chamada lógica**: tentativas, esperas e leitura do corpo. Nunca
+  reinicia por tentativa. `timeoutMs` por chamada substitui o padrão do cliente (é padrão, não teto).
+  Deve ser um número positivo, finito, até `MAX_TIMEOUT_MS`.
+- **`TIMEOUT`** é o prazo do SDK; **`ABORTED`** é o seu `abortSignal`. Se o sinal já estiver
+  cancelado quando você chama, nada é enviado (`effect: "none"` numa escrita); cancelado depois do
+  envio, `effect: "unknown"`.
+- **Retry é opt-in** (`maxRetries`, padrão 0 = nenhuma nova tentativa), vale **só para leituras**
+  e só para falhas transitórias: `RATE_LIMITED`, `NETWORK` e `UPSTREAM` com HTTP 502, 503 ou 504.
+  Há espera exponencial com jitter (base de 500 ms, teto de 10 s) e `Retry-After` (segundos ou data
+  HTTP) é respeitado como piso, nunca encurtado; se a espera não cabe no orçamento, a chamada
+  termina com a última falha. `TIMEOUT`, `ABORTED`, `INVALID_*`, `UNAUTHORIZED`, `FORBIDDEN`,
+  `NOT_FOUND` e `REJECTED` nunca são repetidos.
+- **Escritas nunca são repetidas pelo SDK**, e `request()` também não, qualquer que seja
+  `maxRetries`. Conferir o `attempts` mostra quantas requisições partiram.
+
+## Hooks
+
+```ts
+const sgp = createSgpClient({
+  baseUrl,
+  credentials,
+  hooks: {
+    onRequest: (m) => log.debug({ op: m.operation, attempt: m.attempt }),
+    onResponse: (m) => log.info({ op: m.operation, status: m.status, ms: m.durationMs }),
+    onError: (m) => log.warn({ op: m.operation, code: m.code }),
+  },
+});
+```
+
+Opcionais, **síncronos** e só para observabilidade. Recebem metadados: `callId` (liga as tentativas de
+uma chamada), `attempt` (1, 2, ...), `operation`, `method`, `pathTemplate` (omitido quando
+desconhecido, como em `request()`) e, conforme o hook, `status`, `code` e `durationMs`. Nunca
+recebem credenciais, URLs nem corpos. `onResponse` roda por tentativa quando os headers chegam;
+`onError`, por tentativa que falhou.
+
+Um hook que lança (ou devolve uma Promise, que quebra o contrato síncrono) **nunca altera o
+resultado**: uma escrita confirmada continua confirmada. O fato aparece em `diagnostics`
+(`{ hook, occurrence }`), sem o valor lançado.
+
+## Dados sensíveis
+
+Fidelidade significa que os dados do SGP chegam inteiros, e o SGP mistura credenciais (logins e senhas
+de Central e PPPoE, Wi-Fi, MAC, IP) e dados pessoais de clientes nas respostas. **A sua aplicação
+projeta o que sai do processo.**
+
+- **`getSensitivity("customers.search")`** devolve, por operação, as chaves secretas e pessoais da
+  entrada (`input`) e da resposta (`output`). Serve para saber o que remover. Uma chave que não está
+  listada **não é segura**: o SGP acrescenta campos sem aviso.
+- **`pick(origem, allowlist)`** copia só os caminhos nomeados (`"clientes[].contratos[].id"`;
+  `"[].id"` para array na raiz). Chave não nomeada nunca sai. Use para tudo o que vai a logs,
+  ferramentas, MCP ou agentes.
+- **`toSafeLog(result)`** devolve a versão para log de um resultado: `ok`, `attempts`, `diagnostics`,
+  `warnings` (caminhos e nomes de tipo), status HTTP e, do erro, `code`, `message`, `operation`,
+  `reason`, `effect`, `issues` e os **nomes** dos campos do SGP que vieram. Sem `data`, sem `response.body`, sem headers, sem o texto de `error.sgp`
+  (que costuma repetir o que você enviou).
+
+```ts
+logger.info(toSafeLog(result)); // nunca `logger.info(result)`
+const forTheAgent = pick(result.data, ["contratos[].contratoId", "contratos[].clienteId"]);
+```
+
+**Nunca registre o resultado cru.** `console.log(result)`, `structuredClone(result)`, um logger que
+percorre o objeto ou uma cópia feita antes de `toSafeLog` enxergam tudo. E os corpos em `response.body`
+**não são redigidos**: podem repetir credenciais ou dados pessoais que o SGP devolveu, e o texto de
+erro do SGP pode ecoar o que você enviou. Os headers são redigidos; os corpos, não.
+
+Veja `examples/sensitive-logging.ts` no repositório.
+
+## Leituras com escopo
+
+Princípio: leitor tolerante na interpretação, **fronteira estrita** no isolamento. A tolerância à
+evolução do contrato do SGP nunca alarga o que sai de uma operação.
+
+`experimental.annotations.list` (anotações de um cliente e/ou contrato) é o caso: o SGP ignora os
+filtros e responde com anotações de **outros** clientes. O SDK seleciona localmente, sobre a única
+resposta recebida:
+
+- `response.body` é `{ kind: "withheld" }` em qualquer status, `error.sgp` guarda só textos, e nenhum
+  hook recebe o corpo. Cada anotação selecionada traz `raw`, uma cópia profunda do registro como o SGP
+  mandou.
+- Uma anotação cuja identidade (cliente ou contrato) não pode ser decidida, ou que embute identidade
+  de outro cliente em qualquer profundidade, faz a chamada inteira falhar com `INVALID_RESPONSE`
+  (`error.issues` aponta os caminhos, sem valores). Falha fechada, nunca pulo silencioso.
+- `request()` recusa essa rota (`ROUTE_NOT_ALLOWED`), para a fronteira não ser contornada.
+- Não é uma fronteira de autorização: autorize os ids que você passa e rode isso só em processo de
+  servidor confiável. Uma camada de `fetch` ou tracing que você injete enxerga o corpo inteiro **antes**
+  da seleção e não deve capturá-lo.
+- É **experimental** e pode mudar de forma incompatível em uma versão menor. A completude não é
+  garantida: o SDK faz uma requisição, nunca pagina e nunca trunca; a rota não documenta paginação.
+
+## `request()`: chamada bruta
+
+Para uma rota que nenhum método cobre ainda, com a mesma autenticação, prazo, cancelamento e hooks.
+**Ferramenta de desenvolvedor: nunca a exponha como ferramenta de agente nem monte `path` ou `body`
+a partir de entrada não confiável.**
 
 ```ts
-const safe = omitSensitive(client, clientPersonalKeys);
-safe.nome; // type error: `nome` was omitted
+const raw = await sgp.request({ method: "POST", path: "/api/ura/clientes/", body: { limit: 1 } });
 ```
 
-The SDK only marks and offers the helper; deciding when to apply it is the consumer's job. Strip
-before logging, caching or forwarding an item to a model.
-
-## Known limitations
-
-- **Placeholder arrays.** These fields are declared as arrays of empty objects
-  (`z.array(z.object({}))`) because no sample response had content for them. Every element arrives
-  as `{}`, with no warning, and what SGP sends inside is dropped:
-  - `listClients`: `clientes[].contratos` and `clientes[].titulos` (use `lookupCustomer` and the
-    contract methods for those details);
-  - `lookupCustomer`: `contratos[].telefones_cargos`, `contratos[].outros` and
-    `contratos[].anotacoes`;
-  - `listServiceOrders`: `ordens_servicos[].tecnicos_auxiliares` and
-    `ordens_servicos[].classificacoes`;
-  - `listPlans`: `planos[].combo`;
-  - `os.listOccurrenceTypes` and `os.listOccurrenceReasons`: `classificacoes` and `setores` of
-    each item;
-  - `listInvoices`: `acordados` and `cobrados` of `titulos[].acordoPagamento`.
-- **Guessed types.** SGP only sent `null` for four `lookupCustomer` fields, so their types are
-  inferred: `contratos[].contrato_unificado_principal` (number),
-  `contratos[].contrato_unificado_filhos` (array of numbers), `contratos[].endereco_pontoreferencia`
-  (string) and `contratos[].tags[].categoria_id` (number). A wrong guess does not fail the call: the
-  field comes out as `undefined` and is reported in `warnings`.
-- **A bad element drops the whole array.** When one element of an array field has the wrong type,
-  the whole field becomes `undefined`, and the warning names only the failing element. For example,
-  a non-string entry in `clientes[].contatos.telefones` drops the whole `telefones` array and the
-  warning path is `clientes[0].contatos.telefones[1]`.
-- `listContracts` does not transcribe the address fields returned by `exibir_endereco`.
-
-## Pending
-
-What is left:
-
-- **E-signature of the adhesion term.** Not available in the SGP API.
-- **Boleto delivery methods and invoice (nota fiscal) fields** of the contract. Not available in the
-  SGP API, so `crm.createContract` leaves them empty.
+- Só caminho relativo sob `/api/` da instância configurada, já na forma final (sem query, `//`,
+  `.`/`..`, `%`). Qualquer outro: `INVALID_INPUT`, `effect: "none"`, `attempts: 0`, nada enviado.
+  Parâmetros de um `GET` vão em `body` (só primitivos). `encoding`: `json` (padrão) ou `form`.
+- Classifica só por HTTP, com o mesmo mapa de status dos métodos. **`ok: true` significa "o SGP
+  aceitou em nível HTTP" (2xx), não sucesso de negócio**: o SGP responde algumas recusas com 200,
+  então leia `data` (o corpo como veio, tipado `unknown`).
+- Nunca segue redirecionamentos (3xx é `INVALID_RESPONSE`) e nunca repete.
+- Depois do envio, toda falha tem `effect: "unknown"`, inclusive 4xx; o verbo nunca é tomado como
+  prova de que a chamada só lê.
+- Não declara chaves sensíveis: trate `data` e `response` como sensíveis.
+
+Veja `examples/request-raw.ts` no repositório.
+
+## IDs com marca e os dois catálogos de planos
+
+Alguns ids têm tipo "com marca" (apenas em tempo de compilação; em runtime são números):
+
+| Tipo                    | De onde vem                                                                                                 | Para onde vai                                                                                                                                               |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CustomerId`            | `customers.list` (`clientes[].id`), `customers.search` (`clienteId`), `crm.customers.create` (`cliente_id`) | `cliente_id` de `crm.*`, `documents.*`, `customers.list`, `invoices.list`                                                                                   |
+| `PlanId`                | `plans.list` (`planos[].id`)                                                                                | `plano` de `contracts.list`, `plano_id` de `services.changePlan` e de `crm.contracts.create`, `planobase_id` de `services.addTv` e de `services.addGeneric` |
+| `PreRegistrationPlanId` | `preRegistrations.listPlans` (`id`)                                                                         | `plano_id` de `preRegistrations.create`                                                                                                                     |
+
+Um cliente CRM tem o mesmo `CustomerId` do cliente. **O id de um contrato não é um `CustomerId`**, e
+o compilador recusa um no lugar do outro e um número solto onde um id é esperado. Para marcar um
+número em que você confia: `as CustomerId`.
+
+**Há dois catálogos de planos, com espaços de ids diferentes**: o mesmo plano comercial pode ter outro
+id no catálogo do pré-cadastro, e um id aceito por uma rota pode ser recusado pela outra. Os tipos
+`PlanId` e `PreRegistrationPlanId` são mantidos separados de propósito, nos dois sentidos. A
+conversão entre catálogos não é feita pelo SDK.
+
+## Constantes
+
+Códigos fixos do SGP exportados como constantes; as operações aceitam qualquer número e o SGP
+decide.
+
+| Constante           | Valores                                                                                                            | Evidência                                                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CONTRACT_STATUS`   | `active` 1, `inactive` 2, `canceled` 3, `suspended` 4, `technicalInfeasibility` 5, `new` 6, `activeReducedSpeed` 7 | 1 e 4 confirmados (200 e releitura); 2 enviado e recusado a partir de Ativo; 3, 5 e 7 do painel; 6 documentado pelo fornecedor, nunca observado |
+| `BILLING_METHOD`    | `boleto` 1, `automaticDebit` 2, `booklet` 3, `recurringCharge` 4, `pix` 6                                          | códigos globais fixos; o 5 não é listado (documentado para uma rota, nunca confirmado)                                                          |
+| `ACQUISITION_MODE`  | `owned` 0, `loan` 1                                                                                                | o valor 2, que a documentação do fornecedor lista para o CRM, foi recusado ao vivo                                                              |
+| `CONNECTION_STATUS` | `notChecked` 0, `online` 1, `offline` 2, `maintenance` 9                                                           | 1 e 2 observados; 0 e 9 só na documentação do fornecedor                                                                                        |
+| `SERVICE_TYPE`      | `internet` 1                                                                                                       | só o 1 foi enviado ao SGP                                                                                                                       |
+| `CRM_STATUS`        | `underAnalysis` 1 ... `technicalFeasibilityAnalysis` 10                                                            | só o 6 (`contractMadeInSgp`) foi enviado ao vivo                                                                                                |
+
+O SDK não guarda tabela de transições de status: quem decide o que é permitido é o SGP.
+
+## Referência de operações
+
+Cada método aceita `options?: CallOptions` (`abortSignal`, `timeoutMs`, `maxRetries`) como último
+argumento. Campos de entrada e de resposta usam os nomes do SGP. Uma entrada com chave desconhecida é
+recusada localmente (`INVALID_INPUT`); para campos que ainda não têm tipo, use `request()`. O JSDoc de
+cada método, no tipo `SgpClient` (nos tipos publicados, `dist/client.d.ts`), é o texto de referência; aqui
+ficam só rota, codificação, natureza, recusas conhecidas e evidência.
+
+Legenda. **Natureza:** _leitura_ é repetível com `maxRetries`; _escrita_ nunca é repetida.
+**Codificação:** `query` (GET, parâmetros na URL), `json`, `form` (multipart sem arquivos),
+`form-files` (multipart com arquivo). **Evidência**, resumida (detalhes por cenário em
+[COMPATIBILITY.md](COMPATIBILITY.md)): _observado_ (resposta real capturada), _parcial_ (sucesso
+observado, mas recusas só documentadas ou reconstruídas, ou o inverso), _documentado_ (só a
+documentação do fornecedor), _confirmado pelo fornecedor, não testado_ (o suporte afirmou, nunca exercitado), _reconstruído_ (corpo reconstruído a partir de relatos ou testes, sem
+captura bruta).
+
+### `customers`
+
+| Método                    | Rota e codificação                      | Natureza | Notas                                                                                                                                                                                                                                 | Evidência                        |
+| ------------------------- | --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| `customers.list(input?)`  | `POST /api/ura/clientes/` · json        | leitura  | Uma página; `paginacao` do SGP como veio; filtros `cliente_id`, `cpfcnpj`, `cliente_nome` e `login` (login PPPoE exato; segredo); contratos e serviços aninhados chegam inteiros                                                      | observado                        |
+| `customers.search(input)` | `POST /api/ura/consultacliente/` · json | leitura  | Devolve **candidatos** e nunca escolhe um; ao menos um critério (`cpfcnpj`, `contrato`, `nome`, `login`, `telefone`); texto vazio é recusado; sem resultado é sucesso com `contratos: []`; cada candidato traz credenciais do serviço | observado (corpo mascarado, 1.x) |
+
+### `crm.customers` e `crm.contracts`
+
+| Método                                 | Rota e codificação                                     | Natureza | Notas                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Evidência                                                      |
+| -------------------------------------- | ------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `crm.customers.create(input)`          | `POST /api/crm/cliente/{F\|J}` · json                  | escrita  | `personType` escolhe a rota; `endereco` aninhado, como o SGP o lê. O SDK envia `cpfcnpj` na máscara canônica (CPF `999.999.999-99` em `F`, CNPJ `AA.AAA.AAA/AAAA-99` em `J`, alfanumérico em maiúsculas, com ou sem pontuação na entrada) e recusa localmente (`INVALID_INPUT`, `error.issues` `["cpfcnpj: ..."]`, nada enviado) outro formato ou o tipo errado para a rota; o SDK confere só o formato, mas o SGP confere os dígitos verificadores do CPF (400 `DOCUMENT_INVALID`, `effect: "none"`; os do CNPJ nunca foram testados). O SGP recusa documento já cadastrado, em qualquer status (400 `DOCUMENT_ALREADY_REGISTERED`); **exceção observada: um cliente cujo documento foi gravado sem formatação (ex.: um pré-cadastro só com dígitos, antes do SDK formatar) não foi detectado e cria OUTRO cliente com o mesmo documento**: confira antes (`customers.list({ cpfcnpj })`). 400 de validação de campo: `REJECTED`, `effect: "none"` | observado (`/F`); `/J` confirmado pelo fornecedor, não testado |
+| `crm.customers.updateStatus(input)`    | `POST /api/crm/cliente/{cliente_id}/status/` · json    | escrita  | Códigos em `CRM_STATUS`. Cliente que já saiu do CRM (ou status 6 repetido): 404 `{error:"Cadastro não encontrado"}`, `NOT_FOUND`, `effect: "none"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | observado (status 6; o 404 vem de captura da 1.x)              |
+| `crm.contracts.create(input)`          | `POST /api/crm/cliente/{cliente_id}/contratos/` · json | escrita  | Só para cliente ainda no funil CRM. Recusa `CUSTOMER_NOT_IN_CRM`, `effect: "none"`. `plano_id` é `PlanId`; `modoaquisicao` é `ACQUISITION_MODE`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | parcial                                                        |
+| `crm.contracts.createByCpfCnpj(input)` | `POST /api/crm/cliente/contratos/?cpfcnpj=` · json     | escrita  | Documento na **query** do POST. Mesma recusa `CUSTOMER_NOT_IN_CRM`. Com documento duplicado, qual cliente recebe o contrato não foi verificado. **Nenhum sucesso foi observado nesta rota**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | parcial (sucesso só documentado)                               |
+| `crm.contracts.list(input)`            | `GET /api/crm/cliente/contratos/?cpfcnpj=` · query     | leitura  | Documento que não é cliente CRM: 400, `REJECTED`, sem `reason`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | observado                                                      |
+
+### `preRegistrations`
+
+| Método                           | Rota e codificação                                          | Natureza | Notas                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Evidência                                                                                                                                                    |
+| -------------------------------- | ----------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `preRegistrations.create(input)` | `POST /api/precadastro/{F\|J}` · form                       | escrita  | Endereço em campos soltos no topo da entrada (`logradouro`, `numero`, ...), com os nomes do SGP. O SDK envia `cpfcnpj` na máscara canônica (CPF em `F`, CNPJ em `J`; o SGP grava o que recebe e um CPF só com dígitos escapou da checagem de duplicidade do CRM) e recusa localmente outro formato ou o tipo errado para a rota (`INVALID_INPUT`, `error.issues` `["cpfcnpj: ..."]`); o SGP confere os dígitos verificadores do CPF e recusa o errado (400 `{ message: "CPF inválido", error: "Requisição inválida." }`, `REJECTED`, `DOCUMENT_INVALID`, `effect: "none"`; os do CNPJ nunca foram testados). O SGP recusa um `login` PPPoE já em uso (400 `{ message: "Login <login> já existe", error: "Requisição inválida." }`, `REJECTED`, `LOGIN_ALREADY_REGISTERED`, `effect: "none"`, observado uma vez; `error.sgp` traz só o `error`, e o login que o `message` repete fica em `response.body`, nunca em outro campo do erro): confira antes com `customers.list({ login })`. Com `precadastro_ativar: 1` vira cliente definitivo; contrato só se plano e cobrança forem suficientes. Sucesso traz `message` e, quando o SGP os manda (a captura mais recente mandou; os registros antigos listam só `message`, e como o decoder da 1.x descartava chaves desconhecidas não se sabe se os ids já vinham), `new_cliente_id` (`CustomerId`), `new_contrato_id` e `precadastro_id`, opcionais: sem eles o SDK não inventa nada, releia por `customers.list({ cpfcnpj })`. CPF existente: 402, `REJECTED`, `DOCUMENT_ALREADY_REGISTERED`, `effect: "none"` | parcial (recusa observada; sucesso: `{message}` do fornecedor e, na captura bruta mais recente, também os ids; `/J` confirmado pelo fornecedor, não testado) |
+| `preRegistrations.listPlans()`   | `POST /api/precadastro/plano/list` · form (sem barra final) | leitura  | `PreRegistrationPlanId`: catálogo próprio, não é o de `plans.list`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | observado                                                                                                                                                    |
+| `preRegistrations.listDueDays()` | `POST /api/precadastro/vencimento/list` · json              | leitura  | `id` é o `vencimento_id` de `create`; `dia` é o dia do mês                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | observado (corpo mascarado, 1.x)                                                                                                                             |
+| `preRegistrations.listSellers()` | `POST /api/precadastro/vendedor/list` · json                | leitura  | `id` é o `vendedor_id`; nome, CPF e e-mail são dados pessoais                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | observado (corpo mascarado, 1.x)                                                                                                                             |
+
+### `contracts` e `services`
+
+| Método                             | Rota e codificação                                          | Natureza    | Notas                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Evidência                                                                                                                     |
+| ---------------------------------- | ----------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `contracts.listServices(input?)`   | `POST /api/suporte/contrato/list/` · form (com barra final) | leitura     | Suporte técnico: um array com UMA LINHA POR SERVIÇO (internet e TV) do contrato, com cliente, contrato, endereço e plano repetidos; `servico_online` diz se o serviço está online e a linha online traz a sessão RADIUS (`rad_*`: IP, MAC, NAS, tempo de conexão, contadores). **Exige ao menos um filtro** (`contrato_id` ou `cliente_id`): sem filtro o SGP lista os serviços de todos os clientes, com **senhas de serviço em texto claro**, então o SDK recusa a chamada sem filtro (`INVALID_INPUT`, `attempts: 0`, nada enviado). Ids que o SGP manda como texto e os contadores RADIUS são números, `contrato_status` vem aparado. Login, senha, MACs, IPs (inclusive prefixos IPv6 e NAS) e ids de sessão são segredos; nome, e-mail, contato e endereço são pessoais (`getSensitivity("contracts.listServices")`)                                                                                                    | observado (bruta, contrato sintético offline; a linha online é reconstruída da forma mascarada de um contrato real, só tipos) |
+| `contracts.checkConnection(input)` | `POST /api/ura/verificaacesso/` · form (com barra final)    | **escrita** | Veredito do SGP sobre a conexão (`status` 1 online, 2 offline, 9 manutenção, 0 nada checado: `CONNECTION_STATUS`). `contrato` (exercitado) ou `telefone` (documentado); `status_all: 1` inclui contratos que o filtro padrão deixa de fora (um contrato suspenso devolveu `[]` sem ele). **É DECLARADA ESCRITA**: o fornecedor documenta que, em manutenção ativa, o SGP abre uma ocorrência por padrão, mesmo sem `protocolo_ura` (não testado). Nunca é repetida, e uma falha traz `effect` (em geral `"unknown"`: releia `occurrences.list({ contrato })` antes de reenviar). Chame `maintenance.list()` antes. `protocolo_ura` não é oferecido (use `occurrences.create`). `data` é SEMPRE um array (um item por serviço de internet): o objeto único que o SGP devolve num contrato ativo sem `status_all` é embrulhado; `[]` não é "offline", é sem veredito. `login` é segredo; `razaoSocial` e `cpfCnpj` são pessoais | observado (bruta, contrato sintético suspenso; o objeto único é reconstruído da forma mascarada de um contrato real)          |
+| `contracts.list(input?)`           | `POST /api/ura/listacontrato/` · json                       | leitura     | Sem paginação; array simples; sem filtro pode vir a base inteira do provedor; `plano` é `PlanId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | observado (corpo mascarado, 1.x)                                                                                              |
+| `contracts.updateStatus(input)`    | `POST /api/ura/contrato/status/edit/` · json                | escrita     | Ativar inicia a cobrança. O SGP decide as transições. Recusa `STATUS_NOT_CHANGED` (`effect: "none"`). `motivo` vem de `contracts.listStatusReasons`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | parcial (200 observado; a recusa é reconstruída)                                                                              |
+| `contracts.update(input)`          | `POST /api/ura/contrato/edit/` · json                       | escrita     | Só `forma_cobranca` (`BILLING_METHOD`); devolve `resposta.alterados` como o SGP mandou. Sem recusa conhecida                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | observado                                                                                                                     |
+| `contracts.listStatusReasons()`    | `POST /api/ura/contrato/status/motivos/` · json             | leitura     | Cada provedor tem a sua lista: leia antes de passar `motivo`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | observado                                                                                                                     |
+| `services.changePlan(input)`       | `POST /api/suporte/service/update/{servico_id}/` · form     | escrita     | `action` fixa `change_plano`; `servico_tipo` obrigatório (só `1` exercitado); evento de cobrança. Sucesso traz só `msg`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | observado                                                                                                                     |
+| `services.addTv(input)`            | `POST /api/servico/tv` · form                               | escrita     | HTTP 201 com `servico_id`; só contratos ativos: recusa `CONTRACT_NOT_ACTIVE` (`effect: "none"`); `planobase_id` é `PlanId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | parcial (201 observado; a recusa é reconstruída)                                                                              |
+| `services.removeTv(input)`         | `DELETE /api/servico/tv/{servico_id}` · form                | escrita     | O contrato vai num corpo multipart no DELETE, como o SGP espera. Sem recusa conhecida                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | observado                                                                                                                     |
+| `services.addGeneric(input)`       | `POST /api/servico/generico` · form                         | escrita     | Rota que a TSMX recomenda para serviço extra do tipo genérico. `planobase_id` é `PlanId` de um plano criado como genérico no painel. Plano de outro tipo: recusa `PLAN_NOT_GENERIC` (`effect: "none"`). Sucesso nunca observado (o provedor não tem plano genérico): `data` é o objeto JSON do SGP, sem campo assumido                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | parcial (a recusa foi vista ao vivo, corpo reconstruído; sucesso documentado)                                                 |
+| `services.removeGeneric(input)`    | `DELETE /api/servico/generico/{servico_id}` · form          | escrita     | O contrato vai num corpo multipart, como em `removeTv`. O fornecedor documenta que a rota não remove o único serviço do contrato; nenhum corpo dessa recusa foi capturado, então não há `reason`. Sucesso nunca observado: `data` é o objeto JSON do SGP                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | documentado, nunca observado                                                                                                  |
+
+### `plans`, `invoices`, `workOrders`, `occurrences`
+
+| Método                           | Rota e codificação                                   | Natureza | Notas                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Evidência                                                                                            |
+| -------------------------------- | ---------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `plans.list()`                   | `GET /api/ura/consultaplano/` · query                | leitura  | Mantém o formato do SGP (`planos` e totais); `planos[].id` é `PlanId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | observado                                                                                            |
+| `invoices.list(input?)`          | `POST /api/ura/titulos/` · json                      | leitura  | Uma página; `paginacao.total` ausente é `INVALID_RESPONSE`; máximo de 250 por página é do fornecedor. Valores (`valor`, `valorDesconto`, `valorCorrigido`, `valorPago`, `valorPagoParcial`) são `number` em reais ou `null` (o SGP manda `""` quando não há valor); texto formatado como `"1.234,56"` não é adivinhado e sai de `data` com `warning`. Traz nome, documento, links de pagamento e PIX                                                                                                                                                                                                                                                                                                                                                                          | parcial (página vazia observada; página populada reconstruída)                                       |
+| `workOrders.list(input?)`        | `POST /api/ura/ordemservico/list/` · json            | leitura  | Uma página; `ocorrencia` é texto e continua texto                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | observado                                                                                            |
+| `workOrders.get(input)`          | `POST /api/os/list/id/{id}` · form (sem barra final) | leitura  | Um objeto plano com 72 campos (OS, cliente, contrato, endereço, plano e serviço); a coleção do fornecedor mostra um array de um elemento e o SGP mandou o objeto. **Traz senhas em texto claro** (`servico_password`, `wan_password`, `wifi_password`, `wifi_password_5`) e login, MAC e IP do serviço: segredos; nome, e-mail, contatos, endereço e texto livre são pessoais. Normalizado por campo: `servico_id`, `contrato_status_id` e `os_setor_id` são números (o SGP manda texto) e `contrato_status` vem aparado; o resto como veio                                                                                                                                                                                                                                   | observado (bruta, ao vivo; as senhas de Wi-Fi e WAN vieram vazias)                                   |
+| `workOrders.listComments(input)` | `GET /api/os/{id}/comentario/list/` · query          | leitura  | Array do SGP sem envelope; vazio = sem comentários. Texto do comentário e autor são pessoais                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | parcial (bruta: só `[]`; o formato dos itens é só documentado)                                       |
+| `workOrders.listReasons()`       | `GET /api/os/ocorrencia/motivo/list/` · query        | leitura  | `id` e `codigo` são distintos; `occurrences.create` usa o `codigo` em `motivoos`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | observado (corpo mascarado, 1.x)                                                                     |
+| `occurrences.create(input)`      | `POST /api/ura/chamado/` · json                      | escrita  | "Chamado" do SGP. Devolve `id` da **ocorrência** e `protocolo`, nunca o id da OS (leia com `occurrences.list`). `data_hora_agendamento` tem de ser exatamente `AAAA-MM-DD HH:MM`: o SGP recusa segundos (HTTP 200, `status: 0`, `msg` "Data e hora de agendamento inválida, formato esperado: AAAA-MM-DD HH:MM"; `REJECTED`, `INVALID_SCHEDULE`, `effect: "none"`, observado uma vez, com releitura: nada foi criado) e o SDK não confere o formato antes (quem decide é o SGP). Qualquer outra recusa com HTTP 200 e `status: 0`: `REJECTED`, `effect: "unknown"`. Observado: ocorrência sem `motivoos` é aceita e o SGP cria a OS mesmo assim; `status_encerrado: 1` encerra ocorrência e OS; encerrar uma OS de instalação (`motivoos` 10) não altera o status do contrato | parcial (sucesso: corpo mascarado, 1.x; recusa do agendamento: bruta; outras recusas: reconstruídas) |
+| `occurrences.list(input?)`       | `POST /api/ura/ocorrencia/list/` · form              | leitura  | **Exige ao menos um filtro (de preferência `contrato`): sem filtro o SGP lista as ocorrências de todos os clientes (até 1000), com nomes e texto livre, então o SDK recusa a chamada sem filtro (`INVALID_INPUT`, `attempts: 0`, nada enviado); `offset` e `limit` sozinhos não contam.** Uma página; devolve a OS de cada ocorrência em `ordens_servicos[]` (é o caminho do chamado até a OS: `ordens_servicos[].id`). Só `contrato` e `limit` foram enviados; os demais filtros são os da coleção do fornecedor                                                                                                                                                                                                                                                             | observado (bruta, ao vivo: contrato com e sem ocorrência)                                            |
+| `occurrences.listTypes()`        | `GET /api/os/ocorrencia/tipo/list/` · query          | leitura  | `id` e `codigo`; `occurrences.create` usa o `codigo` em `ocorrenciatipo`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | observado (corpo mascarado, 1.x)                                                                     |
+| `occurrences.listMethods()`      | `GET /api/ura/ocorrencia/metodo/list/` · query       | leitura  |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | observado (corpo mascarado, 1.x)                                                                     |
+
+### `documents`, `coverage`, `catalogs`, `experimental`
+
+| Método                                 | Rota e codificação                                                  | Natureza | Notas                                                                                                                                                                                                                                                                                                                                                                                                | Evidência                                                                                       |
+| -------------------------------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `documents.add(input)`                 | `PUT /api/suporte/cliente/{cliente_id}/documento/add/` · form-files | escrita  | Sucesso é 2xx com corpo **vazio** (`data: null`, nada identifica o documento); qualquer outro corpo 2xx é `INVALID_RESPONSE` com `effect: "unknown"`                                                                                                                                                                                                                                                 | reconstruído                                                                                    |
+| `documents.list(input)`                | `GET /api/suporte/cliente/{cliente_id}/documento/list/` · query     | leitura  | `cliente_id` é um `CustomerId` positivo; array vazio = sem documentos                                                                                                                                                                                                                                                                                                                                | observado (corpo mascarado, 1.x)                                                                |
+| `coverage.check(input)`                | `GET /api/ura/viabilidadeinstalacao` · query (sem barra final)      | leitura  | `gateway`, `raio` (metros) e `coordenada` (`"lat,lng"`) obrigatórios; o SDK não geocodifica; `lat`, `lng`, `distancia` e `id` de cada CTO são números (o Geogrid manda texto, convertido)                                                                                                                                                                                                            | observado (corpo mascarado, 1.x; SGPMaps e Geogrid)                                             |
+| `coverage.checkAddress(input)`         | `POST /api/ura/viabilidade/` · form                                 | leitura  | Viabilidade por **endereço**, sem coordenada: `cep`, `cidade`, `logradouro`, `bairro`, `numero_inicial`, `numero_final`; ao menos um (o fornecedor manda usar um dos filtros). Devolve o objeto do SGP como veio: `{ viabilidade: true }` ou `{}`. **Sem a chave `viabilidade` = desconhecido, nunca "sem cobertura"**; a resposta de "sem cobertura" nunca foi observada. O endereço é dado pessoal | observado (bruta, ao vivo: `cep` sozinho e `cidade` sozinha; os demais filtros só documentados) |
+| `coverage.listGateways()`              | `GET /api/ura/listgatewaymapa` · query (sem barra final)            | leitura  | Gateways de mapa do provedor; o `id` de cada um é o `gateway` de `coverage.check`; array vazio = nenhum gateway                                                                                                                                                                                                                                                                                      | observado (corpo, ao vivo; Geogrid e SGPMaps)                                                   |
+| `maintenance.list()`                   | `GET /api/ura/manutencao/list/` · query                             | leitura  | Avisos de manutenção (SGP "manutenção"), **inclusive os inativos**, sem filtro nem paginação: filtre por `ativa` e pelo período (`data_inicial`, `data_final`). Array do SGP, sem envelope; as listas de elementos afetados vieram vazias, então o conteúdo delas é desconhecido                                                                                                                     | observado (bruta, ao vivo: três avisos, todos inativos)                                         |
+| `catalogs.listPops()`                  | `POST /api/ura/pops/` · json                                        | leitura  |                                                                                                                                                                                                                                                                                                                                                                                                      | observado (corpo mascarado, 1.x)                                                                |
+| `catalogs.listNas()`                   | `POST /api/ura/nas/list/` · json                                    | leitura  | `endereco_ip` é segredo                                                                                                                                                                                                                                                                                                                                                                              | observado (corpo mascarado, 1.x)                                                                |
+| `catalogs.listBillingProfiles()`       | `GET /api/ura/portador/` · query                                    | leitura  | "Portadores" do SGP; os ids alimentam o filtro `portador` de `invoices.list`                                                                                                                                                                                                                                                                                                                         | observado (corpo mascarado, 1.x)                                                                |
+| `experimental.annotations.list(input)` | `GET /api/ura/cliente/anotacao/list/` · query                       | leitura  | **Experimental.** Seleção local, corpo retido. Veja [leituras com escopo](#leituras-com-escopo)                                                                                                                                                                                                                                                                                                      | reconstruído (corpo sintético; tipos de campo observados)                                       |
+
+Todas as leituras acima aceitam `maxRetries`. `request(input, options?)` está descrita
+[acima](#request-chamada-bruta).
+
+## Limitações confirmadas pelo fornecedor (TSMX, 06/11)
+
+O que o suporte da TSMX (Erick Silva, 05/11; Natanael Azevedo, 06/11) afirmou que a API do SGP **não**
+faz. São palavras do fornecedor, que o SDK não testa nem contorna; as evidências por cenário estão em
+[COMPATIBILITY.md](COMPATIBILITY.md).
+
+- **Segundo contrato em cliente definitivo:** sem API ("No momento não seria possível adicionar um
+  segundo contrato em cadastros definitivos via API").
+- **Telefonia:** sem API para adicionar o serviço ("No momento não temos end-points para adicionar
+  serviços de telefonia").
+- **Serviços extras:** pela API só TV (`services.addTv`) e genérico (`services.addGeneric`); internet
+  adicional (como locação de roteador) e multimídia, só pelo painel.
+- **"Alterar Titular" e migração de contrato:** sem rota de API (constatação nossa nas rotas
+  sondadas; a TSMX não respondeu essa pergunta de forma explícita).
+- **Documentação oficial:** só a coleção do Postman; não há Swagger/OpenAPI.
+- **CNPJ alfanumérico e tipos `E`/`EJ`:** os filtros `cpfcnpj` de leitura aceitam um CNPJ
+  alfanumérico (constatação nossa, observada ao vivo, só leitura: resposta normal, sem rejeição de formato; nenhum
+  achado foi observado). A criação de PJ com ele não foi testada, e para
+  `/E` e `/EJ` o fornecedor não tem exemplo que funcione. Detalhes em
+  [COMPATIBILITY.md](COMPATIBILITY.md).
+- **Planos:** os IDs de plano do pré-cadastro e do cliente definitivo são diferentes de propósito e
+  nenhuma rota devolve a correspondência; o consumidor casa pela descrição.
+
+## Migração do 1.x
+
+A 2.0 é uma quebra de contrato (resultado, códigos, nomes e comportamento), sem aliases. O mapa de
+cada método do 1.x e as mudanças de comportamento estão em [MIGRATION.md](MIGRATION.md); o histórico
+de mudanças, em [CHANGELOG.md](CHANGELOG.md).
+
+## Desenvolvimento
+
+Veja `CONTRIBUTING.md` no repositório. Os testes usam sempre um `fetch` injetado: nenhum teste
+toca o SGP, e a CI não usa credenciais.