gdc-common-utils-ts 2.5.20 → 2.6.0

package/dist/constants/http.d.ts

@@ -15,7 +15,9 @@ export declare const HttpStatusCodes: Readonly<{
 export declare const HttpRequestMethods: Readonly<{
     readonly Get: "GET";
     readonly Post: "POST";
+    readonly Put: "PUT";
     readonly Patch: "PATCH";
+    readonly Delete: "DELETE";
 }>;
 /** Canonical HTTP header names. */
 export declare const HttpHeaderNames: Readonly<{

package/dist/constants/http.js

@@ -15,7 +15,9 @@ export const HttpStatusCodes = Object.freeze({
 export const HttpRequestMethods = Object.freeze({
     Get: 'GET',
     Post: 'POST',
+    Put: 'PUT',
     Patch: 'PATCH',
+    Delete: 'DELETE',
 });
 /** Canonical HTTP header names. */
 export const HttpHeaderNames = Object.freeze({

package/dist/models/bundle-editor-types.d.ts

@@ -57,6 +57,7 @@ export type BuiltBundleEntry = {
     request: {
         method: BundleRequest['method'];
         url?: string;
+        ifMatch?: string;
     };
     resource: {
         resourceType: string;
@@ -67,6 +68,8 @@ export type BuiltBundleEntry = {
         [key: string]: unknown;
     };
     fullUrl?: string;
+    /** @internal Materialization hint for request-only FHIR operations. */
+    omitResource?: boolean;
 };
 export declare const BundleTypes: Readonly<{
     readonly batch: "batch";

package/dist/models/bundle.d.ts

@@ -40,8 +40,10 @@ import { OperationOutcome } from "./operation-outcome";
  * - `BundleEntry.type` remains a separate internal business/message label
  */
 export interface BundleRequest {
-    method: 'POST' | 'PUT' | 'DELETE' | 'GET';
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'GET';
     url: string;
+    /** Weak or strong ETag used for optimistic update/delete contention. */
+    ifMatch?: string;
 }
 /**
  * Defines the `response` property for an entry in a response Bundle.

package/dist/utils/bundle-editor-core.js

@@ -14,7 +14,7 @@ import { getClaimValues, setClaimValues } from '../claims/claim-list-helpers.js'
 import { buildBundleDocumentFromClaims } from './bundle-document-builder.js';
 import { buildEmployeeBatchEntry, buildEmployeePurgeBundle, buildEmployeeSearchBundle, EmployeeBundleOperations, EmployeeResourceTypes, } from './employee.js';
 import { BundleEntryEditor } from './bundle-entry-editor.js';
-import { cloneEntry, createCanonicalIdentifierUrn, inferGenericEntryType, normalizeOptionalIdentifier, resolveEntryTypeForOperation, resolveRequestMethodForOperation, } from './bundle-editor-helpers.js';
+import { cloneEntry, createCanonicalIdentifierUrn, inferGenericEntryType, normalizeOptionalIdentifier, materializeBundleEntry, resolveEntryTypeForOperation, resolveRequestMethodForOperation, } from './bundle-editor-helpers.js';
 export class BundleEditor {
     bundleOperation = null;
     allowedResourceType = null;
@@ -92,7 +92,7 @@ export class BundleEditor {
         if (!Object.values(BundleTypes).includes(bundle.type)) {
             throw new TypeError(`BundleEditor.setBundle does not support Bundle.type: ${String(bundle.type || '')}`);
         }
-        const operation = this.requireBundleOperation();
+        const operation = this.bundleOperation || EmployeeBundleOperations.create;
         const nextEntries = bundle.data.map((source, index) => {
             const resource = source?.resource;
             const resourceType = normalizeOptionalIdentifier(resource?.resourceType);
@@ -180,7 +180,11 @@ export class BundleEditor {
     }
     /** Opens one new entry with an explicit resource type, mainly for document bundles. */
     newEntryAs(resourceType, resourceId) {
-        return this.newEntry(resourceId, resourceType).asResourceType(resourceType);
+        const operation = this.bundleOperation || EmployeeBundleOperations.create;
+        const resolvedResourceType = this.resolveEntryResourceType(resourceType);
+        const entry = this.createEntryDraft(operation, resolvedResourceType, resourceId);
+        this.entries.push(entry);
+        return new BundleEntryEditor(this, this.entries.length - 1).asResourceType(resourceType);
     }
     /** Reopens one existing entry by `resource.id` or `fullUrl`. */
     openEntry(resourceIdOrFullUrl) {
@@ -260,9 +264,9 @@ export class BundleEditor {
         if (this.bundleType === BundleTypes.document) {
             return this.buildDocument();
         }
-        const operation = this.requireBundleOperation();
-        const resourceType = this.requireAllowedResourceType();
+        const operation = this.bundleOperation;
         if (operation === EmployeeBundleOperations.search) {
+            const resourceType = this.requireAllowedResourceType();
             if (resourceType !== EmployeeResourceTypes.employee) {
                 throw new Error(`BundleEditor search currently supports only resource type: ${EmployeeResourceTypes.employee}`);
             }
@@ -272,6 +276,7 @@ export class BundleEditor {
             });
         }
         if (operation === EmployeeBundleOperations.purge) {
+            const resourceType = this.requireAllowedResourceType();
             if (resourceType !== EmployeeResourceTypes.employee) {
                 throw new Error(`BundleEditor purge currently supports only resource type: ${EmployeeResourceTypes.employee}`);
             }
@@ -295,7 +300,7 @@ export class BundleEditor {
         return {
             resourceType: ResourceTypesFhirR4.Bundle,
             type: this.bundleType,
-            entry: this.entries.map((entry) => cloneEntry(entry)),
+            entry: this.entries.map((entry) => materializeBundleEntry(entry)),
         };
     }
     /**
@@ -310,12 +315,13 @@ export class BundleEditor {
             resourceType: ResourceTypesFhirR4.Bundle,
             type: this.bundleType,
             data: this.entries.map((entry) => {
-                const clonedEntry = cloneEntry(entry);
+                const clonedEntry = materializeBundleEntry(entry);
                 const { request: _requestIgnored, ...clonedEntryWithoutRequest } = clonedEntry;
                 const normalizedRequest = clonedEntry.request
                     ? {
                         method: clonedEntry.request.method,
                         url: clonedEntry.request.url || '',
+                        ...(clonedEntry.request.ifMatch ? { ifMatch: clonedEntry.request.ifMatch } : {}),
                     }
                     : undefined;
                 return normalizedRequest

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

@@ -11,6 +11,18 @@ export declare function cloneClaimValue<T>(value: T): T;
  * every editor follows the same blank-value rule.
  */
 export declare function normalizeOptionalIdentifier(value: unknown): string | undefined;
+/** Builds the canonical relative FHIR request URL for one technical resource id. */
+export declare function buildFhirResourceRequestUrl(resourceType: string, resourceId: string): string;
+/** Converts one content version id into the weak ETag shape used by FHIR ifMatch. */
+export declare function buildFhirIfMatch(versionId: string): string;
+/** Clones a staged entry and removes the resource body required to be absent for DELETE. */
+export declare function materializeBundleEntry<T extends {
+    request?: {
+        method: BundleRequest['method'];
+    };
+    resource?: unknown;
+    omitResource?: boolean;
+}>(entry: T): T;
 /** Returns one canonical `urn:uuid:*` identifier for new entry/resource drafts. */
 export declare function createCanonicalIdentifierUrn(): string;
 /**

package/dist/utils/bundle-editor-helpers.js

@@ -6,6 +6,7 @@
  *   in the editor classes.
  */
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { HttpRequestMethods } from '../constants/http.js';
 import { AllergyIntoleranceClaim, } from '../models/interoperable-claims/allergy-intolerance-claims.js';
 import { ConditionClaim } from '../models/interoperable-claims/condition-claims.js';
 import { DiagnosticReportClaim } from '../models/interoperable-claims/diagnostic-report-claims.js';
@@ -37,6 +38,34 @@ export function normalizeOptionalIdentifier(value) {
     const normalized = String(value).trim();
     return normalized ? normalized : undefined;
 }
+/** Builds the canonical relative FHIR request URL for one technical resource id. */
+export function buildFhirResourceRequestUrl(resourceType, resourceId) {
+    const normalizedType = normalizeOptionalIdentifier(resourceType);
+    const normalizedId = normalizeOptionalIdentifier(resourceId);
+    if (!normalizedType || !normalizedId) {
+        throw new Error('FHIR resource request URL requires resource type and technical resource id.');
+    }
+    const prefix = `${normalizedType}/`;
+    return normalizedId.startsWith(prefix) ? normalizedId : `${prefix}${normalizedId}`;
+}
+/** Converts one content version id into the weak ETag shape used by FHIR ifMatch. */
+export function buildFhirIfMatch(versionId) {
+    const normalized = normalizeOptionalIdentifier(versionId);
+    if (!normalized)
+        throw new Error('ifMatch requires a non-empty version id.');
+    if (/^(W\/)?"[^"]+"$/.test(normalized))
+        return normalized;
+    return `W/"${normalized}"`;
+}
+/** Clones a staged entry and removes the resource body required to be absent for DELETE. */
+export function materializeBundleEntry(entry) {
+    const materialized = cloneEntry(entry);
+    if (materialized.request?.method === HttpRequestMethods.Delete && materialized.omitResource) {
+        delete materialized.resource;
+    }
+    delete materialized.omitResource;
+    return materialized;
+}
 /** Returns one canonical `urn:uuid:*` identifier for new entry/resource drafts. */
 export function createCanonicalIdentifierUrn() {
     const cryptoLike = globalThis;

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

@@ -24,6 +24,22 @@ export declare class BundleEntryEditor {
     protected readonly bundleEditor: BundleEditor;
     protected readonly entryIndex: number;
     constructor(bundleEditor: BundleEditor, entryIndex: number);
+    /** Stages a FHIR create request for only this batch entry. */
+    create(): this;
+    /** Stages a FHIR update request for only this batch entry. */
+    update(): this;
+    /**
+     * Stages a FHIR delete request for only this batch entry.
+     *
+     * The mutable editor keeps the resource shell so typed methods can still
+     * inspect identity. Materialization removes that shell because DELETE has no
+     * request body.
+     */
+    delete(): this;
+    /** Adds optimistic version matching to this update or delete entry. */
+    ifMatch(versionId: string): this;
+    /** Reads the staged optimistic version ETag. */
+    getIfMatch(): string | undefined;
     /**
      * Reopens the current slot as one typed resource editor.
      *
@@ -102,6 +118,8 @@ export declare class BundleEntryEditor {
     getFullUrl(): string | undefined;
     /** Returns control to the parent bundle editor. */
     doneEntry(): BundleEditor;
+    private requireResourceType;
+    private requireTechnicalResourceId;
     /** Returns the mutable staged entry owned by this editor wrapper. */
     protected getMutableEntry(): BuiltBundleEntry;
     /** Returns a cloned claims view for safe read-modify-write helper code. */

package/dist/utils/bundle-entry-editor.js

@@ -5,10 +5,11 @@
  * - Resource-specific semantics must live in the dedicated typed entry editors.
  */
 import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { HttpRequestMethods } from '../constants/http.js';
 import { BundleEditableResourceTypes, } from '../models/bundle-editor-types.js';
 import { normalizeFhirApiClaimKey } from './fhir-api-claim-helpers.js';
 import { EmployeeResourceTypes, } from './employee.js';
-import { cloneClaimValue, normalizeOptionalIdentifier } from './bundle-editor-helpers.js';
+import { buildFhirIfMatch, buildFhirResourceRequestUrl, cloneClaimValue, normalizeOptionalIdentifier, } from './bundle-editor-helpers.js';
 import { createRegisteredBundleEntryEditor } from './bundle-editor-registry.js';
 export class BundleEntryEditor {
     bundleEditor;
@@ -17,6 +18,61 @@ export class BundleEntryEditor {
         this.bundleEditor = bundleEditor;
         this.entryIndex = entryIndex;
     }
+    /** Stages a FHIR create request for only this batch entry. */
+    create() {
+        const entry = this.getMutableEntry();
+        const resourceType = this.requireResourceType('create');
+        entry.request = { method: HttpRequestMethods.Post, url: resourceType };
+        entry.omitResource = false;
+        return this;
+    }
+    /** Stages a FHIR update request for only this batch entry. */
+    update() {
+        const entry = this.getMutableEntry();
+        const resourceType = this.requireResourceType('update');
+        const resourceId = this.requireTechnicalResourceId('update');
+        entry.request = {
+            method: HttpRequestMethods.Put,
+            url: buildFhirResourceRequestUrl(resourceType, resourceId),
+        };
+        entry.omitResource = false;
+        return this;
+    }
+    /**
+     * Stages a FHIR delete request for only this batch entry.
+     *
+     * The mutable editor keeps the resource shell so typed methods can still
+     * inspect identity. Materialization removes that shell because DELETE has no
+     * request body.
+     */
+    delete() {
+        const entry = this.getMutableEntry();
+        const resourceType = this.requireResourceType('delete');
+        const resourceId = this.requireTechnicalResourceId('delete');
+        entry.request = {
+            method: HttpRequestMethods.Delete,
+            url: buildFhirResourceRequestUrl(resourceType, resourceId),
+        };
+        entry.omitResource = true;
+        return this;
+    }
+    /** Adds optimistic version matching to this update or delete entry. */
+    ifMatch(versionId) {
+        const entry = this.getMutableEntry();
+        if (entry.request?.method !== HttpRequestMethods.Put
+            && entry.request?.method !== HttpRequestMethods.Delete) {
+            throw new Error('ifMatch is supported only for update or delete entries.');
+        }
+        entry.request = {
+            ...entry.request,
+            ifMatch: buildFhirIfMatch(versionId),
+        };
+        return this;
+    }
+    /** Reads the staged optimistic version ETag. */
+    getIfMatch() {
+        return normalizeOptionalIdentifier(this.getMutableEntry().request?.ifMatch);
+    }
     /**
      * Reopens the current slot as one typed resource editor.
      *
@@ -324,6 +380,20 @@ export class BundleEntryEditor {
     doneEntry() {
         return this.bundleEditor;
     }
+    requireResourceType(operation) {
+        const resourceType = normalizeOptionalIdentifier(this.getMutableEntry().resource?.resourceType);
+        if (!resourceType)
+            throw new Error(`${operation} requires a resource type.`);
+        return resourceType;
+    }
+    requireTechnicalResourceId(operation) {
+        const entry = this.getMutableEntry();
+        const resourceId = normalizeOptionalIdentifier(entry.resource?.id)
+            || normalizeOptionalIdentifier(entry.fullUrl);
+        if (!resourceId)
+            throw new Error(`${operation} requires a technical resource id.`);
+        return resourceId;
+    }
     /** Returns the mutable staged entry owned by this editor wrapper. */
     getMutableEntry() {
         return this.bundleEditor.getMutableEntry(this.entryIndex);

package/dist/utils/organization-test-network-credential.d.ts

@@ -51,7 +51,6 @@ export type OrganizationTestNetworkCredentialInput = Readonly<{
     controllerKeyMaterial: string;
     applicationId: string;
     accessPath: 'partner' | 'test-network';
-    targetNetwork: 'test-network' | 'network';
     /**
      * @deprecated Postal-address verification is a separate production-readiness
      * flow. This compatibility input is ignored and is never embedded in a Test
@@ -64,6 +63,8 @@ export type OrganizationTestNetworkCredentialInput = Readonly<{
  * Builds the immutable VC that a controller receives out-of-band and attaches
  * to `Organization/_transaction`. Postal-address verification is deliberately
  * outside this credential and may be completed independently before production.
+ * Test Network scope is expressed by `OrganizationTestNetworkCredential` in
+ * the signed `type[]`, not by a non-schema.org credential-subject property.
  */
 export declare function buildOrganizationTestNetworkCredential(input: OrganizationTestNetworkCredentialInput): VerifiableCredentialV2;
 /**

package/dist/utils/organization-test-network-credential.js

@@ -19,6 +19,8 @@ function required(value, name) {
  * Builds the immutable VC that a controller receives out-of-band and attaches
  * to `Organization/_transaction`. Postal-address verification is deliberately
  * outside this credential and may be completed independently before production.
+ * Test Network scope is expressed by `OrganizationTestNetworkCredential` in
+ * the signed `type[]`, not by a non-schema.org credential-subject property.
  */
 export function buildOrganizationTestNetworkCredential(input) {
     const applicationId = required(input.applicationId, 'applicationId');
@@ -36,7 +38,6 @@ export function buildOrganizationTestNetworkCredential(input) {
             id: required(input.subjectDid, 'subjectDid'),
             applicationId,
             accessPath: input.accessPath,
-            targetNetwork: input.targetNetwork,
             organization: {
                 legalName: required(input.legalName, 'legalName'),
                 identifier: organizationIdentifier,

package/dist/utils/test-network-organization-credentials.d.ts

@@ -31,5 +31,8 @@ export type BuildTestNetworkOrganizationCredentialSetInput = Readonly<{
  * must still be added to every returned credential.
  */
 export declare function buildTestNetworkOrganizationCredentialSet(input: BuildTestNetworkOrganizationCredentialSetInput): TestNetworkOrganizationCredentialSet;
-/** Deterministic detached-proof payload for one of the three Test Network VCs. */
+/**
+ * Deterministic detached-proof payload for one of the three Test Network VCs.
+ * The signed `TestNetworkCredential` type is the sole environment marker.
+ */
 export declare function canonicalizeTestNetworkOrganizationCredential(credential: VerifiableCredentialV2): string;

package/dist/utils/test-network-organization-credentials.js

@@ -37,7 +37,6 @@ export function buildTestNetworkOrganizationCredentialSet(input) {
             id: `urn:sha256:${required(input.pdfSha256, 'pdfSha256')}`,
             documentVersion: required(input.documentVersion, 'documentVersion'),
             applicationId,
-            targetNetwork: 'test-network',
         }];
     const base = {
         '@context': [W3cCredentialContexts.V2, 'https://schema.org'],
@@ -62,7 +61,6 @@ export function buildTestNetworkOrganizationCredentialSet(input) {
             ...(identifierType === 'taxID' ? { taxID: organizationIdentifier } : {}),
             address: { '@type': 'PostalAddress', addressCountry },
             makesOffer: { '@type': 'Offer', category: serviceCategory },
-            targetNetwork: 'test-network',
         },
     };
     const representative = {
@@ -87,7 +85,6 @@ export function buildTestNetworkOrganizationCredentialSet(input) {
                     ? { taxID: organizationIdentifier }
                     : { identifier: { additionalType: identifierType, value: organizationIdentifier } }),
             },
-            targetNetwork: 'test-network',
         },
     };
     const controller = {
@@ -117,7 +114,6 @@ export function buildTestNetworkOrganizationCredentialSet(input) {
                 hasOccupation: { '@type': 'Occupation', occupationalCategory: 'ISCO-08|1330' },
                 hasCredential: { material: required(input.controllerKeyMaterial, 'controllerKeyMaterial') },
             },
-            targetNetwork: 'test-network',
         },
     };
     return [organization, representative, controller];
@@ -132,13 +128,16 @@ function canonicalizeValue(value) {
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([key, nested]) => [key, canonicalizeValue(nested)]));
 }
-/** Deterministic detached-proof payload for one of the three Test Network VCs. */
+/**
+ * Deterministic detached-proof payload for one of the three Test Network VCs.
+ * The signed `TestNetworkCredential` type is the sole environment marker.
+ */
 export function canonicalizeTestNetworkOrganizationCredential(credential) {
     if (!TestNetworkOrganizationCredentialTypes.some(type => credential.type.includes(type))) {
         throw new Error('Credential is not a Test Network organization credential.');
     }
-    if (credential.credentialSubject?.targetNetwork !== 'test-network') {
-        throw new Error('Test Network organization credential requires targetNetwork=test-network.');
+    if (!credential.type.includes(EnvironmentCredentialTypes.TestNetworkCredential)) {
+        throw new Error('Test Network organization credential requires TestNetworkCredential in type[].');
     }
     return JSON.stringify(canonicalizeValue(credential));
 }

package/package.json

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