sgp-sdk 1.2.0 → 2.0.0-beta.2

package/MIGRATION.md

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