sos-sdk-core-ts 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.5.1 - 2026-10-04
+
+- Add the shared Bundle synchronization draft contract for clinical documents,
+  Consent, emergency contacts and Encounter transfers. Optimistic records stay
+  visibly pending after ambiguous or transient provider failures, definite
+  rejections restore the last confirmed Bundle, and only authoritative
+  provider readback marks a mutation as confirmed.
+
 - Add the claims-first Encounter transfer projection helper. It keeps a
   returning source `on-hold`, completes a definitive source departure, starts
   the destination `in-progress`, records both `EncounterHistory` milestones,

package/README.md

@@ -62,6 +62,13 @@ The shared scheduling and response-correlation boundary is documented in
 Source-to-destination care movement and subject-index projection are documented
 in [Encounter transfer projection](docs/ENCOUNTER_TRANSFER_PROJECTION.md).
 
+`BundleSyncDraft` is the shared serializable state for editors that must keep a
+local clinical document, Consent, emergency-contact or Encounter mutation
+visible while its provider write is pending. A successful HTTP response is not
+confirmation: the draft becomes `confirmed` only after authoritative provider
+readback. Ambiguous and transport failures remain `retryable`; definite remote
+rejections restore the last confirmed Bundle.
+
 The emergency-group contract stores subject references only on an enumerated
 FHIR Group. A group assistance request references that Group from one standard,
 compact-coded ServiceRequest; it never copies members or persists split coding

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

@@ -0,0 +1,61 @@
+import type { BundleEntry, BundleJsonApi } from 'gdc-common-utils-ts/models/bundle';
+export declare const BundleSyncKinds: Readonly<{
+    readonly ClinicalDocument: "clinical-document";
+    readonly EncounterTransfer: "encounter-transfer";
+    readonly Consent: "consent";
+    readonly EmergencyContact: "emergency-contact";
+}>;
+export type BundleSyncKind = typeof BundleSyncKinds[keyof typeof BundleSyncKinds];
+export declare const BundleSyncStates: Readonly<{
+    readonly Pending: "pending";
+    readonly Submitting: "submitting";
+    readonly Retryable: "retryable";
+    readonly Reconciling: "reconciling";
+    readonly Confirmed: "confirmed";
+    readonly Rejected: "rejected";
+}>;
+export type BundleSyncState = typeof BundleSyncStates[keyof typeof BundleSyncStates];
+export type BundleSyncPayload = BundleJsonApi<BundleEntry>;
+export type BundleSyncDraft = Readonly<{
+    id: string;
+    kind: BundleSyncKind;
+    subjectReference: string;
+    state: BundleSyncState;
+    changesBundle: BundleSyncPayload;
+    lastConfirmedBundle: BundleSyncPayload;
+    optimisticBundle?: BundleSyncPayload;
+    visibleBundle: BundleSyncPayload;
+    pendingIdentifiers: readonly string[];
+    diagnostics: readonly string[];
+    createdAt: string;
+    updatedAt: string;
+}>;
+export type CreateBundleSyncDraftInput = Readonly<{
+    id: string;
+    kind: BundleSyncKind;
+    subjectReference: string;
+    changesBundle: BundleSyncPayload;
+    lastConfirmedBundle: BundleSyncPayload;
+    optimisticBundle: BundleSyncPayload;
+    createdAt: string;
+}>;
+/**
+ * Creates the portable, serializable state shown while the BFF owns delivery.
+ * The optimistic Bundle remains visibly marked by `state`; it is never proof
+ * of provider persistence.
+ */
+export declare function createBundleSyncDraft(input: CreateBundleSyncDraftInput): BundleSyncDraft;
+/** Marks a durable draft as actively submitted without changing its preview. */
+export declare function submitBundleSyncDraft(draft: BundleSyncDraft, updatedAt: string): BundleSyncDraft;
+/** Retains the exact optimistic draft after a transient transport failure. */
+export declare function markBundleSyncRetryable(draft: BundleSyncDraft, diagnostics: readonly string[], updatedAt: string): BundleSyncDraft;
+/**
+ * Interprets the correlated remote Bundle response.
+ *
+ * Missing or ambiguous results keep the optimistic Bundle as a retryable
+ * draft. A definite rejection removes it. Successful submission moves to
+ * reconciling and still requires an authoritative provider readback.
+ */
+export declare function reconcileBundleSyncSubmission(draft: BundleSyncDraft, responseBundle: BundleSyncPayload, updatedAt: string): BundleSyncDraft;
+/** Replaces the preview only after exact provider readback succeeds. */
+export declare function confirmBundleSyncDraft(draft: BundleSyncDraft, authoritativeBundle: BundleSyncPayload, updatedAt: string): BundleSyncDraft;

package/dist/bundle-sync-draft.js

@@ -0,0 +1,115 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+import { analyzeBundleChangesResponse } from './bundle-changes-response.js';
+export const BundleSyncKinds = Object.freeze({
+    ClinicalDocument: 'clinical-document',
+    EncounterTransfer: 'encounter-transfer',
+    Consent: 'consent',
+    EmergencyContact: 'emergency-contact',
+});
+export const BundleSyncStates = Object.freeze({
+    Pending: 'pending',
+    Submitting: 'submitting',
+    Retryable: 'retryable',
+    Reconciling: 'reconciling',
+    Confirmed: 'confirmed',
+    Rejected: 'rejected',
+});
+/**
+ * Creates the portable, serializable state shown while the BFF owns delivery.
+ * The optimistic Bundle remains visibly marked by `state`; it is never proof
+ * of provider persistence.
+ */
+export function createBundleSyncDraft(input) {
+    requireText(input.id, 'bundle_sync_id_required');
+    requireText(input.subjectReference, 'bundle_sync_subject_required');
+    requireText(input.createdAt, 'bundle_sync_created_at_required');
+    if (!Object.values(BundleSyncKinds).includes(input.kind))
+        throw new TypeError('bundle_sync_kind_invalid');
+    return Object.freeze({
+        ...input,
+        state: BundleSyncStates.Pending,
+        visibleBundle: input.optimisticBundle,
+        pendingIdentifiers: Object.freeze([]),
+        diagnostics: Object.freeze([]),
+        updatedAt: input.createdAt,
+    });
+}
+/** Marks a durable draft as actively submitted without changing its preview. */
+export function submitBundleSyncDraft(draft, updatedAt) {
+    if (![BundleSyncStates.Pending, BundleSyncStates.Retryable].includes(draft.state)) {
+        throw new TypeError('bundle_sync_not_submittable');
+    }
+    return Object.freeze({ ...draft, state: BundleSyncStates.Submitting, updatedAt });
+}
+/** Retains the exact optimistic draft after a transient transport failure. */
+export function markBundleSyncRetryable(draft, diagnostics, updatedAt) {
+    if ([BundleSyncStates.Confirmed, BundleSyncStates.Rejected].includes(draft.state)) {
+        throw new TypeError('bundle_sync_retry_not_allowed');
+    }
+    return Object.freeze({
+        ...draft,
+        state: BundleSyncStates.Retryable,
+        diagnostics: Object.freeze([...diagnostics]),
+        updatedAt,
+    });
+}
+/**
+ * Interprets the correlated remote Bundle response.
+ *
+ * Missing or ambiguous results keep the optimistic Bundle as a retryable
+ * draft. A definite rejection removes it. Successful submission moves to
+ * reconciling and still requires an authoritative provider readback.
+ */
+export function reconcileBundleSyncSubmission(draft, responseBundle, updatedAt) {
+    if (![BundleSyncStates.Pending, BundleSyncStates.Submitting, BundleSyncStates.Retryable].includes(draft.state)) {
+        throw new TypeError('bundle_sync_response_not_expected');
+    }
+    const analysis = analyzeBundleChangesResponse(draft.changesBundle, responseBundle);
+    if (analysis.failedIdentifiers.length) {
+        return Object.freeze({
+            ...draft,
+            state: BundleSyncStates.Rejected,
+            optimisticBundle: undefined,
+            visibleBundle: draft.lastConfirmedBundle,
+            pendingIdentifiers: Object.freeze([]),
+            diagnostics: Object.freeze([...analysis.diagnostics, ...analysis.entries.flatMap(({ diagnostics }) => diagnostics)]),
+            updatedAt,
+        });
+    }
+    if (analysis.pendingIdentifiers.length) {
+        return Object.freeze({
+            ...draft,
+            state: BundleSyncStates.Retryable,
+            pendingIdentifiers: Object.freeze([...analysis.pendingIdentifiers]),
+            diagnostics: Object.freeze([...analysis.diagnostics]),
+            updatedAt,
+        });
+    }
+    return Object.freeze({
+        ...draft,
+        state: BundleSyncStates.Reconciling,
+        pendingIdentifiers: Object.freeze([]),
+        diagnostics: Object.freeze([...analysis.diagnostics]),
+        updatedAt,
+    });
+}
+/** Replaces the preview only after exact provider readback succeeds. */
+export function confirmBundleSyncDraft(draft, authoritativeBundle, updatedAt) {
+    if (draft.state !== BundleSyncStates.Reconciling)
+        throw new TypeError('bundle_sync_readback_not_expected');
+    return Object.freeze({
+        ...draft,
+        state: BundleSyncStates.Confirmed,
+        lastConfirmedBundle: authoritativeBundle,
+        optimisticBundle: undefined,
+        visibleBundle: authoritativeBundle,
+        pendingIdentifiers: Object.freeze([]),
+        diagnostics: Object.freeze([]),
+        updatedAt,
+    });
+}
+function requireText(value, issue) {
+    if (!value.trim())
+        throw new TypeError(issue);
+    return value;
+}

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './communication-bundle.js';
 export * from './fhir-scheduling.js';
 export * from './bundle-changes-response.js';
 export * from './encounter-transfer-communication.js';
+export * from './bundle-sync-draft.js';

package/dist/index.js

@@ -8,3 +8,4 @@ export * from './communication-bundle.js';
 export * from './fhir-scheduling.js';
 export * from './bundle-changes-response.js';
 export * from './encounter-transfer-communication.js';
+export * from './bundle-sync-draft.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-core-ts",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Runtime-neutral shared orchestration for SOS, Vet and UHC products",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -47,6 +47,10 @@
     "./encounter-transfer-communication": {
       "types": "./dist/encounter-transfer-communication.d.ts",
       "default": "./dist/encounter-transfer-communication.js"
+    },
+    "./bundle-sync-draft": {
+      "types": "./dist/bundle-sync-draft.d.ts",
+      "default": "./dist/bundle-sync-draft.js"
     }
   },
   "files": [