gdc-common-utils-ts 1.14.13 → 1.14.15

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/communication-bundle-document-request.d.ts

@@ -1,5 +1,6 @@
 import { HealthcareDocumentTypes } from '../constants/healthcare';
 import type { ParameterData } from '../models/params';
+import { FhirParametersResource } from './fhir-search';
 export declare const BundleDocumentRequesterKinds: Readonly<{
     readonly Controller: "controller";
     readonly Employee: "employee";
@@ -140,6 +141,11 @@ export declare function createSummaryOperationRequestParameters(subjectIdOrInput
  * path currently stored in `Communication.content-reference`.
  */
 export declare function createSummaryOperationRequestReferencePath(parameters: ReadonlyArray<ParameterData>): string;
+/**
+ * Builds the preferred FHIR `Parameters` body for the same semantic summary
+ * search represented by `createSummaryOperationRequestReferencePath(...)`.
+ */
+export declare function createSummaryOperationRequestParametersResource(parameters: ReadonlyArray<ParameterData>): FhirParametersResource;
 /**
  * Resolves the full runtime URL to call GW CORE from the provider sector DID
  * and the generated relative search path.

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

@@ -3,6 +3,7 @@ import { CommunicationCategoryCodes } from '../constants/communication.js';
 import { DocumentTypeLoincOntology, HealthcareDocumentTypes } from '../constants/healthcare.js';
 import { parseActorFromSub } from './actor.js';
 import { getBaseUrlFromDidWeb } from './did.js';
+import { buildFhirParametersResourceFromParameterData } from './fhir-search.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 import { transformCommunicationClaimsToResourceFhirR4 } from './communication-fhir-r4.js';
 export const BundleDocumentRequesterKinds = Object.freeze({
@@ -260,6 +261,13 @@ export function createSummaryOperationRequestReferencePath(parameters) {
     }
     return `individual/org.hl7.fhir.r4/Bundle/_search?${params.filter(Boolean).join('&')}`;
 }
+/**
+ * Builds the preferred FHIR `Parameters` body for the same semantic summary
+ * search represented by `createSummaryOperationRequestReferencePath(...)`.
+ */
+export function createSummaryOperationRequestParametersResource(parameters) {
+    return buildFhirParametersResourceFromParameterData(parameters);
+}
 /**
  * Resolves the full runtime URL to call GW CORE from the provider sector DID
  * and the generated relative search path.

package/dist/utils/employee.d.ts

@@ -0,0 +1,87 @@
+import { SearchParameterPrimitive, SearchRequestEncoding } from './fhir-search';
+export type EmployeeClaims = Record<string, unknown>;
+export type EmployeeSearchValue = SearchParameterPrimitive;
+export type EmployeeDraftInput = Readonly<{
+    identifier?: string;
+    email?: string;
+    role?: string;
+    worksFor?: string;
+    memberOf?: string;
+    memberOfOrgTaxId?: string;
+    additionalClaims?: EmployeeClaims;
+}>;
+export type EmployeeBatchMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type EmployeeBatchEntryInput = Readonly<{
+    method: EmployeeBatchMethod;
+    claims: EmployeeClaims;
+    resourceId?: string;
+    resourceType?: 'Employee';
+    type?: string;
+}>;
+export type EmployeeBatchBundleInput = Readonly<{
+    entries: readonly EmployeeBatchEntryInput[];
+}>;
+export type EmployeeSearchBundleInput = Readonly<{
+    claims?: Record<string, EmployeeSearchValue | undefined>;
+    method?: 'GET' | 'POST';
+    encoding?: SearchRequestEncoding;
+    resourceType?: 'Employee';
+}>;
+/**
+ * Builds canonical `org.schema.Person.*` employee claims from semantic input.
+ */
+export declare function buildEmployeeClaims(input: EmployeeDraftInput): EmployeeClaims;
+/**
+ * Builds a claims-first employee batch entry from the minimum semantic input.
+ *
+ * Callers only provide the operation method, employee claims, and optional
+ * resource id. The helper places claims in the canonical `resource.meta.claims`
+ * location and infers the business `type` internally.
+ */
+export declare function buildEmployeeBatchEntry(input: EmployeeBatchEntryInput): {
+    type: string;
+    request: {
+        method: EmployeeBatchMethod;
+    };
+    resource: {
+        resourceType: 'Employee';
+        id?: string;
+        meta: {
+            claims: EmployeeClaims;
+        };
+    };
+};
+/**
+ * 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.
+ */
+export declare function buildEmployeeSearchQuery(input?: EmployeeSearchBundleInput): string;
+/**
+ * Builds a canonical employee search bundle.
+ *
+ * Defaults to `POST + Parameters`. Set `method` or `encoding` to legacy GET
+ * only when talking to older search consumers.
+ */
+export declare function buildEmployeeSearchBundle(input?: EmployeeSearchBundleInput): {
+    resourceType: 'Bundle';
+    type: 'batch';
+    entry: Array<{
+        request: {
+            method: 'GET' | 'POST';
+            url: string;
+        };
+        resource?: {
+            resourceType: 'Parameters';
+            parameter: Array<Record<string, unknown>>;
+        };
+    }>;
+};