sgp-sdk 0.0.0-stage → 1.2.0

package/dist/result.d.ts

@@ -0,0 +1,55 @@
+/** 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. */
+    status: number;
+    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;
+}
+/** A non-key field whose type did not match the schema; reports type names, never values. */
+export interface SchemaWarning {
+    path: string;
+    expected: string;
+    received: string;
+}
+/** Outcome of every SDK method; methods never throw for network, HTTP or schema failures. */
+export type SgpResult<T> = {
+    success: true;
+    data: T;
+    warnings?: SchemaWarning[];
+} | {
+    success: false;
+    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;
+};

package/dist/schema/parse.d.ts

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,38 @@
+/**
+ * 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/sensitivity.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns a shallow copy of `obj` without `keys`, typed accordingly.
+ *
+ * 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`.
+ */
+export declare const omitSensitive: <T extends object, K extends keyof T>(obj: T, keys: readonly K[]) => Omit<T, K>;

package/dist/transport.d.ts

@@ -0,0 +1,65 @@
+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>;

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "sgp-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Unofficial TypeScript client for the SGP (TSMX) ISP ERP HTTP API, with normalized errors and explicit write outcomes. Not affiliated with TSMX.",
+  "license": "MIT",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --external zod && tsc -p tsconfig.build.json",
+    "release": "bun scripts/release.ts",
+    "test": "bun test",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "check:consumer-types": "bun run build && tsc -p tests/consumer-types/tsconfig.json"
+  },
+  "dependencies": {
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@types/bun": "^1.4.4",
+    "typescript": "^7.0.2"
+  }
+}