gdc-common-utils-ts 1.15.0 → 1.16.0

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

@@ -1,88 +1,134 @@
-import { buildEmployeeBatchBundle, buildEmployeeBatchEntry, buildEmployeeSearchBundle, EmployeeBundleOperations } from './employee';
+import { buildEmployeeBatchEntry, buildEmployeePurgeBundle, buildEmployeeSearchBundle, EmployeeBundleOperations, EmployeeClaims, EmployeeResourceTypes } from './employee';
 export type BundleOperation = (typeof EmployeeBundleOperations)[keyof typeof EmployeeBundleOperations];
-export type BuiltEmployeeBatchEntry = ReturnType<typeof buildEmployeeBatchEntry> & {
+export type AllowedResourceType = (typeof EmployeeResourceTypes)[keyof typeof EmployeeResourceTypes];
+export type BuiltBundleEntry = ReturnType<typeof buildEmployeeBatchEntry> & {
     fullUrl?: string;
 };
 /**
- * Generic bundle editor with an employee adapter surface.
+ * Generic bundle editor for FHIR-like bundle payloads assembled in memory.
  *
- * 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 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()`
  *
- * This editor lives in `common-utils` because it is runtime-neutral and can be
- * consumed by frontend SDKs, backend SDKs, and backend services.
+ * Resource-specific semantics belong to resource entry editors such as
+ * `EmployeeEntryEditor`.
  */
 export declare class BundleEditor {
     private bundleOperation;
+    private allowedResourceType;
     private readonly entries;
-    private activeEntryIndex;
-    /** Declares which business operation the bundle is assembling. */
+    /** Declares which business operation this bundle is staging. */
     setBundleOperation(operation: BundleOperation): this;
-    /** Returns the operation currently assigned to this bundle. */
+    /** Returns the current business operation assigned to the bundle. */
     getBundleOperation(): BundleOperation | null;
     /**
-     * Opens one new active entry.
+     * Restricts the bundle to one resource type.
      *
-     * 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`.
+     * For employee batch bundles this should be fixed to
+     * `EmployeeResourceTypes.employee` so the editor cannot mix unrelated
+     * resource kinds.
      */
-    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[];
+    setAllowedResourceType(resourceType: AllowedResourceType): this;
+    /** Returns the bundle resource type restriction when already declared. */
+    getAllowedResourceType(): AllowedResourceType | null;
     /**
-     * Builds the final bundle payload for the declared operation.
+     * Opens one new entry and returns a generic entry editor for that slot.
      *
-     * `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.
+     * The entry editor can later expose resource-specific semantics through
+     * methods such as `asEmployee()`.
      */
-    build(): ReturnType<typeof buildEmployeeBatchBundle> | ReturnType<typeof buildEmployeeSearchBundle>;
-    /** Reads one claim from the active entry. */
+    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 the active entry contains one claim key. */
+    /** Checks whether this entry contains one claim key. */
     hasClaim(key: string): boolean;
-    /** Writes one claim on the active entry. */
+    /** Writes one claim on this entry. */
     setClaim(key: string, value: unknown): this;
-    /** Appends one claim value on the active entry. */
+    /** Appends one claim value on this entry. */
     addClaim(key: string, value: unknown): this;
-    /** Removes one claim from the active entry. */
+    /** 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 {
     /**
-     * Sets the active entry identifier.
+     * Writes the canonical employee 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.
+     * The identifier is synchronized across:
+     * - `entry.fullUrl`
+     * - `resource.id`
+     * - `org.schema.Person.identifier`
      */
     setIdentifier(identifier?: string | null): this;
-    /** Reads the active entry identifier from claims, resource id, or fullUrl. */
+    /** Reads the canonical employee identifier from claims, resource id, or fullUrl. */
     getIdentifier(): string | undefined;
-    /** Ensures the active entry carries one canonical identifier. */
+    /** Ensures the employee entry carries one canonical `urn:uuid:*` 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. */
+    /** Writes the canonical employee email claim on this entry. */
     setEmail(email: string): this;
-    /** Convenience employee setter for occupational role. */
+    /** 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;
-    /** Convenience employee setter for `worksFor`. */
+    /** 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;
-    /** Convenience employee setter for `memberOf`. */
+    /** Writes the canonical employee `memberOf` claim on this entry. */
     setMemberOf(memberOf: string): this;
-    /** Convenience employee setter for `memberOf.taxID`. */
+    /** Writes the canonical employee organization tax id claim on this entry. */
     setMemberOfOrgTaxId(taxId: string): this;
-    private requireBundleOperation;
-    private getRequiredActiveEntry;
-    private getActiveEntryClaims;
-    private getActiveOrSingleSearchClaims;
 }

package/dist/utils/bundle-editor.js

@@ -1,7 +1,7 @@
 import { ClaimsPersonSchemaorg } from '../constants/schemaorg.js';
-import { EmployeeBatchEntryTypes, buildEmployeeBatchEntry, buildEmployeeClaims, buildEmployeePurgeBundle, buildEmployeeSearchBundle, EmployeeBundleMethods, EmployeeBundleOperations, } from './employee.js';
-function cloneEntry(entry) {
-    return JSON.parse(JSON.stringify(entry));
+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)) {
@@ -16,20 +16,20 @@ function normalizeOptionalIdentifier(value) {
     const normalized = String(value).trim();
     return normalized ? normalized : undefined;
 }
-function createEmployeeIdentifierUrn() {
+function createCanonicalIdentifierUrn() {
     const cryptoLike = globalThis;
     const uuid = typeof cryptoLike.crypto?.randomUUID === 'function'
         ? cryptoLike.crypto.randomUUID()
-        : `employee-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        : `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:
-        case EmployeeBundleOperations.search:
         default:
             return EmployeeBundleMethods.create;
     }
@@ -48,129 +48,221 @@ function resolveEntryTypeForOperation(operation) {
     }
 }
 /**
- * Generic bundle editor with an employee adapter surface.
+ * Generic bundle editor for FHIR-like bundle payloads assembled in memory.
  *
- * 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 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()`
  *
- * This editor lives in `common-utils` because it is runtime-neutral and can be
- * consumed by frontend SDKs, backend SDKs, and backend services.
+ * Resource-specific semantics belong to resource entry editors such as
+ * `EmployeeEntryEditor`.
  */
 export class BundleEditor {
     bundleOperation = null;
+    allowedResourceType = null;
     entries = [];
-    activeEntryIndex = null;
-    /** Declares which business operation the bundle is assembling. */
+    /** Declares which business operation this bundle is staging. */
     setBundleOperation(operation) {
         this.bundleOperation = operation;
         return this;
     }
-    /** Returns the operation currently assigned to this bundle. */
+    /** Returns the current business operation assigned to the bundle. */
     getBundleOperation() {
         return this.bundleOperation;
     }
     /**
-     * Opens one new active entry.
+     * 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.
      *
-     * 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`.
+     * The entry editor can later expose resource-specific semantics through
+     * methods such as `asEmployee()`.
      */
     newEntry(resourceId) {
         const operation = this.requireBundleOperation();
-        const normalizedIdentifier = operation === EmployeeBundleOperations.search
-            ? normalizeOptionalIdentifier(resourceId)
-            : (normalizeOptionalIdentifier(resourceId) || createEmployeeIdentifierUrn());
-        const claims = normalizedIdentifier
-            ? buildEmployeeClaims({ identifier: normalizedIdentifier })
-            : buildEmployeeClaims({});
-        const entry = buildEmployeeBatchEntry({
-            type: resolveEntryTypeForOperation(operation),
-            method: resolveRequestMethodForOperation(operation),
-            resourceId: normalizedIdentifier,
-            claims,
-        });
-        if (normalizedIdentifier) {
-            entry.fullUrl = normalizedIdentifier;
-        }
+        const resourceType = this.requireAllowedResourceType();
+        const entry = this.createEntryDraft(operation, resourceType, resourceId);
         this.entries.push(entry);
-        this.activeEntryIndex = this.entries.length - 1;
-        return this;
+        return new BundleEntryEditor(this, this.entries.length - 1);
     }
-    /** Reopens an existing entry by identifier or `fullUrl`. */
-    openEntry(resourceId) {
-        const normalizedIdentifier = normalizeOptionalIdentifier(resourceId);
+    /** 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.');
+            throw new Error('openEntry requires a non-empty resource identifier or fullUrl.');
         }
-        const nextIndex = this.entries.findIndex((entry) => {
-            const claims = entry.resource?.meta?.claims || {};
+        const entryIndex = this.entries.findIndex((entry) => {
             return normalizeOptionalIdentifier(entry.resource?.id) === normalizedIdentifier
-                || normalizeOptionalIdentifier(entry.fullUrl) === normalizedIdentifier
-                || normalizeOptionalIdentifier(claims[ClaimsPersonSchemaorg.identifier]) === normalizedIdentifier;
+                || normalizeOptionalIdentifier(entry.fullUrl) === normalizedIdentifier;
         });
-        if (nextIndex < 0) {
-            throw new Error(`openEntry could not find resource identifier: ${normalizedIdentifier}`);
+        if (entryIndex < 0) {
+            throw new Error(`openEntry could not find resource identifier or fullUrl: ${normalizedIdentifier}`);
         }
-        this.activeEntryIndex = nextIndex;
-        return this;
+        return new BundleEntryEditor(this, entryIndex);
     }
-    /** Closes the current active entry while preserving it inside the bundle draft. */
-    doneEntry() {
-        this.activeEntryIndex = null;
-        return this;
-    }
-    /** Returns a cloned snapshot of the currently staged entries. */
+    /** Returns cloned staged entries for inspection or debugging. */
     getEntries() {
         return this.entries.map((entry) => cloneEntry(entry));
     }
     /**
-     * Builds the final bundle payload for the declared operation.
+     * Materializes the final bundle payload from the editor state.
      *
-     * `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()` 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) {
-            const claims = this.getActiveOrSingleSearchClaims();
-            return buildEmployeeSearchBundle({ claims });
+            return buildEmployeeSearchBundle({
+                claims: this.getSingleSearchClaims(),
+                resourceType,
+            });
         }
         if (operation === EmployeeBundleOperations.purge) {
             return {
-                resourceType: 'Bundle',
-                type: 'batch',
+                resourceType: EmployeeResourceTypes.bundle,
+                type: EmployeeResourceTypes.batch,
                 entry: this.entries.map((entry) => {
-                    const identifier = normalizeOptionalIdentifier(entry.resource?.meta?.claims?.[ClaimsPersonSchemaorg.identifier]);
+                    const identifier = normalizeOptionalIdentifier(entry.resource?.meta?.claims?.[ClaimsPersonSchemaorg.identifier]
+                        || entry.resource?.id
+                        || entry.fullUrl);
                     if (!identifier) {
-                        throw new Error('Every purge entry requires org.schema.Person.identifier.');
+                        throw new Error('Every purge entry requires one canonical employee identifier.');
                     }
-                    return buildEmployeePurgeBundle({ identifier }).entry[0];
+                    return buildEmployeePurgeBundle({
+                        identifier,
+                        resourceType,
+                    }).entry[0];
                 }),
             };
         }
         return {
-            resourceType: 'Bundle',
-            type: 'batch',
+            resourceType: EmployeeResourceTypes.bundle,
+            type: EmployeeResourceTypes.batch,
             entry: this.entries.map((entry) => cloneEntry(entry)),
         };
     }
-    /** Reads one claim from the active 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.getActiveEntryClaims()[String(key).trim()]);
+        return cloneClaimValue(this.getClaims()[String(key).trim()]);
     }
-    /** Checks whether the active entry contains one claim key. */
+    /** Checks whether this entry contains one claim key. */
     hasClaim(key) {
-        return Object.prototype.hasOwnProperty.call(this.getActiveEntryClaims(), String(key).trim());
+        return Object.prototype.hasOwnProperty.call(this.getClaims(), String(key).trim());
     }
-    /** Writes one claim on the active entry. */
+    /** Writes one claim on this entry. */
     setClaim(key, value) {
-        const entry = this.getRequiredActiveEntry();
-        entry.resource = entry.resource || { resourceType: 'Employee', meta: { claims: {} } };
+        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 || {}),
@@ -178,7 +270,7 @@ export class BundleEditor {
         };
         return this;
     }
-    /** Appends one claim value on the active entry. */
+    /** Appends one claim value on this entry. */
     addClaim(key, value) {
         const normalizedKey = String(key).trim();
         const current = this.getClaim(normalizedKey);
@@ -190,127 +282,140 @@ export class BundleEditor {
         }
         return this.setClaim(normalizedKey, [current, cloneClaimValue(value)]);
     }
-    /** Removes one claim from the active entry. */
+    /** Removes one claim from this entry. */
     removeClaim(key) {
-        const entry = this.getRequiredActiveEntry();
+        const entry = this.getMutableEntry();
         const claims = {
             ...(entry.resource?.meta?.claims || {}),
         };
         delete claims[String(key).trim()];
-        entry.resource = entry.resource || { resourceType: 'Employee', meta: { claims: {} } };
+        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 {
     /**
-     * Sets the active entry identifier.
+     * Writes the canonical employee 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.
+     * The identifier is synchronized across:
+     * - `entry.fullUrl`
+     * - `resource.id`
+     * - `org.schema.Person.identifier`
      */
     setIdentifier(identifier) {
         const normalized = normalizeOptionalIdentifier(identifier);
-        const entry = this.getRequiredActiveEntry();
         if (!normalized) {
             this.removeClaim(ClaimsPersonSchemaorg.identifier);
-            delete entry.resource?.id;
-            delete entry.fullUrl;
+            this.setResourceId(undefined);
+            this.setFullUrl(undefined);
             return this;
         }
         this.setClaim(ClaimsPersonSchemaorg.identifier, normalized);
-        entry.resource = entry.resource || { resourceType: 'Employee', meta: { claims: {} } };
-        entry.resource.id = normalized;
-        entry.fullUrl = normalized;
+        this.setResourceId(normalized);
+        this.setFullUrl(normalized);
         return this;
     }
-    /** Reads the active entry identifier from claims, resource id, or fullUrl. */
+    /** Reads the canonical employee identifier from claims, resource id, or fullUrl. */
     getIdentifier() {
-        const entry = this.getRequiredActiveEntry();
-        return normalizeOptionalIdentifier(entry.resource?.meta?.claims?.[ClaimsPersonSchemaorg.identifier]
-            || entry.resource?.id
-            || entry.fullUrl);
+        return normalizeOptionalIdentifier(this.getClaim(ClaimsPersonSchemaorg.identifier)
+            || this.getResourceId()
+            || this.getFullUrl());
     }
-    /** Ensures the active entry carries one canonical identifier. */
+    /** Ensures the employee entry carries one canonical `urn:uuid:*` identifier. */
     ensureIdentifier() {
         const existing = this.getIdentifier();
         if (existing) {
             return existing;
         }
-        const generated = createEmployeeIdentifierUrn();
+        const generated = createCanonicalIdentifierUrn();
         this.setIdentifier(generated);
         return generated;
     }
-    /** Sets the active entry `fullUrl` explicitly. */
-    setFullUrl(fullUrl) {
-        const entry = this.getRequiredActiveEntry();
-        const normalized = normalizeOptionalIdentifier(fullUrl);
-        if (!normalized) {
-            delete entry.fullUrl;
-            return this;
-        }
-        entry.fullUrl = normalized;
-        return this;
-    }
-    /** Returns the active entry `fullUrl` when present. */
-    getFullUrl() {
-        return normalizeOptionalIdentifier(this.getRequiredActiveEntry().fullUrl);
-    }
-    /** Convenience employee setter for email. */
+    /** Writes the canonical employee email claim on this entry. */
     setEmail(email) {
         return this.setClaim(ClaimsPersonSchemaorg.email, String(email).trim());
     }
-    /** Convenience employee setter for occupational role. */
+    /** 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());
     }
-    /** Convenience employee setter for `worksFor`. */
+    /** 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());
     }
-    /** Convenience employee setter for `memberOf`. */
+    /** Writes the canonical employee `memberOf` claim on this entry. */
     setMemberOf(memberOf) {
         return this.setClaim(ClaimsPersonSchemaorg.memberOf, String(memberOf).trim());
     }
-    /** Convenience employee setter for `memberOf.taxID`. */
+    /** Writes the canonical employee organization tax id claim on this entry. */
     setMemberOfOrgTaxId(taxId) {
         return this.setClaim(ClaimsPersonSchemaorg.memberOfOrgTaxId, String(taxId).trim());
     }
-    requireBundleOperation() {
-        if (!this.bundleOperation) {
-            throw new Error('BundleEditor requires setBundleOperation(...) before newEntry() or build().');
-        }
-        return this.bundleOperation;
-    }
-    getRequiredActiveEntry() {
-        if (this.activeEntryIndex === null) {
-            throw new Error('BundleEditor requires one active entry. Call newEntry(...) or openEntry(...) first.');
-        }
-        return this.entries[this.activeEntryIndex];
-    }
-    getActiveEntryClaims() {
-        return {
-            ...(this.getRequiredActiveEntry().resource?.meta?.claims || {}),
-        };
-    }
-    getActiveOrSingleSearchClaims() {
-        if (this.entries.length === 0) {
-            return {};
-        }
-        if (this.entries.length > 1) {
-            throw new Error('Search bundles currently support one search 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;
-    }
 }

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/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

@@ -48,6 +48,12 @@ export declare const EmployeeBundleMethods: Readonly<{
 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";

package/dist/utils/employee.js

@@ -15,6 +15,12 @@ export const EmployeeBundleMethods = Object.freeze({
 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',

package/dist/utils/index.d.ts

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

@@ -4,6 +4,7 @@ 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.15.0",
+  "version": "1.16.0",
   "publishConfig": {
     "access": "public"
   },