gdc-common-utils-ts 2.1.0 → 2.3.0

package/dist/utils/authority-resolution.js

@@ -0,0 +1,112 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { buildOrganizationDidWeb, getBaseUrlFromDidWeb } from './did.js';
+function normalizeString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function encodeDidWebAuthority(authority) {
+    return authority.replace(/:/g, '%3A').toLowerCase();
+}
+function normalizeAuthorityHost(value) {
+    const raw = normalizeString(value).replace(/\/+$/, '');
+    if (!raw)
+        return '';
+    if (/^https?:\/\//i.test(raw)) {
+        try {
+            return new URL(raw).host;
+        }
+        catch {
+            return raw.replace(/^https?:\/\//i, '');
+        }
+    }
+    return raw;
+}
+function protocolForAuthority(authority) {
+    const normalized = authority.trim().toLowerCase();
+    return normalized.startsWith('localhost')
+        || normalized.startsWith('127.0.0.1')
+        || normalized.startsWith('[::1]')
+        ? 'http'
+        : 'https';
+}
+function inferMatchedBy(input) {
+    if (normalizeString(input.subjectDid))
+        return 'subject-did';
+    if (normalizeString(input.subjectSameAs))
+        return 'subject-same-as';
+    if (normalizeString(input.authorityDidWeb))
+        return 'authority-did';
+    if (normalizeString(input.authorityBaseUrl))
+        return 'authority-base-url';
+    return 'tenant-context';
+}
+/**
+ * Builds one authority/root `did:web` from a bare host authority or URL.
+ *
+ * Examples:
+ * - `https://gw.example.org` -> `did:web:gw.example.org`
+ * - `localhost:3300` -> `did:web:localhost%3A3300`
+ */
+export function buildAuthorityDidWeb(input) {
+    const authority = normalizeAuthorityHost(input.authority);
+    if (!authority)
+        throw new Error('buildAuthorityDidWeb requires authority.');
+    return `did:web:${encodeDidWebAuthority(authority)}`;
+}
+/**
+ * Normalizes one authority base URL from either an explicit URL or one
+ * authority/root `did:web`.
+ */
+export function resolveAuthorityBaseUrl(input) {
+    const direct = normalizeString(input.authorityBaseUrl);
+    if (direct) {
+        const host = normalizeAuthorityHost(direct);
+        return host ? `${protocolForAuthority(host)}://${host}/` : undefined;
+    }
+    const did = normalizeString(input.authorityDidWeb);
+    if (!did)
+        return undefined;
+    return getBaseUrlFromDidWeb(did);
+}
+/**
+ * Builds one compatibility authority resolution when the caller only knows:
+ * - tenant context
+ * - one base URL or one root authority `did:web`
+ *
+ * This helper intentionally keeps the current hosted-DID fallback in one place
+ * so app code does not have to hand-invent `did:web` strings.
+ */
+export function buildLegacyAuthorityResolution(input) {
+    const authorityDidWeb = normalizeString(input.authorityDidWeb)
+        || buildAuthorityDidWeb({ authority: normalizeString(input.authorityBaseUrl) });
+    const authorityBaseUrl = resolveAuthorityBaseUrl({
+        authorityBaseUrl: input.authorityBaseUrl,
+        authorityDidWeb,
+    });
+    const tenantDidWeb = buildOrganizationDidWeb({
+        hostDidWeb: authorityDidWeb,
+        tenantId: input.tenantId,
+        jurisdiction: input.jurisdiction,
+        version: normalizeString(input.version) || 'v1',
+        sector: input.sector,
+    });
+    return {
+        authorityDidWeb,
+        authorityBaseUrl,
+        tenantDidWeb,
+        metadataUrl: normalizeString(input.metadataUrl) || undefined,
+        source: 'legacy',
+        matchedBy: inferMatchedBy(input),
+    };
+}
+/**
+ * Converts one resolution into a catalog-style record so runtimes can preload
+ * legacy fallback data into a shared resolver cache.
+ */
+export function authorityResolutionToCatalogRecord(resolution) {
+    return {
+        authorityDidWeb: resolution.authorityDidWeb,
+        authorityBaseUrl: resolution.authorityBaseUrl,
+        tenantDidWeb: resolution.tenantDidWeb,
+        metadataUrl: resolution.metadataUrl,
+    };
+}

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

@@ -17,6 +17,17 @@ export type BackendMessageManagerMemOptions = Readonly<{
  *
  * This is the lowest reusable BFF/proxy slice before actor-specific SDK
  * facades appear.
+ *
+ * Normal deployment story:
+ * - the injected wallet is the unlocked wallet of the user profile runtime
+ * - that same profile wallet usually encrypts outbound messages and decrypts
+ *   replies
+ *
+ * Optional deployment story:
+ * - one BFF/proxy may also own a separate service wallet for its own
+ *   envelopes, signatures, confidential storage, or tenant-level messaging
+ * - that service wallet is a different actor and must not be confused with
+ *   the user-profile wallet handled here
  */
 export declare class BackendMessageManagerMem {
     private readonly wallet;

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

@@ -12,6 +12,17 @@ function clone(value) {
  *
  * This is the lowest reusable BFF/proxy slice before actor-specific SDK
  * facades appear.
+ *
+ * Normal deployment story:
+ * - the injected wallet is the unlocked wallet of the user profile runtime
+ * - that same profile wallet usually encrypts outbound messages and decrypts
+ *   replies
+ *
+ * Optional deployment story:
+ * - one BFF/proxy may also own a separate service wallet for its own
+ *   envelopes, signatures, confidential storage, or tenant-level messaging
+ * - that service wallet is a different actor and must not be confused with
+ *   the user-profile wallet handled here
  */
 export class BackendMessageManagerMem {
     wallet;

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

@@ -1,7 +1,8 @@
 // Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+import { DidcommMessageTypes } from '../constants/didcomm.js';
 export const BundleDidcommEntryTypes = Object.freeze({
-    Batch: 'Bundle-batch-request-v1.0',
-    Document: 'Bundle-document-request-v1.0',
+    Batch: DidcommMessageTypes.BundleBatchRequest,
+    Document: DidcommMessageTypes.BundleDocumentRequest,
 });
 function clone(value) {
     return JSON.parse(JSON.stringify(value));

package/dist/utils/bundle-document-builder.d.ts

@@ -4,6 +4,7 @@ export type BuildBundleDocumentFromClaimsInput = Readonly<{
     claimsList: readonly BundleDocumentClaims[];
     subjectDid?: string;
     compositionType?: string;
+    compositionClaims?: BundleDocumentClaims;
 }>;
 export type ValidateBundleDocumentResult = Readonly<{
     ok: boolean;
@@ -13,8 +14,43 @@ export type BundleDocumentResourceFilter = Readonly<{
     section?: string;
     resourceType?: string;
 }>;
+export type PrepareBundleDocumentForSubjectOptions = Readonly<{
+    context?: string;
+}>;
 export declare function getSimpleClaimAttributeName(key: string): string;
 export declare function extractFlatClaimValue(record: Record<string, any> | undefined, key: string): string;
+/**
+ * Validates and prepares an imported FHIR document for one authorized subject.
+ *
+ * The input is cloned. Every resource receives a deterministic flat
+ * `meta.claims` projection. Resources referenced by `Composition.section`
+ * receive the canonical section tokens in `Composition.section`, and patient
+ * subject references are rebound to the selected `did:web` subject. Existing
+ * claims are retained, except subject/patient values are forced to the
+ * selected subject so an imported local `Patient/{id}` cannot escape the
+ * controller-authorized index scope. The source object is never mutated.
+ *
+ * This is a conversion primitive only. It neither confirms that a mismatched
+ * Patient is the right person nor persists anything; confirmation belongs to
+ * the product UI and transport/authorization remain GW concerns.
+ */
+export declare function prepareBundleDocumentForSubject(bundle: Record<string, any>, subjectDid: string, options?: PrepareBundleDocumentForSubjectOptions): Record<string, any>;
+/**
+ * Returns the Patient Full Name addressed by the document Composition.
+ *
+ * Resolution prefers the Patient referenced by `Composition.subject`, then
+ * falls back to the first Patient for compatibility with incomplete imports.
+ * Name selection prefers `use=official`, then `usual`, then the first name;
+ * `HumanName.text` wins over assembling prefix/given/family/suffix.
+ */
+export declare function getBundleDocumentPatientFullName(bundle: Record<string, any>): string | undefined;
+/**
+ * Temporary Full Name comparison key: whitespace folding plus uppercase only.
+ * Diacritics and punctuation are intentionally preserved until the shared
+ * ICAO transliteration contract exists, so `JOSE` and `JOSÉ` do not compare as
+ * equal by accident.
+ */
+export declare function normalizeFullNameForComparison(value: unknown): string;
 export declare function detectClaimsResourceType(claims: BundleDocumentClaims): string | undefined;
 export declare function convertClaimsToFhirResource(claims: BundleDocumentClaims, version?: 'r4'): FhirResource;
 /**

package/dist/utils/bundle-document-builder.js

@@ -1,4 +1,10 @@
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { AllergyIntoleranceClaim } from '../models/interoperable-claims/allergy-intolerance-claims.js';
+import { CompositionClaim } from '../models/interoperable-claims/composition-claims.js';
+import { ConditionClaim } from '../models/interoperable-claims/condition-claims.js';
+import { DiagnosticReportClaim } from '../models/interoperable-claims/diagnostic-report-claims.js';
+import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
+import { ClaimConsent } from '../models/consent-rule.js';
 import { allergyIntoleranceFlatToFhirR4, appointmentFlatToFhirR4, carePlanFlatToFhirR4, clinicalImpressionFlatToFhirR4, compositionFlatToFhirR4, conditionFlatToFhirR4, convertFhirResourceToClaims, coverageFlatToFhirR4, deviceFlatToFhirR4, documentReferenceFlatToFhirR4, diagnosticReportFlatToFhirR4, encounterFlatToFhirR4, flagFlatToFhirR4, flatClaimsToFhirResource, immunizationFlatToFhirR4, locationFlatToFhirR4, medicationStatementFlatToFhirR4, observationFromFlatToFhirR4, organizationFlatToFhirR4, procedureFlatToFhirR4, relatedPersonFlatToFhirR4, } from './clinical-resource-converters.js';
 function asTrimmedString(value) {
     if (value === undefined || value === null)
@@ -93,6 +99,219 @@ function normalizeSectionCode(value) {
         return { code: system };
     return { system, code };
 }
+function toCanonicalSectionToken(system, code) {
+    const normalizedSystem = asTrimmedString(system);
+    const normalizedCode = asTrimmedString(code);
+    if (!normalizedCode)
+        return '';
+    if (!normalizedSystem)
+        return normalizedCode;
+    return `${normalizedSystem === 'http://loinc.org' ? 'LOINC' : normalizedSystem}|${normalizedCode}`;
+}
+function resourceReferenceAliases(entry) {
+    const resource = entry?.resource;
+    const resourceType = asTrimmedString(resource?.resourceType);
+    const resourceId = asTrimmedString(resource?.id);
+    const fullUrl = asTrimmedString(entry?.fullUrl);
+    return Array.from(new Set([
+        fullUrl,
+        resourceType && resourceId ? `${resourceType}/${resourceId}` : '',
+        resourceId,
+        fullUrl ? fullUrl.split('/').slice(-2).join('/') : '',
+    ].filter(Boolean)));
+}
+function sectionMembershipByReference(composition) {
+    const memberships = new Map();
+    const visit = (sections) => {
+        if (!Array.isArray(sections))
+            return;
+        for (const section of sections) {
+            const coding = Array.isArray(section?.code?.coding) ? section.code.coding[0] : undefined;
+            const token = toCanonicalSectionToken(coding?.system, coding?.code);
+            if (token && Array.isArray(section?.entry)) {
+                for (const item of section.entry) {
+                    const reference = asTrimmedString(item?.reference);
+                    if (!reference)
+                        continue;
+                    const aliases = [reference, reference.split('/').slice(-2).join('/'), reference.split('/').pop() || ''];
+                    for (const alias of aliases.filter(Boolean)) {
+                        memberships.set(alias, Array.from(new Set([...(memberships.get(alias) || []), token])));
+                    }
+                }
+            }
+            visit(section?.section);
+        }
+    };
+    visit(composition?.section);
+    return memberships;
+}
+function allCompositionSectionTokens(composition) {
+    const tokens = [];
+    const visit = (sections) => {
+        if (!Array.isArray(sections))
+            return;
+        for (const section of sections) {
+            const coding = Array.isArray(section?.code?.coding) ? section.code.coding[0] : undefined;
+            const token = toCanonicalSectionToken(coding?.system, coding?.code);
+            if (token)
+                tokens.push(token);
+            visit(section?.section);
+        }
+    };
+    visit(composition?.section);
+    return Array.from(new Set(tokens));
+}
+function replacePatientSubjectReference(resource, subjectDid) {
+    const resourceType = asTrimmedString(resource?.resourceType);
+    if (resourceType === ResourceTypesFhirR4.Composition || resource?.subject?.reference) {
+        resource.subject = { ...(resource.subject || {}), reference: subjectDid };
+    }
+    if (resource?.patient?.reference) {
+        resource.patient = { ...(resource.patient || {}), reference: subjectDid };
+    }
+}
+/**
+ * Validates and prepares an imported FHIR document for one authorized subject.
+ *
+ * The input is cloned. Every resource receives a deterministic flat
+ * `meta.claims` projection. Resources referenced by `Composition.section`
+ * receive the canonical section tokens in `Composition.section`, and patient
+ * subject references are rebound to the selected `did:web` subject. Existing
+ * claims are retained, except subject/patient values are forced to the
+ * selected subject so an imported local `Patient/{id}` cannot escape the
+ * controller-authorized index scope. The source object is never mutated.
+ *
+ * This is a conversion primitive only. It neither confirms that a mismatched
+ * Patient is the right person nor persists anything; confirmation belongs to
+ * the product UI and transport/authorization remain GW concerns.
+ */
+export function prepareBundleDocumentForSubject(bundle, subjectDid, options = {}) {
+    const validation = validateBundleDocumentBasic(bundle);
+    if (!validation.ok)
+        throw new Error(validation.issues.join(' '));
+    const normalizedSubjectDid = asTrimmedString(subjectDid);
+    if (!normalizedSubjectDid)
+        throw new Error('A subject DID is required.');
+    const prepared = JSON.parse(JSON.stringify(bundle));
+    const entries = prepared.entry;
+    const composition = entries[0]?.resource;
+    const membership = sectionMembershipByReference(composition);
+    const allSections = allCompositionSectionTokens(composition);
+    for (const entry of entries) {
+        const resource = entry?.resource;
+        if (!resource || typeof resource !== 'object')
+            continue;
+        replacePatientSubjectReference(resource, normalizedSubjectDid);
+        const generated = convertFhirResourceToClaims(resource, options.context || 'org.hl7.fhir.r4');
+        const existing = resource?.meta?.claims;
+        const claims = {
+            ...generated,
+            ...(existing && typeof existing === 'object' && !Array.isArray(existing) ? existing : {}),
+        };
+        const resourceType = asTrimmedString(resource.resourceType);
+        if (resourceType !== 'Patient') {
+            if (resource?.subject?.reference)
+                claims[`${resourceType}.subject`] = normalizedSubjectDid;
+            if (resource?.patient?.reference)
+                claims[`${resourceType}.patient`] = normalizedSubjectDid;
+        }
+        const resourceSections = resourceType === ResourceTypesFhirR4.Composition
+            ? allSections
+            : resourceReferenceAliases(entry).flatMap((alias) => membership.get(alias) || []);
+        if (resourceSections.length > 0) {
+            claims[CompositionClaim.Section] = Array.from(new Set(resourceSections)).join(',');
+        }
+        resource.meta = {
+            ...(resource.meta && typeof resource.meta === 'object' ? resource.meta : {}),
+            claims,
+        };
+    }
+    return prepared;
+}
+/**
+ * Returns the Patient Full Name addressed by the document Composition.
+ *
+ * Resolution prefers the Patient referenced by `Composition.subject`, then
+ * falls back to the first Patient for compatibility with incomplete imports.
+ * Name selection prefers `use=official`, then `usual`, then the first name;
+ * `HumanName.text` wins over assembling prefix/given/family/suffix.
+ */
+export function getBundleDocumentPatientFullName(bundle) {
+    const entries = Array.isArray(bundle?.entry) ? bundle.entry : [];
+    const composition = entries[0]?.resource;
+    const subjectReference = asTrimmedString(composition?.subject?.reference);
+    const patientEntry = entries.find((entry) => {
+        if (entry?.resource?.resourceType !== 'Patient')
+            return false;
+        if (!subjectReference)
+            return true;
+        return resourceReferenceAliases(entry).some((alias) => alias === subjectReference
+            || alias === subjectReference.split('/').slice(-2).join('/')
+            || alias === subjectReference.split('/').pop());
+    }) || entries.find((entry) => entry?.resource?.resourceType === 'Patient');
+    const names = Array.isArray(patientEntry?.resource?.name) ? patientEntry.resource.name : [];
+    const name = names.find((item) => item?.use === 'official')
+        || names.find((item) => item?.use === 'usual')
+        || names[0];
+    if (!name)
+        return undefined;
+    const text = asTrimmedString(name.text);
+    if (text)
+        return text;
+    const parts = [
+        ...(Array.isArray(name.prefix) ? name.prefix : []),
+        ...(Array.isArray(name.given) ? name.given : []),
+        name.family,
+        ...(Array.isArray(name.suffix) ? name.suffix : []),
+    ].map(asTrimmedString).filter(Boolean);
+    return parts.length > 0 ? parts.join(' ') : undefined;
+}
+/**
+ * Temporary Full Name comparison key: whitespace folding plus uppercase only.
+ * Diacritics and punctuation are intentionally preserved until the shared
+ * ICAO transliteration contract exists, so `JOSE` and `JOSÉ` do not compare as
+ * equal by accident.
+ */
+export function normalizeFullNameForComparison(value) {
+    return asTrimmedString(value).replace(/\s+/g, ' ').toUpperCase();
+}
+function resolveContainedReferenceListClaimKey(resourceType) {
+    switch (resourceType) {
+        case ResourceTypesFhirR4.MedicationStatement:
+            return MedicationStatementClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.AllergyIntolerance:
+            return AllergyIntoleranceClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.Condition:
+            return ConditionClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.DiagnosticReport:
+            return DiagnosticReportClaim.ContainedReferenceList;
+        case ResourceTypesFhirR4.Consent:
+            return ClaimConsent.containedReferenceList;
+        default:
+            return undefined;
+    }
+}
+function resolveContainedFlagClaimKey(resourceType) {
+    const normalized = asTrimmedString(resourceType);
+    return normalized ? `${normalized}.is-contained` : undefined;
+}
+function resolveContainedParentReferenceClaimKey(resourceType) {
+    const normalized = asTrimmedString(resourceType);
+    return normalized ? `${normalized}.contained-parent-reference` : undefined;
+}
+function mergeContainedResourceReferenceList(claims, references) {
+    const resourceType = detectClaimsResourceType(claims);
+    const claimKey = resourceType ? resolveContainedReferenceListClaimKey(resourceType) : undefined;
+    if (!claimKey || references.length === 0) {
+        return claims;
+    }
+    const current = splitCsv(claims[claimKey]);
+    const next = Array.from(new Set([...current, ...references].map((item) => asTrimmedString(item)).filter(Boolean)));
+    return {
+        ...claims,
+        [claimKey]: next.join(','),
+    };
+}
 export function detectClaimsResourceType(claims) {
     const keys = Object.keys(claims || {});
     if (keys.some((key) => key.startsWith('MedicationStatement.')))
@@ -181,12 +400,47 @@ export function extractBundleDocumentClaimsList(bundle, context = 'org.hl7.fhir.
         .map((entry) => entry?.resource)
         .filter((resource) => resource && typeof resource === 'object')
         .filter((resource) => !ignoredResourceTypes.has(String(resource.resourceType || '')))
-        .map((resource) => {
-        const metaClaims = resource?.meta?.claims;
-        if (metaClaims && typeof metaClaims === 'object' && !Array.isArray(metaClaims)) {
-            return ensureClaimsIdentifier({ ...metaClaims }, resource);
-        }
-        return ensureClaimsIdentifier(convertFhirResourceToClaims(resource, context), resource);
+        .flatMap((resource) => {
+        const resourceRecord = resource;
+        const resourceReference = `${asTrimmedString(resourceRecord.resourceType)}/${asTrimmedString(resourceRecord.id)}`;
+        const metaClaims = resourceRecord?.meta?.claims;
+        const baseClaims = metaClaims && typeof metaClaims === 'object' && !Array.isArray(metaClaims)
+            ? ensureClaimsIdentifier({ ...metaClaims }, resourceRecord)
+            : ensureClaimsIdentifier(convertFhirResourceToClaims(resourceRecord, context), resourceRecord);
+        const containedResources = Array.isArray(resourceRecord.contained)
+            ? resourceRecord.contained
+            : [];
+        const containedClaimsList = containedResources.map((containedResource, index) => {
+            const containedMetaClaims = (containedResource?.meta?.claims);
+            const containedClaims = containedMetaClaims && typeof containedMetaClaims === 'object' && !Array.isArray(containedMetaClaims)
+                ? ensureClaimsIdentifier({ ...containedMetaClaims }, containedResource)
+                : ensureClaimsIdentifier(convertFhirResourceToClaims(containedResource, context), containedResource);
+            const containedResourceType = asTrimmedString(containedResource.resourceType);
+            const containedFlagClaimKey = resolveContainedFlagClaimKey(containedResourceType);
+            const containedParentReferenceClaimKey = resolveContainedParentReferenceClaimKey(containedResourceType);
+            return {
+                ...containedClaims,
+                ...(containedFlagClaimKey ? { [containedFlagClaimKey]: true } : {}),
+                ...(containedParentReferenceClaimKey ? { [containedParentReferenceClaimKey]: resourceReference } : {}),
+                ...(asTrimmedString(containedResource.id) ? {} : {
+                    [`${containedResource.resourceType}.identifier`]: `${resourceReference}#contained-${index + 1}`,
+                }),
+            };
+        });
+        const containedReferences = containedResources
+            .map((containedResource, index) => {
+            const containedType = asTrimmedString(containedResource.resourceType);
+            const containedId = asTrimmedString(containedResource.id) || `${resourceReference}#contained-${index + 1}`;
+            if (!containedType || !containedId) {
+                return '';
+            }
+            return `${containedType}/${containedId}`;
+        })
+            .filter(Boolean);
+        return [
+            mergeContainedResourceReferenceList(baseClaims, containedReferences),
+            ...containedClaimsList,
+        ];
     });
 }
 export function resolveClaimsSectionList(claims) {
@@ -202,9 +456,17 @@ export function resolveClaimsSectionList(claims) {
     return Array.from(new Set(values));
 }
 export function buildBundleDocumentFromClaims(input) {
-    const compositionType = asTrimmedString(input.compositionType) || 'http://loinc.org|60591-5';
+    const compositionClaims = { ...(input.compositionClaims || {}) };
+    const compositionType = asTrimmedString(input.compositionType || compositionClaims[CompositionClaim.Type]) || 'http://loinc.org|60591-5';
+    const compositionSubject = asTrimmedString(input.subjectDid || compositionClaims[CompositionClaim.Subject]);
+    const compositionIdentifier = asTrimmedString(compositionClaims[CompositionClaim.Identifier]);
+    const compositionTitle = asTrimmedString(compositionClaims[CompositionClaim.Title]);
+    const compositionDate = asTrimmedString(compositionClaims[CompositionClaim.Date]);
+    const compositionAuthorList = splitCsv(compositionClaims[CompositionClaim.Author]);
     const compositionSections = new Map();
-    const entries = [];
+    const visibleEntries = [];
+    const resourceByReference = new Map();
+    const containedChildrenByParentReference = new Map();
     input.claimsList.forEach((claims, index) => {
         const resource = convertClaimsToFhirResource(claims);
         resource.meta = {
@@ -212,8 +474,23 @@ export function buildBundleDocumentFromClaims(input) {
             claims: { ...claims },
         };
         ensureResourceIdentifier(resource, claims, index);
-        entries.push({ resource });
-        const resourceRef = `${resource.resourceType}/${resource.id}`;
+        const resourceReference = `${resource.resourceType}/${asTrimmedString(resource.id)}`;
+        const containedFlagClaimKey = resolveContainedFlagClaimKey(resource.resourceType);
+        const containedParentReferenceClaimKey = resolveContainedParentReferenceClaimKey(resource.resourceType);
+        const isContained = containedFlagClaimKey
+            ? (claims[containedFlagClaimKey] === true || claims[containedFlagClaimKey] === 'true')
+            : false;
+        const containedParentReference = containedParentReferenceClaimKey
+            ? asTrimmedString(claims[containedParentReferenceClaimKey])
+            : '';
+        if (isContained && containedParentReference) {
+            const currentChildren = containedChildrenByParentReference.get(containedParentReference) || [];
+            containedChildrenByParentReference.set(containedParentReference, [...currentChildren, resource]);
+            return;
+        }
+        visibleEntries.push({ resource });
+        resourceByReference.set(resourceReference, resource);
+        const resourceRef = resourceReference;
         resolveClaimsSectionList(claims).forEach((sectionValue) => {
             const normalizedSection = asTrimmedString(sectionValue);
             if (!normalizedSection)
@@ -230,6 +507,13 @@ export function buildBundleDocumentFromClaims(input) {
             compositionSections.set(normalizedSection, section);
         });
     });
+    containedChildrenByParentReference.forEach((children, parentReference) => {
+        const parent = resourceByReference.get(parentReference);
+        if (!parent) {
+            return;
+        }
+        parent.contained = [...(Array.isArray(parent.contained) ? parent.contained : []), ...children];
+    });
     const [compositionSystem, compositionCode] = compositionType.split('|');
     return {
         resourceType: ResourceTypesFhirR4.Bundle,
@@ -238,8 +522,14 @@ export function buildBundleDocumentFromClaims(input) {
             {
                 resource: {
                     resourceType: ResourceTypesFhirR4.Composition,
+                    ...(compositionIdentifier ? { id: compositionIdentifier } : {}),
                     status: 'final',
-                    subject: input.subjectDid ? { reference: input.subjectDid } : undefined,
+                    ...(compositionIdentifier ? {
+                        identifier: [{ value: compositionIdentifier }],
+                    } : {}),
+                    ...(compositionSubject ? {
+                        subject: { reference: compositionSubject },
+                    } : {}),
                     type: {
                         coding: [
                             compositionCode
@@ -247,18 +537,24 @@ export function buildBundleDocumentFromClaims(input) {
                                 : { code: compositionSystem },
                         ],
                     },
+                    ...(compositionTitle ? { title: compositionTitle } : {}),
+                    ...(compositionDate ? { date: compositionDate } : {}),
+                    ...(compositionAuthorList.length > 0 ? {
+                        author: compositionAuthorList.map((reference) => ({ reference })),
+                    } : {}),
+                    meta: { claims: compositionClaims },
                     section: Array.from(compositionSections.values()),
                 },
             },
-            ...(input.subjectDid
+            ...(compositionSubject
                 ? [{
                         resource: {
                             resourceType: 'Patient',
-                            id: input.subjectDid,
+                            id: compositionSubject,
                         },
                     }]
                 : []),
-            ...entries,
+            ...visibleEntries,
         ],
     };
 }