@sinio/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ternatek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @sinio/sdk — Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official client for the sinio.ai ingestion API. No runtime dependencies; Node 18+
+(uses the global `fetch`). ESM and CommonJS, typed end to end.
+
+```bash
+npm install @sinio/sdk
+```
+
+## Quick start
+
+```ts
+import { SinioClient } from "@sinio/sdk";
+
+const sinio = new SinioClient({
+  apiKey: process.env.SINIO_API_KEY!,
+  baseUrl: "https://api.sinio.ai",
+});
+
+const result = await sinio.sendEvents([
+  {
+    sourceEventId: "evt_88213",
+    type: "badge_in",
+    occurredAt: "2026-08-28T07:58:12+02:00",
+    roles: { device: "BORNE-A12", subject: "P-4582", location: "SITE-A.HALL" },
+    payload: { badge: "04A2B9C1", reader_firmware: "2.4.1" },
+  },
+]);
+
+// The four roles (device, subject, location, actor) are read from `roles` only;
+// any other key is refused by the API. `payload` is free and optional ({} by
+// default); readings such as a battery level are read from it as the
+// source declares them. `count` (1 by default) says how many units one event stands for.
+
+console.log(result.accepted, result.duplicates, result.rejections);
+```
+
+## What the client does for you
+
+- **Chunking.** Pass 50 000 events; the SDK splits them into calls of 500 (the API
+  limit) and merges the counters and rejections into one result.
+- **Retries.** 429, 5xx and dropped connections are retried with exponential
+  backoff and full jitter, honouring `Retry-After`. This is safe because
+  a resend with the same `source_event_id` and the same content is counted in
+  `duplicates`, never stored twice.
+- **Local validation.** What the API would refuse is refused before any call with a
+  `SinioValidationError` naming the field: a timestamp without a UTC offset (the API's own
+  rule), a kind or level outside its vocabulary, a missing required field, a `validTo` not after
+  `validFrom`, a role other than the four, a `payload` that is not an object.
+- **Typed errors.** `SinioAuthError` (401/403, do not replay),
+  `SinioRequestError` (400/404/413, fix the request), `SinioRateLimitError`
+  (429, carries `retryAfterSeconds`), `SinioServerError` (5xx, replayable),
+  `SinioConnectionError`, `SinioValidationError`.
+
+## Partial acceptance
+
+A 200 means the batch was **received**, not derived — derivation is asynchronous.
+Within a batch, valid events are accepted even when others are rejected, so always
+read `rejections`:
+
+```ts
+for (const rejection of result.rejections) {
+  console.warn(rejection.sourceEventId, rejection.code, rejection.message);
+}
+```
+
+`duplicates` and `revisions` are successes, not failures.
+
+The vocabularies are exported, so a value from elsewhere can be checked or a code handled
+without retyping the lists. A rejection code added by a later API version is kept as is:
+
+```ts
+import { ENTITY_KINDS, isKnownRejectionCode, type EntityKind } from "@sinio/sdk";
+
+const kind = row.type as EntityKind;
+if (!ENTITY_KINDS.includes(kind)) throw new Error(`unexpected kind ${row.type}`);
+
+for (const { code } of result.rejections) {
+  if (!isKnownRejectionCode(code)) console.warn("new rejection code", code);
+}
+```
+
+Also exported: `INGESTION_MODES`, `LOCATION_LEVELS`, `ASSIGNMENT_RELATIONS`, `EVENT_ROLES`,
+`REJECTION_CODES`.
+
+## Reference data
+
+```ts
+await sinio.upsertLocations([
+  { externalId: "SITE-A", kind: "site", name: "Site A" },
+  { externalId: "SITE-A.HALL", kind: "zone", name: "Hall", parent: "SITE-A" },
+]);
+
+await sinio.upsertEntities([
+  { externalId: "BORNE-A12", kind: "device", subkind: "nfc_kiosk", location: "SITE-A.HALL",
+    attributes: { firmware: "2.4.1" } },
+]);
+
+await sinio.createAssignments([
+  { credential: "04A2B9C1", subject: "P-4582", relation: "assigned_to",
+    validFrom: "2026-01-01T00:00:00+01:00" },
+]);
+```
+
+The reference is never a condition of acceptance: an event pointing at an unknown
+device is still accepted. Upserting is how you enrich it, not how you gate it.
+
+## Backfill
+
+```ts
+await sinio.backfillEvents(history);
+```
+
+`mode: "backfill"` persists history without raising alerts; once it has arrived, the
+project's processes replay it in a canonical order. Live catch-up after an outage should stay on
+`sendEvents` — the declared mode decides alerting, not the age of the events.
+
+## Webhook key
+
+For systems that can only be pointed at a URL and cannot set a header:
+
+```ts
+const sinio = new SinioClient({ webhookKey: process.env.SINIO_WEBHOOK_KEY! });
+await sinio.sendEvents(events); // POST /v1/webhooks/<key>
+```
+
+In this mode only event ingestion is available; the reference endpoints require an
+API key.
+
+
+## Development
+
+```bash
+npm install
+npm test     # typecheck + node:test
+npm run build
+```

package/dist/cjs/client.d.ts

@@ -0,0 +1,75 @@
+import { type FetchLike } from "./http.ts";
+import type { AssignmentInput, AssignmentsResult, EntityInput, LocationInput, SendEventsOptions, SendEventsResult, SinioEvent, ProjectOptions, UpsertResult } from "./types.ts";
+export declare const SDK_VERSION = "0.2.0";
+export interface SinioClientOptions {
+    /** Machine credential, sent as `Authorization: Bearer`. Mutually exclusive with `webhookKey`. */
+    readonly apiKey?: string;
+    /**
+     * Key carried in the URL instead of a header, for systems that can only be
+     * pointed at a webhook URL. Only `sendEvents` is available in this mode.
+     */
+    readonly webhookKey?: string;
+    /** Defaults to `https://api.sinio.ai`. */
+    readonly baseUrl?: string;
+    /**
+     * Sent as `X-Source-Code`. Only for keys not bound to a single source (organization-wide keys,
+     * issued on request); a source key already carries its source.
+     */
+    readonly sourceCode?: string;
+    /**
+     * Default project `external_id`. Only for organization-wide keys (issued on request) covering
+     * several projects; a project key already carries its project.
+     */
+    readonly project?: string;
+    /** Per-request timeout, default 30 s. */
+    readonly timeoutMs?: number;
+    /** Retries on 429, 5xx and dropped connections. Default 3. */
+    readonly maxRetries?: number;
+    /** First backoff ceiling, doubled per attempt with full jitter. Default 500 ms. */
+    readonly retryBaseDelayMs?: number;
+    /** Injectable transport, for tests or for Node < 18. */
+    readonly fetch?: FetchLike;
+    /** Injectable sleep, so tests do not wait on retries. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Client for the sinio.ai ingestion API.
+ *
+ * Every method accepts an arbitrarily long list and splits it into calls of
+ * 500 items, the API limit, merging the counters and rejections back into a
+ * single result. Sending the same events twice is safe: idempotency is keyed
+ * on `(project, source, source_event_id, revision)`, so a replay is counted as
+ * a duplicate rather than stored again.
+ */
+export declare class SinioClient {
+    private readonly transport;
+    private readonly authHeaders;
+    private readonly eventsPath;
+    private readonly webhookMode;
+    private readonly sourceCode;
+    private readonly project;
+    constructor(options: SinioClientOptions);
+    /** `POST /v1/events` — live ingestion. Derivation is asynchronous: a 200 confirms receipt only. */
+    sendEvents(events: readonly SinioEvent[], options?: SendEventsOptions): Promise<SendEventsResult>;
+    /**
+     * Same endpoint with `mode: "backfill"`: history is persisted but nothing is
+     * alerted, and derivation is replayed later in a canonical order.
+     */
+    backfillEvents(events: readonly SinioEvent[], options?: Omit<SendEventsOptions, "mode">): Promise<SendEventsResult>;
+    /**
+     * `POST /v1/entities` — bulk upsert keyed on `(kind, external_id)`. An unknown
+     * `subkind` never fails the call: it is created undeclared, for someone
+     * to qualify in the console.
+     */
+    upsertEntities(entities: readonly EntityInput[], options?: ProjectOptions): Promise<UpsertResult>;
+    /** `POST /v1/locations` — bulk upsert of the location tree, keyed on `external_id`. */
+    upsertLocations(locations: readonly LocationInput[], options?: ProjectOptions): Promise<UpsertResult>;
+    /**
+     * `POST /v1/assignments` — `credential -> subject` with a validity range. An
+     * overlap is rejected with `overlapping_assignment`, never merged silently.
+     */
+    createAssignments(assignments: readonly AssignmentInput[], options?: ProjectOptions): Promise<AssignmentsResult>;
+    private upsertReference;
+    private withProject;
+    private assertBearerMode;
+}

package/dist/cjs/client.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SinioClient = exports.SDK_VERSION = void 0;
+const errors_ts_1 = require("./errors.js");
+const http_ts_1 = require("./http.js");
+const serialize_ts_1 = require("./serialize.js");
+exports.SDK_VERSION = "0.2.0";
+/**
+ * Client for the sinio.ai ingestion API.
+ *
+ * Every method accepts an arbitrarily long list and splits it into calls of
+ * 500 items, the API limit, merging the counters and rejections back into a
+ * single result. Sending the same events twice is safe: idempotency is keyed
+ * on `(project, source, source_event_id, revision)`, so a replay is counted as
+ * a duplicate rather than stored again.
+ */
+class SinioClient {
+    transport;
+    authHeaders;
+    eventsPath;
+    webhookMode;
+    sourceCode;
+    project;
+    constructor(options) {
+        const hasApiKey = typeof options.apiKey === "string" && options.apiKey.length > 0;
+        const hasWebhookKey = typeof options.webhookKey === "string" && options.webhookKey.length > 0;
+        if (hasApiKey === hasWebhookKey) {
+            throw new errors_ts_1.SinioValidationError("Provide exactly one of `apiKey` or `webhookKey`.");
+        }
+        this.webhookMode = hasWebhookKey;
+        this.authHeaders = hasApiKey ? { authorization: `Bearer ${options.apiKey}` } : {};
+        this.eventsPath = hasWebhookKey ? `/v1/webhooks/${encodeURIComponent(options.webhookKey)}` : "/v1/events";
+        this.sourceCode = options.sourceCode;
+        this.project = options.project;
+        this.transport = new http_ts_1.Transport({
+            baseUrl: options.baseUrl ?? "https://api.sinio.ai",
+            timeoutMs: options.timeoutMs ?? 30_000,
+            maxRetries: options.maxRetries ?? 3,
+            retryBaseDelayMs: options.retryBaseDelayMs ?? 500,
+            userAgent: `sinio-node/${exports.SDK_VERSION}`,
+            fetch: options.fetch,
+            sleep: options.sleep,
+        });
+    }
+    /** `POST /v1/events` — live ingestion. Derivation is asynchronous: a 200 confirms receipt only. */
+    async sendEvents(events, options = {}) {
+        const mode = (0, serialize_ts_1.toWireMode)(options.mode ?? "webhook");
+        const wire = (0, serialize_ts_1.requireList)(events, "events").map((event, index) => (0, serialize_ts_1.toWireEvent)(withDefaultProject(event, this.project), index));
+        const sourceCode = options.sourceCode ?? this.sourceCode;
+        const headers = sourceCode === undefined ? {} : { "x-source-code": sourceCode };
+        const merged = {
+            batchIds: [],
+            accepted: 0,
+            pendingClassification: 0,
+            duplicates: 0,
+            revisions: 0,
+            rejected: 0,
+            rejections: [],
+            testMode: false,
+        };
+        for (const part of (0, serialize_ts_1.chunk)(wire, serialize_ts_1.MAX_ITEMS_PER_CALL)) {
+            const response = asRecord(await this.transport.post(this.eventsPath, { events: part, mode }, { ...this.authHeaders, ...headers }));
+            const batchId = asString(response["batch_id"]);
+            if (batchId !== null) {
+                merged.batchIds.push(batchId);
+            }
+            merged.accepted += asNumber(response["accepted"]);
+            merged.pendingClassification += asNumber(response["pending_classification"]);
+            merged.duplicates += asNumber(response["duplicates"]);
+            merged.revisions += asNumber(response["revisions"]);
+            merged.rejected += asNumber(response["rejected"]);
+            merged.testMode = merged.testMode || response["test_mode"] === true;
+            for (const rejection of asArray(response["rejections"])) {
+                const item = asRecord(rejection);
+                merged.rejections.push({
+                    sourceEventId: asString(item["source_event_id"]) ?? "",
+                    code: asCode(item["code"]),
+                    message: asString(item["message"]) ?? "",
+                });
+            }
+        }
+        return merged;
+    }
+    /**
+     * Same endpoint with `mode: "backfill"`: history is persisted but nothing is
+     * alerted, and derivation is replayed later in a canonical order.
+     */
+    async backfillEvents(events, options = {}) {
+        return this.sendEvents(events, { ...options, mode: "backfill" });
+    }
+    /**
+     * `POST /v1/entities` — bulk upsert keyed on `(kind, external_id)`. An unknown
+     * `subkind` never fails the call: it is created undeclared, for someone
+     * to qualify in the console.
+     */
+    async upsertEntities(entities, options = {}) {
+        this.assertBearerMode("upsertEntities");
+        return this.upsertReference("/v1/entities", "entities", (0, serialize_ts_1.requireList)(entities, "entities").map((entity, index) => (0, serialize_ts_1.toWireEntity)(entity, index)), options);
+    }
+    /** `POST /v1/locations` — bulk upsert of the location tree, keyed on `external_id`. */
+    async upsertLocations(locations, options = {}) {
+        this.assertBearerMode("upsertLocations");
+        return this.upsertReference("/v1/locations", "locations", (0, serialize_ts_1.requireList)(locations, "locations").map((location, index) => (0, serialize_ts_1.toWireLocation)(location, index)), options);
+    }
+    /**
+     * `POST /v1/assignments` — `credential -> subject` with a validity range. An
+     * overlap is rejected with `overlapping_assignment`, never merged silently.
+     */
+    async createAssignments(assignments, options = {}) {
+        this.assertBearerMode("createAssignments");
+        const wire = (0, serialize_ts_1.requireList)(assignments, "assignments").map((assignment, index) => (0, serialize_ts_1.toWireAssignment)(assignment, index));
+        const merged = {
+            accepted: 0,
+            rejected: 0,
+            rejections: [],
+        };
+        for (const part of (0, serialize_ts_1.chunk)(wire, serialize_ts_1.MAX_ITEMS_PER_CALL)) {
+            const response = asRecord(await this.transport.post("/v1/assignments", this.withProject({ assignments: part }, options), this.authHeaders));
+            merged.accepted += asNumber(response["accepted"]);
+            merged.rejected += asNumber(response["rejected"]);
+            for (const rejection of asArray(response["rejections"])) {
+                const item = asRecord(rejection);
+                merged.rejections.push({
+                    credential: asString(item["credential"]) ?? "",
+                    subject: asString(item["subject"]) ?? "",
+                    code: asCode(item["code"]),
+                    message: asString(item["message"]) ?? "",
+                });
+            }
+        }
+        return merged;
+    }
+    async upsertReference(path, key, wire, options) {
+        const merged = {
+            accepted: 0,
+            rejected: 0,
+            rejections: [],
+        };
+        for (const part of (0, serialize_ts_1.chunk)(wire, serialize_ts_1.MAX_ITEMS_PER_CALL)) {
+            const response = asRecord(await this.transport.post(path, this.withProject({ [key]: part }, options), this.authHeaders));
+            merged.accepted += asNumber(response["accepted"]);
+            merged.rejected += asNumber(response["rejected"]);
+            for (const rejection of asArray(response["rejections"])) {
+                const item = asRecord(rejection);
+                merged.rejections.push({
+                    externalId: asString(item["external_id"]) ?? "",
+                    code: asCode(item["code"]),
+                    message: asString(item["message"]) ?? "",
+                });
+            }
+        }
+        return merged;
+    }
+    withProject(body, options) {
+        const project = optionalProject(options.project) ?? this.project;
+        return project === undefined ? body : { project, ...body };
+    }
+    assertBearerMode(operation) {
+        if (this.webhookMode) {
+            throw new errors_ts_1.SinioValidationError(`${operation} requires an API key: a webhook key only authenticates event ingestion.`);
+        }
+    }
+}
+exports.SinioClient = SinioClient;
+/** The client-level project applies only to an event that does not name its own. */
+function withDefaultProject(event, project) {
+    if (project === undefined || typeof event !== "object" || event === null || event.project !== undefined) {
+        return event;
+    }
+    return { ...event, project };
+}
+function optionalProject(value) {
+    if (value !== undefined && typeof value !== "string") {
+        throw new errors_ts_1.SinioValidationError(`project must be a string (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+/** A known code or any code the API adds later, kept as is; never a reason to fail. */
+function asCode(value) {
+    return asString(value) ?? "unknown";
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,35 @@
+import type { RejectionCodeValue } from "./types.ts";
+/** Base class for every error the SDK throws. */
+export declare class SinioError extends Error {
+    constructor(message: string);
+}
+/** The request never got a usable HTTP response (DNS, TCP, TLS, timeout). */
+export declare class SinioConnectionError extends SinioError {
+    readonly reason: unknown;
+    constructor(message: string, reason?: unknown);
+}
+/** A 4xx or 5xx response. */
+export declare class SinioApiError extends SinioError {
+    readonly status: number;
+    readonly body: unknown;
+    /** Rejection code returned by the API, when the body carries one (a known `RejectionCode` or a newer one). */
+    readonly code: RejectionCodeValue | null;
+    constructor(message: string, status: number, body: unknown, code?: RejectionCodeValue | null);
+}
+/** 401 / 403 — invalid, revoked, or insufficiently scoped key. Never replay. */
+export declare class SinioAuthError extends SinioApiError {
+}
+/** 400 / 404 / 413 — the request itself is wrong. Fix it before replaying. */
+export declare class SinioRequestError extends SinioApiError {
+}
+/** 429 — quota exceeded. `retryAfterSeconds` mirrors the `Retry-After` header. */
+export declare class SinioRateLimitError extends SinioApiError {
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, status: number, body: unknown, retryAfterSeconds: number | null);
+}
+/** 5xx — temporary. Safe to replay verbatim: ingestion is idempotent. */
+export declare class SinioServerError extends SinioApiError {
+}
+/** Raised before any network call, when the input cannot be a valid request. */
+export declare class SinioValidationError extends SinioError {
+}

package/dist/cjs/errors.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SinioValidationError = exports.SinioServerError = exports.SinioRateLimitError = exports.SinioRequestError = exports.SinioAuthError = exports.SinioApiError = exports.SinioConnectionError = exports.SinioError = void 0;
+/** Base class for every error the SDK throws. */
+class SinioError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.SinioError = SinioError;
+/** The request never got a usable HTTP response (DNS, TCP, TLS, timeout). */
+class SinioConnectionError extends SinioError {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+exports.SinioConnectionError = SinioConnectionError;
+/** A 4xx or 5xx response. */
+class SinioApiError extends SinioError {
+    status;
+    body;
+    /** Rejection code returned by the API, when the body carries one (a known `RejectionCode` or a newer one). */
+    code;
+    constructor(message, status, body, code = null) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.code = code;
+    }
+}
+exports.SinioApiError = SinioApiError;
+/** 401 / 403 — invalid, revoked, or insufficiently scoped key. Never replay. */
+class SinioAuthError extends SinioApiError {
+}
+exports.SinioAuthError = SinioAuthError;
+/** 400 / 404 / 413 — the request itself is wrong. Fix it before replaying. */
+class SinioRequestError extends SinioApiError {
+}
+exports.SinioRequestError = SinioRequestError;
+/** 429 — quota exceeded. `retryAfterSeconds` mirrors the `Retry-After` header. */
+class SinioRateLimitError extends SinioApiError {
+    retryAfterSeconds;
+    constructor(message, status, body, retryAfterSeconds) {
+        super(message, status, body);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+exports.SinioRateLimitError = SinioRateLimitError;
+/** 5xx — temporary. Safe to replay verbatim: ingestion is idempotent. */
+class SinioServerError extends SinioApiError {
+}
+exports.SinioServerError = SinioServerError;
+/** Raised before any network call, when the input cannot be a valid request. */
+class SinioValidationError extends SinioError {
+}
+exports.SinioValidationError = SinioValidationError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAEA,iDAAiD;AACjD,MAAa,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AALD,gCAKC;AAED,6EAA6E;AAC7E,MAAa,oBAAqB,SAAQ,UAAU;IACzC,MAAM,CAAU;IAEzB,YAAY,OAAe,EAAE,MAAgB;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAPD,oDAOC;AAED,6BAA6B;AAC7B,MAAa,aAAc,SAAQ,UAAU;IAClC,MAAM,CAAS;IACf,IAAI,CAAU;IACvB,8GAA8G;IACrG,IAAI,CAA4B;IAEzC,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa,EAAE,OAAkC,IAAI;QAChG,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAZD,sCAYC;AAED,gFAAgF;AAChF,MAAa,cAAe,SAAQ,aAAa;CAAG;AAApD,wCAAoD;AAEpD,8EAA8E;AAC9E,MAAa,iBAAkB,SAAQ,aAAa;CAAG;AAAvD,8CAAuD;AAEvD,kFAAkF;AAClF,MAAa,mBAAoB,SAAQ,aAAa;IAC3C,iBAAiB,CAAgB;IAE1C,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa,EAAE,iBAAgC;QAC1F,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;IAC7C,CAAC;CACF;AAPD,kDAOC;AAED,yEAAyE;AACzE,MAAa,gBAAiB,SAAQ,aAAa;CAAG;AAAtD,4CAAsD;AAEtD,gFAAgF;AAChF,MAAa,oBAAqB,SAAQ,UAAU;CAAG;AAAvD,oDAAuD"}

package/dist/cjs/http.d.ts

@@ -0,0 +1,22 @@
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface TransportOptions {
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly retryBaseDelayMs: number;
+    readonly userAgent: string;
+    readonly fetch?: FetchLike | undefined;
+    /** Injected in tests so retries do not actually wait. */
+    readonly sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+/** `Retry-After` is either a delay in seconds or an HTTP date. Both are accepted. */
+export declare function parseRetryAfter(header: string | null, now?: number): number | null;
+export declare class Transport {
+    private readonly options;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(options: TransportOptions);
+    post(path: string, body: unknown, headers: Record<string, string>): Promise<unknown>;
+    /** Exponential backoff with full jitter, unless the server told us how long to wait. */
+    private backoffMs;
+}