gdc-common-utils-ts 1.14.14 → 1.15.0

package/README.md

@@ -27,7 +27,15 @@ 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)
+- [`docs/101-BUNDLE_EDITOR_READER.md`](docs/101-BUNDLE_EDITOR_READER.md)
 
 ## Install
 
@@ -148,12 +156,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 +185,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 +275,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 +344,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/bundle-editor.d.ts

@@ -0,0 +1,88 @@
+import { buildEmployeeBatchBundle, buildEmployeeBatchEntry, buildEmployeeSearchBundle, EmployeeBundleOperations } from './employee';
+export type BundleOperation = (typeof EmployeeBundleOperations)[keyof typeof EmployeeBundleOperations];
+export type BuiltEmployeeBatchEntry = ReturnType<typeof buildEmployeeBatchEntry> & {
+    fullUrl?: string;
+};
+/**
+ * Generic bundle editor with an employee adapter surface.
+ *
+ * Current scope:
+ * - one declared business operation per bundle
+ * - active-entry editing through generic claim helpers
+ * - employee convenience setters layered on the same active entry
+ *
+ * This editor lives in `common-utils` because it is runtime-neutral and can be
+ * consumed by frontend SDKs, backend SDKs, and backend services.
+ */
+export declare class BundleEditor {
+    private bundleOperation;
+    private readonly entries;
+    private activeEntryIndex;
+    /** Declares which business operation the bundle is assembling. */
+    setBundleOperation(operation: BundleOperation): this;
+    /** Returns the operation currently assigned to this bundle. */
+    getBundleOperation(): BundleOperation | null;
+    /**
+     * Opens one new active entry.
+     *
+     * If the current bundle operation needs an identifier and none is supplied,
+     * a canonical `urn:uuid:*` identifier is generated and aligned across
+     * `fullUrl`, `resource.id`, and `org.schema.Person.identifier`.
+     */
+    newEntry(resourceId?: string): this;
+    /** Reopens an existing entry by identifier or `fullUrl`. */
+    openEntry(resourceId: string): this;
+    /** Closes the current active entry while preserving it inside the bundle draft. */
+    doneEntry(): this;
+    /** Returns a cloned snapshot of the currently staged entries. */
+    getEntries(): readonly BuiltEmployeeBatchEntry[];
+    /**
+     * Builds the final bundle payload for the declared operation.
+     *
+     * `search` returns one canonical search bundle.
+     * `purge` returns a batch bundle whose entries are routed later to
+     * `Employee/_purge`.
+     * `create` and `disable` return canonical batch bundles.
+     */
+    build(): ReturnType<typeof buildEmployeeBatchBundle> | ReturnType<typeof buildEmployeeSearchBundle>;
+    /** Reads one claim from the active entry. */
+    getClaim(key: string): unknown;
+    /** Checks whether the active entry contains one claim key. */
+    hasClaim(key: string): boolean;
+    /** Writes one claim on the active entry. */
+    setClaim(key: string, value: unknown): this;
+    /** Appends one claim value on the active entry. */
+    addClaim(key: string, value: unknown): this;
+    /** Removes one claim from the active entry. */
+    removeClaim(key: string): this;
+    /**
+     * Sets the active entry identifier.
+     *
+     * When informed, the value is synchronized into `fullUrl`, `resource.id`,
+     * and the canonical identifier claim.
+     * Empty values remove the identifier from all three places.
+     */
+    setIdentifier(identifier?: string | null): this;
+    /** Reads the active entry identifier from claims, resource id, or fullUrl. */
+    getIdentifier(): string | undefined;
+    /** Ensures the active entry carries one canonical identifier. */
+    ensureIdentifier(): string;
+    /** Sets the active entry `fullUrl` explicitly. */
+    setFullUrl(fullUrl?: string | null): this;
+    /** Returns the active entry `fullUrl` when present. */
+    getFullUrl(): string | undefined;
+    /** Convenience employee setter for email. */
+    setEmail(email: string): this;
+    /** Convenience employee setter for occupational role. */
+    setRole(role: string): this;
+    /** Convenience employee setter for `worksFor`. */
+    setWorksFor(worksFor: string): this;
+    /** Convenience employee setter for `memberOf`. */
+    setMemberOf(memberOf: string): this;
+    /** Convenience employee setter for `memberOf.taxID`. */
+    setMemberOfOrgTaxId(taxId: string): this;
+    private requireBundleOperation;
+    private getRequiredActiveEntry;
+    private getActiveEntryClaims;
+    private getActiveOrSingleSearchClaims;
+}