gdc-common-utils-ts 2.0.18 → 2.1.0

package/dist/models/communication-attached-bundle-session.d.ts

@@ -0,0 +1,193 @@
+import type { HealthcareCanonicalSectionFamily, HealthcareRoleFamily } from '../constants/healthcare';
+import type { BundleEntry, BundleJsonApi, BundleRequest } from './bundle';
+/**
+ * Runtime strictness used by `CommunicationAttachedBundleSession`.
+ */
+export type CommunicationAttachedBundleSessionMode = 'strict' | 'normalize';
+/**
+ * Constructor options for `CommunicationAttachedBundleSession`.
+ */
+export type CommunicationAttachedBundleSessionOptions = Readonly<{
+    communicationClaims?: Record<string, unknown>;
+    initialBundle?: BundleJsonApi<BundleEntry>;
+    mode?: CommunicationAttachedBundleSessionMode;
+}>;
+/**
+ * Canonical `@context` for outer `Communication` claim payloads.
+ *
+ * Rationale:
+ * - the outer container is materialized as one FHIR `Communication` resource
+ * - the inner `resource.meta.claims` rows stay version-agnostic and therefore
+ *   use `FHIR_API`
+ */
+export declare const CommunicationAttachmentClaimsContext: "org.hl7.fhir.r4";
+/**
+ * Canonical `@context` for bundle entry `resource.meta.claims`.
+ *
+ * These claims are intended to stay version-agnostic across FHIR releases.
+ */
+export declare const BundleEntryClaimsContext: "org.hl7.fhir.api";
+/**
+ * Selector for reopening one active bundle entry.
+ *
+ * Prefer `position` for bundle-array addressing. `index` is kept only as a
+ * backward-compatible alias during migration.
+ */
+export type ActiveEntrySelection = Readonly<{
+    position?: number;
+    /** @deprecated Prefer `position`. */
+    index?: number;
+    fullUrl?: string;
+}>;
+/**
+ * Generic upsert contract for one bundle entry stored in memory.
+ */
+export type UpsertEntryInput = Readonly<{
+    resourceType: string;
+    claims: Record<string, unknown>;
+    type?: string;
+    fullUrl?: string;
+    request?: BundleRequest;
+}>;
+/**
+ * Reusable resource-specific upsert contract used by typed session helpers.
+ */
+export type UpsertClaimsResourceEntryInput<TClaims extends object = Record<string, unknown>> = Readonly<{
+    claims: TClaims;
+    type?: string;
+    fullUrl?: string;
+    request?: BundleRequest;
+}>;
+/**
+ * Input for adding one linked `DocumentReference` to the current active entry.
+ */
+export type AddContainedDocumentToActiveEntryInput = Readonly<{
+    identifier?: string;
+    fullUrl?: string;
+    claims?: Record<string, unknown>;
+    attachmentContentType?: string;
+    attachmentDataBase64?: string;
+    attachmentUrl?: string;
+    description?: string;
+    date?: string;
+    language?: string;
+}>;
+/**
+ * Canonical target kinds for consent access editing.
+ */
+export declare const ConsentEditorTargetKinds: Readonly<{
+    readonly Section: "section";
+    readonly ResourceType: "resource-type";
+}>;
+export type ConsentEditorTargetKind = typeof ConsentEditorTargetKinds[keyof typeof ConsentEditorTargetKinds];
+/**
+ * Canonical operation scope codes for consent access editing.
+ */
+export declare const ConsentEditorScopeCodes: Readonly<{
+    readonly Search: "s";
+    readonly Read: "r";
+    readonly Create: "c";
+    readonly Update: "u";
+    readonly Delete: "d";
+}>;
+export type ConsentEditorScopeCode = typeof ConsentEditorScopeCodes[keyof typeof ConsentEditorScopeCodes];
+/**
+ * One classified scope attached to a consent target.
+ */
+export type ConsentEditorClassifiedScope = Readonly<{
+    code: ConsentEditorScopeCode;
+    display?: string;
+}>;
+/**
+ * One classified target entry shown to consent-editing callers.
+ */
+export type ConsentEditorClassifiedTarget = Readonly<{
+    target: Readonly<{
+        kind: ConsentEditorTargetKind;
+        code: string;
+        display?: string;
+        sectionFamily?: HealthcareCanonicalSectionFamily;
+    }>;
+    scopes: readonly ConsentEditorClassifiedScope[];
+}>;
+/**
+ * Classified actor role resolved from canonical healthcare role catalogs.
+ */
+export type ConsentEditorClassifiedActorRole = Readonly<{
+    codingSystem: string;
+    code: string;
+    display?: string;
+}>;
+/**
+ * Role kind used in consent role classification.
+ *
+ * The underlying catalog still comes from `HealthcareRoleFamily`, but this
+ * editor-level view intentionally names the field `kind` instead of `family`
+ * to avoid leaking `individual-organization` terminology into generic consent
+ * editing flows.
+ */
+export type ConsentEditorClassifiedRoleKind = HealthcareRoleFamily;
+/**
+ * Classified role entry exposed by the consent editor.
+ */
+export type ConsentEditorClassifiedRole = Readonly<{
+    kind?: ConsentEditorClassifiedRoleKind;
+    codingSystem: string;
+    code: string;
+    display?: string;
+    definition?: string;
+}>;
+/**
+ * Role buckets exposed by the consent editor.
+ */
+export type ConsentEditorClassifiedRoles = Readonly<{
+    professional: readonly ConsentEditorClassifiedRole[];
+    relationship: readonly ConsentEditorClassifiedRole[];
+    legalRepresentative: readonly ConsentEditorClassifiedRole[];
+    other: readonly ConsentEditorClassifiedRole[];
+}>;
+export type ConsentEditorClassifiedDepartment = Readonly<{
+    code: string;
+    display?: string;
+}>;
+export type ConsentEditorClassifiedLocation = Readonly<{
+    code: string;
+    display?: string;
+}>;
+export type ConsentEditorClassifiedOrganization = Readonly<{
+    domain: string;
+    display?: string;
+    departments: readonly ConsentEditorClassifiedDepartment[];
+    locations: readonly ConsentEditorClassifiedLocation[];
+}>;
+export type ConsentEditorClassifiedJurisdiction = Readonly<{
+    code: string;
+    display?: string;
+}>;
+export type ConsentEditorClassifiedUser = Readonly<{
+    email?: string;
+    phone?: string;
+    role?: ConsentEditorClassifiedActorRole;
+}>;
+export type ConsentEditorClassifiedActors = Readonly<{
+    jurisdictions: readonly ConsentEditorClassifiedJurisdiction[];
+    organizations: readonly ConsentEditorClassifiedOrganization[];
+    users: readonly ConsentEditorClassifiedUser[];
+}>;
+export type ConsentEditorClassifiedPurpose = Readonly<{
+    code: string;
+    display?: string;
+}>;
+/**
+ * Normalized consent view model exposed by the editor.
+ */
+export type ConsentViewModel = Readonly<{
+    fullUrl?: string;
+    identifier: string;
+    subject: string;
+    decision: string;
+    classifiedActors: ConsentEditorClassifiedActors;
+    classifiedRoles: ConsentEditorClassifiedRoles;
+    classifiedPurposes: readonly ConsentEditorClassifiedPurpose[];
+    classifiedTargets: readonly ConsentEditorClassifiedTarget[];
+}>;

package/dist/models/communication-attached-bundle-session.js

@@ -0,0 +1,34 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { Format } from '../constants/Schemas.js';
+/**
+ * Canonical `@context` for outer `Communication` claim payloads.
+ *
+ * Rationale:
+ * - the outer container is materialized as one FHIR `Communication` resource
+ * - the inner `resource.meta.claims` rows stay version-agnostic and therefore
+ *   use `FHIR_API`
+ */
+export const CommunicationAttachmentClaimsContext = Format.FHIR_R4;
+/**
+ * Canonical `@context` for bundle entry `resource.meta.claims`.
+ *
+ * These claims are intended to stay version-agnostic across FHIR releases.
+ */
+export const BundleEntryClaimsContext = Format.FHIR_API;
+/**
+ * Canonical target kinds for consent access editing.
+ */
+export const ConsentEditorTargetKinds = Object.freeze({
+    Section: 'section',
+    ResourceType: 'resource-type',
+});
+/**
+ * Canonical operation scope codes for consent access editing.
+ */
+export const ConsentEditorScopeCodes = Object.freeze({
+    Search: 's',
+    Read: 'r',
+    Create: 'c',
+    Update: 'u',
+    Delete: 'd',
+});

package/dist/models/index.d.ts

@@ -6,6 +6,7 @@ export * from './comm';
 export * from './clinical-sections';
 export * from './clinical-sections.en';
 export * from './clinical-workbook-summary';
+export * from './communication-attached-bundle-session';
 export * from './confidential-job';
 export * from './confidential-message';
 export * from './confidential-storage';
@@ -36,6 +37,7 @@ export * from './oidc4ida.electronicRecord.model';
 export * from './oidc4ida.evidence.model';
 export * from './openid-device';
 export * from './permission-templates';
+export * from './profile-manager';
 export * from './operation-outcome';
 export * from './params';
 export * from './permission-templates';
@@ -44,3 +46,4 @@ export * from './relationship-access';
 export * from './response';
 export * from './urlPath';
 export * from './verifiable-credential';
+export * from './wallet';

package/dist/models/index.js

@@ -6,6 +6,7 @@ export * from './comm.js';
 export * from './clinical-sections.js';
 export * from './clinical-sections.en.js';
 export * from './clinical-workbook-summary.js';
+export * from './communication-attached-bundle-session.js';
 export * from './confidential-job.js';
 export * from './confidential-message.js';
 export * from './confidential-storage.js';
@@ -36,6 +37,7 @@ export * from './oidc4ida.electronicRecord.model.js';
 export * from './oidc4ida.evidence.model.js';
 export * from './openid-device.js';
 export * from './permission-templates.js';
+export * from './profile-manager.js';
 export * from './operation-outcome.js';
 export * from './params.js';
 export * from './permission-templates.js';
@@ -44,3 +46,4 @@ export * from './relationship-access.js';
 export * from './response.js';
 export * from './urlPath.js';
 export * from './verifiable-credential.js';
+export * from './wallet.js';

package/dist/models/interoperable-claims/diagnostic-report-claims.d.ts

@@ -91,6 +91,5 @@ export declare const DiagnosticReportSearchParamToClaimKey: Record<DiagnosticRep
  *
  * Keep `DiagnosticReport` paused at the typing/mapping layer until:
  * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. `CommunicationAttachedBundleSession.upsertActiveDiagnosticReportEntry(...)` exists
- * 3. GW Core readers/tests consume the same shared claim keys
+ * 2. GW Core readers/tests consume the same shared claim keys
  */

package/dist/models/interoperable-claims/diagnostic-report-claims.js

@@ -100,6 +100,5 @@ export const DiagnosticReportSearchParamToClaimKey = {
  *
  * Keep `DiagnosticReport` paused at the typing/mapping layer until:
  * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. `CommunicationAttachedBundleSession.upsertActiveDiagnosticReportEntry(...)` exists
- * 3. GW Core readers/tests consume the same shared claim keys
+ * 2. GW Core readers/tests consume the same shared claim keys
  */

package/dist/models/profile-manager.d.ts

@@ -0,0 +1,85 @@
+import type { WalletMessagePriority, WalletQueuedMessage } from './wallet';
+/**
+ * Minimal local profile descriptor for memory-backed wallet/runtime tests.
+ *
+ * This stays intentionally below actor-specific SDK facades.
+ */
+export type ProfileManagerMemProfile = Readonly<{
+    profileId: string;
+    displayName?: string;
+    did: string;
+}>;
+/**
+ * Result returned by one backend message transport after submitting one local
+ * queued message envelope.
+ */
+export type BackendMessageTransportSubmitResult = Readonly<{
+    accepted: boolean;
+    retryable?: boolean;
+    errorMessage?: string;
+    responseEnvelope?: string;
+    locationUrl?: string;
+}>;
+/**
+ * Result returned by one backend message poll operation after a previous
+ * transport submit accepted the request asynchronously.
+ */
+export type BackendMessageTransportPollResult = Readonly<{
+    pending: boolean;
+    completed?: boolean;
+    retryable?: boolean;
+    errorMessage?: string;
+    responseEnvelope?: string;
+}>;
+/**
+ * Pluggable submit-only transport used by the low-level backend message manager.
+ */
+export type BackendMessageTransport = Readonly<{
+    submit(input: Readonly<{
+        message: WalletQueuedMessage;
+        envelope: string;
+    }>): Promise<BackendMessageTransportSubmitResult>;
+    poll?(input: Readonly<{
+        message: ProfileOutboxMessageRecord;
+    }>): Promise<BackendMessageTransportPollResult>;
+}>;
+/**
+ * One decoded inbound response associated with one DIDComm thread.
+ */
+export type BackendMessageResponseRecord = Readonly<{
+    thid: string;
+    receivedAt: string;
+    content: Record<string, unknown>;
+    meta: Record<string, unknown>;
+}>;
+/**
+ * Immutable historical record written after one profile message is submitted.
+ *
+ * It complements the mutable queue state by preserving:
+ * - the final submitted envelope
+ * - the last known queue status at submission time
+ * - the optional decoded response thread reference
+ */
+export type ProfileOutboxMessageRecord = Readonly<{
+    id: string;
+    thid?: string;
+    messageType?: string;
+    priority: string;
+    status: string;
+    transportStatus?: 'submitted' | 'completed' | 'failed';
+    recordedAt: string;
+    payload: Record<string, unknown>;
+    envelope: string;
+    responseThid?: string;
+    locationUrl?: string;
+    pollCount?: number;
+}>;
+/**
+ * Input used by `BackendMessageManagerMem` and `ProfileManagerMem` to queue one
+ * outbound business payload.
+ */
+export type QueueProfileMessageInput = Readonly<{
+    payload: Record<string, unknown>;
+    priority?: WalletMessagePriority;
+    recipientEncryptionJwk: Record<string, unknown>;
+}>;

package/dist/models/profile-manager.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+export {};

package/dist/models/wallet.d.ts

@@ -0,0 +1,59 @@
+import type { JWK } from './jwk';
+/**
+ * Canonical priority levels for wallet-managed outbound messages.
+ *
+ * Ordering rule:
+ * - `emergency` is always processed before all other priorities
+ * - for the same priority level, insertion order must be preserved
+ */
+export declare const WalletMessagePriorities: Readonly<{
+    readonly Emergency: "emergency";
+    readonly High: "high";
+    readonly Normal: "normal";
+    readonly Low: "low";
+}>;
+export type WalletMessagePriority = typeof WalletMessagePriorities[keyof typeof WalletMessagePriorities];
+/**
+ * Lifecycle states for one local wallet queue/outbox message.
+ */
+export declare const WalletQueueStatuses: Readonly<{
+    readonly Pending: "pending";
+    readonly Delivered: "delivered";
+    readonly Failed: "failed";
+}>;
+export type WalletQueueStatus = typeof WalletQueueStatuses[keyof typeof WalletQueueStatuses];
+/**
+ * One message tracked by the local wallet queue or outbox.
+ */
+export type WalletQueuedMessage = Readonly<{
+    id: string;
+    createdAt: string;
+    priority: WalletMessagePriority;
+    status: WalletQueueStatus;
+    sequence: number;
+    payload: Record<string, unknown>;
+    thid?: string;
+    messageType?: string;
+    deliveredAt?: string;
+    errorMessage?: string;
+}>;
+/**
+ * Input accepted by wallet-local queue implementations when creating one
+ * queued outbound message.
+ */
+export type WalletEnqueueMessageInput = Readonly<{
+    payload: Record<string, unknown>;
+    priority?: WalletMessagePriority;
+    thid?: string;
+    messageType?: string;
+    id?: string;
+    createdAt?: string;
+}>;
+/**
+ * Public summary of one wallet-managed entity key set.
+ */
+export type WalletManagedEntityDescriptor = Readonly<{
+    entityId: string;
+    signingJwk: JWK;
+    encryptionJwk: JWK;
+}>;

package/dist/models/wallet.js

@@ -0,0 +1,22 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+/**
+ * Canonical priority levels for wallet-managed outbound messages.
+ *
+ * Ordering rule:
+ * - `emergency` is always processed before all other priorities
+ * - for the same priority level, insertion order must be preserved
+ */
+export const WalletMessagePriorities = Object.freeze({
+    Emergency: 'emergency',
+    High: 'high',
+    Normal: 'normal',
+    Low: 'low',
+});
+/**
+ * Lifecycle states for one local wallet queue/outbox message.
+ */
+export const WalletQueueStatuses = Object.freeze({
+    Pending: 'pending',
+    Delivered: 'delivered',
+    Failed: 'failed',
+});

package/dist/utils/backend-message-manager-mem.d.ts

@@ -0,0 +1,67 @@
+import type { IWallet } from '../interfaces/IWallet';
+import type { IProfileOutboxRepository } from '../interfaces/IProfileOutboxRepository';
+import type { BackendMessageResponseRecord, BackendMessageTransport, ProfileOutboxMessageRecord, QueueProfileMessageInput } from '../models/profile-manager';
+import { type WalletQueuedMessage } from '../models/wallet';
+export type BackendMessageManagerMemOptions = Readonly<{
+    wallet: IWallet;
+    entityId: string;
+    transport: BackendMessageTransport;
+    outboxRepository: IProfileOutboxRepository;
+}>;
+/**
+ * Memory-backed backend message manager that:
+ * - queues outbound payloads through `WalletMem`
+ * - packs the next pending message as DIDComm-like JWS+JWE
+ * - submits it through an injected transport
+ * - unwraps the response and indexes it by `thid`
+ *
+ * This is the lowest reusable BFF/proxy slice before actor-specific SDK
+ * facades appear.
+ */
+export declare class BackendMessageManagerMem {
+    private readonly wallet;
+    private readonly entityId;
+    private readonly transport;
+    private readonly outboxRepository;
+    private readonly responsesByThread;
+    constructor(options: BackendMessageManagerMemOptions);
+    /**
+     * Queues one outbound business payload for later submission.
+     */
+    queueMessage(input: QueueProfileMessageInput): Promise<WalletQueuedMessage>;
+    /**
+     * Returns queued messages in current priority/FIFO processing order.
+     */
+    listQueuedMessages(): Promise<WalletQueuedMessage[]>;
+    /**
+     * Submits the next pending message through the injected transport and stores
+     * the decoded response by `thid` when one response envelope is returned.
+     */
+    submitNextPendingMessage(recipientEncryptionJwk: Record<string, unknown>): Promise<{
+        message: WalletQueuedMessage;
+        response?: BackendMessageResponseRecord;
+        pending?: boolean;
+    }>;
+    /**
+     * Returns the latest decoded response for one DIDComm thread.
+     */
+    getResponseByThreadId(thid: string): BackendMessageResponseRecord | undefined;
+    /**
+     * Lists submitted message history records preserved by the outbox repository.
+     */
+    listOutboxHistory(): Promise<ProfileOutboxMessageRecord[]>;
+    /**
+     * Polls one previously submitted asynchronous message by id.
+     */
+    pollSubmittedMessage(messageId: string): Promise<{
+        pending: boolean;
+        response?: BackendMessageResponseRecord;
+        record: ProfileOutboxMessageRecord;
+    }>;
+    /**
+     * Reads one decoded response by thread id, first from memory and then from the repository.
+     */
+    readResponseByThreadId(thid: string): Promise<BackendMessageResponseRecord | undefined>;
+    private persistMessageRecord;
+    private requireOutboxRecord;
+}