gdc-common-utils-ts 1.14.15 → 1.16.0

package/README.md

@@ -35,6 +35,7 @@ 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
 

package/dist/utils/bundle-editor.d.ts

@@ -0,0 +1,134 @@
+import { buildEmployeeBatchEntry, buildEmployeePurgeBundle, buildEmployeeSearchBundle, EmployeeBundleOperations, EmployeeClaims, EmployeeResourceTypes } from './employee';
+export type BundleOperation = (typeof EmployeeBundleOperations)[keyof typeof EmployeeBundleOperations];
+export type AllowedResourceType = (typeof EmployeeResourceTypes)[keyof typeof EmployeeResourceTypes];
+export type BuiltBundleEntry = ReturnType<typeof buildEmployeeBatchEntry> & {
+    fullUrl?: string;
+};
+/**
+ * Generic bundle editor for FHIR-like bundle payloads assembled in memory.
+ *
+ * This class owns bundle-level concerns:
+ * - which business operation the bundle represents
+ * - which resource type the bundle allows
+ * - which entries belong to the bundle
+ * - when the final bundle is materialized through `build()`
+ *
+ * Resource-specific semantics belong to resource entry editors such as
+ * `EmployeeEntryEditor`.
+ */
+export declare class BundleEditor {
+    private bundleOperation;
+    private allowedResourceType;
+    private readonly entries;
+    /** Declares which business operation this bundle is staging. */
+    setBundleOperation(operation: BundleOperation): this;
+    /** Returns the current business operation assigned to the bundle. */
+    getBundleOperation(): BundleOperation | null;
+    /**
+     * Restricts the bundle to one resource type.
+     *
+     * For employee batch bundles this should be fixed to
+     * `EmployeeResourceTypes.employee` so the editor cannot mix unrelated
+     * resource kinds.
+     */
+    setAllowedResourceType(resourceType: AllowedResourceType): this;
+    /** Returns the bundle resource type restriction when already declared. */
+    getAllowedResourceType(): AllowedResourceType | null;
+    /**
+     * Opens one new entry and returns a generic entry editor for that slot.
+     *
+     * The entry editor can later expose resource-specific semantics through
+     * methods such as `asEmployee()`.
+     */
+    newEntry(resourceId?: string): BundleEntryEditor;
+    /** Reopens one existing entry by `resource.id` or `fullUrl`. */
+    openEntry(resourceIdOrFullUrl: string): BundleEntryEditor;
+    /** Returns cloned staged entries for inspection or debugging. */
+    getEntries(): readonly BuiltBundleEntry[];
+    /**
+     * Materializes the final bundle payload from the editor state.
+     *
+     * `build()` does not send, sign, or wrap the payload. It only returns the
+     * final bundle object for the declared operation and staged entries.
+     */
+    build(): ReturnType<typeof buildEmployeePurgeBundle> | ReturnType<typeof buildEmployeeSearchBundle>;
+    /** @internal */
+    getMutableEntry(entryIndex: number): BuiltBundleEntry;
+    private createEntryDraft;
+    private getSingleSearchClaims;
+    private requireBundleOperation;
+    private requireAllowedResourceType;
+}
+/**
+ * Generic editor for one staged bundle entry.
+ *
+ * This class only knows generic entry concerns such as:
+ * - resource id
+ * - fullUrl
+ * - meta claims
+ * - conversion to one resource-specific entry editor
+ */
+export declare class BundleEntryEditor {
+    protected readonly bundleEditor: BundleEditor;
+    protected readonly entryIndex: number;
+    constructor(bundleEditor: BundleEditor, entryIndex: number);
+    /** Opens the current entry as one employee-specific resource editor. */
+    asEmployee(): EmployeeEntryEditor;
+    /** Reads one claim from this entry. */
+    getClaim(key: string): unknown;
+    /** Checks whether this entry contains one claim key. */
+    hasClaim(key: string): boolean;
+    /** Writes one claim on this entry. */
+    setClaim(key: string, value: unknown): this;
+    /** Appends one claim value on this entry. */
+    addClaim(key: string, value: unknown): this;
+    /** Removes one claim from this entry. */
+    removeClaim(key: string): this;
+    /** Writes the staged entry `resource.id`. */
+    setResourceId(resourceId?: string | null): this;
+    /** Reads the staged entry `resource.id` when present. */
+    getResourceId(): string | undefined;
+    /** Writes the staged entry `fullUrl`. */
+    setFullUrl(fullUrl?: string | null): this;
+    /** Reads the staged entry `fullUrl` when present. */
+    getFullUrl(): string | undefined;
+    /** Returns control to the parent bundle editor. */
+    doneEntry(): BundleEditor;
+    protected getMutableEntry(): BuiltBundleEntry;
+    protected getClaims(): EmployeeClaims;
+}
+/**
+ * Employee-specific editor for one staged bundle entry.
+ *
+ * Use this class after `bundle.newEntry().asEmployee()` or
+ * `bundle.openEntry(...).asEmployee()`.
+ */
+export declare class EmployeeEntryEditor extends BundleEntryEditor {
+    /**
+     * Writes the canonical employee identifier.
+     *
+     * The identifier is synchronized across:
+     * - `entry.fullUrl`
+     * - `resource.id`
+     * - `org.schema.Person.identifier`
+     */
+    setIdentifier(identifier?: string | null): this;
+    /** Reads the canonical employee identifier from claims, resource id, or fullUrl. */
+    getIdentifier(): string | undefined;
+    /** Ensures the employee entry carries one canonical `urn:uuid:*` identifier. */
+    ensureIdentifier(): string;
+    /** Writes the canonical employee email claim on this entry. */
+    setEmail(email: string): this;
+    /** Reads the canonical employee email claim from this entry. */
+    getEmail(): string | undefined;
+    /** Writes the canonical employee occupational role claim on this entry. */
+    setRole(role: string): this;
+    /** Reads the canonical employee occupational role claim from this entry. */
+    getRole(): string | undefined;
+    /** Writes the canonical employee `worksFor` claim on this entry. */
+    setWorksFor(worksFor: string): this;
+    /** Writes the canonical employee `memberOf` claim on this entry. */
+    setMemberOf(memberOf: string): this;
+    /** Writes the canonical employee organization tax id claim on this entry. */
+    setMemberOfOrgTaxId(taxId: string): this;
+}

package/dist/utils/bundle-editor.js

@@ -0,0 +1,421 @@
+import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
+import { buildEmployeeBatchEntry, buildEmployeePurgeBundle, buildEmployeeSearchBundle, EmployeeBatchEntryTypes, EmployeeBundleMethods, EmployeeBundleOperations, EmployeeResourceTypes, } from './employee.js';
+function cloneEntry(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function cloneClaimValue(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    return value;
+}
+function normalizeOptionalIdentifier(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    const normalized = String(value).trim();
+    return normalized ? normalized : undefined;
+}
+function createCanonicalIdentifierUrn() {
+    const cryptoLike = globalThis;
+    const uuid = typeof cryptoLike.crypto?.randomUUID === 'function'
+        ? cryptoLike.crypto.randomUUID()
+        : `resource-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    return `urn:uuid:${uuid}`;
+}
+function resolveRequestMethodForOperation(operation) {
+    switch (operation) {
+        case EmployeeBundleOperations.disable:
+            return EmployeeBundleMethods.disable;
+        case EmployeeBundleOperations.search:
+        case EmployeeBundleOperations.create:
+        case EmployeeBundleOperations.purge:
+        default:
+            return EmployeeBundleMethods.create;
+    }
+}
+function resolveEntryTypeForOperation(operation) {
+    switch (operation) {
+        case EmployeeBundleOperations.disable:
+            return EmployeeBatchEntryTypes.disable;
+        case EmployeeBundleOperations.purge:
+            return EmployeeBatchEntryTypes.purge;
+        case EmployeeBundleOperations.search:
+            return EmployeeBatchEntryTypes.search;
+        case EmployeeBundleOperations.create:
+        default:
+            return EmployeeBatchEntryTypes.create;
+    }
+}
+/**
+ * Generic bundle editor for FHIR-like bundle payloads assembled in memory.
+ *
+ * This class owns bundle-level concerns:
+ * - which business operation the bundle represents
+ * - which resource type the bundle allows
+ * - which entries belong to the bundle
+ * - when the final bundle is materialized through `build()`
+ *
+ * Resource-specific semantics belong to resource entry editors such as
+ * `EmployeeEntryEditor`.
+ */
+export class BundleEditor {
+    bundleOperation = null;
+    allowedResourceType = null;
+    entries = [];
+    /** Declares which business operation this bundle is staging. */
+    setBundleOperation(operation) {
+        this.bundleOperation = operation;
+        return this;
+    }
+    /** Returns the current business operation assigned to the bundle. */
+    getBundleOperation() {
+        return this.bundleOperation;
+    }
+    /**
+     * Restricts the bundle to one resource type.
+     *
+     * For employee batch bundles this should be fixed to
+     * `EmployeeResourceTypes.employee` so the editor cannot mix unrelated
+     * resource kinds.
+     */
+    setAllowedResourceType(resourceType) {
+        this.allowedResourceType = resourceType;
+        return this;
+    }
+    /** Returns the bundle resource type restriction when already declared. */
+    getAllowedResourceType() {
+        return this.allowedResourceType;
+    }
+    /**
+     * Opens one new entry and returns a generic entry editor for that slot.
+     *
+     * The entry editor can later expose resource-specific semantics through
+     * methods such as `asEmployee()`.
+     */
+    newEntry(resourceId) {
+        const operation = this.requireBundleOperation();
+        const resourceType = this.requireAllowedResourceType();
+        const entry = this.createEntryDraft(operation, resourceType, resourceId);
+        this.entries.push(entry);
+        return new BundleEntryEditor(this, this.entries.length - 1);
+    }
+    /** Reopens one existing entry by `resource.id` or `fullUrl`. */
+    openEntry(resourceIdOrFullUrl) {
+        const normalizedIdentifier = normalizeOptionalIdentifier(resourceIdOrFullUrl);
+        if (!normalizedIdentifier) {
+            throw new Error('openEntry requires a non-empty resource identifier or fullUrl.');
+        }
+        const entryIndex = this.entries.findIndex((entry) => {
+            return normalizeOptionalIdentifier(entry.resource?.id) === normalizedIdentifier
+                || normalizeOptionalIdentifier(entry.fullUrl) === normalizedIdentifier;
+        });
+        if (entryIndex < 0) {
+            throw new Error(`openEntry could not find resource identifier or fullUrl: ${normalizedIdentifier}`);
+        }
+        return new BundleEntryEditor(this, entryIndex);
+    }
+    /** Returns cloned staged entries for inspection or debugging. */
+    getEntries() {
+        return this.entries.map((entry) => cloneEntry(entry));
+    }
+    /**
+     * Materializes the final bundle payload from the editor state.
+     *
+     * `build()` does not send, sign, or wrap the payload. It only returns the
+     * final bundle object for the declared operation and staged entries.
+     */
+    build() {
+        const operation = this.requireBundleOperation();
+        const resourceType = this.requireAllowedResourceType();
+        if (resourceType !== EmployeeResourceTypes.employee) {
+            throw new Error(`BundleEditor does not yet support build() for resource type: ${resourceType}`);
+        }
+        if (operation === EmployeeBundleOperations.search) {
+            return buildEmployeeSearchBundle({
+                claims: this.getSingleSearchClaims(),
+                resourceType,
+            });
+        }
+        if (operation === EmployeeBundleOperations.purge) {
+            return {
+                resourceType: EmployeeResourceTypes.bundle,
+                type: EmployeeResourceTypes.batch,
+                entry: this.entries.map((entry) => {
+                    const identifier = normalizeOptionalIdentifier(entry.resource?.meta?.claims?.[ClaimsPersonSchemaorg.identifier]
+                        || entry.resource?.id
+                        || entry.fullUrl);
+                    if (!identifier) {
+                        throw new Error('Every purge entry requires one canonical employee identifier.');
+                    }
+                    return buildEmployeePurgeBundle({
+                        identifier,
+                        resourceType,
+                    }).entry[0];
+                }),
+            };
+        }
+        return {
+            resourceType: EmployeeResourceTypes.bundle,
+            type: EmployeeResourceTypes.batch,
+            entry: this.entries.map((entry) => cloneEntry(entry)),
+        };
+    }
+    /** @internal */
+    getMutableEntry(entryIndex) {
+        if (!Number.isInteger(entryIndex) || entryIndex < 0 || entryIndex >= this.entries.length) {
+            throw new Error(`BundleEditor could not open entry index: ${entryIndex}`);
+        }
+        return this.entries[entryIndex];
+    }
+    createEntryDraft(operation, resourceType, resourceId) {
+        if (resourceType !== EmployeeResourceTypes.employee) {
+            throw new Error(`BundleEditor does not yet support newEntry() for resource type: ${resourceType}`);
+        }
+        const normalizedIdentifier = operation === EmployeeBundleOperations.search
+            ? normalizeOptionalIdentifier(resourceId)
+            : (normalizeOptionalIdentifier(resourceId) || createCanonicalIdentifierUrn());
+        const claims = {
+            '@context': 'org.schema',
+            ...(normalizedIdentifier ? { [ClaimsPersonSchemaorg.identifier]: normalizedIdentifier } : {}),
+        };
+        const entry = buildEmployeeBatchEntry({
+            type: resolveEntryTypeForOperation(operation),
+            method: resolveRequestMethodForOperation(operation),
+            resourceId: normalizedIdentifier,
+            resourceType,
+            claims,
+        });
+        if (normalizedIdentifier) {
+            entry.fullUrl = normalizedIdentifier;
+        }
+        return entry;
+    }
+    getSingleSearchClaims() {
+        if (this.entries.length === 0) {
+            return {};
+        }
+        if (this.entries.length > 1) {
+            throw new Error('Search bundles currently support one entry per bundle.');
+        }
+        const claims = this.entries[0].resource?.meta?.claims || {};
+        const searchClaims = {};
+        for (const [key, value] of Object.entries(claims)) {
+            if (value === undefined
+                || value === null
+                || typeof value === 'string'
+                || typeof value === 'number'
+                || typeof value === 'boolean') {
+                searchClaims[key] = value;
+            }
+        }
+        return searchClaims;
+    }
+    requireBundleOperation() {
+        if (!this.bundleOperation) {
+            throw new Error('BundleEditor requires setBundleOperation(...) before newEntry() or build().');
+        }
+        return this.bundleOperation;
+    }
+    requireAllowedResourceType() {
+        if (!this.allowedResourceType) {
+            throw new Error('BundleEditor requires setAllowedResourceType(...) before newEntry() or build().');
+        }
+        return this.allowedResourceType;
+    }
+}
+/**
+ * Generic editor for one staged bundle entry.
+ *
+ * This class only knows generic entry concerns such as:
+ * - resource id
+ * - fullUrl
+ * - meta claims
+ * - conversion to one resource-specific entry editor
+ */
+export class BundleEntryEditor {
+    bundleEditor;
+    entryIndex;
+    constructor(bundleEditor, entryIndex) {
+        this.bundleEditor = bundleEditor;
+        this.entryIndex = entryIndex;
+    }
+    /** Opens the current entry as one employee-specific resource editor. */
+    asEmployee() {
+        const entry = this.getMutableEntry();
+        if (entry.resource?.resourceType !== EmployeeResourceTypes.employee) {
+            throw new Error(`BundleEntryEditor cannot open this entry as Employee: ${String(entry.resource?.resourceType || '')}`);
+        }
+        return new EmployeeEntryEditor(this.bundleEditor, this.entryIndex);
+    }
+    /** Reads one claim from this entry. */
+    getClaim(key) {
+        return cloneClaimValue(this.getClaims()[String(key).trim()]);
+    }
+    /** Checks whether this entry contains one claim key. */
+    hasClaim(key) {
+        return Object.prototype.hasOwnProperty.call(this.getClaims(), String(key).trim());
+    }
+    /** Writes one claim on this entry. */
+    setClaim(key, value) {
+        const entry = this.getMutableEntry();
+        entry.resource = entry.resource || {
+            resourceType: this.bundleEditor.getAllowedResourceType() || EmployeeResourceTypes.employee,
+            meta: { claims: {} },
+        };
+        entry.resource.meta = entry.resource.meta || {};
+        entry.resource.meta.claims = {
+            ...(entry.resource.meta.claims || {}),
+            [String(key).trim()]: cloneClaimValue(value),
+        };
+        return this;
+    }
+    /** Appends one claim value on this entry. */
+    addClaim(key, value) {
+        const normalizedKey = String(key).trim();
+        const current = this.getClaim(normalizedKey);
+        if (current === undefined) {
+            return this.setClaim(normalizedKey, value);
+        }
+        if (Array.isArray(current)) {
+            return this.setClaim(normalizedKey, [...current, cloneClaimValue(value)]);
+        }
+        return this.setClaim(normalizedKey, [current, cloneClaimValue(value)]);
+    }
+    /** Removes one claim from this entry. */
+    removeClaim(key) {
+        const entry = this.getMutableEntry();
+        const claims = {
+            ...(entry.resource?.meta?.claims || {}),
+        };
+        delete claims[String(key).trim()];
+        entry.resource = entry.resource || {
+            resourceType: this.bundleEditor.getAllowedResourceType() || EmployeeResourceTypes.employee,
+            meta: { claims: {} },
+        };
+        entry.resource.meta = entry.resource.meta || {};
+        entry.resource.meta.claims = claims;
+        return this;
+    }
+    /** Writes the staged entry `resource.id`. */
+    setResourceId(resourceId) {
+        const entry = this.getMutableEntry();
+        const normalized = normalizeOptionalIdentifier(resourceId);
+        if (!normalized) {
+            delete entry.resource?.id;
+            return this;
+        }
+        entry.resource = entry.resource || {
+            resourceType: this.bundleEditor.getAllowedResourceType() || EmployeeResourceTypes.employee,
+            meta: { claims: {} },
+        };
+        entry.resource.id = normalized;
+        return this;
+    }
+    /** Reads the staged entry `resource.id` when present. */
+    getResourceId() {
+        return normalizeOptionalIdentifier(this.getMutableEntry().resource?.id);
+    }
+    /** Writes the staged entry `fullUrl`. */
+    setFullUrl(fullUrl) {
+        const entry = this.getMutableEntry();
+        const normalized = normalizeOptionalIdentifier(fullUrl);
+        if (!normalized) {
+            delete entry.fullUrl;
+            return this;
+        }
+        entry.fullUrl = normalized;
+        return this;
+    }
+    /** Reads the staged entry `fullUrl` when present. */
+    getFullUrl() {
+        return normalizeOptionalIdentifier(this.getMutableEntry().fullUrl);
+    }
+    /** Returns control to the parent bundle editor. */
+    doneEntry() {
+        return this.bundleEditor;
+    }
+    getMutableEntry() {
+        return this.bundleEditor.getMutableEntry(this.entryIndex);
+    }
+    getClaims() {
+        return {
+            ...(this.getMutableEntry().resource?.meta?.claims || {}),
+        };
+    }
+}
+/**
+ * Employee-specific editor for one staged bundle entry.
+ *
+ * Use this class after `bundle.newEntry().asEmployee()` or
+ * `bundle.openEntry(...).asEmployee()`.
+ */
+export class EmployeeEntryEditor extends BundleEntryEditor {
+    /**
+     * Writes the canonical employee identifier.
+     *
+     * The identifier is synchronized across:
+     * - `entry.fullUrl`
+     * - `resource.id`
+     * - `org.schema.Person.identifier`
+     */
+    setIdentifier(identifier) {
+        const normalized = normalizeOptionalIdentifier(identifier);
+        if (!normalized) {
+            this.removeClaim(ClaimsPersonSchemaorg.identifier);
+            this.setResourceId(undefined);
+            this.setFullUrl(undefined);
+            return this;
+        }
+        this.setClaim(ClaimsPersonSchemaorg.identifier, normalized);
+        this.setResourceId(normalized);
+        this.setFullUrl(normalized);
+        return this;
+    }
+    /** Reads the canonical employee identifier from claims, resource id, or fullUrl. */
+    getIdentifier() {
+        return normalizeOptionalIdentifier(this.getClaim(ClaimsPersonSchemaorg.identifier)
+            || this.getResourceId()
+            || this.getFullUrl());
+    }
+    /** Ensures the employee entry carries one canonical `urn:uuid:*` identifier. */
+    ensureIdentifier() {
+        const existing = this.getIdentifier();
+        if (existing) {
+            return existing;
+        }
+        const generated = createCanonicalIdentifierUrn();
+        this.setIdentifier(generated);
+        return generated;
+    }
+    /** Writes the canonical employee email claim on this entry. */
+    setEmail(email) {
+        return this.setClaim(ClaimsPersonSchemaorg.email, String(email).trim());
+    }
+    /** Reads the canonical employee email claim from this entry. */
+    getEmail() {
+        const email = this.getClaim(ClaimsPersonSchemaorg.email);
+        return typeof email === 'string' && email.trim() ? email.trim() : undefined;
+    }
+    /** Writes the canonical employee occupational role claim on this entry. */
+    setRole(role) {
+        return this.setClaim(ClaimsPersonSchemaorg.hasOccupationalRoleValue, String(role).trim());
+    }
+    /** Reads the canonical employee occupational role claim from this entry. */
+    getRole() {
+        const role = this.getClaim(ClaimsPersonSchemaorg.hasOccupationalRoleValue);
+        return typeof role === 'string' && role.trim() ? role.trim() : undefined;
+    }
+    /** Writes the canonical employee `worksFor` claim on this entry. */
+    setWorksFor(worksFor) {
+        return this.setClaim(ClaimsPersonSchemaorg.worksFor, String(worksFor).trim());
+    }
+    /** Writes the canonical employee `memberOf` claim on this entry. */
+    setMemberOf(memberOf) {
+        return this.setClaim(ClaimsPersonSchemaorg.memberOf, String(memberOf).trim());
+    }
+    /** Writes the canonical employee organization tax id claim on this entry. */
+    setMemberOfOrgTaxId(taxId) {
+        return this.setClaim(ClaimsPersonSchemaorg.memberOfOrgTaxId, String(taxId).trim());
+    }
+}

package/dist/utils/bundle-reader.d.ts

@@ -0,0 +1,34 @@
+export type BundleReaderEntry = Record<string, unknown>;
+/**
+ * Runtime-neutral reader for built or received FHIR-like bundles.
+ *
+ * The reader does not assume one business resource. It only exposes generic
+ * bundle navigation, per-entry response inspection, and aggregate counters.
+ */
+export declare class BundleReader {
+    private readonly bundle;
+    private activeEntryIndex;
+    constructor(bundle: Record<string, unknown>);
+    /** Returns the current bundle resource type when present. */
+    getResourceType(): string | undefined;
+    /** Returns the current FHIR bundle type when present. */
+    getBundleType(): string | undefined;
+    /** Returns cloned bundle entries. */
+    getEntries(): readonly BundleReaderEntry[];
+    /** Opens one entry by index. */
+    openEntry(index: number): this;
+    /** Returns the active entry response status when present. */
+    getEntryResponseStatus(): string | undefined;
+    /** Returns all active entry issue severities. */
+    getIssueSeverities(): string[];
+    /** Returns all active entry issue diagnostics strings. */
+    getIssueDiagnostics(): string[];
+    /** Returns the number of bundle entries. */
+    getTotalOperations(): number;
+    /** Returns the number of entries with one 2xx response status. */
+    getTotalSuccessfulOperations(): number;
+    /** Returns the number of entries without one 2xx response status. */
+    getTotalErrorOperations(): number;
+    private getRequiredActiveEntry;
+    private getActiveEntryIssues;
+}

package/dist/utils/bundle-reader.js

@@ -0,0 +1,88 @@
+function cloneEntry(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * Runtime-neutral reader for built or received FHIR-like bundles.
+ *
+ * The reader does not assume one business resource. It only exposes generic
+ * bundle navigation, per-entry response inspection, and aggregate counters.
+ */
+export class BundleReader {
+    bundle;
+    activeEntryIndex = null;
+    constructor(bundle) {
+        this.bundle = cloneEntry(bundle);
+    }
+    /** Returns the current bundle resource type when present. */
+    getResourceType() {
+        const resourceType = this.bundle.resourceType;
+        return typeof resourceType === 'string' && resourceType.trim() ? resourceType.trim() : undefined;
+    }
+    /** Returns the current FHIR bundle type when present. */
+    getBundleType() {
+        const bundleType = this.bundle.type;
+        return typeof bundleType === 'string' && bundleType.trim() ? bundleType.trim() : undefined;
+    }
+    /** Returns cloned bundle entries. */
+    getEntries() {
+        const entries = this.bundle.entry;
+        return Array.isArray(entries) ? entries.map((entry) => cloneEntry(entry)) : [];
+    }
+    /** Opens one entry by index. */
+    openEntry(index) {
+        const entries = this.getEntries();
+        if (!Number.isInteger(index) || index < 0 || index >= entries.length) {
+            throw new Error(`BundleReader could not open entry index: ${index}`);
+        }
+        this.activeEntryIndex = index;
+        return this;
+    }
+    /** Returns the active entry response status when present. */
+    getEntryResponseStatus() {
+        const entry = this.getRequiredActiveEntry();
+        const response = entry.response;
+        const status = response?.status;
+        return typeof status === 'string' && status.trim() ? status.trim() : undefined;
+    }
+    /** Returns all active entry issue severities. */
+    getIssueSeverities() {
+        return this.getActiveEntryIssues()
+            .map((issue) => issue.severity)
+            .filter((severity) => typeof severity === 'string' && severity.trim().length > 0);
+    }
+    /** Returns all active entry issue diagnostics strings. */
+    getIssueDiagnostics() {
+        return this.getActiveEntryIssues()
+            .map((issue) => issue.diagnostics)
+            .filter((diagnostics) => typeof diagnostics === 'string' && diagnostics.trim().length > 0);
+    }
+    /** Returns the number of bundle entries. */
+    getTotalOperations() {
+        return this.getEntries().length;
+    }
+    /** Returns the number of entries with one 2xx response status. */
+    getTotalSuccessfulOperations() {
+        return this.getEntries().filter((entry) => {
+            const response = entry.response;
+            return typeof response?.status === 'string' && /^2\d\d$/.test(response.status);
+        }).length;
+    }
+    /** Returns the number of entries without one 2xx response status. */
+    getTotalErrorOperations() {
+        return this.getTotalOperations() - this.getTotalSuccessfulOperations();
+    }
+    getRequiredActiveEntry() {
+        if (this.activeEntryIndex === null) {
+            throw new Error('BundleReader requires one active entry. Call openEntry(...) first.');
+        }
+        const entries = this.getEntries();
+        return entries[this.activeEntryIndex];
+    }
+    getActiveEntryIssues() {
+        const entry = this.getRequiredActiveEntry();
+        const response = entry.response;
+        const outcome = response?.outcome;
+        const issue = outcome?.issue;
+        return Array.isArray(issue) ? issue.filter((value) => !!value && typeof value === 'object') : [];
+    }
+}

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

@@ -38,6 +38,8 @@ export type AddContainedDocumentToActiveEntryInput = Readonly<{
  * - `Communication.content-attachment-data` is always derived from the
  *   in-memory bundle after each committed update.
  * - saving can release active entry memory via `saveAndReleaseActiveEntry()`.
+ * - consent onboarding should prefer semantic helpers first, but this session
+ *   also exposes direct claim-level editing on the selected active entry.
  */
 export declare class CommunicationAttachedBundleSession {
     private communicationClaims;
@@ -53,6 +55,16 @@ export declare class CommunicationAttachedBundleSession {
     getActiveEntryIndex(): number | null;
     /** Returns a deep copy of the active entry when selected. */
     getActiveEntry(): BundleEntry | null;
+    /** Returns one claim from the currently selected active entry. */
+    getActiveEntryClaim(key: string): unknown;
+    /** Returns whether the currently selected active entry carries one claim key. */
+    hasActiveEntryClaim(key: string): boolean;
+    /** Sets one claim on the currently selected active entry and syncs the bundle attachment. */
+    setActiveEntryClaim(key: string, value: unknown): this;
+    /** Appends one claim value on the currently selected active entry and syncs the bundle attachment. */
+    addActiveEntryClaim(key: string, value: unknown): this;
+    /** Removes one claim from the currently selected active entry and syncs the bundle attachment. */
+    removeActiveEntryClaim(key: string): this;
     /** Selects an active entry by index or fullUrl. */
     selectActiveEntry(selection: ActiveEntrySelection): this;
     /** Clears active entry selection from memory. */
@@ -164,6 +176,8 @@ export declare class CommunicationAttachedBundleSession {
      * Resolves the entry URL (`fullUrl`) for a given entry/resource identifier.
      */
     getEntryUrl(entryId: string): string | undefined;
+    private getRequiredActiveEntry;
+    private getRequiredActiveEntryClaims;
     private decodeBundleFromClaims;
     private syncAttachmentFromBundle;
     private resolveCurrentSubject;

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

@@ -18,6 +18,8 @@ import { MedicationStatementClaim, } from '../models/interoperable-claims/medica
  * - `Communication.content-attachment-data` is always derived from the
  *   in-memory bundle after each committed update.
  * - saving can release active entry memory via `saveAndReleaseActiveEntry()`.
+ * - consent onboarding should prefer semantic helpers first, but this session
+ *   also exposes direct claim-level editing on the selected active entry.
  */
 export class CommunicationAttachedBundleSession {
     communicationClaims;
@@ -55,6 +57,70 @@ export class CommunicationAttachedBundleSession {
         }
         return cloneEntry(this.bundleInMemory.data[this.activeEntryIndex]);
     }
+    /** Returns one claim from the currently selected active entry. */
+    getActiveEntryClaim(key) {
+        const claims = this.getRequiredActiveEntryClaims();
+        return cloneUnknownValue(claims[key]);
+    }
+    /** Returns whether the currently selected active entry carries one claim key. */
+    hasActiveEntryClaim(key) {
+        const claims = this.getRequiredActiveEntryClaims();
+        return Object.prototype.hasOwnProperty.call(claims, key);
+    }
+    /** Sets one claim on the currently selected active entry and syncs the bundle attachment. */
+    setActiveEntryClaim(key, value) {
+        const current = cloneEntry(this.getRequiredActiveEntry());
+        const resource = ensureEntryResource(current, this.mode);
+        resource.meta = resource.meta || {};
+        resource.meta.claims = {
+            ...(resource.meta.claims || {}),
+            [String(key).trim()]: cloneUnknownValue(value),
+        };
+        current.resource = resource;
+        this.bundleInMemory.data[this.activeEntryIndex] = current;
+        this.syncAttachmentFromBundle();
+        return this;
+    }
+    /** Appends one claim value on the currently selected active entry and syncs the bundle attachment. */
+    addActiveEntryClaim(key, value) {
+        const current = cloneEntry(this.getRequiredActiveEntry());
+        const resource = ensureEntryResource(current, this.mode);
+        resource.meta = resource.meta || {};
+        const claims = {
+            ...(resource.meta.claims || {}),
+        };
+        const normalizedKey = String(key).trim();
+        const currentValue = claims[normalizedKey];
+        if (currentValue === undefined) {
+            claims[normalizedKey] = cloneUnknownValue(value);
+        }
+        else if (Array.isArray(currentValue)) {
+            claims[normalizedKey] = [...currentValue, cloneUnknownValue(value)];
+        }
+        else {
+            claims[normalizedKey] = [currentValue, cloneUnknownValue(value)];
+        }
+        resource.meta.claims = claims;
+        current.resource = resource;
+        this.bundleInMemory.data[this.activeEntryIndex] = current;
+        this.syncAttachmentFromBundle();
+        return this;
+    }
+    /** Removes one claim from the currently selected active entry and syncs the bundle attachment. */
+    removeActiveEntryClaim(key) {
+        const current = cloneEntry(this.getRequiredActiveEntry());
+        const resource = ensureEntryResource(current, this.mode);
+        resource.meta = resource.meta || {};
+        const claims = {
+            ...(resource.meta.claims || {}),
+        };
+        delete claims[String(key).trim()];
+        resource.meta.claims = claims;
+        current.resource = resource;
+        this.bundleInMemory.data[this.activeEntryIndex] = current;
+        this.syncAttachmentFromBundle();
+        return this;
+    }
     /** Selects an active entry by index or fullUrl. */
     selectActiveEntry(selection) {
         if (typeof selection.index === 'number') {
@@ -297,6 +363,20 @@ export class CommunicationAttachedBundleSession {
         const query = new BundleQuery(this.bundleInMemory);
         return query.getEntryUrl(entryId);
     }
+    getRequiredActiveEntry() {
+        if (this.activeEntryIndex === null) {
+            throw new Error('No active entry selected.');
+        }
+        return this.bundleInMemory.data[this.activeEntryIndex];
+    }
+    getRequiredActiveEntryClaims() {
+        const current = cloneEntry(this.getRequiredActiveEntry());
+        const resource = ensureEntryResource(current, this.mode);
+        resource.meta = resource.meta || {};
+        return {
+            ...(resource.meta.claims || {}),
+        };
+    }
     decodeBundleFromClaims(claims) {
         const encoded = asTrimmedString(claims[CommunicationClaim.ContentAttachmentData]);
         if (!encoded) {
@@ -495,6 +575,12 @@ function cloneBundle(bundle) {
 function cloneEntry(entry) {
     return JSON.parse(JSON.stringify(entry));
 }
+function cloneUnknownValue(value) {
+    if (value === undefined) {
+        return value;
+    }
+    return JSON.parse(JSON.stringify(value));
+}
 function asTrimmedString(value) {
     if (value === undefined || value === null) {
         return '';

package/dist/utils/employee-editor.d.ts

@@ -0,0 +1,24 @@
+import { BundleEditor } from './bundle-editor';
+/**
+ * High-level employee adapter on top of the shared `BundleEditor`.
+ *
+ * Use this class when the active bundle entry is known to represent one
+ * employee resource and callers should work with employee semantics instead of
+ * raw claim keys.
+ */
+export declare class EmployeeEditor extends BundleEditor {
+    /** Writes the canonical employee email claim on the active entry. */
+    setEmail(email: string): this;
+    /** Reads the canonical employee email claim from the active entry. */
+    getEmail(): string | undefined;
+    /** Writes the canonical employee occupational role claim on the active entry. */
+    setRole(role: string): this;
+    /** Reads the canonical employee occupational role claim from the active entry. */
+    getRole(): string | undefined;
+    /** Writes the canonical employee `worksFor` claim on the active entry. */
+    setWorksFor(worksFor: string): this;
+    /** Writes the canonical employee `memberOf` claim on the active entry. */
+    setMemberOf(memberOf: string): this;
+    /** Writes the canonical employee organization tax id claim on the active entry. */
+    setMemberOfOrgTaxId(taxId: string): this;
+}

package/dist/utils/employee-editor.js

@@ -0,0 +1,41 @@
+import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
+import { BundleEditor } from './bundle-editor.js';
+/**
+ * High-level employee adapter on top of the shared `BundleEditor`.
+ *
+ * Use this class when the active bundle entry is known to represent one
+ * employee resource and callers should work with employee semantics instead of
+ * raw claim keys.
+ */
+export class EmployeeEditor extends BundleEditor {
+    /** Writes the canonical employee email claim on the active entry. */
+    setEmail(email) {
+        return this.setClaim(ClaimsPersonSchemaorg.email, String(email).trim());
+    }
+    /** Reads the canonical employee email claim from the active entry. */
+    getEmail() {
+        const email = this.getClaim(ClaimsPersonSchemaorg.email);
+        return typeof email === 'string' && email.trim() ? email.trim() : undefined;
+    }
+    /** Writes the canonical employee occupational role claim on the active entry. */
+    setRole(role) {
+        return this.setClaim(ClaimsPersonSchemaorg.hasOccupationalRoleValue, String(role).trim());
+    }
+    /** Reads the canonical employee occupational role claim from the active entry. */
+    getRole() {
+        const role = this.getClaim(ClaimsPersonSchemaorg.hasOccupationalRoleValue);
+        return typeof role === 'string' && role.trim() ? role.trim() : undefined;
+    }
+    /** Writes the canonical employee `worksFor` claim on the active entry. */
+    setWorksFor(worksFor) {
+        return this.setClaim(ClaimsPersonSchemaorg.worksFor, String(worksFor).trim());
+    }
+    /** Writes the canonical employee `memberOf` claim on the active entry. */
+    setMemberOf(memberOf) {
+        return this.setClaim(ClaimsPersonSchemaorg.memberOf, String(memberOf).trim());
+    }
+    /** Writes the canonical employee organization tax id claim on the active entry. */
+    setMemberOfOrgTaxId(taxId) {
+        return this.setClaim(ClaimsPersonSchemaorg.memberOfOrgTaxId, String(taxId).trim());
+    }
+}

package/dist/utils/employee.d.ts

@@ -21,12 +21,45 @@ export type EmployeeBatchEntryInput = Readonly<{
 export type EmployeeBatchBundleInput = Readonly<{
     entries: readonly EmployeeBatchEntryInput[];
 }>;
+export type EmployeePurgeBundleInput = Readonly<{
+    identifier: string;
+    resourceId?: string;
+    resourceType?: 'Employee';
+    requestType?: (typeof EmployeeBatchEntryTypes)['purge'];
+}>;
 export type EmployeeSearchBundleInput = Readonly<{
     claims?: Record<string, EmployeeSearchValue | undefined>;
     method?: 'GET' | 'POST';
     encoding?: SearchRequestEncoding;
     resourceType?: 'Employee';
 }>;
+export declare const EmployeeBundleOperations: Readonly<{
+    readonly create: "create";
+    readonly search: "search";
+    readonly disable: "disable";
+    readonly purge: "purge";
+}>;
+export declare const EmployeeBundleMethods: Readonly<{
+    readonly create: "POST";
+    readonly search: "POST";
+    readonly disable: "DELETE";
+    readonly purge: "POST";
+}>;
+export declare const EmployeeBundleRoutes: Readonly<{
+    readonly search: "Employee/_search";
+}>;
+export declare const EmployeeResourceTypes: Readonly<{
+    readonly employee: "Employee";
+    readonly bundle: "Bundle";
+    readonly batch: "batch";
+    readonly parameters: "Parameters";
+}>;
+export declare const EmployeeBatchEntryTypes: Readonly<{
+    readonly create: "Employee-create-request-v1.0";
+    readonly disable: "Employee-disable-request-v1.0";
+    readonly search: "Employee-search-request-v1.0";
+    readonly purge: "Employee-purge-request-v1.0";
+}>;
 /**
  * Builds canonical `org.schema.Person.*` employee claims from semantic input.
  */
@@ -60,6 +93,19 @@ export declare function buildEmployeeBatchBundle(input: EmployeeBatchBundleInput
     type: 'batch';
     entry: Array<ReturnType<typeof buildEmployeeBatchEntry>>;
 };
+/**
+ * Builds the canonical employee purge batch bundle.
+ *
+ * Purge is a terminal lifecycle operation routed to the explicit
+ * `Employee/_purge` endpoint by runtime layers. The bundle selector should be
+ * one concrete employee identity, therefore this helper keeps the payload
+ * focused on the canonical employee identifier.
+ */
+export declare function buildEmployeePurgeBundle(input: EmployeePurgeBundleInput): {
+    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

@@ -1,5 +1,32 @@
 import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
 import { buildFhirParametersResourceFromSearchParams, buildSearchQueryString, } from './fhir-search.js';
+export const EmployeeBundleOperations = Object.freeze({
+    create: 'create',
+    search: 'search',
+    disable: 'disable',
+    purge: 'purge',
+});
+export const EmployeeBundleMethods = Object.freeze({
+    create: 'POST',
+    search: 'POST',
+    disable: 'DELETE',
+    purge: 'POST',
+});
+export const EmployeeBundleRoutes = Object.freeze({
+    search: 'Employee/_search',
+});
+export const EmployeeResourceTypes = Object.freeze({
+    employee: 'Employee',
+    bundle: 'Bundle',
+    batch: 'batch',
+    parameters: 'Parameters',
+});
+export const EmployeeBatchEntryTypes = Object.freeze({
+    create: 'Employee-create-request-v1.0',
+    disable: 'Employee-disable-request-v1.0',
+    search: 'Employee-search-request-v1.0',
+    purge: 'Employee-purge-request-v1.0',
+});
 function cloneClaims(claims) {
     return { ...(claims || {}) };
 }
@@ -15,15 +42,15 @@ function normalizeEmployeeSearchClaims(claims) {
 function inferEmployeeEntryType(method) {
     switch (method) {
         case 'DELETE':
-            return 'Employee-delete-request-v1.0';
+            return EmployeeBatchEntryTypes.disable;
         case 'PUT':
         case 'PATCH':
             return 'Employee-update-request-v1.0';
         case 'GET':
-            return 'Employee-search-request-v1.0';
+            return EmployeeBatchEntryTypes.search;
         case 'POST':
         default:
-            return 'Employee-create-request-v1.0';
+            return EmployeeBatchEntryTypes.create;
     }
 }
 /**
@@ -85,6 +112,28 @@ export function buildEmployeeBatchBundle(input) {
         entry: [...input.entries].map((entry) => buildEmployeeBatchEntry(entry)),
     };
 }
+/**
+ * Builds the canonical employee purge batch bundle.
+ *
+ * Purge is a terminal lifecycle operation routed to the explicit
+ * `Employee/_purge` endpoint by runtime layers. The bundle selector should be
+ * one concrete employee identity, therefore this helper keeps the payload
+ * focused on the canonical employee identifier.
+ */
+export function buildEmployeePurgeBundle(input) {
+    const identifier = input.identifier.trim();
+    return buildEmployeeBatchBundle({
+        entries: [
+            {
+                type: input.requestType || EmployeeBatchEntryTypes.purge,
+                method: EmployeeBundleMethods.purge,
+                resourceId: input.resourceId || identifier,
+                resourceType: input.resourceType,
+                claims: buildEmployeeClaims({ identifier }),
+            },
+        ],
+    });
+}
 /**
  * Builds the legacy query-string employee search target kept for compatibility
  * with older `_search` wrappers.
@@ -103,7 +152,7 @@ export function buildEmployeeSearchQuery(input = {}) {
 export function buildEmployeeSearchBundle(input = {}) {
     const resourceType = input.resourceType || 'Employee';
     const claims = normalizeEmployeeSearchClaims(input.claims);
-    const method = input.method || (input.encoding === 'get-query' ? 'GET' : 'POST');
+    const method = input.method || (input.encoding === 'get-query' ? 'GET' : EmployeeBundleMethods.search);
     if (method === 'GET') {
         return {
             resourceType: 'Bundle',
@@ -124,8 +173,8 @@ export function buildEmployeeSearchBundle(input = {}) {
         entry: [
             {
                 request: {
-                    method: 'POST',
-                    url: `${resourceType}/_search`,
+                    method: EmployeeBundleMethods.search,
+                    url: EmployeeBundleRoutes.search,
                 },
                 resource: buildFhirParametersResourceFromSearchParams(claims),
             },

package/dist/utils/index.d.ts

@@ -3,6 +3,8 @@ export * from './activation-policy';
 export * from './base-convert';
 export * from './baseN';
 export * from './bundle';
+export * from './bundle-editor';
+export * from './bundle-reader';
 export * from './bundle-query';
 export * from '../claims';
 export * from './content';

package/dist/utils/index.js

@@ -3,6 +3,8 @@ export * from './activation-policy.js';
 export * from './base-convert.js';
 export * from './baseN.js';
 export * from './bundle.js';
+export * from './bundle-editor.js';
+export * from './bundle-reader.js';
 export * from './bundle-query.js';
 export * from '../claims/index.js';
 export * from './content.js';

package/package.json

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