sgp-sdk 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/client.d.ts

@@ -2,11 +2,15 @@ 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 ContractsCheckConnectionData, type ContractsCheckConnectionInput } from "./operations/contracts-check-connection.js";
 import { type ContractsListData, type ContractsListInput } from "./operations/contracts-list.js";
+import { type ContractsListServicesData, type ContractsListServicesInput } from "./operations/contracts-list-services.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 CoverageCheckAddressData, type CoverageCheckAddressInput } from "./operations/coverage-check-address.js";
+import { type CoverageListGatewaysData } from "./operations/coverage-list-gateways.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";
@@ -18,7 +22,9 @@ 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 MaintenanceListData } from "./operations/maintenance-list.js";
 import { type OccurrenceCreateData, type OccurrenceCreateInput } from "./operations/occurrences-create.js";
+import { type OccurrencesListData, type OccurrencesListInput } from "./operations/occurrences-list.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";
@@ -26,10 +32,14 @@ import { type PreRegistrationCreateData, type PreRegistrationCreateInput } from
 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 ServiceAddGenericData, type ServiceAddGenericInput } from "./operations/services-add-generic.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 ServiceRemoveGenericData, type ServiceRemoveGenericInput } from "./operations/services-remove-generic.js";
 import { type ServiceRemoveTvData, type ServiceRemoveTvInput } from "./operations/services-remove-tv.js";
+import { type WorkOrdersGetData, type WorkOrdersGetInput } from "./operations/work-orders-get.js";
 import { type WorkOrdersListData, type WorkOrdersListInput } from "./operations/work-orders-list.js";
+import { type WorkOrdersListCommentsData, type WorkOrdersListCommentsInput } from "./operations/work-orders-list-comments.js";
 import { type WorkOrdersListReasonsData } from "./operations/work-orders-list-reasons.js";
 import { type RawRequestInput } from "./raw-request.js";
 import type { SgpResult } from "./result.js";
@@ -75,14 +85,27 @@ export interface CrmCustomersClient {
      * 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
+     * SGP refuses a document that is already registered: HTTP 400 with `errors.cpfcnpj`, which is
+     * `REJECTED` with `error.reason === "DOCUMENT_ALREADY_REGISTERED"` (the same reason as
+     * `preRegistrations.create`) and effect `"none"`; any other field error keeps no reason. The
+     * check holds for every customer, at any status (status 6, "Contrato realizado no SGP",
+     * included), with one observed exception: a customer whose document was stored UNFORMATTED (for
+     * example a pré-cadastro created with digits only, which SGP stores as sent) was not
+     * detected, and a duplicate was created (live: both customers were listed by `customers.list`).
+     * A duplicate breaks every lookup by document. So a rejection is NOT a complete guard: ALWAYS read
+     * `customers.list({ cpfcnpj })` first 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.
      *
+     * `cpfcnpj` goes out in the canonical mask the base holds: a CPF (`/F`) as `999.999.999-99`, a
+     * CNPJ (`/J`, alphanumeric included, uppercased) as `AA.AAA.AAA/AAAA-99`, whether you give it
+     * with or without punctuation. A document in any other format, or of the other kind than the
+     * route, is refused locally (`INVALID_INPUT`, `error.issues` `["cpfcnpj: expected ..."]`, nothing
+     * sent, effect `"none"`). Format only: the SDK does not verify the check digits, but SGP does for
+     * a CPF: a CPF with wrong digits is refused with HTTP 400 `errors.cpfcnpj` "CPF inválido.", which
+     * is `REJECTED` with `error.reason === "DOCUMENT_INVALID"` and effect `"none"` (observed live on
+     * `/F`, and a read-back showed nothing created). The check digits of a CNPJ were never tested.
+     *
      * 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
@@ -241,18 +264,61 @@ export interface OccurrencesClient {
      * 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).
+     * required. It never carries the ID of the work order: read it with `occurrences.list({ contrato })`,
+     * whose `ordens_servicos[].id` is the work order id (observed once; the occurrence's `numero`
+     * equals the work order's `ocorrencia`). That the `protocolo` returned here equals that `numero`
+     * was not compared in a raw capture, so check 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`.
+     * occurrences before sending again. The exception is `data_hora_agendamento` with seconds
+     * (`AAAA-MM-DD HH:MM:SS`), which SGP refuses with `msg` "Data e hora de agendamento inválida,
+     * formato esperado: AAAA-MM-DD HH:MM": `reason: "INVALID_SCHEDULE"` and effect `"none"` (the
+     * contract's occurrences were read back and nothing had been created; observed once). The SDK
+     * sends the date as given: SGP decides what is valid. Other failures carry `error.effect` by the
+     * same rules as `crm.customers.create`.
+     *
+     * Observed live: an occurrence WITHOUT `motivoos` is accepted and SGP still creates a work order;
+     * `status_encerrado: 1` closes both the occurrence and the work order; closing an installation work
+     * order (`motivoos` 10) did not change the contract status (it stayed inactive; observed once).
      */
     create: (input: OccurrenceCreateInput, options?: CallOptions) => Promise<SgpResult<OccurrenceCreateData>>;
+    /**
+     * Lists one page of occurrences with their work orders: `POST /api/ura/ocorrencia/list/`
+     * (trailing slash), `multipart/form-data` without files; every filter is optional (the vendor
+     * marks none as required).
+     *
+     * AT LEAST ONE FILTER IS REQUIRED: WITHOUT ONE, SGP LISTS THE OCCURRENCES OF EVERY CUSTOMER (up to
+     * 1000 per call, with names and free text). A call with no filter is refused locally
+     * (`INVALID_INPUT`, `attempts` 0, nothing sent); `offset` and `limit` are paging and do not count.
+     * Filter by `contrato` whenever you can. A filter that is present must say something: `contrato: 0`
+     * or an empty text filter is refused locally too, since SGP could read it as "no filter". Only `contrato` with `limit` was exercised; the other filters follow the
+     * vendor's collection.
+     *
+     * This is how to find the work order a `occurrences.create` opened: each occurrence carries
+     * `ordens_servicos[]`, whose `id` is the work order id (observed once, with the same
+     * `numero` as the work order's `ocorrencia`). Read the work order with `workOrders.get`.
+     *
+     * Returns ONE page with SGP's own `paginacao` as received: `offset` (index of the first
+     * occurrence, from 0), `limit` (the page size SGP applied), `parcial` (occurrences on this page)
+     * and `total` (occurrences 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`. A contract with no occurrence is a success with
+     * `ocorrencias: []` and `total: 0`.
+     *
+     * Unknown fields reach `data` unchanged at every level. Only `paginacao.total`, `ocorrencias`,
+     * the `id` of each occurrence and the `id` of each of its work orders 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 `numero` is text and stays text. Before the route was in the
+     * token's whitelist SGP answered 401 (`UNAUTHORIZED`), not the 403 of the other support reads.
+     *
+     * Each occurrence carries the customer's name, free text and the people involved: see
+     * `getSensitivity("occurrences.list")` and project with `pick` before logging or handing it on. A
+     * read: the opt-in `maxRetries` may retry it.
+     */
+    list: (input?: OccurrencesListInput, options?: CallOptions) => Promise<SgpResult<OccurrencesListData>>;
     /**
      * 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
@@ -294,6 +360,60 @@ export interface ContractsClient {
      * the opt-in `maxRetries` may retry it.
      */
     list: (input?: ContractsListInput, options?: CallOptions) => Promise<SgpResult<ContractsListData>>;
+    /**
+     * Lists the services of a contract with their online state and session: `POST
+     * /api/suporte/contrato/list/` (note the trailing slash), multipart form. The technical support
+     * read: is the customer online now (`servico_online`), since when (`rad_dataconexao`, `rad_tempo`),
+     * on which IP, MAC and NAS. SGP's own bare array with ONE ROW PER SERVICE (internet and TV), each
+     * repeating the customer, contract, address and plan; `[]` when nothing matches. A row of an
+     * online internet service also carries the RADIUS session (`rad_*`); an offline one has none.
+     * Filter by `contrato_id` (exercised) or `cliente_id` (exercised); `cliente_nome`,
+     * `cliente_cpfcnpj` and `servico_login` follow the vendor's documentation and were never sent.
+     *
+     * At least one filter is required: without one SGP lists the services of EVERY customer, with
+     * plaintext service passwords, so a call with no filter is refused locally (`INVALID_INPUT`,
+     * `attempts` 0, nothing sent). An empty text or a 0 id in a filter is refused locally too.
+     *
+     * Type normalization: `servico_id`, `contrato_id`, `contrato_status_id` and
+     * `contrato_pop_id` are numbers (SGP sends text), the RADIUS counters and ids are numbers,
+     * `contrato_status` is trimmed (SGP pads it: `" Ativo "`). Each row needs a numeric `servico_id`
+     * (`INVALID_RESPONSE` otherwise); any other field of the wrong type is left out of `data` and
+     * reported in `warnings` (the original stays in `response`).
+     *
+     * The rows hold PLAINTEXT SERVICE PASSWORDS and network identifiers (login, MACs, IPs, NAS, IPv6
+     * prefixes, session ids), and the customer's name, contact and address. Read
+     * `getSensitivity("contracts.listServices")` and project with `pick`; never log or hand the result
+     * on whole. A read: the opt-in `maxRetries` may retry it.
+     *
+     * Online rows were never captured from a synthetic contract: their `rad_*` fields follow the
+     * masked shape of a real contract (types only).
+     */
+    listServices: (input?: ContractsListServicesInput, options?: CallOptions) => Promise<SgpResult<ContractsListServicesData>>;
+    /**
+     * Asks SGP for its verdict on a contract's connection: `POST /api/ura/verificaacesso/` (note the
+     * trailing slash), multipart form. Online (`status` 1), offline (2), under maintenance (9) or not
+     * checked (0): see `CONNECTION_STATUS`. Pass `contrato` (exercised) or `telefone` (documented,
+     * never sent); `status_all: 1` includes the contracts the default filter leaves out (a suspended
+     * contract answered `[]` without it). `protocolo_ura` is not offered: it asks SGP to open an
+     * occurrence, which is `occurrences.create`'s job.
+     *
+     * THIS IS DECLARED A WRITE, although it only looks like a check. The vendor documents that, under
+     * an active maintenance, SGP opens an occurrence by default, even without `protocolo_ura`. That
+     * was not tested here (the exercised calls ran with no active maintenance, and the occurrence
+     * counts before and after were equal). So: it is NEVER retried, whatever `maxRetries` says; every
+     * failure after the request was sent carries `error.effect`, usually `"unknown"` (an occurrence may
+     * have been opened: read `occurrences.list({ contrato })` before sending again); and it is never
+     * part of a sweep or a health poll. Call `maintenance.list()` first: with an active maintenance
+     * covering the customer, you already know the answer and avoid the side effect.
+     *
+     * The data is ALWAYS an array with one item per internet service, whatever SGP sent: SGP answers
+     * an array with `status_all`, ONE bare object (wrapped by the SDK) for an active contract without
+     * it, and `[]` when the contract is outside its default filter. `[]` is no verdict, not "offline".
+     * Each item needs a numeric `status`; the rest (`msg`, `servico_id`, `contratoId`, `login`,
+     * `razaoSocial`, `cpfCnpj`) is read tolerantly. `login` is a secret and `razaoSocial` and `cpfCnpj`
+     * are personal: see `getSensitivity("contracts.checkConnection")` and project with `pick`.
+     */
+    checkConnection: (input: ContractsCheckConnectionInput, options?: CallOptions) => Promise<SgpResult<ContractsCheckConnectionData>>;
     /**
      * 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.
@@ -349,13 +469,16 @@ export interface CoverageClient {
      * 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.
+     * nothing sent). Read the `gateway` ids with `coverage.listGateways`. The SDK does not geocode:
+     * bring the coordinate yourself.
      *
      * 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.
+     * inviável"` when there are none. `lat`, `lng`, `distancia` and `id` are a `number` or `null`:
+     * Geogrid sends them as numeric text (`"0"`), SGPMaps as numbers, and an empty text is `null`,
+     * never `0`. Text that is not a plain number is left out of `data` with a warning (the original
+     * stays in `response`). No page envelope.
      *
      * 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
@@ -364,6 +487,55 @@ export interface CoverageClient {
      * read: the opt-in `maxRetries` may retry it.
      */
     check: (input: CoverageCheckInput, options?: CallOptions) => Promise<SgpResult<CoverageCheckData>>;
+    /**
+     * Checks viability by ADDRESS, before a coordinate exists: `POST /api/ura/viabilidade/` (trailing
+     * slash), `multipart/form-data` without files. The filters are SGP's own: `cep`, `cidade`,
+     * `logradouro`, `bairro`, `numero_inicial`, `numero_final`; the vendor says to use one of them, so
+     * at least one is required or the call is refused locally (`INVALID_INPUT`, nothing sent). Only
+     * `cep` alone and `cidade` alone were exercised; how filters combine is SGP's decision. For a
+     * coordinate and a map gateway use `check`.
+     *
+     * The result is SGP's own object, kept as received: observed `{ "viabilidade": true }` (a postal
+     * code) and `{}` (a city alone). A MISSING `viabilidade` MEANS UNKNOWN, NEVER "NO COVERAGE": do
+     * not turn it into `false`. The "no coverage" answer was NEVER OBSERVED, so what SGP sends for an
+     * address without coverage is not known; whatever comes is passed through. The body must be an
+     * object (`INVALID_RESPONSE` otherwise); `viabilidade` of the wrong type is left out of `data` and
+     * reported in `warnings` (the original stays in `response`). The address is personal data: see
+     * `getSensitivity("coverage.checkAddress")`. A read: the opt-in `maxRetries` may retry it.
+     */
+    checkAddress: (input: CoverageCheckAddressInput, options?: CallOptions) => Promise<SgpResult<CoverageCheckAddressData>>;
+    /**
+     * Lists the map gateways the provider can check coverage against: `GET /api/ura/listgatewaymapa`
+     * (no trailing slash), credentials in the query string, no input. The `id` of each entry is the
+     * `gateway` that `coverage.check` takes, so read it here and never assume a value. The route is
+     * not paginated, so the result is SGP's own bare array of `{ id, descricao, gateway }`: no page
+     * envelope, no total. Unknown fields reach `data` unchanged. Only the `id` (a number) and the
+     * `descricao` (text) of each gateway 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`). A read: the
+     * opt-in `maxRetries` may retry it.
+     */
+    listGateways: (options?: CallOptions) => Promise<SgpResult<CoverageListGatewaysData>>;
+}
+/** Operations on maintenance notices (SGP "manutenção", the planned or emergency network works). */
+export interface MaintenanceClient {
+    /**
+     * Lists the maintenance notices: `GET /api/ura/manutencao/list/` (trailing slash), credentials in
+     * the query string, no input and NO FILTER. The route is not paginated, so the result is SGP's
+     * own bare array: no page envelope, no total. It holds EVERY notice, INACTIVE ONES INCLUDED (the
+     * one capture held three past notices, all with `ativa: false`): filter by `ativa` and by the
+     * period (`data_inicial`, `data_final`, `AAAA-MM-DD HH:MM:SS` text) yourself, and by the affected
+     * network elements if you need an area (their lists were empty in the capture, so their content
+     * is unknown). An empty array means no notice.
+     *
+     * Unknown fields reach `data` unchanged. Only the `id` of each notice 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 notices are the provider's announcements; no customer data was seen in the capture (its
+     * equipment lists were empty, and `mensagem_central` is free text). A read: the
+     * opt-in `maxRetries` may retry it.
+     */
+    list: (options?: CallOptions) => Promise<SgpResult<MaintenanceListData>>;
 }
 /** Operations on customers (SGP "clientes"). */
 export interface CustomersClient {
@@ -375,6 +547,11 @@ export interface CustomersClient {
      * `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`).
+     *
+     * The `login` filter (the vendor documents it) matches the exact PPPoE login: observed live, the
+     * exact login listed its customer, a prefix of it and an unknown login listed nothing (`total`
+     * 0). Use it before `preRegistrations.create` to find out whether a login is already taken. The
+     * login is a secret: see `getSensitivity("customers.list")`.
      */
     list: (input?: CustomersListInput, options?: CallOptions) => Promise<SgpResult<CustomersListData>>;
     /**
@@ -513,9 +690,12 @@ export interface PreRegistrationsClient {
      * 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`.
+     * row itself keeps existing afterwards. A success carries SGP's `message` and, when SGP sends
+     * them, the created `new_cliente_id` (a `CustomerId`), `new_contrato_id` and `precadastro_id`,
+     * as numbers (`null` when SGP sends an empty text). They are optional: older records list only
+     * `message`, and the 1.x decoder dropped unknown keys, so whether SGP sent the IDs before is
+     * unknown. When they are absent, read the customer back with `customers.list({ cpfcnpj })`; the
+     * SDK never fabricates them. `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
@@ -527,8 +707,29 @@ export interface PreRegistrationsClient {
      * 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.
+     * SGP stores `cpfcnpj` exactly as sent, and a digits-only document was observed to escape the
+     * duplicate check of `crm.customers.create`. So the SDK sends it in the canonical mask the base
+     * holds: a CPF (`/F`) as `999.999.999-99`, a CNPJ (`/J`, alphanumeric included, uppercased) as
+     * `AA.AAA.AAA/AAAA-99`, whether you give it with or without punctuation. A document in any
+     * other format, or of the other kind than the route, is refused locally (`INVALID_INPUT`,
+     * `error.issues` `["cpfcnpj: expected ..."]`, nothing sent). Format only: the SDK does not verify
+     * the check digits, but SGP does for a CPF: a CPF with wrong digits is refused with HTTP 400
+     * `{ message: "CPF inválido", error: "Requisição inválida." }`, which is `REJECTED` with
+     * `error.reason === "DOCUMENT_INVALID"` and effect `"none"` (observed live on `/F`, and a
+     * read-back showed nothing created; `error.sgp` carries the `error` text, the `message` stays in
+     * `response.body`). The check digits of a CNPJ were never tested.
+     *
+     * A PPPoE `login` already in use is refused with HTTP 400 `{ message: "Login <login> já existe",
+     * error: "Requisição inválida." }` (exactly those two text keys), which is `REJECTED` with
+     * `error.reason === "LOGIN_ALREADY_REGISTERED"` and effect `"none"` (observed once on `/F`, and a
+     * read-back showed nothing created). `error.sgp` carries the `error` text only: the `message`
+     * echoes the login you sent and stays in `response.body`; the SDK copies it into no error field.
+     * Any other 400 keeps no reason. The refusal is not a complete guard: read
+     * `customers.list({ login })` BEFORE creating, to learn whether the login is taken and by whom.
+     *
+     * Evidence: only `/F` was exercised. The 200 body was seen live with `message` and the three IDs;
+     * older records list only `message` (the 1.x decoder dropped unknown keys, so whether the IDs
+     * were sent before is unknown). `/J` follows the vendor's documentation.
      */
     create: (input: PreRegistrationCreateInput, options?: CallOptions) => Promise<SgpResult<PreRegistrationCreateData>>;
     /**
@@ -538,8 +739,8 @@ export interface PreRegistrationsClient {
      * 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.
+     * `response`). `gateway.id` and `gateway.gateway_id` are a `number` or `null`: SGP sends `""` for a
+     * plan without a gateway and numeric text (or a number) otherwise; `""` is `null`, never `0`.
      *
      * 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
@@ -594,6 +795,43 @@ export interface WorkOrdersClient {
      * read: the opt-in `maxRetries` may retry it.
      */
     list: (input?: WorkOrdersListInput, options?: CallOptions) => Promise<SgpResult<WorkOrdersListData>>;
+    /**
+     * Reads one work order in full: `POST /api/os/list/id/{id}` (NO trailing slash), `multipart/form-data`
+     * without files, credentials only. `id` is a positive integer, refused locally otherwise.
+     *
+     * The result is ONE flat object (72 fields observed) mixing the work order (`os_*`), the customer,
+     * contract, address, plan and service. The vendor's collection shows a one-element array; SGP
+     * sent the bare object, and that is what `data` is. Unknown fields reach `data` unchanged. Only
+     * `os_id` must be a number; any other field of the wrong type is left out of `data` and reported
+     * in `warnings` (the original stays in `response`). Normalized: SGP sends `servico_id`,
+     * `contrato_status_id` and `os_setor_id` as text, and `data` carries each as a `number` (`null`
+     * for an empty text, never `0`; text that is not a plain number is left out with a warning). SGP
+     * pads `contrato_status` with a leading space and `data` carries it trimmed.
+     *
+     * WARNING: THE OBJECT HOLDS PLAINTEXT CREDENTIALS. `servico_password` (the service's password),
+     * `servico_login`, `wan_user`, `wan_password`, `wifi_ssid`, `wifi_password`, `wifi_ssid_5` and
+     * `wifi_password_5`, plus the MAC and IP of the service and the NAS IP, are SECRET; the customer's
+     * name, e-mail, contacts and address (and the coordinates), the free text of the work order and
+     * the people involved are PERSONAL. See `getSensitivity("workOrders.get")`, project with `pick`
+     * and log `toSafeLog(result)`, never the result. The Wi-Fi and WAN keys were empty in the one
+     * capture; they are classified as secret anyway. A read: the opt-in `maxRetries` may retry it.
+     */
+    get: (input: WorkOrdersGetInput, options?: CallOptions) => Promise<SgpResult<WorkOrdersGetData>>;
+    /**
+     * Lists the comments of a work order: `GET /api/os/{id}/comentario/list/` (trailing slash),
+     * credentials in the query string. `id` is a positive integer, refused locally otherwise. The
+     * route is not paginated, so the result is SGP's own bare array: no page envelope, no total. An
+     * empty array means no comment.
+     *
+     * DOCUMENTED ONLY: the one live read returned `[]`, so the item fields (`comentario_id`,
+     * `comentario`, `usuario`, `data_cadastro`, `checklist_id`, `checklist_descricao`,
+     * `usuario_setores`) come from the vendor's collection and were never seen. Nothing is required
+     * of an item beyond being an object (an element that is not an object fails the response:
+     * `INVALID_RESPONSE`); any known field of the wrong type is left out of `data` and reported in
+     * `warnings`. The comment text and its author are personal data: see
+     * `getSensitivity("workOrders.listComments")`. A read: the opt-in `maxRetries` may retry it.
+     */
+    listComments: (input: WorkOrdersListCommentsInput, options?: CallOptions) => Promise<SgpResult<WorkOrdersListCommentsData>>;
     /**
      * 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
@@ -629,14 +867,37 @@ export interface ServicesClient {
      * before sending again.
      */
     changePlan: (input: ServiceChangePlanInput, options?: CallOptions) => Promise<SgpResult<ServiceChangePlanData>>;
+    /**
+     * Adds a service of the generic type to a contract: `POST /api/servico/generico` (no trailing
+     * slash), `multipart/form-data` without files, the route TSMX recommends for extra services of
+     * that type. Never retried. TSMX says a generic plan has no billing effect (it only sets the service type);
+     * not verified.
+     *
+     * `planobase_id` must be a plan created as "generic" in the SGP panel (a `PlanId`; whether the
+     * URA catalog `plans.list` shows it is not confirmed). SGP refuses any other plan type with HTTP
+     * 400 `{ error: "Plano informado não é do tipo genérico." }`, which is `REJECTED` with
+     * `error.reason === "PLAN_NOT_GENERIC"` and effect `"none"` (a read-back after the observed
+     * refusal showed nothing added; its raw body was not captured). That refusal is the only
+     * exchange observed: this provider has no generic plan, so a success was never seen. It is
+     * documented, not observed, and `data` is the JSON object SGP sends, kept as received with no
+     * field assumed (in particular, the new service's id is not guaranteed). A 2xx that is not a JSON
+     * object is `INVALID_RESPONSE` with effect `"unknown"`. Only `descricao` among the optional fields
+     * was sent (in the refused call); the others are documented by the vendor and never sent.
+     *
+     * Other failures carry `error.effect` by the same rules as `services.changePlan`. On
+     * `"unknown"`, read the contract's services (`customers.list`) before sending again: a second
+     * call may add a duplicate service.
+     */
+    addGeneric: (input: ServiceAddGenericInput, options?: CallOptions) => Promise<SgpResult<ServiceAddGenericData>>;
     /**
      * 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`
+     * success (HTTP 201) returns the new `servico_id` (a number); `clientecontrato_id` is a `number` (SGP sends it as
+     * text; `null` for an empty text, and text that is not a plain number is left out of `data` with a
+     * warning, the original stays in `response`). 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
@@ -650,12 +911,26 @@ export interface ServicesClient {
      * duplicate service.
      */
     addTv: (input: ServiceAddTvInput, options?: CallOptions) => Promise<SgpResult<ServiceAddTvData>>;
+    /**
+     * Removes a generic service: `DELETE /api/servico/generico/{servico_id}` (no trailing slash),
+     * with the contract in a `multipart/form-data` body (without files), as SGP expects. Never
+     * retried.
+     *
+     * Documented by the vendor, never observed: no generic service was ever created, so none could
+     * be removed. The vendor documents that the route does not remove the only service of a contract;
+     * no SGP body for that refusal was captured, so it has no `reason` and, like any other failure,
+     * carries `error.effect` by the same rules as `services.changePlan`. A success is the JSON object
+     * SGP sends, kept as received with no field assumed; a 2xx that is not a JSON object is
+     * `INVALID_RESPONSE` with effect `"unknown"`. On `"unknown"`, read the contract's services
+     * (`customers.list`) before sending again.
+     */
+    removeGeneric: (input: ServiceRemoveGenericInput, options?: CallOptions) => Promise<SgpResult<ServiceRemoveGenericData>>;
     /**
      * 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
+     * A success returns SGP's `msg`, the removed `servico_id` and `clientecontrato_id` (a `number`: SGP
+     * sends it as text, and `null` for an empty text). 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.
      */
@@ -681,6 +956,8 @@ export interface SgpClient {
     experimental: ExperimentalClient;
     /** Operations on invoices. */
     invoices: InvoicesClient;
+    /** Operations on maintenance notices. */
+    maintenance: MaintenanceClient;
     /** Operations on occurrences. */
     occurrences: OccurrencesClient;
     /** Operations on plans. */

package/dist/constants.d.ts

@@ -41,6 +41,19 @@ export declare const CONTRACT_STATUS: {
 };
 /** A known contract-status code. Operations accept any number: SGP decides what it takes. */
 export type ContractStatus = (typeof CONTRACT_STATUS)[keyof typeof CONTRACT_STATUS];
+/**
+ * The `status` of an item that `contracts.checkConnection` returns: SGP's verdict on a connection.
+ * 1 (online) and 2 (offline) were observed; 0 (nothing checked) and 9 (maintenance) come from the
+ * vendor's documentation and were never seen. The data carries any number: SGP may send others.
+ */
+export declare const CONNECTION_STATUS: {
+    readonly notChecked: 0;
+    readonly online: 1;
+    readonly offline: 2;
+    readonly maintenance: 9;
+};
+/** A known connection-status code. `status` may be any number: compare, do not assume. */
+export type ConnectionStatus = (typeof CONNECTION_STATUS)[keyof typeof CONNECTION_STATUS];
 /**
  * SGP's service types, the `servico_tipo` that `services.changePlan` sends. Only internet (1) was
  * exercised against SGP: the vendor documents other types but no value beyond 1 was ever sent, so

package/dist/document.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+/** INTERNAL. Validation of the `cpfcnpj` of a `/F` write: the canonical CPF, or a refusal on the field. */
+export declare const storedCpfSchema: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+/** INTERNAL. Validation of the `cpfcnpj` of a `/J` write: the canonical CNPJ, or a refusal on the field. */
+export declare const storedCnpjSchema: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+/**
+ * `["cpfcnpj: expected ..."]` when a failed parse broke the `cpfcnpj` field of a `/F` or `/J` input
+ * (wrong format, wrong kind for the route, or missing where required), otherwise no issues. The
+ * message is the one the field's schema raised; it never carries the value.
+ */
+export declare const documentIssues: (error: z.ZodError) => readonly string[] | undefined;

package/dist/index.d.ts

@@ -1,21 +1,25 @@
 export type { SgpAddress } from "./address.js";
-export type { CatalogsClient, ContractsClient, CoverageClient, CrmClient, CrmContractsClient, CrmCustomersClient, CustomersClient, DocumentsClient, ExperimentalAnnotationsClient, ExperimentalClient, InvoicesClient, OccurrencesClient, PlansClient, PreRegistrationsClient, ServicesClient, SgpClient, WorkOrdersClient, } from "./client.js";
+export type { CatalogsClient, ContractsClient, CoverageClient, CrmClient, CrmContractsClient, CrmCustomersClient, CustomersClient, DocumentsClient, ExperimentalAnnotationsClient, ExperimentalClient, InvoicesClient, MaintenanceClient, OccurrencesClient, PlansClient, PreRegistrationsClient, ServicesClient, SgpClient, WorkOrdersClient, } from "./client.js";
 export { createSgpClient } from "./client.js";
 export type { CallOptions, ClientOptions, Credentials, ErrorHookMetadata, FetchLike, HookMetadata, Hooks, ResponseHookMetadata, TokenCredentials, } from "./config.js";
 export { DEFAULT_TIMEOUT_MS, InvalidConfigurationError, MAX_TIMEOUT_MS } from "./config.js";
-export type { AcquisitionMode, BillingMethod, ContractStatus, CrmStatus, ServiceType, } from "./constants.js";
-export { ACQUISITION_MODE, BILLING_METHOD, CONTRACT_STATUS, CRM_STATUS, SERVICE_TYPE, } from "./constants.js";
+export type { AcquisitionMode, BillingMethod, ConnectionStatus, ContractStatus, CrmStatus, ServiceType, } from "./constants.js";
+export { ACQUISITION_MODE, BILLING_METHOD, CONNECTION_STATUS, CONTRACT_STATUS, CRM_STATUS, SERVICE_TYPE, } from "./constants.js";
 export type { CustomerId } from "./ids.js";
 export type { OperationName } from "./operation-sensitivity.js";
 export { getSensitivity } from "./operation-sensitivity.js";
 export type { CatalogsListBillingProfilesData } from "./operations/catalogs-list-billing-profiles.js";
 export type { CatalogsListNasData } from "./operations/catalogs-list-nas.js";
 export type { CatalogsListPopsData } from "./operations/catalogs-list-pops.js";
+export type { ContractsCheckConnectionData, ContractsCheckConnectionInput, } from "./operations/contracts-check-connection.js";
 export type { ContractsListData, ContractsListInput } from "./operations/contracts-list.js";
+export type { ContractsListServicesData, ContractsListServicesInput, } from "./operations/contracts-list-services.js";
 export type { ContractsListStatusReasonsData } from "./operations/contracts-list-status-reasons.js";
 export type { ContractUpdateData, ContractUpdateInput } from "./operations/contracts-update.js";
 export type { ContractUpdateStatusData, ContractUpdateStatusInput, } from "./operations/contracts-update-status.js";
 export type { CoverageCheckData, CoverageCheckInput, CoverageCto, } from "./operations/coverage-check.js";
+export type { CoverageCheckAddressData, CoverageCheckAddressInput, } from "./operations/coverage-check-address.js";
+export type { CoverageListGatewaysData } from "./operations/coverage-list-gateways.js";
 export type { CrmContractCreateData, CrmContractCreateInput, } from "./operations/crm-contracts-create.js";
 export type { CrmContractCreateByCpfCnpjData, CrmContractCreateByCpfCnpjInput, } from "./operations/crm-contracts-create-by-cpf-cnpj.js";
 export type { CrmContractsListData, CrmContractsListInput, } from "./operations/crm-contracts-list.js";
@@ -27,7 +31,9 @@ export type { DocumentAddInput, DocumentFile } from "./operations/documents-add.
 export type { DocumentsListData, DocumentsListInput } from "./operations/documents-list.js";
 export type { ExperimentalAnnotation, ExperimentalAnnotationsListData, ExperimentalAnnotationsListInput, } from "./operations/experimental-annotations-list.js";
 export type { InvoicesListData, InvoicesListInput } from "./operations/invoices-list.js";
+export type { MaintenanceListData } from "./operations/maintenance-list.js";
 export type { OccurrenceCreateData, OccurrenceCreateInput, } from "./operations/occurrences-create.js";
+export type { OccurrencesListData, OccurrencesListInput, } from "./operations/occurrences-list.js";
 export type { OccurrencesListMethodsData } from "./operations/occurrences-list-methods.js";
 export type { OccurrencesListTypesData } from "./operations/occurrences-list-types.js";
 export type { PlanId, PlansListData } from "./operations/plans-list.js";
@@ -35,10 +41,14 @@ export type { PreRegistrationCreateCompanyInput, PreRegistrationCreateData, PreR
 export type { PreRegistrationsListDueDaysData } from "./operations/pre-registrations-list-due-days.js";
 export type { PreRegistrationsListPlansData } from "./operations/pre-registrations-list-plans.js";
 export type { PreRegistrationsListSellersData } from "./operations/pre-registrations-list-sellers.js";
+export type { ServiceAddGenericData, ServiceAddGenericInput, } from "./operations/services-add-generic.js";
 export type { ServiceAddTvData, ServiceAddTvInput } from "./operations/services-add-tv.js";
 export type { ServiceChangePlanData, ServiceChangePlanInput, } from "./operations/services-change-plan.js";
+export type { ServiceRemoveGenericData, ServiceRemoveGenericInput, } from "./operations/services-remove-generic.js";
 export type { ServiceRemoveTvData, ServiceRemoveTvInput, } from "./operations/services-remove-tv.js";
+export type { WorkOrdersGetData, WorkOrdersGetInput } from "./operations/work-orders-get.js";
 export type { WorkOrdersListData, WorkOrdersListInput, } from "./operations/work-orders-list.js";
+export type { WorkOrdersListCommentsData, WorkOrdersListCommentsInput, } from "./operations/work-orders-list-comments.js";
 export type { WorkOrdersListReasonsData } from "./operations/work-orders-list-reasons.js";
 export type { RawRequestInput } from "./raw-request.js";
 export type { CapturedResponse, Diagnostic, Effect, ResponseBody, ResultBase, SchemaWarning, SgpError, SgpErrorCode, SgpErrorFields, SgpFailure, SgpResult, SgpSuccess, } from "./result.js";