@sinio/sdk 0.0.0-stage → 0.1.0

package/dist/esm/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/esm/http.js

@@ -0,0 +1,134 @@
+import { SinioAuthError, SinioConnectionError, SinioRateLimitError, SinioRequestError, SinioServerError, } from "./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. */
+export 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;
+}
+export 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 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;
+    }
+}
+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 SinioAuthError(message, response.status, body, code);
+    }
+    if (response.status === 429) {
+        return new SinioRateLimitError(message, response.status, body, retryAfterSeconds);
+    }
+    if (response.status >= 500) {
+        return new SinioServerError(message, response.status, body, code);
+    }
+    return new 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

package/dist/esm/http.js.map

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

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { SinioClient, SDK_VERSION, type SinioClientOptions } from "./client.ts";
+export { SinioApiError, SinioAuthError, SinioConnectionError, SinioError, SinioRateLimitError, SinioRequestError, SinioServerError, SinioValidationError, } from "./errors.ts";
+export { MAX_ITEMS_PER_CALL } from "./serialize.ts";
+export type * from "./types.ts";

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { SinioClient, SDK_VERSION } from "./client.js";
+export { SinioApiError, SinioAuthError, SinioConnectionError, SinioError, SinioRateLimitError, SinioRequestError, SinioServerError, SinioValidationError, } from "./errors.js";
+export { MAX_ITEMS_PER_CALL } from "./serialize.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAA2B,MAAM,aAAa,CAAC;AAChF,OAAO,EACL,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/esm/serialize.d.ts

@@ -0,0 +1,11 @@
+import type { AssignmentInput, EntityInput, LocationInput, SinioEvent, Timestamp } from "./types.ts";
+/** The API caps every collection at 500 items per call. */
+export declare const MAX_ITEMS_PER_CALL = 500;
+/** The most units one event may stand for. */
+export declare const MAX_EVENT_COUNT = 1000000;
+export declare function toIso(value: Timestamp, field: string): string;
+export declare function chunk<T>(items: readonly T[], size: number): T[][];
+export declare function toWireEvent(event: SinioEvent, index: number): Record<string, unknown>;
+export declare function toWireEntity(entity: EntityInput, index: number): Record<string, unknown>;
+export declare function toWireLocation(location: LocationInput, index: number): Record<string, unknown>;
+export declare function toWireAssignment(assignment: AssignmentInput, index: number): Record<string, unknown>;

package/dist/esm/serialize.js

@@ -0,0 +1,102 @@
+import { SinioValidationError } from "./errors.js";
+/** The API caps every collection at 500 items per call. */
+export const MAX_ITEMS_PER_CALL = 500;
+/** The most units one event may stand for. */
+export const MAX_EVENT_COUNT = 1_000_000;
+// The API's own rule: a `T`, seconds, an optional fraction, then `Z` or an offset. It rejects the
+// event otherwise (`invalid_occurred_at`); refused here, it is a fixable local error before any call.
+const ISO_WITH_OFFSET = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})$/;
+export function toIso(value, field) {
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new SinioValidationError(`${field} is an invalid Date`);
+        }
+        return value.toISOString();
+    }
+    if (typeof value !== "string" || !ISO_WITH_OFFSET.test(value)) {
+        throw new SinioValidationError(`${field} must be an ISO 8601 timestamp with an offset (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+/** Drops `undefined` keys so they never reach the wire as `null`. */
+function compact(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}
+export function chunk(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}
+export function toWireEvent(event, index) {
+    if (!event.sourceEventId) {
+        throw new SinioValidationError(`events[${index}].sourceEventId is required`);
+    }
+    if (!event.type) {
+        throw new SinioValidationError(`events[${index}].type is required`);
+    }
+    if (event.payload !== undefined &&
+        (typeof event.payload !== "object" || event.payload === null || Array.isArray(event.payload))) {
+        throw new SinioValidationError(`events[${index}].payload must be an object`);
+    }
+    if (event.count !== undefined && (!Number.isInteger(event.count) || event.count < 1 || event.count > MAX_EVENT_COUNT)) {
+        throw new SinioValidationError(`events[${index}].count must be an integer between 1 and ${MAX_EVENT_COUNT}`);
+    }
+    return compact({
+        source_event_id: event.sourceEventId,
+        source_version: event.sourceVersion,
+        project: event.project,
+        type: event.type,
+        label: event.label,
+        occurred_at: toIso(event.occurredAt, `events[${index}].occurredAt`),
+        roles: event.roles === undefined ? undefined : compact({ ...event.roles }),
+        payload: event.payload,
+        count: event.count,
+    });
+}
+export function toWireEntity(entity, index) {
+    if (!entity.externalId) {
+        throw new SinioValidationError(`entities[${index}].externalId is required`);
+    }
+    if (!entity.kind) {
+        throw new SinioValidationError(`entities[${index}].kind is required`);
+    }
+    return compact({
+        external_id: entity.externalId,
+        kind: entity.kind,
+        subkind: entity.subkind,
+        label: entity.label,
+        location: entity.location,
+        attributes: entity.attributes,
+    });
+}
+export function toWireLocation(location, index) {
+    if (!location.externalId) {
+        throw new SinioValidationError(`locations[${index}].externalId is required`);
+    }
+    if (!location.name) {
+        throw new SinioValidationError(`locations[${index}].name is required`);
+    }
+    return compact({
+        external_id: location.externalId,
+        kind: location.kind,
+        name: location.name,
+        parent: location.parent,
+    });
+}
+export function toWireAssignment(assignment, index) {
+    if (!assignment.credential || !assignment.subject) {
+        throw new SinioValidationError(`assignments[${index}] requires both credential and subject`);
+    }
+    return compact({
+        credential: assignment.credential,
+        subject: assignment.subject,
+        relation: assignment.relation,
+        valid_from: toIso(assignment.validFrom, `assignments[${index}].validFrom`),
+        valid_to: assignment.validTo === undefined || assignment.validTo === null
+            ? undefined
+            : toIso(assignment.validTo, `assignments[${index}].validTo`),
+    });
+}
+//# sourceMappingURL=serialize.js.map

package/dist/esm/serialize.js.map

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

package/dist/esm/types.d.ts

@@ -0,0 +1,114 @@
+/** Ingestion mode. `backfill` persists history without triggering alerts. */
+export type IngestionMode = "webhook" | "backfill";
+/** Kinds accepted by `POST /v1/entities`. */
+export type EntityKind = "device" | "subject" | "asset" | "actor" | "credential";
+/** Levels accepted by `POST /v1/locations`. */
+export type LocationLevel = "site" | "zone" | "point";
+/** An ISO 8601 timestamp *with* an offset, or a `Date`. */
+export type Timestamp = string | Date;
+/**
+ * The four structural roles the derivation engine resolves, each a raw
+ * identifier from the source. Anything else (ticket number, firmware, ...)
+ * belongs in `payload`. The API refuses any other key.
+ */
+export interface EventRoles {
+    readonly device?: string;
+    readonly subject?: string;
+    readonly location?: string;
+    readonly actor?: string;
+}
+export interface SinioEvent {
+    /** Identity at the source, stable over time. Part of the idempotency key. */
+    readonly sourceEventId: string;
+    /** Source-side version, kept for tracing: it plays no part in deduplication. */
+    readonly sourceVersion?: string;
+    /** Project `external_id`. Required for publisher-level keys, forbidden for project-level ones. */
+    readonly project?: string;
+    /** `code` of an event type in the catalog. */
+    readonly type: string;
+    readonly label?: string;
+    /** ISO 8601 with offset. Without an offset the API rejects the event. */
+    readonly occurredAt: Timestamp;
+    readonly roles?: EventRoles;
+    /** Free-form, optional (`{}` when omitted); the readings (battery, signal, ...) are read from it as its source declares them. */
+    readonly payload?: Record<string, unknown>;
+    /** How many units this one event stands for (a button pressed ten times). An integer from 1 to 1,000,000; omitted = 1. */
+    readonly count?: number;
+}
+export interface EntityInput {
+    readonly externalId: string;
+    readonly kind: EntityKind;
+    readonly subkind?: string;
+    readonly label?: string;
+    /** External id of the location the entity sits in. */
+    readonly location?: string;
+    readonly attributes?: Record<string, unknown>;
+}
+export interface LocationInput {
+    readonly externalId: string;
+    readonly kind: LocationLevel;
+    readonly name: string;
+    /** External id of the parent location, if any. */
+    readonly parent?: string;
+}
+export interface AssignmentInput {
+    /** External id of the credential (badge, card, ...). */
+    readonly credential: string;
+    /** External id of the subject the credential is assigned to. */
+    readonly subject: string;
+    readonly relation?: string;
+    readonly validFrom: Timestamp;
+    readonly validTo?: Timestamp | null;
+}
+export interface EventRejection {
+    readonly sourceEventId: string;
+    readonly code: string;
+    readonly message: string;
+}
+export interface ReferenceRejection {
+    readonly externalId: string;
+    readonly code: string;
+    readonly message: string;
+}
+export interface AssignmentRejection {
+    readonly credential: string;
+    readonly subject: string;
+    readonly code: string;
+    readonly message: string;
+}
+/**
+ * Outcome of `sendEvents`. `duplicates` and `revisions` are successes, not
+ * errors: replaying a batch is expected and never creates anything twice.
+ */
+export interface SendEventsResult {
+    /** Server-side batch ids, one per HTTP call the SDK made (batches are chunked at 500). */
+    readonly batchIds: string[];
+    readonly accepted: number;
+    readonly pendingClassification: number;
+    readonly duplicates: number;
+    readonly revisions: number;
+    readonly rejected: number;
+    readonly rejections: EventRejection[];
+    /** The key is in test mode: its events are checked and kept apart, never used for detection. */
+    readonly testMode: boolean;
+}
+export interface UpsertResult {
+    readonly accepted: number;
+    readonly rejected: number;
+    readonly rejections: ReferenceRejection[];
+}
+export interface AssignmentsResult {
+    readonly accepted: number;
+    readonly rejected: number;
+    readonly rejections: AssignmentRejection[];
+}
+export interface SendEventsOptions {
+    /** Defaults to `webhook`. */
+    readonly mode?: IngestionMode;
+    /** Overrides the client-level source code for this call. */
+    readonly sourceCode?: string;
+}
+/** Project override, for publisher-level API keys covering several projects. */
+export interface ProjectOptions {
+    readonly project?: string;
+}

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@sinio/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Official Node.js SDK for the sinio.ai ingestion API (events, entities, locations, assignments).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.json --noEmit && node --test --experimental-strip-types test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "sinio",
+    "events",
+    "ingestion",
+    "sdk"
+  ]
+}