sos-sdk-node-ts 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# sos-sdk-node-ts
+
+SOSChain-specific Node adapters built above the shared runtime-neutral SDK.
+
+```text
+gdc-* frozen
+    ↓
+sos-data-utils-ts
+    ↓
+sos-sdk-core-ts
+    ↓
+sos-sdk-node-ts
+```
+
+This package owns server-side SOSChain transport, credentials, persistence and
+jobs. It does not own deterministic data contracts or common authorization.
+Vet and UHC consume `sos-sdk-core-ts` independently; they do not consume this
+SOSChain runtime package.
+
+The first adapter, `SosEmergencyDispatchClient`, sends an already-authorized
+emergency request over HTTPS with a stable idempotency key and validates the
+provider acknowledgement. The bearer credential remains only in the trusted
+Node runtime.
+
+```bash
+npm ci
+npm run check
+```

package/dist/emergency-dispatch.d.ts

@@ -0,0 +1,29 @@
+import type { EmergencyDeliveryTarget } from 'sos-sdk-core-ts/emergency-authorization';
+export type SosEmergencyDispatchInput = Readonly<{
+    requestId: string;
+    callerId: string;
+    memberSubjectIds: readonly string[];
+    authorizationEvidenceIds: readonly string[];
+    deliveryTarget: EmergencyDeliveryTarget;
+    payload: unknown;
+}>;
+export type SosEmergencyDispatchAcknowledgement = Readonly<{
+    acknowledgedAt: string;
+    receiverId: string;
+}>;
+export type SosEmergencyDispatchClientOptions = Readonly<{
+    endpoint: string;
+    bearerToken: string;
+    fetch?: typeof globalThis.fetch;
+}>;
+/**
+ * Sends an already-authorized SOSChain request from a trusted Node runtime.
+ *
+ * Authorization remains in `sos-sdk-core-ts`; this adapter owns only HTTPS
+ * transport, service credentials, idempotency and acknowledgement validation.
+ */
+export declare class SosEmergencyDispatchClient {
+    #private;
+    constructor(options: SosEmergencyDispatchClientOptions);
+    dispatch(input: SosEmergencyDispatchInput): Promise<SosEmergencyDispatchAcknowledgement>;
+}

package/dist/emergency-dispatch.js

@@ -0,0 +1,66 @@
+/**
+ * Sends an already-authorized SOSChain request from a trusted Node runtime.
+ *
+ * Authorization remains in `sos-sdk-core-ts`; this adapter owns only HTTPS
+ * transport, service credentials, idempotency and acknowledgement validation.
+ */
+export class SosEmergencyDispatchClient {
+    #endpoint;
+    #bearerToken;
+    #fetch;
+    constructor(options) {
+        this.#endpoint = secureEndpoint(options.endpoint);
+        this.#bearerToken = required(options.bearerToken, 'bearerToken');
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    async dispatch(input) {
+        const requestId = required(input.requestId, 'requestId');
+        const callerId = required(input.callerId, 'callerId');
+        const memberSubjectIds = identifiers(input.memberSubjectIds, 'memberSubjectIds');
+        const authorizationEvidenceIds = identifiers(input.authorizationEvidenceIds, 'authorizationEvidenceIds');
+        const response = await this.#fetch(this.#endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${this.#bearerToken}`,
+                'idempotency-key': requestId,
+            },
+            body: JSON.stringify({
+                ...input,
+                requestId,
+                callerId,
+                memberSubjectIds,
+                authorizationEvidenceIds,
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`emergency_dispatch_http_${response.status}`);
+        const body = await response.json().catch(() => undefined);
+        const acknowledgedAt = String(body?.acknowledgedAt ?? '').trim();
+        const receiverId = String(body?.receiverId ?? '').trim();
+        if (!receiverId || !Number.isFinite(Date.parse(acknowledgedAt))) {
+            throw new Error('emergency_dispatch_acknowledgement_invalid');
+        }
+        return Object.freeze({ acknowledgedAt, receiverId });
+    }
+}
+function secureEndpoint(value) {
+    const endpoint = new URL(required(value, 'endpoint'));
+    const local = endpoint.hostname === 'localhost' || endpoint.hostname === '127.0.0.1';
+    if (endpoint.protocol !== 'https:' && !(local && endpoint.protocol === 'http:')) {
+        throw new TypeError('Emergency dispatch endpoint must use HTTPS outside local development.');
+    }
+    return endpoint;
+}
+function identifiers(values, field) {
+    const normalized = [...new Set((values ?? []).map((value) => required(value, field)))];
+    if (normalized.length === 0)
+        throw new TypeError(`${field} must not be empty.`);
+    return normalized;
+}
+function required(value, field) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized)
+        throw new TypeError(`${field} is required.`);
+    return normalized;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+/** SOSChain-specific Node adapters over the shared runtime-neutral SDK. */
+export * from './emergency-dispatch.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/** SOSChain-specific Node adapters over the shared runtime-neutral SDK. */
+export * from './emergency-dispatch.js';

package/docs/SDK_LAYERING.md

@@ -0,0 +1,17 @@
+# SOSChain Node SDK boundary
+
+```mermaid
+flowchart TB
+  GDC["gdc-* frozen"] --> DATA["sos-data-utils-ts<br/>deterministic contracts"]
+  DATA --> CORE["sos-sdk-core-ts<br/>runtime-neutral authorization"]
+  CORE --> NODE["sos-sdk-node-ts<br/>SOSChain Node adapters"]
+  NODE --> RUNTIME["SOSChain BFF · jobs · portal server"]
+  CORE --> VET["vet-sdk-core-ts"]
+  CORE --> UHC["uhc-sdk-core-ts"]
+  DATA --> VET
+  DATA --> UHC
+```
+
+`sos-sdk-node-ts` is a product runtime consumer, not another common layer. It
+may integrate public Vet or UHC contracts for an SOSChain operation, but that
+does not permit a dependency from either shared package back to a product SDK.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "sos-sdk-node-ts",
+  "version": "0.1.0",
+  "description": "SOSChain-specific Node adapters over the shared runtime-neutral SOS SDK",
+  "license": "Apache-2.0",
+  "author": "Connecting Solution & Applications Ltd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fundacion-UNID/sos-sdk-node-ts.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./emergency-dispatch": {
+      "types": "./dist/emergency-dispatch.d.ts",
+      "default": "./dist/emergency-dispatch.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "check": "npm run typecheck && npm test",
+    "prepack": "npm run check"
+  },
+  "dependencies": {
+    "sos-sdk-core-ts": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}