sgp-sdk 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SYXS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,304 @@
-# Temporary Holding Version
+# sgp-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+- 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.
+
+## Install
+
+```sh
+bun add sgp-sdk
+# or
+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.
+
+## Usage
+
+```ts
+import { clientPersonalKeys, createSgpClient, omitSensitive } 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)
+});
+
+const plans = await sgp.ura.listPlans();
+if (plans.success) {
+  console.log(plans.data.planos.length, plans.warnings ?? []);
+} else {
+  console.error(plans.error.code, plans.error.status, plans.error.endpoint);
+}
+
+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);
+  }
+}
+```
+
+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
+
+```ts
+const notes = await sgp.ura.listAnnotations({ cliente_id: 10, contrato_id: 100 });
+```
+
+`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>`:
+
+```ts
+type SgpResult<T> =
+  | { success: true; data: T; warnings?: SchemaWarning[] }
+  | { success: false; error: SgpError };
+
+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
+}
+
+interface SchemaWarning {
+  path: string; // e.g. "contratos[0].cobIsento"
+  expected: string; // type names only, never values
+  received: string;
+}
+```
+
+| 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:
+
+```ts
+const safe = omitSensitive(client, clientPersonalKeys);
+safe.nome; // type error: `nome` was omitted
+```
+
+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.

package/dist/client.d.ts

@@ -0,0 +1,228 @@
+import { type CreateContractParams, type CreateContractResponse } from "./endpoints/crm/create-contract.js";
+import { type CreateCompanyCustomerParams, type CreateCustomerResponse, type CreateIndividualCustomerParams } from "./endpoints/crm/create-customer.js";
+import { type UpdateCustomerStatusParams, type UpdateCustomerStatusResponse } from "./endpoints/crm/update-customer-status.js";
+import { type ListOccurrenceReasonsResponse } from "./endpoints/os/list-occurrence-reasons.js";
+import { type ListOccurrenceTypesResponse } from "./endpoints/os/list-occurrence-types.js";
+import { type ListDueDaysResponse } from "./endpoints/precadastro/list-due-days.js";
+import { type ListSellersResponse } from "./endpoints/precadastro/list-sellers.js";
+import { type AddCustomerDocumentParams, type AddCustomerDocumentResponse } from "./endpoints/suporte/add-customer-document.js";
+import { type ListCustomerDocumentsResponse } from "./endpoints/suporte/list-customer-documents.js";
+import { type CheckCoverageParams, type CheckCoverageResponse } from "./endpoints/ura/check-coverage.js";
+import { type ListAnnotationsParams, type ListAnnotationsResponse } from "./endpoints/ura/list-annotations.js";
+import { type ListClientsParams, type ListClientsResponse } from "./endpoints/ura/list-clients.js";
+import { type ListContractsParams, type ListContractsResponse } from "./endpoints/ura/list-contracts.js";
+import { type ListInvoicesParams, type ListInvoicesResponse } from "./endpoints/ura/list-invoices.js";
+import { type ListNasResponse } from "./endpoints/ura/list-nas.js";
+import { type ListOccurrenceMethodsResponse } from "./endpoints/ura/list-occurrence-methods.js";
+import { type ListPaymentCarriersResponse } from "./endpoints/ura/list-payment-carriers.js";
+import { type ListPlansResponse } from "./endpoints/ura/list-plans.js";
+import { type ListPopsResponse } from "./endpoints/ura/list-pops.js";
+import { type ListServiceOrdersParams, type ListServiceOrdersResponse } from "./endpoints/ura/list-service-orders.js";
+import { type LookupCustomerParams, type LookupCustomerResponse } from "./endpoints/ura/lookup-customer.js";
+import { type OpenTicketParams, type OpenTicketResponse } from "./endpoints/ura/open-ticket.js";
+import type { SgpResult, SgpWriteResult } from "./result.js";
+import type { SgpClientConfig, SgpFile } from "./transport.js";
+/** Methods that hit the `/api/ura/` routes. All are reads, except `openTicket`: a write that returns an {@link SgpWriteResult}. */
+export interface UraClient {
+    /**
+     * @experimental Lists annotations: `GET /api/ura/cliente/anotacao/list/`, with local identity selection.
+     * Requires positive safe-integer `cliente_id` and/or `contrato_id`; both mean AND.
+     * Returns matching notes present in one SGP response; source completeness is not guaranteed while this method is experimental.
+     * The bulk upstream body enters SDK memory but is never returned, logged or cached by the SDK.
+     * Use only on a trusted server; authorize requested IDs. Injected fetch/tracing must not capture
+     * the upstream body. Omit note text/staff identity with `annotationPersonalKeys` before logging.
+     * The public API and local validation/selection remain when upstream filtering is fixed.
+     */
+    listAnnotations: (params: ListAnnotationsParams) => Promise<SgpResult<ListAnnotationsResponse>>;
+    /**
+     * Lists clients, one page at a time: `POST /api/ura/clientes/`.
+     *
+     * Filter with `cliente_id`, `cpfcnpj` or `cliente_nome`; page with `offset` and `limit`.
+     */
+    listClients: (params?: ListClientsParams) => Promise<SgpResult<ListClientsResponse>>;
+    /**
+     * Looks up a customer and its contracts: `POST /api/ura/consultacliente/`.
+     *
+     * Requires at least one of `cpfcnpj`, `contrato`, `nome`, `login` or `telefone`. Each contract
+     * carries secrets (Central and PPPoE credentials, Wi-Fi, MACs, payoff link) and personal data;
+     * strip them with `omitSensitive` and the exported key tuples before logging or forwarding.
+     */
+    lookupCustomer: (params: LookupCustomerParams) => Promise<SgpResult<LookupCustomerResponse>>;
+    /**
+     * Lists contract summaries: `POST /api/ura/listacontrato/`.
+     *
+     * Filter with `contrato`, `plano`, `tipo` or `status`. Without any filter the response may
+     * carry the whole contract base. Results contain personal data (name, CPF/CNPJ, e-mail, phone,
+     * status reason); strip it with `omitSensitive` and the exported key tuples before logging or
+     * forwarding.
+     */
+    listContracts: (params?: ListContractsParams) => Promise<SgpResult<ListContractsResponse>>;
+    /**
+     * Lists service orders (OS), one page at a time: `POST /api/ura/ordemservico/list/`.
+     *
+     * Filter with `ordem_servico`, `status`, `pop`, `motivo` or `contrato`; page with `offset` and
+     * `limit`. Results contain personal data (customer name, free-text content); strip it with
+     * `omitSensitive` and the exported key tuples before logging or forwarding.
+     */
+    listServiceOrders: (params?: ListServiceOrdersParams) => Promise<SgpResult<ListServiceOrdersResponse>>;
+    /** Lists the plan catalog: `GET /api/ura/consultaplano/`. Takes no parameters. */
+    listPlans: () => Promise<SgpResult<ListPlansResponse>>;
+    /** Lists the occurrence methods: `GET /api/ura/ocorrencia/metodo/list/`. Takes no parameters. */
+    listOccurrenceMethods: () => Promise<SgpResult<ListOccurrenceMethodsResponse>>;
+    /**
+     * Lists invoices (titulos), one page at a time: `POST /api/ura/titulos/`.
+     *
+     * Filter with `contrato`, `cliente_id`, `cpfcnpj`, `titulo_id`, `status`, `portador` or the date
+     * ranges; order with `ordenar` and `ordenar_ordem`; page with `offset` and `limit`. Results
+     * contain personal data (customer name, CPF/CNPJ, statement text) and payment links and PIX
+     * codes that may resolve to the debtor; strip them with `omitSensitive` and the exported key
+     * tuples before logging or forwarding.
+     */
+    listInvoices: (params?: ListInvoicesParams) => Promise<SgpResult<ListInvoicesResponse>>;
+    /** Lists the POPs (points of presence): `POST /api/ura/pops/`. Takes no parameters. */
+    listPops: () => Promise<SgpResult<ListPopsResponse>>;
+    /**
+     * Lists the NAS (network access servers) and the POPs each serves: `POST /api/ura/nas/list/`.
+     * Takes no parameters.
+     *
+     * `endereco_ip` is network infrastructure; strip it with `omitSensitive` and `nasSecretKeys`
+     * before logging or forwarding.
+     */
+    listNas: () => Promise<SgpResult<ListNasResponse>>;
+    /** Lists the payment carriers (portadores): `GET /api/ura/portador/`. Takes no parameters. */
+    listPaymentCarriers: () => Promise<SgpResult<ListPaymentCarriersResponse>>;
+    /**
+     * Checks installation viability around a coordinate: `GET /api/ura/viabilidadeinstalacao`.
+     *
+     * The SDK does not geocode: the consumer supplies `coordenada` (`"lat,lng"`), the map `gateway`
+     * ID (from `/api/ura/listgatewaymapa`) and the `raio` in meters. The answer is keyed by the gateway's name and
+     * holds the CTOs within the radius, or `"Localização inviável"` when there are none.
+     *
+     * A malformed gateway answer (an entry that is neither CTOs nor a message) is `SCHEMA_MISMATCH`.
+     */
+    checkCoverage: (params: CheckCoverageParams) => Promise<SgpResult<CheckCoverageResponse>>;
+    /**
+     * Opens a ticket on a contract: `POST /api/ura/chamado/`. Opens an occurrence and, unless
+     * `desativa_os: 1`, a service order; `data_hora_agendamento` (`"AAAA-MM-DD HH:MM"`) schedules it.
+     *
+     * Requires `contrato`. To schedule an installation, send `motivoos` with your instance's
+     * installation reason code (see `os.listOccurrenceReasons`) and `data_hora_agendamento`. Success is `status` 1 with a `protocolo`; the response carries the
+     * customer's name and CPF/CNPJ: strip them with `omitSensitive` and `ticketOpenedPersonalKeys`
+     * before logging or forwarding. `contato_nome` and `contato_telefone` in the params are personal
+     * data.
+     *
+     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     */
+    openTicket: (params: OpenTicketParams) => Promise<SgpWriteResult<OpenTicketResponse>>;
+}
+/** Methods that hit the `/api/os/` routes. */
+export interface OsClient {
+    /** Lists the occurrence types of service orders (OS): `GET /api/os/ocorrencia/tipo/list/`. Takes no parameters. */
+    listOccurrenceTypes: () => Promise<SgpResult<ListOccurrenceTypesResponse>>;
+    /** Lists the occurrence reasons of service orders (OS): `GET /api/os/ocorrencia/motivo/list/`. Takes no parameters. */
+    listOccurrenceReasons: () => Promise<SgpResult<ListOccurrenceReasonsResponse>>;
+}
+/** Methods that hit the `/api/precadastro/` routes. */
+export interface PrecadastroClient {
+    /** Lists the due days offered at pre-registration: `POST /api/precadastro/vencimento/list`. Takes no parameters. */
+    listDueDays: () => Promise<SgpResult<ListDueDaysResponse>>;
+    /**
+     * Lists the sellers (vendedores): `POST /api/precadastro/vendedor/list`. Takes no parameters.
+     *
+     * Used for `vendedor_id` when creating contracts (v1.1). Sellers are employees: name, CPF and
+     * e-mail are personal data; strip them with `omitSensitive` and `sellerPersonalKeys` before
+     * logging or forwarding.
+     */
+    listSellers: () => Promise<SgpResult<ListSellersResponse>>;
+}
+/** Methods that hit the `/api/crm/` routes. Writes: they return an {@link SgpWriteResult}. */
+export interface CrmClient {
+    /**
+     * Creates an individual (PF) customer: `POST /api/crm/cliente/F`.
+     *
+     * Requires `nome`, `cpfcnpj` and `endereco`; the address is sent nested and as loose fields.
+     * The response `message` carries the name and CPF; strip it with `omitSensitive` and
+     * `customerCreatedPersonalKeys` before logging or forwarding.
+     *
+     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     */
+    createIndividualCustomer: (params: CreateIndividualCustomerParams) => Promise<SgpWriteResult<CreateCustomerResponse>>;
+    /**
+     * Creates a company (PJ) customer: `POST /api/crm/cliente/J`.
+     *
+     * Requires `nome`, `cpfcnpj` and `endereco`; the address is sent nested and as loose fields.
+     * The response `message` carries the name and CNPJ; strip it with `omitSensitive` and
+     * `customerCreatedPersonalKeys` before logging or forwarding.
+     *
+     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     */
+    createCompanyCustomer: (params: CreateCompanyCustomerParams) => Promise<SgpWriteResult<CreateCustomerResponse>>;
+    /**
+     * Creates a contract on a CRM customer: `POST /api/crm/cliente/{cliente_id}/contratos/`.
+     *
+     * Requires `pop_id`, `plano_id`, `portador_id`, `forma_cobranca_codigo` (`formaCobrancaCodigo`),
+     * `vencimento_dia` and both addresses: `endereco_instalacao` and `endereco_cobranca`, sent
+     * nested; the installation one also goes as loose fields. SGP requires `login` and `senha`
+     * (PPPoE) for an internet service. The params carry secrets (`login`, `senha`, `central_login`,
+     * `central_senha`): never log them. The response `cliente` is the customer's name; strip it with
+     * `omitSensitive` and `contractCreatedPersonalKeys` before logging or forwarding.
+     *
+     * The loose address fields carry the installation address. A billing address different from the
+     * installation one has not been verified live. `error.detail` is SGP's text and may echo submitted
+     * values (e.g. `senha`): treat it as sensitive before logging.
+     *
+     * `os_instalacao` opens the installation service order without a date; to schedule one, use
+     * `ura.openTicket`. The boleto delivery methods and the invoice (nota fiscal) are not in the
+     * API: they stay empty.
+     *
+     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     */
+    createContract: (clienteId: number, params: CreateContractParams) => Promise<SgpWriteResult<CreateContractResponse>>;
+    /**
+     * Sets the CRM status of a customer: `POST /api/crm/cliente/{cliente_id}/status/`.
+     *
+     * Set `crmStatus.contratoRealizadoNoSgp` after the contract, or SGP's screen keeps the customer
+     * as a CRM customer and blocks contract status changes. The response `message` carries the
+     * customer's name; strip it with `omitSensitive` and `customerStatusPersonalKeys` before
+     * logging or forwarding.
+     *
+     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     */
+    updateCustomerStatus: (clienteId: number, params: UpdateCustomerStatusParams) => Promise<SgpWriteResult<UpdateCustomerStatusResponse>>;
+}
+/** Methods that hit the `/api/suporte/` routes. */
+export interface SuporteClient {
+    /**
+     * Attaches a document to a customer: `PUT /api/suporte/cliente/{cliente_id}/documento/add/`,
+     * sent as multipart with the file in the `file` part.
+     *
+     * SGP answers 200 with an empty body and does not return the document ID: `data` is `null`. To
+     * check the upload, use `listCustomerDocuments`. SGP converts images to `.jpeg`, so the stored
+     * file name may differ from `file.filename`. `descricao` is personal data when it names the
+     * customer.
+     *
+     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     */
+    addCustomerDocument: (clienteId: number, file: SgpFile, params?: AddCustomerDocumentParams) => Promise<SgpWriteResult<AddCustomerDocumentResponse>>;
+    /**
+     * Lists the documents attached to a customer: `GET /api/suporte/cliente/{cliente_id}/documento/list/`.
+     *
+     * Each document carries the file name or link (`arquivo`), its description and the operator:
+     * personal data; strip it with `omitSensitive` and `customerDocumentPersonalKeys` before logging
+     * or forwarding.
+     */
+    listCustomerDocuments: (clienteId: number) => Promise<SgpResult<ListCustomerDocumentsResponse>>;
+}
+/**
+ * SGP client. Reads return an {@link SgpResult}, writes (`crm`, `ura.openTicket`,
+ * `suporte.addCustomerDocument`) an {@link SgpWriteResult}; no method ever throws.
+ */
+export interface SgpClient {
+    ura: UraClient;
+    os: OsClient;
+    precadastro: PrecadastroClient;
+    crm: CrmClient;
+    suporte: SuporteClient;
+}
+/** Creates an SGP client bound to `config`; `token` and `app` are sent on every request. */
+export declare const createSgpClient: (config: SgpClientConfig) => SgpClient;

package/dist/endpoint.d.ts

@@ -0,0 +1,66 @@
+import type { z } from "zod";
+import type { SgpResult, SgpWriteResult } from "./result.js";
+import { type ParamValue, type RequestSpec, type SgpClientConfig, type SgpFile } from "./transport.js";
+/** Static description of one SGP route: how to call it, how to parse it and what is sensitive. */
+export interface EndpointDefinition<S extends z.ZodType> {
+    method: "GET" | "POST";
+    /** Request path starting with `/`; also the `endpoint` of every error. */
+    path: string;
+    schema: S;
+    /** Normalized paths of the required, strict fields (see `parseResponse`). */
+    keyFields: readonly string[];
+    /** Normalized path of the response items that carry sensitive keys, e.g. `clientes[]`. */
+    itemPath: string;
+    /** Keys of an item holding secrets (passwords, MACs, links with embedded token). */
+    secretKeys: readonly string[];
+    /** Keys of an item holding personal data (CPF/CNPJ, phone, e-mail, address, name). */
+    personalKeys: readonly string[];
+}
+/**
+ * Static description of one SGP write route. Like {@link EndpointDefinition}, but `schema` is the
+ * success body: a 2xx only counts as success when it validates (key fields present, right type).
+ */
+export interface WriteEndpointDefinition<S extends z.ZodType> {
+    kind: "write";
+    method: "POST" | "PUT";
+    /** Request path template, e.g. `/api/crm/cliente/{cliente_id}/contratos/`; also the `endpoint` of every error. */
+    path: string;
+    schema: S;
+    /** Normalized paths of the required, strict fields (see `parseResponse`). */
+    keyFields: readonly string[];
+    /** Normalized path of the response items that carry sensitive keys. */
+    itemPath: string;
+    /** Keys of an item holding secrets. */
+    secretKeys: readonly string[];
+    /** Keys of an item holding personal data. */
+    personalKeys: readonly string[];
+}
+/** Inputs of one write call: values for the path placeholders, the request params and any files. */
+export interface WriteCall {
+    pathParams?: Record<string, string | number>;
+    params?: Record<string, ParamValue | undefined>;
+    files?: Record<string, SgpFile>;
+}
+/**
+ * Sends the request described by `def` and parses the response with its schema.
+ *
+ * Never throws: transport and HTTP failures come back as `{ success: false, error }` and a body
+ * that does not match the schema as `SCHEMA_MISMATCH`.
+ */
+export declare const callEndpoint: <S extends z.ZodType>(config: SgpClientConfig, def: EndpointDefinition<S>, params?: RequestSpec["params"], pathParams?: RequestSpec["pathParams"]) => Promise<SgpResult<z.output<S>>>;
+/**
+ * Sends the write described by `def` and tells whether SGP applied it.
+ *
+ * Never throws. Success is a 2xx whose body validates against `def.schema`. A failure carries an
+ * `outcome`:
+ * - `"not_applied"`: SGP answered 4xx and rejected the request, or the SDK rejected it locally before
+ *   sending (invalid path params, `VALIDATION` with status 0);
+ * - `"unknown"`: no response (timeout, network), 5xx, 3xx (redirects are never followed), a 4xx
+ *   whose body `errors` is an array (SGP's generic exception wrapper, except 401/403/404/405/422),
+ *   or a 2xx that is not a valid success (empty or non-JSON body, key field missing). The 2xx case
+ *   is a `VALIDATION` error with the real HTTP status and, for a JSON body, SGP's own text
+ *   (`detail`/`msg`/`errors`/`error`) or else the failing paths.
+ *
+ * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+ */
+export declare const callWriteEndpoint: <S extends z.ZodType>(config: SgpClientConfig, def: WriteEndpointDefinition<S>, call?: WriteCall) => Promise<SgpWriteResult<z.output<S>>>;

package/dist/endpoints/crm/address.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Address as SGP takes it. Pass it once: the SDK serializes it both nested (`endereco`) and as
+ * loose fields (`logradouro`, `numero`, ...), which are the two formats the CRM routes read.
+ */
+export interface SgpAddress {
+    logradouro: string;
+    numero?: string | number;
+    complemento?: string;
+    bairro: string;
+    cidade: string;
+    cep: string;
+    uf: string;
+    pais?: string;
+    pontoreferencia?: string;
+    /** Map position, `"lat,lng"`. */
+    map_ll?: string;
+    condominio?: string | number;
+}
+/** The address as a plain record with the same keys and no `undefined` ones. */
+export declare const flatAddress: (address: SgpAddress) => Record<string, string | number>;