sgp-sdk 1.2.0 → 2.0.0-beta.1

package/dist/address.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+/**
+ * Address as SGP takes it. Pass it once: operations that take an address send it as the loose
+ * fields (`logradouro`, `numero`, ...) SGP reads, with the names unchanged. Every key is optional
+ * here: each operation declares which ones it requires.
+ */
+export interface SgpAddress {
+    /** Street name. */
+    logradouro?: string;
+    /** A label, not a count: `"S/N"` and `"12-A"` are valid. */
+    numero?: string | number;
+    /** Complement (apartment, block, ...). */
+    complemento?: string;
+    /** Neighbourhood. */
+    bairro?: string;
+    /** City. */
+    cidade?: string;
+    /** Postal code (CEP). */
+    cep?: string;
+    /** State code, e.g. `"SC"`. */
+    uf?: string;
+    /** Country code, e.g. `"BR"` (SGP's default). */
+    pais?: string;
+    /** Reference point. */
+    pontoreferencia?: string;
+    /** Map position, `"lat,lng"`. */
+    map_ll?: string;
+    /** Condominium ID. */
+    condominio?: string | number;
+}
+/** Validation shape of an {@link SgpAddress}, every key optional; operations override what they require. */
+export declare const addressShape: {
+    logradouro: z.ZodOptional<z.ZodString>;
+    numero: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    complemento: z.ZodOptional<z.ZodString>;
+    bairro: z.ZodOptional<z.ZodString>;
+    cidade: z.ZodOptional<z.ZodString>;
+    cep: z.ZodOptional<z.ZodString>;
+    uf: z.ZodOptional<z.ZodString>;
+    pais: z.ZodOptional<z.ZodString>;
+    pontoreferencia: z.ZodOptional<z.ZodString>;
+    map_ll: z.ZodOptional<z.ZodString>;
+    condominio: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+};
+/** The address as the loose fields to send: same keys, no `undefined` ones. */
+export declare const flatAddress: (address: SgpAddress) => Record<string, string | number>;

package/dist/annotation-selection.d.ts

@@ -0,0 +1,32 @@
+/** The requested identities; at least one is present, and both mean AND. */
+export interface AnnotationFilters {
+    cliente_id?: number;
+    contrato_id?: number;
+}
+/**
+ * Outcome of the local selection. `paths` names the identity fields (`[].cliente`,
+ * `[].clientecontrato`) that kept a row's membership undecidable: paths only, never values.
+ */
+type AnnotationSelection = {
+    ok: true;
+    selected: unknown[];
+} | {
+    ok: false;
+    paths: readonly string[];
+};
+/**
+ * INTERNAL. Local selection of the rows of one SGP annotation response, by raw identity and BEFORE
+ * any row is parsed: SGP ignores the customer and contract filters and answers with other
+ * customers' notes, so nothing but a row that provably matches may go on.
+ *
+ * - One definite mismatch excludes a row (AND), even when the other identity is malformed or the
+ *   rest of the row is garbage: a foreign row is never looked at again.
+ * - A `null` contract is a definite mismatch when a contract was requested.
+ * - A row that no definite mismatch excludes, and whose requested identity is missing or not a
+ *   number, is undecidable: the whole selection fails at the first such row (never a silent skip,
+ *   never a partial success).
+ * - A selected note whose nested objects carry another identity fails the selection too.
+ * - Order and duplicates are kept; nothing is parsed, coerced or deduplicated.
+ */
+export declare const selectAnnotations: (rows: readonly unknown[], filters: AnnotationFilters) => AnnotationSelection;
+export {};

package/dist/budget.d.ts

@@ -0,0 +1,29 @@
+/** Who stopped the call: the SDK's own deadline or the caller's signal. */
+export type StopCause = "timeout" | "aborted";
+/** Whether `error` is the unwinding of a race that the budget won, and nothing else. */
+export declare const isBudgetStopped: (error: unknown) => boolean;
+/**
+ * The one time budget of a logical call: a deadline plus the caller's signal, merged into a single
+ * signal for `fetch`. It is never reset, so it covers every wait of the call (headers, body,
+ * retries and backoff). The deadline is enforced by a real timer; `now` only measures what is left.
+ */
+export interface Budget {
+    /** Aborts when the deadline expires or the caller's signal aborts. */
+    readonly signal: AbortSignal;
+    /** Why the budget stopped; `undefined` while it is still running. */
+    cause: () => StopCause | undefined;
+    /** Milliseconds left until the deadline, by the injected clock. Never negative. */
+    remainingMs: () => number;
+    /**
+     * Settles with `work`, or rejects as soon as the budget stops, even when `work` ignores the
+     * signal. The caller decides what the rejection means from {@link Budget.cause}.
+     */
+    race: <T>(work: Promise<T>) => Promise<T>;
+    /** Clears the timer and the listener on the caller's signal. Safe to call twice. */
+    dispose: () => void;
+}
+/**
+ * Starts the budget. `undefined` when the caller's signal cannot be read or listened to (it is unusable):
+ * nothing is left running in that case, because the listener is registered before the timer.
+ */
+export declare const startBudget: (timeoutMs: number, callerSignal: AbortSignal | undefined, now?: () => number) => Budget | undefined;

package/dist/classify.d.ts

@@ -0,0 +1,15 @@
+import type { ResponseBody, SgpError, SgpErrorCode, SgpErrorFields } from "./result.js";
+/** SGP's own error fields found in a JSON object body, values untouched. `undefined` when none. */
+export declare const projectSgpFields: (body: ResponseBody) => SgpErrorFields | undefined;
+interface Classification {
+    code: SgpErrorCode;
+    reason?: string;
+}
+/**
+ * Classifies a complete HTTP response by status alone: the body can only refine a 403, and
+ * a body that cannot be read or parsed never erases the status already received.
+ */
+export declare const classifyStatus: (status: number, body: ResponseBody) => Classification;
+/** Builds an error with the SDK-authored message for `code`. */
+export declare const buildError: (code: SgpErrorCode, operation: string, extra?: Partial<Pick<SgpError, "reason" | "effect" | "sgp" | "issues">>) => SgpError;
+export {};