gdc-sdk-node-ts 2.9.3 → 2.9.5

package/README.md

@@ -1,5 +1,8 @@
 # gdc-sdk-node-ts
 
+Development and releases follow the mandatory
+[`local-first TDD and release contract`](docs/LOCAL_FIRST_RELEASE_CONTRACT.md).
+
 See [ARCHITECTURE.md](./ARCHITECTURE.md) and
 [CONTRIBUTING.md](./CONTRIBUTING.md) before adding node runtime facades,
 execution adapters, or orchestration tests.
@@ -69,50 +72,53 @@ If you are integrating this package for the first time, open these in order:
 2. [docs/101-SDK_END_TO_END.md](./docs/101-SDK_END_TO_END.md)
   Ordered onboarding guide with end-to-end journeys, copy/paste snippets, and
   the recommended reading path for new backend integrators.
-3. [docs/101-HIGH_LEVEL_CLINICAL_PROFILE_WRITES.md](./docs/101-HIGH_LEVEL_CLINICAL_PROFILE_WRITES.md)
+3. [docs/101-PDQM_PATIENT_MATCH.md](./docs/101-PDQM_PATIENT_MATCH.md)
+   Resolve only `indexProviderDid` in Fabric, then use the high-level Node SDK
+   to call IHE PDQm `POST Patient/$match` with one FHIR `Parameters` request.
+4. [docs/101-HIGH_LEVEL_CLINICAL_PROFILE_WRITES.md](./docs/101-HIGH_LEVEL_CLINICAL_PROFILE_WRITES.md)
    Focused subset of the end-to-end guide: load a professional or individual
    member/controller profile, create or import clinical data in the selected
    index provider, and verify it through an authoritative summary readback.
-4. [docs/101-PROFESSIONAL-CONSENT-SMART.md](./docs/101-PROFESSIONAL-CONSENT-SMART.md)
+5. [docs/101-PROFESSIONAL-CONSENT-SMART.md](./docs/101-PROFESSIONAL-CONSENT-SMART.md)
    Canonical professional DID, consent, VP and SMART flow without literal
    sections or caller-built audience URLs.
-5. [docs/101-AUTHORIZED_SUBJECT_DIRECTORY.md](./docs/101-AUTHORIZED_SUBJECT_DIRECTORY.md)
+6. [docs/101-AUTHORIZED_SUBJECT_DIRECTORY.md](./docs/101-AUTHORIZED_SUBJECT_DIRECTORY.md)
    Signed OpenID account discovery of already-authorized subjects without
    treating the account token as VP, SMART or wallet proof.
-6. [docs/101-SDK_INTEGRATION.md](./docs/101-SDK_INTEGRATION.md)
+7. [docs/101-SDK_INTEGRATION.md](./docs/101-SDK_INTEGRATION.md)
    Real backend setup plus the public runtime entrypoints:
    `HostOnboardingSdk`, `OrganizationControllerSdk`,
    `IndividualControllerSdk`, `ProfessionalSdk`, route-context usage, and the
    canonical `ProfileRuntime -> loadProfile(...) -> workspace/session -> actor facade -> submit/poll` shape.
-7. [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](./tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
+8. [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](./tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
    Canonical live backend/BFF walkthrough on a fresh local GW lifecycle:
    host/tenant activation, employee provisioning, individual bootstrap,
    consent grant, professional SMART token, clinical read, and final cleanup.
-8. [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
+9. [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
    Exact TTY/local/Docker commands for running the SDK against a real local GW
    CORE, including tenant bootstrap and employee-seat setup.
-9. [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
+10. [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
    Node/BFF dataspace discovery, hosting-operator resolution, provider
    resolution, and the correct integration boundary for fallback and cache.
-10. [gdc-sdk-core-ts/docs/101-SDK_FLOWS.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_FLOWS.md)
+11. [gdc-sdk-core-ts/docs/101-SDK_FLOWS.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_FLOWS.md)
    Actor split and business-flow map across organization, individual,
    permissions, invitation, import, and SMART flows.
-11. [gwtemplate-node-ts/docs/PORTAL_API_TO_GW_CORE.md](https://github.com/Global-DataCare/gwtemplate-node-ts/blob/main/docs/PORTAL_API_TO_GW_CORE.md)
+12. [gwtemplate-node-ts/docs/PORTAL_API_TO_GW_CORE.md](https://github.com/Global-DataCare/gwtemplate-node-ts/blob/main/docs/PORTAL_API_TO_GW_CORE.md)
    Canonical portal/BFF functional map over GW CORE, including the domain
    split between `employees`, `related persons`, `members`, and `consents`.
-12. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
+13. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
    Shared payload values used by the docs and tests.
-13. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
+14. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
    Canonical `enable/disable/delete` semantics and copy/paste placeholders.
-14. [tests/101-backend-profile-runtime.test.mjs](./tests/101-backend-profile-runtime.test.mjs)
+15. [tests/101-backend-profile-runtime.test.mjs](./tests/101-backend-profile-runtime.test.mjs)
    Technical runtime slice for profile/device/session orchestration internals.
    Read this after the public actor SDK guides, not before them.
-15. [tests/101-individual-controller-backend-runtime.test.mjs](./tests/101-individual-controller-backend-runtime.test.mjs)
+16. [tests/101-individual-controller-backend-runtime.test.mjs](./tests/101-individual-controller-backend-runtime.test.mjs)
    Technical wrapper slice around the generic profile runtime. This is not the
    main onboarding path for new integrators.
-16. [docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md](./docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md)
+17. [docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md](./docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md)
    Historical reconciliation note for the current CORE registration baseline.
-17. [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
+18. [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
    Follow-up scope after GW CORE live validation, including the future user job
    manager boundary.
 

package/dist/index.d.ts

@@ -51,3 +51,4 @@ export * from './orchestration/professional-sdk.js';
 export * from './orchestration/digital-twin-sdk.js';
 export * from './legacy-compat.js';
 export * from './local-terminology-bff.js';
+export * from './pdqm-patient-match.js';

package/dist/index.js

@@ -52,3 +52,4 @@ export * from './orchestration/professional-sdk.js';
 export * from './orchestration/digital-twin-sdk.js';
 export * from './legacy-compat.js';
 export * from './local-terminology-bff.js';
+export * from './pdqm-patient-match.js';

package/dist/node-runtime-client.d.ts

@@ -22,6 +22,7 @@ import { type FhirR5SubscriptionBatchInput } from './fhir-r5-subscription-runtim
 import type { FhirR5SubscriptionTopic } from 'gdc-common-utils-ts/models/fhir-r5-subscription';
 import { type DigitalTwinMaterializationInput, type DigitalTwinSearchInput, type DigitalTwinSelectionInput } from './digital-twin.js';
 import { type AuthorizedIndividualSubject, type AuthorizedIndividualSubjectDirectoryInput } from './authorized-subject-directory.js';
+import { type FhirPatientMatchBundle, type MatchPatientAtIndexProviderInput } from './pdqm-patient-match.js';
 export type HttpRuntimeClientOptions = {
     baseUrl: string;
     bearerToken?: string;
@@ -125,6 +126,15 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * Returns the configured ICA-issued runtime/software proof token, when present.
      */
     getRuntimeVpToken(): string | undefined;
+    /**
+     * Matches a known human identifier at the index provider resolved in Fabric.
+     *
+     * The BFF supplies the provider DID and its discovered FHIR base URL. This
+     * method never forwards the Fabric lookup hash. It sends one IHE PDQm
+     * `Parameters` request and returns the resulting FHIR search `Bundle`, while
+     * applying the runtime's configured FHIR, DIDComm plain or strict profile.
+     */
+    matchPatientAtIndexProvider(input: MatchPatientAtIndexProviderInput): Promise<FhirPatientMatchBundle>;
     /**
      * Builds a canonical GDC v1 resource/action path from a route context.
      */

package/dist/node-runtime-client.js

@@ -20,6 +20,7 @@ import { runtimeUuid, wrapBundleAsGatewayTransactionMessage } from './runtime-me
 import { submitFhirR5SubscriptionBatchWithDeps, submitFhirR5SubscriptionTopicBatchWithDeps, } from './fhir-r5-subscription-runtime.js';
 import { materializeDigitalTwinWithDeps, saveDigitalTwinSelectionWithDeps, searchDigitalTwinsWithDeps, } from './digital-twin.js';
 import { listAuthorizedIndividualSubjectsWithDeps, } from './authorized-subject-directory.js';
+import { matchPatientAtIndexProviderWithDeps, } from './pdqm-patient-match.js';
 const bootstrapFacade = createBootstrapFacade();
 /**
  * Runtime-oriented HTTP client for Node backends, BFFs, and workers that need
@@ -93,6 +94,22 @@ export class HttpRuntimeClient {
     getRuntimeVpToken() {
         return this.runtimeVpToken;
     }
+    /**
+     * Matches a known human identifier at the index provider resolved in Fabric.
+     *
+     * The BFF supplies the provider DID and its discovered FHIR base URL. This
+     * method never forwards the Fabric lookup hash. It sends one IHE PDQm
+     * `Parameters` request and returns the resulting FHIR search `Bundle`, while
+     * applying the runtime's configured FHIR, DIDComm plain or strict profile.
+     */
+    async matchPatientAtIndexProvider(input) {
+        return matchPatientAtIndexProviderWithDeps(input, {
+            transportProfile: this.transportProfile,
+            secureTransportAdapter: this.secureTransportAdapter,
+            createUuid: runtimeUuid,
+            post: async (url, rendered) => postRenderedWithRuntimeConfig(this.transportConfig, url, rendered),
+        });
+    }
     /**
      * Builds a canonical GDC v1 resource/action path from a route context.
      */

package/dist/pdqm-patient-match.d.ts

@@ -0,0 +1,44 @@
+import { type FhirPatientMatchInput, type SecureDidcommTransportAdapter, type TransportProfile } from 'gdc-sdk-core-ts';
+export type MatchPatientAtIndexProviderInput = Readonly<{
+    /** Provider FHIR base discovered from the resolved index-provider DID. */
+    fhirBaseUrl: string;
+    /** Patient containing the governed identifier known by the requesting BFF. */
+    patient: FhirPatientMatchInput;
+    /** DID of the authenticated professional, member or controller making the request. */
+    requesterDid: string;
+    /** Provider DID returned by the public subject-identifier ledger lookup. */
+    indexProviderDid: string;
+    /** Optional PDQm control that excludes possible, lower-confidence matches. */
+    onlyCertainMatches?: boolean;
+}>;
+export type FhirPatientMatchBundle = Readonly<{
+    resourceType: 'Bundle';
+    type: 'searchset';
+    [key: string]: unknown;
+}>;
+type PatientMatchDependencies = Readonly<{
+    transportProfile: TransportProfile;
+    secureTransportAdapter?: SecureDidcommTransportAdapter;
+    createUuid: () => string;
+    post: (url: string, request: Readonly<{
+        contentType: string;
+        accept: string;
+        body: Record<string, unknown> | string;
+    }>) => Promise<Readonly<{
+        status: number;
+        body: unknown;
+    }>>;
+}>;
+/**
+ * Calls the resolved provider's IHE PDQm `POST Patient/$match` facade.
+ *
+ * The opaque subject-identifier hash is deliberately absent: it stops at the
+ * preceding Fabric lookup. Native FHIR sends one `Parameters` body. DIDComm
+ * plain places that same resource in the only `body.data[]` entry. Strict mode
+ * signs and encrypts the identical DIDComm message through the wallet adapter
+ * and sends `request=<JWE>` as `application/x-www-form-urlencoded`.
+ *
+ * @see https://profiles.ihe.net/ITI/PDQm/ITI-119.html
+ */
+export declare function matchPatientAtIndexProviderWithDeps(input: MatchPatientAtIndexProviderInput, dependencies: PatientMatchDependencies): Promise<FhirPatientMatchBundle>;
+export {};

package/dist/pdqm-patient-match.js

@@ -0,0 +1,63 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { buildPdqmPatientMatchGatewayBody, buildPdqmPatientMatchRequest, decodeTransportResponse, renderGatewayMessageRequest, TransportProfiles, } from 'gdc-sdk-core-ts';
+function requiredDid(value, name) {
+    const normalized = String(value || '').trim();
+    if (!normalized.startsWith('did:'))
+        throw new TypeError(`${name} must be a DID.`);
+    return normalized;
+}
+function readPatientMatchBundle(value) {
+    const candidate = value && typeof value === 'object' && !Array.isArray(value)
+        && 'body' in value
+        ? value.body
+        : value;
+    if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+        throw new Error('PDQm Patient/$match response must contain one FHIR search Bundle.');
+    }
+    const bundle = candidate;
+    if (bundle.resourceType !== 'Bundle' || bundle.type !== 'searchset') {
+        throw new Error('PDQm Patient/$match response must contain one FHIR search Bundle.');
+    }
+    return bundle;
+}
+/**
+ * Calls the resolved provider's IHE PDQm `POST Patient/$match` facade.
+ *
+ * The opaque subject-identifier hash is deliberately absent: it stops at the
+ * preceding Fabric lookup. Native FHIR sends one `Parameters` body. DIDComm
+ * plain places that same resource in the only `body.data[]` entry. Strict mode
+ * signs and encrypts the identical DIDComm message through the wallet adapter
+ * and sends `request=<JWE>` as `application/x-www-form-urlencoded`.
+ *
+ * @see https://profiles.ihe.net/ITI/PDQm/ITI-119.html
+ */
+export async function matchPatientAtIndexProviderWithDeps(input, dependencies) {
+    const requesterDid = requiredDid(input.requesterDid, 'requesterDid');
+    const indexProviderDid = requiredDid(input.indexProviderDid, 'indexProviderDid');
+    const matchRequest = buildPdqmPatientMatchRequest({
+        fhirBaseUrl: input.fhirBaseUrl,
+        patient: input.patient,
+        onlyCertainMatches: input.onlyCertainMatches,
+    });
+    const thid = `pdqm-patient-match-${dependencies.createUuid()}`;
+    const rendered = dependencies.transportProfile === TransportProfiles.FhirJson
+        ? {
+            contentType: TransportProfiles.FhirJson,
+            accept: 'application/fhir+json, application/json',
+            body: matchRequest.body,
+        }
+        : await renderGatewayMessageRequest({
+            id: dependencies.createUuid(),
+            thid,
+            type: TransportProfiles.DidcommPlainJson,
+            from: requesterDid,
+            to: [indexProviderDid],
+            body: buildPdqmPatientMatchGatewayBody(matchRequest),
+        }, dependencies.transportProfile, dependencies.secureTransportAdapter);
+    const response = await dependencies.post(matchRequest.url, rendered);
+    if (response.status < 200 || response.status >= 300) {
+        throw new Error(`PDQm Patient/$match failed with HTTP ${response.status}.`);
+    }
+    const decoded = await decodeTransportResponse(response.body, dependencies.transportProfile, dependencies.secureTransportAdapter);
+    return readPatientMatchBundle(decoded);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "2.9.3",
+  "version": "2.9.5",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -38,8 +38,8 @@
     "test:e2e:live-gw:clean": "bash ./scripts/run-live-gw-clean.sh"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "2.9.4",
-    "gdc-sdk-core-ts": "2.9.2"
+    "gdc-common-utils-ts": "2.9.7",
+    "gdc-sdk-core-ts": "2.9.5"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",