gdc-common-utils-ts 2.3.4 → 2.3.5

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/examples/professional.js

@@ -210,115 +210,4 @@ function buildConsentDecisionScenario(params) {
  * consent state + actor target + role + purpose + requested scope.
  */
 export const EXAMPLE_PROFESSIONAL_CONSENT_SCENARIOS = Object.freeze({
-    physicianByEmailContinuousCareAllergiesAllowed: buildConsentDecisionScenario({
-        actorId: EXAMPLE_PHYSICIAN_EMAIL,
-        actorRole: HealthcareActorRoles.Physician,
-        purpose: HealthcareConsentPurposes.Treatment,
-        consentActions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
-        requestedSections: HealthcareBasicSections.AllergiesAndIntolerances.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.AllergyIntolerance,
-            ResourceTypesFhirR4.DocumentReference,
-        ],
-        expectedSmartTokenDecision: 'allowed',
-        reason: 'physician is targeted directly by email and role for continuous care over allergies section',
-    }),
-    physicianByEmailEmergencySummaryAllowed: buildConsentDecisionScenario({
-        actorId: EXAMPLE_PHYSICIAN_EMAIL,
-        actorRole: HealthcareActorRoles.Physician,
-        purpose: HealthcareConsentPurposes.EmergencyTreatment,
-        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
-        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.DocumentReference,
-            ResourceTypesFhirR4.Observation,
-        ],
-        expectedSmartTokenDecision: 'allowed',
-        reason: 'physician is targeted directly by email and role for emergency summary access',
-    }),
-    physicianByOrganizationResultsAllowed: buildConsentDecisionScenario({
-        actorId: { organizationUrl: EXAMPLE_PROVIDER_ORG_URL },
-        actorRole: HealthcareActorRoles.Physician,
-        purpose: HealthcareConsentPurposes.Treatment,
-        consentActions: [HealthcareBasicSections.Results.claim],
-        requestedSections: HealthcareBasicSections.Results.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.DiagnosticReport,
-            ResourceTypesFhirR4.DocumentReference,
-        ],
-        expectedSmartTokenDecision: 'allowed',
-        reason: 'consent is granted to a physician role within a given organization for continuous care results access',
-    }),
-    physicianByJurisdictionEmergencySummaryAllowed: buildConsentDecisionScenario({
-        actorId: EXAMPLE_JURISDICTION,
-        actorRole: HealthcareActorRoles.Physician,
-        purpose: HealthcareConsentPurposes.EmergencyTreatment,
-        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
-        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.DocumentReference,
-            ResourceTypesFhirR4.Observation,
-        ],
-        expectedSmartTokenDecision: 'allowed',
-        reason: 'consent is granted at jurisdiction level for physician emergency access',
-    }),
-    nursingByOrganizationMedicationHistoryAllowed: buildConsentDecisionScenario({
-        actorId: { organizationUrl: EXAMPLE_PROVIDER_ORG_URL },
-        actorRole: HealthcareActorRoles.NursingProfessional,
-        purpose: HealthcareConsentPurposes.Treatment,
-        consentActions: [HealthcareBasicSections.HistoryOfMedicationUse.claim],
-        requestedSections: HealthcareBasicSections.HistoryOfMedicationUse.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.MedicationStatement,
-            ResourceTypesFhirR4.DocumentReference,
-        ],
-        expectedSmartTokenDecision: 'allowed',
-        reason: 'nursing professional is allowed to read medication history for treatment through organization-scoped consent',
-    }),
-    paramedicByJurisdictionEmergencySummaryAllowed: buildConsentDecisionScenario({
-        actorId: EXAMPLE_JURISDICTION,
-        actorRole: HealthcareActorRoles.Paramedic,
-        purpose: HealthcareConsentPurposes.EmergencyTreatment,
-        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
-        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.DocumentReference,
-            ResourceTypesFhirR4.Observation,
-        ],
-        expectedSmartTokenDecision: 'allowed',
-        reason: 'paramedic receives emergency-only jurisdiction-scoped access to patient summary',
-    }),
-    physicianObstetricianDeniedWhenOnlyAllergiesConsent: buildConsentDecisionScenario({
-        actorId: EXAMPLE_PHYSICIAN_EMAIL,
-        actorRole: `${HealthcareActorRoles.Physician}:obstetrician`,
-        purpose: HealthcareConsentPurposes.Treatment,
-        consentActions: [HealthcareBasicSections.AllergiesAndIntolerances.claim],
-        requestedSections: HealthcareBasicSections.Results.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.DiagnosticReport,
-            ResourceTypesFhirR4.DocumentReference,
-        ],
-        expectedSmartTokenDecision: 'denied',
-        reason: 'requested SMART scope targets results but active consent only covers allergies section',
-    }),
-    physicianByEmailDeniedWhenConsentRevokedAndNoOrgNorJurisdictionConsentIsActive: buildConsentDecisionScenario({
-        actorId: EXAMPLE_PHYSICIAN_EMAIL,
-        actorRole: HealthcareActorRoles.Physician,
-        purpose: HealthcareConsentPurposes.EmergencyTreatment,
-        consentActions: [HealthcareBasicSections.PatientSummaryDocument.claim],
-        requestedSections: HealthcareBasicSections.PatientSummaryDocument.claim,
-        includedTypes: [
-            ResourceTypesFhirR4.Composition,
-            ResourceTypesFhirR4.DocumentReference,
-        ],
-        expectedSmartTokenDecision: 'denied',
-        reason: 'matching consent rule existed before but is no longer active after controller deactivation/revocation',
-    }),
-});
+    physicianB

package/dist/models/indexing.js

@@ -193,7 +193,7 @@ export function buildIndexParametersFromClaims(claims, allowedClaims) {
         const parameter = {
             name: claimKey,
             value: value,
-            type: inferParameterTypeFromClaimKey(claimKey, rawValue),
+            type: inferPa     type: inferParameterTypeFromClaimKey(claimKey, rawValue),
             ...(claimKey === ObservationClaim.ValueQuantityUnit && typeof rawValue === 'string'
                 ? { unit: rawValue }
                 : {}),

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

@@ -235,7 +235,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 +247,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 +460,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/clinical-resource-filter-editor.d.ts

@@ -0,0 +1,39 @@
+import type { BundleResourceDateFilter, BundleResourceIdFilters } from './bundle-query';
+/**
+ * Canonical high-level filter accepted by both Bundle section readers and
+ * `FhirDocumentFacade`.
+ */
+export type ClinicalResourceFilter = Readonly<{
+    sections?: string[];
+    types?: string[];
+    date?: BundleResourceDateFilter;
+}>;
+/**
+ * Chainable editor for one clinical document resource filter.
+ *
+ * The built value can be passed unchanged to:
+ *
+ * - `BundleReader.getDocumentSectionResourceIds(...)`
+ * - `BundleReader.getDocumentSectionResourceEntries(...)`
+ * - `FhirDocumentFacade.getResourcesByFilter(...)`
+ * - `FhirDocumentFacade.getResourceCount(...)`
+ */
+export declare class ClinicalResourceFilterEditor {
+    private sections?;
+    private types?;
+    private date?;
+    /** Replaces the selected Composition sections. An empty list means all. */
+    setSections(values: readonly string[]): this;
+    /** Replaces the selected FHIR resource types. An empty list means all. */
+    setTypes(values: readonly string[]): this;
+    /** Sets the complete clinical date interval. Either boundary may be omitted. */
+    setPeriod(start?: string, end?: string): this;
+    /** Sets or clears only the start boundary of the clinical date interval. */
+    setPeriodStart(start?: string): this;
+    /** Sets or clears only the end boundary of the clinical date interval. */
+    setPeriodEnd(end?: string): this;
+    /** Removes both clinical date boundaries. */
+    clearPeriod(): this;
+    /** Returns a detached canonical filter safe for either public reader. */
+    build(): ClinicalResourceFilter & BundleResourceIdFilters;
+}

package/dist/utils/clinical-resource-filter-editor.js

@@ -0,0 +1,84 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Chainable editor for one clinical document resource filter.
+ *
+ * The built value can be passed unchanged to:
+ *
+ * - `BundleReader.getDocumentSectionResourceIds(...)`
+ * - `BundleReader.getDocumentSectionResourceEntries(...)`
+ * - `FhirDocumentFacade.getResourcesByFilter(...)`
+ * - `FhirDocumentFacade.getResourceCount(...)`
+ */
+export class ClinicalResourceFilterEditor {
+    sections;
+    types;
+    date;
+    /** Replaces the selected Composition sections. An empty list means all. */
+    setSections(values) {
+        this.sections = normalizeTokens(values);
+        return this;
+    }
+    /** Replaces the selected FHIR resource types. An empty list means all. */
+    setTypes(values) {
+        this.types = normalizeTokens(values);
+        return this;
+    }
+    /** Sets the complete clinical date interval. Either boundary may be omitted. */
+    setPeriod(start, end) {
+        this.date = buildDateFilter(start, end);
+        return this;
+    }
+    /** Sets or clears only the start boundary of the clinical date interval. */
+    setPeriodStart(start) {
+        this.date = buildDateFilter(start, this.date?.end);
+        return this;
+    }
+    /** Sets or clears only the end boundary of the clinical date interval. */
+    setPeriodEnd(end) {
+        this.date = buildDateFilter(this.date?.start, end);
+        return this;
+    }
+    /** Removes both clinical date boundaries. */
+    clearPeriod() {
+        this.date = undefined;
+        return this;
+    }
+    /** Returns a detached canonical filter safe for either public reader. */
+    build() {
+        return {
+            ...(this.sections?.length ? { sections: [...this.sections] } : {}),
+            ...(this.types?.length ? { types: [...this.types] } : {}),
+            ...(this.date ? { date: { ...this.date } } : {}),
+        };
+    }
+}
+function normalizeTokens(values) {
+    const normalized = [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))];
+    return normalized.length ? normalized : undefined;
+}
+function buildDateFilter(start, end) {
+    const normalizedStart = normalizeDate(start, 'start');
+    const normalizedEnd = normalizeDate(end, 'end');
+    if (normalizedStart && normalizedEnd) {
+        if (Date.parse(normalizedStart) > Date.parse(normalizedEnd)) {
+            throw new RangeError('Clinical resource filter period start must not be after end.');
+        }
+    }
+    if (!normalizedStart && !normalizedEnd) {
+        return undefined;
+    }
+    return {
+        ...(normalizedStart ? { start: normalizedStart } : {}),
+        ...(normalizedEnd ? { end: normalizedEnd } : {}),
+    };
+}
+function normalizeDate(value, boundary) {
+    const normalized = String(value || '').trim();
+    if (!normalized) {
+        return undefined;
+    }
+    if (!Number.isFinite(Date.parse(normalized))) {
+        throw new TypeError(`Clinical resource filter period ${boundary} must be a valid date.`);
+    }
+    return normalized;
+}

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.5",
   "publishConfig": {
     "access": "public"
   },