gdc-common-utils-ts 1.14.14 → 1.14.15

package/README.md

@@ -27,7 +27,14 @@ boundaries used in `gdc-common-utils-ts`.
 - FHIR SearchParameter names must use canonical FHIR naming (lowercase, with `-` when defined by FHIR).
 - Never use invented camelCase parameter names for FHIR claims/search keys (example: `Communication.part-of` is valid, `Communication.partOf` is not).
 - Only define custom names when no canonical FHIR SearchParameter exists.
-- `resource.meta.claims` is the canonical claims container and must be preserved across conversions/transports.
+- `resource.meta.claims` is the canonical project-specific claims container and must be preserved across conversions/transports.
+- `resource.meta.claims` is not part of base FHIR; it is a claims-first extension carried by FHIR-like resources in GDC contracts.
+
+If you need the canonical explanation of how DIDComm envelope, batch body,
+entry types, FHIR-like resources, and `resource.meta.claims` fit together,
+read first:
+
+- [`docs/101-COMMUNICATION_LAYERING.md`](docs/101-COMMUNICATION_LAYERING.md)
 
 ## Install
 
@@ -148,12 +155,12 @@ import { JweObject, JwtCompactParts } from 'gdc-common-utils-ts/models';
 - [docs/DATASPACE_DISCOVERY_ROADMAP.md](docs/DATASPACE_DISCOVERY_ROADMAP.md)
   - cross-repo contract for dataspace discovery semantics, EU coverage
     inference, shared DTOs, and parameterized examples
-- [docs/DATASPACE_DISCOVERY_DEFAULTS_101.md](docs/DATASPACE_DISCOVERY_DEFAULTS_101.md)
+- [docs/101-DATASPACE_DISCOVERY_DEFAULTS.md](docs/101-DATASPACE_DISCOVERY_DEFAULTS.md)
   - portal/backend bootstrap guide for `defaults-only`, `default-first`, and
     `internet-first` discovery seeding by `jurisdiction + version + networkType`
 - [docs/consent-access-matrix-task.md](docs/consent-access-matrix-task.md)
   - next-step design/task document for active consent aggregation, explicit deny precedence, controller views, permission-request communications, and SMART access evaluation
-- [docs/IPS_BUNDLE_101.md](docs/IPS_BUNDLE_101.md)
+- [docs/101-IPS_BUNDLE.md](docs/101-IPS_BUNDLE.md)
   - canonical 101 for requesting IPS, editing IPS-style bundles in `Communication.content-attachment-data`, and reading resources by section
 
 ## Dataspace Protocol And Discovery
@@ -177,7 +184,7 @@ Main entry points:
 - [`src/examples/dataspace-discovery.ts`](src/examples/dataspace-discovery.ts)
   - synthetic provider/operator examples that distinguish discovery URL from
     derived catalog artifact URL
-- [`docs/DATASPACE_DISCOVERY_DEFAULTS_101.md`](docs/DATASPACE_DISCOVERY_DEFAULTS_101.md)
+- [`docs/101-DATASPACE_DISCOVERY_DEFAULTS.md`](docs/101-DATASPACE_DISCOVERY_DEFAULTS.md)
   - copy/paste backend bootstrap guide for portal `default-first` rollout
 - [`__tests__/dataspace-discovery-defaults.101.test.ts`](__tests__/dataspace-discovery-defaults.101.test.ts)
   - executable defaults-registry examples for ICAs, hosting operators, and
@@ -267,7 +274,7 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - This is the preferred first scope to teach when the backend only needs subject-scoped read access.
 - [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`](src/utils/vp-token.ts)
   - Extract typed VC objects from a VP token when GW/SDK flows carry canonical proof only in `vp_token`.
-- [`docs/VP_TOKEN_101.md`](docs/VP_TOKEN_101.md)
+- [`docs/101-VP_TOKEN.md`](docs/101-VP_TOKEN.md)
   - Step-by-step guide for building the canonical compact `vp_token` string from organization and representative VCs.
 - [`validateCommunicationResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
   - Validates FHIR R4 `Communication` resources.
@@ -336,9 +343,9 @@ The canonical API contract should live in JSDoc on exported code. The README act
 - [`src/examples/shared.ts`](src/examples/shared.ts)
   - Shared route contexts, controller binding fragments, and reusable helper builders.
   - `tenantId` is modeled as an identifier-like route token (`acme-id`), not as a friendly alternate name.
-- [`docs/LIFECYCLE_101.md`](docs/LIFECYCLE_101.md)
+- [`docs/101-LIFECYCLE.md`](docs/101-LIFECYCLE.md)
   - Copy/paste lifecycle `101` guide with semantic rules and reusable placeholders.
-- [`docs/HEALTHCARE_ROLES_I18N_101.md`](docs/HEALTHCARE_ROLES_I18N_101.md)
+- [`docs/101-HEALTHCARE_ROLES_I18N.md`](docs/101-HEALTHCARE_ROLES_I18N.md)
   - Sector-aware healthcare role catalog and i18n `101` (ISCO-08 + HL7) for FE/BE onboarding.
 
 ## Documentation Naming Rules

package/dist/examples/communication-attached-bundle-session.d.ts

@@ -0,0 +1,22 @@
+import { BundleEntry, BundleJsonApi } from '../models/bundle';
+/**
+ * First developer use case:
+ * - edit a Consent entry inside a Communication-attached Bundle
+ * - keep active entry in memory
+ * - serialize full Bundle to Communication.content-attachment-data on save
+ * - release active entry memory when finished
+ */
+export declare function buildConsentEditingCommunicationSessionExample(): {
+    communicationClaims: Record<string, unknown>;
+    bundleInMemory: BundleJsonApi<BundleEntry>;
+};
+/**
+ * Second developer use case:
+ * - edit MedicationStatement claims to drive a health view
+ * - keep bundle attached to Communication as base64 payload
+ * - apply save/release lifecycle consistently
+ */
+export declare function buildMedicationEditingCommunicationSessionExample(): {
+    communicationClaims: Record<string, unknown>;
+    bundleInMemory: BundleJsonApi<BundleEntry>;
+};

package/dist/examples/communication-attached-bundle-session.js

@@ -0,0 +1,79 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+import { HealthcareBasicSections } from '../constants/healthcare.js';
+import { CommunicationCategoryCodes } from '../constants/communication.js';
+import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
+import { EXAMPLE_COMMUNICATION_IDENTIFIER, EXAMPLE_CONSENT_DATE, EXAMPLE_CONSENT_IDENTIFIER, EXAMPLE_CONSENT_PERIOD_END, EXAMPLE_CONSENT_PERIOD_START, EXAMPLE_CONSENT_PURPOSE_TREATMENT, EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN, EXAMPLE_IPS_BUNDLE_NOTE_TEXT, EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER, EXAMPLE_MEDICATION_STATEMENT_STATUS, EXAMPLE_MEDICATION_STATEMENT_TEXT, EXAMPLE_SUBJECT_DID, } from './shared.js';
+import { CommunicationAttachedBundleSession } from '../utils/communication-attached-bundle-session.js';
+import { setCommunicationCategory, setCommunicationIdentifier, setCommunicationSubject, setCommunicationText, } from '../claims/claims-helpers-communication.js';
+import { setActorIdentifierList, setActorRoleList, setConsentDate, setConsentDecision, setConsentIdentifier, setConsentPeriodEnd, setConsentPeriodStart, setConsentSubject, setPurposeList, setSectionList, } from '../claims/claims-helpers-consent.js';
+/**
+ * First developer use case:
+ * - edit a Consent entry inside a Communication-attached Bundle
+ * - keep active entry in memory
+ * - serialize full Bundle to Communication.content-attachment-data on save
+ * - release active entry memory when finished
+ */
+export function buildConsentEditingCommunicationSessionExample() {
+    let communicationClaims = { '@context': 'org.hl7.fhir.r4' };
+    communicationClaims = setCommunicationIdentifier(communicationClaims, EXAMPLE_COMMUNICATION_IDENTIFIER);
+    communicationClaims = setCommunicationSubject(communicationClaims, EXAMPLE_SUBJECT_DID);
+    communicationClaims = setCommunicationCategory(communicationClaims, CommunicationCategoryCodes.Notification.attributeValue);
+    communicationClaims = setCommunicationText(communicationClaims, EXAMPLE_IPS_BUNDLE_NOTE_TEXT);
+    const bundleEditor = new CommunicationAttachedBundleSession({
+        communicationClaims,
+    });
+    let consentClaims = { '@context': 'org.hl7.fhir.api' };
+    consentClaims = setConsentDecision(consentClaims, 'permit');
+    consentClaims = setConsentSubject(consentClaims, EXAMPLE_SUBJECT_DID);
+    consentClaims = setConsentIdentifier(consentClaims, EXAMPLE_CONSENT_IDENTIFIER);
+    consentClaims = setConsentDate(consentClaims, EXAMPLE_CONSENT_DATE);
+    consentClaims = setConsentPeriodStart(consentClaims, EXAMPLE_CONSENT_PERIOD_START);
+    consentClaims = setConsentPeriodEnd(consentClaims, EXAMPLE_CONSENT_PERIOD_END);
+    consentClaims = setPurposeList(consentClaims, [EXAMPLE_CONSENT_PURPOSE_TREATMENT]);
+    consentClaims = setSectionList(consentClaims, [
+        HealthcareBasicSections.AllergiesAndIntolerances.attributeValue,
+    ]);
+    consentClaims = setActorIdentifierList(consentClaims, [EXAMPLE_EMAIL_PROFESSIONAL]);
+    consentClaims = setActorRoleList(consentClaims, [EXAMPLE_HEALTHCARE_ACTOR_ROLE_PHYSICIAN]);
+    bundleEditor.upsertActiveConsentEntry({
+        claims: consentClaims,
+        fullUrl: `urn:uuid:${EXAMPLE_CONSENT_IDENTIFIER}`,
+    });
+    bundleEditor.saveAndReleaseActiveEntry();
+    return {
+        communicationClaims: bundleEditor.getCommunicationClaims(),
+        bundleInMemory: bundleEditor.getBundleInMemory(),
+    };
+}
+/**
+ * Second developer use case:
+ * - edit MedicationStatement claims to drive a health view
+ * - keep bundle attached to Communication as base64 payload
+ * - apply save/release lifecycle consistently
+ */
+export function buildMedicationEditingCommunicationSessionExample() {
+    let communicationClaims = { '@context': 'org.hl7.fhir.r4' };
+    communicationClaims = setCommunicationIdentifier(communicationClaims, EXAMPLE_COMMUNICATION_IDENTIFIER);
+    communicationClaims = setCommunicationSubject(communicationClaims, EXAMPLE_SUBJECT_DID);
+    communicationClaims = setCommunicationCategory(communicationClaims, CommunicationCategoryCodes.Reminder.attributeValue);
+    communicationClaims = setCommunicationText(communicationClaims, EXAMPLE_IPS_BUNDLE_NOTE_TEXT);
+    const bundleEditor = new CommunicationAttachedBundleSession({
+        communicationClaims,
+    });
+    bundleEditor.upsertActiveMedicationStatementEntry({
+        claims: {
+            '@context': 'org.hl7.fhir.api',
+            [MedicationStatementClaim.Identifier]: EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER,
+            [MedicationStatementClaim.Subject]: EXAMPLE_SUBJECT_DID,
+            [MedicationStatementClaim.Status]: EXAMPLE_MEDICATION_STATEMENT_STATUS,
+            [MedicationStatementClaim.MedicationText]: EXAMPLE_MEDICATION_STATEMENT_TEXT,
+        },
+        fullUrl: `urn:uuid:${EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER}`,
+    });
+    bundleEditor.saveAndReleaseActiveEntry();
+    return {
+        communicationClaims: bundleEditor.getCommunicationClaims(),
+        bundleInMemory: bundleEditor.getBundleInMemory(),
+    };
+}

package/dist/examples/index.d.ts

@@ -12,6 +12,6 @@ export * from './frontend-session';
 export * from './lifecycle';
 export * from './api-flow-examples';
 export * from './contract-examples';
-export * from './communication-bundle-session';
+export * from './communication-attached-bundle-session';
 export * from './communication-bundle-document-request';
 export * from './ips-bundle';

package/dist/examples/index.js

@@ -12,6 +12,6 @@ export * from './frontend-session.js';
 export * from './lifecycle.js';
 export * from './api-flow-examples.js';
 export * from './contract-examples.js';
-export * from './communication-bundle-session.js';
+export * from './communication-attached-bundle-session.js';
 export * from './communication-bundle-document-request.js';
 export * from './ips-bundle.js';

package/dist/examples/ips-bundle.js

@@ -8,13 +8,13 @@ import { ConditionClaim } from '../models/interoperable-claims/condition-claims.
 import { MedicationStatementClaim } from '../models/interoperable-claims/medication-statement-claims.js';
 import { EXAMPLE_COMMUNICATION_IDENTIFIER, EXAMPLE_DOCUMENT_REFERENCE_CONTENT_TYPE_PDF, EXAMPLE_DOCUMENT_REFERENCE_DATE, EXAMPLE_DOCUMENT_REFERENCE_DESCRIPTION, EXAMPLE_DOCUMENT_REFERENCE_IDENTIFIER, EXAMPLE_DOCUMENT_REFERENCE_URL, EXAMPLE_IPS_BUNDLE_NOTE_TEXT, EXAMPLE_MEDICATION_STATEMENT_IDENTIFIER, EXAMPLE_MEDICATION_STATEMENT_STATUS, EXAMPLE_MEDICATION_STATEMENT_TEXT, EXAMPLE_SUBJECT_DID, } from './shared.js';
 import { toClinicalResourceCardViews, toClinicalResourceCommonViews, } from '../utils/clinical-resource-view.js';
-import { CommunicationBundleSession } from '../utils/communication-bundle-session.js';
+import { CommunicationAttachedBundleSession } from '../utils/communication-attached-bundle-session.js';
 /**
  * Builds a minimal IPS-like history bundle with common clinical resource types
  * authored as `resource.meta.claims`.
  */
 export function buildIpsClinicalHistoryBundleExample() {
-    const bundleEditor = new CommunicationBundleSession({
+    const bundleEditor = new CommunicationAttachedBundleSession({
         communicationClaims: {
             '@context': 'org.hl7.fhir.r4',
             [CommunicationClaim.Identifier]: EXAMPLE_COMMUNICATION_IDENTIFIER,
@@ -81,7 +81,7 @@ export function buildIpsClinicalHistoryBundleExample() {
  */
 export function buildIpsBundleFrontCardsExample() {
     const { communicationClaims, bundleInMemory } = buildIpsClinicalHistoryBundleExample();
-    const bundleEditor = new CommunicationBundleSession({
+    const bundleEditor = new CommunicationAttachedBundleSession({
         communicationClaims,
         initialBundle: bundleInMemory,
     });

package/dist/models/bundle.d.ts

@@ -16,16 +16,28 @@
  * 2.  **`BundleEntry`**: The core component of a Bundle. Represents a single unit of work,
  *     such as registering one organization or creating one employee. It has a strict
  *     structure:
- *     - `type`: A string that defines the business action (e.g., 'Organization-registration-offer-v1.0').
+ *     - `type`: A string that defines the internal business/message kind
+ *       (e.g., 'Organization-registration-offer-v1.0').
  *     - `resource.meta.claims`: Canonical location for claims in request entries.
  *     - `meta.claims`: Legacy compatibility location accepted during migration.
  *     - `resource`: A FHIR-like resource object that is the subject of the action.
  *     - `request`/`response`: Contextual objects indicating the operation's details or result.
+ *
+ * Important distinction:
+ * - `BundleEntry.type` is not a FHIR field
+ * - `BundleEntry.resource.resourceType` is the actual FHIR-like resource type
+ * - `BundleJsonApi.type` is the batch container type
+ * - DIDComm envelope `type` is yet another outer field
  */
 import { OperationOutcome } from "./operation-outcome";
 /**
  * Defines the `request` property for an entry in a request Bundle.
  * This indicates the intended action for the entry.
+ *
+ * FHIR note:
+ * - this is the closest layer to FHIR batch semantics
+ * - `request.method` and `request.url` describe the operation
+ * - `BundleEntry.type` remains a separate internal business/message label
  */
 export interface BundleRequest {
     method: 'POST' | 'PUT' | 'DELETE' | 'GET';
@@ -131,7 +143,8 @@ export interface ErrorEntry {
  * Represents a single, canonical entry within a `BundleJsonApi`.
  * This structure is used for both requests and successful responses.
  *
- * @property {string} type - A string identifying the business action of the entry.
+ * @property {string} type - Internal business/message kind for this entry.
+ * This is not the FHIR `resourceType`.
  * @property {object} resource - The primary FHIR-like resource that is the subject of the action.
  *                               Canonical claims location is `resource.meta.claims`.
  * @property {BundleEntryMeta} [meta] - Legacy top-level claims location for backward compatibility.
@@ -153,6 +166,11 @@ export type BundleEntry = {
  * The generic type `T` allows for specifying whether the `data` array contains request
  * entries or response entries, providing strong type safety.
  *
+ * Layering note:
+ * - this is the business batch container
+ * - it is often placed inside the `body` of a DIDComm/FAPI envelope
+ * - entries inside it carry FHIR-like resources plus internal business labels
+ *
  * @example
  * const requestBundle: BundleJsonApi<BundleEntry> = { ... };
  * const responseBundle: BundleJsonApi<BundleEntry | ErrorEntry> = { ... };

package/dist/models/bundle.js

@@ -16,10 +16,17 @@
  * 2.  **`BundleEntry`**: The core component of a Bundle. Represents a single unit of work,
  *     such as registering one organization or creating one employee. It has a strict
  *     structure:
- *     - `type`: A string that defines the business action (e.g., 'Organization-registration-offer-v1.0').
+ *     - `type`: A string that defines the internal business/message kind
+ *       (e.g., 'Organization-registration-offer-v1.0').
  *     - `resource.meta.claims`: Canonical location for claims in request entries.
  *     - `meta.claims`: Legacy compatibility location accepted during migration.
  *     - `resource`: A FHIR-like resource object that is the subject of the action.
  *     - `request`/`response`: Contextual objects indicating the operation's details or result.
+ *
+ * Important distinction:
+ * - `BundleEntry.type` is not a FHIR field
+ * - `BundleEntry.resource.resourceType` is the actual FHIR-like resource type
+ * - `BundleJsonApi.type` is the batch container type
+ * - DIDComm envelope `type` is yet another outer field
  */
 export {};

package/dist/models/comm.d.ts

@@ -1,5 +1,16 @@
 /**
  * Represents the standard payload of a DIDComm v2 message.
+ *
+ * Layering rule:
+ * - `type` here is the DIDComm/protocol envelope type
+ * - it is not the FHIR `resourceType`
+ * - it is not the internal GW batch-entry business type
+ * - `body` carries the next business layer (often a `BundleJsonApi`)
+ *
+ * Read together with:
+ * - `docs/101-COMMUNICATION_LAYERING.md`
+ * - `src/models/bundle.ts`
+ *
  * @see https://identity.foundation/didcomm-messaging/spec/v2.0/#plaintext-message-structure
  */
 export interface DidCommPayload {
@@ -18,6 +29,11 @@ export interface DidCommPayload {
 /**
  * Represents a data entry in the `body` of a CommMsgExtended,
  * following a hybrid JSON:API and FHIR structure.
+ *
+ * Important:
+ * - `type` is an internal entry/data kind such as `Reference` or `Attachment`
+ * - it is not the DIDComm envelope type
+ * - it is not a FHIR `resourceType`
  */
 export interface DataEntry {
     id: string;
@@ -44,6 +60,19 @@ export interface DidCommAttachment {
 /**
  * The canonical, internal representation of a secure message, extending
  * the standard DIDComm payload with FHIR-specific, flattened metadata.
+ *
+ * Intended usage:
+ * - internal GW/runtime representation
+ * - derived from FHIR-like `Communication` payloads when needed
+ *
+ * Not intended as:
+ * - the primary client-facing payload new integrators should author first
+ *
+ * New client code should usually send:
+ * - DIDComm/FAPI-style envelope
+ * - carrying a batch body
+ * - carrying FHIR-like resources such as `Communication`
+ * - with canonical business semantics in `resource.meta.claims`
  */
 export interface CommMsgExtended extends DidCommPayload {
     body: {

package/dist/models/confidential-message.d.ts

@@ -29,6 +29,15 @@ export interface DidCommDecodedMetadata {
  * Represents the plaintext of a decoded DIDComm message.
  * This is the core business-level "input" for a job.
  * For FAPI compliance, this entire object is typically the payload of a signed JWS.
+ *
+ * Layering rule:
+ * - `type` is the outer envelope/protocol type
+ * - `body` carries the business payload
+ * - that `body` is often a batch container such as `BundleJsonApi`
+ * - resources inside that batch may be FHIR-like resources with
+ *   `resource.meta.claims`
+ *
+ * This object is not itself a FHIR resource.
  */
 export interface IDecodedDidcommPayload {
     /** Relevant information available through the decryption and verification process */
@@ -66,10 +75,24 @@ export interface IDecodedDidcommPayload {
     from?: string;
     /**
      * The Message Type URI, identifying the type of data in the body or protocol used.
-     * (e.g. 'application/json')
+     *
+     * Examples:
+     * - DIDComm/business envelope type
+     * - transport protocol hint
+     *
+     * This is not:
+     * - a FHIR `resourceType`
+     * - a GW batch-entry business type
     */
     type: string;
-    /** The main business payload of the message. The structure is defined by the 'type' protocol. */
+    /**
+     * The main business payload of the message.
+     *
+     * In GW/SDK flows this is often:
+     * - a hybrid batch container (`BundleJsonApi`)
+     * - carrying entries
+     * - carrying FHIR-like resources
+     */
     body: any;
 }
 /**
@@ -89,6 +112,11 @@ export interface CommDataEntry {
 /**
  * The canonical, internal representation of a secure message, extending
  * the standard DIDComm payload with FHIR-specific, flattened metadata.
+ *
+ * Internal model note:
+ * - this is a gateway/runtime representation
+ * - it is not the main payload shape that new SDK/frontend/backend integrators
+ *   should author directly
  */
 export interface ICommPayloadExtended extends IDecodedDidcommPayload {
     body: {

package/dist/models/interoperable-claims/diagnostic-report-claims.d.ts

@@ -91,6 +91,6 @@ export declare const DiagnosticReportSearchParamToClaimKey: Record<DiagnosticRep
  *
  * Keep `DiagnosticReport` paused at the typing/mapping layer until:
  * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. `CommunicationBundleSession.upsertActiveDiagnosticReportEntry(...)` exists
+ * 2. `CommunicationAttachedBundleSession.upsertActiveDiagnosticReportEntry(...)` exists
  * 3. GW Core readers/tests consume the same shared claim keys
  */

package/dist/models/interoperable-claims/diagnostic-report-claims.js

@@ -100,6 +100,6 @@ export const DiagnosticReportSearchParamToClaimKey = {
  *
  * Keep `DiagnosticReport` paused at the typing/mapping layer until:
  * 1. `claims-helpers-diagnostic-report.ts` exists
- * 2. `CommunicationBundleSession.upsertActiveDiagnosticReportEntry(...)` exists
+ * 2. `CommunicationAttachedBundleSession.upsertActiveDiagnosticReportEntry(...)` exists
  * 3. GW Core readers/tests consume the same shared claim keys
  */

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

@@ -0,0 +1,191 @@
+import { BundleEntry, BundleJsonApi, BundleRequest } from '../models/bundle';
+import { type BundleResourceIdFilters } from './bundle-query';
+import { type MedicationStatementClaimsFlat } from '../models/interoperable-claims/medication-statement-claims';
+export type CommunicationAttachedBundleSessionMode = 'strict' | 'normalize';
+export type CommunicationAttachedBundleSessionOptions = Readonly<{
+    communicationClaims?: Record<string, unknown>;
+    initialBundle?: BundleJsonApi<BundleEntry>;
+    mode?: CommunicationAttachedBundleSessionMode;
+}>;
+export type ActiveEntrySelection = Readonly<{
+    index?: number;
+    fullUrl?: string;
+}>;
+export type UpsertEntryInput = Readonly<{
+    resourceType: string;
+    claims: Record<string, unknown>;
+    type?: string;
+    fullUrl?: string;
+    request?: BundleRequest;
+}>;
+export type AddContainedDocumentToActiveEntryInput = Readonly<{
+    identifier?: string;
+    fullUrl?: string;
+    claims?: Record<string, unknown>;
+    attachmentContentType?: string;
+    attachmentDataBase64?: string;
+    attachmentUrl?: string;
+    description?: string;
+    date?: string;
+    language?: string;
+}>;
+/**
+ * Communication editing session with bundle-in-memory as source of truth.
+ *
+ * Design contract:
+ * - `activeEntry` is the real editing unit (not only `activeResource`), because
+ *   it can include `fullUrl`, `request`, and entry-level context.
+ * - `Communication.content-attachment-data` is always derived from the
+ *   in-memory bundle after each committed update.
+ * - saving can release active entry memory via `saveAndReleaseActiveEntry()`.
+ */
+export declare class CommunicationAttachedBundleSession {
+    private communicationClaims;
+    private bundleInMemory;
+    private activeEntryIndex;
+    private mode;
+    constructor(options?: CommunicationAttachedBundleSessionOptions);
+    /** Returns a deep copy of communication claims. */
+    getCommunicationClaims(): Record<string, unknown>;
+    /** Returns a deep copy of the current in-memory bundle. */
+    getBundleInMemory(): BundleJsonApi<BundleEntry>;
+    /** Returns the active entry index, or null when no entry is selected. */
+    getActiveEntryIndex(): number | null;
+    /** Returns a deep copy of the active entry when selected. */
+    getActiveEntry(): BundleEntry | null;
+    /** Selects an active entry by index or fullUrl. */
+    selectActiveEntry(selection: ActiveEntrySelection): this;
+    /** Clears active entry selection from memory. */
+    clearActiveEntry(): this;
+    /**
+     * Upserts an entry in bundle memory and marks it as active.
+     * Matching priority: `fullUrl` if present, then resource claim identifier.
+     */
+    upsertActiveEntry(input: UpsertEntryInput): this;
+    /**
+     * Consent-first helper for developer onboarding.
+     *
+     * Expected keys should come from `ClaimConsent` in caller code.
+     */
+    upsertActiveConsentEntry(input: Readonly<{
+        claims: Record<string, unknown>;
+        fullUrl?: string;
+        type?: string;
+        request?: BundleRequest;
+    }>): this;
+    /**
+     * MedicationStatement helper for IPS-in-Communication use cases.
+     *
+     * Expected keys should come from MedicationStatement claims constants.
+     */
+    upsertActiveMedicationStatementEntry(input: Readonly<{
+        claims: MedicationStatementClaimsFlat | Record<string, unknown>;
+        fullUrl?: string;
+        type?: string;
+        request?: BundleRequest;
+    }>): this;
+    /**
+     * DocumentReference helper for bundle-contained attachments linked from
+     * other clinical resources through `*.contained-documents`.
+     */
+    upsertActiveDocumentReferenceEntry(input: Readonly<{
+        claims: Record<string, unknown>;
+        fullUrl?: string;
+        type?: string;
+        request?: BundleRequest;
+    }>): this;
+    /**
+     * Condition helper for IPS-in-Communication use cases.
+     *
+     * Expected keys should come from Condition claims constants.
+     */
+    upsertActiveConditionEntry(input: Readonly<{
+        claims: Record<string, unknown>;
+        fullUrl?: string;
+        type?: string;
+        request?: BundleRequest;
+    }>): this;
+    /**
+     * AllergyIntolerance helper for IPS-in-Communication use cases.
+     *
+     * Expected keys should come from AllergyIntolerance claims constants.
+     */
+    upsertActiveAllergyIntoleranceEntry(input: Readonly<{
+        claims: Record<string, unknown>;
+        fullUrl?: string;
+        type?: string;
+        request?: BundleRequest;
+    }>): this;
+    /**
+     * TODO(ips-next):
+     * Add `upsertActiveDiagnosticReportEntry(...)` once the shared claim helpers
+     * for `DiagnosticReport` are in place.
+     *
+     * Expected shape should mirror the existing resource helpers:
+     * - `claims` authored with `@context = org.hl7.fhir.api`
+     * - matching priority by `DiagnosticReport.identifier`
+     * - support for linked `DocumentReference` ids through
+     *   `DiagnosticReport.contained-documents`
+     *
+     * Intentionally not implemented in this pass:
+     * - IPS authoring already works for the currently documented resources
+     * - GW Core can already consume bundle-contained `DocumentReference` rows
+     * - adding the DiagnosticReport editing surface now would expand the IPS
+     *   contract further than intended for this release slice
+     */
+    /**
+     * Creates or updates a linked `DocumentReference` entry and stores its
+     * identifier under the active resource `*.contained-documents` claim.
+     */
+    addContainedDocumentToActiveEntry(input: AddContainedDocumentToActiveEntryInput): this;
+    /**
+     * Patches active entry `resource.meta.claims` and synchronizes attachment data.
+     */
+    patchActiveEntryClaims(claimPatch: Record<string, unknown>): this;
+    /**
+     * Persists current memory state into communication claims attachment.
+     * No-op for active entry pointer.
+     */
+    saveActiveEntry(): this;
+    /**
+     * Persists and releases active entry memory pointer.
+     * This is the recommended step after a successful save operation.
+     */
+    saveAndReleaseActiveEntry(): this;
+    /**
+     * Returns stable resource IDs from bundle entries with optional filters.
+     */
+    getResourceIds(filters?: BundleResourceIdFilters): string[];
+    /**
+     * Returns bundle entries matching resource IDs produced by `getResourceIds`.
+     */
+    getResourceEntriesByIds(resourceIds: readonly string[]): BundleEntry[];
+    /**
+     * Resolves the entry URL (`fullUrl`) for a given entry/resource identifier.
+     */
+    getEntryUrl(entryId: string): string | undefined;
+    private decodeBundleFromClaims;
+    private syncAttachmentFromBundle;
+    private resolveCurrentSubject;
+    private findUpsertIndex;
+    private resolveEntryIdentifier;
+    private createBundleEntry;
+    private resolveEntryCanonicalIdValue;
+    private assertEntryIndex;
+}
+/**
+ * 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 {
+}
+/**
+ * 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-attached-bundle-session.js

@@ -0,0 +1,542 @@
+// Copyright 2026 Conectate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { ClaimConsent } from '../models/consent-rule.js';
+import { AllergyIntoleranceClaim } from '../models/interoperable-claims/allergy-intolerance-claims.js';
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+import { ConditionClaim } from '../models/interoperable-claims/condition-claims.js';
+import { DocumentReferenceClaim } from '../models/interoperable-claims/document-reference-claims.js';
+import { BundleQuery } from './bundle-query.js';
+import { addClaimValues } from '../claims/claim-list-helpers.js';
+import { MedicationStatementClaim, } from '../models/interoperable-claims/medication-statement-claims.js';
+/**
+ * Communication editing session with bundle-in-memory as source of truth.
+ *
+ * Design contract:
+ * - `activeEntry` is the real editing unit (not only `activeResource`), because
+ *   it can include `fullUrl`, `request`, and entry-level context.
+ * - `Communication.content-attachment-data` is always derived from the
+ *   in-memory bundle after each committed update.
+ * - saving can release active entry memory via `saveAndReleaseActiveEntry()`.
+ */
+export class CommunicationAttachedBundleSession {
+    communicationClaims;
+    bundleInMemory;
+    activeEntryIndex;
+    mode;
+    constructor(options = {}) {
+        this.mode = options.mode || 'strict';
+        this.communicationClaims = {
+            ...options.communicationClaims,
+        };
+        this.activeEntryIndex = null;
+        const providedBundle = options.initialBundle ? cloneBundle(options.initialBundle) : undefined;
+        this.bundleInMemory = providedBundle || this.decodeBundleFromClaims(this.communicationClaims);
+        this.syncAttachmentFromBundle();
+    }
+    /** Returns a deep copy of communication claims. */
+    getCommunicationClaims() {
+        return {
+            ...this.communicationClaims,
+        };
+    }
+    /** Returns a deep copy of the current in-memory bundle. */
+    getBundleInMemory() {
+        return cloneBundle(this.bundleInMemory);
+    }
+    /** Returns the active entry index, or null when no entry is selected. */
+    getActiveEntryIndex() {
+        return this.activeEntryIndex;
+    }
+    /** Returns a deep copy of the active entry when selected. */
+    getActiveEntry() {
+        if (this.activeEntryIndex === null) {
+            return null;
+        }
+        return cloneEntry(this.bundleInMemory.data[this.activeEntryIndex]);
+    }
+    /** Selects an active entry by index or fullUrl. */
+    selectActiveEntry(selection) {
+        if (typeof selection.index === 'number') {
+            this.assertEntryIndex(selection.index);
+            this.activeEntryIndex = selection.index;
+            return this;
+        }
+        if (selection.fullUrl) {
+            const foundIndex = this.bundleInMemory.data.findIndex((entry) => String(entry?.fullUrl || '').trim() === selection.fullUrl);
+            if (foundIndex < 0) {
+                throw new Error(`Active entry not found for fullUrl: ${selection.fullUrl}`);
+            }
+            this.activeEntryIndex = foundIndex;
+            return this;
+        }
+        throw new Error('selectActiveEntry requires either index or fullUrl.');
+    }
+    /** Clears active entry selection from memory. */
+    clearActiveEntry() {
+        this.activeEntryIndex = null;
+        return this;
+    }
+    /**
+     * Upserts an entry in bundle memory and marks it as active.
+     * Matching priority: `fullUrl` if present, then resource claim identifier.
+     */
+    upsertActiveEntry(input) {
+        const entry = this.createBundleEntry(input);
+        const nextIndex = this.findUpsertIndex(entry, input.fullUrl);
+        if (nextIndex >= 0) {
+            this.bundleInMemory.data[nextIndex] = entry;
+            this.activeEntryIndex = nextIndex;
+        }
+        else {
+            this.bundleInMemory.data.push(entry);
+            this.activeEntryIndex = this.bundleInMemory.data.length - 1;
+        }
+        this.syncAttachmentFromBundle();
+        return this;
+    }
+    /**
+     * Consent-first helper for developer onboarding.
+     *
+     * Expected keys should come from `ClaimConsent` in caller code.
+     */
+    upsertActiveConsentEntry(input) {
+        return this.upsertActiveEntry({
+            resourceType: ResourceTypesFhirR4.Consent,
+            claims: input.claims,
+            fullUrl: input.fullUrl,
+            type: input.type,
+            request: input.request,
+        });
+    }
+    /**
+     * MedicationStatement helper for IPS-in-Communication use cases.
+     *
+     * Expected keys should come from MedicationStatement claims constants.
+     */
+    upsertActiveMedicationStatementEntry(input) {
+        return this.upsertActiveEntry({
+            resourceType: ResourceTypesFhirR4.MedicationStatement,
+            claims: {
+                ...input.claims,
+            },
+            fullUrl: input.fullUrl,
+            type: input.type,
+            request: input.request,
+        });
+    }
+    /**
+     * DocumentReference helper for bundle-contained attachments linked from
+     * other clinical resources through `*.contained-documents`.
+     */
+    upsertActiveDocumentReferenceEntry(input) {
+        return this.upsertActiveEntry({
+            resourceType: ResourceTypesFhirR4.DocumentReference,
+            claims: {
+                ...input.claims,
+            },
+            fullUrl: input.fullUrl,
+            type: input.type,
+            request: input.request,
+        });
+    }
+    /**
+     * Condition helper for IPS-in-Communication use cases.
+     *
+     * Expected keys should come from Condition claims constants.
+     */
+    upsertActiveConditionEntry(input) {
+        return this.upsertActiveEntry({
+            resourceType: ResourceTypesFhirR4.Condition,
+            claims: {
+                ...input.claims,
+            },
+            fullUrl: input.fullUrl,
+            type: input.type,
+            request: input.request,
+        });
+    }
+    /**
+     * AllergyIntolerance helper for IPS-in-Communication use cases.
+     *
+     * Expected keys should come from AllergyIntolerance claims constants.
+     */
+    upsertActiveAllergyIntoleranceEntry(input) {
+        return this.upsertActiveEntry({
+            resourceType: ResourceTypesFhirR4.AllergyIntolerance,
+            claims: {
+                ...input.claims,
+            },
+            fullUrl: input.fullUrl,
+            type: input.type,
+            request: input.request,
+        });
+    }
+    /**
+     * TODO(ips-next):
+     * Add `upsertActiveDiagnosticReportEntry(...)` once the shared claim helpers
+     * for `DiagnosticReport` are in place.
+     *
+     * Expected shape should mirror the existing resource helpers:
+     * - `claims` authored with `@context = org.hl7.fhir.api`
+     * - matching priority by `DiagnosticReport.identifier`
+     * - support for linked `DocumentReference` ids through
+     *   `DiagnosticReport.contained-documents`
+     *
+     * Intentionally not implemented in this pass:
+     * - IPS authoring already works for the currently documented resources
+     * - GW Core can already consume bundle-contained `DocumentReference` rows
+     * - adding the DiagnosticReport editing surface now would expand the IPS
+     *   contract further than intended for this release slice
+     */
+    /**
+     * Creates or updates a linked `DocumentReference` entry and stores its
+     * identifier under the active resource `*.contained-documents` claim.
+     */
+    addContainedDocumentToActiveEntry(input) {
+        if (this.activeEntryIndex === null) {
+            throw new Error('No active entry selected.');
+        }
+        const parentIndex = this.activeEntryIndex;
+        const parentEntry = cloneEntry(this.bundleInMemory.data[parentIndex]);
+        const parentResource = ensureEntryResource(parentEntry, this.mode);
+        const parentClaims = {
+            ...(parentResource.meta?.claims || {}),
+        };
+        const parentResourceType = asTrimmedString(parentResource.resourceType);
+        const containedDocumentsClaimKey = resolveContainedDocumentsClaimKey(parentResourceType);
+        if (!containedDocumentsClaimKey) {
+            throw new Error(`Contained documents are not supported for resourceType: ${parentResourceType || 'unknown'}`);
+        }
+        const documentIdentifier = asTrimmedString(input.identifier)
+            || asTrimmedString(input.claims?.[DocumentReferenceClaim.Identifier])
+            || runtimeUuid('docref');
+        const documentSubject = asTrimmedString(input.claims?.[DocumentReferenceClaim.Subject])
+            || resolveSubjectFromClaims(parentClaims)
+            || asTrimmedString(this.communicationClaims[CommunicationClaim.Subject]);
+        const documentClaims = {
+            '@context': 'org.hl7.fhir.api',
+            ...(input.claims || {}),
+            [DocumentReferenceClaim.Identifier]: documentIdentifier,
+        };
+        if (documentSubject) {
+            documentClaims[DocumentReferenceClaim.Subject] = documentSubject;
+        }
+        setIfMissing(documentClaims, DocumentReferenceClaim.ContentType, input.attachmentContentType);
+        setIfMissing(documentClaims, DocumentReferenceClaim.ContentData, input.attachmentDataBase64);
+        setIfMissing(documentClaims, DocumentReferenceClaim.Location, input.attachmentUrl);
+        setIfMissing(documentClaims, DocumentReferenceClaim.Description, input.description);
+        setIfMissing(documentClaims, DocumentReferenceClaim.Date, input.date);
+        setIfMissing(documentClaims, DocumentReferenceClaim.Language, input.language);
+        this.upsertActiveDocumentReferenceEntry({
+            claims: documentClaims,
+            fullUrl: input.fullUrl || `urn:uuid:${documentIdentifier}`,
+        });
+        parentResource.meta = parentResource.meta || {};
+        parentResource.meta.claims = addClaimValues(parentClaims, containedDocumentsClaimKey, [documentIdentifier]);
+        parentEntry.resource = parentResource;
+        this.bundleInMemory.data[parentIndex] = parentEntry;
+        this.activeEntryIndex = parentIndex;
+        this.syncAttachmentFromBundle();
+        return this;
+    }
+    /**
+     * Patches active entry `resource.meta.claims` and synchronizes attachment data.
+     */
+    patchActiveEntryClaims(claimPatch) {
+        if (this.activeEntryIndex === null) {
+            throw new Error('No active entry selected.');
+        }
+        const current = cloneEntry(this.bundleInMemory.data[this.activeEntryIndex]);
+        const resource = ensureEntryResource(current, this.mode);
+        resource.meta = resource.meta || {};
+        resource.meta.claims = {
+            ...(resource.meta.claims || {}),
+            ...claimPatch,
+        };
+        current.resource = resource;
+        this.bundleInMemory.data[this.activeEntryIndex] = current;
+        this.syncAttachmentFromBundle();
+        return this;
+    }
+    /**
+     * Persists current memory state into communication claims attachment.
+     * No-op for active entry pointer.
+     */
+    saveActiveEntry() {
+        this.syncAttachmentFromBundle();
+        return this;
+    }
+    /**
+     * Persists and releases active entry memory pointer.
+     * This is the recommended step after a successful save operation.
+     */
+    saveAndReleaseActiveEntry() {
+        this.syncAttachmentFromBundle();
+        this.clearActiveEntry();
+        return this;
+    }
+    /**
+     * Returns stable resource IDs from bundle entries with optional filters.
+     */
+    getResourceIds(filters = {}) {
+        const query = new BundleQuery(this.bundleInMemory);
+        return query.getResourceIds(filters);
+    }
+    /**
+     * Returns bundle entries matching resource IDs produced by `getResourceIds`.
+     */
+    getResourceEntriesByIds(resourceIds) {
+        const query = new BundleQuery(this.bundleInMemory);
+        return query.getResourceEntriesByIds(resourceIds);
+    }
+    /**
+     * Resolves the entry URL (`fullUrl`) for a given entry/resource identifier.
+     */
+    getEntryUrl(entryId) {
+        const query = new BundleQuery(this.bundleInMemory);
+        return query.getEntryUrl(entryId);
+    }
+    decodeBundleFromClaims(claims) {
+        const encoded = asTrimmedString(claims[CommunicationClaim.ContentAttachmentData]);
+        if (!encoded) {
+            return createEmptyBundle();
+        }
+        try {
+            const text = Buffer.from(encoded, 'base64').toString('utf8');
+            const parsed = JSON.parse(text);
+            validateBundleLike(parsed, this.mode);
+            return cloneBundle(parsed);
+        }
+        catch (error) {
+            if (this.mode === 'normalize') {
+                return createEmptyBundle();
+            }
+            throw new Error(`Invalid ${CommunicationClaim.ContentAttachmentData}: ${error.message}`);
+        }
+    }
+    syncAttachmentFromBundle() {
+        this.communicationClaims[CommunicationClaim.ContentAttachmentType] = 'application/fhir+json';
+        this.communicationClaims[CommunicationClaim.ContentAttachmentData] = encodeBundleToBase64(this.bundleInMemory);
+        const activeSubject = this.resolveCurrentSubject();
+        if (activeSubject) {
+            this.communicationClaims[CommunicationClaim.Subject] = activeSubject;
+        }
+    }
+    resolveCurrentSubject() {
+        if (this.activeEntryIndex !== null) {
+            const claims = this.bundleInMemory.data[this.activeEntryIndex]?.resource?.meta?.claims || {};
+            const consentSubject = asTrimmedString(claims[ClaimConsent.subject]);
+            if (consentSubject) {
+                return consentSubject;
+            }
+            const medicationSubject = asTrimmedString(claims[MedicationStatementClaim.Subject]);
+            if (medicationSubject) {
+                return medicationSubject;
+            }
+            const conditionSubject = asTrimmedString(claims[ConditionClaim.Subject]);
+            if (conditionSubject) {
+                return conditionSubject;
+            }
+            const allergySubject = asTrimmedString(claims[AllergyIntoleranceClaim.Subject] || claims[AllergyIntoleranceClaim.Patient]);
+            if (allergySubject) {
+                return allergySubject;
+            }
+            const documentReferenceSubject = asTrimmedString(claims[DocumentReferenceClaim.Subject]);
+            if (documentReferenceSubject) {
+                return documentReferenceSubject;
+            }
+        }
+        const fromClaims = asTrimmedString(this.communicationClaims[CommunicationClaim.Subject]);
+        return fromClaims || undefined;
+    }
+    findUpsertIndex(entry, fullUrl) {
+        if (fullUrl) {
+            const byFullUrl = this.bundleInMemory.data.findIndex((item) => String(item?.fullUrl || '').trim() === fullUrl);
+            if (byFullUrl >= 0) {
+                return byFullUrl;
+            }
+        }
+        const incomingClaims = entry.resource?.meta?.claims || {};
+        const incomingIdentifier = this.resolveEntryIdentifier(incomingClaims);
+        if (!incomingIdentifier) {
+            return -1;
+        }
+        return this.bundleInMemory.data.findIndex((item) => {
+            const itemClaims = item?.resource?.meta?.claims || {};
+            return this.resolveEntryIdentifier(itemClaims) === incomingIdentifier;
+        });
+    }
+    resolveEntryIdentifier(claims) {
+        const consentIdentifier = asTrimmedString(claims[ClaimConsent.identifier]);
+        if (consentIdentifier) {
+            return `${ResourceTypesFhirR4.Consent}:${consentIdentifier}`;
+        }
+        const medicationIdentifier = asTrimmedString(claims[MedicationStatementClaim.Identifier]);
+        if (medicationIdentifier) {
+            return `${ResourceTypesFhirR4.MedicationStatement}:${medicationIdentifier}`;
+        }
+        const conditionIdentifier = asTrimmedString(claims[ConditionClaim.Identifier]);
+        if (conditionIdentifier) {
+            return `${ResourceTypesFhirR4.Condition}:${conditionIdentifier}`;
+        }
+        const allergyIdentifier = asTrimmedString(claims[AllergyIntoleranceClaim.Identifier]);
+        if (allergyIdentifier) {
+            return `${ResourceTypesFhirR4.AllergyIntolerance}:${allergyIdentifier}`;
+        }
+        const documentReferenceIdentifier = asTrimmedString(claims[DocumentReferenceClaim.Identifier]);
+        if (documentReferenceIdentifier) {
+            return `${ResourceTypesFhirR4.DocumentReference}:${documentReferenceIdentifier}`;
+        }
+        return '';
+    }
+    createBundleEntry(input) {
+        const resourceClaims = {
+            ...input.claims,
+        };
+        const canonicalEntryIdentifier = this.resolveEntryCanonicalIdValue(resourceClaims);
+        return {
+            id: canonicalEntryIdentifier || undefined,
+            type: input.type || `${input.resourceType}-edit-request-v1.0`,
+            fullUrl: input.fullUrl,
+            request: input.request,
+            resource: {
+                resourceType: input.resourceType,
+                meta: {
+                    claims: resourceClaims,
+                },
+            },
+        };
+    }
+    resolveEntryCanonicalIdValue(claims) {
+        const consentIdentifier = asTrimmedString(claims[ClaimConsent.identifier]);
+        if (consentIdentifier) {
+            return consentIdentifier;
+        }
+        const medicationIdentifier = asTrimmedString(claims[MedicationStatementClaim.Identifier]);
+        if (medicationIdentifier) {
+            return medicationIdentifier;
+        }
+        const conditionIdentifier = asTrimmedString(claims[ConditionClaim.Identifier]);
+        if (conditionIdentifier) {
+            return conditionIdentifier;
+        }
+        const allergyIdentifier = asTrimmedString(claims[AllergyIntoleranceClaim.Identifier]);
+        if (allergyIdentifier) {
+            return allergyIdentifier;
+        }
+        const documentReferenceIdentifier = asTrimmedString(claims[DocumentReferenceClaim.Identifier]);
+        if (documentReferenceIdentifier) {
+            return documentReferenceIdentifier;
+        }
+        const communicationIdentifier = asTrimmedString(claims[CommunicationClaim.Identifier]);
+        if (communicationIdentifier) {
+            return communicationIdentifier;
+        }
+        return '';
+    }
+    assertEntryIndex(index) {
+        if (!Number.isInteger(index) || index < 0 || index >= this.bundleInMemory.data.length) {
+            throw new Error(`Entry index out of range: ${index}`);
+        }
+    }
+}
+/**
+ * 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 {
+}
+/**
+ * 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);
+}
+function ensureEntryResource(entry, mode) {
+    const resource = entry.resource;
+    if (resource && typeof resource === 'object') {
+        return resource;
+    }
+    if (mode === 'normalize') {
+        return { meta: { claims: {} } };
+    }
+    throw new Error('Active entry does not contain a valid resource object.');
+}
+function validateBundleLike(bundle, mode) {
+    const looksLikeBundle = bundle && bundle.resourceType === ResourceTypesFhirR4.Bundle && Array.isArray(bundle.data);
+    if (looksLikeBundle) {
+        return;
+    }
+    if (mode === 'normalize') {
+        return;
+    }
+    throw new Error('Decoded attachment is not a valid BundleJsonApi payload.');
+}
+function createEmptyBundle() {
+    return {
+        resourceType: ResourceTypesFhirR4.Bundle,
+        type: 'batch',
+        data: [],
+    };
+}
+function encodeBundleToBase64(bundle) {
+    return Buffer.from(JSON.stringify(bundle), 'utf8').toString('base64');
+}
+function cloneBundle(bundle) {
+    return JSON.parse(JSON.stringify(bundle));
+}
+function cloneEntry(entry) {
+    return JSON.parse(JSON.stringify(entry));
+}
+function asTrimmedString(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return String(value).trim();
+}
+function resolveContainedDocumentsClaimKey(resourceType) {
+    if (resourceType === ResourceTypesFhirR4.Consent) {
+        return ClaimConsent.containedDocuments;
+    }
+    if (resourceType === ResourceTypesFhirR4.MedicationStatement) {
+        return MedicationStatementClaim.ContainedDocuments;
+    }
+    if (resourceType === ResourceTypesFhirR4.Condition) {
+        return ConditionClaim.ContainedDocuments;
+    }
+    if (resourceType === ResourceTypesFhirR4.AllergyIntolerance) {
+        return AllergyIntoleranceClaim.ContainedDocuments;
+    }
+    return '';
+}
+function resolveSubjectFromClaims(claims) {
+    return asTrimmedString(claims[ClaimConsent.subject]
+        || claims[MedicationStatementClaim.Subject]
+        || claims[ConditionClaim.Subject]
+        || claims[AllergyIntoleranceClaim.Subject]
+        || claims[AllergyIntoleranceClaim.Patient]
+        || claims[DocumentReferenceClaim.Subject]);
+}
+function setIfMissing(target, key, value) {
+    if (target[key] !== undefined) {
+        return;
+    }
+    if (value === undefined || value === null || String(value).trim() === '') {
+        return;
+    }
+    target[key] = value;
+}
+function runtimeUuid(prefix) {
+    const cryptoLike = globalThis;
+    if (typeof cryptoLike.crypto?.randomUUID === 'function') {
+        return cryptoLike.crypto.randomUUID();
+    }
+    return `${prefix}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}

package/dist/utils/employee.d.ts

@@ -18,6 +18,9 @@ export type EmployeeBatchEntryInput = Readonly<{
     resourceType?: 'Employee';
     type?: string;
 }>;
+export type EmployeeBatchBundleInput = Readonly<{
+    entries: readonly EmployeeBatchEntryInput[];
+}>;
 export type EmployeeSearchBundleInput = Readonly<{
     claims?: Record<string, EmployeeSearchValue | undefined>;
     method?: 'GET' | 'POST';
@@ -48,6 +51,15 @@ export declare function buildEmployeeBatchEntry(input: EmployeeBatchEntryInput):
         };
     };
 };
+/**
+ * Builds a canonical employee `_batch` bundle from one or more employee batch
+ * entries.
+ */
+export declare function buildEmployeeBatchBundle(input: EmployeeBatchBundleInput): {
+    resourceType: 'Bundle';
+    type: 'batch';
+    entry: Array<ReturnType<typeof buildEmployeeBatchEntry>>;
+};
 /**
  * Builds the legacy query-string employee search target kept for compatibility
  * with older `_search` wrappers.

package/dist/utils/employee.js

@@ -3,6 +3,15 @@ import { buildFhirParametersResourceFromSearchParams, buildSearchQueryString, }
 function cloneClaims(claims) {
     return { ...(claims || {}) };
 }
+function normalizeEmployeeSearchClaims(claims) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(claims || {})) {
+        if (key === '@context')
+            continue;
+        normalized[key] = value;
+    }
+    return normalized;
+}
 function inferEmployeeEntryType(method) {
     switch (method) {
         case 'DELETE':
@@ -65,13 +74,24 @@ export function buildEmployeeBatchEntry(input) {
         },
     };
 }
+/**
+ * Builds a canonical employee `_batch` bundle from one or more employee batch
+ * entries.
+ */
+export function buildEmployeeBatchBundle(input) {
+    return {
+        resourceType: 'Bundle',
+        type: 'batch',
+        entry: [...input.entries].map((entry) => buildEmployeeBatchEntry(entry)),
+    };
+}
 /**
  * Builds the legacy query-string employee search target kept for compatibility
  * with older `_search` wrappers.
  */
 export function buildEmployeeSearchQuery(input = {}) {
     const resourceType = input.resourceType || 'Employee';
-    const query = buildSearchQueryString(input.claims || {});
+    const query = buildSearchQueryString(normalizeEmployeeSearchClaims(input.claims));
     return query ? `${resourceType}?${query}` : resourceType;
 }
 /**
@@ -82,7 +102,7 @@ export function buildEmployeeSearchQuery(input = {}) {
  */
 export function buildEmployeeSearchBundle(input = {}) {
     const resourceType = input.resourceType || 'Employee';
-    const claims = input.claims || {};
+    const claims = normalizeEmployeeSearchClaims(input.claims);
     const method = input.method || (input.encoding === 'get-query' ? 'GET' : 'POST');
     if (method === 'GET') {
         return {

package/dist/utils/index.d.ts

@@ -26,7 +26,7 @@ export * from './communication-fhir-r4';
 export * from './communication-document-reference';
 export * from './communication-bundle-document-request';
 export * from './communication-identity';
-export * from './communication-bundle-session';
+export * from './communication-attached-bundle-session';
 export * from './clinical-resource-converters';
 export * from './clinical-resource-view';
 export * from './fhir-validator';

package/dist/utils/index.js

@@ -26,7 +26,7 @@ export * from './communication-fhir-r4.js';
 export * from './communication-document-reference.js';
 export * from './communication-bundle-document-request.js';
 export * from './communication-identity.js';
-export * from './communication-bundle-session.js';
+export * from './communication-attached-bundle-session.js';
 export * from './clinical-resource-converters.js';
 export * from './clinical-resource-view.js';
 export * from './fhir-validator.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "1.14.14",
+  "version": "1.14.15",
   "publishConfig": {
     "access": "public"
   },