@sinio/sdk 0.1.0 → 0.2.0

package/dist/esm/serialize.js

@@ -1,4 +1,5 @@
 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. */
@@ -29,74 +30,150 @@ export function chunk(items, size) {
     }
     return chunks;
 }
-export function toWireEvent(event, index) {
-    if (!event.sourceEventId) {
-        throw new SinioValidationError(`events[${index}].sourceEventId is required`);
+// 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)})`);
     }
-    if (!event.type) {
-        throw new SinioValidationError(`events[${index}].type is required`);
+    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)})`);
     }
-    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`);
+    return value;
+}
+export function requireList(value, field) {
+    if (!Array.isArray(value)) {
+        throw new SinioValidationError(`${field} must be an array (got ${describe(value)})`);
     }
-    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 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({
-        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,
+        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 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`);
+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({
-        external_id: entity.externalId,
-        kind: entity.kind,
-        subkind: entity.subkind,
-        label: entity.label,
-        location: entity.location,
-        attributes: entity.attributes,
+        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) {
-    if (!location.externalId) {
-        throw new SinioValidationError(`locations[${index}].externalId is required`);
-    }
-    if (!location.name) {
-        throw new SinioValidationError(`locations[${index}].name is required`);
-    }
+    const at = `locations[${index}]`;
+    const item = requireItem(location, at);
     return compact({
-        external_id: location.externalId,
-        kind: location.kind,
-        name: location.name,
-        parent: location.parent,
+        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) {
-    if (!assignment.credential || !assignment.subject) {
-        throw new SinioValidationError(`assignments[${index}] requires both credential and subject`);
+    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: 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`),
+        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

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

package/dist/esm/types.d.ts

@@ -1,28 +1,28 @@
-/** 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";
+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
+ * 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 interface EventRoles {
-    readonly device?: string;
-    readonly subject?: string;
-    readonly location?: string;
-    readonly actor?: string;
-}
+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`. Required for publisher-level keys, forbidden for project-level ones. */
+    /** 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;
@@ -31,18 +31,20 @@ export interface SinioEvent {
     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>;
+    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;
-    readonly attributes?: Record<string, unknown>;
+    /** Free-form JSON object. */
+    readonly attributes?: JsonObject;
 }
 export interface LocationInput {
     readonly externalId: string;
@@ -56,24 +58,27 @@ export interface AssignmentInput {
     readonly credential: string;
     /** External id of the subject the credential is assigned to. */
     readonly subject: string;
-    readonly relation?: 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: string;
+    readonly code: RejectionCodeValue;
     readonly message: string;
 }
 export interface ReferenceRejection {
     readonly externalId: string;
-    readonly code: string;
+    readonly code: RejectionCodeValue;
     readonly message: string;
 }
 export interface AssignmentRejection {
     readonly credential: string;
     readonly subject: string;
-    readonly code: string;
+    readonly code: RejectionCodeValue;
     readonly message: string;
 }
 /**
@@ -82,33 +87,40 @@ export interface AssignmentRejection {
  */
 export interface SendEventsResult {
     /** Server-side batch ids, one per HTTP call the SDK made (batches are chunked at 500). */
-    readonly batchIds: string[];
+    readonly batchIds: readonly string[];
     readonly accepted: number;
     readonly pendingClassification: number;
     readonly duplicates: number;
     readonly revisions: number;
     readonly rejected: number;
-    readonly rejections: EventRejection[];
+    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: ReferenceRejection[];
+    readonly rejections: readonly ReferenceRejection[];
 }
 export interface AssignmentsResult {
     readonly accepted: number;
     readonly rejected: number;
-    readonly rejections: AssignmentRejection[];
+    readonly rejections: readonly AssignmentRejection[];
 }
 export interface SendEventsOptions {
     /** Defaults to `webhook`. */
     readonly mode?: IngestionMode;
-    /** Overrides the client-level source code for this call. */
+    /**
+     * 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, for publisher-level API keys covering several projects. */
+/**
+ * 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/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,8 +1,14 @@
 {
   "name": "@sinio/sdk",
-  "version": "0.1.0",
+  "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",