sgp-sdk 1.2.0 → 2.0.0-beta.1

package/dist/operations/pre-registrations-list-plans.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const preRegistrationPlansSchema: z.ZodArray<z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodNumber, "PreRegistrationPlanId", "out">;
+    tipo: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    valor: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+    descricao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    observacao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    gateway: z.ZodNullable<z.ZodOptional<z.ZodObject<{
+        gateway_id: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        id: z.ZodNullable<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        descricao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/precadastro/plano/list`, in SGP's own shape: a bare array with one
+ * entry per plan of the pré-cadastro catalog. The route is not paginated, so there is no envelope
+ * and no total. Each `id` is a `PreRegistrationPlanId`, a type apart from the `PlanId` of
+ * `plans.list`.
+ */
+export type PreRegistrationsListPlansData = z.output<typeof preRegistrationPlansSchema>;
+/** INTERNAL definition of `preRegistrations.listPlans`. */
+export declare const preRegistrationsListPlans: OperationDefinition<PreRegistrationsListPlansData, "preRegistrations.listPlans">;
+export {};

package/dist/operations/pre-registrations-list-sellers.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const sellersSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    nome: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    cpf: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    email: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+}, z.core.$loose>>;
+/**
+ * The response of `POST /api/precadastro/vendedor/list`, in SGP's own shape: a bare array with one
+ * entry per seller. The route is not paginated, so there is no envelope and no total.
+ */
+export type PreRegistrationsListSellersData = z.output<typeof sellersSchema>;
+/** INTERNAL definition of `preRegistrations.listSellers`. */
+export declare const preRegistrationsListSellers: OperationDefinition<PreRegistrationsListSellersData, "preRegistrations.listSellers">;
+export {};

package/dist/operations/services-add-tv.d.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+import type { PlanId } from "./plans-list.js";
+/** Input of `services.addTv`, named as SGP names the fields. */
+export interface ServiceAddTvInput {
+    /** Exercised. ID of the contract; it must be active (SGP refuses otherwise). */
+    clientecontrato_id: number;
+    /**
+     * Exercised. ID of the TV plan, a `PlanId` from the URA plan list (`plans.list`): a TV plan was
+     * accepted and a read-back confirmed the plan. The ID spaces differ: a plan id from this list
+     * was refused (400) as `plano_id` on the pré-cadastro route while accepted (200) as
+     * `planobase_id` here.
+     */
+    planobase_id: PlanId;
+    /** Exercised. Free-text note about the service. Personal data: never log it. */
+    info_extra?: string;
+    /** Documented, never sent. ID of the equipment type. */
+    tipo_equipamento?: number;
+    /**
+     * Documented, never sent. ID of the address to copy to the installation (omitted: the
+     * customer's).
+     */
+    endereco_id?: number;
+}
+/** INTERNAL. Validation of the input, exported so a test can check it against the public type. */
+export declare const servicesAddTvInputSchema: z.ZodObject<{
+    clientecontrato_id: z.ZodNumber;
+    planobase_id: z.core.$ZodBranded<z.ZodNumber, "PlanId", "out">;
+    info_extra: z.ZodOptional<z.ZodString>;
+    tipo_equipamento: z.ZodOptional<z.ZodNumber>;
+    endereco_id: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * Success body of `POST /api/servico/tv` (HTTP 201): SGP's `msg`, the new `servico_id` (a number)
+ * and `clientecontrato_id`, which SGP sends as a string (`"<n>"`) and is kept as such. Other keys
+ * SGP may add are kept.
+ */
+declare const tvAddedSchema: z.ZodObject<{
+    msg: z.ZodString;
+    clientecontrato_id: z.ZodOptional<z.ZodString>;
+    servico_id: z.ZodNumber;
+}, z.core.$loose>;
+/** Response of `services.addTv`. */
+export type ServiceAddTvData = z.output<typeof tvAddedSchema>;
+/** INTERNAL definition of `services.addTv`. */
+export declare const servicesAddTv: OperationDefinition<ServiceAddTvData, "services.addTv">;
+export {};

package/dist/operations/services-change-plan.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+import type { PlanId } from "./plans-list.js";
+/**
+ * Input of `services.changePlan`, named as SGP names the fields. `action` is fixed by the method
+ * (`change_plano`) and is not an input.
+ */
+export interface ServiceChangePlanInput {
+    /** Exercised. ID of the serviço to change (the `id` of `customers.list` -> `servicos[]`). */
+    servico_id: number;
+    /**
+     * Exercised with `1` only (`SERVICE_TYPE.internet`). Type of the serviço; required. Any
+     * positive integer is sent and SGP decides what it takes, but only internet was ever exercised.
+     */
+    servico_tipo: number;
+    /**
+     * Exercised. ID of the new plan, a `PlanId` from the URA catalog (`plans.list`), which is the ID
+     * space of operations on existing services (not the pré-cadastro catalog of
+     * `preRegistrations.listPlans`, whose ids are `PreRegistrationPlanId`).
+     */
+    plano_id: PlanId;
+}
+/** INTERNAL. Validation of the input, exported so a test can check it against the public type. */
+export declare const servicesChangePlanInputSchema: z.ZodObject<{
+    servico_id: z.ZodNumber;
+    servico_tipo: z.ZodNumber;
+    plano_id: z.core.$ZodBranded<z.ZodNumber, "PlanId", "out">;
+}, z.core.$strict>;
+/**
+ * Success body of `POST /api/suporte/service/update/{servico_id}/`: SGP's `msg`. It names neither
+ * the service nor the plan. Other keys SGP may add are kept.
+ */
+declare const planChangedSchema: z.ZodObject<{
+    msg: z.ZodString;
+}, z.core.$loose>;
+/** Response of `services.changePlan`. */
+export type ServiceChangePlanData = z.output<typeof planChangedSchema>;
+/** INTERNAL definition of `services.changePlan`. */
+export declare const servicesChangePlan: OperationDefinition<ServiceChangePlanData, "services.changePlan">;
+export {};

package/dist/operations/services-remove-tv.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+/** Input of `services.removeTv`, named as SGP names the fields. */
+export interface ServiceRemoveTvInput {
+    /** Exercised. ID of the TV serviço to remove (the `servico_id` of `services.addTv`). */
+    servico_id: number;
+    /** Exercised. ID of the contract the serviço belongs to. */
+    clientecontrato_id: number;
+}
+/** INTERNAL. Validation of the input, exported so a test can check it against the public type. */
+export declare const servicesRemoveTvInputSchema: z.ZodObject<{
+    servico_id: z.ZodNumber;
+    clientecontrato_id: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Success body of `DELETE /api/servico/tv/{servico_id}`: SGP's `msg`, the removed `servico_id` (a
+ * number) and `clientecontrato_id`, which SGP sends as a string and is kept as such. Other keys SGP
+ * may add are kept.
+ */
+declare const tvRemovedSchema: z.ZodObject<{
+    msg: z.ZodString;
+    clientecontrato_id: z.ZodOptional<z.ZodString>;
+    servico_id: z.ZodNumber;
+}, z.core.$loose>;
+/** Response of `services.removeTv`. */
+export type ServiceRemoveTvData = z.output<typeof tvRemovedSchema>;
+/** INTERNAL definition of `services.removeTv`. */
+export declare const servicesRemoveTv: OperationDefinition<ServiceRemoveTvData, "services.removeTv">;
+export {};

package/dist/operations/work-orders-list-reasons.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const workOrderReasonsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    codigo: z.ZodNumber;
+    descricao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    ativo: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+    classificacoes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodUnknown>>>;
+    classificacoes_obrigatorio: z.ZodNullable<z.ZodOptional<z.ZodBoolean>>;
+    setores: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodUnknown>>>;
+}, z.core.$loose>>;
+/**
+ * The response of `GET /api/os/ocorrencia/motivo/list/`, in SGP's own shape: a bare array with one
+ * entry per occurrence reason (the `motivo` of a work order). The route is not paginated, so there
+ * is no envelope and no total.
+ */
+export type WorkOrdersListReasonsData = z.output<typeof workOrderReasonsSchema>;
+/** INTERNAL definition of `workOrders.listReasons`. */
+export declare const workOrdersListReasons: OperationDefinition<WorkOrdersListReasonsData, "workOrders.listReasons">;
+export {};

package/dist/operations/work-orders-list.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import type { OperationDefinition } from "../operation.js";
+declare const pageSchema: z.ZodObject<{
+    paginacao: z.ZodObject<{
+        offset: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        limit: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        parcial: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        total: z.ZodNumber;
+    }, z.core.$loose>;
+    ordens_servicos: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        contrato: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        status_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        status: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        tipo_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        data_cadastro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        cliente: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        contrato_status: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        contrato_status_id: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
+        ocorrencia: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        hora_cadastro: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        data_agendamento: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        hora_agendamento: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        data_finalizacao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        hora_finalizacao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        tipo: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        motivo: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        pop: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        conteudo: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        responsavel: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        tecnicos_auxiliares: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodUnknown>>>;
+        usuario: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        usuario_finalizacao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        classificacoes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodUnknown>>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * One page of `POST /api/ura/ordemservico/list/`, with SGP's own `paginacao`, returned as received:
+ *
+ * - `offset`: index of the first work order of the page (SGP starts at 0);
+ * - `limit`: page size SGP applied, which may differ from the one requested;
+ * - `parcial`: how many work orders this page holds (observed equal to `ordens_servicos.length`);
+ * - `total`: how many work orders match the filters in all, across every page.
+ *
+ * `total` is SGP's and never computed by the SDK: a page without a numeric `total` is
+ * `INVALID_RESPONSE`. Nothing here fetches the next page: ask for it with `offset`.
+ */
+export type WorkOrdersListData = z.output<typeof pageSchema>;
+/** Filters and paging of `workOrders.list`, named as SGP names them. All optional. */
+export interface WorkOrdersListInput {
+    /** Index of the first work order of the page; SGP starts at 0. Non-negative integer. */
+    offset?: number;
+    /** Work orders per page. Non-negative integer; SGP decides the cap. */
+    limit?: number;
+    /**
+     * Work order id. SGP's collection describes it as the id of the occurrence (the OS); whether it
+     * matches `ordens_servicos[].id` or the `ocorrencia` number was not verified.
+     */
+    ordem_servico?: number;
+    /** Work order status id (`status_id` in the result; 0 is "Aberta" in the captures). */
+    status?: number;
+    /** POP id. */
+    pop?: number;
+    /** Occurrence reason id. */
+    motivo?: number;
+    /** Only work orders of this contract. */
+    contrato?: number;
+}
+/** INTERNAL. Validation of the input, exported so a test can check its keys are classified. */
+export declare const workOrdersListInputSchema: z.ZodObject<{
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    ordem_servico: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodNumber>;
+    pop: z.ZodOptional<z.ZodNumber>;
+    motivo: z.ZodOptional<z.ZodNumber>;
+    contrato: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** INTERNAL definition of `workOrders.list`. */
+export declare const workOrdersList: OperationDefinition<WorkOrdersListData, "workOrders.list">;
+export {};

package/dist/path.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fills the `{name}` placeholders of `template` with URL-encoded `pathParams`. Otherwise the first
+ * problem, named without its value: a placeholder with no value, an empty value, `.`/`..` (dot
+ * segments would change the route), a number that is not a safe integer, a value that cannot be
+ * encoded (lone surrogate), or a `pathParams` key that is not in the template.
+ */
+export declare const resolvePath: (template: string, pathParams?: Readonly<Record<string, string | number>>) => {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    problem: string;
+};

package/dist/raw-request.d.ts

@@ -0,0 +1,26 @@
+import type { CallOptions, ResolvedConfig } from "./config.js";
+import type { Encoding } from "./operation.js";
+import type { SgpResult } from "./result.js";
+/** Input of `request()`. */
+export interface RawRequestInput {
+    /** HTTP method. Which one a route needs is for the caller to know: the SDK never infers it. */
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /**
+     * Route on the configured SGP instance, e.g. `/api/ura/clientes/`: it starts with `/api/` and is
+     * already in its final form (no query, no fragment, no `//`, no `.`/`..` segments, no `%`).
+     * Anything else is refused locally with `INVALID_INPUT` before a request is sent. Put query
+     * parameters of a GET in `body`. `;` is sent literally (it stays on the same origin, under `/api/`).
+     */
+    path: string;
+    /**
+     * Request fields. A GET has no body: they go in the query string (primitives only). Other
+     * methods send them in `encoding`; a `json` body must be serializable (no `BigInt`, no cycle)
+     * and a `form` body takes primitives only. It is copied once when the call starts. Credentials are added by the SDK and cannot be
+     * overridden.
+     */
+    body?: Readonly<Record<string, unknown>>;
+    /** Body encoding of POST/PUT/DELETE: `json` (default) or `form` (multipart text fields). */
+    encoding?: Encoding;
+}
+/** INTERNAL. Runs `request()`: validates the destination, then the shared executor. */
+export declare const executeRawRequest: (config: ResolvedConfig, input: RawRequestInput, options?: CallOptions) => Promise<SgpResult<unknown>>;

package/dist/request.d.ts

@@ -0,0 +1,28 @@
+import type { ResolvedConfig } from "./config.js";
+import type { OperationDefinition, RequestBuild } from "./operation.js";
+/** What goes on the wire for one attempt. */
+export interface EncodedRequest {
+    url: string;
+    headers?: Record<string, string>;
+    body?: string | FormData;
+}
+/** The parts of a successful `buildRequest` that the encoder writes: body fields, files, URL query. */
+type BuiltRequest = Pick<Extract<RequestBuild, {
+    ok: true;
+}>, "params" | "files" | "query">;
+/**
+ * Encodes one request. A GET never has a body: params and credentials go in the query string
+ * (primitives only, `undefined` omitted). Every other method (POST, PUT and DELETE alike) sends
+ * the body in the operation's encoding: `json`, or `form` (multipart text fields, no content-type
+ * header so `fetch` adds the boundary), or `form-files`, the same plus one part per file (written
+ * before the credentials, so these stay last). Credentials are written once and last, so a param
+ * can never replace or repeat them. `undefined` when a GET or form param is not a primitive.
+ *
+ * `query` is for a request that has a body: its entries go in the URL after the path (primitives
+ * only, `undefined` omitted; none, or only `undefined`, leaves the URL as it was) while the
+ * credentials stay in the body. A GET already puts everything in the query string, so a GET with a
+ * `query`, a `query` that is not made of primitives, or one that names `token` or `app` gives
+ * `undefined`.
+ */
+export declare const encodeRequest: (config: ResolvedConfig, definition: Pick<OperationDefinition<unknown>, "method" | "encoding">, path: string, built?: BuiltRequest) => EncodedRequest | undefined;
+export {};

package/dist/result.d.ts

@@ -1,55 +1,123 @@
-/** Normalized failure category returned by every SDK method. */
-export type SgpErrorCode = "UNAUTHORIZED" | "ROUTE_NOT_ALLOWED" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "VALIDATION" | "SCHEMA_MISMATCH" | "UPSTREAM" | "TIMEOUT" | "NETWORK" | "UNKNOWN";
-/** Normalized error. Never carries credentials, query strings, raw bodies or fetch exception messages. */
-export interface SgpError {
-    /** HTTP status, or 0 when no response was received. */
+/** Stable failure category of every 2.0 method. Branch on this, never on `message`. */
+export type SgpErrorCode = "INVALID_INPUT" | "UNAUTHORIZED" | "FORBIDDEN" | "RATE_LIMITED" | "ROUTE_NOT_ALLOWED" | "NOT_FOUND" | "REJECTED" | "UPSTREAM" | "NETWORK" | "TIMEOUT" | "ABORTED" | "INVALID_RESPONSE";
+/**
+ * What the SDK can affirm about the requested change of a write: `"none"` when it can affirm the
+ * change was not applied, `"unknown"` otherwise. Reads carry no effect.
+ */
+export type Effect = "none" | "unknown";
+/**
+ * Body of a captured response, as a discriminated value. `json` and `text` hold the decoded content
+ * (not the wire bytes); `unavailable` means the body started but could not be read to the end.
+ * `withheld` is a body the SDK received and deliberately did not keep: only
+ * `experimental.annotations.list` produces it, because its body holds other customers' notes.
+ */
+export type ResponseBody = {
+    kind: "json";
+    value: unknown;
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "empty";
+} | {
+    kind: "unavailable";
+    reason: "timeout" | "aborted" | "network";
+} | {
+    kind: "withheld";
+    reason: "bulk-privacy";
+};
+/** The HTTP response SGP sent: status, headers (lowercased names) and body. */
+export interface CapturedResponse {
+    /** HTTP status code SGP answered with. */
     status: number;
+    /**
+     * Header values as received, except that the credentials of the client are replaced by
+     * `<redacted>`: the value of any `token`/`app` parameter of a query or fragment, and the exact
+     * token or app (plain or URL-encoded) wherever it appears, when it has at least 8 characters.
+     */
+    headers: Readonly<Record<string, string>>;
+    /** The body as read; see {@link ResponseBody} for what each kind means. */
+    body: ResponseBody;
+}
+/** SGP's own error fields, values exactly as received. Only the keys present in the body appear. */
+export interface SgpErrorFields {
+    /** SGP's `detail` text, as received. */
+    detail?: unknown;
+    /** SGP's `msg` text, as received. */
+    msg?: unknown;
+    /** SGP's `error` text, as received. */
+    error?: unknown;
+    /** SGP's `errors`, as received: an object of field errors or an array of texts. */
+    errors?: unknown;
+}
+/** Normalized failure of a method. Never carries credentials, URLs or thrown objects. */
+export interface SgpError {
+    /** Stable failure category; branch on this. */
     code: SgpErrorCode;
     /** Written by the SDK, in English. */
     message: string;
-    /**
-     * Text from SGP's error body, copied verbatim (it can echo values from the request; the SDK adds
-     * nothing to it). Precedence: `detail` string, then non-empty `msg` string, then `errors`
-     * (array items, or `"key: value"` pairs from an object, joined by `"; "`), then non-empty
-     * `error` string. 401/403 are classified by it.
-     */
-    detail?: string;
-    /** Request path only, without query string. */
-    endpoint: string;
+    /** Name of the operation that failed, e.g. `customers.list`. */
+    operation: string;
+    /** Operation-specific code, only where there is per-operation evidence. */
+    reason?: string;
+    /** What is known about the remote effect; set by writes only. */
+    effect?: Effect;
+    /** Projection of the SGP error fields found in the response body. */
+    sgp?: SgpErrorFields;
+    /** On `INVALID_RESPONSE`: the paths that broke the contract, never values. */
+    issues?: readonly string[];
+}
+/** A hook that threw. Only its name and the attempt it ran on are kept, never the thrown value. */
+export interface Diagnostic {
+    /** Which hook threw. */
+    hook: "onRequest" | "onResponse" | "onError";
+    /** Attempt number (1-based) during which the hook ran. */
+    occurrence: number;
 }
-/** A non-key field whose type did not match the schema; reports type names, never values. */
+/** Fields every result carries, on success and on failure. */
+export interface ResultBase {
+    /** Requests the SDK started: 0 when refused locally, 1 for the first transport call. */
+    attempts: number;
+    /** Present only when a hook failed. */
+    diagnostics?: readonly Diagnostic[];
+}
+/**
+ * A field that did not have the type the method expects but is not essential to the response. The
+ * field left `data` and stays untouched in `response.body`, unless that body is `withheld` (then it
+ * is not recoverable). Type names only, never values.
+ */
 export interface SchemaWarning {
+    /** Where the mismatch is, with real indices: `clientes[0].contratos[1].status`. */
     path: string;
+    /**
+     * The field that is absent from `data` because of it. Equal to `path`, except when the mismatch is
+     * an array element: the whole array field is dropped (`clientes[0].contatos.emails`).
+     */
+    dropped: string;
+    /** Type the method expects (`string`, or `number | string` when several are accepted). */
     expected: string;
+    /** Type that arrived: `string`, `number`, `boolean`, `null`, `undefined`, `array` or `object`. */
     received: string;
 }
-/** Outcome of every SDK method; methods never throw for network, HTTP or schema failures. */
-export type SgpResult<T> = {
-    success: true;
+/** Successful call. `response` is the raw HTTP response the data came from. */
+export interface SgpSuccess<T> extends ResultBase {
+    /** Discriminant: `true` on success. */
+    ok: true;
+    /** What the method returns, decoded from the response. */
     data: T;
-    warnings?: SchemaWarning[];
-} | {
-    success: false;
+    /** The HTTP response `data` came from. */
+    response: CapturedResponse;
+    /** Present only when a non-essential field was dropped from `data`; see {@link SchemaWarning}. */
+    warnings?: readonly SchemaWarning[];
+}
+/** Failed call. `response` is `null` when no HTTP response was available. */
+export interface SgpFailure extends ResultBase {
+    /** Discriminant: `false` on failure. */
+    ok: false;
+    /** Why the call failed. */
     error: SgpError;
-};
-/**
- * Whether SGP applied a failed write: `"not_applied"` for a 4xx or a request rejected locally before
- * being sent (`VALIDATION`, status 0), `"unknown"` for everything else. The exception is SGP's
- * generic exception wrapper, a 4xx (in practice 400) whose body `errors` is an array (e.g.
- * `"Ocorreu um erro: ..."`): SGP may have failed after applying the write, so it is `"unknown"`.
- * 401/403/404/405/422 stay `"not_applied"`.
- */
-export type WriteOutcome = "not_applied" | "unknown";
-/** Normalized write error; `outcome` says whether the write may have taken effect. */
-export interface SgpWriteError extends SgpError {
-    outcome: WriteOutcome;
-}
-/** Outcome of every SDK write method; like reads, they never throw for network, HTTP or schema failures. */
-export type SgpWriteResult<T> = {
-    success: true;
-    data: T;
-    warnings?: SchemaWarning[];
-} | {
-    success: false;
-    error: SgpWriteError;
-};
+    /** The HTTP response received, or `null` when none was (refused locally, or the transport failed). */
+    response: CapturedResponse | null;
+}
+/** Outcome of every 2.0 method: expected failures are returned, never thrown. */
+export type SgpResult<T> = SgpSuccess<T> | SgpFailure;

package/dist/retry.d.ts

@@ -0,0 +1,34 @@
+import type { SgpFailure } from "./result.js";
+/**
+ * INTERNAL. The clock, the jitter and the wait of a call, injectable so retry timing is testable
+ * without real sleeps. Consumers never see it.
+ */
+export interface Runtime {
+    /** Epoch milliseconds. */
+    now: () => number;
+    /** In [0, 1). */
+    random: () => number;
+    /**
+     * Resolves after `ms`, or as soon as `signal` aborts (the executor then reads the budget's stop
+     * cause). Must release its timer and listener either way.
+     */
+    sleep: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+export declare const defaultRuntime: Runtime;
+/**
+ * Whether the failure itself is the kind a repeat can fix: `RATE_LIMITED`, any `NETWORK`
+ * (the transport broke before or while reading the response, so nothing came of the attempt) and
+ * `UPSTREAM` with status 502, 503 or 504. A plain 500 is not on the list: it is as likely a
+ * deterministic bug of the route as a blip. The caller must still check the budget's stop cause.
+ */
+export declare const isTransientFailure: (failure: SgpFailure) => boolean;
+/**
+ * Wait before retry number `retryNumber` (1-based): "equal jitter" over an exponential ceiling,
+ * half fixed and half random, so a burst of clients spreads out without ever waiting zero.
+ */
+export declare const backoffMs: (retryNumber: number, random: () => number) => number;
+/**
+ * Milliseconds the server asked to wait: whole seconds, or an HTTP date relative to `now`. A past
+ * date is `0`. `undefined` when the header is absent or unreadable (the backoff then decides).
+ */
+export declare const parseRetryAfter: (value: string | null, now: number) => number | undefined;

package/dist/sensitivity.d.ts

@@ -1,7 +1,92 @@
+import type { Diagnostic, Effect, SchemaWarning, SgpErrorCode, SgpResult } from "./result.js";
 /**
- * Returns a shallow copy of `obj` without `keys`, typed accordingly.
+ * The keys of one kind of object that hold sensitive values. The same declaration describes the
+ * request fields (`input`) and the fields of the 2xx body (`output`, same shape as `data` and as
+ * `response.body.value`) of an operation.
+ */
+export interface SensitivityScope {
+    /**
+     * Where the objects are, in {@link pick} path syntax: `""` for the root object,
+     * `clientes[].contratos[]` for each contract of each customer.
+     */
+    path: string;
+    /** Credentials and network identifiers: Central/PPPoE logins and passwords, Wi-Fi, MAC, IP... */
+    secretKeys: readonly string[];
+    /** Personal data of a customer: name, document, address, contacts... A key covers its subtree. */
+    personalKeys: readonly string[];
+}
+/**
+ * What an operation declares as sensitive. Keys not listed are not "safe": the SDK treats every
+ * field it does not know as potentially sensitive, and so should the consumer (use {@link pick}).
+ */
+export interface OperationSensitivity {
+    /** Fields of the request. */
+    input: readonly SensitivityScope[];
+    /** Fields of the 2xx body. */
+    output: readonly SensitivityScope[];
+}
+/**
+ * Allowlist projection: a copy of `source` holding only the paths of `allowlist`. This is the way
+ * to hand anything to a log, a tool or an MCP server; never pass a result, `data` or `response`
+ * on as is.
+ *
+ * `source` is a `data` object or a whole result (then paths start at `data`, `error`, `response`,
+ * `attempts`...). Path syntax: keys joined by `.`, `[]` after a key for each element of an array
+ * (`clientes[].contratos[].id`), `[].id` for a root array. A path naming an object or array takes
+ * its whole subtree, which is the caller's explicit choice, with one exception: naming `response`
+ * alone takes neither `response.body` nor `response.headers`; those two come out only when a path
+ * names them exactly or goes below them (`response.body`, `response.headers.content-type`). Every
+ * key not named never comes out. A malformed path picks nothing. Only own, JSON-like values are
+ * copied. Depth is not bounded: do not hand it untrusted, arbitrarily deep input.
+ *
+ * Returns `{}` (or `[]`) when nothing matches.
+ */
+export declare const pick: (source: unknown, allowlist: readonly string[]) => unknown;
+/**
+ * What {@link toSafeLog} keeps of a result. Nothing of `data`, of the response (body and headers
+ * included) or of SGP's own error text.
+ */
+export interface SafeLog {
+    /** Whether the call succeeded. */
+    ok: boolean;
+    /** Requests the SDK started: 0 when refused locally. */
+    attempts: number;
+    /** Hooks that threw: name and attempt, never the thrown value. */
+    diagnostics?: readonly Diagnostic[];
+    /** Fields dropped from `data`: paths and type names, never values. */
+    warnings?: readonly SchemaWarning[];
+    /** Only the status of the HTTP response; no body, no headers. */
+    response?: {
+        /** HTTP status SGP answered with. */
+        status: number;
+    };
+    /** The failure, without SGP's own text. */
+    error?: {
+        /** Stable failure category. */
+        code: SgpErrorCode;
+        /** Written by the SDK, never by SGP. */
+        message: string;
+        /** Name of the operation that failed. */
+        operation: string;
+        /** Operation-specific code, where there is evidence for it. */
+        reason?: string;
+        /** What is known about the remote effect of a write. */
+        effect?: Effect;
+        /** Paths that broke the contract, never values. */
+        issues?: readonly string[];
+        /** Names of the SGP error fields that came (`detail`, `errors`...); their values stay out. */
+        sgpFields?: readonly string[];
+    };
+}
+/**
+ * A copy of a success or failure that is meant to be logged: outcome, attempts, status, error
+ * code, reason, effect and the names of the SGP fields that came. No `data`, no `response.body`,
+ * no headers, no value of SGP's error text (`error.sgp`, which echoes what was sent), and no
+ * credentials.
  *
- * Meant for the `secretKeys` / `personalKeys` tuples of an endpoint, so callers can drop sensitive
- * fields before logging or forwarding an item. Does not mutate `obj`.
+ * An aid, not a guarantee: it protects only what goes through it. `console.log(result)`,
+ * `structuredClone(result)`, a logger that walks the object, or any copy made before this call
+ * still sees everything. Log `toSafeLog(result)`, never the result. To log or send part of `data`,
+ * use {@link pick} with an explicit allowlist.
  */
-export declare const omitSensitive: <T extends object, K extends keyof T>(obj: T, keys: readonly K[]) => Omit<T, K>;
+export declare const toSafeLog: (result: SgpResult<unknown>) => SafeLog;