gdc-common-utils-ts 2.3.4 → 2.3.6

package/dist/constants/actor-session.d.ts

@@ -38,6 +38,7 @@ export declare const ActorCapabilities: Readonly<{
     readonly IndividualImportIps: "individual.import_ips";
     readonly IndividualGenerateDigitalTwin: "individual.generate_digital_twin";
     readonly IndividualIngestCommunication: "individual.ingest_communication";
+    readonly IndividualReadClinicalSummary: "individual.read_clinical_summary";
     readonly IndividualUpsertRelatedPerson: "individual.upsert_related_person";
     readonly IndividualMemberDisable: "individual_member.disable";
     readonly IndividualMemberPurge: "individual_member.purge";

package/dist/constants/actor-session.js

@@ -40,6 +40,7 @@ export const ActorCapabilities = Object.freeze({
     IndividualImportIps: 'individual.import_ips',
     IndividualGenerateDigitalTwin: 'individual.generate_digital_twin',
     IndividualIngestCommunication: 'individual.ingest_communication',
+    IndividualReadClinicalSummary: 'individual.read_clinical_summary',
     IndividualUpsertRelatedPerson: 'individual.upsert_related_person',
     IndividualMemberDisable: 'individual_member.disable',
     IndividualMemberPurge: 'individual_member.purge',
@@ -161,6 +162,12 @@ export const ActorCapabilityDocs = Object.freeze({
         programmingHint: 'Choose the route family carefully (`api`, `didcomm-plain`, `legacy-fhir`) to match the runtime transport profile.',
         relatedMethods: ['ingestCommunicationAndUpdateIndex'],
     },
+    [ActorCapabilities.IndividualReadClinicalSummary]: {
+        actorKind: ActorKinds.IndividualController,
+        summary: 'Reads the clinical summary currently available for one subject through an auditable Communication.',
+        programmingHint: 'Use requestClinicalSummary with Subject/$summary and attached FHIR Parameters. Do not route reads through ingestion methods.',
+        relatedMethods: ['requestClinicalSummary'],
+    },
     [ActorCapabilities.IndividualUpsertRelatedPerson]: {
         actorKind: ActorKinds.IndividualController,
         summary: 'Creates or updates one related-person/member relationship for the individual scope.',

package/dist/utils/bundle-entry-editor.js

@@ -234,7 +234,7 @@ export class BundleEntryEditor {
             resourceType: this.bundleEditor.getAllowedResourceType() || EmployeeResourceTypes.employee,
             meta: { claims: {} },
         };
-        entry.resource.meta = entry.resource.meta || {};
+        entry.resource.meta = entry.resource.meta || { claims: {} };
         entry.resource.meta.claims = {
             ...(entry.resource.meta.claims || {}),
             [String(key).trim()]: cloneClaimValue(value),
@@ -264,7 +264,7 @@ export class BundleEntryEditor {
             resourceType: this.bundleEditor.getAllowedResourceType() || EmployeeResourceTypes.employee,
             meta: { claims: {} },
         };
-        entry.resource.meta = entry.resource.meta || {};
+        entry.resource.meta = entry.resource.meta || { claims: {} };
         entry.resource.meta.claims = claims;
         return this;
     }

package/dist/utils/bundle-query.d.ts

@@ -1,8 +1,25 @@
 import type { BundleEntry, BundleJsonApi } from '../models/bundle.js';
+/** Canonical date interval shared by clinical Bundle read filters. */
+export type BundleResourceDateFilter = Readonly<{
+    start?: string;
+    end?: string;
+}>;
+/**
+ * Filters Bundle resources by section, resource type and clinical date.
+ *
+ * Use `types` and `date` in new code. The flat names remain temporary
+ * compatibility aliases for callers created before the document readers were
+ * aligned with `FhirDocumentFacade`.
+ */
 export type BundleResourceIdFilters = Readonly<{
     sections?: string | readonly string[];
+    types?: string | readonly string[];
+    date?: BundleResourceDateFilter;
+    /** @deprecated Use `types`. */
     resourceTypes?: string | readonly string[];
+    /** @deprecated Use `date.start`. */
     dateFrom?: string;
+    /** @deprecated Use `date.end`. */
     dateTo?: string;
 }>;
 /**

package/dist/utils/bundle-query.js

@@ -82,7 +82,7 @@ export class BundleQuery {
     }
     matchesResourceFilters(entry, filters) {
         const resourceType = asTrimmedString(entry?.resource?.resourceType);
-        const resourceTypeFilters = normalizeTokenInput(filters.resourceTypes);
+        const resourceTypeFilters = normalizeTokenInput(filters.types !== undefined ? filters.types : filters.resourceTypes);
         if (resourceTypeFilters.length > 0 && !resourceTypeFilters.includes(resourceType)) {
             return false;
         }
@@ -92,7 +92,9 @@ export class BundleQuery {
             return false;
         }
         const entryDate = this.resolveEntryDate(claims);
-        if (!this.matchesDateRange(entryDate, filters.dateFrom, filters.dateTo)) {
+        const dateFrom = filters.date !== undefined ? filters.date.start : filters.dateFrom;
+        const dateTo = filters.date !== undefined ? filters.date.end : filters.dateTo;
+        if (!this.matchesDateRange(entryDate, dateFrom, dateTo)) {
             return false;
         }
         return true;
@@ -116,6 +118,11 @@ export class BundleQuery {
             const normalized = String(key || '').toLowerCase();
             if (normalized.endsWith('.date')
                 || normalized.endsWith('.effective')
+                || normalized.endsWith('.effective-datetime')
+                || normalized.endsWith('.effective-period-start')
+                || normalized.endsWith('.onset-datetime')
+                || normalized.endsWith('.occurrence-datetime')
+                || normalized.endsWith('.recorded-date')
                 || normalized.endsWith('.sent')
                 || normalized.endsWith('.authored-on')) {
                 const dateValue = asTrimmedString(value);

package/dist/utils/bundle-reader.d.ts

@@ -114,6 +114,21 @@ export declare class BundleReader {
     getDocumentSectionResourceCount(sectionCodeOrClaim: string): number;
     /** Returns bundle resource references listed under one document section. */
     getDocumentSectionResourceReferences(sectionCodeOrClaim: string): string[];
+    /**
+     * Returns stable resource IDs that both belong to one Composition section
+     * and match the optional resource-type/date filters.
+     *
+     * Use this after `$summary` when a screen or channel needs the concrete
+     * resources for one section. `getDocumentSectionResourceCount(...)` counts
+     * declared Composition references; this method resolves those references
+     * against the returned Bundle and can narrow the result.
+     */
+    getDocumentSectionResourceIds(sectionCodeOrClaim: string, filters?: BundleResourceIdFilters): string[];
+    /**
+     * Returns cloned Bundle entries for the resources selected from one
+     * Composition section, optionally filtered by type and inclusive date range.
+     */
+    getDocumentSectionResourceEntries(sectionCodeOrClaim: string, filters?: BundleResourceIdFilters): BundleReaderEntry[];
     /** Returns the active entry response status when present. */
     getEntryResponseStatus(): string | undefined;
     /** Returns all active entry issue severities. */
@@ -150,6 +165,7 @@ export declare class BundleReader {
     private buildEntrySummary;
     private buildSeverityBucket;
     private resolveEntryIdentifier;
+    private resolveEntryReferenceCandidates;
 }
 export declare function unwrapBundleLikeResponseBody(input: unknown): Record<string, unknown>;
 export declare function readFirstBundleResourceFromResponseBody(input: unknown): Record<string, unknown> | undefined;

package/dist/utils/bundle-reader.js

@@ -136,7 +136,13 @@ export class BundleReader {
         }
         const entries = this.getEntries();
         for (let index = 0; index < entries.length; index += 1) {
-            if (this.resolveEntryIdentifier(entries[index]) === normalizedIdentifier) {
+            const resource = asRecord(entries[index].resource);
+            const resourceType = asNonEmptyString(resource.resourceType) || 'resource';
+            const candidates = new Set([
+                ...this.resolveEntryReferenceCandidates(entries[index]),
+                `${resourceType}#${index}`,
+            ]);
+            if (candidates.has(normalizedIdentifier)) {
                 return index;
             }
         }
@@ -235,7 +241,9 @@ export class BundleReader {
         if (!normalized) {
             return undefined;
         }
-        return this.getDocumentSections().find((section) => section.claim === normalized || section.code === normalized);
+        const normalizedClaim = normalizeSectionClaim(normalized);
+        return this.getDocumentSections().find((section) => section.code === normalized
+            || (section.claim !== undefined && normalizeSectionClaim(section.claim) === normalizedClaim));
     }
     /** Returns the number of resource references inside one document section. */
     getDocumentSectionResourceCount(sectionCodeOrClaim) {
@@ -245,6 +253,30 @@ export class BundleReader {
     getDocumentSectionResourceReferences(sectionCodeOrClaim) {
         return [...(this.getDocumentSectionByCode(sectionCodeOrClaim)?.entryReferences || [])];
     }
+    /**
+     * Returns stable resource IDs that both belong to one Composition section
+     * and match the optional resource-type/date filters.
+     *
+     * Use this after `$summary` when a screen or channel needs the concrete
+     * resources for one section. `getDocumentSectionResourceCount(...)` counts
+     * declared Composition references; this method resolves those references
+     * against the returned Bundle and can narrow the result.
+     */
+    getDocumentSectionResourceIds(sectionCodeOrClaim, filters = {}) {
+        const references = new Set(this.getDocumentSectionResourceReferences(sectionCodeOrClaim));
+        if (references.size === 0) {
+            return [];
+        }
+        return this.getResourceIds(filters).filter((resourceId) => this.getEntriesByIds([resourceId]).some((entry) => this.resolveEntryReferenceCandidates(entry)
+            .some((reference) => references.has(reference))));
+    }
+    /**
+     * Returns cloned Bundle entries for the resources selected from one
+     * Composition section, optionally filtered by type and inclusive date range.
+     */
+    getDocumentSectionResourceEntries(sectionCodeOrClaim, filters = {}) {
+        return this.getEntriesByIds(this.getDocumentSectionResourceIds(sectionCodeOrClaim, filters));
+    }
     /** Returns the active entry response status when present. */
     getEntryResponseStatus() {
         const entry = this.getRequiredActiveEntry();
@@ -434,10 +466,32 @@ export class BundleReader {
             .find((key) => String(key || '').toLowerCase().endsWith('.identifier'));
         return identifierKey ? normalizeOptionalString(claims[identifierKey]) : undefined;
     }
+    resolveEntryReferenceCandidates(entry) {
+        const resource = asRecord(entry.resource);
+        const resourceType = asNonEmptyString(resource.resourceType);
+        const resourceId = asNonEmptyString(resource.id);
+        return Array.from(new Set([
+            asNonEmptyString(entry.id),
+            asNonEmptyString(entry.fullUrl),
+            resourceId,
+            resourceType && resourceId ? `${resourceType}/${resourceId}` : undefined,
+            this.resolveEntryIdentifier(entry),
+        ].filter((value) => Boolean(value))));
+    }
 }
 function normalizeOptionalString(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
+function normalizeSectionClaim(value) {
+    const [system, ...codeParts] = value.split('|');
+    if (codeParts.length === 0) {
+        return value.trim().toLowerCase();
+    }
+    const normalizedSystem = system.trim().toLowerCase() === 'http://loinc.org'
+        ? 'loinc'
+        : system.trim().toLowerCase();
+    return `${normalizedSystem}|${codeParts.join('|').trim().toLowerCase()}`;
+}
 export function unwrapBundleLikeResponseBody(input) {
     const body = input && typeof input === 'object' ? input : {};
     const nested = body.body && typeof body.body === 'object' ? body.body : undefined;

package/dist/utils/client-assertion.d.ts

@@ -1,4 +1,4 @@
-import { type JsonWebKey } from 'node:crypto';
+import { type JWK } from 'jose';
 export type ClientAssertionJwtAlgorithm = 'ES256' | 'ES384' | 'ES512' | 'EdDSA';
 export type BuildClientAssertionJwtInput = {
     clientId: string;
@@ -34,5 +34,5 @@ export declare function buildClientAssertionJwt(input: BuildClientAssertionJwtIn
  */
 export declare function buildClientAssertionFixture(input: BuildClientAssertionJwtInput): Promise<{
     jwt: string;
-    publicJwk: JsonWebKey;
+    publicJwk: JWK;
 }>;

package/dist/utils/communication-bundle-document-request.d.ts

@@ -150,9 +150,10 @@ export declare function buildBundleSearchReferenceUrl(input: Readonly<{
 /**
  * Creates the canonical semantic parameters for an IPS summary-style request.
  *
- * These parameters are the source of truth. Current search flows flatten them
- * to `Communication.content-reference`, while future operation flows may attach
- * them directly as FHIR `Parameters`.
+ * These parameters are the source of truth. The canonical `$summary` read
+ * attaches them as one FHIR `Parameters` resource to an auditable
+ * `Communication`. Flattening them into a `Bundle/_search` reference is a
+ * compatibility path and must not be taught as the primary 101 read flow.
  */
 export declare function createSummaryOperationRequestParameters(subjectIdOrInput: string | CreateSummaryOperationParametersInput, filterSections?: string[]): ReadonlyArray<ParameterData>;
 /**
@@ -161,8 +162,8 @@ export declare function createSummaryOperationRequestParameters(subjectIdOrInput
  */
 export declare function createSummaryOperationRequestReferencePath(parameters: ReadonlyArray<ParameterData>): string;
 /**
- * Builds the preferred FHIR `Parameters` body for the same semantic summary
- * search represented by `createSummaryOperationRequestReferencePath(...)`.
+ * Builds the canonical FHIR `Parameters` body attached to a `$summary`
+ * request `Communication`.
  */
 export declare function createSummaryOperationRequestParametersResource(parameters: ReadonlyArray<ParameterData>): FhirParametersResource;
 export declare function buildCommunicationRequestOperationWithAttachedParametersClaims(input: CreateSummaryOperationCommunicationInput): Record<string, unknown>;
@@ -188,11 +189,11 @@ export declare const flattenParametersToSearchReference: typeof createSummaryOpe
  * carried inside `Communication`.
  *
  * Current split:
- * - `newSearchWithReferencePath(...)` keeps the existing `content-reference`
- *   search-url contract
- * - `setRequestSummaryOperation(...)` builds the operation contract where
+ * - `setRequestSummaryOperation(...)` is the canonical 101 read contract where
  *   `content-reference` points to the operation path and
  *   `content-attachment-data` carries the serialized FHIR `Parameters`
+ * - `newSearchWithReferencePath(...)` keeps the older flattened `_search`
+ *   compatibility contract
  */
 export declare const communication: Readonly<{
     /**

package/dist/utils/communication-bundle-document-request.js

@@ -217,9 +217,10 @@ export function buildBundleSearchReferenceUrl(input) {
 /**
  * Creates the canonical semantic parameters for an IPS summary-style request.
  *
- * These parameters are the source of truth. Current search flows flatten them
- * to `Communication.content-reference`, while future operation flows may attach
- * them directly as FHIR `Parameters`.
+ * These parameters are the source of truth. The canonical `$summary` read
+ * attaches them as one FHIR `Parameters` resource to an auditable
+ * `Communication`. Flattening them into a `Bundle/_search` reference is a
+ * compatibility path and must not be taught as the primary 101 read flow.
  */
 export function createSummaryOperationRequestParameters(subjectIdOrInput, filterSections) {
     const input = typeof subjectIdOrInput === 'string'
@@ -234,10 +235,14 @@ export function createSummaryOperationRequestParameters(subjectIdOrInput, filter
     if (!documentTypeDescriptor) {
         throw new Error(`Unsupported documentType: ${String(documentType)}`);
     }
+    const sections = normalizeStringArray(input.filterSections);
+    if (sections.includes('*')) {
+        throw new Error('Omit filterSections to request all available sections; "*" is reserved for SMART permission scopes.');
+    }
     return [
         buildSubjectParameter(subjectDid),
         buildDocumentTypeParameter(documentTypeDescriptor.id, documentTypeDescriptor.attributeValue),
-        ...buildSectionParameters(input.filterSections),
+        ...buildSectionParameters(sections),
     ];
 }
 /**
@@ -267,8 +272,8 @@ export function createSummaryOperationRequestReferencePath(parameters) {
     return `individual/org.hl7.fhir.r4/Bundle/_search?${params.filter(Boolean).join('&')}`;
 }
 /**
- * Builds the preferred FHIR `Parameters` body for the same semantic summary
- * search represented by `createSummaryOperationRequestReferencePath(...)`.
+ * Builds the canonical FHIR `Parameters` body attached to a `$summary`
+ * request `Communication`.
  */
 export function createSummaryOperationRequestParametersResource(parameters) {
     return buildFhirParametersResourceFromParameterData(parameters);
@@ -348,11 +353,11 @@ export const flattenParametersToSearchReference = createSummaryOperationRequestR
  * carried inside `Communication`.
  *
  * Current split:
- * - `newSearchWithReferencePath(...)` keeps the existing `content-reference`
- *   search-url contract
- * - `setRequestSummaryOperation(...)` builds the operation contract where
+ * - `setRequestSummaryOperation(...)` is the canonical 101 read contract where
  *   `content-reference` points to the operation path and
  *   `content-attachment-data` carries the serialized FHIR `Parameters`
+ * - `newSearchWithReferencePath(...)` keeps the older flattened `_search`
+ *   compatibility contract
  */
 export const communication = Object.freeze({
     /**

package/dist/utils/communication-fhir-r4.js

@@ -35,7 +35,8 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
         const hasReference = Boolean(payloadReference);
         const hasCode = Boolean(payloadCodeRaw);
         const payloadKinds = [hasAttachment, hasReference, hasCode].filter(Boolean).length;
-        if (payloadKinds > 1) {
+        const isOperationReferenceWithParameters = hasAttachment && hasReference && !hasCode;
+        if (payloadKinds > 1 && !isOperationReferenceWithParameters) {
             const msg = `Communication[${index}] has more than one payload kind (attachment/reference/code).`;
             if (mode === 'strict')
                 throw new Error(msg);
@@ -50,10 +51,10 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
                 throw new Error(msg);
             warnings.push(`${msg} Keeping first note only.`);
         }
-        const payload = buildPayload({
+        const payload = buildPayloads({
             hasAttachment,
-            hasReference,
-            hasCode,
+            hasReference: isOperationReferenceWithParameters || (!hasAttachment && hasReference),
+            hasCode: !hasAttachment && !hasReference && hasCode,
             payloadAttachmentData,
             payloadAttachmentType,
             payloadAttachmentTitle,
@@ -95,8 +96,8 @@ export function transformCommunicationClaimsToResourceFhirR4(communicationClaims
             resource['sender'] = { reference: sender };
         if (partOf)
             resource['partOf'] = [{ reference: partOf }];
-        if (payload)
-            resource['payload'] = [payload];
+        if (payload.length)
+            resource['payload'] = payload;
         if (noteValues.length)
             resource['note'] = [{ text: noteValues[0] }];
         return resource;
@@ -126,10 +127,13 @@ export function extractCommunicationClaimsFromResourceFhirR4(resource, options =
     const partOfRef = resource?.partOf?.[0]?.reference;
     const noteText = resource?.note?.[0]?.text;
     const categoryCoding = resource?.category?.[0]?.coding?.[0];
-    const payload = resource?.payload?.[0];
-    const contentReference = payload?.contentReference?.reference;
-    const contentAttachment = payload?.contentAttachment;
-    const contentCodeableConcept = payload?.contentCodeableConcept?.coding?.[0];
+    const payloads = resource?.payload || [];
+    const referencePayload = payloads.find((payload) => payload.contentReference !== undefined);
+    const attachmentPayload = payloads.find((payload) => payload.contentAttachment !== undefined);
+    const codePayload = payloads.find((payload) => payload.contentCodeableConcept !== undefined);
+    const contentReference = referencePayload?.contentReference?.reference;
+    const contentAttachment = attachmentPayload?.contentAttachment;
+    const contentCodeableConcept = codePayload?.contentCodeableConcept?.coding?.[0];
     setIf(claims, CommunicationClaim.Identifier, identifierValue);
     setIf(claims, CommunicationClaim.Status, status);
     setIf(claims, CommunicationClaim.Sent, sent);
@@ -177,8 +181,12 @@ function normalizeNoteValues(raw) {
     }
     return [];
 }
-function buildPayload(input) {
+function buildPayloads(input) {
     const { hasAttachment, hasReference, hasCode, payloadAttachmentData, payloadAttachmentType, payloadAttachmentTitle, payloadAttachmentUrl, payloadReference, payloadCodeRaw, } = input;
+    const payloads = [];
+    if (hasReference) {
+        payloads.push({ contentReference: { reference: payloadReference } });
+    }
     if (hasAttachment) {
         const value = {};
         if (payloadAttachmentData)
@@ -189,13 +197,12 @@ function buildPayload(input) {
             value['title'] = payloadAttachmentTitle;
         if (payloadAttachmentUrl)
             value['url'] = payloadAttachmentUrl;
-        return { contentAttachment: value };
+        payloads.push({ contentAttachment: value });
+    }
+    if (hasCode && payloadCodeRaw) {
+        payloads.push({ contentCodeableConcept: { coding: [parseSystemCode(payloadCodeRaw)] } });
     }
-    if (hasReference)
-        return { contentReference: { reference: payloadReference } };
-    if (hasCode && payloadCodeRaw)
-        return { contentCodeableConcept: { coding: [parseSystemCode(payloadCodeRaw)] } };
-    return undefined;
+    return payloads;
 }
 function parseSystemCode(value) {
     const trimmed = String(value || '').trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.3.4",
+  "version": "2.3.6",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,10 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "build": "tsc -p tsconfig.build.json && node patch-esm-imports.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node patch-esm-imports.mjs",
+    "verify:dist": "node scripts/verify-dist-syntax.mjs",
+    "prepack": "npm run verify:dist",
     "prepublishOnly": "npm run typecheck && npm test -- --watchman=false && npm run build"
   },
   "main": "./dist/index.js",