sgp-sdk 1.2.0 → 2.0.0-beta.1

package/dist/client.d.ts

@@ -1,228 +1,724 @@
-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.
+import { type CallOptions, type ClientOptions } from "./config.js";
+import { type CatalogsListBillingProfilesData } from "./operations/catalogs-list-billing-profiles.js";
+import { type CatalogsListNasData } from "./operations/catalogs-list-nas.js";
+import { type CatalogsListPopsData } from "./operations/catalogs-list-pops.js";
+import { type ContractsListData, type ContractsListInput } from "./operations/contracts-list.js";
+import { type ContractsListStatusReasonsData } from "./operations/contracts-list-status-reasons.js";
+import { type ContractUpdateData, type ContractUpdateInput } from "./operations/contracts-update.js";
+import { type ContractUpdateStatusData, type ContractUpdateStatusInput } from "./operations/contracts-update-status.js";
+import { type CoverageCheckData, type CoverageCheckInput } from "./operations/coverage-check.js";
+import { type CrmContractCreateData, type CrmContractCreateInput } from "./operations/crm-contracts-create.js";
+import { type CrmContractCreateByCpfCnpjData, type CrmContractCreateByCpfCnpjInput } from "./operations/crm-contracts-create-by-cpf-cnpj.js";
+import { type CrmContractsListData, type CrmContractsListInput } from "./operations/crm-contracts-list.js";
+import { type CrmCustomerCreateData, type CrmCustomerCreateInput } from "./operations/crm-customers-create.js";
+import { type CrmCustomerUpdateStatusData, type CrmCustomerUpdateStatusInput } from "./operations/crm-customers-update-status.js";
+import { type CustomersListData, type CustomersListInput } from "./operations/customers-list.js";
+import { type CustomersSearchData, type CustomersSearchInput } from "./operations/customers-search.js";
+import { type DocumentAddInput } from "./operations/documents-add.js";
+import { type DocumentsListData, type DocumentsListInput } from "./operations/documents-list.js";
+import { type ExperimentalAnnotationsListData, type ExperimentalAnnotationsListInput } from "./operations/experimental-annotations-list.js";
+import { type InvoicesListData, type InvoicesListInput } from "./operations/invoices-list.js";
+import { type OccurrenceCreateData, type OccurrenceCreateInput } from "./operations/occurrences-create.js";
+import { type OccurrencesListMethodsData } from "./operations/occurrences-list-methods.js";
+import { type OccurrencesListTypesData } from "./operations/occurrences-list-types.js";
+import { type PlansListData } from "./operations/plans-list.js";
+import { type PreRegistrationCreateData, type PreRegistrationCreateInput } from "./operations/pre-registrations-create.js";
+import { type PreRegistrationsListDueDaysData } from "./operations/pre-registrations-list-due-days.js";
+import { type PreRegistrationsListPlansData } from "./operations/pre-registrations-list-plans.js";
+import { type PreRegistrationsListSellersData } from "./operations/pre-registrations-list-sellers.js";
+import { type ServiceAddTvData, type ServiceAddTvInput } from "./operations/services-add-tv.js";
+import { type ServiceChangePlanData, type ServiceChangePlanInput } from "./operations/services-change-plan.js";
+import { type ServiceRemoveTvData, type ServiceRemoveTvInput } from "./operations/services-remove-tv.js";
+import { type WorkOrdersListData, type WorkOrdersListInput } from "./operations/work-orders-list.js";
+import { type WorkOrdersListReasonsData } from "./operations/work-orders-list-reasons.js";
+import { type RawRequestInput } from "./raw-request.js";
+import type { SgpResult } from "./result.js";
+/** Operations on catalogs of the provider's own setup (POPs, NAS, billing profiles). */
+export interface CatalogsClient {
+    /**
+     * Lists the POPs (points of presence): `POST /api/ura/pops/`, JSON, no input. The route is not
+     * paginated, so the result is SGP's own bare array: no page envelope, no total. Unknown fields
+     * reach `data` unchanged. Only the `id` of each POP must be a number (an element that is not an
+     * object fails the response too: `INVALID_RESPONSE`); any other field of the wrong type is left
+     * out of `data` and reported in `warnings` (the original stays in `response`). A read: the opt-in
+     * `maxRetries` may retry it.
      */
-    listAnnotations: (params: ListAnnotationsParams) => Promise<SgpResult<ListAnnotationsResponse>>;
+    listPops: (options?: CallOptions) => Promise<SgpResult<CatalogsListPopsData>>;
     /**
-     * Lists clients, one page at a time: `POST /api/ura/clientes/`.
+     * Lists the NAS (network access servers) and the POPs each one serves: `POST /api/ura/nas/list/`,
+     * JSON, no input. The route is not paginated, so the result is SGP's own bare array: no page
+     * envelope, no total. Unknown fields reach `data` unchanged at every level. Only the `id` of each
+     * NAS must be a number (an element that is not an object fails the response too:
+     * `INVALID_RESPONSE`); any other field of the wrong type is left out of `data` and reported in
+     * `warnings` (the original stays in `response`).
      *
-     * Filter with `cliente_id`, `cpfcnpj` or `cliente_nome`; page with `offset` and `limit`.
+     * The IP address of a NAS (`endereco_ip`) is a secret: see `getSensitivity("catalogs.listNas")`
+     * and project with `pick` before logging or handing it on. A read: the opt-in `maxRetries` may
+     * retry it.
+     */
+    listNas: (options?: CallOptions) => Promise<SgpResult<CatalogsListNasData>>;
+    /**
+     * Lists the billing profiles (SGP "portadores", who issues and collects the invoices):
+     * `GET /api/ura/portador/`, credentials in the query string, no input. The route is not
+     * paginated, so the result is SGP's own bare array: no page envelope, no total. Unknown fields
+     * reach `data` unchanged. Only the `id` of each billing profile must be a number (an element that
+     * is not an object fails the response too: `INVALID_RESPONSE`); any other field of the wrong type
+     * is left out of `data` and reported in `warnings` (the original stays in `response`). The
+     * `portador` filter of `invoices.list` takes these ids. A read: the opt-in `maxRetries` may retry
+     * it.
      */
-    listClients: (params?: ListClientsParams) => Promise<SgpResult<ListClientsResponse>>;
+    listBillingProfiles: (options?: CallOptions) => Promise<SgpResult<CatalogsListBillingProfilesData>>;
+}
+/** Operations on the CRM funnel's customers (SGP "clientes CRM"). */
+export interface CrmCustomersClient {
     /**
-     * Looks up a customer and its contracts: `POST /api/ura/consultacliente/`.
+     * Creates a CRM customer: `POST /api/crm/cliente/F` or `/J`, picked by `input.personType`, JSON
+     * with the address nested (`endereco`) and also as loose fields, as SGP reads both. Never retried.
+     *
+     * WARNING: SGP accepts a CPF that already belongs to a customer and creates ANOTHER customer with
+     * the same document (live: the duplicate was created and both customers were listed by `customers.list`). Unlike
+     * `preRegistrations.create`, which refuses an existing CPF (402), nothing here prevents a
+     * duplicate, and a duplicate breaks every lookup by document. Check the document first
+     * (`customers.search`, `customers.list`) and decide in your own code whether a second customer is
+     * acceptable. A CRM customer is an ordinary customer: its `cliente_id` is the `CustomerId` that
+     * `customers.list` shows.
+     *
+     * A success carries the new `cliente_id` (a `CustomerId`, required: a 2xx without it is
+     * `INVALID_RESPONSE`) and SGP's `message`, which echoes the customer's name and document. Only
+     * `/F` was exercised; `/J` follows the vendor's documentation. Other person types (`E`, `EJ`) are
+     * reachable through `request()`.
      *
-     * 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.
+     * SGP's field validation (HTTP 400, `errors` as an object keyed by field, e.g. `nome` refused for
+     * containing digits) is `REJECTED` with effect `"none"`. Other failures carry `error.effect` by
+     * the usual rules: `"none"` only when the SDK can affirm nothing was applied (refused locally,
+     * cancelled before send, or SGP refused with a field/business error such as `errors` as an
+     * object, `error` or `detail`); `"unknown"` after a timeout, network failure, cancellation after
+     * send, an HTTP 5xx or 3xx, SGP's generic `errors` array, or a 2xx outside the contract. On
+     * `"unknown"`, search for the document before sending again: a second call may create a duplicate.
      */
-    lookupCustomer: (params: LookupCustomerParams) => Promise<SgpResult<LookupCustomerResponse>>;
+    create: (input: CrmCustomerCreateInput, options?: CallOptions) => Promise<SgpResult<CrmCustomerCreateData>>;
     /**
-     * Lists contract summaries: `POST /api/ura/listacontrato/`.
+     * Changes the status of a CRM customer: `POST /api/crm/cliente/{cliente_id}/status/` (trailing
+     * slash), JSON. Never retried. Status codes are in `CRM_STATUS` (6 is "Contrato realizado no
+     * SGP"), but any number is sent and SGP decides; only 6 was exercised.
      *
-     * 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.
+     * A success carries `cliente_id` and `novo_status.codigo`, both required, and SGP's `message`
+     * (which echoes the customer's name). A customer that already left the CRM (or a repeated status
+     * 6) answers HTTP 404 `{ "error": "Cadastro não encontrado" }`: `NOT_FOUND`, effect `"none"`
+     * (a 1.x capture). This route has no other known rejection: a customer that never
+     * was in the CRM answers with SGP's generic `errors` array, which stays `"unknown"`;
+     * field/business errors (`errors` as an object, `error`, `detail`) are `"none"`. On `"unknown"`,
+     * read the customer before sending again.
      */
-    listContracts: (params?: ListContractsParams) => Promise<SgpResult<ListContractsResponse>>;
+    updateStatus: (input: CrmCustomerUpdateStatusInput, options?: CallOptions) => Promise<SgpResult<CrmCustomerUpdateStatusData>>;
+}
+/** Operations on the contracts of CRM customers. */
+export interface CrmContractsClient {
     /**
-     * Lists service orders (OS), one page at a time: `POST /api/ura/ordemservico/list/`.
+     * Creates a contract for a CRM customer, by customer id: `POST
+     * /api/crm/cliente/{cliente_id}/contratos/` (trailing slash), JSON with both addresses nested
+     * and the installation address also as loose fields. Never retried. It works only for a customer
+     * that is still in the CRM funnel: a definitive customer (such as one created by
+     * `preRegistrations.create` with `precadastro_ativar`) is refused.
+     *
+     * SGP's refusal of a customer outside the CRM, HTTP 400
+     * `{ errors: ["Ocorreu um erro: Não encontrado cliente CRM com ID <n>"] }`, is `REJECTED` with
+     * `error.reason === "CUSTOMER_NOT_IN_CRM"` and effect `"none"` (read-backs showed no contract
+     * added). Any other `errors` array is SGP's generic wrapper and stays `"unknown"`.
+     *
+     * `plano_id` is a `PlanId` from the URA catalog (`plans.list`). For an Internet service the
+     * vendor's documentation also requires `login`, `senha` and `modoaquisicao`, and SGP requires
+     * `nas` (a NAS name); it answers 400 with `errors` as an object, `"none"`, when one is missing.
+     * Only the missing-`nas` 400 was observed; the other three come from the vendor's documentation. `modoaquisicao` takes
+     * `ACQUISITION_MODE` (0 or 1): the vendor's documentation lists 1 and 2, but SGP refused 2 live.
      *
-     * 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.
+     * A success (HTTP 200) carries the new `clientecontrato` (the contract id, required), SGP's
+     * `message` and `cliente`, which echoes the customer's name and CPF (personal data: see
+     * `getSensitivity`). Other failures carry `error.effect` by the same
+     * rules as `crm.customers.create`. On `"unknown"`, read the customer's contracts before sending
+     * again: a second call may create a duplicate contract.
      */
-    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>>;
+    create: (input: CrmContractCreateInput, options?: CallOptions) => Promise<SgpResult<CrmContractCreateData>>;
     /**
-     * Lists invoices (titulos), one page at a time: `POST /api/ura/titulos/`.
+     * Creates a contract for a CRM customer, by the customer's document: `POST
+     * /api/crm/cliente/contratos/?cpfcnpj=<document>` (trailing slash). The document goes in the
+     * QUERY string of the POST, as in the live capture; the body is the same JSON contract as
+     * `create` (both addresses nested, the installation one also loose) with the credentials, and
+     * has no `cliente_id`. Never retried.
+     *
+     * `cpfcnpj` is SGP's single field: the API decides whether it is a CPF or a CNPJ. Only a CPF was
+     * ever exercised; a CNPJ is accepted by the field's name and was never tried. Send it as you
+     * hold it (digits or formatted). It works only for a customer still in the CRM funnel.
+     *
+     * SGP's refusal of a document that is not a CRM customer, HTTP 400
+     * `{ errors: ["Ocorreu um erro: Não encontrado cliente CRM com documento <formatted document>"] }`
+     * (the document comes back formatted), is `REJECTED` with `error.reason === "CUSTOMER_NOT_IN_CRM"`
+     * and effect `"none"` (the read-back showed no contract added). The matcher covers numeric
+     * documents (CPF or CNPJ digits, dots, dashes, slashes); an alphanumeric CNPJ, or any other `errors`
+     * array (SGP's generic wrapper), stays `"unknown"` without a reason.
      *
-     * 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.
+     * When several customers share a document (SGP allows duplicates, see `crm.customers.create`),
+     * which CRM customer receives the contract is unverified.
+     *
+     * NOT OBSERVED: no success was ever seen on this route, so NO input field reached a success here
+     * (the "Exercised" markers of `CrmContractCreateInput` come from the by-id route) (the only live call was that refusal). The
+     * success shape is assumed to be that of `create` (HTTP 200 with the new `clientecontrato`,
+     * required, SGP's `message` and `cliente`, which echoes the customer's name and is personal
+     * data); a 2xx without a numeric `clientecontrato` is `INVALID_RESPONSE` with effect `"unknown"`.
+     * Other failures carry `error.effect` by the same rules as `create`. On `"unknown"`, read the
+     * customer's contracts (`crm.contracts.list`) before sending again: a second call may create a
+     * duplicate contract.
      */
-    listInvoices: (params?: ListInvoicesParams) => Promise<SgpResult<ListInvoicesResponse>>;
-    /** Lists the POPs (points of presence): `POST /api/ura/pops/`. Takes no parameters. */
-    listPops: () => Promise<SgpResult<ListPopsResponse>>;
+    createByCpfCnpj: (input: CrmContractCreateByCpfCnpjInput, options?: CallOptions) => Promise<SgpResult<CrmContractCreateByCpfCnpjData>>;
     /**
-     * Lists the NAS (network access servers) and the POPs each serves: `POST /api/ura/nas/list/`.
-     * Takes no parameters.
+     * Lists the contracts of a CRM customer, by the customer's document: `GET
+     * /api/crm/cliente/contratos/?cpfcnpj=<document>` (trailing slash), credentials in the query
+     * string. A repeatable read. `cpfcnpj` is SGP's single field: the API decides whether it is a CPF
+     * or a CNPJ; only a CPF was ever exercised. Send it as you hold it (digits or formatted). When
+     * several customers share the document (SGP allows duplicates), which one's contracts are
+     * listed is unverified.
+     *
+     * A success is SGP's own object: `cliente` and `cpf_cnpj` (personal data) and `contratos`, one
+     * summary per contract, an empty array when the CRM customer has none. Each contract must carry a
+     * numeric `cliente_contrato_id` and `contratos` must be an array, or the call is
+     * `INVALID_RESPONSE`; everything else is optional and tolerant (a field of the wrong type is
+     * dropped with a warning, and unknown keys reach `data` as received). `data_cadastro` and
+     * `data_status` stay `DD/MM/AAAA` strings. `endereco`, `motivo_status`, `vendedor` and each
+     * service's `login` (a PPPoE secret) are sensitive: see `getSensitivity`.
      *
-     * `endereco_ip` is network infrastructure; strip it with `omitSensitive` and `nasSecretKeys`
-     * before logging or forwarding.
+     * A document that is not a CRM customer answers HTTP 400
+     * `{ errors: ["Ocorreu um erro: Não encontrado cliente CRM com documento <formatted document>"] }`:
+     * `REJECTED`, with no `reason` and no `effect` (a read applies nothing).
      */
-    listNas: () => Promise<SgpResult<ListNasResponse>>;
-    /** Lists the payment carriers (portadores): `GET /api/ura/portador/`. Takes no parameters. */
-    listPaymentCarriers: () => Promise<SgpResult<ListPaymentCarriersResponse>>;
+    list: (input: CrmContractsListInput, options?: CallOptions) => Promise<SgpResult<CrmContractsListData>>;
+}
+/** Operations of the CRM funnel (SGP "CRM"). */
+export interface CrmClient {
+    /** Operations on CRM customers. */
+    customers: CrmCustomersClient;
+    /** Operations on the contracts of CRM customers. */
+    contracts: CrmContractsClient;
+}
+/** Operations on customers' documents (SGP "documentos" of the support area). */
+export interface DocumentsClient {
     /**
-     * Checks installation viability around a coordinate: `GET /api/ura/viabilidadeinstalacao`.
+     * Attaches a file to a customer: `PUT /api/suporte/cliente/{cliente_id}/documento/add/`
+     * (trailing slash), `multipart/form-data` with the file as the part `file` (and `descricao` as a
+     * text field when given). Never retried: a second call may attach the file twice.
      *
-     * 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 success is a 2xx with an EMPTY body: `data` is `null`, and nothing identifies the new
+     * document. Any other 2xx body is `INVALID_RESPONSE` with effect `"unknown"` (the upload may have
+     * been stored): read the customer's documents before sending again.
      *
-     * A malformed gateway answer (an entry that is neither CTOs nor a message) is `SCHEMA_MISMATCH`.
+     * Failures carry `error.effect` by the same rules as `crm.customers.create`; this route has no
+     * known rejection. The file and its description are the customer's documents: personal data.
      */
-    checkCoverage: (params: CheckCoverageParams) => Promise<SgpResult<CheckCoverageResponse>>;
+    add: (input: DocumentAddInput, options?: CallOptions) => Promise<SgpResult<null>>;
     /**
-     * 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.
+     * Lists the documents attached to a customer: `GET /api/suporte/cliente/{cliente_id}/documento/list/`
+     * (trailing slash), credentials in the query string. The route is not paginated, so the result is
+     * SGP's own bare array: no page envelope, no total. An empty array means the customer has no
+     * document. `cliente_id` is a `CustomerId` (never the id of a contract) and must be a positive
+     * integer, or the call is refused locally (`INVALID_INPUT`, nothing sent); the `cliente_id` of
+     * each row is a `CustomerId` too.
      *
-     * 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.
+     * Unknown fields reach `data` unchanged. Only the `id` and the `cliente_id` of each document must
+     * be numbers (an element that is not an object fails the response too: `INVALID_RESPONSE`); any
+     * other field of the wrong type is left out of `data` and reported in `warnings` (the original
+     * stays in `response`).
      *
-     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     * Each document carries the file name or link (`arquivo`), its description and the operator:
+     * personal data, see `getSensitivity("documents.list")` and project with `pick` before logging or
+     * handing it on. A read: the opt-in `maxRetries` may retry it.
      */
-    openTicket: (params: OpenTicketParams) => Promise<SgpWriteResult<OpenTicketResponse>>;
+    list: (input: DocumentsListInput, options?: CallOptions) => Promise<SgpResult<DocumentsListData>>;
 }
-/** 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>>;
+/** Operations on occurrences (SGP "ocorrências", the support tickets or "chamados"). */
+export interface OccurrencesClient {
+    /**
+     * Opens an occurrence (a support ticket) for a contract: `POST /api/ura/chamado/` (trailing
+     * slash), JSON. Never retried: a second call opens a second ticket. Unless `desativa_os` is `1`,
+     * SGP opens a work order with it.
+     *
+     * A success returns `id` (the ID of the OCCURRENCE) and `protocolo` (its protocol number), both
+     * required. It never carries the ID of the work order: read it with `workOrders.list`. The work
+     * order's `ocorrencia` has the format of the `protocolo` (observed: a work order whose
+     * `ocorrencia` had that format), not of the occurrence `id`; that link is observed but not
+     * confirmed, so match on `protocolo` and verify the work order before relying on it. `motivoos` is the `codigo` of a reason of the work order, from
+     * `workOrders.listReasons` (each SGP instance has its own).
+     *
+     * SGP answers some refusals with HTTP 200 and `status: 0` (and a `msg`): that is `REJECTED` with
+     * effect `"unknown"`, since nothing says whether anything was created. Read the contract's
+     * occurrences before sending again. Other failures carry `error.effect` by the same rules as
+     * `crm.customers.create`.
+     */
+    create: (input: OccurrenceCreateInput, options?: CallOptions) => Promise<SgpResult<OccurrenceCreateData>>;
+    /**
+     * Lists the occurrence types: `GET /api/os/ocorrencia/tipo/list/`, credentials in the query
+     * string, no input. The route is not paginated, so the result is SGP's own bare array: no page
+     * envelope, no total. Each type has two identifiers, `id` and `codigo`, both numbers and kept
+     * apart as SGP sends them: `occurrences.create` takes the `codigo` as `ocorrenciatipo` (the
+     * vendor's collection says "Código"). Unknown fields
+     * reach `data` unchanged. Only `id` and `codigo` of each type must be numbers (an element that is
+     * not an object fails the response too: `INVALID_RESPONSE`); any other field of the wrong type is
+     * left out of `data` and reported in `warnings` (the original stays in `response`).
+     * `classificacoes` and `setores` were always empty in the captures: their content is untyped. A
+     * read: the opt-in `maxRetries` may retry it.
+     */
+    listTypes: (options?: CallOptions) => Promise<SgpResult<OccurrencesListTypesData>>;
+    /**
+     * Lists the occurrence methods: `GET /api/ura/ocorrencia/metodo/list/`, credentials in the query
+     * string, no input. The route is not paginated, so the result is SGP's own bare array: no page
+     * envelope, no total. Unknown fields reach `data` unchanged. Only the `codigo` of each method
+     * must be a number (an element that is not an object fails the response too:
+     * `INVALID_RESPONSE`); any other field of the wrong type is left out of `data` and reported in
+     * `warnings` (the original stays in `response`). A read: the opt-in `maxRetries` may retry it.
+     */
+    listMethods: (options?: CallOptions) => Promise<SgpResult<OccurrencesListMethodsData>>;
 }
-/** 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>>;
+/** Operations on contracts (SGP "contratos"). */
+export interface ContractsClient {
     /**
-     * Lists the sellers (vendedores): `POST /api/precadastro/vendedor/list`. Takes no parameters.
+     * Lists contracts: `POST /api/ura/listacontrato/`, JSON; every filter is optional. The route is
+     * not paginated, so the result is SGP's own bare array with one summary per matching contract: no
+     * page envelope, no total. Without any filter SGP may answer with the whole contract base, so
+     * filter whenever you can. An empty array means no contract matched.
      *
-     * 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.
+     * Unknown fields reach `data` unchanged (the address SGP adds with `exibir_endereco` is one: it
+     * was never captured, so it is untyped and personal data; see `getSensitivity` and `pick`). Only
+     * each `id_contrato` and `id_cliente` must be numbers, and every element must be an object
+     * (`INVALID_RESPONSE` otherwise); any other field of the wrong type is left out of `data` and
+     * reported in `warnings` (the original stays in `response`).
+     *
+     * `plano` is a `PlanId` from `plans.list`, never an id of `preRegistrations.listPlans`. A read:
+     * the opt-in `maxRetries` may retry it.
      */
-    listSellers: () => Promise<SgpResult<ListSellersResponse>>;
+    list: (input?: ContractsListInput, options?: CallOptions) => Promise<SgpResult<ContractsListData>>;
+    /**
+     * Changes the status of a contract: `POST /api/ura/contrato/status/edit/`, JSON. Never retried.
+     * Activating a contract starts its billing, so a status change is a billing event.
+     *
+     * SGP decides which transitions it allows; the SDK keeps no transition table. Evidence by
+     * transition: Suspenso to Ativo and Ativo to Suspenso returned 200 with the `resposta` body
+     * captured raw (`resposta.contrato_status` names the new status); Inativo to Ativo returned 200
+     * and a read-back confirmed it, but the body was not captured; Ativo to Inativo was refused with
+     * a 400 (the body is known from the support notes' prose, not from a capture; SGP's panel does
+     * not offer Inativo from Ativo). Status codes are in `CONTRACT_STATUS`, but any number is sent.
+     * `motivo` is the ID of a reason from the provider's own list: read it with
+     * `contracts.listStatusReasons`, never assume a value; it is optional, and omitted it is not
+     * sent (a call without it was never exercised).
+     *
+     * SGP's refusal, HTTP 400 `{ error: "Status de Contrato não alterado." }`, is `REJECTED` with
+     * `error.reason === "STATUS_NOT_CHANGED"` and effect `"none"`. Its body text is known from the
+     * support exchange only, not from a raw capture.
+     *
+     * Other failures carry `error.effect`: `"none"` only when the SDK can affirm nothing was applied
+     * (the input was refused locally, the call was cancelled before send, or SGP refused with a
+     * field/business error such as `errors` as an object, `error` or `detail`); `"unknown"` after a
+     * timeout, network failure, cancellation after send, an HTTP 5xx or 3xx, SGP's generic `errors`
+     * array, or a 2xx outside the contract (`INVALID_RESPONSE`). On `"unknown"`, read the contract
+     * (`contracts.list`) before sending again.
+     */
+    updateStatus: (input: ContractUpdateStatusInput, options?: CallOptions) => Promise<SgpResult<ContractUpdateStatusData>>;
+    /**
+     * Edits a contract: `POST /api/ura/contrato/edit/`, JSON. Never retried. Only `forma_cobranca`
+     * (the billing method, `BILLING_METHOD`) is accepted; changing it changes how the contract is
+     * billed. A success carries SGP's `resposta.alterados`, the list of fields SGP says it applied,
+     * returned as-is.
+     *
+     * Failures carry `error.effect` by the same rules as `contracts.updateStatus`; this route has no
+     * known rejection, so a 4xx is `"none"` only with an `errors` object, `error` or `detail` body.
+     * On `"unknown"`, read the contract before sending again.
+     */
+    update: (input: ContractUpdateInput, options?: CallOptions) => Promise<SgpResult<ContractUpdateData>>;
+    /**
+     * Lists the reasons the provider can register with a status change: `POST
+     * /api/ura/contrato/status/motivos/` (trailing slash), JSON, no input. Each provider has its own
+     * list, so read it before passing a `motivo` to `contracts.updateStatus` and never assume a
+     * value. The route is not paginated, so the result is SGP's own bare array of `{ id, motivo }`:
+     * no page envelope, no total. Unknown fields reach `data` unchanged. Only the `id` of each reason
+     * must be a number (an element that is not an object fails the response too:
+     * `INVALID_RESPONSE`); any other field of the wrong type is left out of `data` and reported in
+     * `warnings` (the original stays in `response`). A read: the opt-in `maxRetries` may retry it.
+     */
+    listStatusReasons: (options?: CallOptions) => Promise<SgpResult<ContractsListStatusReasonsData>>;
 }
-/** Methods that hit the `/api/crm/` routes. Writes: they return an {@link SgpWriteResult}. */
-export interface CrmClient {
+/** Operations on installation coverage (SGP "viabilidade de instalação"). */
+export interface CoverageClient {
     /**
-     * Creates an individual (PF) customer: `POST /api/crm/cliente/F`.
+     * Checks the viability of an installation around a coordinate: `GET /api/ura/viabilidadeinstalacao`
+     * (no trailing slash), params and credentials in the query string. `gateway`, `raio` (meters) and
+     * `coordenada` (`"lat,lng"`) are all required, or the call is refused locally (`INVALID_INPUT`,
+     * nothing sent). The SDK does not geocode: bring the coordinate yourself.
      *
-     * 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.
+     * The result keeps SGP's own shape: an array whose element is an object keyed by the gateway's
+     * own name (`SGPMaps`, `Geogrid`: data-defined), holding the CTOs within the radius (`lat`,
+     * `lng`, `distancia` in meters, `nome`, and `id` on Geogrid) or the message `"Localização
+     * inviável"` when there are none. Nothing is converted: Geogrid sends the numbers as text and
+     * they stay text, so check the type before computing. No page envelope.
      *
-     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     * Unknown fields reach `data` unchanged. The structure must hold (the answer an array of objects,
+     * each gateway's answer a list of objects or a message, `INVALID_RESPONSE` otherwise); any field
+     * of a CTO of the wrong type is left out of `data` and reported in `warnings` (the original stays
+     * in `response`). The coordinate is personal data: see `getSensitivity("coverage.check")`. A
+     * read: the opt-in `maxRetries` may retry it.
+     */
+    check: (input: CoverageCheckInput, options?: CallOptions) => Promise<SgpResult<CoverageCheckData>>;
+}
+/** Operations on customers (SGP "clientes"). */
+export interface CustomersClient {
+    /**
+     * Lists one page of customers: `POST /api/ura/clientes/`. `paginacao` is SGP's own, `total`
+     * included; the SDK never computes it. Unknown fields reach `data` unchanged at every level.
+     * Only `paginacao.total`, `clientes` and the ids, name, document and type of each customer, plus
+     * the ids of contracts, services and plans, must have the expected type; an element of
+     * `clientes`, `contratos` or `servicos` that is not an object fails the response too
+     * (`INVALID_RESPONSE`). Any other field of the wrong type is left out of `data` and reported in
+     * `warnings` (`dropped` names the field that is absent; the original stays in `response`).
      */
-    createIndividualCustomer: (params: CreateIndividualCustomerParams) => Promise<SgpWriteResult<CreateCustomerResponse>>;
+    list: (input?: CustomersListInput, options?: CallOptions) => Promise<SgpResult<CustomersListData>>;
     /**
-     * Creates a company (PJ) customer: `POST /api/crm/cliente/J`.
+     * Searches customers by contract, document, name, PPPoE login or phone: `POST
+     * /api/ura/consultacliente/`, JSON. At least one criterion is required, or the call is refused
+     * locally (`INVALID_INPUT`, nothing sent). A text criterion (`cpfcnpj`, `nome`, `login`,
+     * `telefone`) cannot be an empty string, not even next to a valid criterion: that is parameter
+     * validation, not protection against a broad search (a string of spaces is not empty and goes to
+     * SGP as given). How criteria combine and how names and phones are matched is SGP's decision.
      *
-     * 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.
+     * It returns CANDIDATES and never picks one: `data.contratos` has one entry per matching
+     * contract, each carrying its customer's data flattened (`clienteId`, `razaoSocial`,
+     * `cpfCnpj`...). Any criterion other than `contrato` may match several contracts, of one customer
+     * or of different customers (the same document may belong to more than one customer), so decide
+     * between candidates yourself, by `clienteId` and `contratoId`. No match is a success with
+     * `contratos: []`. For a filtered, paginated list of customers with their contracts and services,
+     * use `customers.list`.
      *
-     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     * Every candidate carries the service's Central and PPPoE credentials, Wi-Fi and the customer's
+     * identity and address: see `getSensitivity("customers.search")` and project with `pick` before
+     * logging or handing it on. Unknown fields reach `data` unchanged. Only `contratos`, and each
+     * candidate's `contratoId` and `clienteId`, must have the expected type (a candidate that is not
+     * an object fails the response too: `INVALID_RESPONSE`); any other field of the wrong type is left
+     * out of `data` and reported in `warnings` (the original stays in `response`). A read: the opt-in
+     * `maxRetries` may retry it.
      */
-    createCompanyCustomer: (params: CreateCompanyCustomerParams) => Promise<SgpWriteResult<CreateCustomerResponse>>;
+    search: (input: CustomersSearchInput, options?: CallOptions) => Promise<SgpResult<CustomersSearchData>>;
+}
+/** Annotations (SGP "anotações") of a customer. */
+export interface ExperimentalAnnotationsClient {
     /**
-     * Creates a contract on a CRM customer: `POST /api/crm/cliente/{cliente_id}/contratos/`.
+     * EXPERIMENTAL: may change incompatibly in a minor release, without a major version.
      *
-     * 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.
+     * Lists the notes of a customer and/or a contract: `GET /api/ura/cliente/anotacao/list/`, query
+     * string. At least one of `cliente_id` and `contrato_id` is required (a positive safe integer);
+     * both together mean AND. Without a valid filter the call is refused locally (`INVALID_INPUT`,
+     * nothing sent), and a key other than those two is refused too, never forwarded.
      *
-     * 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.
+     * SGP ignores both filters and answers with the notes of other customers, so the SDK selects
+     * LOCALLY, over the one response it received, by each note's raw `cliente` and `clientecontrato`.
+     * A customer-only call keeps that customer's notes without a contract; a contract-only call keeps
+     * that contract's; no match is a success with `[]`, never a relaxed filter. Source order and
+     * duplicates are kept. A note that no definite mismatch excludes and whose requested identity is
+     * missing or not a number cannot be decided: the whole call is `INVALID_RESPONSE`
+     * (`error.issues` names `[].cliente` and/or `[].clientecontrato`), never a silent skip. A note of
+     * another customer is dropped before it is read, so its malformed fields do not matter.
      *
-     * `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.
+     * The selected notes are then read like any 2.0 response: `id`, `cliente`, `clientecontrato`
+     * (a number or `null`) and `anotacao` must have their type (`INVALID_RESPONSE` otherwise); any
+     * other known field of the wrong type is left out of `data` and reported in `warnings`, whose
+     * paths index the selected notes. Unknown fields of a selected note reach `data` unchanged, and
+     * each note also carries `raw`, a deep copy of that one record as SGP sent it (personal data like
+     * the note), so a field dropped from its typed position stays recoverable there. A selected note
+     * that embeds, at any depth, an identity of another customer (or of another contract when a
+     * contract was requested), or one that cannot be read, fails the call (`INVALID_RESPONSE`,
+     * `error.issues` `[].(nested).cliente` or `[].(nested).clientecontrato`). Identity keys are matched
+     * by pattern and letter case (`Cliente`, `cliente_id`, `clienteContrato`, `contratos`...), a number
+     * or a list of numbers is compared, and on a customer-only call another contract of the same
+     * customer is accepted only in an object that also names that customer.
      *
-     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     * COMPLETENESS: returns the matching notes present in one SGP response; source completeness is
+     * not guaranteed while this method is experimental. The route documents no pagination, and an
+     * undocumented cap cannot be ruled out. The SDK sends one request, never pages, never truncates.
+     *
+     * PRIVACY: the whole upstream body, other customers' notes included, enters this process's memory.
+     * The SDK never returns, caches or logs it: `response.body` is `{ kind: "withheld" }` whatever the
+     * status (a field dropped from `data` is recoverable from that note's `raw`, never from
+     * `response`), `error.sgp` keeps only strings, and no hook receives it. `request()` refuses this
+     * route (`ROUTE_NOT_ALLOWED`, nothing sent), so it cannot go around this method.
+     * A `fetch` or tracing layer you inject sees the body BEFORE the selection: it must not capture
+     * it. Local selection is not an authorization boundary: authorize the ids you pass, and run this
+     * only in a trusted server process. The note text (`anotacao`) and the staff member (`usuario`)
+     * are personal data, and the text may hold anything a person typed: see
+     * `getSensitivity("experimental.annotations.list")` and project with `pick` before logging or
+     * handing a note on. A read: the opt-in `maxRetries` may retry it, and each attempt downloads the
+     * whole response again.
      */
-    createContract: (clienteId: number, params: CreateContractParams) => Promise<SgpWriteResult<CreateContractResponse>>;
+    list: (input: ExperimentalAnnotationsListInput, options?: CallOptions) => Promise<SgpResult<ExperimentalAnnotationsListData>>;
+}
+/** Operations that are not stable yet: they may change incompatibly in a minor release. */
+export interface ExperimentalClient {
+    /** Customer annotations. */
+    annotations: ExperimentalAnnotationsClient;
+}
+/** Operations on invoices (SGP "títulos"). */
+export interface InvoicesClient {
     /**
-     * Sets the CRM status of a customer: `POST /api/crm/cliente/{cliente_id}/status/`.
+     * Lists one page of invoices: `POST /api/ura/titulos/`, JSON; every filter is optional. Returns
+     * ONE page with SGP's own `paginacao` as received: `offset` (index of the first invoice, from 0),
+     * `limit` (the page size SGP applied, which may differ from the requested one: SGP documents a
+     * maximum of 250), `parcial` (invoices on this page) and `total` (invoices matching the filters
+     * across all pages). The SDK never computes `total`: a page without a numeric `paginacao.total`
+     * is `INVALID_RESPONSE`. It never fetches the next page either: ask for it with `offset`.
      *
-     * 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.
+     * An empty page is a success with `titulos: []` (and, for a filter that matches nothing,
+     * `total: 0`). Unknown fields reach `data` unchanged at every level. Only `paginacao.total`,
+     * `titulos` and the `id` of each invoice must have the expected type (an element of `titulos` that
+     * is not an object fails the response too: `INVALID_RESPONSE`); any other field of the wrong type
+     * is left out of `data` and reported in `warnings` (the original stays in `response`).
      *
-     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     * Each invoice carries the customer's name and document, payment links and the PIX code: see
+     * `getSensitivity("invoices.list")` and project with `pick` before logging or handing it on. A
+     * read: the opt-in `maxRetries` may retry it.
      */
-    updateCustomerStatus: (clienteId: number, params: UpdateCustomerStatusParams) => Promise<SgpWriteResult<UpdateCustomerStatusResponse>>;
+    list: (input?: InvoicesListInput, options?: CallOptions) => Promise<SgpResult<InvoicesListData>>;
 }
-/** Methods that hit the `/api/suporte/` routes. */
-export interface SuporteClient {
+/** Operations on plans (SGP "planos"), the catalog of existing services and contracts. */
+export interface PlansClient {
     /**
-     * Attaches a document to a customer: `PUT /api/suporte/cliente/{cliente_id}/documento/add/`,
-     * sent as multipart with the file in the `file` part.
+     * Lists the plan catalog: `GET /api/ura/consultaplano/`, credentials in the query string. The
+     * route is not paginated, so the result keeps SGP's own shape (`planos` plus SGP's totals
+     * `total_planos` and `total_qtd_servicos`, as received), with no page envelope. Unknown fields
+     * reach `data` unchanged at every level. Only `planos` and the `id` of each plan must have the
+     * expected type (an element of `planos` that is not an object fails the response too:
+     * `INVALID_RESPONSE`); any other field of the wrong type is left out of `data` and reported in
+     * `warnings` (the original stays in `response`).
      *
-     * 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.
+     * ID space: `planos[].id` is a `PlanId`, the identifier of the operations on existing services and
+     * contracts (the `plano` filter of `contracts.list`, `services.changePlan`, `services.addTv`,
+     * and the `servicos[].plano.id` of `customers.list`). It is NOT the id of
+     * `preRegistrations.listPlans` (a `PreRegistrationPlanId`), the catalog `preRegistrations.create`
+     * takes `plano_id` from: the same commercial plan may carry another id there. The two types are
+     * kept apart on purpose, in both directions.
      *
-     * Never retried by the SDK. With `outcome: "unknown"`, check the state in SGP before repeating.
+     * A read: the opt-in `maxRetries` may retry it.
      */
-    addCustomerDocument: (clienteId: number, file: SgpFile, params?: AddCustomerDocumentParams) => Promise<SgpWriteResult<AddCustomerDocumentResponse>>;
+    list: (options?: CallOptions) => Promise<SgpResult<PlansListData>>;
+}
+/** Operations on pré-cadastros (pre-registrations). */
+export interface PreRegistrationsClient {
     /**
-     * Lists the documents attached to a customer: `GET /api/suporte/cliente/{cliente_id}/documento/list/`.
+     * Creates a pré-cadastro: `POST /api/precadastro/F` or `/J`, picked by `input.personType`, sent as
+     * `multipart/form-data` without files. The address goes in SGP's own loose top-level fields
+     * (`logradouro`, `numero`, ...), not grouped. Never retried.
      *
-     * 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.
+     * What it does in SGP: with `precadastro_ativar: 1` the pré-cadastro becomes a definitive
+     * customer, and a contract is created only when the plan and billing data are sufficient
+     * (`plano_id`, `pop_id`, `portador_id`, `vencimento_id`, `formacobranca_id`, ...). The pré-cadastro
+     * row itself keeps existing afterwards. A success carries only SGP's `message`: it holds no
+     * customer, contract or pré-cadastro ID, so look the customer up (`customers.list` by `cpfcnpj`)
+     * to follow up. `plano_id` is a `PreRegistrationPlanId`: it comes from `preRegistrations.listPlans`, never a `PlanId` of `plans.list`; `vencimento_id` from `preRegistrations.listDueDays` and `vendedor_id` from `preRegistrations.listSellers`.
+     *
+     * Failures carry `error.effect`: `"none"` only when the SDK can affirm nothing was applied (the
+     * input was refused locally, the call was cancelled before send, or SGP refused with a
+     * field/business error such as `errors` as an object, `error` or `detail`); `"unknown"` after a
+     * timeout, network failure, cancellation after send, an HTTP 5xx or 3xx, SGP's generic `errors`
+     * array, or a 2xx outside the contract (`INVALID_RESPONSE`). On `"unknown"`, check SGP before
+     * sending again: a second call may create a duplicate.
+     *
+     * An existing CPF is refused with HTTP 402 and `error.reason === "DOCUMENT_ALREADY_REGISTERED"`
+     * (`REJECTED`, effect `"none"`, observed live on `/F`).
+     *
+     * Evidence: only `/F` was exercised; the 200 body `{ message }` is the vendor's, only the key
+     * `message` was seen live; `/J` follows the vendor's documentation.
+     */
+    create: (input: PreRegistrationCreateInput, options?: CallOptions) => Promise<SgpResult<PreRegistrationCreateData>>;
+    /**
+     * Lists the plans of the pré-cadastro catalog: `POST /api/precadastro/plano/list`
+     * (no trailing slash), sent as `multipart/form-data` without files and with no input. The route
+     * is not paginated, so the result is SGP's own bare array: no page envelope, no total. Unknown
+     * fields reach `data` unchanged at every level. Only the `id` of each plan must be a number (an
+     * element that is not an object fails the response too: `INVALID_RESPONSE`); any other field of
+     * the wrong type is left out of `data` and reported in `warnings` (the original stays in
+     * `response`). `gateway.id` and `gateway.gateway_id` are kept as SGP sends them, `""` or text or
+     * number.
+     *
+     * ID space: `id` is a `PreRegistrationPlanId`, the one `preRegistrations.create` takes as
+     * `plano_id`. It is NOT a `PlanId` of `plans.list`: the same commercial plan may carry another id
+     * there, and an id accepted by one route can be refused by the other. The two types are kept
+     * apart on purpose, in both directions. A read: the opt-in `maxRetries` may retry it.
+     */
+    listPlans: (options?: CallOptions) => Promise<SgpResult<PreRegistrationsListPlansData>>;
+    /**
+     * Lists the due days of the pré-cadastro: `POST /api/precadastro/vencimento/list` (no trailing
+     * slash), JSON, no input. The route is not paginated, so the result is SGP's own bare array: no
+     * page envelope, no total. Each entry pairs an `id` (what `preRegistrations.create` takes as
+     * `vencimento_id`) with the `dia` of the month it stands for: read it, never assume a value.
+     * Unknown fields reach `data` unchanged. Only the `id` of each entry must be a number (an element
+     * that is not an object fails the response too: `INVALID_RESPONSE`); any other field of the wrong
+     * type is left out of `data` and reported in `warnings` (the original stays in `response`). A
+     * read: the opt-in `maxRetries` may retry it.
+     */
+    listDueDays: (options?: CallOptions) => Promise<SgpResult<PreRegistrationsListDueDaysData>>;
+    /**
+     * Lists the sellers: `POST /api/precadastro/vendedor/list` (no trailing slash), JSON, no input.
+     * The route is not paginated, so the result is SGP's own bare array: no page envelope, no total.
+     * `id` is what `preRegistrations.create` takes as `vendedor_id`. Unknown fields reach `data`
+     * unchanged. Only the `id` of each seller must be a number (an element that is not an object
+     * fails the response too: `INVALID_RESPONSE`); any other field of the wrong type is left out of
+     * `data` and reported in `warnings` (the original stays in `response`).
+     *
+     * Sellers are employees of the provider: name, CPF and e-mail are personal data, see
+     * `getSensitivity("preRegistrations.listSellers")` and project with `pick` before logging or
+     * handing it on. A read: the opt-in `maxRetries` may retry it.
+     */
+    listSellers: (options?: CallOptions) => Promise<SgpResult<PreRegistrationsListSellersData>>;
+}
+/** Operations on work orders (SGP "ordens de serviço"). */
+export interface WorkOrdersClient {
+    /**
+     * Lists one page of work orders: `POST /api/ura/ordemservico/list/`, JSON; every filter is
+     * optional. Returns ONE page with SGP's own `paginacao` as received: `offset` (index of the first
+     * work order, from 0), `limit` (the page size SGP applied, which may differ from the requested
+     * one), `parcial` (work orders on this page) and `total` (work orders matching the filters across
+     * all pages). The SDK never computes `total`: a page without a numeric `paginacao.total` is
+     * `INVALID_RESPONSE`. It never fetches the next page either: ask for it with `offset`.
+     *
+     * An empty page is a success with `ordens_servicos: []`. Unknown fields reach `data` unchanged at
+     * every level. Only `paginacao.total`, `ordens_servicos` and the `id` of each work order must have
+     * the expected type (an element that is not an object fails the response too:
+     * `INVALID_RESPONSE`); any other field of the wrong type is left out of `data` and reported in
+     * `warnings` (the original stays in `response`). The occurrence number (`ocorrencia`) is text and
+     * stays text.
+     *
+     * Each work order carries the customer's name, free text and the people involved: see
+     * `getSensitivity("workOrders.list")` and project with `pick` before logging or handing it on. A
+     * read: the opt-in `maxRetries` may retry it.
+     */
+    list: (input?: WorkOrdersListInput, options?: CallOptions) => Promise<SgpResult<WorkOrdersListData>>;
+    /**
+     * Lists the occurrence reasons (the `motivo` of a work order): `GET /api/os/ocorrencia/motivo/list/`,
+     * credentials in the query string, no input. The route is not paginated, so the result is SGP's
+     * own bare array: no page envelope, no total. Each reason has two identifiers, `id` and `codigo`,
+     * both numbers and kept apart as SGP sends them: `occurrences.create` takes the `codigo` as
+     * `motivoos` (the vendor's collection says "Código"; live, `motivoos` 10 was the reason whose
+     * `codigo` is 10 and `id` 1). Unknown fields reach `data` unchanged. Only `id` and `codigo` of each reason must be
+     * numbers (an element that is not an object fails the response too: `INVALID_RESPONSE`); any
+     * other field of the wrong type is left out of `data` and reported in `warnings` (the original
+     * stays in `response`). `classificacoes` and `setores` were always empty in the captures: their
+     * content is untyped. A read: the opt-in `maxRetries` may retry it.
      */
-    listCustomerDocuments: (clienteId: number) => Promise<SgpResult<ListCustomerDocumentsResponse>>;
+    listReasons: (options?: CallOptions) => Promise<SgpResult<WorkOrdersListReasonsData>>;
 }
-/**
- * SGP client. Reads return an {@link SgpResult}, writes (`crm`, `ura.openTicket`,
- * `suporte.addCustomerDocument`) an {@link SgpWriteResult}; no method ever throws.
- */
+/** Operations on services (SGP "serviços") of a contract. */
+export interface ServicesClient {
+    /**
+     * Changes the plan of a service: `POST /api/suporte/service/update/{servico_id}/` (trailing
+     * slash), `multipart/form-data` without files, with `action` fixed to `change_plano`. Never
+     * retried. A plan change is a billing event.
+     *
+     * `plano_id` is a `PlanId` from the URA catalog (`plans.list`). `servico_tipo` is required; only `1`
+     * (`SERVICE_TYPE.internet`) was exercised against SGP, other values are sent as given and SGP
+     * decides. A success carries SGP's `msg` only, with no ID of the service or the plan: read the
+     * contract (`customers.list`) to confirm the new plan.
+     *
+     * Failures carry `error.effect`: `"none"` only when the SDK can affirm nothing was applied (the
+     * input was refused locally, including a `servico_id` that is not a positive safe integer, the
+     * call was cancelled before send, or SGP refused with a field/business error such as `errors` as
+     * an object, `error` or `detail`); `"unknown"` after a timeout, network failure, cancellation
+     * after send, an HTTP 5xx or 3xx, SGP's generic `errors` array, or a 2xx outside the contract
+     * (`INVALID_RESPONSE`). This route has no known rejection. On `"unknown"`, read the service
+     * before sending again.
+     */
+    changePlan: (input: ServiceChangePlanInput, options?: CallOptions) => Promise<SgpResult<ServiceChangePlanData>>;
+    /**
+     * Adds a TV service to a contract: `POST /api/servico/tv` (no trailing slash),
+     * `multipart/form-data` without files. Never retried. Adding a service changes what the contract
+     * is billed for.
+     *
+     * `planobase_id` is a `PlanId` from the URA catalog (`plans.list`). SGP accepts only active contracts. A
+     * success (HTTP 201) returns the new `servico_id` (a number); `clientecontrato_id` is kept as the
+     * string SGP sends. Only `info_extra` was exercised among the optional fields; `tipo_equipamento`
+     * and `endereco_id` are documented by the vendor and never sent.
+     *
+     * SGP's refusal of a contract that is not active, HTTP 400
+     * `{ errors: ["clientecontrato_id: Só é possível adicionar serviços em contratos ativos."] }`, is
+     * `REJECTED` with `error.reason === "CONTRACT_NOT_ACTIVE"` and effect `"none"` (a read-back after
+     * the observed refusal showed nothing added on read-back; its raw body is reconstructed). Any other `errors` array is SGP's generic wrapper and
+     * stays `"unknown"`.
+     *
+     * Other failures carry `error.effect` by the same rules as `services.changePlan`. On
+     * `"unknown"`, read the contract's services before sending again: a second call may add a
+     * duplicate service.
+     */
+    addTv: (input: ServiceAddTvInput, options?: CallOptions) => Promise<SgpResult<ServiceAddTvData>>;
+    /**
+     * Removes a TV service: `DELETE /api/servico/tv/{servico_id}` (no trailing slash), with the
+     * contract in a `multipart/form-data` body (without files), as SGP expects. Never retried.
+     *
+     * A success returns SGP's `msg`, the removed `servico_id` and `clientecontrato_id` (kept as the
+     * string SGP sends). This route has no known rejection; failures carry `error.effect` by the same
+     * rules as `services.changePlan`. On `"unknown"`, read the contract's services before sending
+     * again.
+     */
+    removeTv: (input: ServiceRemoveTvInput, options?: CallOptions) => Promise<SgpResult<ServiceRemoveTvData>>;
+}
+/** SGP 2.0 client. */
 export interface SgpClient {
-    ura: UraClient;
-    os: OsClient;
-    precadastro: PrecadastroClient;
+    /** Operations on catalogs (POPs, NAS, billing profiles). */
+    catalogs: CatalogsClient;
+    /** Operations on contracts. */
+    contracts: ContractsClient;
+    /** Operations on installation coverage. */
+    coverage: CoverageClient;
+    /** Operations of the CRM funnel. */
     crm: CrmClient;
-    suporte: SuporteClient;
+    /** Operations on customers. */
+    customers: CustomersClient;
+    /** Operations on customers' documents. */
+    documents: DocumentsClient;
+    /**
+     * Operations that may change incompatibly in a minor release; SemVer holds for everything else.
+     */
+    experimental: ExperimentalClient;
+    /** Operations on invoices. */
+    invoices: InvoicesClient;
+    /** Operations on occurrences. */
+    occurrences: OccurrencesClient;
+    /** Operations on plans. */
+    plans: PlansClient;
+    /** Operations on pré-cadastros. */
+    preRegistrations: PreRegistrationsClient;
+    /**
+     * Raw call to a route no method covers yet. A developer tool: never expose it as an agent or
+     * MCP tool, and never build `path` or `body` from untrusted input.
+     *
+     * It uses the client's credentials, time budget, cancellation and hooks, and classifies by
+     * HTTP alone (the same status mapping as every method). Nothing else is interpreted: `ok: true`
+     * means SGP accepted the request at HTTP level (a 2xx), never that the business operation
+     * succeeded: SGP answers some refusals with a 200, so read `data` yourself. `data` is the body
+     * as received (parsed JSON, text, or `undefined` when empty), typed `unknown`; `response` is the
+     * full evidence.
+     *
+     * Destination: only a relative path under `/api/` of the configured instance is accepted (see
+     * {@link RawRequestInput.path}; a `;` is sent literally and stays on the same origin, under
+     * `/api/`); anything else is `INVALID_INPUT` with `effect: "none"` and `attempts: 0`, and
+     * nothing is sent. The annotations route is refused as `ROUTE_NOT_ALLOWED` (same effect and
+     * attempts; use `experimental.annotations.list`). Redirects are never followed: a 3xx is `INVALID_RESPONSE`.
+     * It is never retried, whatever `maxRetries` says.
+     *
+     * Effect: `"none"` only when the call was refused or cancelled before send. After a request was
+     * sent every failure is `"unknown"`, a 4xx included, and the HTTP verb is never taken as proof
+     * that a call only reads: check SGP before sending again.
+     *
+     * Sensitivity: the result declares no sensitive keys, so treat `data` and `response` as
+     * sensitive. The body is not redacted and may echo credentials or personal data (only header
+     * values are redacted); `toSafeLog` leaves it out. Log `toSafeLog(result)`, and send on only what `pick` names; an unknown key is
+     * never safe. Hooks get the method but never the path.
+     */
+    request: (input: RawRequestInput, options?: CallOptions) => Promise<SgpResult<unknown>>;
+    /** Operations on services. */
+    services: ServicesClient;
+    /** Operations on work orders. */
+    workOrders: WorkOrdersClient;
 }
-/** Creates an SGP client bound to `config`; `token` and `app` are sent on every request. */
-export declare const createSgpClient: (config: SgpClientConfig) => SgpClient;
+/** Creates a client. Throws `InvalidConfigurationError` for an invalid configuration. */
+export declare const createSgpClient: (options: ClientOptions) => SgpClient;