sos-sdk-node-ts 0.1.2 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@ deterministic failures and never commit a local package reference. Staging
 begins only after exact registry packages are installed and verified.
 
 
-SOSChain-specific Node adapters built above the shared runtime-neutral SDK.
+Product-neutral Node adapters shared by SOSChain, Vet and UHC trusted runtimes.
 
 ```text
 gdc-* frozen
@@ -21,10 +21,10 @@ 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.
+This package owns reusable server-side Node transport, credentials,
+persistence, jobs and prompt-audio runtime behavior. It does not own
+deterministic data contracts, common authorization or sector policy. Vet, UHC
+and SOSChain may consume it without depending on one another.
 
 The first adapter, `SosEmergencyDispatchClient`, sends an already-authorized
 emergency request over HTTPS with a stable idempotency key and validates the
@@ -43,6 +43,16 @@ API. Applications select the protected `contentType`, apply their own upload or
 audio-duration limits, and authorize every recipient change before calling the
 shared core. See [docs/SECURE_MESSAGES.md](docs/SECURE_MESSAGES.md).
 
+## Immutable prompt audio
+
+`sos-sdk-node-ts/prompt-audio-runtime` hashes the canonical descriptor produced
+by `sos-data-utils-ts/prompt-audio`, coalesces concurrent misses, persists the
+audio and prewarms prompts sequentially. It includes a filesystem adapter for
+local execution and an ElevenLabs multilingual-v2 synthesizer. A production
+runtime supplies its approved durable-object-store adapter. Complete live OTPs
+are never cache entries; ICA composes static prefix and digit assets. See
+[docs/PROMPT_AUDIO_RUNTIME.md](docs/PROMPT_AUDIO_RUNTIME.md).
+
 ```bash
 npm ci
 npm run check

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-/** SOSChain-specific Node adapters over the shared runtime-neutral SDK. */
+/** Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes. */
 export * from './emergency-dispatch.js';
+export * from './prompt-audio-runtime.js';
 export * from './secure-message-crypto.js';

package/dist/index.js

@@ -1,3 +1,4 @@
-/** SOSChain-specific Node adapters over the shared runtime-neutral SDK. */
+/** Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes. */
 export * from './emergency-dispatch.js';
+export * from './prompt-audio-runtime.js';
 export * from './secure-message-crypto.js';

package/dist/prompt-audio-runtime.d.ts

@@ -0,0 +1,85 @@
+export interface PromptAudioObjectStore {
+    get(objectKey: string): Promise<Uint8Array | undefined>;
+    putIfAbsent(objectKey: string, audio: Uint8Array): Promise<void>;
+}
+/** Structural subset of a GCS Bucket; keeps the shared SDK cloud-client-version agnostic. */
+export interface PromptAudioGcsBucket {
+    file(name: string): {
+        download(): Promise<readonly [Buffer]>;
+        save(data: Uint8Array, options: Readonly<{
+            resumable: false;
+            contentType: string;
+            metadata: Readonly<{
+                cacheControl: string;
+            }>;
+            preconditionOpts: Readonly<{
+                ifGenerationMatch: number;
+            }>;
+        }>): Promise<unknown>;
+    };
+}
+export interface CachedPromptAudio {
+    objectKey: string;
+    audio: Uint8Array;
+    created: boolean;
+}
+export interface ElevenLabsPromptAudioRequest {
+    voiceId: string;
+    text: string;
+    modelId?: string;
+    outputFormat?: string;
+}
+/** Hash a canonical descriptor produced by `sos-data-utils-ts/prompt-audio`. */
+export declare function buildPromptAudioObjectKey(canonicalDescriptor: string, extension: string): string;
+/** Durable local adapter. Production callers may implement the same interface over object storage. */
+export declare class FileSystemPromptAudioStore implements PromptAudioObjectStore {
+    private readonly rootDirectory;
+    constructor(rootDirectory: string);
+    private resolveObjectPath;
+    get(objectKey: string): Promise<Uint8Array | undefined>;
+    putIfAbsent(objectKey: string, audio: Uint8Array): Promise<void>;
+}
+/**
+ * Shared durable GCS adapter for public immutable prompts.
+ *
+ * The default prefix is intentionally product-neutral: Vet, UHC and Connect
+ * ICA resolve the same object whenever their complete canonical descriptors
+ * match. `ifGenerationMatch: 0` makes concurrent cross-process writes
+ * create-only; an existing object wins and is read back by the cache.
+ */
+export declare class GcsPromptAudioStore implements PromptAudioObjectStore {
+    private readonly bucket;
+    private readonly prefix;
+    constructor(bucket: PromptAudioGcsBucket, options?: Readonly<{
+        prefix?: string;
+        cacheControl?: string;
+    }>);
+    private readonly cacheControl;
+    private resolveObjectName;
+    get(objectKey: string): Promise<Uint8Array | undefined>;
+    putIfAbsent(objectKey: string, audio: Uint8Array): Promise<void>;
+}
+/** Runtime cache with one synthesis operation for every in-process immutable miss. */
+export declare class ImmutablePromptAudioCache {
+    private readonly store;
+    private readonly inFlight;
+    constructor(store: PromptAudioObjectStore);
+    getOrCreate(input: Readonly<{
+        canonicalDescriptor: string;
+        extension: string;
+        synthesize: () => Promise<Uint8Array>;
+    }>): Promise<CachedPromptAudio>;
+    private create;
+}
+/** Prewarm deliberately serializes paid synthesis and stops at the first failure. */
+export declare function prewarmPromptAudioSequentially<Input, Output>(inputs: readonly Input[], prepare: (input: Input) => Promise<Output>): Promise<Output[]>;
+/** Minimal ElevenLabs adapter; credentials stay only in the trusted Node runtime. */
+export declare class ElevenLabsPromptAudioSynthesizer {
+    private readonly apiKey;
+    private readonly fetchImplementation;
+    constructor(options: Readonly<{
+        apiKey: string;
+        fetch?: typeof fetch;
+    }>);
+    synthesize(request: ElevenLabsPromptAudioRequest): Promise<Uint8Array>;
+}

package/dist/prompt-audio-runtime.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const REQUIRED_TOKEN = /^[A-Za-z0-9._-]+$/u;
+function requireText(value, errorCode) {
+    const normalized = String(value ?? '').trim();
+    if (!normalized)
+        throw new Error(errorCode);
+    return normalized;
+}
+/** Hash a canonical descriptor produced by `sos-data-utils-ts/prompt-audio`. */
+export function buildPromptAudioObjectKey(canonicalDescriptor, extension) {
+    requireText(canonicalDescriptor, 'prompt_audio_canonical_descriptor_required');
+    const normalizedExtension = requireText(extension, 'prompt_audio_extension_required').replace(/^\./u, '');
+    if (!REQUIRED_TOKEN.test(normalizedExtension))
+        throw new Error('prompt_audio_extension_invalid');
+    const digest = createHash('sha256').update(canonicalDescriptor, 'utf8').digest('hex');
+    return `prompt-audio/sha256/${digest}.${normalizedExtension}`;
+}
+/** Durable local adapter. Production callers may implement the same interface over object storage. */
+export class FileSystemPromptAudioStore {
+    rootDirectory;
+    constructor(rootDirectory) {
+        this.rootDirectory = rootDirectory;
+        if (!path.isAbsolute(rootDirectory))
+            throw new Error('prompt_audio_store_root_must_be_absolute');
+    }
+    resolveObjectPath(objectKey) {
+        if (!/^prompt-audio\/sha256\/[a-f0-9]{64}\.[A-Za-z0-9._-]+$/u.test(objectKey)) {
+            throw new Error('prompt_audio_object_key_invalid');
+        }
+        const resolved = path.resolve(this.rootDirectory, objectKey);
+        const relative = path.relative(this.rootDirectory, resolved);
+        if (relative.startsWith('..') || path.isAbsolute(relative))
+            throw new Error('prompt_audio_object_key_invalid');
+        return resolved;
+    }
+    async get(objectKey) {
+        try {
+            return new Uint8Array(await readFile(this.resolveObjectPath(objectKey)));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+    }
+    async putIfAbsent(objectKey, audio) {
+        if (!(audio instanceof Uint8Array) || audio.byteLength === 0)
+            throw new Error('prompt_audio_bytes_required');
+        const objectPath = this.resolveObjectPath(objectKey);
+        await mkdir(path.dirname(objectPath), { recursive: true });
+        try {
+            await writeFile(objectPath, audio, { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+}
+/**
+ * Shared durable GCS adapter for public immutable prompts.
+ *
+ * The default prefix is intentionally product-neutral: Vet, UHC and Connect
+ * ICA resolve the same object whenever their complete canonical descriptors
+ * match. `ifGenerationMatch: 0` makes concurrent cross-process writes
+ * create-only; an existing object wins and is read back by the cache.
+ */
+export class GcsPromptAudioStore {
+    bucket;
+    prefix;
+    constructor(bucket, options = {}) {
+        this.bucket = bucket;
+        this.prefix = String(options.prefix ?? '').trim().replace(/^\/+|\/+$/gu, '');
+        this.cacheControl = String(options.cacheControl ?? 'public, max-age=31536000, immutable').trim();
+        if (!this.cacheControl)
+            throw new Error('prompt_audio_gcs_cache_control_required');
+    }
+    cacheControl;
+    resolveObjectName(objectKey) {
+        if (!/^prompt-audio\/sha256\/[a-f0-9]{64}\.[A-Za-z0-9._-]+$/u.test(objectKey)) {
+            throw new Error('prompt_audio_object_key_invalid');
+        }
+        return this.prefix ? `${this.prefix}/${objectKey}` : objectKey;
+    }
+    async get(objectKey) {
+        try {
+            const [bytes] = await this.bucket.file(this.resolveObjectName(objectKey)).download();
+            return new Uint8Array(bytes);
+        }
+        catch (error) {
+            const status = error.code;
+            if (status === 404 || status === '404')
+                return undefined;
+            throw error;
+        }
+    }
+    async putIfAbsent(objectKey, audio) {
+        if (!(audio instanceof Uint8Array) || audio.byteLength === 0)
+            throw new Error('prompt_audio_bytes_required');
+        try {
+            await this.bucket.file(this.resolveObjectName(objectKey)).save(audio, {
+                resumable: false,
+                contentType: objectKey.endsWith('.mp3') ? 'audio/mpeg' : 'application/octet-stream',
+                metadata: { cacheControl: this.cacheControl },
+                preconditionOpts: { ifGenerationMatch: 0 },
+            });
+        }
+        catch (error) {
+            const status = error.code;
+            if (status !== 409 && status !== 412 && status !== '409' && status !== '412')
+                throw error;
+        }
+    }
+}
+/** Runtime cache with one synthesis operation for every in-process immutable miss. */
+export class ImmutablePromptAudioCache {
+    store;
+    inFlight = new Map();
+    constructor(store) {
+        this.store = store;
+    }
+    async getOrCreate(input) {
+        const objectKey = buildPromptAudioObjectKey(input.canonicalDescriptor, input.extension);
+        const stored = await this.store.get(objectKey);
+        if (stored)
+            return { objectKey, audio: stored, created: false };
+        const current = this.inFlight.get(objectKey);
+        if (current)
+            return current;
+        const creation = this.create(objectKey, input.synthesize);
+        this.inFlight.set(objectKey, creation);
+        try {
+            return await creation;
+        }
+        finally {
+            this.inFlight.delete(objectKey);
+        }
+    }
+    async create(objectKey, synthesize) {
+        const audio = await synthesize();
+        if (!(audio instanceof Uint8Array) || audio.byteLength === 0)
+            throw new Error('prompt_audio_synthesis_empty');
+        await this.store.putIfAbsent(objectKey, audio);
+        const durableAudio = await this.store.get(objectKey);
+        if (!durableAudio)
+            throw new Error('prompt_audio_persistence_failed');
+        return { objectKey, audio: durableAudio, created: true };
+    }
+}
+/** Prewarm deliberately serializes paid synthesis and stops at the first failure. */
+export async function prewarmPromptAudioSequentially(inputs, prepare) {
+    const outputs = [];
+    for (const input of inputs)
+        outputs.push(await prepare(input));
+    return outputs;
+}
+/** Minimal ElevenLabs adapter; credentials stay only in the trusted Node runtime. */
+export class ElevenLabsPromptAudioSynthesizer {
+    apiKey;
+    fetchImplementation;
+    constructor(options) {
+        this.apiKey = requireText(options.apiKey, 'elevenlabs_api_key_required');
+        this.fetchImplementation = options.fetch ?? fetch;
+    }
+    async synthesize(request) {
+        const voiceId = requireText(request.voiceId, 'elevenlabs_voice_id_required');
+        const outputFormat = request.outputFormat ?? 'mp3_44100_128';
+        if (!REQUIRED_TOKEN.test(voiceId))
+            throw new Error('elevenlabs_voice_id_invalid');
+        if (!REQUIRED_TOKEN.test(outputFormat))
+            throw new Error('elevenlabs_output_format_invalid');
+        const response = await this.fetchImplementation(`https://api.elevenlabs.io/v1/text-to-speech/${encodeURIComponent(voiceId)}?output_format=${encodeURIComponent(outputFormat)}`, {
+            method: 'POST',
+            headers: {
+                accept: 'audio/mpeg',
+                'content-type': 'application/json',
+                'xi-api-key': this.apiKey,
+            },
+            body: JSON.stringify({
+                text: requireText(request.text, 'elevenlabs_text_required'),
+                model_id: request.modelId ?? 'eleven_multilingual_v2',
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`prompt_audio_synthesis_failed:${response.status}`);
+        const audio = new Uint8Array(await response.arrayBuffer());
+        if (audio.byteLength === 0)
+            throw new Error('prompt_audio_synthesis_empty');
+        return audio;
+    }
+}

package/docs/PROMPT_AUDIO_RUNTIME.md

@@ -0,0 +1,36 @@
+# Immutable prompt audio in Node runtimes
+
+Telephone, portal, chatbot and messaging channels use the same reviewed prompt
+identity from `sos-data-utils-ts/prompt-audio`. The application canonicalizes
+the public-static descriptor, then passes that opaque canonical value to
+`ImmutablePromptAudioCache`.
+
+```text
+reviewed prompt descriptor
+        ↓ canonicalize in sos-data-utils-ts
+canonical JSON
+        ↓ SHA-256 in sos-sdk-node-ts
+immutable object key
+        ↓
+durable store ── miss only ──> configured synthesizer
+```
+
+The durable store, rather than process memory, is authoritative across
+restarts. Concurrent in-process misses are coalesced. Startup prewarming is
+sequential so it cannot create a burst of paid requests or exhaust a shared
+developer machine.
+
+`FileSystemPromptAudioStore` supports local and demo execution. Production
+applications use `GcsPromptAudioStore` or implement `PromptAudioObjectStore`
+over another approved object store without changing the cache lifecycle.
+One GCS bucket may be shared by Vet, UHC and Connect ICA: the default object
+name has no product prefix and reuse occurs only when the complete canonical
+descriptor matches. Deployments may configure an isolation prefix when policy
+requires separate storage. `ElevenLabsPromptAudioSynthesizer`
+defaults to `eleven_multilingual_v2`; API keys stay in the trusted runtime and
+are neither logged nor included in an error.
+
+Activation and verification services must never cache a complete live code.
+They retain its value, expiry and attempt counter, and compose the call from a
+static prefix plus localized digit fragments. Personalized names and clinical
+data are not public-static prompts.

package/docs/SDK_LAYERING.md

@@ -1,17 +1,25 @@
-# SOSChain Node SDK boundary
+# Shared 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"]
+  DATA --> NODE["sos-sdk-node-ts<br/>product-neutral Node adapters"]
+  CORE --> NODE
+  NODE --> RUNTIME["SOSChain · Vet · UHC trusted Node runtimes"]
   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.
+`sos-sdk-node-ts` is the common Node-runtime layer; it is not the SOSChain
+product SDK. Product-neutral storage, transport, credential, job and audio
+adapters belong here. Sector policy remains in the corresponding Vet, UHC or
+SOSChain package, and no shared package may depend back on a product SDK.
+
+For immutable prompt audio, `sos-data-utils-ts/prompt-audio` produces the
+canonical descriptor and localized numeric-code fragments. This package
+hashes that exact descriptor, stores the resulting bytes durably and invokes
+the configured provider only on a miss. Complete activation or verification
+codes remain ICA state and are played by composing reusable digit assets.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.2",
-  "description": "SOSChain-specific Node adapters over the shared runtime-neutral SOS SDK",
+  "version": "0.1.3",
+  "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
   "repository": {
@@ -20,6 +20,10 @@
       "types": "./dist/emergency-dispatch.d.ts",
       "default": "./dist/emergency-dispatch.js"
     },
+    "./prompt-audio-runtime": {
+      "types": "./dist/prompt-audio-runtime.d.ts",
+      "default": "./dist/prompt-audio-runtime.js"
+    },
     "./secure-message-crypto": {
       "types": "./dist/secure-message-crypto.d.ts",
       "default": "./dist/secure-message-crypto.js"
@@ -34,7 +38,7 @@
     "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",
+    "test": "npm run build && node --test --test-concurrency=1 tests/*.test.mjs",
     "check": "npm run typecheck && npm test",
     "prepack": "npm run check"
   },