gdc-sdk-node-ts 0.5.1 → 0.6.1

package/README.md

@@ -25,12 +25,15 @@ If you are integrating this package for the first time, open these in order:
    Real backend setup, imports, `initializeCommunicationIdentity(...)`,
    `new NodeHttpClient(...)`, route context, facade selection, and live method
    usage.
-3. [gdc-sdk-core-ts/docs/SDK_FLOWS_101.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/SDK_FLOWS_101.md)
+3. [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
+   Node/BFF dataspace discovery, hosting-operator resolution, provider
+   resolution, and the correct integration boundary for fallback and cache.
+4. [gdc-sdk-core-ts/docs/SDK_FLOWS_101.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/SDK_FLOWS_101.md)
    Actor split and business-flow map across organization, individual,
    permissions, invitation, import, and SMART flows.
-4. [gdc-common-utils-ts/src/examples/](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/tree/main/src/examples)
+5. [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.
-5. [gdc-common-utils-ts/docs/LIFECYCLE_101.md](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/docs/LIFECYCLE_101.md)
+6. [gdc-common-utils-ts/docs/LIFECYCLE_101.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/LIFECYCLE_101.md)
    Canonical `enable/disable/delete` semantics and copy/paste placeholders.
 
 If you need the shortest path:
@@ -46,6 +49,8 @@ If you need the shortest path:
   [`NodeHttpClient`](src/node-runtime-client.ts)
 - step-by-step runtime usage:
   [docs/SDK_INTEGRATION_101.md](./docs/SDK_INTEGRATION_101.md)
+- dataspace discovery and fallback/cache boundary:
+  [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
 
 ## Executable Usage Examples
 
@@ -65,6 +70,42 @@ Open these tests when you want to see exact method calls and exact inputs:
   SMART token request flow.
 - [tests/live-gw-node-runtime.e2e.test.mjs](tests/live-gw-node-runtime.e2e.test.mjs)
   End-to-end runtime wiring against a real GW environment.
+- [tests/dataspace-resolver.101.test.mjs](tests/dataspace-resolver.101.test.mjs)
+  Dataspace discovery 101 with capability filtering, jurisdiction filtering,
+  reader-vs-provider semantics, and fetcher-level fallback/cache examples.
+
+## Dataspace Discovery Quick Map
+
+Use the Node resolver when your backend or BFF needs to:
+
+- start from preloaded hosting-operator semantics
+- fetch the canonical `/.well-known/dspace-version` entrypoint
+- derive the participant-scoped `/dsp/catalog/dcat.json` artifact
+- return normalized provider/operator matches to portal or app backends
+
+Primary references:
+
+- [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
+- [tests/dataspace-resolver.101.test.mjs](tests/dataspace-resolver.101.test.mjs)
+- [tests/dataspace-resolver.test.mjs](tests/dataspace-resolver.test.mjs)
+
+Copy/paste starting point:
+
+```ts
+import { HttpDataspaceResolver } from 'gdc-sdk-node-ts';
+import { ServiceCapabilityToken } from 'gdc-common-utils-ts/constants';
+
+const resolver = new HttpDataspaceResolver({
+  hostingOperators,
+  fetcher, // optional injection for tests, fallback, tracing, or custom agents
+});
+
+const providers = await resolver.resolvePublishedProviders({
+  sector: 'animal-care',
+  jurisdiction: 'ES',
+  providerCapability: ServiceCapabilityToken.IndexProvider,
+});
+```
 
 ## Actor Split And Runtime Scope
 
@@ -247,16 +288,16 @@ Teaching rule:
 ## Shared Contract Sources
 
 - [gdc-sdk-core-ts/README.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/README.md)
-- [gdc-common-utils-ts/docs/CONSENT_ACCESS_101.md](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/docs/CONSENT_ACCESS_101.md)
+- [gdc-common-utils-ts/docs/CONSENT_ACCESS_101.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/CONSENT_ACCESS_101.md)
 
 Reusable payload examples:
 
-- [gdc-common-utils-ts/src/examples/organization-controller.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/organization-controller.ts)
-- [gdc-common-utils-ts/src/examples/individual-controller.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/individual-controller.ts)
-- [gdc-common-utils-ts/src/examples/professional.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/professional.ts)
-- [gdc-common-utils-ts/src/examples/shared.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/shared.ts)
-- [gdc-common-utils-ts/src/examples/lifecycle.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/lifecycle.ts)
-- [gdc-common-utils-ts/src/examples/api-flow-examples.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/api-flow-examples.ts)
+- [gdc-common-utils-ts/src/examples/organization-controller.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/organization-controller.ts)
+- [gdc-common-utils-ts/src/examples/individual-controller.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/individual-controller.ts)
+- [gdc-common-utils-ts/src/examples/professional.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/professional.ts)
+- [gdc-common-utils-ts/src/examples/shared.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/shared.ts)
+- [gdc-common-utils-ts/src/examples/lifecycle.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/lifecycle.ts)
+- [gdc-common-utils-ts/src/examples/api-flow-examples.ts](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/src/examples/api-flow-examples.ts)
 
 ## API Index
 

package/dist/discovery/DataspaceResolver.d.ts

@@ -0,0 +1,24 @@
+import type { HostingOperatorMatch, PublishedProviderMatch, ResolveHostingOperatorsInput, ResolvePublishedProvidersInput } from './types.js';
+/**
+ * Backend/BFF-facing abstraction for dataspace discovery resolution.
+ *
+ * Responsibility boundary:
+ * - node runtimes orchestrate VC parsing, host-catalog fetch, and capability
+ *   filtering
+ * - semantic extraction and EU coverage inference come from
+ *   `gdc-common-utils-ts`
+ * - tenant-host linkage is resolved from host public catalogs, not from private
+ *   tenant VC fields
+ */
+export declare abstract class DataspaceResolver {
+    /**
+     * Resolves hosting operators whose semantic service metadata matches the
+     * requested sector, capability set, and optional coverage dimensions.
+     */
+    abstract resolveHostingOperators(input: ResolveHostingOperatorsInput): Promise<HostingOperatorMatch[]>;
+    /**
+     * Resolves publicly published provider offerings starting from eligible
+     * hosting operators and their public discovery catalogs.
+     */
+    abstract resolvePublishedProviders(input: ResolvePublishedProvidersInput): Promise<PublishedProviderMatch[]>;
+}

package/dist/discovery/DataspaceResolver.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Backend/BFF-facing abstraction for dataspace discovery resolution.
+ *
+ * Responsibility boundary:
+ * - node runtimes orchestrate VC parsing, host-catalog fetch, and capability
+ *   filtering
+ * - semantic extraction and EU coverage inference come from
+ *   `gdc-common-utils-ts`
+ * - tenant-host linkage is resolved from host public catalogs, not from private
+ *   tenant VC fields
+ */
+export class DataspaceResolver {
+}

package/dist/discovery/HttpDataspaceResolver.d.ts

@@ -0,0 +1,30 @@
+import { DataspaceResolver } from './DataspaceResolver.js';
+import type { HostingOperatorMatch, HttpDataspaceResolverOptions, PublishedProviderMatch, ResolveHostingOperatorsInput, ResolvePublishedProvidersInput } from './types.js';
+/**
+ * Concrete node/BFF resolver that combines preloaded hosting-operator records
+ * with each host's public service-autodiscovery catalog.
+ */
+export declare class HttpDataspaceResolver extends DataspaceResolver {
+    private readonly hostingOperators;
+    private readonly fetcher;
+    constructor(options: HttpDataspaceResolverOptions);
+    /**
+     * Resolves hosting operators from the preloaded semantic records.
+     */
+    resolveHostingOperators(input: ResolveHostingOperatorsInput): Promise<HostingOperatorMatch[]>;
+    /**
+     * Resolves published providers by fetching and filtering eligible host public
+     * discovery catalogs.
+     */
+    resolvePublishedProviders(input: ResolvePublishedProvidersInput): Promise<PublishedProviderMatch[]>;
+    /**
+     * Fetches a public discovery catalog for a hosting operator.
+     *
+     * Resolution order:
+     * - canonical DSP entrypoint via `discoveryUrl` (`/.well-known/dspace-version`)
+     * - direct catalog artifact compatibility via `catalogUrl`
+     */
+    private fetchCatalog;
+    private resolveCatalogArtifactUrl;
+    private fetchDspaceVersionMetadata;
+}

package/dist/discovery/HttpDataspaceResolver.js

@@ -0,0 +1,231 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceCoverageScope, DataspaceProtocolVersions, DataspaceWellKnownPaths, deriveGwCatalogArtifactUrlFromDspaceVersion, inferCoverageScopeFromCountryCode, isProviderServiceCapability, normalizeCountryCode, } from 'gdc-common-utils-ts';
+import { DataspaceResolver } from './DataspaceResolver.js';
+function isObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function equalsIgnoreCase(left, right) {
+    return left.trim().toLowerCase() === right.trim().toLowerCase();
+}
+function splitTokens(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => asString(entry)).filter(Boolean);
+    }
+    const raw = typeof value === 'string' ? value : '';
+    if (!raw)
+        return [];
+    return raw.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+function hasAllTokens(values, requiredValues) {
+    if (!requiredValues?.length)
+        return true;
+    const normalizedValues = new Set((values || []).map((value) => value.trim().toLowerCase()).filter(Boolean));
+    return requiredValues.every((requiredValue) => normalizedValues.has(requiredValue.trim().toLowerCase()));
+}
+function matchSectorValues(values, sector) {
+    if (!sector)
+        return true;
+    return (values || []).some((value) => equalsIgnoreCase(value, sector));
+}
+function buildCoverageTokens(recordCountry, areaServed, coverageScope) {
+    const tokens = new Set();
+    splitTokens(areaServed).forEach((token) => tokens.add(token.toUpperCase()));
+    const normalizedCountry = normalizeCountryCode(recordCountry);
+    if (normalizedCountry) {
+        tokens.add(normalizedCountry);
+        const inferred = inferCoverageScopeFromCountryCode(normalizedCountry);
+        if (inferred)
+            tokens.add(inferred.toUpperCase());
+    }
+    if (coverageScope) {
+        tokens.add(coverageScope.trim().toUpperCase());
+    }
+    return tokens;
+}
+function matchesDiscoveryCoverage(recordCountry, areaServed, filterJurisdiction, filterCoverageScope) {
+    const normalizedJurisdiction = normalizeCountryCode(filterJurisdiction);
+    const normalizedCoverageScope = asString(filterCoverageScope).toUpperCase();
+    if (!normalizedJurisdiction && !normalizedCoverageScope)
+        return true;
+    const tokens = buildCoverageTokens(recordCountry, areaServed, undefined);
+    if (normalizedJurisdiction && tokens.has(normalizedJurisdiction))
+        return true;
+    if (normalizedCoverageScope && tokens.has(normalizedCoverageScope))
+        return true;
+    if (normalizedJurisdiction) {
+        const inferred = inferCoverageScopeFromCountryCode(normalizedJurisdiction);
+        if (inferred && tokens.has(inferred.toUpperCase()))
+            return true;
+    }
+    if (normalizedCoverageScope === DataspaceCoverageScope.EuropeanUnion) {
+        if (Array.from(tokens).some((token) => inferCoverageScopeFromCountryCode(token) === DataspaceCoverageScope.EuropeanUnion)) {
+            return true;
+        }
+    }
+    return false;
+}
+function toHostingOperatorCatalog(value) {
+    if (!isObject(value))
+        return null;
+    const providers = value.providers;
+    if (!Array.isArray(providers))
+        return null;
+    const normalizedProviders = providers
+        .filter(isObject)
+        .map((provider) => {
+        const normalized = {
+            providerDid: asString(provider.providerDid),
+            serviceType: asString(provider.serviceType),
+            category: asString(provider.category),
+            areaServed: asString(provider.areaServed) || undefined,
+            endpointUrl: asString(provider.endpointUrl) || undefined,
+            discoveryUrl: asString(provider.discoveryUrl) || undefined,
+            catalogUrl: asString(provider.catalogUrl) || undefined,
+        };
+        return normalized.providerDid && normalized.serviceType && normalized.category
+            ? normalized
+            : null;
+    })
+        .filter((provider) => Boolean(provider));
+    return {
+        hostingOperatorDid: asString(value.hostingOperatorDid) || undefined,
+        discoveryUrl: asString(value.discoveryUrl) || undefined,
+        catalogUrl: asString(value.catalogUrl) || undefined,
+        providers: normalizedProviders,
+    };
+}
+function matchHostingOperatorRecord(record, input) {
+    if (!matchSectorValues(record.categories, input.sector))
+        return false;
+    if (!hasAllTokens(record.serviceTypes, input.requiredCapabilities))
+        return false;
+    if (!matchesDiscoveryCoverage(record.addressCountry, record.areaServed, input.jurisdiction, input.coverageScope))
+        return false;
+    return true;
+}
+function matchPublishedProviderRecord(provider, input) {
+    if (!equalsIgnoreCase(provider.category, input.sector))
+        return false;
+    if (!isProviderServiceCapability(provider.serviceType))
+        return false;
+    if (!equalsIgnoreCase(provider.serviceType, input.providerCapability))
+        return false;
+    if (!matchesDiscoveryCoverage(undefined, provider.areaServed, input.jurisdiction, input.coverageScope))
+        return false;
+    return true;
+}
+/**
+ * Concrete node/BFF resolver that combines preloaded hosting-operator records
+ * with each host's public service-autodiscovery catalog.
+ */
+export class HttpDataspaceResolver extends DataspaceResolver {
+    constructor(options) {
+        super();
+        this.hostingOperators = [...options.hostingOperators];
+        this.fetcher = options.fetcher || globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Resolves hosting operators from the preloaded semantic records.
+     */
+    async resolveHostingOperators(input) {
+        return this.hostingOperators
+            .filter(({ record }) => matchHostingOperatorRecord(record, input))
+            .map(({ operatorDid, discoveryUrl, record, catalogUrl }) => ({
+            operatorDid,
+            record,
+            matchedCapabilities: (input.requiredCapabilities || []).filter((capability) => record.serviceTypes.some((value) => equalsIgnoreCase(value, capability))),
+            discoveryUrl,
+            catalogUrl,
+        }))
+            .sort((left, right) => left.operatorDid.localeCompare(right.operatorDid));
+    }
+    /**
+     * Resolves published providers by fetching and filtering eligible host public
+     * discovery catalogs.
+     */
+    async resolvePublishedProviders(input) {
+        const eligibleHosts = await this.resolveHostingOperators({
+            sector: input.sector,
+            jurisdiction: input.jurisdiction,
+            coverageScope: input.coverageScope,
+            requiredCapabilities: [input.providerCapability],
+        });
+        const catalogs = await Promise.all(eligibleHosts.map(async (host) => ({
+            host,
+            catalog: await this.fetchCatalog(host.discoveryUrl, host.catalogUrl),
+        })));
+        return catalogs.flatMap(({ host, catalog }) => {
+            if (!catalog)
+                return [];
+            return catalog.providers
+                .filter((record) => matchPublishedProviderRecord(record, input))
+                .map((record) => ({
+                providerDid: record.providerDid,
+                record,
+                hostingOperator: host.record,
+                hostingOperatorDid: host.operatorDid,
+                discoveryUrl: record.discoveryUrl || catalog.discoveryUrl || host.discoveryUrl,
+                catalogUrl: record.catalogUrl || catalog.catalogUrl || host.catalogUrl,
+            }));
+        }).sort((left, right) => left.providerDid.localeCompare(right.providerDid));
+    }
+    /**
+     * Fetches a public discovery catalog for a hosting operator.
+     *
+     * Resolution order:
+     * - canonical DSP entrypoint via `discoveryUrl` (`/.well-known/dspace-version`)
+     * - direct catalog artifact compatibility via `catalogUrl`
+     */
+    async fetchCatalog(discoveryUrl, catalogUrl) {
+        const resolvedCatalogUrl = await this.resolveCatalogArtifactUrl(discoveryUrl, catalogUrl);
+        if (!resolvedCatalogUrl)
+            return undefined;
+        const response = await this.fetcher(resolvedCatalogUrl, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        return toHostingOperatorCatalog(body) || undefined;
+    }
+    async resolveCatalogArtifactUrl(discoveryUrl, catalogUrl) {
+        const normalizedDiscoveryUrl = String(discoveryUrl || '').trim();
+        if (normalizedDiscoveryUrl) {
+            if (normalizedDiscoveryUrl.endsWith(DataspaceWellKnownPaths.VersionMetadata)) {
+                const metadata = await this.fetchDspaceVersionMetadata(normalizedDiscoveryUrl);
+                return deriveGwCatalogArtifactUrlFromDspaceVersion(normalizedDiscoveryUrl, metadata, DataspaceProtocolVersions.Current);
+            }
+            return normalizedDiscoveryUrl;
+        }
+        const normalizedCatalogUrl = String(catalogUrl || '').trim();
+        return normalizedCatalogUrl || undefined;
+    }
+    async fetchDspaceVersionMetadata(discoveryUrl) {
+        const response = await this.fetcher(discoveryUrl, {
+            method: 'GET',
+            headers: {
+                accept: 'application/json',
+            },
+        });
+        if (!response.ok) {
+            return undefined;
+        }
+        const body = await response.json();
+        return isDspaceVersionMetadata(body)
+            ? body
+            : undefined;
+    }
+}
+function isDspaceVersionMetadata(value) {
+    if (!isObject(value))
+        return false;
+    return Array.isArray(value.protocolVersions)
+        && value.protocolVersions.every((entry) => isObject(entry) && asString(entry.version) && asString(entry.path));
+}

package/dist/discovery/index.d.ts

@@ -0,0 +1,3 @@
+export * from './DataspaceResolver.js';
+export * from './HttpDataspaceResolver.js';
+export * from './types.js';

package/dist/discovery/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export * from './DataspaceResolver.js';
+export * from './HttpDataspaceResolver.js';
+export * from './types.js';

package/dist/discovery/types.d.ts

@@ -0,0 +1,68 @@
+import type { DataspaceDiscoveryFilter, HostingOperatorDiscoveryCatalog, HostingOperatorSemanticRecord, PublishedProviderCatalogRecord, TenantServiceSemanticRecord } from 'gdc-common-utils-ts';
+/**
+ * Input for resolving hosting operators that can serve a given dataspace use
+ * case.
+ */
+export type ResolveHostingOperatorsInput = Omit<DataspaceDiscoveryFilter, 'capability'> & Readonly<{
+    requiredCapabilities: readonly string[];
+}>;
+/**
+ * Input for resolving publicly published providers through hosting-operator
+ * catalogs.
+ */
+export type ResolvePublishedProvidersInput = Omit<DataspaceDiscoveryFilter, 'capability' | 'requiredCapabilities'> & Readonly<{
+    providerCapability: string;
+}>;
+/**
+ * Preloaded semantic hosting-operator record used by the node runtime to
+ * resolve public discovery data without re-parsing VCs.
+ */
+export type PreloadedHostingOperatorRecord = Readonly<{
+    operatorDid: string;
+    /**
+     * Canonical DSP discovery entrypoint.
+     *
+     * For GW CORE this should normally be `/.well-known/dspace-version`.
+     */
+    discoveryUrl?: string;
+    /**
+     * @deprecated Prefer `discoveryUrl`. This remains as a compatibility field
+     * for direct catalog artifact URLs.
+     */
+    catalogUrl?: string;
+    record: HostingOperatorSemanticRecord;
+}>;
+/**
+ * Runtime configuration for the HTTP-capable dataspace resolver.
+ */
+export type HttpDataspaceResolverOptions = Readonly<{
+    hostingOperators: readonly PreloadedHostingOperatorRecord[];
+    fetcher?: typeof fetch;
+    requestHeaders?: Record<string, string>;
+}>;
+/**
+ * Normalized hosting-operator match returned by a node/BFF resolver.
+ */
+export type HostingOperatorMatch = Readonly<{
+    operatorDid: string;
+    record: HostingOperatorSemanticRecord;
+    matchedCapabilities: string[];
+    discoveryUrl?: string;
+    catalogUrl?: string;
+}>;
+/**
+ * Normalized published-provider match returned by a node/BFF resolver.
+ */
+export type PublishedProviderMatch = Readonly<{
+    providerDid: string;
+    record: PublishedProviderCatalogRecord;
+    hostingOperator: HostingOperatorSemanticRecord;
+    hostingOperatorDid: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+    tenantSemanticRecord?: TenantServiceSemanticRecord;
+}>;
+/**
+ * Shared host catalog shape returned by HTTP discovery endpoints.
+ */
+export type HostingOperatorCatalog = HostingOperatorDiscoveryCatalog;

package/dist/discovery/types.js

@@ -0,0 +1,2 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+export {};

package/dist/host-onboarding.d.ts

@@ -3,11 +3,13 @@ import type { PollOptions, SubmitAndPollResult } from './orchestration/client-po
  * Current host-registry route context for existing host endpoints.
  *
  * This is a routing object for host registry calls. It is not the same thing as
- * a node-operator discovery descriptor.
+ * a host discovery descriptor.
  */
 export type HostRouteContext = {
     jurisdiction: string;
-    sector: string;
+    hostNetwork?: string;
+    /** @deprecated Use `hostNetwork`. */
+    sector?: string;
     controllerDid?: string;
     hostDid?: string;
 };
@@ -17,6 +19,8 @@ export type HostRouteContext = {
 export type LegalOrganizationOrderInput = {
     offerId: string;
     jurisdiction?: string;
+    hostNetwork?: string;
+    /** @deprecated Use `hostNetwork`. */
     sector?: string;
     dataType?: string;
     additionalClaims?: Record<string, unknown>;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from './smart-token.js';
 export * from './resource-operations.js';
 export * from './session.js';
 export * from './node-runtime-client.js';
+export * from './discovery/index.js';
 export * from './gdc-session-bridge.js';
 export * from './orchestration/client-port.js';
 export * from './orchestration/host-onboarding-sdk.js';

package/dist/index.js

@@ -12,6 +12,7 @@ export * from './smart-token.js';
 export * from './resource-operations.js';
 export * from './session.js';
 export * from './node-runtime-client.js';
+export * from './discovery/index.js';
 export * from './gdc-session-bridge.js';
 export * from './orchestration/client-port.js';
 export * from './orchestration/host-onboarding-sdk.js';

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

@@ -5,7 +5,7 @@ import type { NodeOrganizationActivationInput } from './orchestration/client-por
 import { type IndividualOrganizationConfirmOrderInput, type RouteContext } from './individual-onboarding.js';
 import { type SmartTokenRequestInput } from './smart-token.js';
 import { type IndividualOrganizationBootstrapInput, type IndividualOrganizationStartResult } from './individual-start.js';
-import { type CommunicationIngestionInput, type ClinicalBundleSearchInput, type GrantProfessionalAccessInput, type GrantProfessionalAccessResult, type IndividualMemberLifecycleInput, type IndividualOrganizationLifecycleInput, type OrganizationEmployeeCreationInput, type OrganizationEmployeeLifecycleInput, type RelatedPersonUpsertInput, type RelatedProfileSearchRuntimeInput } from './resource-operations.js';
+import { type CommunicationIngestionInput, type ClinicalBundleSearchInput, type GrantProfessionalAccessInput, type GrantProfessionalAccessResult, type IndividualMemberLifecycleInput, type IndividualOrganizationLifecycleInput, type OrganizationEmployeeCreationInput, type OrganizationEmployeeLifecycleInput, type RelatedPersonUpsertInput } from './resource-operations.js';
 import type { LegalOrganizationOrderInput } from './host-onboarding.js';
 import type { SmartTokenExchangeResult } from './smart-token.js';
 import type { NodeRuntimeClient, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse } from './orchestration/client-port.js';
@@ -205,11 +205,6 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * roles such as a grandfather, guardian, or external caregiver.
      */
     upsertRelatedPersonAndPoll(ctx: RouteContext, input: RelatedPersonUpsertInput): Promise<SubmitAndPollResult>;
-    /**
-     * Searches active related profiles for the given actor identifier by querying
-     * `RelatedPerson/_search`.
-     */
-    searchRelatedProfiles(ctx: RouteContext, input: RelatedProfileSearchRuntimeInput): Promise<SubmitAndPollResult>;
     /**
      * Submits a FHIR `Communication` ingestion request and polls until the
      * GW has persisted the audit record and related projections.
@@ -281,8 +276,6 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
     individualFamilyOrderPollPath(ctx?: RouteContext): string;
     individualRelatedPersonBatchPath(ctx?: RouteContext): string;
     individualRelatedPersonPollPath(ctx?: RouteContext): string;
-    individualRelatedPersonSearchPath(ctx?: RouteContext): string;
-    individualRelatedPersonSearchPollPath(ctx?: RouteContext): string;
     individualConsentR4BatchPath(ctx: RouteContext): string;
     individualConsentR4PollPath(ctx: RouteContext): string;
     individualCommunicationBatchPath(ctx: RouteContext, format: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4'): string;

package/dist/node-runtime-client.js

@@ -1,11 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-/**
- * @fileoverview Default HTTP implementation of the node runtime client.
- *
- * @architecture 101
- * Keep deployed path conventions centralized here so higher-level SDK methods can
- * stay business-oriented and testable.
- */
+// Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import fs from 'node:fs';
 import path from 'node:path';
 import { buildAppHeaders, createBootstrapFacade, resolveAppInfo, } from 'gdc-sdk-core-ts';
@@ -15,7 +9,7 @@ import { confirmLegalOrganizationOrderWithDeps } from './host-onboarding.js';
 import { confirmIndividualOrganizationOrderWithDeps, } from './individual-onboarding.js';
 import { requestSmartTokenWithDeps } from './smart-token.js';
 import { startIndividualOrganizationWithDeps } from './individual-start.js';
-import { createOrganizationEmployeeWithDeps, disableIndividualOrganizationWithDeps, disableOrganizationEmployeeWithDeps, grantProfessionalAccessWithDeps, ingestCommunicationAndUpdateIndexWithDeps, purgeIndividualOrganizationWithDeps, purgeOrganizationEmployeeWithDeps, searchRelatedProfilesWithDeps, searchClinicalBundleWithDeps, searchLatestIpsWithDeps, upsertRelatedPersonAndPollWithDeps, } from './resource-operations.js';
+import { createOrganizationEmployeeWithDeps, disableIndividualOrganizationWithDeps, disableOrganizationEmployeeWithDeps, grantProfessionalAccessWithDeps, ingestCommunicationAndUpdateIndexWithDeps, purgeIndividualOrganizationWithDeps, purgeOrganizationEmployeeWithDeps, searchClinicalBundleWithDeps, searchLatestIpsWithDeps, upsertRelatedPersonAndPollWithDeps, } from './resource-operations.js';
 import { submitAndPollWithMethods } from './orchestration/client-port.js';
 import { GwCoreLifecycleAction } from './constants/lifecycle.js';
 const bootstrapFacade = createBootstrapFacade();
@@ -336,17 +330,6 @@ export class HttpRuntimeClient {
             submitAndPoll: this.submitAndPoll.bind(this),
         });
     }
-    /**
-     * Searches active related profiles for the given actor identifier by querying
-     * `RelatedPerson/_search`.
-     */
-    async searchRelatedProfiles(ctx, input) {
-        return searchRelatedProfilesWithDeps(ctx, input, {
-            individualRelatedPersonSearchPath: this.individualRelatedPersonSearchPath.bind(this),
-            individualRelatedPersonSearchPollPath: this.individualRelatedPersonSearchPollPath.bind(this),
-            submitAndPoll: this.submitAndPoll.bind(this),
-        });
-    }
     /**
      * Submits a FHIR `Communication` ingestion request and polls until the
      * GW has persisted the audit record and related projections.
@@ -530,14 +513,15 @@ export class HttpRuntimeClient {
     }
     hostRegistryPath(ctx, resourceType, action) {
         const hostCtx = this.requireHostRouteContext(ctx);
-        return `/host/cds-${encodeURIComponent(hostCtx.jurisdiction)}/v1/${encodeURIComponent(hostCtx.sector)}/registry/org.schema/${encodeURIComponent(resourceType)}/${encodeURIComponent(action)}`;
+        return `/host/cds-${encodeURIComponent(hostCtx.jurisdiction)}/v1/${encodeURIComponent(hostCtx.hostNetwork || '')}/registry/org.schema/${encodeURIComponent(resourceType)}/${encodeURIComponent(action)}`;
     }
     requireHostRouteContext(ctx) {
+        const runtimeCtx = (this.ctx || {});
         const jurisdiction = String(ctx?.jurisdiction || this.ctx?.jurisdiction || '').trim();
-        const sector = String(ctx?.sector || this.ctx?.sector || '').trim();
-        if (!jurisdiction || !sector)
+        const hostNetwork = String(ctx?.hostNetwork || ctx?.sector || runtimeCtx.hostNetwork || runtimeCtx.sector || '').trim();
+        if (!jurisdiction || !hostNetwork)
             throw new Error('Host route context is required.');
-        return { jurisdiction, sector };
+        return { jurisdiction, hostNetwork };
     }
     hostRegistryOrganizationActivatePath(ctx) { return this.hostRegistryPath(ctx, 'Organization', '_activate'); }
     hostRegistryOrganizationActivatePollPath(ctx) { return this.hostRegistryPath(ctx, 'Organization', '_activate-response'); }
@@ -559,8 +543,6 @@ export class HttpRuntimeClient {
     individualFamilyOrderPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Order', '_batch-response'); }
     individualRelatedPersonBatchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'RelatedPerson', '_batch'); }
     individualRelatedPersonPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'RelatedPerson', '_batch-response'); }
-    individualRelatedPersonSearchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'RelatedPerson', '_search'); }
-    individualRelatedPersonSearchPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'RelatedPerson', '_search-response'); }
     individualConsentR4BatchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'Consent', '_batch'); }
     individualConsentR4PollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'Consent', '_batch-response'); }
     individualCommunicationBatchPath(ctx, format) { return this.v1Path(ctx, 'individual', format, 'Communication', '_batch'); }

package/dist/orchestration/client-port.d.ts

@@ -1,10 +1,4 @@
-/**
- * @fileoverview Shared runtime-client contracts for node orchestration.
- *
- * @architecture 101
- * This module is contract-only. Route/path details stay in concrete runtime clients.
- */
-import type { ControllerBindingInput } from 'gdc-common-utils-ts/models/index';
+import type { ControllerBindingInput } from 'gdc-common-utils-ts/models';
 import type { AsyncPollRequest, OrganizationActivationServiceOptions, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse } from 'gdc-sdk-core-ts';
 export type { AsyncPollRequest, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse, } from 'gdc-sdk-core-ts';
 import type { EmployeeDeviceActivationResult, EmployeeDeviceActivationRequestInput } from '../device-activation.js';
@@ -12,7 +6,7 @@ import type { HostRouteContext, LegalOrganizationOrderInput } from '../host-onbo
 import type { IndividualOrganizationConfirmOrderInput, RouteContext } from '../individual-onboarding.js';
 import type { IndividualOrganizationBootstrapInput, IndividualOrganizationStartResult } from '../individual-start.js';
 import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-token.js';
-import type { CommunicationIngestionInput, ClinicalBundleSearchInput, DigitalTwinGenerationInput, GrantProfessionalAccessInput, GrantProfessionalAccessResult, IndividualMemberLifecycleInput, IndividualOrganizationLifecycleInput, IpsOrFhirImportInput, OrganizationEmployeeCreationInput, OrganizationEmployeeLifecycleInput, RelatedPersonUpsertInput, RelatedProfileSearchRuntimeInput } from '../resource-operations.js';
+import type { CommunicationIngestionInput, ClinicalBundleSearchInput, DigitalTwinGenerationInput, GrantProfessionalAccessInput, GrantProfessionalAccessResult, IndividualMemberLifecycleInput, IndividualOrganizationLifecycleInput, IpsOrFhirImportInput, OrganizationEmployeeCreationInput, OrganizationEmployeeLifecycleInput, RelatedPersonUpsertInput } from '../resource-operations.js';
 /**
  * Shared node-runtime activation input.
  *
@@ -55,7 +49,6 @@ export type RuntimeClient = {
     bootstrapIndividualOrganization?: (input: IndividualOrganizationBootstrapInput) => Promise<IndividualOrganizationStartResult>;
     importIpsOrFhirAndUpdateIndex?: (ctx: RouteContext, input: IpsOrFhirImportInput) => Promise<SubmitAndPollResult>;
     upsertRelatedPersonAndPoll?: (ctx: RouteContext, input: RelatedPersonUpsertInput) => Promise<SubmitAndPollResult>;
-    searchRelatedProfiles?: (ctx: RouteContext, input: RelatedProfileSearchRuntimeInput) => Promise<SubmitAndPollResult>;
     generateDigitalTwinFromSubjectData?: (ctx: RouteContext, input: DigitalTwinGenerationInput) => Promise<SubmitAndPollResult>;
     searchClinicalBundle?: (ctx: RouteContext, input: ClinicalBundleSearchInput) => Promise<SubmitAndPollResult>;
     submitBatch?: (submitPath: string, payload: SubmitPayload) => Promise<SubmitResponse>;

package/dist/resource-operations.d.ts

@@ -1,11 +1,4 @@
-/**
- * @fileoverview Runtime helpers for GW resource submit/poll operations.
- *
- * @architecture 101
- * - Keep request-payload construction centralized here.
- * - Reuse shared DTO/parameter constants instead of repeating string literals.
- */
-import type { BundleSearchQuery, CommunicationInput, DateRange, RelatedProfileSearchInput } from 'gdc-sdk-core-ts';
+import type { BundleSearchQuery, CommunicationInput, DateRange } from 'gdc-sdk-core-ts';
 import type { SubmitAndPollResult } from './orchestration/client-port.js';
 import type { RouteContext } from './individual-onboarding.js';
 export type OrganizationEmployeeCreationInput = {
@@ -104,13 +97,6 @@ export type RelatedPersonUpsertInput = {
         intervalMs?: number;
     };
 };
-export type RelatedProfileSearchRuntimeInput = RelatedProfileSearchInput & {
-    requestThid?: string;
-    pollOptions?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    };
-};
 export type CommunicationIngestionInput = {
     communicationPayload: CommunicationInput & Record<string, unknown>;
     pathFormatSegment?: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4' | 'api' | 'r4' | 'fhir.r4';
@@ -289,16 +275,6 @@ export declare function upsertRelatedPersonAndPollWithDeps(routeCtx: RouteContex
         intervalMs?: number;
     }) => Promise<SubmitAndPollResult>;
 }): Promise<SubmitAndPollResult>;
-export declare function searchRelatedProfilesWithDeps(routeCtx: RouteContext, input: RelatedProfileSearchRuntimeInput, deps: {
-    individualRelatedPersonSearchPath: (ctx: RouteContext) => string;
-    individualRelatedPersonSearchPollPath: (ctx: RouteContext) => string;
-    submitAndPoll: (submitPath: string, pollPath: string, payload: {
-        thid?: string;
-    } & Record<string, unknown>, pollOptions?: {
-        timeoutMs?: number;
-        intervalMs?: number;
-    }) => Promise<SubmitAndPollResult>;
-}): Promise<SubmitAndPollResult>;
 export declare function ingestCommunicationAndUpdateIndexWithDeps(routeCtx: RouteContext, input: CommunicationIngestionInput, deps: {
     individualCommunicationBatchPath: (ctx: RouteContext, pathFormatSegment: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4') => string;
     individualCommunicationPollPath: (ctx: RouteContext, pathFormatSegment: 'org.hl7.fhir.api' | 'org.hl7.fhir.r4') => string;

package/dist/resource-operations.js

@@ -1,13 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-/**
- * @fileoverview Runtime helpers for GW resource submit/poll operations.
- *
- * @architecture 101
- * - Keep request-payload construction centralized here.
- * - Reuse shared DTO/parameter constants instead of repeating string literals.
- */
 import { HealthcareBasicSections } from 'gdc-common-utils-ts/constants';
-import { RELATED_PROFILE_SEARCH_PARAM_ACTOR_IDENTIFIER, RELATED_PROFILE_SEARCH_PARAM_INCLUDE_INACTIVE, RELATED_PROFILE_SEARCH_PARAM_RELATIONSHIP, RELATED_PROFILE_SEARCH_PARAM_SUBJECT_ID, } from 'gdc-sdk-core-ts';
 import { GwCoreLifecycleRequestMethod, GwCoreLifecycleRequestType, GwCoreLifecycleTodo, } from './constants/lifecycle.js';
 export async function createOrganizationEmployeeWithDeps(routeCtx, input, options, deps) {
     const payload = buildEmployeeLifecyclePayload({
@@ -87,21 +79,6 @@ export async function upsertRelatedPersonAndPollWithDeps(routeCtx, input, deps)
     };
     return deps.submitAndPoll(deps.individualRelatedPersonBatchPath(routeCtx), deps.individualRelatedPersonPollPath(routeCtx), payload, input.pollOptions);
 }
-export async function searchRelatedProfilesWithDeps(routeCtx, input, deps) {
-    const payload = {
-        thid: input.requestThid || `relatedprofile-search-${createRuntimeUuid()}`,
-        body: {
-            resourceType: 'Parameters',
-            parameter: [
-                { name: RELATED_PROFILE_SEARCH_PARAM_ACTOR_IDENTIFIER, valueString: input.actorIdentifier },
-                ...(input.subjectId ? [{ name: RELATED_PROFILE_SEARCH_PARAM_SUBJECT_ID, valueString: input.subjectId }] : []),
-                ...(input.relationship ? [{ name: RELATED_PROFILE_SEARCH_PARAM_RELATIONSHIP, valueString: input.relationship }] : []),
-                ...(input.includeInactive === true ? [{ name: RELATED_PROFILE_SEARCH_PARAM_INCLUDE_INACTIVE, valueBoolean: true }] : []),
-            ],
-        },
-    };
-    return deps.submitAndPoll(deps.individualRelatedPersonSearchPath(routeCtx), deps.individualRelatedPersonSearchPollPath(routeCtx), payload, input.pollOptions);
-}
 export async function ingestCommunicationAndUpdateIndexWithDeps(routeCtx, input, deps) {
     const payload = {
         thid: input.communicationPayload.thid || `communication-${createRuntimeUuid()}`,

package/dist/runtime-contracts.d.ts

@@ -1,5 +1,6 @@
 import type { NodeOperatorNetworkType } from 'gdc-common-utils-ts/constants/network';
 import type { DataPersistencePolicy } from 'gdc-sdk-core-ts';
+type HostNetworkType = NodeOperatorNetworkType;
 export type LegacyNodeSourcePackage = never;
 /**
  * Deployment/runtime form factor of the Node SDK host process itself.
@@ -28,17 +29,19 @@ export type TenantContext = {
     sector: string;
 };
 /**
- * Discovery/bootstrap context for a node operator environment.
+ * Discovery/bootstrap context for a host environment.
  *
- * This describes the operator network/environment itself. It does not replace
+ * This describes the host network/environment itself. It does not replace
  * the tenant route context used by tenant-scoped GW endpoints.
  */
-export type NodeOperatorContext = {
-    networkType: NodeOperatorNetworkType;
+export type HostContext = {
+    networkType: HostNetworkType;
     jurisdiction: string;
     operatorDid?: string;
     baseUrl?: string;
 };
+/** @deprecated Use `HostContext`. */
+export type NodeOperatorContext = HostContext;
 export type NodeFetchLike = typeof fetch;
 /**
  * Node runtime configuration for backend/BFF integrations.
@@ -63,3 +66,4 @@ export type NodePackageStatus = {
     status: 'bootstrap';
 };
 export declare const GDC_SDK_NODE_STATUS: NodePackageStatus;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -17,8 +17,8 @@
     "test:e2e:live-gw": "npm run build && RUN_LIVE_GW_E2E=1 node --test tests/live-gw-node-runtime.e2e.test.mjs"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "^1.10.0",
-    "gdc-sdk-core-ts": "^0.5.1"
+    "gdc-common-utils-ts": "^1.14.0",
+    "gdc-sdk-core-ts": "^0.6.1"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",