@sinio/sdk 0.0.0-stage → 0.1.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,118 @@
-# 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.** A timestamp without a UTC offset is rejected before any
+  call, with the API's own rule, instead of coming back as an `invalid_occurred_at` rejection.
+- **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.
+
+## 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,69 @@
+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.1.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`; optional when the key is already bound to a source. */
+    readonly sourceCode?: string;
+    /** Default project `external_id`, for publisher-level keys covering several projects. */
+    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,176 @@
+"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.1.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 wire = events.map((event, index) => (0, serialize_ts_1.toWireEvent)(this.project === undefined || event.project !== undefined ? event : { ...event, project: 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 body = { events: part, mode: options.mode ?? "webhook" };
+            const response = asRecord(await this.transport.post(this.eventsPath, body, { ...this.authHeaders, ...headers }));
+            const batchId = asString(response["batch_id"]);
+            if (batchId !== null) {
+                merged.batchIds.push(batchId);
+            }
+            Object.assign(merged, {
+                accepted: merged.accepted + asNumber(response["accepted"]),
+                pendingClassification: merged.pendingClassification + asNumber(response["pending_classification"]),
+                duplicates: merged.duplicates + asNumber(response["duplicates"]),
+                revisions: merged.revisions + asNumber(response["revisions"]),
+                rejected: merged.rejected + asNumber(response["rejected"]),
+                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: asString(item["code"]) ?? "unknown",
+                    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 = {}) {
+        return this.upsertReference("/v1/entities", "entities", entities.map(serialize_ts_1.toWireEntity), options);
+    }
+    /** `POST /v1/locations` — bulk upsert of the location tree, keyed on `external_id`. */
+    async upsertLocations(locations, options = {}) {
+        return this.upsertReference("/v1/locations", "locations", locations.map(serialize_ts_1.toWireLocation), 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 = assignments.map(serialize_ts_1.toWireAssignment);
+        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));
+            Object.assign(merged, {
+                accepted: merged.accepted + asNumber(response["accepted"]),
+                rejected: 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: asString(item["code"]) ?? "unknown",
+                    message: asString(item["message"]) ?? "",
+                });
+            }
+        }
+        return merged;
+    }
+    async upsertReference(path, key, wire, options) {
+        this.assertBearerMode(path);
+        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));
+            Object.assign(merged, {
+                accepted: merged.accepted + asNumber(response["accepted"]),
+                rejected: 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: asString(item["code"]) ?? "unknown",
+                    message: asString(item["message"]) ?? "",
+                });
+            }
+        }
+        return merged;
+    }
+    withProject(body, options) {
+        const project = 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;
+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,34 @@
+/** 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. */
+    readonly code: string | null;
+    constructor(message: string, status: number, body: unknown, code?: string | 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. */
+    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":";;;AAAA,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,qEAAqE;IAC5D,IAAI,CAAgB;IAE7B,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa,EAAE,OAAsB,IAAI;QACpF,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;
+    /** Injected in tests so retries do not actually wait. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/** `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;
+}

package/dist/cjs/http.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transport = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+const errors_ts_1 = require("./errors.js");
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** `Retry-After` is either a delay in seconds or an HTTP date. Both are accepted. */
+function parseRetryAfter(header, now = Date.now()) {
+    if (header === null) {
+        return null;
+    }
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, seconds);
+    }
+    const date = Date.parse(header);
+    if (Number.isNaN(date)) {
+        return null;
+    }
+    return Math.max(0, (date - now) / 1000);
+}
+/**
+ * A 429 or a 5xx is retried, and so is a dropped connection: ingestion is
+ * idempotent, so a replay can only ever be counted as a duplicate. A 4xx that
+ * is not a 429 is the caller's fault and is raised immediately.
+ */
+function isRetriableStatus(status) {
+    return status === 429 || status >= 500;
+}
+class Transport {
+    options;
+    fetchImpl;
+    sleep;
+    constructor(options) {
+        this.options = options;
+        const provided = options.fetch ?? globalThis.fetch;
+        if (provided === undefined) {
+            throw new Error("No global fetch available; pass `fetch` in the client options (Node < 18).");
+        }
+        this.fetchImpl = provided;
+        this.sleep = options.sleep ?? defaultSleep;
+    }
+    async post(path, body, headers) {
+        const url = `${this.options.baseUrl.replace(/\/+$/, "")}${path}`;
+        const payload = JSON.stringify(body);
+        let attempt = 0;
+        for (;;) {
+            let response;
+            try {
+                response = await this.fetchImpl(url, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/json",
+                        accept: "application/json",
+                        "user-agent": this.options.userAgent,
+                        ...headers,
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(this.options.timeoutMs),
+                });
+            }
+            catch (cause) {
+                if (attempt >= this.options.maxRetries) {
+                    throw new errors_ts_1.SinioConnectionError(`Request to ${url} failed: ${String(cause)}`, cause);
+                }
+                await this.sleep(this.backoffMs(attempt, null));
+                attempt += 1;
+                continue;
+            }
+            if (response.ok) {
+                return await readJson(response);
+            }
+            const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+            if (isRetriableStatus(response.status) && attempt < this.options.maxRetries) {
+                await this.sleep(this.backoffMs(attempt, retryAfter));
+                attempt += 1;
+                continue;
+            }
+            throw await toApiError(response, retryAfter);
+        }
+    }
+    /** Exponential backoff with full jitter, unless the server told us how long to wait. */
+    backoffMs(attempt, retryAfterSeconds) {
+        if (retryAfterSeconds !== null) {
+            return retryAfterSeconds * 1000;
+        }
+        const ceiling = Math.min(this.options.retryBaseDelayMs * 2 ** attempt, 30_000);
+        return Math.random() * ceiling;
+    }
+}
+exports.Transport = Transport;
+async function readJson(response) {
+    const text = await response.text();
+    if (text.length === 0) {
+        return null;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+async function toApiError(response, retryAfterSeconds) {
+    const body = await readJson(response);
+    const code = extractCode(body);
+    const message = `${response.status} ${response.statusText}: ${extractMessage(body) ?? "no message"}`;
+    if (response.status === 401 || response.status === 403) {
+        return new errors_ts_1.SinioAuthError(message, response.status, body, code);
+    }
+    if (response.status === 429) {
+        return new errors_ts_1.SinioRateLimitError(message, response.status, body, retryAfterSeconds);
+    }
+    if (response.status >= 500) {
+        return new errors_ts_1.SinioServerError(message, response.status, body, code);
+    }
+    return new errors_ts_1.SinioRequestError(message, response.status, body, code);
+}
+function extractCode(body) {
+    if (typeof body === "object" && body !== null && "code" in body && typeof body.code === "string") {
+        return body.code;
+    }
+    return null;
+}
+function extractMessage(body) {
+    if (typeof body === "string") {
+        return body;
+    }
+    if (typeof body !== "object" || body === null || !("message" in body)) {
+        return null;
+    }
+    const { message } = body;
+    // NestJS's ValidationPipe returns an array of messages, one per failed rule.
+    if (Array.isArray(message)) {
+        return message.join("; ");
+    }
+    return typeof message === "string" ? message : null;
+}
+//# sourceMappingURL=http.js.map