sgp-sdk 1.2.0 → 2.0.0-beta.2

package/dist/endpoints/ura/list-service-orders.d.ts

@@ -1,64 +0,0 @@
-import { z } from "zod";
-import type { EndpointDefinition } from "../../endpoint.js";
-/** Response of `POST /api/ura/ordemservico/list/`: one page of service orders (OS). */
-export declare const listServiceOrdersSchema: 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.$strip>;
-    ordens_servicos: z.ZodArray<z.ZodObject<{
-        id: z.ZodNumber;
-        contrato: z.ZodNumber;
-        status_id: z.ZodNumber;
-        status: z.ZodString;
-        tipo_id: z.ZodNumber;
-        data_cadastro: 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.ZodObject<{}, z.core.$strip>>>>;
-        usuario: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-        usuario_finalizacao: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-        classificacoes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodObject<{}, z.core.$strip>>>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-/** Key fields of `ura/ordemservico/list`: required and strict; any mismatch is `SCHEMA_MISMATCH`. */
-export declare const listServiceOrdersKeyFields: readonly ["paginacao.total", "ordens_servicos", "ordens_servicos[].id", "ordens_servicos[].contrato", "ordens_servicos[].status_id", "ordens_servicos[].status", "ordens_servicos[].tipo_id", "ordens_servicos[].data_cadastro"];
-/** Normalized path of each service order in the `ura/ordemservico/list` response. */
-export declare const serviceOrderItemPath = "ordens_servicos[]";
-/** Keys of a service order holding secrets (none in `ura/ordemservico/list`). */
-export declare const serviceOrderSecretKeys: readonly [];
-/** Keys of a service order holding personal data: customer name and the free-text content. */
-export declare const serviceOrderPersonalKeys: readonly ["cliente", "conteudo"];
-/** Body parameters of `POST /api/ura/ordemservico/list/` (besides credentials); all optional filters and paging. */
-export interface ListServiceOrdersParams {
-    offset?: number;
-    limit?: number;
-    /** ID of the occurrence (the OS). */
-    ordem_servico?: number;
-    /** Service order status ID. */
-    status?: number;
-    /** POP ID. */
-    pop?: number;
-    /** Occurrence reason ID. */
-    motivo?: number;
-    /** Contract ID. */
-    contrato?: number;
-}
-/** Parsed response of `POST /api/ura/ordemservico/list/`. */
-export type ListServiceOrdersResponse = z.output<typeof listServiceOrdersSchema>;
-/** Definition of `POST /api/ura/ordemservico/list/`. */
-export declare const listServiceOrdersDefinition: EndpointDefinition<typeof listServiceOrdersSchema>;

package/dist/endpoints/ura/open-ticket.d.ts

@@ -1,81 +0,0 @@
-import { z } from "zod";
-import type { WriteEndpointDefinition } from "../../endpoint.js";
-/**
- * Success body of `POST /api/ura/chamado/`: `status` 1, the ticket protocol and the ID of the
- * occurrence, plus the contract and customer SGP echoes back. `status` 0 is SGP's refusal.
- */
-export declare const openTicketSchema: z.ZodObject<{
-    status: z.ZodLiteral<1>;
-    protocolo: z.ZodString;
-    id: z.ZodNumber;
-    contratoId: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
-    razaoSocial: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-    cpfCnpj: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-    msg: z.ZodNullable<z.ZodOptional<z.ZodString>>;
-}, z.core.$strip>;
-/**
- * Key fields of `ura/chamado`: required and strict. A 2xx is only a success with `status` 1 and a
- * `protocolo`; anything else (e.g. `status` 0 with a `msg`) is `VALIDATION` with `outcome: "unknown"`.
- */
-export declare const openTicketKeyFields: readonly ["status", "protocolo", "id"];
-/** Normalized path of the opened ticket in the response (the root object). */
-export declare const ticketOpenedItemPath = "";
-/** Keys of the response holding secrets (none in `ura/chamado`). */
-export declare const ticketOpenedSecretKeys: readonly [];
-/** Keys of the response holding personal data: the customer's name and CPF/CNPJ. */
-export declare const ticketOpenedPersonalKeys: readonly ["razaoSocial", "cpfCnpj"];
-/** Parsed response of `POST /api/ura/chamado/`. */
-export type OpenTicketResponse = z.output<typeof openTicketSchema>;
-/**
- * Params of `POST /api/ura/chamado/`; only `contrato` is required. `contato_nome` and
- * `contato_telefone` are personal data.
- */
-export interface OpenTicketParams {
-    /** Contract ID. */
-    contrato: number;
-    /** Content of the occurrence and the service order. */
-    conteudo?: string;
-    /** 1 removes SGP's default opening message ("via URA"). */
-    conteudolimpo?: 0 | 1;
-    observacao?: string;
-    /** Occurrence type code (SGP's default is 5). */
-    ocorrenciatipo?: number;
-    /** Classification IDs linked to the occurrence. */
-    tipoclassificacoes?: number[];
-    /** Occurrence method code (see `ura.listOccurrenceMethods`). */
-    metodo?: number;
-    /** Sector ID. */
-    setor?: number;
-    /** Username shown as who opened the occurrence. */
-    usuario?: string;
-    /** Username of the occurrence's responsible. */
-    responsaveloc?: string;
-    contato_nome?: string;
-    contato_telefone?: string;
-    /** 1 does not open a service order. */
-    desativa_os?: 0 | 1;
-    /** 1 creates the occurrence and the service order already closed. */
-    status_encerrado?: 0 | 1;
-    /** 1 notifies the customer of the closing, when created already closed. */
-    notificar_cliente?: 0 | 1;
-    /** Service order reason code; each SGP instance has its own (see `os.listOccurrenceReasons`). */
-    motivoos?: number;
-    /** Classification IDs linked to the service order. */
-    motivoclassificacoes?: number[];
-    /** Username of the service order's responsible technician. */
-    responsavel?: string;
-    /** Usernames of the auxiliary technicians. */
-    tecnicos?: string[];
-    /** Schedules the occurrence and the service order: `"AAAA-MM-DD HH:MM"`. */
-    data_hora_agendamento?: string;
-    /** 1 warns the responsible technician of the new service order; needs `data_hora_agendamento` and a messaging gateway in SGP. */
-    sms_tecnico?: 0 | 1;
-    /** With `servico_id`, links a specific contract service to the occurrence. */
-    tipo_servico?: "internet" | "telefonia" | "tv" | "multimidia" | "generico";
-    /** ID of the contract's service; use with `tipo_servico`. */
-    servico_id?: number;
-    /** ID of the company to link. */
-    empresa_id?: number;
-}
-/** Definition of `POST /api/ura/chamado/` (trailing slash required by the token whitelist). */
-export declare const openTicketDefinition: WriteEndpointDefinition<typeof openTicketSchema>;

package/dist/errors.d.ts

@@ -1,59 +0,0 @@
-import type { SgpError, SgpErrorCode, SgpWriteError } from "./result.js";
-/** SGP `detail` for 401/403 caused by wrong token/app credentials. */
-export declare const DETAIL_UNAUTHORIZED = "Credenciais de autentica\u00E7\u00E3o incorretas.";
-/** SGP `detail` for 401/403 when the app has no permission for the route (credentials "not provided"). */
-export declare const DETAIL_ROUTE_NOT_ALLOWED = "As credenciais de autentica\u00E7\u00E3o n\u00E3o foram fornecidas.";
-/** `message` of a write whose 2xx answer does not confirm it: the write may have been applied. */
-export declare const MESSAGE_WRITE_NOT_CONFIRMED = "SGP answered with a success status but the response does not confirm the write; it may have been applied.";
-/** `message` of a write SGP answered with its generic exception wrapper (a 4xx `errors` list): it may have been applied. */
-export declare const MESSAGE_WRITE_FAILED_GENERICALLY = "SGP reported an error while processing the write; it may have been applied.";
-/** `message` of a request the SDK refused before sending it (nothing left the process). */
-export declare const MESSAGE_REJECTED_LOCALLY = "The SDK rejected the request before sending it.";
-/**
- * Reads the SGP error text from a response body: a string `detail`, else a non-empty string `msg`,
- * else `errors`, else a non-empty string `error` (see {@link mapHttpFailure}). `undefined` when the
- * body carries none.
- */
-export declare const readSgpDetail: (body: unknown) => string | undefined;
-/**
- * Whether the body is SGP's generic exception wrapper: `errors` is an array (e.g.
- * `{"errors":["Ocorreu um erro: ..."]}`), as opposed to an object of field messages.
- */
-export declare const hasErrorList: (body: unknown) => boolean;
-/**
- * Builds a normalized error with the SDK-authored message for `code`, or with `message` when given.
- *
- * The `detail` key is omitted when `detail` is undefined.
- */
-export declare const createError: (code: SgpErrorCode, status: number, endpoint: string, detail?: string, message?: string) => SgpError;
-/**
- * Maps a non-2xx SGP response to a normalized error.
- *
- * `detail` is read from the first of these that yields text: a string `detail` (SGP's DRF message),
- * a non-empty string `msg` (e.g. `{"msg":"Informe um Raio válido."}`), then `errors` (the CRM format):
- * an array of strings joined by `"; "`, or an object of string values as `"key: value"` joined by
- * `"; "` in key order. Non-string items and values are ignored. Last, a non-empty string `error`
- * (e.g. `{"error":"Cadastro não encontrado"}`, a 404 on CRM routes). A body with none of these
- * leaves `detail` undefined. The raw body is never retained.
- */
-export declare const mapHttpFailure: (status: number, body: unknown, endpoint: string) => SgpError;
-/**
- * Maps an exception thrown by `fetch` to a normalized error (status 0).
- *
- * `TimeoutError` and `AbortError` become `TIMEOUT`; anything else becomes `NETWORK`.
- * The cause's message is never copied, since it can embed the request URL with credentials.
- */
-export declare const mapFetchFailure: (cause: unknown, endpoint: string) => SgpError;
-/**
- * Tags a failed write with whether SGP applied it: `"not_applied"` for a 4xx (SGP rejected the
- * request) and for a `VALIDATION` with status 0 (rejected locally, nothing was sent), `"unknown"`
- * for anything else (timeout/network, 5xx, 2xx that failed validation, 1xx/3xx).
- *
- * `isErrorListBody` (the {@link hasErrorList} result for the response body) marks a 4xx body that is
- * SGP's generic exception wrapper: SGP may have failed after applying part of the write, so that 4xx
- * is `"unknown"` too and carries {@link MESSAGE_WRITE_FAILED_GENERICALLY} as its `message`, except
- * 401/403/404/405/422, which stay `"not_applied"`. Omit it when the body is not known.
- *
- * Returns a new object; the input is not mutated.
- */
-export declare const toWriteError: (error: SgpError, isErrorListBody?: boolean) => SgpWriteError;

package/dist/schema/parse.d.ts

@@ -1,19 +0,0 @@
-import type { z } from "zod";
-import type { SgpResult } from "../result.js";
-/**
- * Validates an SGP response body, tolerating type drift in non-key fields.
- *
- * 1. Parses with `schema` (unknown keys are stripped at every level). Success → `data`.
- * 2. Otherwise picks, per issue, the property to remove: the property the issue points at or, when
- *    the issue sits on an array element, the nearest enclosing object property (the whole array
- *    field, e.g. `clientes[0].contatos.telefones`). If none exists, or it is a key field or an
- *    ancestor of one (`keyFields`, normalized paths like `clientes[].id`) → `SCHEMA_MISMATCH`.
- *    That property is the issue's own path or a prefix of it, so every issue on a key field or on
- *    an ancestor of one ends here.
- * 3. Removes those properties from a clone of `input` and parses exactly once more. Success →
- *    `data` plus one `SchemaWarning` per issue, with the precise issue location
- *    (e.g. `clientes[0].contatos.telefones[0]`) and type names only. Failure → `SCHEMA_MISMATCH`.
- *
- * `SCHEMA_MISMATCH.detail` lists the failing normalized paths (`(root)` for the body itself), never values.
- */
-export declare const parseResponse: <S extends z.ZodType>(schema: S, keyFields: readonly string[], input: unknown, endpoint: string) => SgpResult<z.output<S>>;

package/dist/schema/paths.d.ts

@@ -1,38 +0,0 @@
-/**
- * Joins a Zod issue path with array indices collapsed to `[]`, the form used by `keyFields`.
- *
- * `["contratos", 0, "contratoId"]` → `"contratos[].contratoId"`; `[0, "id"]` → `"[].id"`; `[]` → `""`.
- */
-export declare const normalizePath: (path: ReadonlyArray<PropertyKey>) => string;
-/**
- * Joins a Zod issue path keeping the real array indices, the form used in `SchemaWarning.path`.
- *
- * `["clientes", 0, "sexo"]` → `"clientes[0].sexo"`.
- */
-export declare const formatPath: (path: ReadonlyArray<PropertyKey>) => string;
-/**
- * Tells whether a raw Zod issue path is a key field or an ancestor of one.
- *
- * Segments are compared as they are, never joined into a string, so a data-defined property name
- * holding `.`, `[` or `]` stays one segment. The root (`[]`) is an ancestor of every key.
- * A numeric segment matches only a `[]` key segment. A string segment matches a `*` key segment
- * (any name, the empty one included) or an equal name, never `[]`: `["[].*"]` covers `[0, "Geogrid"]`
- * and `[0, "Geo.grid"]` (data-defined names), but not what sits below them.
- */
-export declare const isKeyPathOf: (path: ReadonlyArray<PropertyKey>, keyFields: readonly string[]) => boolean;
-/**
- * Tells whether a normalized path is a key field or an ancestor of one.
- *
- * The root (`""`) is an ancestor of every key. `"cliente"` is not an ancestor of `"clientes[].id"`.
- * A `*` segment in a key matches exactly one property name, never an array index: `"[].*"` covers
- * `"[].SGPMaps"` and `"[].Geogrid"` (data-defined names), but not what sits below them.
- */
-export declare const isKeyPath: (path: string, keyFields: readonly string[]) => boolean;
-/** Reads the value at `path`, or `undefined` when any step is missing or not indexable. */
-export declare const valueAt: (input: unknown, path: ReadonlyArray<PropertyKey>) => unknown;
-/**
- * Names the type of the value at `path`; never returns the value itself.
- *
- * One of `"string" | "number" | "boolean" | "null" | "undefined" | "array" | "object"` for JSON input.
- */
-export declare const typeNameAt: (input: unknown, path: ReadonlyArray<PropertyKey>) => string;

package/dist/transport.d.ts

@@ -1,65 +0,0 @@
-import type { SgpError } from "./result.js";
-/** Default request timeout in milliseconds. */
-export declare const DEFAULT_TIMEOUT_MS = 20000;
-/** Connection settings shared by every SDK method. */
-export interface SgpClientConfig {
-    baseUrl: string;
-    token: string;
-    app: string;
-    /** Request timeout in milliseconds. Defaults to {@link DEFAULT_TIMEOUT_MS}. */
-    timeoutMs?: number;
-    /** Custom `fetch`, mainly for tests. Defaults to the global `fetch`. */
-    fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-}
-/**
- * A request parameter value. Arrays and objects are only valid on POST/PUT; `undefined` object keys
- * are omitted at any depth.
- */
-export type ParamValue = string | number | boolean | null | readonly ParamValue[] | {
-    readonly [key: string]: ParamValue | undefined;
-};
-/** A file sent as one part of a multipart request. */
-export interface SgpFile {
-    data: Blob | Uint8Array | ArrayBuffer;
-    filename: string;
-    /** MIME type of the part. Defaults to the `type` of a `Blob`; none for bytes. */
-    contentType?: string;
-}
-/**
- * One SGP request; `path` starts with `/` and may hold `{name}` placeholders filled from
- * `pathParams`. `params` with `undefined` values are dropped. POST/PUT with `files` is sent as
- * multipart; otherwise as JSON.
- */
-export interface RequestSpec {
-    method: "GET" | "POST" | "PUT";
-    path: string;
-    pathParams?: Record<string, string | number>;
-    params?: Record<string, ParamValue | undefined>;
-    files?: Record<string, SgpFile>;
-}
-/**
- * Parsed JSON body of a 2xx response with its HTTP status, or the normalized failure.
- * `hasErrorList` is set on a non-2xx answer: its JSON body is SGP's generic exception wrapper
- * (`errors` is an array). The body itself is never kept.
- */
-export type RawResponse = {
-    ok: true;
-    body: unknown;
-    status: number;
-} | {
-    ok: false;
-    error: SgpError;
-    hasErrorList?: boolean;
-};
-/**
- * Sends one request to SGP and returns the parsed JSON body or a normalized error.
- *
- * GET sends `token` and `app` in the query string and only accepts primitive params; POST/PUT send
- * them in a JSON body, or as multipart fields when `files` is set. A 2xx response with an empty
- * body yields `body: null`. The success result carries the real 2xx `status`. Redirects are never
- * followed (`redirect: "manual"`): a 3xx comes back as an `UNKNOWN` error with its status.
- * Never throws: invalid path params or structured GET params (`VALIDATION`, status 0, no request
- * sent), network failures, timeouts, non-2xx statuses and non-JSON 2xx bodies all come back as
- * `{ ok: false, error }`, where `error.endpoint` is `spec.path` (the template) only.
- */
-export declare const sendRequest: (config: SgpClientConfig, spec: RequestSpec) => Promise<RawResponse>;