sos-sdk-core-ts 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -2,9 +2,49 @@
 
 ## Unreleased
 
+- 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,
+  and sends the already-committed result to the subject index in one completed
+  Communication batch.
+- Document that movement does not imply `discharged`, that department sender,
+  HealthcareService and authenticated audit actor remain distinct, and that
+  emergency-contact files stay DocumentReference resources inside the Bundle.
+
+- Add the neutral `bundle-changes-response` contract and publish its scheduling
+  ownership guide. UHC consumers no longer expose a provisional copy.
+
+- Move the standard Appointment-in-Communication authoring flow and the
+  capability-driven FHIR scheduling client into the shared SOS/Vet/UHC layer.
+  Product packages no longer need human or veterinary wrappers for standard
+  FHIR resources.
+- Remove temporary SOSChain-prefixed emergency authorization aliases and data
+  reexport subpaths. Emergency Group and card-to-Place records now come from
+  their single owner, `sos-data-utils-ts@0.6.0`.
+- Consume the complete shared Task status vocabulary directly instead of
+  maintaining a local compatibility overlay.
+
+## 0.4.0 - 2026-09-29
+
+- Add the shared high-level Communication Bundle editor and reader for SOS,
+  Vet and UHC. Author an outer batch Bundle of Communications, validate each
+  attached inner document/batch/collection Bundle with
+  `fhir-data-utils-ts@0.6.0`, and keep PDF, image, audio and calendar files as
+  inner DocumentReference resources.
+- Pin `sos-data-utils-ts@0.5.1` and extend the existing
+  `gdc-common-utils-ts@2.9.21` Bundle editor, reader and attached-Bundle session
+  rather than introducing a parallel high-level implementation.
+
+- Add runtime-neutral, department-aware equipment calibration and operating-authorization orchestration; blood-bank labeling remains explicitly deferred.
+
+- Link the coordinated SOS/Vet/UHC clinical accessor adoption boundary so
+  shared orchestration is added only with an actual multichannel workflow.
+
 - Require the initial emergency triage Task owner to be a professional Group,
-  while keeping the accepting PractitionerRole as Task owner and actual
-  callback/message sender after acknowledgement.
+  while keeping the accepting PractitionerRole as Task owner and authenticated
+  transport actor after acknowledgement.
+- Define the department Organization as the FHIR Communication sender and keep
+  the professional Group solely as the stable reply queue.
 - Clarify that Group reply routing never replaces the legal Organization
   document author, professional attester or authenticated transport actor.
 

package/README.md

@@ -1,4 +1,6 @@
 # Shared SOS SDK Core
+
+Shared SOS/Vet/UHC orchestration includes [equipment calibration and operating authorization](docs/EQUIPMENT_COMPLIANCE.md) without embedding product roles or persistence plumbing.
 ## 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).
@@ -38,6 +40,28 @@ jobs; those adapters do not belong here.
 Git, workspace, vendored and `file:` dependencies are forbidden in committed
 or deployed dependency state.
 
+The cross-product Bundle/Communication editor and reader are owned here as
+high-level extensions of the existing `gdc-common-utils-ts` `BundleEditor`,
+`BundleReader` and `CommunicationAttachedBundleSession`. They preserve those
+APIs instead of duplicating their attachment or claims-first lifecycle, while
+`fhir-data-utils-ts` supplies neutral import, projection and validation tools.
+Follow 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)
+before changing dependencies: unaffected portals and assistants are not forced
+to upgrade merely because a lower package published a newer editor.
+
+All cross-participant exchanges use the established claims-first outer batch
+Bundle containing one or more Communication resources. Each Communication
+contains exactly one inner document, batch or collection Bundle in its
+`application/fhir+json` attachment claims. Binary files such as PDF, image,
+audio or `text/calendar` are DocumentReference entries inside the inner Bundle.
+Native FHIR R4/R5 is materialized only at an explicit adapter boundary. See
+[Communication Bundle editor and reader](docs/COMMUNICATION_BUNDLE_EDITOR_READER.md).
+The shared scheduling and response-correlation boundary is documented in
+[FHIR scheduling interoperability](docs/FHIR_SCHEDULING_INTEROPERABILITY.md).
+Source-to-destination care movement and subject-index projection are documented
+in [Encounter transfer projection](docs/ENCOUNTER_TRANSFER_PROJECTION.md).
+
 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
@@ -52,11 +76,9 @@ The `incident-reporter` relationship represents a short-lived grant issued by
 a trusted scan resolver to an already verified person at the scene; it does
 not imply guardianship, control or professional status.
 
-The older `SoschainEmergency*` names remain deprecated compatibility aliases
-to the same types and implementation; they are not a second contract.
-
-`buildSoschainPlaceCardAssociationClaims` records a UHC/VetChain card link to
-a canonical SOSChain Place or vehicle without merging either identity.
+Emergency evidence, Group records and card-to-Place associations are imported
+directly from `sos-data-utils-ts`; this orchestration package does not retain
+temporary reexport subpaths or product-prefixed authorization aliases.
 
 ## Care, emergency and alert orchestration
 

package/dist/bundle-changes-response.d.ts

@@ -0,0 +1,32 @@
+import type { BundleEntry, BundleJsonApi } from 'gdc-common-utils-ts/models/bundle';
+export declare const BundleChangeResponseStates: Readonly<{
+    readonly Successful: "successful";
+    readonly Failed: "failed";
+    readonly Pending: "pending";
+}>;
+export type BundleChangeResponseState = typeof BundleChangeResponseStates[keyof typeof BundleChangeResponseStates];
+export type BundleChangeResponseItem = Readonly<{
+    identifier: string;
+    changeEntryIndex: number;
+    responseEntryIndex?: number;
+    state: BundleChangeResponseState;
+    responseStatus?: string;
+    diagnostics: readonly string[];
+}>;
+export type BundleChangesResponseAnalysis = Readonly<{
+    entries: readonly BundleChangeResponseItem[];
+    successfulIdentifiers: readonly string[];
+    failedIdentifiers: readonly string[];
+    pendingIdentifiers: readonly string[];
+    diagnostics: readonly string[];
+}>;
+/** Reads every stable identifier carried by one Bundle entry in preference order. */
+export declare function readBundleEntryCorrelationIdentifiers(entry: BundleEntry): readonly string[];
+/**
+ * Correlates the submitted changes Bundle with the GW Bundle response.
+ *
+ * Correlation uses stable identifiers only, never array position. A missing,
+ * malformed or ambiguous response remains pending until the caller performs
+ * the resource-specific authoritative search.
+ */
+export declare function analyzeBundleChangesResponse(changesBundle: BundleJsonApi<BundleEntry>, responseBundle: BundleJsonApi<BundleEntry>): BundleChangesResponseAnalysis;

package/dist/bundle-changes-response.js

@@ -0,0 +1,154 @@
+// Copyright 2026 Connecting Solution & Applications Ltd under the Apache License, Version 2.0.
+export const BundleChangeResponseStates = Object.freeze({
+    Successful: 'successful',
+    Failed: 'failed',
+    Pending: 'pending',
+});
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function appendIdentifier(target, value) {
+    const identifier = asNonEmptyString(value);
+    if (identifier && !target.includes(identifier))
+        target.push(identifier);
+}
+function appendClaimIdentifiers(target, claims) {
+    for (const [name, value] of Object.entries(claims)) {
+        if (name === 'identifier' || name.endsWith('.identifier') || name.endsWith('.identifier.value')) {
+            appendIdentifier(target, value);
+        }
+    }
+}
+/** Reads every stable identifier carried by one Bundle entry in preference order. */
+export function readBundleEntryCorrelationIdentifiers(entry) {
+    const identifiers = [];
+    const resource = asRecord(entry.resource);
+    const resourceMeta = asRecord(resource.meta);
+    const entryMeta = asRecord(entry.meta);
+    appendIdentifier(identifiers, entry.fullUrl);
+    appendIdentifier(identifiers, resource.id);
+    appendIdentifier(identifiers, entry.id);
+    appendClaimIdentifiers(identifiers, asRecord(resourceMeta.claims));
+    appendClaimIdentifiers(identifiers, asRecord(entryMeta.claims));
+    return identifiers;
+}
+function readBundleEntryResponseOutcome(entry) {
+    const response = asRecord(entry.response);
+    const outcome = asRecord(response.outcome);
+    const issues = Array.isArray(outcome.issue) ? outcome.issue.map(asRecord) : [];
+    const severities = [];
+    const diagnostics = [];
+    for (const issue of issues) {
+        const severity = asNonEmptyString(issue.severity)?.toLowerCase();
+        if (severity)
+            severities.push(severity);
+        const diagnostic = asNonEmptyString(issue.diagnostics)
+            ?? asNonEmptyString(asRecord(issue.details).text);
+        if (diagnostic)
+            diagnostics.push(diagnostic);
+    }
+    const status = asNonEmptyString(response.status);
+    return { ...(status ? { status } : {}), severities, diagnostics };
+}
+function isSuccessfulStatus(status) {
+    return !!status && /^2\d\d(?:\s|$)/.test(status);
+}
+/**
+ * Correlates the submitted changes Bundle with the GW Bundle response.
+ *
+ * Correlation uses stable identifiers only, never array position. A missing,
+ * malformed or ambiguous response remains pending until the caller performs
+ * the resource-specific authoritative search.
+ */
+export function analyzeBundleChangesResponse(changesBundle, responseBundle) {
+    const responseEntries = responseBundle.data.map((entry, index) => ({
+        entry,
+        index,
+        identifiers: readBundleEntryCorrelationIdentifiers(entry),
+    }));
+    const seenChangeIdentifiers = new Set();
+    const claimedResponseIndexes = new Set();
+    const diagnostics = [];
+    const entries = [];
+    const changes = changesBundle.data.map((changeEntry, changeEntryIndex) => {
+        const identifiers = readBundleEntryCorrelationIdentifiers(changeEntry);
+        const identifier = identifiers[0];
+        if (!identifier) {
+            throw new Error(`Changes Bundle entry ${changeEntryIndex} requires a stable fullUrl, resource.id, entry.id or identifier claim.`);
+        }
+        if (seenChangeIdentifiers.has(identifier)) {
+            throw new Error(`Changes Bundle contains duplicate primary identifier '${identifier}'.`);
+        }
+        seenChangeIdentifiers.add(identifier);
+        return {
+            index: changeEntryIndex,
+            identifier,
+            matchingResponses: responseEntries.filter((candidate) => candidate.identifiers.some((candidateIdentifier) => identifiers.includes(candidateIdentifier))),
+        };
+    });
+    const responseMatchCounts = new Map();
+    changes.forEach(({ matchingResponses }) => matchingResponses.forEach(({ index }) => {
+        responseMatchCounts.set(index, (responseMatchCounts.get(index) ?? 0) + 1);
+    }));
+    changes.forEach(({ identifier, index: changeEntryIndex, matchingResponses }) => {
+        if (matchingResponses.length !== 1) {
+            const message = matchingResponses.length === 0
+                ? `No response entry carries a stable identifier for change '${identifier}'.`
+                : `More than one response entry matches change '${identifier}'.`;
+            diagnostics.push(message);
+            entries.push({ identifier, changeEntryIndex, state: BundleChangeResponseStates.Pending, diagnostics: [message] });
+            return;
+        }
+        const match = matchingResponses[0];
+        if ((responseMatchCounts.get(match.index) ?? 0) > 1) {
+            const message = `Response entry ${match.index} ambiguously matches more than one submitted change.`;
+            diagnostics.push(message);
+            entries.push({
+                identifier,
+                changeEntryIndex,
+                responseEntryIndex: match.index,
+                state: BundleChangeResponseStates.Pending,
+                diagnostics: [message],
+            });
+            return;
+        }
+        claimedResponseIndexes.add(match.index);
+        const outcome = readBundleEntryResponseOutcome(match.entry);
+        const hasError = outcome.severities.some((severity) => severity === 'fatal' || severity === 'error');
+        const state = !outcome.status
+            ? BundleChangeResponseStates.Pending
+            : isSuccessfulStatus(outcome.status) && !hasError
+                ? BundleChangeResponseStates.Successful
+                : BundleChangeResponseStates.Failed;
+        const itemDiagnostics = [...outcome.diagnostics];
+        if (!outcome.status)
+            itemDiagnostics.push(`Response entry ${match.index} has no status.`);
+        entries.push({
+            identifier,
+            changeEntryIndex,
+            responseEntryIndex: match.index,
+            state,
+            ...(outcome.status ? { responseStatus: outcome.status } : {}),
+            diagnostics: itemDiagnostics,
+        });
+    });
+    responseEntries.forEach(({ index }) => {
+        if (!claimedResponseIndexes.has(index)) {
+            diagnostics.push(`Response entry ${index} does not correlate with one submitted change.`);
+        }
+    });
+    return {
+        entries,
+        successfulIdentifiers: entries.filter(({ state }) => state === BundleChangeResponseStates.Successful).map(({ identifier }) => identifier),
+        failedIdentifiers: entries.filter(({ state }) => state === BundleChangeResponseStates.Failed).map(({ identifier }) => identifier),
+        pendingIdentifiers: entries.filter(({ state }) => state === BundleChangeResponseStates.Pending).map(({ identifier }) => identifier),
+        diagnostics,
+    };
+}

package/dist/care-emergency-alert-orchestration.js

@@ -89,17 +89,6 @@ export function orchestrateEmergencyRequest(input) {
     });
     return Object.freeze({ intake, serviceRequestEntry, triageTaskEntry });
 }
-// Compatibility overlay for the published data package used by clean installs.
-// The next grouped release exposes the same standard values directly there.
-const EmergencyTaskStatus = Object.freeze({
-    ...TaskStatus,
-    Received: 'received',
-    Accepted: 'accepted',
-    Rejected: 'rejected',
-    Ready: 'ready',
-    OnHold: 'on-hold',
-    EnteredInError: 'entered-in-error',
-});
 /**
  * Reads only the standard, claims-first coordinates required by a responder
  * console. It does not resolve contact endpoints or grant callback authority.
@@ -110,7 +99,7 @@ export function readEmergencyTriageTask(taskEntry) {
     }
     const claims = taskEntry.claims;
     const status = scalarClaim(claims[TaskClaim.Status], 'emergency_triage_status_required');
-    if (!Object.values(EmergencyTaskStatus).includes(status)) {
+    if (!Object.values(TaskStatus).includes(status)) {
         throw new TypeError('emergency_triage_status_invalid');
     }
     return Object.freeze({
@@ -161,7 +150,7 @@ export function prepareEmergencyResponderCallback(input) {
     const responderReference = reference(input.responderReference, 'PractitionerRole', 'emergency_callback_responder_invalid');
     if (task.ownerReference !== responderReference)
         throw new TypeError('emergency_callback_task_owner_required');
-    if (task.status !== EmergencyTaskStatus.Accepted && task.status !== EmergencyTaskStatus.InProgress) {
+    if (task.status !== TaskStatus.Accepted && task.status !== TaskStatus.InProgress) {
         throw new TypeError('emergency_callback_active_task_required');
     }
     if (!task.communicationThreadId)
@@ -180,20 +169,20 @@ export function prepareEmergencyResponderCallback(input) {
 }
 function emergencyTriageTransition(currentStatus, action) {
     const transitions = {
-        acknowledge: { [EmergencyTaskStatus.Requested]: EmergencyTaskStatus.Accepted, [EmergencyTaskStatus.Received]: EmergencyTaskStatus.Accepted },
-        start: { [EmergencyTaskStatus.Accepted]: EmergencyTaskStatus.InProgress, [EmergencyTaskStatus.Ready]: EmergencyTaskStatus.InProgress },
+        acknowledge: { [TaskStatus.Requested]: TaskStatus.Accepted, [TaskStatus.Received]: TaskStatus.Accepted },
+        start: { [TaskStatus.Accepted]: TaskStatus.InProgress, [TaskStatus.Ready]: TaskStatus.InProgress },
         escalate: {
-            [EmergencyTaskStatus.Requested]: EmergencyTaskStatus.Requested,
-            [EmergencyTaskStatus.Received]: EmergencyTaskStatus.Requested,
-            [EmergencyTaskStatus.Accepted]: EmergencyTaskStatus.Requested,
-            [EmergencyTaskStatus.InProgress]: EmergencyTaskStatus.Requested,
+            [TaskStatus.Requested]: TaskStatus.Requested,
+            [TaskStatus.Received]: TaskStatus.Requested,
+            [TaskStatus.Accepted]: TaskStatus.Requested,
+            [TaskStatus.InProgress]: TaskStatus.Requested,
         },
         reject: {
-            [EmergencyTaskStatus.Requested]: EmergencyTaskStatus.Rejected,
-            [EmergencyTaskStatus.Received]: EmergencyTaskStatus.Rejected,
-            [EmergencyTaskStatus.Accepted]: EmergencyTaskStatus.Rejected,
+            [TaskStatus.Requested]: TaskStatus.Rejected,
+            [TaskStatus.Received]: TaskStatus.Rejected,
+            [TaskStatus.Accepted]: TaskStatus.Rejected,
         },
-        complete: { [EmergencyTaskStatus.InProgress]: EmergencyTaskStatus.Completed },
+        complete: { [TaskStatus.InProgress]: TaskStatus.Completed },
     };
     const nextStatus = transitions[action]?.[currentStatus];
     if (!nextStatus)

package/dist/communication-bundle.d.ts

@@ -0,0 +1,125 @@
+import { BundleEditor } from 'gdc-common-utils-ts/utils/bundle-editor';
+import { BundleReader } from 'gdc-common-utils-ts/utils/bundle-reader';
+import { CommunicationAttachedBundleSession } from 'gdc-common-utils-ts/utils/communication-attached-bundle-session';
+import { type FhirResource } from 'fhir-data-utils-ts';
+export type CommunicationInnerBundleType = 'document' | 'batch' | 'collection';
+export type AttachmentDocumentInput = Readonly<{
+    identifier: string;
+    subjectReference: string;
+    contentType: string;
+    dataBase64?: string;
+    url?: string;
+    title?: string;
+    description?: string;
+    date?: string;
+    authorReferences?: readonly string[];
+    eventReferences?: readonly string[];
+}>;
+export type AppointmentCommunicationBundleInput = Readonly<{
+    communicationIdentifier: string;
+    status: string;
+    category?: string | readonly string[];
+    topic?: string;
+    text?: string;
+    subjectReference: string;
+    senderReference: string;
+    recipientReferences: readonly string[];
+    sent?: string;
+    appointment: FhirResource & Readonly<{
+        resourceType: 'Appointment';
+        id: string;
+    }>;
+    calendarDocument?: Readonly<{
+        identifier: string;
+        contentType: 'text/calendar';
+        dataBase64?: string;
+        url?: string;
+        title?: string;
+    }>;
+}>;
+/**
+ * SOS/Vet/UHC extension of the existing GDC BundleEditor.
+ *
+ * The inherited editor owns the canonical outer claims-first batch. Each
+ * staged message is a CommunicationAttachedBundleSession, so the existing
+ * attachment synchronization and Bundle lifecycle remain the source of truth.
+ * FHIR data utilities are used only at import/materialization boundaries.
+ */
+export declare class CommunicationBundleEditor extends BundleEditor {
+    #private;
+    constructor();
+    newCommunication(): CommunicationMessageEditor;
+    /** Builds the inherited claims-first outer batch after validating every attached Bundle. */
+    build(): ReturnType<BundleEditor['build']>;
+}
+/**
+ * Authors the standard FHIR Appointment delivery flow for every sector.
+ *
+ * Product SDKs use this class directly. They must not introduce human or
+ * veterinary Appointment wrappers unless they add a genuinely sector-owned
+ * rule that is absent from the FHIR and shared data contracts.
+ */
+export declare class AppointmentCommunicationBundleEditor extends CommunicationBundleEditor {
+    addAppointmentCommunication(input: AppointmentCommunicationBundleInput): this;
+}
+/** Authors one standard Appointment delivery without a product-specific wrapper. */
+export declare function prepareAppointmentCommunicationBundle(input: AppointmentCommunicationBundleInput): Record<string, unknown>;
+/** High-level message editor extending the established attached-Bundle session. */
+export declare class CommunicationMessageEditor extends CommunicationAttachedBundleSession {
+    #private;
+    constructor(parent: CommunicationBundleEditor);
+    setIdentifier(value: string): this;
+    getIdentifier(): string | undefined;
+    setStatus(value: string): this;
+    getStatus(): string | undefined;
+    setSubject(value: string): this;
+    getSubject(): string | undefined;
+    setSender(value: string): this;
+    getSender(): string | undefined;
+    setRecipients(values: readonly string[]): this;
+    getRecipients(): readonly string[];
+    setSent(value: string): this;
+    getSent(): string | undefined;
+    setAttachmentTitle(value: string): this;
+    getAttachmentTitle(): string | undefined;
+    setInnerBundleType(value: CommunicationInnerBundleType): this;
+    getInnerBundleType(): CommunicationInnerBundleType;
+    /** Adds one canonical claims-first resource to the existing attached-Bundle session. */
+    addResource(resource: FhirResource, request?: Readonly<{
+        method: 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET';
+        url: string;
+        ifMatch?: string;
+    }>): this;
+    /** Adds a PDF, image, audio or calendar file as an inner DocumentReference. */
+    addAttachmentDocument(input: AttachmentDocumentInput): this;
+    doneCommunication(): CommunicationBundleEditor;
+    /** @internal */
+    validateForBuild(): void;
+    /** @internal */
+    getCompleteCommunicationClaims(): Record<string, unknown>;
+}
+/** Read-only extension of the established BundleReader for an outer Communication batch. */
+export declare class CommunicationBundleReader extends BundleReader {
+    #private;
+    constructor(outerBatch: Record<string, unknown>);
+    getCommunicationCount(): number;
+    openCommunication(index: number): CommunicationMessageReader;
+}
+/** High-level getters over one claims-first Communication and its attached Bundle. */
+export declare class CommunicationMessageReader extends BundleReader {
+    #private;
+    constructor(entry: Record<string, unknown>);
+    getCommunication(): FhirResource;
+    getInnerBundle(): Record<string, unknown>;
+    getIdentifier(): string;
+    getStatus(): string | undefined;
+    getSubject(): string | undefined;
+    getSender(): string | undefined;
+    getRecipients(): readonly string[];
+    getSent(): string | undefined;
+    getAttachmentTitle(): string | undefined;
+    getInnerBundleType(): string | undefined;
+    getResourcesByType<TResource extends FhirResource = FhirResource>(resourceType: string): readonly TResource[];
+    getAppointments(): readonly FhirResource[];
+    getDocumentReferences(): readonly FhirResource[];
+}