sgp-sdk 1.2.0 → 2.0.0-beta.2

package/dist/operation.d.ts

@@ -0,0 +1,145 @@
+import type { Exposure } from "./exposure.js";
+import type { ResponseBody, SchemaWarning } from "./result.js";
+import type { OperationSensitivity } from "./sensitivity.js";
+/**
+ * How a request body is encoded; the executor switches on it. `form` is `multipart/form-data`
+ * without files: every param is a text field and the content-type (with its boundary) is left to
+ * `fetch`.
+ */
+export type Encoding = "json" | "form";
+/**
+ * The encodings an operation may declare: {@link Encoding} plus `form-files`, `multipart/form-data`
+ * with file parts next to the text fields (the file parts come from `RequestBuild.files`). Only
+ * typed operations use it: `request()` takes {@link Encoding}.
+ */
+type OperationEncoding = Encoding | "form-files";
+/** A file sent as one part of a `form-files` body. */
+export interface FilePart {
+    /** The bytes of the file: a `Blob`, raw bytes or an `ArrayBuffer`, sent as they are. */
+    data: Blob | Uint8Array | ArrayBuffer;
+    /** Name SGP sees for the part. */
+    filename: string;
+    /** MIME type of the part. Defaults to the `type` of a `Blob`; none for raw bytes. */
+    contentType?: string;
+}
+/** The fields every operation has, read or write. */
+interface OperationFields<Data, Name extends string> {
+    /** Public name, e.g. `customers.list`; also the `operation` of hooks and errors. */
+    name: Name;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Path template starting with `/`; `{name}` placeholders are filled from `pathParams`. */
+    pathTemplate: string;
+    /**
+     * Hook metadata leaves out `pathTemplate`: for a call whose path is a literal chosen by the
+     * caller (`request()`), not a template. Absent means the template is shown.
+     */
+    omitPathFromHooks?: boolean;
+    /** Body encoding of POST/PUT/DELETE. A GET has no body: its params go in the query string. */
+    encoding: OperationEncoding;
+    /** Validates the raw input and builds the request. No I/O. */
+    buildRequest: (input: unknown) => RequestBuild;
+    /**
+     * Recognizes a 2xx body that is a known refusal (a 200 that did not do what was asked). Pure.
+     * `undefined` when the body is not a refusal.
+     */
+    detectRefusal?: (body: ResponseBody) => Refusal | undefined;
+    /** Checks a 2xx body against the contract the method promises. Pure, no I/O. */
+    decode: (body: ResponseBody) => DecodeOutcome<Data>;
+    /**
+     * Secret and personal keys of the request and of the 2xx body, per item path. Required: the
+     * single source `getSensitivity` reads. A definition with nothing sensitive says
+     * `{ input: [], output: [] }`.
+     */
+    sensitivity: OperationSensitivity;
+    /**
+     * For an operation whose response mixes records outside the requested scope: the executor
+     * withholds the body and keeps only message strings in `error.sgp`, on every status and path,
+     * before it builds any public object. Absent means the body is the evidence, as everywhere else.
+     */
+    exposure?: Exposure;
+}
+/**
+ * INTERNAL. An operation is data plus a few small pure functions; the executor does everything else.
+ * Not exported from the package: consumers only see the client methods, their types and options.
+ *
+ * A read may be `repeatable` (the retry gate of the operation contract; absent means `false`). A write, marked by
+ * `write`, carries an `effect` on every failure and is never repeatable: the type forbids
+ * `repeatable: true` next to `write`, and the executor refuses such a definition.
+ */
+export type OperationDefinition<Data, Name extends string = string> = (OperationFields<Data, Name> & {
+    repeatable?: boolean;
+    write?: undefined;
+}) | (OperationFields<Data, Name> & {
+    repeatable?: false;
+    write: WriteSpec;
+});
+/** What a write declares about itself on top of the default effect rules of the operation contract. */
+export interface WriteSpec {
+    /**
+     * Every failure after a request was sent has effect `unknown`, whatever the status and body say:
+     * for a call the SDK does not interpret (`request()`), where no rejection is known to apply
+     * nothing. Absent means the default rules of the operation contract.
+     */
+    effectUnknownAfterSend?: boolean;
+    /**
+     * Remote rejections this operation is proven to apply no effect for, whatever their body shape
+     * (in particular SGP's generic `errors` array, which is `unknown` by default). Declare one only
+     * with captured evidence for this operation.
+     */
+    knownRejections?: readonly KnownRejection[];
+}
+/** A remote 4xx known to leave the requested change unapplied. Gives the failure its `reason`. */
+export interface KnownRejection {
+    /** HTTP status of the rejection. Must be 4xx: any other status is never matched. */
+    status: number;
+    /** Recognizes the rejection from the body. Pure; must say `false` for a body it cannot read. */
+    matches: (body: ResponseBody) => boolean;
+    /** Value of `SgpError.reason`. */
+    reason: string;
+}
+/** What `buildRequest` returns: the request to send, or the first problem with the input. */
+export type RequestBuild = {
+    ok: true;
+    /** Values for the `{name}` placeholders of the path template. */
+    pathParams?: Readonly<Record<string, string | number>>;
+    /**
+     * Request fields: the body for POST/PUT/DELETE, the query string for GET. `undefined` values
+     * are omitted. A GET or a `form` body takes primitives only (a `json` body takes any value).
+     */
+    params?: Readonly<Record<string, unknown>>;
+    /**
+     * Fields that go in the URL of a request that has a body (POST/PUT/DELETE), after the path;
+     * `params` and the credentials stay in the body. Primitives only, `undefined` omitted, never
+     * `token` or `app`. A GET puts everything in its query string already: a GET with `query` is
+     * refused (`INVALID_INPUT`).
+     */
+    query?: Readonly<Record<string, unknown>>;
+    /** File parts by field name; only a `form-files` body sends them, after the text fields. */
+    files?: Readonly<Record<string, FilePart>>;
+} | {
+    ok: false;
+    problem: string;
+    /** Value-free issues (field path, then what was expected) that become `error.issues`. */
+    issues?: readonly string[];
+};
+/**
+ * A recognized refusal inside a 2xx response. `effect: "none"` only with a read-back that showed
+ * nothing was created; absent, the effect of a write stays `unknown`.
+ */
+export interface Refusal {
+    reason?: string;
+    effect?: "none";
+}
+/**
+ * Result of checking a 2xx body. `warnings` lists the non-essential fields the decoder had to drop
+ * from `data`; it is absent when nothing was dropped.
+ */
+export type DecodeOutcome<Data> = {
+    ok: true;
+    data: Data;
+    warnings?: readonly SchemaWarning[];
+} | {
+    ok: false;
+    issues: readonly string[];
+};
+export {};

package/dist/operations/catalogs-list-billing-profiles.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const billingProfilesSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    descricao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    codigo_banco: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `GET /api/ura/portador/`, in SGP's own shape: a bare array with one entry per
+ * billing profile (SGP "portador"). The route is not paginated, so there is no envelope and no
+ * total.
+ */
+export type CatalogsListBillingProfilesData = z.output<typeof billingProfilesSchema>;
+/** INTERNAL definition of `catalogs.listBillingProfiles`. */
+export declare const catalogsListBillingProfiles: OperationDefinition<CatalogsListBillingProfilesData, "catalogs.listBillingProfiles">;
+export {};

package/dist/operations/catalogs-list-nas.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const nasListSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    descricao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    identificador: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_ip: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    ativo: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+    pops: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        cidade: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        uf: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        codigo_ibge: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        ativo: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$loose>>>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/ura/nas/list/`, in SGP's own shape: a bare array with one entry per
+ * NAS (network access server) and the POPs each one serves. The route is not paginated, so there is
+ * no envelope and no total.
+ */
+export type CatalogsListNasData = z.output<typeof nasListSchema>;
+/** INTERNAL definition of `catalogs.listNas`. */
+export declare const catalogsListNas: OperationDefinition<CatalogsListNasData, "catalogs.listNas">;
+export {};

package/dist/operations/catalogs-list-pops.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const popsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    pop: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/ura/pops/`, in SGP's own shape: a bare array with one entry per POP
+ * (point of presence). The route is not paginated, so there is no envelope and no total.
+ */
+export type CatalogsListPopsData = z.output<typeof popsSchema>;
+/** INTERNAL definition of `catalogs.listPops`. */
+export declare const catalogsListPops: OperationDefinition<CatalogsListPopsData, "catalogs.listPops">;
+export {};

package/dist/operations/contracts-check-connection.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const connectionsSchema: z.ZodArray<z.ZodObject<{
+    status: z.ZodNumber;
+    msg: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    servico_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    contratoId: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    login: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    razaoSocial: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    cpfCnpj: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The verdict of SGP on a contract's connection: ALWAYS an array, one item per internet service
+ * (`status`, `msg`, and the service, contract and holder it speaks of). SGP's answer varies: an
+ * array, `[]` when the contract is outside its default filter (observed on a suspended contract
+ * without `status_all`), or ONE bare object (observed on an active contract without `status_all`).
+ * The SDK wraps the bare object, so a consumer reads one shape; `response.body` keeps what SGP sent,
+ * and the paths of `warnings` and `issues` refer to the array form (`[0].login`). `[]` is not
+ * "offline": it means SGP gave no verdict (try `status_all: 1`).
+ */
+export type ContractsCheckConnectionData = z.output<typeof connectionsSchema>;
+/**
+ * Input of `contracts.checkConnection`, named as SGP names the fields. At least one of `contrato`
+ * and `telefone`. `protocolo_ura` is NOT offered: it explicitly asks SGP to open an occurrence (use
+ * `occurrences.create`).
+ */
+export interface ContractsCheckConnectionInput {
+    /** Exercised. The contract to check. */
+    contrato?: number;
+    /** Documented, never sent. The phone of the customer, instead of the contract. */
+    telefone?: string;
+    /**
+     * Exercised. Also checks the contracts the default filter leaves out (suspended ones): without it a
+     * suspended contract answered `[]`. Sent as `1`.
+     */
+    status_all?: 1;
+    /** Documented, never sent. SGP's status filter; its accepted values are not documented. */
+    status_filter?: string;
+    /** Documented, never sent. SGP's URA contact; its meaning and format are not documented. */
+    uracontato?: string;
+}
+/** INTERNAL. Validation of the input, exported so a test can check its keys are classified. */
+export declare const contractsCheckConnectionInputSchema: z.ZodObject<{
+    contrato: z.ZodOptional<z.ZodNumber>;
+    telefone: z.ZodOptional<z.ZodString>;
+    status_all: z.ZodOptional<z.ZodLiteral<1>>;
+    status_filter: z.ZodOptional<z.ZodString>;
+    uracontato: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * INTERNAL definition of `contracts.checkConnection`. A WRITE, though it looks like a read: the
+ * vendor documents that, under an active maintenance, SGP opens an occurrence by default, even
+ * without `protocolo_ura` (never tested). So it is never retried and its failures carry an effect.
+ */
+export declare const contractsCheckConnection: OperationDefinition<ContractsCheckConnectionData, "contracts.checkConnection">;
+export {};

package/dist/operations/contracts-list-services.d.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { type CustomerId } from "../ids.js";
+import type { OperationDefinition } from "../operation.js";
+declare const rowsSchema: z.ZodArray<z.ZodObject<{
+    servico_id: z.ZodPipe<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>, z.ZodNumber>;
+    servico_tipo: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    servico_login: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    servico_password: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    servico_mac: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    servico_online: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+    nas_ip: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    servicos: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodUnknown>>>;
+    contrato_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    contrato_status: z.ZodNullable<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    contrato_status_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    contrato_status_data: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    contrato_cadastro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    contrato_pop_id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    contrato_pop_nome: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    contrato_endereco_ll: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    cliente_id: z.ZodNullable<z.ZodOptional<z.core.$ZodBranded<z.ZodNumber, "CustomerId", "out">>>;
+    cliente_nome: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    cliente_email: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    cliente_contato: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    endereco_logradouro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_numero: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>>;
+    endereco_complemento: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_bairro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_cidade: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_uf: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_pontoreferencia: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    endereco_ll: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    plano_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    plano: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    plano_download: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    plano_upload: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    os_servicoprestado: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_username: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_ip: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_mac: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_nasipaddress: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_nasportid: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_nasporttype: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_calledstationid: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_acctsessionid: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_radacctid: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    rad_dataconexao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_tempo: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_tempo_ordem: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    rad_acctinputoctets: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    rad_acctoutputoctets: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    rad_framedprotocol: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_framedipv6prefix: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    rad_delegatedipv6prefix: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/suporte/contrato/list/`, in SGP's own shape: a bare array with ONE ROW
+ * PER SERVICE (internet and TV) of the matching contracts, each repeating the customer, contract,
+ * address and plan. `[]` when nothing matches. A row of an ONLINE internet service also carries the
+ * RADIUS session (`rad_*`: user, IP, MAC, NAS, session ids, connection time, octet counters).
+ *
+ * Normalized: `servico_id`, `contrato_id`, `contrato_status_id`, `contrato_pop_id`,
+ * `rad_radacctid`, `rad_tempo_ordem`, `rad_acctinputoctets` and `rad_acctoutputoctets` are numbers
+ * (SGP sends the first four as text); `contrato_status` is trimmed (SGP pads it with spaces). The
+ * row's `servico_id` is an invariant: a row without a numeric one is `INVALID_RESPONSE`.
+ *
+ * It holds PLAINTEXT CREDENTIALS and network identifiers (`servico_password`, `servico_login`,
+ * MACs, IPs, NAS, session ids): see `getSensitivity("contracts.listServices")` and project with
+ * `pick` before logging or handing it on.
+ */
+export type ContractsListServicesData = z.output<typeof rowsSchema>;
+/**
+ * Filters of `contracts.listServices`, named as SGP names them (the vendor's collection documents
+ * all five). All optional, as the vendor marks none as required.
+ *
+ * At least one filter is required: without one SGP lists the services of EVERY customer, with
+ * plaintext service passwords, so the SDK refuses the call locally (`INVALID_INPUT`, `attempts` 0,
+ * nothing sent). There is no paging input. Filter by `contrato_id` whenever you can. Text filters are sent as given; SGP decides how it matches them.
+ */
+export interface ContractsListServicesInput {
+    /** Exercised. Only the services of this contract (the `contrato_id` of a row, a number). */
+    contrato_id?: number;
+    /** Exercised. Only the services of the customer with this id (a `CustomerId`, never a contract id). */
+    cliente_id?: CustomerId;
+    /** Documented, never sent. Only the customer with this name. */
+    cliente_nome?: string;
+    /** Documented, never sent. Only the customer with this CPF/CNPJ. */
+    cliente_cpfcnpj?: string;
+    /** Documented, never sent. Only the service with this login. */
+    servico_login?: string;
+}
+/** INTERNAL. Validation of the input, exported so a test can check its keys are classified. */
+export declare const contractsListServicesInputSchema: z.ZodObject<{
+    contrato_id: z.ZodOptional<z.ZodNumber>;
+    cliente_id: z.ZodOptional<z.core.$ZodBranded<z.ZodNumber, "CustomerId", "out">>;
+    cliente_nome: z.ZodOptional<z.ZodString>;
+    cliente_cpfcnpj: z.ZodOptional<z.ZodString>;
+    servico_login: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** INTERNAL definition of `contracts.listServices`. */
+export declare const contractsListServices: OperationDefinition<ContractsListServicesData, "contracts.listServices">;
+export {};

package/dist/operations/contracts-list-status-reasons.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const statusReasonsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    motivo: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/ura/contrato/status/motivos/`, in SGP's own shape: a bare array of
+ * `{ id, motivo }`, one entry per reason the provider can register with a status change. Each
+ * provider has its own list. The route is not paginated, so there is no envelope and no total.
+ */
+export type ContractsListStatusReasonsData = z.output<typeof statusReasonsSchema>;
+/** INTERNAL definition of `contracts.listStatusReasons`. */
+export declare const contractsListStatusReasons: OperationDefinition<ContractsListStatusReasonsData, "contracts.listStatusReasons">;
+export {};

package/dist/operations/contracts-list.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+import type { PlanId } from "./plans-list.js";
+declare const contractsSchema: z.ZodArray<z.ZodObject<{
+    id_contrato: z.ZodNumber;
+    id_cliente: z.core.$ZodBranded<z.ZodNumber, "CustomerId", "out">;
+    status: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    pop_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    nome: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    cpfcnpj: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    email: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    telefone: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    data_status: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    data_cadastro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    motivo_status: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/ura/listacontrato/`, in SGP's own shape: a bare array with one summary
+ * per matching contract. The route is not paginated, so there is no `paginacao`, no total and no
+ * envelope. An empty array means no contract matched.
+ */
+export type ContractsListData = z.output<typeof contractsSchema>;
+/** Filters of `contracts.list`, named as SGP names them. All optional. */
+export interface ContractsListInput {
+    /** Only the contract with this id. */
+    contrato?: number;
+    /**
+     * Only contracts linked to this plan. The id comes from `plans.list` (the catalog of existing
+     * services and contracts), never from `preRegistrations.listPlans`.
+     */
+    plano?: PlanId;
+    /** Person type, as SGP names it (see SGP's public documentation for the values). */
+    tipo?: string;
+    /** Contract status code (see `CONTRACT_STATUS`; any number is sent). */
+    status?: number;
+    /**
+     * Ask SGP to include the address. The address fields were never captured: they reach `data` as
+     * received but untyped, and they are personal data (see `getSensitivity`; use `pick`).
+     */
+    exibir_endereco?: boolean;
+}
+/** INTERNAL. Validation of the input, exported so a test can check its keys are classified. */
+export declare const contractsListInputSchema: z.ZodObject<{
+    contrato: z.ZodOptional<z.ZodNumber>;
+    plano: z.ZodOptional<z.ZodNumber>;
+    tipo: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    exibir_endereco: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** INTERNAL definition of `contracts.list`. */
+export declare const contractsList: OperationDefinition<ContractsListData, "contracts.list">;
+export {};

package/dist/operations/contracts-update-status.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+/**
+ * Input of `contracts.updateStatus`, named as SGP names the fields. Both codes are sent as given:
+ * SGP decides what it takes and which transitions it allows.
+ */
+export interface ContractUpdateStatusInput {
+    /** Exercised. ID of the contract (the `id` of `customers.list` -> `contratos[]`). */
+    contrato: number;
+    /** Exercised with 1 and 4. Status code to move to (`CONTRACT_STATUS`); any number is sent. */
+    status: number;
+    /**
+     * Documented, always sent in observed calls (1 and 5); a call without it was never exercised.
+     * ID of the reason (motivo de status) registered with the change. The list is the provider's
+     * own: read it with `contracts.listStatusReasons`, never assume a value. Omitted: no `motivo`
+     * is sent.
+     */
+    motivo?: number;
+}
+/** INTERNAL. Validation of the input, exported so a test can check it against the public type. */
+export declare const contractsUpdateStatusInputSchema: z.ZodObject<{
+    contrato: z.ZodNumber;
+    status: z.ZodNumber;
+    motivo: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * Success body of `POST /api/ura/contrato/status/edit/`: SGP's `resposta`, which names the contract
+ * and the status it is in now. Other keys SGP may add are kept.
+ */
+declare const statusChangedSchema: z.ZodObject<{
+    resposta: z.ZodObject<{
+        mensagem: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        contrato: z.ZodNumber;
+        contrato_status: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/** Response of `contracts.updateStatus`. */
+export type ContractUpdateStatusData = z.output<typeof statusChangedSchema>;
+/** INTERNAL definition of `contracts.updateStatus`. */
+export declare const contractsUpdateStatus: OperationDefinition<ContractUpdateStatusData, "contracts.updateStatus">;
+export {};

package/dist/operations/contracts-update.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+/**
+ * Input of `contracts.update`. Only the field whose format and behavior are known is accepted: the
+ * other keys the vendor documents (`portador`, `debito_*`, `sms_desativado`, `tag_add`,
+ * `tag_remove`) have no known types, so they stay reachable through `request()` until documented.
+ */
+export interface ContractUpdateInput {
+    /** Exercised. ID of the contract (the `id` of `customers.list` -> `contratos[]`). */
+    contrato: number;
+    /**
+     * Exercised with 3 and 1. Billing-method code (`BILLING_METHOD`: 1 boleto, 2 automatic debit, 3
+     * booklet, 4 recurring charge, 6 PIX); any number is sent as given. Code 5 appears in SGP's panel
+     * select for this route only and was never confirmed, so it has no constant. Changing it changes
+     * how the contract is billed.
+     */
+    forma_cobranca: number;
+}
+/** INTERNAL. Validation of the input, exported so a test can check it against the public type. */
+export declare const contractsUpdateInputSchema: z.ZodObject<{
+    contrato: z.ZodNumber;
+    forma_cobranca: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Success body of `POST /api/ura/contrato/edit/`: SGP's `resposta`, with the contract and the list
+ * of fields SGP says it applied (`alterados`, returned as-is). Other keys SGP may add are kept.
+ */
+declare const contractUpdatedSchema: z.ZodObject<{
+    resposta: z.ZodObject<{
+        mensagem: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        contrato: z.ZodNumber;
+        alterados: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/** Response of `contracts.update`. */
+export type ContractUpdateData = z.output<typeof contractUpdatedSchema>;
+/** INTERNAL definition of `contracts.update`. */
+export declare const contractsUpdate: OperationDefinition<ContractUpdateData, "contracts.update">;
+export {};

package/dist/operations/coverage-check-address.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+/**
+ * Input of `coverage.checkAddress`, named as SGP names the fields. The vendor's collection says
+ * "use one of the filters", so at least one is required, or the call is refused locally
+ * (`INVALID_INPUT`, nothing sent). How filters combine is SGP's decision: only `cep` alone and
+ * `cidade` alone were exercised.
+ */
+export interface CoverageCheckAddressInput {
+    /** Exercised. Postal code, as SGP keeps it (digits only in the capture). */
+    cep?: string;
+    /** Exercised. City name, as SGP spells it (upper case in the capture). */
+    cidade?: string;
+    /** Documented, never sent. Street. */
+    logradouro?: string;
+    /** Documented, never sent. Neighborhood. */
+    bairro?: string;
+    /** Documented, never sent. Lowest street number to include (the vendor: "from a street number"). */
+    numero_inicial?: number | string;
+    /** Documented, never sent. Highest street number to include (the vendor: "up to a street number"). */
+    numero_final?: number | string;
+}
+/** INTERNAL. Validation of the input, exported so a test can check its keys are classified. */
+export declare const coverageCheckAddressInputSchema: z.ZodObject<{
+    cep: z.ZodOptional<z.ZodString>;
+    cidade: z.ZodOptional<z.ZodString>;
+    logradouro: z.ZodOptional<z.ZodString>;
+    bairro: z.ZodOptional<z.ZodString>;
+    numero_inicial: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+    numero_final: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+}, z.core.$strict>;
+declare const answerSchema: z.ZodObject<{
+    viabilidade: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$loose>;
+/**
+ * The response of `POST /api/ura/viabilidade/`, in SGP's own shape, kept as received. Observed:
+ * `{ "viabilidade": true }` (a postal code) and `{}` (a city alone).
+ *
+ * A MISSING `viabilidade` MEANS UNKNOWN, NEVER "NO COVERAGE": SGP answered `{}` for a city it
+ * could not decide on. Do not read `data.viabilidade ?? false`. The "no coverage" answer was NEVER
+ * OBSERVED: whether SGP sends `false` is not known, so a `false` is passed through as it comes.
+ */
+export type CoverageCheckAddressData = z.output<typeof answerSchema>;
+/** INTERNAL definition of `coverage.checkAddress`. */
+export declare const coverageCheckAddress: OperationDefinition<CoverageCheckAddressData, "coverage.checkAddress">;
+export {};

package/dist/operations/coverage-check.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+/** Input of `coverage.check`, named as SGP names the fields. All three are required. */
+export interface CoverageCheckInput {
+    /**
+     * Exercised. ID of the map gateway SGP checks against. Read the provider's own list with
+     * `coverage.listGateways`, never assume a value.
+     */
+    gateway: number;
+    /** Exercised. Search radius in meters. */
+    raio: number;
+    /**
+     * Exercised. The coordinate to check, `"lat,lng"` (for example `"-23.55,-46.63"`). The SDK does
+     * not geocode: bring the coordinate yourself. Sent as given; SGP decides what it accepts.
+     */
+    coordenada: string;
+}
+/** INTERNAL. Validation of the input, exported so a test can check it against the public type. */
+export declare const coverageCheckInputSchema: z.ZodObject<{
+    gateway: z.ZodNumber;
+    raio: z.ZodNumber;
+    coordenada: z.ZodString;
+}, z.core.$strict>;
+declare const ctoSchema: z.ZodObject<{
+    lat: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    lng: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    distancia: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    id: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<number | null, unknown>>>;
+    nome: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>;
+/** One CTO (the nearest network box) within the radius, as the gateway reports it. */
+export type CoverageCto = z.output<typeof ctoSchema>;
+/**
+ * The response of `GET /api/ura/viabilidadeinstalacao`, in SGP's own shape: an array whose
+ * element is an object keyed by the gateway's own name (`"SGPMaps"`, `"Geogrid"`: data-defined),
+ * holding either the CTOs within the radius or a message (`"Localização inviável"`) when there
+ * are none. A CTO's `lat`, `lng`, `distancia` and `id` are numbers (`null` for `""`/`null`): Geogrid's
+ * numeric strings are converted, SGPMaps' numbers pass through (changed versus 2.0.0-beta.1).
+ */
+export type CoverageCheckData = Array<Record<string, string | CoverageCto[]>>;
+/** INTERNAL definition of `coverage.check`. */
+export declare const coverageCheck: OperationDefinition<CoverageCheckData, "coverage.check">;
+export {};

package/dist/operations/coverage-list-gateways.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const gatewaysSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    descricao: z.ZodString;
+    gateway: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `GET /api/ura/listgatewaymapa`, in SGP's own shape: a bare array with one entry
+ * per map gateway (SGP "Mapa FTTH"). The `id` is the `gateway` that `coverage.check` takes. The
+ * route is not paginated, so there is no envelope and no total.
+ */
+export type CoverageListGatewaysData = z.output<typeof gatewaysSchema>;
+/** INTERNAL definition of `coverage.listGateways`. */
+export declare const coverageListGateways: OperationDefinition<CoverageListGatewaysData, "coverage.listGateways">;
+export {};