gdc-common-utils-ts 2.0.18 → 2.2.2

package/dist/utils/communication-consent-access-editor.d.ts

@@ -0,0 +1,85 @@
+import { type HealthcareActorRoleDescriptor, type HealthcareSectionDescriptor } from '../constants/healthcare';
+import type { DataspaceSector } from '../constants/sectors';
+import type { CommunicationAttachedBundleSessionOptions, ConsentEditorClassifiedActors, ConsentEditorClassifiedPurpose, ConsentEditorClassifiedRoles, ConsentEditorClassifiedTarget, ConsentViewModel } from '../models/communication-attached-bundle-session';
+import type { ConsentDuplicateRuleConflict } from './consent-duplicate-rules';
+import { CommunicationAttachedBundleSession } from './communication-attached-bundle-session';
+/**
+ * High-level consent-access editor alias for onboarding and app-facing code.
+ *
+ * This keeps the business intent explicit for developers who are editing
+ * Consent access rules inside a Communication-carried bundle and should not
+ * need to start from the lower-level generic session name.
+ */
+export declare class ConsentAccessEditor extends CommunicationAttachedBundleSession {
+    /** Returns duplicate atomic consent-rule conflicts across the current bundle. */
+    getConsentRuleDuplicateConflicts(): ConsentDuplicateRuleConflict[];
+    /** Returns duplicate atomic consent-rule conflicts affecting the active Consent entry. */
+    getActiveConsentRuleDuplicateConflicts(): ConsentDuplicateRuleConflict[];
+    /** Returns one frontend-facing editable view model for the active Consent entry. */
+    getConsentViewModel(): ConsentViewModel;
+    /** Applies one frontend-facing editable view model back into the active Consent entry. */
+    applyConsentViewModel(viewModel: ConsentViewModel): this;
+    /** Returns the canonical permit/deny decision from the active Consent entry. */
+    getDecision(): string;
+    /** @deprecated Use `getDecision()`. */
+    getPermit(): string;
+    /** Returns target classification derived from the current consent claim contract. */
+    getTargetsClassified(): ConsentEditorClassifiedTarget[];
+    getCoreSectionOptions(): readonly ConsentEditorClassifiedTarget[];
+    getCoreSectionCatalog(): Readonly<Record<string, HealthcareSectionDescriptor>>;
+    getKindOfDocumentOptions(): readonly ConsentEditorClassifiedTarget[];
+    getKindOfDocumentCatalog(): Readonly<Record<string, HealthcareSectionDescriptor>>;
+    getTypeOfServiceOptions(): readonly ConsentEditorClassifiedTarget[];
+    getTypeOfServiceCatalog(): Readonly<Record<string, HealthcareSectionDescriptor>>;
+    getSubjectMatterDomainOptions(): readonly ConsentEditorClassifiedTarget[];
+    getSubjectMatterDomainCatalog(): Readonly<Record<string, HealthcareSectionDescriptor>>;
+    getResourceTypeOptions(): readonly ConsentEditorClassifiedTarget[];
+    getResourceTypeCatalog(): readonly string[];
+    getAvailableProfessionalRolesBySector(sector: DataspaceSector): Readonly<Record<string, HealthcareActorRoleDescriptor>>;
+    getAvailableRelationshipRoles(): Readonly<Record<string, HealthcareActorRoleDescriptor>>;
+    getSelectedCoreSections(): string[];
+    getSelectedKindOfDocuments(): string[];
+    getSelectedTypeOfServices(): string[];
+    getSelectedSubjectMatterDomains(): string[];
+    getSelectedResourceTypes(): string[];
+    setSelectedCoreSections(codes: readonly string[]): this;
+    setSelectedKindOfDocuments(codes: readonly string[]): this;
+    setSelectedTypeOfServices(codes: readonly string[]): this;
+    setSelectedSubjectMatterDomains(codes: readonly string[]): this;
+    setSelectedResourceTypes(codes: readonly string[]): this;
+    addCoreSections(codes: readonly string[]): this;
+    removeCoreSections(codes: readonly string[]): this;
+    addKindOfDocuments(codes: readonly string[]): this;
+    removeKindOfDocuments(codes: readonly string[]): this;
+    addTypeOfServices(codes: readonly string[]): this;
+    removeTypeOfServices(codes: readonly string[]): this;
+    addSubjectMatterDomains(codes: readonly string[]): this;
+    removeSubjectMatterDomains(codes: readonly string[]): this;
+    addResourceTypes(codes: readonly string[]): this;
+    removeResourceTypes(codes: readonly string[]): this;
+    getPurposesClassified(): ConsentEditorClassifiedPurpose[];
+    getSelectedPurposes(): string[];
+    setSelectedPurposes(codes: readonly string[]): this;
+    addPurposes(codes: readonly string[]): this;
+    removePurposes(codes: readonly string[]): this;
+    getRolesClassified(): ConsentEditorClassifiedRoles;
+    getSelectedRoles(): string[];
+    setSelectedRoles(codes: readonly string[]): this;
+    addRoles(codes: readonly string[]): this;
+    removeRoles(codes: readonly string[]): this;
+    getActorsClassified(): ConsentEditorClassifiedActors;
+    private getSelectedSectionCodesByFamily;
+    private setSelectedSectionCodesByFamily;
+    private addSectionCodesByFamily;
+    private removeSectionCodesByFamily;
+    private setActiveEntryClaimList;
+    private addActiveEntryClaimList;
+    private removeActiveEntryClaimList;
+}
+/**
+ * High-level factory for consent-access editing.
+ *
+ * Prefer this name in onboarding docs when the developer intent is:
+ * "edit a Consent access bundle carried by a Communication".
+ */
+export declare function createConsentAccessEditor(options?: CommunicationAttachedBundleSessionOptions): ConsentAccessEditor;

package/dist/utils/communication-consent-access-editor.js

@@ -0,0 +1,244 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { getHealthcareProfessionalRolesBySector, getHealthcareRolesByFamily, getHealthcareSectionsByFamily, getHealthcareSectionFamilyByCode, HealthcareRoleFamilies, HealthcareCanonicalSectionFamilies, } from '../constants/healthcare.js';
+import { ClaimConsent } from '../models/consent-rule.js';
+import { ConsentEditorScopeCodes, ConsentEditorTargetKinds, } from '../models/communication-attached-bundle-session.js';
+import { detectDuplicateConsentRuleConflicts } from './consent-duplicate-rules.js';
+import { CommunicationAttachedBundleSession } from './communication-attached-bundle-session.js';
+import { asTrimmedString, buildClassifiedConsentTarget, buildConsentViewModel, buildSectionCatalogOptions, classifyConsentActors, classifyConsentPurposes, classifyConsentRoles, classifyConsentTargetsFromClaims, CSV_SEPARATOR, flattenClassifiedActors, flattenClassifiedRoles, flattenClassifiedTargets, normalizeCsvValues, splitCsv, } from './communication-attached-bundle-session-helpers.js';
+/**
+ * High-level consent-access editor alias for onboarding and app-facing code.
+ *
+ * This keeps the business intent explicit for developers who are editing
+ * Consent access rules inside a Communication-carried bundle and should not
+ * need to start from the lower-level generic session name.
+ */
+export class ConsentAccessEditor extends CommunicationAttachedBundleSession {
+    /** Returns duplicate atomic consent-rule conflicts across the current bundle. */
+    getConsentRuleDuplicateConflicts() {
+        return detectDuplicateConsentRuleConflicts(this.getBundleInMemory().data);
+    }
+    /** Returns duplicate atomic consent-rule conflicts affecting the active Consent entry. */
+    getActiveConsentRuleDuplicateConflicts() {
+        const activeEntryIndex = this.getActiveEntryIndex();
+        if (activeEntryIndex === null) {
+            return [];
+        }
+        return this.getConsentRuleDuplicateConflicts()
+            .filter((conflict) => conflict.affectedEntries.some((entry) => entry.entryIndex === activeEntryIndex));
+    }
+    /** Returns one frontend-facing editable view model for the active Consent entry. */
+    getConsentViewModel() {
+        return buildConsentViewModel(this.getActiveEntry(), this.getDecision(), this.getActorsClassified(), this.getRolesClassified(), this.getPurposesClassified(), this.getTargetsClassified());
+    }
+    /** Applies one frontend-facing editable view model back into the active Consent entry. */
+    applyConsentViewModel(viewModel) {
+        this.setActiveEntryClaim(ClaimConsent.identifier, viewModel.identifier);
+        this.setActiveEntryClaim(ClaimConsent.subject, viewModel.subject);
+        this.setActiveEntryClaim(ClaimConsent.decision, viewModel.decision);
+        this.setActiveEntryClaimList(ClaimConsent.actorIdentifier, flattenClassifiedActors(viewModel.classifiedActors));
+        this.setSelectedRoles(flattenClassifiedRoles(viewModel.classifiedRoles));
+        this.setSelectedPurposes(viewModel.classifiedPurposes.map((purpose) => purpose.code));
+        const flattenedTargets = flattenClassifiedTargets(viewModel.classifiedTargets);
+        this.setSelectedCoreSections(flattenedTargets.coreSections);
+        this.setSelectedKindOfDocuments(flattenedTargets.kindOfDocuments);
+        this.setSelectedTypeOfServices(flattenedTargets.typeOfServices);
+        this.setSelectedSubjectMatterDomains(flattenedTargets.subjectMatterDomains);
+        this.setSelectedResourceTypes(flattenedTargets.resourceTypes);
+        return this;
+    }
+    /** Returns the canonical permit/deny decision from the active Consent entry. */
+    getDecision() {
+        return asTrimmedString(this.getActiveEntryClaim(ClaimConsent.decision));
+    }
+    /** @deprecated Use `getDecision()`. */
+    getPermit() {
+        return this.getDecision();
+    }
+    /** Returns target classification derived from the current consent claim contract. */
+    getTargetsClassified() {
+        return classifyConsentTargetsFromClaims({
+            ...(this.getActiveEntry()?.resource?.meta?.claims || {}),
+        });
+    }
+    getCoreSectionOptions() {
+        return buildSectionCatalogOptions(HealthcareCanonicalSectionFamilies.CoreSection);
+    }
+    getCoreSectionCatalog() {
+        return getHealthcareSectionsByFamily(HealthcareCanonicalSectionFamilies.CoreSection);
+    }
+    getKindOfDocumentOptions() {
+        return buildSectionCatalogOptions(HealthcareCanonicalSectionFamilies.KindOfDocument);
+    }
+    getKindOfDocumentCatalog() {
+        return getHealthcareSectionsByFamily(HealthcareCanonicalSectionFamilies.KindOfDocument);
+    }
+    getTypeOfServiceOptions() {
+        return buildSectionCatalogOptions(HealthcareCanonicalSectionFamilies.TypeOfService);
+    }
+    getTypeOfServiceCatalog() {
+        return getHealthcareSectionsByFamily(HealthcareCanonicalSectionFamilies.TypeOfService);
+    }
+    getSubjectMatterDomainOptions() {
+        return buildSectionCatalogOptions(HealthcareCanonicalSectionFamilies.SubjectMatterDomain);
+    }
+    getSubjectMatterDomainCatalog() {
+        return getHealthcareSectionsByFamily(HealthcareCanonicalSectionFamilies.SubjectMatterDomain);
+    }
+    getResourceTypeOptions() {
+        return this.getSelectedResourceTypes().map((code) => buildClassifiedConsentTarget(ConsentEditorTargetKinds.ResourceType, code, [ConsentEditorScopeCodes.Read]));
+    }
+    getResourceTypeCatalog() {
+        return Object.values(ResourceTypesFhirR4).filter((resourceType) => resourceType !== ResourceTypesFhirR4.Bundle);
+    }
+    getAvailableProfessionalRolesBySector(sector) {
+        return getHealthcareProfessionalRolesBySector(sector);
+    }
+    getAvailableRelationshipRoles() {
+        return getHealthcareRolesByFamily(HealthcareRoleFamilies.PersonalRelationshipHl7);
+    }
+    getSelectedCoreSections() {
+        return this.getSelectedSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.CoreSection);
+    }
+    getSelectedKindOfDocuments() {
+        return splitCsv(this.getActiveEntryClaim(ClaimConsent.category));
+    }
+    getSelectedTypeOfServices() {
+        return this.getSelectedSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.TypeOfService);
+    }
+    getSelectedSubjectMatterDomains() {
+        return this.getSelectedSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.SubjectMatterDomain);
+    }
+    getSelectedResourceTypes() {
+        return splitCsv(this.getActiveEntryClaim(ClaimConsent.resourceType));
+    }
+    setSelectedCoreSections(codes) {
+        return this.setSelectedSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.CoreSection, codes);
+    }
+    setSelectedKindOfDocuments(codes) {
+        return this.setActiveEntryClaimList(ClaimConsent.category, codes);
+    }
+    setSelectedTypeOfServices(codes) {
+        return this.setSelectedSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.TypeOfService, codes);
+    }
+    setSelectedSubjectMatterDomains(codes) {
+        return this.setSelectedSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.SubjectMatterDomain, codes);
+    }
+    setSelectedResourceTypes(codes) {
+        return this.setActiveEntryClaimList(ClaimConsent.resourceType, codes);
+    }
+    addCoreSections(codes) {
+        return this.addSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.CoreSection, codes);
+    }
+    removeCoreSections(codes) {
+        return this.removeSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.CoreSection, codes);
+    }
+    addKindOfDocuments(codes) {
+        return this.addActiveEntryClaimList(ClaimConsent.category, codes);
+    }
+    removeKindOfDocuments(codes) {
+        return this.removeActiveEntryClaimList(ClaimConsent.category, codes);
+    }
+    addTypeOfServices(codes) {
+        return this.addSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.TypeOfService, codes);
+    }
+    removeTypeOfServices(codes) {
+        return this.removeSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.TypeOfService, codes);
+    }
+    addSubjectMatterDomains(codes) {
+        return this.addSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.SubjectMatterDomain, codes);
+    }
+    removeSubjectMatterDomains(codes) {
+        return this.removeSectionCodesByFamily(ClaimConsent.action, HealthcareCanonicalSectionFamilies.SubjectMatterDomain, codes);
+    }
+    addResourceTypes(codes) {
+        return this.addActiveEntryClaimList(ClaimConsent.resourceType, codes);
+    }
+    removeResourceTypes(codes) {
+        return this.removeActiveEntryClaimList(ClaimConsent.resourceType, codes);
+    }
+    getPurposesClassified() {
+        return classifyConsentPurposes(this.getSelectedPurposes());
+    }
+    getSelectedPurposes() {
+        return splitCsv(this.getActiveEntryClaim(ClaimConsent.purpose));
+    }
+    setSelectedPurposes(codes) {
+        return this.setActiveEntryClaimList(ClaimConsent.purpose, codes);
+    }
+    addPurposes(codes) {
+        return this.addActiveEntryClaimList(ClaimConsent.purpose, codes);
+    }
+    removePurposes(codes) {
+        return this.removeActiveEntryClaimList(ClaimConsent.purpose, codes);
+    }
+    getRolesClassified() {
+        return classifyConsentRoles(this.getSelectedRoles());
+    }
+    getSelectedRoles() {
+        return splitCsv(this.getActiveEntryClaim(ClaimConsent.actorRole));
+    }
+    setSelectedRoles(codes) {
+        return this.setActiveEntryClaimList(ClaimConsent.actorRole, codes);
+    }
+    addRoles(codes) {
+        return this.addActiveEntryClaimList(ClaimConsent.actorRole, codes);
+    }
+    removeRoles(codes) {
+        return this.removeActiveEntryClaimList(ClaimConsent.actorRole, codes);
+    }
+    getActorsClassified() {
+        const claims = {
+            ...(this.getActiveEntry()?.resource?.meta?.claims || {}),
+        };
+        return classifyConsentActors(splitCsv(claims[ClaimConsent.actorIdentifier]), splitCsv(claims[ClaimConsent.actorRole])[0] || '');
+    }
+    getSelectedSectionCodesByFamily(claimKey, family) {
+        return splitCsv(this.getActiveEntryClaim(claimKey))
+            .filter((code) => getHealthcareSectionFamilyByCode(code) === family);
+    }
+    setSelectedSectionCodesByFamily(claimKey, family, codes) {
+        const preserved = splitCsv(this.getActiveEntryClaim(claimKey))
+            .filter((code) => getHealthcareSectionFamilyByCode(code) !== family);
+        return this.setActiveEntryClaimList(claimKey, [...preserved, ...codes]);
+    }
+    addSectionCodesByFamily(claimKey, family, codes) {
+        const next = [...this.getSelectedSectionCodesByFamily(claimKey, family), ...codes];
+        return this.setSelectedSectionCodesByFamily(claimKey, family, next);
+    }
+    removeSectionCodesByFamily(claimKey, family, codes) {
+        const codesToRemove = new Set(normalizeCsvValues(codes));
+        const next = this.getSelectedSectionCodesByFamily(claimKey, family)
+            .filter((code) => !codesToRemove.has(code));
+        return this.setSelectedSectionCodesByFamily(claimKey, family, next);
+    }
+    setActiveEntryClaimList(key, values) {
+        const normalized = normalizeCsvValues(values);
+        if (normalized.length === 0) {
+            return this.removeActiveEntryClaim(key);
+        }
+        return this.setActiveEntryClaim(key, normalized.join(CSV_SEPARATOR));
+    }
+    addActiveEntryClaimList(key, values) {
+        const next = normalizeCsvValues([
+            ...splitCsv(this.getActiveEntryClaim(key)),
+            ...values,
+        ]);
+        return this.setActiveEntryClaimList(key, next);
+    }
+    removeActiveEntryClaimList(key, values) {
+        const valuesToRemove = new Set(normalizeCsvValues(values));
+        const next = splitCsv(this.getActiveEntryClaim(key))
+            .filter((value) => !valuesToRemove.has(value));
+        return this.setActiveEntryClaimList(key, next);
+    }
+}
+/**
+ * High-level factory for consent-access editing.
+ *
+ * Prefer this name in onboarding docs when the developer intent is:
+ * "edit a Consent access bundle carried by a Communication".
+ */
+export function createConsentAccessEditor(options = {}) {
+    return new ConsentAccessEditor(options);
+}

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

@@ -0,0 +1,38 @@
+import type { IDecodedDidcommPayload } from '../models/confidential-message';
+export declare const CommunicationDidcommEntryTypes: Readonly<{
+    readonly AttachedBundle: "Communication-attached-bundle-v1.0";
+}>;
+/**
+ * Input contract for wrapping canonical Communication claims as one low-level
+ * DIDComm-style batch payload.
+ */
+export type BuildDidcommPayloadFromCommunicationClaimsInput = Readonly<{
+    communicationClaims: Record<string, unknown>;
+    iss: string;
+    aud: string;
+    jti: string;
+    thid: string;
+    entryType?: string;
+}>;
+/**
+ * Builds the low-level DIDComm-style batch payload that carries one FHIR-like
+ * `Communication` resource authored from canonical communication claims.
+ *
+ * This helper intentionally stays below actor-specific SDK facades so frontend,
+ * BFF, and GW-like tests can reuse the same wrapping contract.
+ */
+export declare function buildDidcommPayloadFromCommunicationClaims(input: BuildDidcommPayloadFromCommunicationClaimsInput): IDecodedDidcommPayload;
+/**
+ * Reads canonical communication claims from the first `body.data[]` entry of
+ * one DIDComm-style payload.
+ */
+export declare function getFirstCommunicationClaimsFromDidcommPayload(payload: IDecodedDidcommPayload): Record<string, unknown>;
+/**
+ * Reads canonical communication claims from every `body.data[]` entry of one
+ * DIDComm-style payload.
+ */
+export declare function getCommunicationClaimsListFromDidcommPayload(payload: IDecodedDidcommPayload): Record<string, unknown>[];
+/**
+ * Decodes the attached bundle carried in `Communication.content-attachment-data`.
+ */
+export declare function decodeAttachedBundleFromCommunicationClaims(communicationClaims: Record<string, unknown>): Record<string, unknown>;

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

@@ -0,0 +1,85 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { DidcommMessageTypes } from '../constants/didcomm.js';
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+import { transformCommunicationClaimsToResourceFhirR4 } from './communication-fhir-r4.js';
+export const CommunicationDidcommEntryTypes = Object.freeze({
+    AttachedBundle: DidcommMessageTypes.CommunicationAttachedBundle,
+});
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Builds the low-level DIDComm-style batch payload that carries one FHIR-like
+ * `Communication` resource authored from canonical communication claims.
+ *
+ * This helper intentionally stays below actor-specific SDK facades so frontend,
+ * BFF, and GW-like tests can reuse the same wrapping contract.
+ */
+export function buildDidcommPayloadFromCommunicationClaims(input) {
+    const claims = clone(input.communicationClaims);
+    const transformed = transformCommunicationClaimsToResourceFhirR4([claims], {
+        mode: 'strict',
+    });
+    const communicationResource = transformed.resources[0] || {};
+    return {
+        iss: String(input.iss || '').trim(),
+        aud: String(input.aud || '').trim(),
+        jti: String(input.jti || '').trim(),
+        thid: String(input.thid || '').trim(),
+        type: CommunicationDidcommEntryTypes.AttachedBundle,
+        body: {
+            data: [
+                {
+                    id: String(claims[CommunicationClaim.Identifier] || input.jti || '').trim(),
+                    type: String(input.entryType || CommunicationDidcommEntryTypes.AttachedBundle).trim(),
+                    meta: {
+                        claims,
+                    },
+                    resource: communicationResource,
+                },
+            ],
+        },
+    };
+}
+/**
+ * Reads canonical communication claims from the first `body.data[]` entry of
+ * one DIDComm-style payload.
+ */
+export function getFirstCommunicationClaimsFromDidcommPayload(payload) {
+    return getCommunicationClaimsListFromDidcommPayload(payload)[0] || {};
+}
+/**
+ * Reads canonical communication claims from every `body.data[]` entry of one
+ * DIDComm-style payload.
+ */
+export function getCommunicationClaimsListFromDidcommPayload(payload) {
+    const entries = Array.isArray(payload?.body?.data) ? payload.body.data : [];
+    return entries.map((first) => {
+        const metaClaims = first?.meta && typeof first.meta === 'object'
+            ? first.meta['claims']
+            : undefined;
+        if (metaClaims && typeof metaClaims === 'object') {
+            return clone(metaClaims);
+        }
+        const resource = first?.resource && typeof first.resource === 'object'
+            ? first.resource
+            : {};
+        const meta = resource.meta && typeof resource.meta === 'object'
+            ? resource.meta
+            : {};
+        const claims = meta.claims && typeof meta.claims === 'object'
+            ? meta.claims
+            : {};
+        return clone(claims);
+    });
+}
+/**
+ * Decodes the attached bundle carried in `Communication.content-attachment-data`.
+ */
+export function decodeAttachedBundleFromCommunicationClaims(communicationClaims) {
+    const encoded = String(communicationClaims[CommunicationClaim.ContentAttachmentData] || '').trim();
+    if (!encoded) {
+        throw new Error(`decodeAttachedBundleFromCommunicationClaims requires ${CommunicationClaim.ContentAttachmentData}.`);
+    }
+    return JSON.parse(Buffer.from(encoded, 'base64').toString('utf8'));
+}

package/dist/utils/communication-document-reference.d.ts

@@ -25,6 +25,18 @@ export type BuildDocumentReferenceResult = {
     evidence: EvidenceObjectDLT[];
     warnings: string[];
 };
+export type BlockchainArtifactDocumentReferenceInput = Readonly<{
+    subject: string;
+    resource?: Record<string, unknown>;
+    contentDataBase64?: string;
+    contentType?: string;
+    identifier?: string;
+    title?: string;
+    description?: string;
+    date?: string;
+    location?: string;
+    language?: string;
+}>;
 /**
  * Detects the logical attachment kind from a MIME type.
  *
@@ -39,3 +51,14 @@ export declare function detectAttachmentKind(contentType?: string): AttachmentKi
  * @param options.mode `strict` throws on invalid input, `normalize` applies best-effort defaults.
  */
 export declare function buildDocumentReferenceFromCommunicationPayload(communication: Record<string, any>, options?: BuildDocumentReferenceOptions): BuildDocumentReferenceResult;
+/**
+ * Builds a blockchain-ready `DocumentReference` projection from either a FHIR
+ * resource or already-encoded attachment bytes.
+ *
+ * The resulting projection keeps two identifiers distinct:
+ * - `contentCid`: canonical content address used for blockchain registration
+ * - `documentReference.identifier`: optional business identifier supplied by the caller
+ *
+ * @param input Source artifact data to wrap.
+ */
+export declare function buildBlockchainArtifactDocumentReference(input: BlockchainArtifactDocumentReferenceInput): BuildDocumentReferenceResult;

package/dist/utils/communication-document-reference.js

@@ -38,6 +38,9 @@ function cidFromBytes(bytes) {
 function decodeBase64(data) {
     return Uint8Array.from(Buffer.from(data, 'base64'));
 }
+function encodeBase64Utf8(data) {
+    return Buffer.from(data, 'utf8').toString('base64');
+}
 function toStringOrUndefined(value) {
     if (value === undefined || value === null)
         return undefined;
@@ -168,3 +171,89 @@ export function buildDocumentReferenceFromCommunicationPayload(communication, op
         warnings,
     };
 }
+/**
+ * Builds a blockchain-ready `DocumentReference` projection from either a FHIR
+ * resource or already-encoded attachment bytes.
+ *
+ * The resulting projection keeps two identifiers distinct:
+ * - `contentCid`: canonical content address used for blockchain registration
+ * - `documentReference.identifier`: optional business identifier supplied by the caller
+ *
+ * @param input Source artifact data to wrap.
+ */
+export function buildBlockchainArtifactDocumentReference(input) {
+    const subject = toStringOrUndefined(input.subject);
+    if (!subject) {
+        throw new Error('buildBlockchainArtifactDocumentReference requires subject.');
+    }
+    const resource = input.resource;
+    const hasResource = !!resource && typeof resource === 'object' && !Array.isArray(resource);
+    const contentType = toStringOrUndefined(input.contentType) || (hasResource ? 'application/fhir+json' : 'application/octet-stream');
+    const title = toStringOrUndefined(input.title) || (hasResource
+        ? `${String(resource.resourceType || 'resource').toLowerCase()}.json`
+        : 'artifact.bin');
+    let contentDataBase64 = toStringOrUndefined(input.contentDataBase64);
+    let contentCid;
+    let communicationLike;
+    if (hasResource) {
+        const serialized = JSON.stringify(resource);
+        contentDataBase64 = encodeBase64Utf8(serialized);
+        contentCid = fhirResourceToCid(resource).cid;
+        communicationLike = {
+            resourceType: 'Communication',
+            meta: { claims: { [CommunicationClaim.Subject]: subject } },
+            payload: [{ contentAttachment: { contentType, data: contentDataBase64, title } }],
+        };
+    }
+    else {
+        if (!contentDataBase64) {
+            throw new Error('buildBlockchainArtifactDocumentReference requires contentDataBase64 when resource is absent.');
+        }
+        contentCid = cidFromBytes(decodeBase64(contentDataBase64));
+        communicationLike = {
+            resourceType: 'Communication',
+            meta: { claims: { [CommunicationClaim.Subject]: subject } },
+            payload: [{ contentAttachment: { contentType, data: contentDataBase64, title, url: input.location } }],
+        };
+    }
+    const result = buildDocumentReferenceFromCommunicationPayload(communicationLike, { mode: 'strict' });
+    const logicalIdentifier = toStringOrUndefined(input.identifier) || contentCid;
+    const documentReference = {
+        ...result.documentReference,
+        identifier: logicalIdentifier ? [{ value: logicalIdentifier }] : undefined,
+        description: toStringOrUndefined(input.description) || result.documentReference.description,
+        date: toStringOrUndefined(input.date) || result.documentReference.date,
+        content: [{
+                attachment: {
+                    ...(result.documentReference.content?.[0]?.attachment || {}),
+                    contentType,
+                    data: contentDataBase64,
+                    url: toStringOrUndefined(input.location) || result.documentReference.content?.[0]?.attachment?.url,
+                    title,
+                    language: toStringOrUndefined(input.language) || result.documentReference.content?.[0]?.attachment?.language,
+                    hash: contentCid,
+                },
+            }],
+        meta: {
+            ...(result.documentReference.meta || {}),
+            versionId: contentCid,
+            claims: {
+                ...((result.documentReference.meta || {}).claims || {}),
+                [DocumentReferenceClaim.Identifier]: logicalIdentifier,
+                [DocumentReferenceClaim.ContentHash]: contentCid,
+                [DocumentReferenceClaim.ContentData]: contentDataBase64,
+                [DocumentReferenceClaim.ContentType]: contentType,
+                [DocumentReferenceClaim.Subject]: subject,
+                ...(toStringOrUndefined(input.description) ? { [DocumentReferenceClaim.Description]: input.description } : {}),
+                ...(toStringOrUndefined(input.date) ? { [DocumentReferenceClaim.Date]: input.date } : {}),
+                ...(toStringOrUndefined(input.location) ? { [DocumentReferenceClaim.Location]: input.location } : {}),
+                ...(toStringOrUndefined(input.language) ? { [DocumentReferenceClaim.Language]: input.language } : {}),
+            },
+        },
+    };
+    return {
+        ...result,
+        contentCid,
+        documentReference,
+    };
+}

package/dist/utils/communication-editor.d.ts

@@ -0,0 +1,53 @@
+import type { BundleEntry, BundleJsonApi } from '../models/bundle';
+import type { BundleResourceIdFilters } from './bundle-query';
+import { type CommunicationAttachedBundleSessionMode } from '../models/communication-attached-bundle-session';
+import { BundleReader } from './bundle-reader';
+import { CommunicationAttachedBundleSession } from './communication-attached-bundle-session';
+import type { IDecodedDidcommPayload } from '../models/confidential-message';
+export type CommunicationEditorOptions = Readonly<{
+    initialBundle?: BundleJsonApi<BundleEntry>;
+    mode?: CommunicationAttachedBundleSessionMode;
+    communicationClaims?: Record<string, unknown>;
+}>;
+/**
+ * Public high-level editor for one delivery `Communication`.
+ *
+ * Teaching contract:
+ * - use this name in tutorials when the caller is authoring one outer
+ *   `Communication`
+ * - keep `CommunicationAttachedBundleSession` as the lower-level compatibility
+ *   implementation detail underneath
+ */
+export declare class CommunicationEditor extends CommunicationAttachedBundleSession {
+    constructor(options?: CommunicationEditorOptions);
+    /** Materializes one immutable snapshot of the current Communication claims. */
+    done(): Record<string, unknown>;
+    /** Returns one reader over the current Communication snapshot. */
+    toReader(): CommunicationReader;
+}
+/**
+ * Public high-level reader for one delivery `Communication`.
+ */
+export declare class CommunicationReader {
+    private readonly session;
+    constructor(communicationClaims: Record<string, unknown>);
+    /** Reads the first delivery `Communication` carried in one DIDComm/plain payload. */
+    static fromDidcommPayload(payload: IDecodedDidcommPayload): CommunicationReader;
+    /** Reads every delivery `Communication` carried in one DIDComm/plain payload. */
+    static listFromDidcommPayload(payload: IDecodedDidcommPayload): CommunicationReader[];
+    getCommunicationClaims(): Record<string, unknown>;
+    getCommunicationIdentifier(): string;
+    getCommunicationSubject(): string;
+    getCommunicationCategoryList(): string[];
+    getCommunicationTopic(): string;
+    getCommunicationText(): string;
+    getAttachmentContentType(): string;
+    getAttachmentTitle(): string;
+    getAttachmentUrl(): string;
+    getAttachmentDataBase64(): string;
+    getAttachedBundle(): BundleJsonApi<BundleEntry>;
+    getAttachedBundleReader(): BundleReader;
+    getAttachedBundleResourceIds(filters?: BundleResourceIdFilters): string[];
+    getAttachedBundleEntriesByIds(resourceIds: readonly string[]): BundleEntry[];
+    getAttachedBundleEntryUrl(resourceId: string): string | undefined;
+}