gdc-common-utils-ts 2.0.18 → 2.1.0

package/dist/utils/backend-message-manager-mem.js

@@ -0,0 +1,227 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { WalletQueueStatuses } from '../models/wallet.js';
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * 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 class BackendMessageManagerMem {
+    wallet;
+    entityId;
+    transport;
+    outboxRepository;
+    responsesByThread = new Map();
+    constructor(options) {
+        this.wallet = options.wallet;
+        this.entityId = String(options.entityId || '').trim();
+        this.transport = options.transport;
+        this.outboxRepository = options.outboxRepository;
+    }
+    /**
+     * Queues one outbound business payload for later submission.
+     */
+    async queueMessage(input) {
+        if (!this.wallet.enqueueMessage) {
+            throw new Error('BackendMessageManagerMem requires wallet.enqueueMessage().');
+        }
+        const thid = typeof input.payload['thid'] === 'string' ? String(input.payload['thid']) : undefined;
+        const messageType = typeof input.payload['type'] === 'string' ? String(input.payload['type']) : undefined;
+        return this.wallet.enqueueMessage({
+            payload: input.payload,
+            priority: input.priority,
+            thid,
+            messageType,
+        });
+    }
+    /**
+     * Returns queued messages in current priority/FIFO processing order.
+     */
+    async listQueuedMessages() {
+        if (!this.wallet.listMessages) {
+            throw new Error('BackendMessageManagerMem requires wallet.listMessages().');
+        }
+        return this.wallet.listMessages();
+    }
+    /**
+     * Submits the next pending message through the injected transport and stores
+     * the decoded response by `thid` when one response envelope is returned.
+     */
+    async submitNextPendingMessage(recipientEncryptionJwk) {
+        if (!this.wallet.peekNextMessage) {
+            throw new Error('BackendMessageManagerMem requires wallet.peekNextMessage().');
+        }
+        if (!this.wallet.pack) {
+            throw new Error('BackendMessageManagerMem requires wallet.pack().');
+        }
+        if (!this.wallet.markMessageDelivered || !this.wallet.markMessageFailed) {
+            throw new Error('BackendMessageManagerMem requires wallet.markMessageDelivered() and wallet.markMessageFailed().');
+        }
+        const next = await this.wallet.peekNextMessage();
+        if (!next || next.status !== WalletQueueStatuses.Pending) {
+            throw new Error('BackendMessageManagerMem found no pending queued message.');
+        }
+        const envelope = await this.wallet.pack(next.payload, recipientEncryptionJwk, this.entityId);
+        const transportResult = await this.transport.submit({
+            message: next,
+            envelope,
+        });
+        if (!transportResult.accepted) {
+            const failed = await this.wallet.markMessageFailed(next.id, String(transportResult.errorMessage || 'transport rejected queued message'));
+            await this.persistMessageRecord(failed, envelope, undefined, {
+                transportStatus: 'failed',
+            });
+            return { message: failed };
+        }
+        const delivered = await this.wallet.markMessageDelivered(next.id);
+        if (!transportResult.responseEnvelope) {
+            await this.persistMessageRecord(delivered, envelope, undefined, {
+                transportStatus: 'submitted',
+                locationUrl: transportResult.locationUrl,
+                pollCount: 0,
+            });
+            return { message: delivered, pending: true };
+        }
+        if (!this.wallet.unpack) {
+            throw new Error('BackendMessageManagerMem requires wallet.unpack() to decode response envelopes.');
+        }
+        const unpacked = await this.wallet.unpack(transportResult.responseEnvelope, this.entityId);
+        const responseContent = clone(unpacked.content);
+        const thid = String(responseContent['thid'] || delivered.thid || delivered.id).trim();
+        const response = {
+            thid,
+            receivedAt: new Date().toISOString(),
+            content: responseContent,
+            meta: clone(unpacked.meta),
+        };
+        this.responsesByThread.set(thid, response);
+        await this.outboxRepository.putResponse(response);
+        await this.persistMessageRecord(delivered, envelope, response.thid, {
+            transportStatus: 'completed',
+        });
+        return {
+            message: delivered,
+            response,
+        };
+    }
+    /**
+     * Returns the latest decoded response for one DIDComm thread.
+     */
+    getResponseByThreadId(thid) {
+        const normalizedThreadId = String(thid || '').trim();
+        const stored = this.responsesByThread.get(normalizedThreadId);
+        return stored ? clone(stored) : undefined;
+    }
+    /**
+     * Lists submitted message history records preserved by the outbox repository.
+     */
+    async listOutboxHistory() {
+        return this.outboxRepository.listMessages();
+    }
+    /**
+     * Polls one previously submitted asynchronous message by id.
+     */
+    async pollSubmittedMessage(messageId) {
+        if (!this.transport.poll) {
+            throw new Error('BackendMessageManagerMem requires transport.poll() for asynchronous polling.');
+        }
+        const currentRecord = await this.requireOutboxRecord(messageId);
+        const pollResult = await this.transport.poll({
+            message: currentRecord,
+        });
+        if (pollResult.pending) {
+            const pendingRecord = await this.outboxRepository.putMessage({
+                ...currentRecord,
+                transportStatus: 'submitted',
+                pollCount: (currentRecord.pollCount || 0) + 1,
+                recordedAt: new Date().toISOString(),
+            });
+            return {
+                pending: true,
+                record: pendingRecord,
+            };
+        }
+        if (!pollResult.completed || !pollResult.responseEnvelope) {
+            const failedRecord = await this.outboxRepository.putMessage({
+                ...currentRecord,
+                transportStatus: pollResult.retryable ? 'submitted' : 'failed',
+                pollCount: (currentRecord.pollCount || 0) + 1,
+                recordedAt: new Date().toISOString(),
+            });
+            return {
+                pending: Boolean(pollResult.retryable),
+                record: failedRecord,
+            };
+        }
+        if (!this.wallet.unpack) {
+            throw new Error('BackendMessageManagerMem requires wallet.unpack() to decode polled response envelopes.');
+        }
+        const unpacked = await this.wallet.unpack(pollResult.responseEnvelope, this.entityId);
+        const responseContent = clone(unpacked.content);
+        const thid = String(responseContent['thid'] || currentRecord.thid || currentRecord.id).trim();
+        const response = {
+            thid,
+            receivedAt: new Date().toISOString(),
+            content: responseContent,
+            meta: clone(unpacked.meta),
+        };
+        this.responsesByThread.set(thid, response);
+        await this.outboxRepository.putResponse(response);
+        const completedRecord = await this.outboxRepository.putMessage({
+            ...currentRecord,
+            transportStatus: 'completed',
+            responseThid: response.thid,
+            pollCount: (currentRecord.pollCount || 0) + 1,
+            recordedAt: new Date().toISOString(),
+        });
+        return {
+            pending: false,
+            response,
+            record: completedRecord,
+        };
+    }
+    /**
+     * Reads one decoded response by thread id, first from memory and then from the repository.
+     */
+    async readResponseByThreadId(thid) {
+        const inMemory = this.getResponseByThreadId(thid);
+        if (inMemory)
+            return inMemory;
+        const stored = await this.outboxRepository.getLatestResponseByThreadId(thid);
+        if (stored) {
+            this.responsesByThread.set(String(stored.thid || '').trim(), clone(stored));
+        }
+        return stored;
+    }
+    async persistMessageRecord(message, envelope, responseThid, options = {}) {
+        await this.outboxRepository.putMessage({
+            id: message.id,
+            thid: message.thid,
+            messageType: message.messageType,
+            priority: message.priority,
+            status: message.status,
+            transportStatus: options.transportStatus,
+            recordedAt: new Date().toISOString(),
+            payload: clone(message.payload),
+            envelope,
+            ...(responseThid ? { responseThid } : {}),
+            ...(options.locationUrl ? { locationUrl: options.locationUrl } : {}),
+            ...(typeof options.pollCount === 'number' ? { pollCount: options.pollCount } : {}),
+        });
+    }
+    async requireOutboxRecord(messageId) {
+        const normalizedMessageId = String(messageId || '').trim();
+        const stored = await this.outboxRepository.getMessage(normalizedMessageId);
+        if (!stored) {
+            throw new Error(`BackendMessageManagerMem outbox record not found: ${normalizedMessageId}`);
+        }
+        return stored;
+    }
+}

package/dist/utils/bundle-didcomm-payload.d.ts

@@ -0,0 +1,29 @@
+import type { IDecodedDidcommPayload } from '../models/confidential-message';
+export declare const BundleDidcommEntryTypes: Readonly<{
+    readonly Batch: "Bundle-batch-request-v1.0";
+    readonly Document: "Bundle-document-request-v1.0";
+}>;
+/**
+ * Input contract for wrapping one bundle-like resource as one low-level
+ * DIDComm-style batch payload.
+ */
+export type BuildDidcommPayloadFromBundleInput = Readonly<{
+    bundle: Record<string, unknown>;
+    iss: string;
+    aud: string;
+    jti: string;
+    thid: string;
+    entryType?: string;
+}>;
+/**
+ * Builds one low-level DIDComm-style payload carrying one direct `Bundle`
+ * resource in `body.data[0].resource`.
+ *
+ * This path is meant for operational bundles such as employee/search/purge
+ * flows that travel as a bundle itself, not nested inside a `Communication`.
+ */
+export declare function buildDidcommPayloadFromBundle(input: BuildDidcommPayloadFromBundleInput): IDecodedDidcommPayload;
+/**
+ * Reads the first `Bundle` resource carried under `body.data[0].resource`.
+ */
+export declare function getFirstBundleResourceFromDidcommPayload(payload: IDecodedDidcommPayload): Record<string, unknown>;

package/dist/utils/bundle-didcomm-payload.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+export const BundleDidcommEntryTypes = Object.freeze({
+    Batch: 'Bundle-batch-request-v1.0',
+    Document: 'Bundle-document-request-v1.0',
+});
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Builds one low-level DIDComm-style payload carrying one direct `Bundle`
+ * resource in `body.data[0].resource`.
+ *
+ * This path is meant for operational bundles such as employee/search/purge
+ * flows that travel as a bundle itself, not nested inside a `Communication`.
+ */
+export function buildDidcommPayloadFromBundle(input) {
+    return {
+        iss: String(input.iss || '').trim(),
+        aud: String(input.aud || '').trim(),
+        jti: String(input.jti || '').trim(),
+        thid: String(input.thid || '').trim(),
+        type: String(input.entryType || BundleDidcommEntryTypes.Batch).trim(),
+        body: {
+            data: [
+                {
+                    id: String(input.jti || '').trim(),
+                    type: String(input.entryType || BundleDidcommEntryTypes.Batch).trim(),
+                    resource: clone(input.bundle),
+                },
+            ],
+        },
+    };
+}
+/**
+ * Reads the first `Bundle` resource carried under `body.data[0].resource`.
+ */
+export function getFirstBundleResourceFromDidcommPayload(payload) {
+    const first = Array.isArray(payload?.body?.data)
+        ? payload.body.data[0]
+        : undefined;
+    const resource = first?.resource && typeof first.resource === 'object'
+        ? clone(first.resource)
+        : {};
+    if (String(resource['resourceType'] || '').trim() !== 'Bundle') {
+        throw new Error('getFirstBundleResourceFromDidcommPayload requires body.data[0].resource.resourceType = Bundle.');
+    }
+    return resource;
+}

package/dist/utils/communication-attached-bundle-session-helpers.d.ts

@@ -0,0 +1,54 @@
+import { type HealthcareCanonicalSectionFamily } from '../constants/healthcare';
+import type { BundleEntry, BundleEntryResource, BundleJsonApi } from '../models/bundle';
+import type { CommunicationAttachedBundleSessionMode, ConsentEditorClassifiedActorRole, ConsentEditorClassifiedActors, ConsentEditorClassifiedOrganization, ConsentEditorClassifiedPurpose, ConsentEditorClassifiedRole, ConsentEditorClassifiedRoles, ConsentEditorClassifiedTarget, ConsentViewModel, ConsentEditorScopeCode, ConsentEditorTargetKind } from '../models/communication-attached-bundle-session';
+export declare const CSV_SEPARATOR = ",";
+export declare function ensureEntryResource(entry: BundleEntry, mode: CommunicationAttachedBundleSessionMode): BundleEntryResource;
+export declare function validateBundleLike(bundle: BundleJsonApi<BundleEntry>, mode: CommunicationAttachedBundleSessionMode): void;
+export declare function createEmptyBundle(): BundleJsonApi<BundleEntry>;
+export declare function encodeBundleToBase64(bundle: BundleJsonApi<BundleEntry>): string;
+export declare function cloneBundle(bundle: BundleJsonApi<BundleEntry>): BundleJsonApi<BundleEntry>;
+export declare function cloneEntry(entry: BundleEntry): BundleEntry;
+export declare function cloneUnknownValue<T>(value: T): T;
+export declare function asTrimmedString(value: unknown): string;
+export declare function resolveContainedDocumentsClaimKey(resourceType: string): string;
+export declare function resolveSubjectFromClaims(claims: Record<string, unknown>): string;
+/**
+ * Resolves the canonical resource-scoped identifier used for upsert matching.
+ */
+export declare function resolveBundleEntryIdentifier(claims: Record<string, unknown>): string;
+/**
+ * Resolves the stable entry id value stored in `BundleEntry.id`.
+ */
+export declare function resolveBundleEntryCanonicalIdValue(claims: Record<string, unknown>): string;
+export declare function setIfMissing(target: Record<string, unknown>, key: string, value: unknown): void;
+export declare function runtimeUuid(prefix: string): string;
+export declare function splitCsv(value: unknown): string[];
+export declare function normalizeCsvValues(values: readonly unknown[]): string[];
+export declare function buildClassifiedConsentTarget(kind: ConsentEditorTargetKind, code: string, scopeCodes: readonly ConsentEditorScopeCode[], sectionFamily?: HealthcareCanonicalSectionFamily): ConsentEditorClassifiedTarget;
+export declare function buildSectionCatalogOptions(sectionKind: HealthcareCanonicalSectionFamily): ConsentEditorClassifiedTarget[];
+export declare function normalizeScopeCodes(scopeCodes: readonly ConsentEditorScopeCode[]): ConsentEditorScopeCode[];
+export declare function normalizeClassifiedTargets(targets: readonly ConsentEditorClassifiedTarget[]): ConsentEditorClassifiedTarget[];
+export declare function resolveConsentTargetDisplay(kind: ConsentEditorTargetKind, code: string): string | undefined;
+export declare function resolveConsentScopeDisplay(scopeCode: ConsentEditorScopeCode): string;
+export declare function resolveConsentPurposeDisplay(code: string): string;
+export declare function looksLikeEmailToken(value: string): boolean;
+export declare function looksLikePhoneToken(value: string): boolean;
+export declare function looksLikeJurisdictionToken(value: string): boolean;
+export declare function parseDidWebOrganizationToken(value: string): ConsentEditorClassifiedOrganization | undefined;
+export declare function parseConsentActorRole(value: string): ConsentEditorClassifiedActorRole | undefined;
+export declare function flattenClassifiedActors(classifiedActors: ConsentEditorClassifiedActors): string[];
+export declare function serializeClassifiedOrganization(organization: ConsentEditorClassifiedOrganization): string;
+export declare function flattenClassifiedRoles(classifiedRoles: ConsentEditorClassifiedRoles): string[];
+export declare function serializeClassifiedRole(role: ConsentEditorClassifiedRole): string;
+export declare function flattenClassifiedTargets(classifiedTargets: readonly ConsentEditorClassifiedTarget[]): Readonly<{
+    coreSections: readonly string[];
+    kindOfDocuments: readonly string[];
+    typeOfServices: readonly string[];
+    subjectMatterDomains: readonly string[];
+    resourceTypes: readonly string[];
+}>;
+export declare function classifyConsentTargetsFromClaims(claims: Record<string, unknown>): ConsentEditorClassifiedTarget[];
+export declare function classifyConsentPurposes(purposeCodes: readonly string[]): ConsentEditorClassifiedPurpose[];
+export declare function classifyConsentRoles(roleTokens: readonly string[]): ConsentEditorClassifiedRoles;
+export declare function classifyConsentActors(actorTokens: readonly string[], actorRoleToken?: string): ConsentEditorClassifiedActors;
+export declare function buildConsentViewModel(activeEntry: BundleEntry | null, decision: string, classifiedActors: ConsentEditorClassifiedActors, classifiedRoles: ConsentEditorClassifiedRoles, classifiedPurposes: readonly ConsentEditorClassifiedPurpose[], classifiedTargets: readonly ConsentEditorClassifiedTarget[]): ConsentViewModel;