@sinio/sdk 0.0.0-stage → 0.2.0

package/dist/esm/serialize.js

@@ -0,0 +1,179 @@
+import { SinioValidationError } from "./errors.js";
+import { ASSIGNMENT_RELATIONS, ENTITY_KINDS, EVENT_ROLES, INGESTION_MODES, LOCATION_LEVELS } from "./vocabularies.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;
+}
+// Local checks, each the API's own rule: the types already say it to TypeScript callers, these say it
+// at runtime to plain JavaScript and to values typed loosely (`as`, `any`, parsed JSON).
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function requireItem(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new SinioValidationError(`${field} must be an object (got ${describe(value)})`);
+    }
+    return value;
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new SinioValidationError(`${field} is required and must be a non-empty string (got ${describe(value)})`);
+    }
+    return value;
+}
+function optionalString(value, field) {
+    if (value !== undefined && typeof value !== "string") {
+        throw new SinioValidationError(`${field} must be a string (got ${describe(value)})`);
+    }
+    return value;
+}
+function optionalNonEmptyString(value, field) {
+    return value === undefined ? undefined : requireString(value, field);
+}
+function optionalObject(value, field) {
+    if (value !== undefined && !isPlainObject(value)) {
+        throw new SinioValidationError(`${field} must be a JSON object (got ${describe(value)})`);
+    }
+    return value;
+}
+export function requireOneOf(value, values, field) {
+    if (typeof value !== "string" || !values.includes(value)) {
+        throw new SinioValidationError(`${field} must be one of ${values.join(", ")} (got ${describe(value)})`);
+    }
+    return value;
+}
+export function requireList(value, field) {
+    if (!Array.isArray(value)) {
+        throw new SinioValidationError(`${field} must be an array (got ${describe(value)})`);
+    }
+    return value;
+}
+export function toWireMode(mode) {
+    return requireOneOf(mode, INGESTION_MODES, "mode");
+}
+function describe(value) {
+    if (value === undefined) {
+        return "undefined";
+    }
+    if (Array.isArray(value)) {
+        return "an array";
+    }
+    if (value instanceof Date) {
+        return "a Date";
+    }
+    return JSON.stringify(value) ?? String(value);
+}
+function toWireRoles(value, field) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const roles = requireItem(value, field);
+    for (const key of Object.keys(roles)) {
+        if (!EVENT_ROLES.includes(key)) {
+            throw new SinioValidationError(`${field}.${key} is not a role: roles are ${EVENT_ROLES.join(", ")}`);
+        }
+    }
+    return compact({
+        device: optionalNonEmptyString(roles["device"], `${field}.device`),
+        subject: optionalNonEmptyString(roles["subject"], `${field}.subject`),
+        location: optionalNonEmptyString(roles["location"], `${field}.location`),
+        actor: optionalNonEmptyString(roles["actor"], `${field}.actor`),
+    });
+}
+export function toWireEvent(event, index) {
+    const at = `events[${index}]`;
+    const item = requireItem(event, at);
+    const count = item["count"];
+    if (count !== undefined && (!Number.isInteger(count) || count < 1 || count > MAX_EVENT_COUNT)) {
+        throw new SinioValidationError(`${at}.count must be an integer between 1 and ${MAX_EVENT_COUNT} (got ${describe(count)})`);
+    }
+    return compact({
+        source_event_id: requireString(item["sourceEventId"], `${at}.sourceEventId`),
+        source_version: optionalString(item["sourceVersion"], `${at}.sourceVersion`),
+        project: optionalString(item["project"], `${at}.project`),
+        type: requireString(item["type"], `${at}.type`),
+        label: optionalString(item["label"], `${at}.label`),
+        occurred_at: toIso(requireTimestamp(item["occurredAt"], `${at}.occurredAt`), `${at}.occurredAt`),
+        roles: toWireRoles(item["roles"], `${at}.roles`),
+        payload: optionalObject(item["payload"], `${at}.payload`),
+        count: count,
+    });
+}
+export function toWireEntity(entity, index) {
+    const at = `entities[${index}]`;
+    const item = requireItem(entity, at);
+    return compact({
+        external_id: requireString(item["externalId"], `${at}.externalId`),
+        kind: requireOneOf(item["kind"], ENTITY_KINDS, `${at}.kind`),
+        subkind: optionalNonEmptyString(item["subkind"], `${at}.subkind`),
+        label: optionalString(item["label"], `${at}.label`),
+        location: optionalString(item["location"], `${at}.location`),
+        attributes: optionalObject(item["attributes"], `${at}.attributes`),
+    });
+}
+export function toWireLocation(location, index) {
+    const at = `locations[${index}]`;
+    const item = requireItem(location, at);
+    return compact({
+        external_id: requireString(item["externalId"], `${at}.externalId`),
+        kind: requireOneOf(item["kind"], LOCATION_LEVELS, `${at}.kind`),
+        name: requireString(item["name"], `${at}.name`),
+        parent: optionalString(item["parent"], `${at}.parent`),
+    });
+}
+export function toWireAssignment(assignment, index) {
+    const at = `assignments[${index}]`;
+    const item = requireItem(assignment, at);
+    const relation = item["relation"];
+    const validFrom = toIso(requireTimestamp(item["validFrom"], `${at}.validFrom`), `${at}.validFrom`);
+    const rawValidTo = item["validTo"];
+    const validTo = rawValidTo === undefined || rawValidTo === null ? undefined : toIso(rawValidTo, `${at}.validTo`);
+    // The API's `invalid_validity_period`: an assignment has to end after it starts.
+    if (validTo !== undefined && Date.parse(validTo) <= Date.parse(validFrom)) {
+        throw new SinioValidationError(`${at}.validTo must be after validFrom (got ${validFrom} -> ${validTo})`);
+    }
+    return compact({
+        credential: requireString(item["credential"], `${at}.credential`),
+        subject: requireString(item["subject"], `${at}.subject`),
+        relation: relation === undefined ? undefined : requireOneOf(relation, ASSIGNMENT_RELATIONS, `${at}.relation`),
+        valid_from: validFrom,
+        valid_to: validTo,
+    });
+}
+function requireTimestamp(value, field) {
+    if (value === undefined || value === null || value === "") {
+        throw new SinioValidationError(`${field} is required`);
+    }
+    return value;
+}
+//# 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,126 @@
+import type { AssignmentRelation, EntityKind, EventRole, IngestionMode, LocationLevel, RejectionCode } from "./vocabularies.ts";
+export type { AssignmentRelation, EntityKind, EventRole, IngestionMode, LocationLevel, RejectionCode };
+/**
+ * A rejection code as read from a response: one of the known `RejectionCode`s (autocompleted), or
+ * any other string the API may add later, kept as is.
+ */
+export type RejectionCodeValue = RejectionCode | (string & {});
+/** A JSON object: `payload` and `attributes` are never an array or a scalar. */
+export type JsonObject = Readonly<Record<string, unknown>>;
+/** 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, non-empty
+ * identifier from the source. Anything else (ticket number, firmware, ...)
+ * belongs in `payload`. The API refuses any other key.
+ */
+export type EventRoles = {
+    readonly [role in EventRole]?: 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`. Only for organization-wide keys (issued on request), which cover several projects; a project key already carries its project. */
+    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?: JsonObject;
+    /** 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;
+    /** Code of the entity's subkind; never empty when given. An unknown code is created undeclared. */
+    readonly subkind?: string;
+    readonly label?: string;
+    /** External id of the location the entity sits in. */
+    readonly location?: string;
+    /** Free-form JSON object. */
+    readonly attributes?: JsonObject;
+}
+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;
+    /** Defaults to `assigned_to`, the only relation today. */
+    readonly relation?: AssignmentRelation;
+    /** ISO 8601 with offset, or a `Date`. */
+    readonly validFrom: Timestamp;
+    /** Open-ended when omitted or `null`; otherwise strictly after `validFrom`. */
+    readonly validTo?: Timestamp | null;
+}
+export interface EventRejection {
+    readonly sourceEventId: string;
+    readonly code: RejectionCodeValue;
+    readonly message: string;
+}
+export interface ReferenceRejection {
+    readonly externalId: string;
+    readonly code: RejectionCodeValue;
+    readonly message: string;
+}
+export interface AssignmentRejection {
+    readonly credential: string;
+    readonly subject: string;
+    readonly code: RejectionCodeValue;
+    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: readonly string[];
+    readonly accepted: number;
+    readonly pendingClassification: number;
+    readonly duplicates: number;
+    readonly revisions: number;
+    readonly rejected: number;
+    readonly rejections: readonly 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: readonly ReferenceRejection[];
+}
+export interface AssignmentsResult {
+    readonly accepted: number;
+    readonly rejected: number;
+    readonly rejections: readonly AssignmentRejection[];
+}
+export interface SendEventsOptions {
+    /** Defaults to `webhook`. */
+    readonly mode?: IngestionMode;
+    /**
+     * Overrides the client-level source code for this call. Only needed for keys not bound to a
+     * single source (organization-wide keys, issued on request).
+     */
+    readonly sourceCode?: string;
+}
+/**
+ * Project override, only for organization-wide API keys (issued on request) covering several
+ * projects. A project key already carries its project.
+ */
+export interface ProjectOptions {
+    /** Project `external_id`. */
+    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/dist/esm/vocabularies.d.ts

@@ -0,0 +1,23 @@
+/** Ingestion modes. `backfill` persists history without triggering alerts. */
+export declare const INGESTION_MODES: readonly ["webhook", "backfill"];
+export type IngestionMode = (typeof INGESTION_MODES)[number];
+/** Kinds accepted by `POST /v1/entities`. */
+export declare const ENTITY_KINDS: readonly ["device", "subject", "asset", "actor", "credential"];
+export type EntityKind = (typeof ENTITY_KINDS)[number];
+/** Levels accepted by `POST /v1/locations`. */
+export declare const LOCATION_LEVELS: readonly ["site", "zone", "point"];
+export type LocationLevel = (typeof LOCATION_LEVELS)[number];
+/** Relations accepted by `POST /v1/assignments`; `assigned_to` when omitted. */
+export declare const ASSIGNMENT_RELATIONS: readonly ["assigned_to"];
+export type AssignmentRelation = (typeof ASSIGNMENT_RELATIONS)[number];
+/** The four structural roles an event may carry in `roles`. */
+export declare const EVENT_ROLES: readonly ["device", "subject", "location", "actor"];
+export type EventRole = (typeof EVENT_ROLES)[number];
+/**
+ * Codes the API returns in `rejections[].code` today. The list may grow (additive changes): a
+ * response carrying a code missing here is passed through unchanged, never refused.
+ */
+export declare const REJECTION_CODES: readonly ["payload_too_large", "unknown_project", "unknown_source", "archived_source", "source_mismatch", "ambiguous_source", "invalid_occurred_at", "missing_required_field", "unknown_location", "unknown_parent_location", "overlapping_assignment", "invalid_validity_period"];
+export type RejectionCode = (typeof REJECTION_CODES)[number];
+/** Whether a rejection code is one this SDK version knows, narrowing it to `RejectionCode`. */
+export declare function isKnownRejectionCode(code: string): code is RejectionCode;

package/dist/esm/vocabularies.js

@@ -0,0 +1,35 @@
+// The closed vocabularies of the ingestion API, each defined once: the value list (used by the local
+// checks) and the type derived from it. They mirror the API contract exactly.
+/** Ingestion modes. `backfill` persists history without triggering alerts. */
+export const INGESTION_MODES = ["webhook", "backfill"];
+/** Kinds accepted by `POST /v1/entities`. */
+export const ENTITY_KINDS = ["device", "subject", "asset", "actor", "credential"];
+/** Levels accepted by `POST /v1/locations`. */
+export const LOCATION_LEVELS = ["site", "zone", "point"];
+/** Relations accepted by `POST /v1/assignments`; `assigned_to` when omitted. */
+export const ASSIGNMENT_RELATIONS = ["assigned_to"];
+/** The four structural roles an event may carry in `roles`. */
+export const EVENT_ROLES = ["device", "subject", "location", "actor"];
+/**
+ * Codes the API returns in `rejections[].code` today. The list may grow (additive changes): a
+ * response carrying a code missing here is passed through unchanged, never refused.
+ */
+export const REJECTION_CODES = [
+    "payload_too_large",
+    "unknown_project",
+    "unknown_source",
+    "archived_source",
+    "source_mismatch",
+    "ambiguous_source",
+    "invalid_occurred_at",
+    "missing_required_field",
+    "unknown_location",
+    "unknown_parent_location",
+    "overlapping_assignment",
+    "invalid_validity_period",
+];
+/** Whether a rejection code is one this SDK version knows, narrowing it to `RejectionCode`. */
+export function isKnownRejectionCode(code) {
+    return REJECTION_CODES.includes(code);
+}
+//# sourceMappingURL=vocabularies.js.map

package/dist/esm/vocabularies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabularies.js","sourceRoot":"","sources":["../../src/vocabularies.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,8EAA8E;AAE9E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,UAAU,CAAU,CAAC;AAGhE,6CAA6C;AAC7C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAU,CAAC;AAG3F,+CAA+C;AAC/C,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AAGlE,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,aAAa,CAAU,CAAC;AAG7D,+DAA+D;AAC/D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,CAAU,CAAC;AAG/E;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,mBAAmB;IACnB,iBAAiB;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,iBAAiB;IACjB,kBAAkB;IAClB,qBAAqB;IACrB,wBAAwB;IACxB,kBAAkB;IAClB,yBAAyB;IACzB,wBAAwB;IACxB,yBAAyB;CACjB,CAAC;AAGX,+FAA+F;AAC/F,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAQ,eAAqC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC"}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@sinio/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Official Node.js SDK for the sinio.ai ingestion API (events, entities, locations, assignments).",
+  "license": "MIT",
+  "homepage": "https://docs.sinio.ai/sdks",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sinio-ai/sinio-node.git"
+  },
+  "bugs": "https://github.com/sinio-ai/sinio-node/issues",
+  "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"
+  ]
+}