gdc-common-utils-ts 1.14.13 → 1.14.15

package/README.md

@@ -1,5 +1,11 @@
 # gdc-common-utils-ts
 
+Employee shared examples live in `src/examples/employee.ts`.
+Employee pure helper functions live in `src/utils/employee.ts`.
+
+The canonical employee contract note lives in
+`gdc-sdk-core-ts/docs/EMPLOYEES_101.md`.
+
 Shared TypeScript utilities for GDC client and connector code. This package provides low-level primitives for cryptography, DID/DIDComm-related helpers, and the shared models and interfaces used across SDKs.
 
 It is intentionally not a full backend orchestration layer.
@@ -21,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
 
@@ -142,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
@@ -171,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
@@ -261,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.
@@ -330,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/employee.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical employee directory fixture shared by docs and tests.
+ *
+ * Semantics:
+ * - `identifier` points to one technical employee profile
+ * - `email` can map to multiple active roles
+ * - a purged profile remains historically addressable by `identifier`
+ */
+export type ExampleEmployeeRecord = Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: 'active' | 'inactive' | 'purged';
+}>;
+export declare const ExampleEmployeeEmails: Readonly<{
+    readonly SharedProfessional: "shared.professional@example.org";
+}>;
+export declare const ExampleEmployeeRoles: Readonly<{
+    readonly Controller: "ISCO-08|1120";
+    readonly Doctor: "ISCO-08|2211";
+}>;
+export declare const EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE: ExampleEmployeeRecord;
+export declare const EXAMPLE_EMPLOYEE_DOCTOR_ACTIVE: ExampleEmployeeRecord;
+export declare const EXAMPLE_EMPLOYEE_DOCTOR_PURGED_HISTORICAL: ExampleEmployeeRecord;
+export declare const EXAMPLE_EMPLOYEE_DIRECTORY_RECORDS: readonly [Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: "active" | "inactive" | "purged";
+}>, Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: "active" | "inactive" | "purged";
+}>, Readonly<{
+    identifier: string;
+    email: string;
+    role: string;
+    status: "active" | "inactive" | "purged";
+}>];
+export declare function buildExampleEmployeeClaims(record: ExampleEmployeeRecord): Readonly<Record<string, string>>;

package/dist/examples/employee.js

@@ -0,0 +1,39 @@
+import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
+export const ExampleEmployeeEmails = Object.freeze({
+    SharedProfessional: 'shared.professional@example.org',
+});
+export const ExampleEmployeeRoles = Object.freeze({
+    Controller: 'ISCO-08|1120',
+    Doctor: 'ISCO-08|2211',
+});
+export const EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE = Object.freeze({
+    identifier: 'urn:uuid:employee-controller-active-001',
+    email: ExampleEmployeeEmails.SharedProfessional,
+    role: ExampleEmployeeRoles.Controller,
+    status: 'active',
+});
+export const EXAMPLE_EMPLOYEE_DOCTOR_ACTIVE = Object.freeze({
+    identifier: 'urn:uuid:employee-doctor-active-001',
+    email: ExampleEmployeeEmails.SharedProfessional,
+    role: ExampleEmployeeRoles.Doctor,
+    status: 'active',
+});
+export const EXAMPLE_EMPLOYEE_DOCTOR_PURGED_HISTORICAL = Object.freeze({
+    identifier: 'urn:uuid:employee-doctor-purged-000',
+    email: ExampleEmployeeEmails.SharedProfessional,
+    role: ExampleEmployeeRoles.Doctor,
+    status: 'purged',
+});
+export const EXAMPLE_EMPLOYEE_DIRECTORY_RECORDS = Object.freeze([
+    EXAMPLE_EMPLOYEE_CONTROLLER_ACTIVE,
+    EXAMPLE_EMPLOYEE_DOCTOR_ACTIVE,
+    EXAMPLE_EMPLOYEE_DOCTOR_PURGED_HISTORICAL,
+]);
+export function buildExampleEmployeeClaims(record) {
+    return Object.freeze({
+        '@context': 'org.schema',
+        [ClaimsPersonSchemaorg.identifier]: record.identifier,
+        [ClaimsPersonSchemaorg.email]: record.email,
+        [ClaimsPersonSchemaorg.hasOccupationalRoleValue]: record.role,
+    });
+}

package/dist/examples/index.d.ts

@@ -4,6 +4,7 @@ export * from './dataspace-discovery';
 export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';
+export * from './employee';
 export * from './related-person';
 export * from './consent-access';
 export * from './relationship-access';
@@ -11,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

@@ -4,6 +4,7 @@ export * from './dataspace-discovery.js';
 export * from './organization-controller.js';
 export * from './individual-controller.js';
 export * from './professional.js';
+export * from './employee.js';
 export * from './related-person.js';
 export * from './consent-access.js';
 export * from './relationship-access.js';
@@ -11,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
  */