sos-sdk-node-ts 0.1.4 → 0.1.6

package/README.md

@@ -1,4 +1,8 @@
 # sos-sdk-node-ts
+
+Accepted Encounter handover persistence and future channel-audience
+reconciliation are documented in
+[`docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md`](docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md).
 ## Blocking local-first SDK release
 
 The canonical contract is [`SDK_LAYERING.md`](https://github.com/Fundacion-UNID/sos-data-utils-ts/blob/main/docs/SDK_LAYERING.md). Its

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/encounter-transfer-audience-service.d.ts

@@ -0,0 +1,34 @@
+import { type EncounterTransferOrchestrationInput } from 'sos-sdk-core-ts/encounter-transfer-communication';
+export type AcceptedEncounterHandoverCommit = Readonly<{
+    idempotencyKey: string;
+    communicationThreadId: string;
+    projectionCommunication: Readonly<Record<string, unknown>>;
+    expectedProfessionalGroupReferences: readonly string[];
+    retainedProfessionalGroupReferences: readonly string[];
+    addedProfessionalGroupReferences: readonly string[];
+    removedProfessionalGroupReferences: readonly string[];
+    nextProfessionalGroupReferences: readonly string[];
+    familyJourneyEvent: Readonly<Record<string, unknown>>;
+}>;
+export type AcceptedEncounterHandoverReceipt = Readonly<{
+    idempotencyKey: string;
+    outcome: 'committed' | 'already-committed';
+    revision: string;
+}>;
+export type AcceptedEncounterHandoverPersistence = Readonly<{
+    /** Atomically persists every field or none; partial commits are forbidden. */
+    commitAcceptedHandover(commit: AcceptedEncounterHandoverCommit): Promise<AcceptedEncounterHandoverReceipt>;
+}>;
+/**
+ * Prepare and atomically persist one accepted Encounter handover.
+ *
+ * The injected adapter owns compare-and-swap/idempotency and must commit the
+ * provider projection, future professional audience and family-safe journey
+ * event as one unit. This service deliberately exposes no sequence of partial
+ * persistence callbacks. Authorization and service Group resolution occur in
+ * the product BFF before this call; historical Communications are untouched.
+ */
+export declare function persistAcceptedEncounterHandover(input: EncounterTransferOrchestrationInput, persistence: AcceptedEncounterHandoverPersistence): Promise<Readonly<{
+    commit: AcceptedEncounterHandoverCommit;
+    receipt: AcceptedEncounterHandoverReceipt;
+}>>;

package/dist/encounter-transfer-audience-service.js

@@ -0,0 +1,35 @@
+import { prepareEncounterTransferOrchestration, } from 'sos-sdk-core-ts/encounter-transfer-communication';
+/**
+ * Prepare and atomically persist one accepted Encounter handover.
+ *
+ * The injected adapter owns compare-and-swap/idempotency and must commit the
+ * provider projection, future professional audience and family-safe journey
+ * event as one unit. This service deliberately exposes no sequence of partial
+ * persistence callbacks. Authorization and service Group resolution occur in
+ * the product BFF before this call; historical Communications are untouched.
+ */
+export async function persistAcceptedEncounterHandover(input, persistence) {
+    const plan = prepareEncounterTransferOrchestration(input);
+    const reconciliation = plan.audienceReconciliation;
+    const commit = Object.freeze({
+        idempotencyKey: reconciliation.idempotencyKey,
+        communicationThreadId: reconciliation.communicationThreadId,
+        projectionCommunication: Object.freeze(plan.projectionCommunication),
+        expectedProfessionalGroupReferences: Object.freeze([...input.currentProfessionalGroupReferences]),
+        retainedProfessionalGroupReferences: reconciliation.retainedProfessionalGroupReferences,
+        addedProfessionalGroupReferences: reconciliation.addedProfessionalGroupReferences,
+        removedProfessionalGroupReferences: reconciliation.removedProfessionalGroupReferences,
+        nextProfessionalGroupReferences: reconciliation.nextProfessionalGroupReferences,
+        familyJourneyEvent: reconciliation.familyJourneyEvent,
+    });
+    const receipt = await persistence.commitAcceptedHandover(commit);
+    if (receipt.idempotencyKey !== commit.idempotencyKey) {
+        throw new TypeError('encounter_handover_receipt_idempotency_mismatch');
+    }
+    if (receipt.outcome !== 'committed' && receipt.outcome !== 'already-committed') {
+        throw new TypeError('encounter_handover_receipt_outcome_invalid');
+    }
+    if (!String(receipt.revision || '').trim())
+        throw new TypeError('encounter_handover_receipt_revision_required');
+    return Object.freeze({ commit, receipt: Object.freeze({ ...receipt }) });
+}

package/dist/index.d.ts

@@ -2,4 +2,6 @@
 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';
+export * from './encounter-transfer-audience-service.js';

package/dist/index.js

@@ -2,4 +2,6 @@
 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';
+export * from './encounter-transfer-audience-service.js';

package/docs/ENCOUNTER_TRANSFER_AUDIENCE_PERSISTENCE.md

@@ -0,0 +1,38 @@
+# Accepted Encounter handover persistence
+
+`persistAcceptedEncounterHandover(...)` is the product-neutral Node boundary
+for one accepted patient movement. The product BFF authenticates the actor,
+authorizes the transition and resolves exact source/destination
+`HealthcareService` Group assignments before calling it.
+
+The injected persistence adapter receives one indivisible commit containing:
+
+- the completed Communication Bundle that projects both Encounter updates and
+  both EncounterHistory milestones;
+- the expected current professional Groups and retained/added/removed/next
+  future audience;
+- the family-safe journey event;
+- one idempotency key and communication-thread identifier.
+
+The adapter must compare-and-swap the expected audience and commit every field
+or none. Retrying the same idempotency key returns `already-committed`. It must
+not expose separate public callbacks that could persist the Encounter while
+failing to update the channel, or vice versa.
+
+```ts
+const persisted = await persistAcceptedEncounterHandover(
+  authorizedEncounterTransfer,
+  {
+    commitAcceptedHandover: commit => handoverRepository.commitAtomically(commit),
+  },
+)
+
+if (persisted.receipt.outcome === 'already-committed') {
+  return persisted.receipt
+}
+```
+
+Historical Communications and their recipient snapshots are never modified.
+Subsequent Communications use `nextProfessionalGroupReferences`. The
+family-facing channel receives only `familyJourneyEvent` after its independent
+recipient and purpose checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -31,6 +31,14 @@
     "./bundle-sync-service": {
       "types": "./dist/bundle-sync-service.d.ts",
       "default": "./dist/bundle-sync-service.js"
+    },
+    "./encounter-transfer-audience-service": {
+      "types": "./dist/encounter-transfer-audience-service.d.ts",
+      "default": "./dist/encounter-transfer-audience-service.js"
+    },
+    "./confidential-channel-cache": {
+      "types": "./dist/confidential-channel-cache.d.ts",
+      "default": "./dist/confidential-channel-cache.js"
     }
   },
   "files": [
@@ -47,7 +55,7 @@
     "prepack": "npm run check"
   },
   "dependencies": {
-    "sos-sdk-core-ts": "0.5.1"
+    "sos-sdk-core-ts": "0.5.2"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",