sos-sdk-node-ts 0.1.3 → 0.1.5

package/README.md

@@ -26,6 +26,19 @@ 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.
 
+`BundleSyncDraftService` is the trusted-runtime adapter for the shared durable
+editor outbox. The application injects protected storage, payload protection
+and the real provider executor. The service stores no clear clinical Bundle,
+reuses the same idempotent draft after transient failures, and does not report
+confirmation until the provider write has been followed by authoritative
+readback.
+
+It also does not duplicate the typed clinical Bundle editors exposed by the
+GDC Node SDK. Add a SOS Node adapter only when a real shared channel workflow
+requires runtime behavior, following the
+[SOS/Vet/UHC clinical accessor adoption matrix](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/CLINICAL_TYPED_ACCESSOR_ADOPTION.md).
+Portals and assistants without that editor remain on their verified versions.
+
 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

package/dist/bundle-sync-service.d.ts

@@ -0,0 +1,46 @@
+import { type BundleSyncDraft, type BundleSyncPayload, type BundleSyncState } from 'sos-sdk-core-ts/bundle-sync-draft';
+export type ProtectedBundleSyncRecord = Readonly<{
+    id: string;
+    kind: BundleSyncDraft['kind'];
+    subjectReference: string;
+    state: BundleSyncState;
+    protectedPayload: string;
+    createdAt: string;
+    updatedAt: string;
+}>;
+export interface BundleSyncRepository {
+    put(record: ProtectedBundleSyncRecord): Promise<void>;
+    get(id: string): Promise<ProtectedBundleSyncRecord | undefined>;
+    list(): Promise<readonly ProtectedBundleSyncRecord[]>;
+}
+export interface BundleSyncProtection {
+    protect(draft: BundleSyncDraft): Promise<string>;
+    unprotect(protectedPayload: string): Promise<BundleSyncDraft>;
+}
+export interface BundleSyncExecutor {
+    submit(draft: BundleSyncDraft): Promise<BundleSyncPayload>;
+    readback(draft: BundleSyncDraft): Promise<BundleSyncPayload>;
+}
+export type BundleSyncDraftServiceOptions = Readonly<{
+    repository: BundleSyncRepository;
+    protection: BundleSyncProtection;
+    executor: BundleSyncExecutor;
+    now?: () => Date;
+}>;
+/** Deterministic test adapter. Production runtimes inject durable storage. */
+export declare class BundleSyncRepositoryMemory implements BundleSyncRepository {
+    #private;
+    put(record: ProtectedBundleSyncRecord): Promise<void>;
+    get(id: string): Promise<ProtectedBundleSyncRecord | undefined>;
+    list(): Promise<readonly ProtectedBundleSyncRecord[]>;
+}
+/** Protected outbox shared by clinical, Consent, contact and Encounter Bundles. */
+export declare class BundleSyncDraftService {
+    private readonly options;
+    constructor(options: BundleSyncDraftServiceOptions);
+    enqueue(draft: BundleSyncDraft): Promise<BundleSyncDraft>;
+    read(id: string): Promise<BundleSyncDraft | undefined>;
+    process(id: string): Promise<BundleSyncDraft>;
+    private persist;
+    private now;
+}

package/dist/bundle-sync-service.js

@@ -0,0 +1,82 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+import { BundleSyncStates, confirmBundleSyncDraft, markBundleSyncRetryable, reconcileBundleSyncSubmission, submitBundleSyncDraft, } from 'sos-sdk-core-ts/bundle-sync-draft';
+/** Deterministic test adapter. Production runtimes inject durable storage. */
+export class BundleSyncRepositoryMemory {
+    #records = new Map();
+    async put(record) {
+        this.#records.set(record.id, structuredClone(record));
+    }
+    async get(id) {
+        const record = this.#records.get(id);
+        return record ? structuredClone(record) : undefined;
+    }
+    async list() {
+        return [...this.#records.values()].map((record) => structuredClone(record));
+    }
+}
+/** Protected outbox shared by clinical, Consent, contact and Encounter Bundles. */
+export class BundleSyncDraftService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async enqueue(draft) {
+        const current = await this.options.repository.get(draft.id);
+        if (current) {
+            const restored = await this.options.protection.unprotect(current.protectedPayload);
+            if (JSON.stringify(restored.changesBundle) !== JSON.stringify(draft.changesBundle)) {
+                throw new Error('bundle_sync_idempotency_conflict');
+            }
+            return restored;
+        }
+        await this.persist(draft);
+        return draft;
+    }
+    async read(id) {
+        const record = await this.options.repository.get(id);
+        return record ? this.options.protection.unprotect(record.protectedPayload) : undefined;
+    }
+    async process(id) {
+        const draft = await this.read(id);
+        if (!draft)
+            throw new Error('bundle_sync_draft_not_found');
+        if (draft.state === BundleSyncStates.Confirmed || draft.state === BundleSyncStates.Rejected)
+            return draft;
+        const submitting = submitBundleSyncDraft(draft, this.now());
+        await this.persist(submitting);
+        try {
+            const response = await this.options.executor.submit(submitting);
+            const reconciled = reconcileBundleSyncSubmission(submitting, response, this.now());
+            await this.persist(reconciled);
+            if (reconciled.state !== BundleSyncStates.Reconciling)
+                return reconciled;
+            const authoritativeBundle = await this.options.executor.readback(reconciled);
+            const confirmed = confirmBundleSyncDraft(reconciled, authoritativeBundle, this.now());
+            await this.persist(confirmed);
+            return confirmed;
+        }
+        catch (reason) {
+            const retryable = markBundleSyncRetryable(submitting, [classify(reason)], this.now());
+            await this.persist(retryable);
+            return retryable;
+        }
+    }
+    async persist(draft) {
+        await this.options.repository.put({
+            id: draft.id,
+            kind: draft.kind,
+            subjectReference: draft.subjectReference,
+            state: draft.state,
+            protectedPayload: await this.options.protection.protect(draft),
+            createdAt: draft.createdAt,
+            updatedAt: draft.updatedAt,
+        });
+    }
+    now() {
+        return (this.options.now?.() ?? new Date()).toISOString();
+    }
+}
+function classify(reason) {
+    const message = reason instanceof Error ? reason.message : String(reason || 'bundle_sync_failed');
+    return message.slice(0, 300);
+}

package/dist/confidential-channel-cache.d.ts

@@ -0,0 +1,73 @@
+export type ConfidentialChannelSourceMessage<TEnvelope = unknown> = Readonly<{
+    id: string;
+    channelId: string;
+    sender: string;
+    recipients: readonly string[];
+    sent?: string;
+    envelope: TEnvelope;
+}>;
+export type ConfidentialChannelMessage = Readonly<{
+    id: string;
+    channelId: string;
+    sender: string;
+    recipients: readonly string[];
+    sent?: string;
+    messageKind: 'clinical-document' | 'text' | 'audio';
+    text?: string;
+    bundle?: unknown;
+    audioBase64?: string;
+    audioContentType?: string;
+}>;
+export type ConfidentialChannelDocument = Readonly<{
+    version: 1;
+    cursor?: string;
+    messages: readonly ConfidentialChannelMessage[];
+}>;
+export type ConfidentialChannelVault = Readonly<{
+    get(collection: string, id: string): Promise<unknown>;
+    put(collection: string, record: Readonly<Record<string, unknown> & {
+        id: string;
+    }>): Promise<unknown>;
+    query(collection: string, where: readonly Readonly<{
+        attribute: string;
+        equals: string;
+    }>[]): Promise<readonly unknown[]>;
+}>;
+export type ConfidentialChannelStorageAdapter = Readonly<{
+    protect(document: Readonly<{
+        id?: string;
+        content: unknown;
+    }>): Promise<unknown>;
+    unprotect(document: Readonly<{
+        id?: string;
+        jwe: unknown;
+    }>): Promise<unknown>;
+}>;
+/** Rebuildable encrypted materialization; canonical messages remain in their governed source. */
+export declare class ConfidentialChannelCache {
+    private readonly vault;
+    constructor(vault: ConfidentialChannelVault);
+    synchronize<TEnvelope>(input: Readonly<{
+        profileId: string;
+        subjectId: string;
+        channelId: string;
+        adapter: ConfidentialChannelStorageAdapter;
+        messages: readonly ConfidentialChannelSourceMessage<TEnvelope>[];
+        open(envelope: TEnvelope): Promise<Readonly<{
+            contentType: string;
+            plaintext: Uint8Array;
+        }>>;
+    }>): Promise<ConfidentialChannelDocument>;
+    read(input: Readonly<{
+        profileId: string;
+        subjectId: string;
+        channelId: string;
+        adapter: ConfidentialChannelStorageAdapter;
+    }>): Promise<ConfidentialChannelDocument | undefined>;
+    listSubject(input: Readonly<{
+        profileId: string;
+        subjectId: string;
+        adapter: ConfidentialChannelStorageAdapter;
+    }>): Promise<ConfidentialChannelDocument[]>;
+    private stored;
+}

package/dist/confidential-channel-cache.js

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+const COLLECTION = 'channel_communication_cache';
+/** Rebuildable encrypted materialization; canonical messages remain in their governed source. */
+export class ConfidentialChannelCache {
+    vault;
+    constructor(vault) {
+        this.vault = vault;
+    }
+    async synchronize(input) {
+        const identity = cacheIdentity(input);
+        const current = await this.read(input) ?? emptyChannel();
+        const knownIds = new Set(current.messages.map(message => message.id));
+        const additions = [];
+        for (const source of input.messages) {
+            if (source.channelId !== input.channelId || knownIds.has(source.id))
+                continue;
+            additions.push(materialize(source, await input.open(source.envelope)));
+        }
+        const messages = [...current.messages, ...additions].sort(compareMessages);
+        const cursor = messages.reduce((latest, message) => {
+            if (!message.sent)
+                return latest;
+            return !latest || message.sent > latest ? message.sent : latest;
+        }, current.cursor);
+        const content = { version: 1, cursor, messages };
+        const protectedDocument = protectedResult(await input.adapter.protect({ id: identity.id, content }));
+        await this.vault.put(COLLECTION, {
+            id: identity.id,
+            profileHash: identity.profileHash,
+            subjectHash: identity.subjectHash,
+            updatedAt: new Date().toISOString(),
+            jwe: protectedDocument.jwe,
+        });
+        return content;
+    }
+    async read(input) {
+        const identity = cacheIdentity(input);
+        const stored = this.stored(await this.vault.get(COLLECTION, identity.id));
+        if (!stored || stored.profileHash !== identity.profileHash || stored.subjectHash !== identity.subjectHash)
+            return undefined;
+        return channelContent(openedResult(await input.adapter.unprotect({ id: identity.id, jwe: stored.jwe })).content);
+    }
+    async listSubject(input) {
+        const profileHash = digest(required(input.profileId, 'channel_cache_profile_required'));
+        const subjectHash = digest(required(input.subjectId, 'channel_cache_subject_required'));
+        const rows = await this.vault.query(COLLECTION, [
+            { attribute: 'profileHash', equals: profileHash },
+            { attribute: 'subjectHash', equals: subjectHash },
+        ]);
+        return Promise.all(rows.map(async (row) => {
+            const stored = this.stored(row);
+            if (!stored)
+                throw new Error('channel_cache_record_invalid');
+            return channelContent(openedResult(await input.adapter.unprotect({ id: stored.id, jwe: stored.jwe })).content);
+        }));
+    }
+    stored(value) {
+        if (!value || typeof value !== 'object' || !('id' in value) || !('jwe' in value))
+            return undefined;
+        return value;
+    }
+}
+function materialize(source, opened) {
+    const contentType = String(opened.contentType || '').trim().toLowerCase();
+    const common = {
+        id: source.id, channelId: source.channelId, sender: source.sender,
+        recipients: [...source.recipients], sent: source.sent,
+    };
+    if (contentType.startsWith('text/plain')) {
+        return { ...common, messageKind: 'text', text: Buffer.from(opened.plaintext).toString('utf8') };
+    }
+    if (contentType.startsWith('audio/')) {
+        return { ...common, messageKind: 'audio', audioBase64: Buffer.from(opened.plaintext).toString('base64'), audioContentType: contentType };
+    }
+    if (contentType === 'application/fhir+json') {
+        const bundle = JSON.parse(Buffer.from(opened.plaintext).toString('utf8'));
+        if (bundle?.resourceType !== 'Bundle')
+            throw new Error('channel_cache_bundle_required');
+        return { ...common, messageKind: 'clinical-document', bundle };
+    }
+    throw new Error('channel_cache_content_type_unsupported');
+}
+function cacheIdentity(input) {
+    const profileHash = digest(required(input.profileId, 'channel_cache_profile_required'));
+    const subjectHash = digest(required(input.subjectId, 'channel_cache_subject_required'));
+    const channelHash = digest(required(input.channelId, 'channel_cache_channel_required'));
+    return { id: digest(`${profileHash}\u0000${subjectHash}\u0000${channelHash}`), profileHash, subjectHash };
+}
+function digest(value) { return createHash('sha256').update(value, 'utf8').digest('hex'); }
+function required(value, error) { const normalized = String(value || '').trim(); if (!normalized)
+    throw new Error(error); return normalized; }
+function emptyChannel() { return { version: 1, messages: [] }; }
+function compareMessages(left, right) { return String(left.sent || left.id).localeCompare(String(right.sent || right.id)); }
+function protectedResult(value) {
+    if (!value || typeof value !== 'object' || !('jwe' in value))
+        throw new Error('channel_cache_protection_failed');
+    return value;
+}
+function openedResult(value) {
+    if (!value || typeof value !== 'object' || !('content' in value))
+        throw new Error('channel_cache_open_failed');
+    return value;
+}
+function channelContent(value) {
+    const candidate = value;
+    if (candidate?.version !== 1 || !Array.isArray(candidate.messages))
+        throw new Error('channel_cache_document_invalid');
+    return candidate;
+}

package/dist/index.d.ts

@@ -2,3 +2,5 @@
 export * from './emergency-dispatch.js';
 export * from './prompt-audio-runtime.js';
 export * from './secure-message-crypto.js';
+export * from './confidential-channel-cache.js';
+export * from './bundle-sync-service.js';

package/dist/index.js

@@ -2,3 +2,5 @@
 export * from './emergency-dispatch.js';
 export * from './prompt-audio-runtime.js';
 export * from './secure-message-crypto.js';
+export * from './confidential-channel-cache.js';
+export * from './bundle-sync-service.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -27,6 +27,14 @@
     "./secure-message-crypto": {
       "types": "./dist/secure-message-crypto.d.ts",
       "default": "./dist/secure-message-crypto.js"
+    },
+    "./bundle-sync-service": {
+      "types": "./dist/bundle-sync-service.d.ts",
+      "default": "./dist/bundle-sync-service.js"
+    },
+    "./confidential-channel-cache": {
+      "types": "./dist/confidential-channel-cache.d.ts",
+      "default": "./dist/confidential-channel-cache.js"
     }
   },
   "files": [
@@ -43,7 +51,7 @@
     "prepack": "npm run check"
   },
   "dependencies": {
-    "sos-sdk-core-ts": "0.2.2"
+    "sos-sdk-core-ts": "0.5.1"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",