gdc-common-utils-ts 1.12.0 → 1.13.0

package/README.md

@@ -92,6 +92,54 @@ import { JweObject, JwtCompactParts } from 'gdc-common-utils-ts/models';
 - [docs/consent-access-matrix-task.md](docs/consent-access-matrix-task.md)
   - next-step design/task document for active consent aggregation, explicit deny precedence, controller views, permission-request communications, and SMART access evaluation
 
+## Dataspace Protocol And Discovery
+
+Use `gdc-common-utils-ts` as the shared source of truth for DSP route building,
+`dspace-version` metadata, and normalized discovery DTOs.
+
+Main entry points:
+
+- [`src/utils/dataspace-protocol.ts`](src/utils/dataspace-protocol.ts)
+  - canonical GW CORE path builders for host-scoped and tenant-scoped DSP
+    routes
+- [`src/utils/dataspace-discovery.ts`](src/utils/dataspace-discovery.ts)
+  - semantic extraction, provider filtering, default DTO builders, and the
+    copy/paste fetcher harness used by docs/tests
+- [`src/examples/dataspace-discovery.ts`](src/examples/dataspace-discovery.ts)
+  - synthetic provider/operator examples that distinguish discovery URL from
+    derived catalog artifact URL
+- [`__tests__/dataspace-protocol.test.ts`](__tests__/dataspace-protocol.test.ts)
+  - executable path and `dspace-version` examples
+- [`__tests__/dataspace-discovery.test.ts`](__tests__/dataspace-discovery.test.ts)
+  - executable semantic extraction and filtering examples
+
+Copy/paste example:
+
+```ts
+import {
+  buildDspaceVersionMetadata,
+  buildGwCatalogArtifactPath,
+  buildGwDspaceVersionWellKnownPath,
+  deriveGwCatalogArtifactUrlFromDspaceVersion,
+} from 'gdc-common-utils-ts/utils/dataspace-protocol';
+import { HostNetworkTypes } from 'gdc-common-utils-ts/constants/network';
+
+const hostContext = {
+  participantId: 'host',
+  jurisdiction: 'ES',
+  version: 'v1',
+  hostNetwork: HostNetworkTypes.Test,
+};
+
+const discoveryPath = buildGwDspaceVersionWellKnownPath(hostContext);
+const metadata = buildDspaceVersionMetadata('/host/cds-ES/v1/test/dsp');
+const catalogPath = buildGwCatalogArtifactPath(hostContext);
+const catalogUrl = deriveGwCatalogArtifactUrlFromDspaceVersion(
+  `https://host.example.org${discoveryPath}`,
+  metadata,
+);
+```
+
 ## API Index
 
 The canonical API contract should live in JSDoc on exported code. The README acts as a navigable index.
@@ -116,8 +164,8 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - Reusable professional role/permission examples tying actor role, consent action, SMART scope, and expected FHIR resource types together.
 - [`DeviceUserClasses`, `DeviceAppTypes`](src/constants/device.ts)
   - Shared user-class and app/device-type constants used by licensing and SDK flows.
-- [`NodeOperatorNetworkTypes`](src/constants/network.ts)
-  - Shared network/environment labels for node-operator discovery/bootstrap.
+- [`HostNetworkTypes`](src/constants/network.ts)
+  - Shared network/environment labels for host discovery/bootstrap.
 - [`SmartGatewayScopesFhirR4`](src/constants/smart.ts)
   - Current CORE GW SMART scope literals such as `organization/Consent.cruds`.
   - Treat these as optional elevated scopes. Do not add them to the first read-only tutorial by default.

package/dist/constants/dataspace-protocol.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical Dataspace Protocol version identifiers used by the current GW/SDK
+ * discovery flows.
+ */
+export declare const DataspaceProtocolVersions: Readonly<{
+    readonly Current: "2025-1";
+}>;
+/**
+ * Canonical well-known paths used by Dataspace Protocol discovery.
+ */
+export declare const DataspaceWellKnownPaths: Readonly<{
+    readonly VersionMetadata: "/.well-known/dspace-version";
+}>;
+/**
+ * Project-local GW CORE DSP binding paths.
+ *
+ * These preserve the current internal API structure while still ending in the
+ * DSP catalog route shapes.
+ */
+export declare const GwDataspaceBindingPaths: Readonly<{
+    readonly Base: "/dsp";
+    readonly CatalogCollectionSuffix: "/catalog";
+    readonly CatalogRequestSuffix: "/catalog/request";
+    readonly CatalogArtifactSuffix: "/catalog/dcat.json";
+    readonly CatalogDatasetsPrefix: "/catalog/datasets";
+}>;
+export type DataspaceProtocolVersionValue = typeof DataspaceProtocolVersions[keyof typeof DataspaceProtocolVersions];

package/dist/constants/dataspace-protocol.js

@@ -0,0 +1,27 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Canonical Dataspace Protocol version identifiers used by the current GW/SDK
+ * discovery flows.
+ */
+export const DataspaceProtocolVersions = Object.freeze({
+    Current: '2025-1',
+});
+/**
+ * Canonical well-known paths used by Dataspace Protocol discovery.
+ */
+export const DataspaceWellKnownPaths = Object.freeze({
+    VersionMetadata: '/.well-known/dspace-version',
+});
+/**
+ * Project-local GW CORE DSP binding paths.
+ *
+ * These preserve the current internal API structure while still ending in the
+ * DSP catalog route shapes.
+ */
+export const GwDataspaceBindingPaths = Object.freeze({
+    Base: '/dsp',
+    CatalogCollectionSuffix: '/catalog',
+    CatalogRequestSuffix: '/catalog/request',
+    CatalogArtifactSuffix: '/catalog/dcat.json',
+    CatalogDatasetsPrefix: '/catalog/datasets',
+});

package/dist/constants/index.d.ts

@@ -1,6 +1,7 @@
 export * from './actor-session';
 export * from './communication';
 export * from './cryptography';
+export * from './dataspace-protocol';
 export * from './device';
 export * from './did-services';
 export * from './eu-countries';

package/dist/constants/index.js

@@ -1,6 +1,7 @@
 export * from './actor-session.js';
 export * from './communication.js';
 export * from './cryptography.js';
+export * from './dataspace-protocol.js';
 export * from './device.js';
 export * from './did-services.js';
 export * from './eu-countries.js';

package/dist/constants/network.d.ts

@@ -1,13 +1,25 @@
 /**
- * Canonical network/environment labels used to identify node-operator networks
- * during discovery/bootstrap flows.
+ * Canonical network/environment labels used to identify host networks during
+ * discovery/bootstrap flows.
  *
- * These labels do not replace the clinical route `sector`. They describe the
- * operator environment itself.
+ * These labels do not replace the business route `sector`. They describe the
+ * host environment itself.
+ */
+export declare const HostNetworkTypes: Readonly<{
+    readonly Test: "test";
+    readonly TestNetwork: "test-network";
+    readonly Network: "network";
+}>;
+export type HostNetworkType = typeof HostNetworkTypes[keyof typeof HostNetworkTypes];
+/**
+ * @deprecated Use `HostNetworkTypes`.
  */
 export declare const NodeOperatorNetworkTypes: Readonly<{
     readonly Test: "test";
     readonly TestNetwork: "test-network";
     readonly Network: "network";
 }>;
-export type NodeOperatorNetworkType = typeof NodeOperatorNetworkTypes[keyof typeof NodeOperatorNetworkTypes];
+/**
+ * @deprecated Use `HostNetworkType`.
+ */
+export type NodeOperatorNetworkType = HostNetworkType;

package/dist/constants/network.js

@@ -1,13 +1,17 @@
 // Copyright 2025 Antifraud Services Inc. under the Apache License, Version 2.0.
 /**
- * Canonical network/environment labels used to identify node-operator networks
- * during discovery/bootstrap flows.
+ * Canonical network/environment labels used to identify host networks during
+ * discovery/bootstrap flows.
  *
- * These labels do not replace the clinical route `sector`. They describe the
- * operator environment itself.
+ * These labels do not replace the business route `sector`. They describe the
+ * host environment itself.
  */
-export const NodeOperatorNetworkTypes = Object.freeze({
+export const HostNetworkTypes = Object.freeze({
     Test: 'test',
     TestNetwork: 'test-network',
     Network: 'network',
 });
+/**
+ * @deprecated Use `HostNetworkTypes`.
+ */
+export const NodeOperatorNetworkTypes = HostNetworkTypes;

package/dist/examples/dataspace-discovery.d.ts

@@ -75,6 +75,11 @@ export declare function buildExampleTenantServiceMetaClaims(input?: ExampleDatas
  * Builds a synthetic published-provider record as it would appear in a host
  * service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the participant-scoped `/.well-known/dspace-version`
+ *   entrypoint
+ * - `catalogUrl` is the derived `/dsp/catalog/dcat.json` artifact
+ *
  * @param input Optional overrides for the synthetic provider publication.
  * @returns Shared host-catalog provider entry.
  */
@@ -82,6 +87,11 @@ export declare function buildExamplePublishedProviderCatalogRecord(input?: Examp
 /**
  * Builds a synthetic host/operator service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the canonical entrypoint clients should fetch first
+ * - `catalogUrl` is the read-only DSP artifact derived from the advertised
+ *   base path
+ *
  * @param providers Optional published providers to include.
  * @returns Shared catalog DTO for host-side public service autodiscovery.
  */

package/dist/examples/dataspace-discovery.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { ClaimsOrganizationSchemaorg, ClaimsServiceSchemaorg } from '../constants/schemaorg.js';
 import { serializeServiceCapabilityTokens, ServiceCapabilityToken } from '../constants/service-capabilities.js';
-import { EXAMPLE_HOSTING_OPERATOR_CATALOG_URL, EXAMPLE_HOSTING_OPERATOR_DID, EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL, EXAMPLE_JURISDICTION, EXAMPLE_SECTOR, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
+import { EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL, EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL, EXAMPLE_HOSTING_OPERATOR_DID, EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL, EXAMPLE_JURISDICTION, EXAMPLE_SECTOR, EXAMPLE_TENANT_SERVICE_DID, } from './shared.js';
 function firstOrCsv(values) {
     return values.length <= 1 ? (values[0] || '') : values.join(',');
 }
@@ -98,6 +98,11 @@ export function buildExampleTenantServiceMetaClaims(input = {}) {
  * Builds a synthetic published-provider record as it would appear in a host
  * service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the participant-scoped `/.well-known/dspace-version`
+ *   entrypoint
+ * - `catalogUrl` is the derived `/dsp/catalog/dcat.json` artifact
+ *
  * @param input Optional overrides for the synthetic provider publication.
  * @returns Shared host-catalog provider entry.
  */
@@ -109,21 +114,28 @@ export function buildExamplePublishedProviderCatalogRecord(input = {}) {
         providerDid: input.did || EXAMPLE_TENANT_SERVICE_DID,
         serviceType: serviceTypes[0] || ServiceCapabilityToken.IndexProvider,
         category: categories[0] || EXAMPLE_SECTOR,
-        areaServed: areaServed[0] || 'EU',
+        areaServed: firstOrCsv(areaServed) || 'EU',
         endpointUrl: EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL,
-        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_URL,
+        discoveryUrl: EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL,
     };
 }
 /**
  * Builds a synthetic host/operator service-autodiscovery catalog.
  *
+ * URL rule:
+ * - `discoveryUrl` is the canonical entrypoint clients should fetch first
+ * - `catalogUrl` is the read-only DSP artifact derived from the advertised
+ *   base path
+ *
  * @param providers Optional published providers to include.
  * @returns Shared catalog DTO for host-side public service autodiscovery.
  */
 export function buildExampleHostingOperatorDiscoveryCatalog(providers = [buildExamplePublishedProviderCatalogRecord()]) {
     return {
         hostingOperatorDid: EXAMPLE_HOSTING_OPERATOR_DID,
-        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_URL,
+        discoveryUrl: EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL,
         providers: [...providers],
     };
 }

package/dist/examples/shared.d.ts

@@ -20,7 +20,7 @@ export declare const EXAMPLE_TENANT_ROUTE_CONTEXT: {
 };
 export declare const EXAMPLE_HOST_ROUTE_CONTEXT: {
     readonly jurisdiction: "ES";
-    readonly sector: "health-care";
+    readonly sector: "test";
 };
 export declare const EXAMPLE_CONTROLLER_DID: "did:web:people.acme.org:controllers:primary";
 export declare const EXAMPLE_CONTROLLER_EMAIL: "controller@acme.org";
@@ -36,7 +36,10 @@ export declare const EXAMPLE_HOST_PUBLIC_HOSTNAME: "host.example.com";
 export declare const EXAMPLE_HOSTING_OPERATOR_DID: "did:web:host.example.org";
 export declare const EXAMPLE_TENANT_SERVICE_DID: "did:web:provider.example.org";
 export declare const EXAMPLE_SECONDARY_TENANT_SERVICE_DID: "did:web:provider-b.example.org";
-export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL: "https://host.example.org/.well-known/dcat3/catalog";
+export declare const EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL: "https://host.example.org/host/cds-ES/v1/test/.well-known/dspace-version";
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL: "https://host.example.org/host/cds-ES/v1/test/dsp/catalog/dcat.json";
+/** @deprecated Use `EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL`. */
+export declare const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL: "https://host.example.org/host/cds-ES/v1/test/.well-known/dspace-version";
 export declare const EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL: "https://host.example.org/catalog/provider-a";
 export declare const EXAMPLE_PROVIDER_LEGAL_NAME: "ACME Health Provider";
 export declare const EXAMPLE_SECONDARY_PROVIDER_LEGAL_NAME: "Reader Only Provider";

package/dist/examples/shared.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 import { DataspaceSectors } from '../constants/sectors.js';
+import { HostNetworkTypes } from '../constants/network.js';
 import { HealthcareActorRoles, HealthcareBasicSections, HealthcareConsentPurposes, } from '../constants/healthcare.js';
 import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
 /**
@@ -25,7 +26,7 @@ export const EXAMPLE_TENANT_ROUTE_CONTEXT = {
 };
 export const EXAMPLE_HOST_ROUTE_CONTEXT = {
     jurisdiction: EXAMPLE_JURISDICTION,
-    sector: EXAMPLE_SECTOR,
+    sector: HostNetworkTypes.Test,
 };
 export const EXAMPLE_CONTROLLER_DID = 'did:web:people.acme.org:controllers:primary';
 export const EXAMPLE_CONTROLLER_EMAIL = EXAMPLE_EMAIL_CONTROLLER_ORG;
@@ -41,7 +42,10 @@ export const EXAMPLE_HOST_PUBLIC_HOSTNAME = 'host.example.com';
 export const EXAMPLE_HOSTING_OPERATOR_DID = 'did:web:host.example.org';
 export const EXAMPLE_TENANT_SERVICE_DID = 'did:web:provider.example.org';
 export const EXAMPLE_SECONDARY_TENANT_SERVICE_DID = 'did:web:provider-b.example.org';
-export const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL = 'https://host.example.org/.well-known/dcat3/catalog';
+export const EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL = `https://host.example.org/host/cds-ES/v1/${HostNetworkTypes.Test}/.well-known/dspace-version`;
+export const EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL = `https://host.example.org/host/cds-ES/v1/${HostNetworkTypes.Test}/dsp/catalog/dcat.json`;
+/** @deprecated Use `EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL`. */
+export const EXAMPLE_HOSTING_OPERATOR_CATALOG_URL = EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL;
 export const EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_URL = 'https://host.example.org/catalog/provider-a';
 export const EXAMPLE_PROVIDER_LEGAL_NAME = 'ACME Health Provider';
 export const EXAMPLE_SECONDARY_PROVIDER_LEGAL_NAME = 'Reader Only Provider';

package/dist/models/dataspace-discovery.d.ts

@@ -38,6 +38,7 @@ export type PublishedProviderCatalogRecord = Readonly<{
     category: string;
     areaServed?: string;
     endpointUrl?: string;
+    discoveryUrl?: string;
     catalogUrl?: string;
 }>;
 /**
@@ -61,6 +62,7 @@ export type DataspaceDiscoveryFilter = Readonly<{
  */
 export type HostingOperatorDiscoveryCatalog = Readonly<{
     hostingOperatorDid?: string;
+    discoveryUrl?: string;
     catalogUrl?: string;
     providers: PublishedProviderCatalogRecord[];
 }>;

package/dist/models/dataspace-protocol.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One advertised Dataspace Protocol version entry from `/.well-known/dspace-version`.
+ */
+export type DspaceProtocolVersionEntry = Readonly<{
+    version: string;
+    path: string;
+}>;
+/**
+ * Minimal version metadata payload returned by the DSP well-known discovery
+ * endpoint.
+ */
+export type DspaceVersionMetadata = Readonly<{
+    protocolVersions: readonly DspaceProtocolVersionEntry[];
+}>;

package/dist/models/dataspace-protocol.js

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

package/dist/models/index.d.ts

@@ -13,6 +13,7 @@ export * from './consent-rule';
 export * from './consent-access';
 export * from './crypto';
 export * from './dataspace-discovery';
+export * from './dataspace-protocol';
 export * from './device-license';
 export * from './did';
 export * from './fhir-documents';

package/dist/models/index.js

@@ -13,6 +13,7 @@ export * from './consent-rule.js';
 export * from './consent-access.js';
 export * from './crypto.js';
 export * from './dataspace-discovery.js';
+export * from './dataspace-protocol.js';
 export * from './device-license.js';
 export * from './did.js';
 export * from './fhir-documents.js';

package/dist/utils/dataspace-discovery.d.ts

@@ -1,4 +1,46 @@
 import { type DataspaceDiscoveryFilter, type DataspaceServiceSemanticRecord, type HostingOperatorSemanticRecord, type HostingOperatorDiscoveryCatalog, type PublishedProviderCatalogRecord, type TenantServiceSemanticRecord } from '../models/dataspace-discovery';
+export type DiscoveryCatalogFetchResponse = Readonly<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export declare const DiscoveryCatalogSource: Readonly<{
+    readonly Internet: "internet";
+    readonly Cache: "cache";
+    readonly Default: "default";
+}>;
+export type DiscoveryCatalogSourceValue = typeof DiscoveryCatalogSource[keyof typeof DiscoveryCatalogSource];
+export type DiscoveryCatalogFetcherOptions = Readonly<{
+    internetCatalogs?: Record<string, HostingOperatorDiscoveryCatalog>;
+    internetJsonByUrl?: Record<string, unknown>;
+    defaultCatalogs?: Record<string, HostingOperatorDiscoveryCatalog>;
+}>;
+export type DiscoveryCatalogFetcherHarness = Readonly<{
+    fetcher(input: string, init?: unknown): Promise<DiscoveryCatalogFetchResponse>;
+    calls: string[];
+    sources: Map<string, DiscoveryCatalogSourceValue>;
+    cache: Map<string, HostingOperatorDiscoveryCatalog>;
+    setInternetCatalog(url: string, catalog: HostingOperatorDiscoveryCatalog): void;
+    setInternetJson(url: string, payload: unknown): void;
+    setInternetFailure(url: string, status?: number, body?: unknown): void;
+    clearInternetRoute(url: string): void;
+}>;
+export type DefaultPublishedProviderCatalogRecordInput = Readonly<{
+    providerDid: string;
+    serviceType: string;
+    category: string;
+    areaServed?: string | readonly string[];
+    endpointUrl?: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+}>;
+export type DefaultHostingOperatorDiscoveryCatalogInput = Readonly<{
+    hostingOperatorDid?: string;
+    discoveryUrl?: string;
+    catalogUrl?: string;
+    providers?: ReadonlyArray<PublishedProviderCatalogRecord>;
+}>;
 /**
  * Parses the CSV or array representation of `serviceType`.
  *
@@ -144,3 +186,50 @@ export declare function filterPublishedProvidersByDiscoveryFilter(records: Reado
  * the requested service-autodiscovery filter.
  */
 export declare function filterHostingOperatorDiscoveryCatalog(catalog: HostingOperatorDiscoveryCatalog, filter: DataspaceDiscoveryFilter): HostingOperatorDiscoveryCatalog;
+/**
+ * Builds a normalized published-provider catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default discovery data loaded from configuration
+ * - tests that should use the same DTO constructors as production code
+ *
+ * This helper is intentionally neutral:
+ * - no example DIDs
+ * - no example URLs
+ * - no hidden business defaults
+ *
+ * @param input Required provider catalog fields plus optional URLs.
+ * @returns Normalized published-provider catalog record.
+ */
+export declare function buildDefaultPublishedProviderCatalogRecord(input: DefaultPublishedProviderCatalogRecordInput): PublishedProviderCatalogRecord;
+/**
+ * Builds a normalized hosting-operator discovery catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default host catalogs assembled from configuration
+ * - tests that should reuse the same constructor as production code
+ *
+ * @param input Optional host identity fields plus the provider list.
+ * @returns Normalized host discovery catalog.
+ */
+export declare function buildDefaultHostingOperatorDiscoveryCatalog(input?: DefaultHostingOperatorDiscoveryCatalogInput): HostingOperatorDiscoveryCatalog;
+/**
+ * Creates a generic host-catalog fetcher with cache and default fallback.
+ *
+ * Intended use:
+ * - docs
+ * - SDK integration examples
+ * - tests that need to demonstrate the transport boundary around discovery
+ *
+ * Behavior:
+ * - successful network catalog refreshes cache
+ * - later network failures reuse cached catalog when available
+ * - when both network and cache are unavailable, configured defaults are used
+ *
+ * Production integrations may follow the same policy while replacing this
+ * in-memory harness with real logging, metrics, and storage.
+ *
+ * @param options Optional initial network and default catalogs keyed by URL.
+ * @returns Fetcher plus observable state and mutation helpers.
+ */
+export declare function createDiscoveryCatalogFetcher(options?: DiscoveryCatalogFetcherOptions): DiscoveryCatalogFetcherHarness;

package/dist/utils/dataspace-discovery.js

@@ -11,6 +11,19 @@ function asObject(value) {
 function asNonEmptyString(value) {
     return typeof value === 'string' ? value.trim() : '';
 }
+export const DiscoveryCatalogSource = Object.freeze({
+    Internet: 'internet',
+    Cache: 'cache',
+    Default: 'default',
+});
+function createDiscoveryCatalogFetchResponse(payload, init = {}) {
+    return {
+        ok: init.ok ?? true,
+        status: init.status ?? 200,
+        json: async () => payload,
+        text: async () => JSON.stringify(payload),
+    };
+}
 function toStringList(value) {
     if (Array.isArray(value)) {
         return Array.from(new Set(value
@@ -339,3 +352,131 @@ export function filterHostingOperatorDiscoveryCatalog(catalog, filter) {
         providers: filterPublishedProvidersByDiscoveryFilter(catalog.providers, filter),
     };
 }
+/**
+ * Builds a normalized published-provider catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default discovery data loaded from configuration
+ * - tests that should use the same DTO constructors as production code
+ *
+ * This helper is intentionally neutral:
+ * - no example DIDs
+ * - no example URLs
+ * - no hidden business defaults
+ *
+ * @param input Required provider catalog fields plus optional URLs.
+ * @returns Normalized published-provider catalog record.
+ */
+export function buildDefaultPublishedProviderCatalogRecord(input) {
+    const normalizedAreaServed = Array.isArray(input.areaServed)
+        ? normalizeList(input.areaServed.map((value) => asNonEmptyString(value)).filter(Boolean))
+        : toStringList(input.areaServed);
+    return {
+        providerDid: asNonEmptyString(input.providerDid),
+        serviceType: asNonEmptyString(input.serviceType),
+        category: asNonEmptyString(input.category),
+        areaServed: normalizedAreaServed.length ? normalizedAreaServed.join(',') : undefined,
+        endpointUrl: asNonEmptyString(input.endpointUrl) || undefined,
+        discoveryUrl: asNonEmptyString(input.discoveryUrl) || undefined,
+        catalogUrl: asNonEmptyString(input.catalogUrl) || undefined,
+    };
+}
+/**
+ * Builds a normalized hosting-operator discovery catalog DTO suitable for:
+ *
+ * - backend-owned fallback catalogs
+ * - default host catalogs assembled from configuration
+ * - tests that should reuse the same constructor as production code
+ *
+ * @param input Optional host identity fields plus the provider list.
+ * @returns Normalized host discovery catalog.
+ */
+export function buildDefaultHostingOperatorDiscoveryCatalog(input = {}) {
+    return {
+        hostingOperatorDid: asNonEmptyString(input.hostingOperatorDid) || undefined,
+        discoveryUrl: asNonEmptyString(input.discoveryUrl) || undefined,
+        catalogUrl: asNonEmptyString(input.catalogUrl) || undefined,
+        providers: [...(input.providers || [])],
+    };
+}
+function isHostingOperatorCatalogPayload(value) {
+    const objectValue = asObject(value);
+    return Boolean(objectValue && Array.isArray(objectValue.providers));
+}
+/**
+ * Creates a generic host-catalog fetcher with cache and default fallback.
+ *
+ * Intended use:
+ * - docs
+ * - SDK integration examples
+ * - tests that need to demonstrate the transport boundary around discovery
+ *
+ * Behavior:
+ * - successful network catalog refreshes cache
+ * - later network failures reuse cached catalog when available
+ * - when both network and cache are unavailable, configured defaults are used
+ *
+ * Production integrations may follow the same policy while replacing this
+ * in-memory harness with real logging, metrics, and storage.
+ *
+ * @param options Optional initial network and default catalogs keyed by URL.
+ * @returns Fetcher plus observable state and mutation helpers.
+ */
+export function createDiscoveryCatalogFetcher(options = {}) {
+    const internetResponses = new Map([
+        ...Object.entries(options.internetCatalogs || {}).map(([url, catalog]) => [url, createDiscoveryCatalogFetchResponse(catalog, { ok: true, status: 200 })]),
+        ...Object.entries(options.internetJsonByUrl || {}).map(([url, payload]) => [url, createDiscoveryCatalogFetchResponse(payload, { ok: true, status: 200 })]),
+    ]);
+    const internetPayloads = new Map([
+        ...Object.entries(options.internetCatalogs || {}).map(([url, catalog]) => [String(url), catalog]),
+        ...Object.entries(options.internetJsonByUrl || {}).map(([url, payload]) => [String(url), payload]),
+    ]);
+    const defaultCatalogs = new Map(Object.entries(options.defaultCatalogs || {}));
+    const cache = new Map();
+    const sources = new Map();
+    const calls = [];
+    return {
+        calls,
+        sources,
+        cache,
+        setInternetCatalog(url, catalog) {
+            internetResponses.set(String(url), createDiscoveryCatalogFetchResponse(catalog, { ok: true, status: 200 }));
+            internetPayloads.set(String(url), catalog);
+        },
+        setInternetJson(url, payload) {
+            internetResponses.set(String(url), createDiscoveryCatalogFetchResponse(payload, { ok: true, status: 200 }));
+            internetPayloads.set(String(url), payload);
+        },
+        setInternetFailure(url, status = 503, body = { error: 'temporary failure' }) {
+            internetResponses.set(String(url), createDiscoveryCatalogFetchResponse(body, { ok: false, status }));
+            internetPayloads.delete(String(url));
+        },
+        clearInternetRoute(url) {
+            internetResponses.delete(String(url));
+            internetPayloads.delete(String(url));
+        },
+        async fetcher(input) {
+            const key = String(input);
+            calls.push(key);
+            const internetResponse = internetResponses.get(key);
+            if (internetResponse && internetResponse.ok) {
+                const payload = internetPayloads.get(key);
+                if (isHostingOperatorCatalogPayload(payload)) {
+                    cache.set(key, payload);
+                }
+                sources.set(key, DiscoveryCatalogSource.Internet);
+                return internetResponse;
+            }
+            if (cache.has(key)) {
+                sources.set(key, DiscoveryCatalogSource.Cache);
+                return createDiscoveryCatalogFetchResponse(cache.get(key), { ok: true, status: 200 });
+            }
+            if (defaultCatalogs.has(key)) {
+                sources.set(key, DiscoveryCatalogSource.Default);
+                return createDiscoveryCatalogFetchResponse(defaultCatalogs.get(key), { ok: true, status: 200 });
+            }
+            sources.set(key, DiscoveryCatalogSource.Default);
+            return createDiscoveryCatalogFetchResponse({ error: 'not found' }, { ok: false, status: 404 });
+        },
+    };
+}

package/dist/utils/dataspace-protocol.d.ts

@@ -0,0 +1,66 @@
+import { type DataspaceProtocolVersionValue } from '../constants/dataspace-protocol';
+import type { DspaceProtocolVersionEntry, DspaceVersionMetadata } from '../models/dataspace-protocol';
+/**
+ * Route context used to build tenant-scoped or host-scoped GW CORE DSP paths.
+ *
+ * Semantic rule:
+ * - `tenantId` participants use `businessSector`
+ * - `host`/ICA/runtime participants use `hostNetwork`
+ */
+export type GwDataspaceRouteContext = Readonly<{
+    participantId?: string;
+    tenantId?: string;
+    jurisdiction?: string;
+    version?: string;
+    hostNetwork?: string;
+    /** @deprecated Use `hostNetwork`. */
+    hostNetworkOrBusinessSector?: string;
+    businessSector?: string;
+    sector?: string;
+}>;
+/**
+ * Builds the GW CORE base DSP path.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/dsp`
+ */
+export declare function buildGwDataspaceBasePath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the canonical DSP version-discovery well-known path for GW CORE.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/.well-known/dspace-version`
+ */
+export declare function buildGwDspaceVersionWellKnownPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the project-local GW CORE DSP catalog request endpoint.
+ */
+export declare function buildGwCatalogRequestPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the GW CORE catalog collection base path.
+ */
+export declare function buildGwCatalogCollectionPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the project-local GW CORE catalog artifact URL path used for public
+ * read-only autodiscovery.
+ */
+export declare function buildGwCatalogArtifactPath(input?: GwDataspaceRouteContext): string;
+/**
+ * Builds the project-local GW CORE dataset lookup path.
+ */
+export declare function buildGwCatalogDatasetPath(input?: GwDataspaceRouteContext, datasetId?: string): string;
+/**
+ * Builds a minimal DSP version metadata payload for a given GW CORE DSP base
+ * path.
+ */
+export declare function buildDspaceVersionMetadata(path: string, version?: DataspaceProtocolVersionValue): DspaceVersionMetadata;
+/**
+ * Selects the preferred advertised DSP version entry from a `dspace-version`
+ * payload.
+ */
+export declare function selectDspaceProtocolVersionEntry(metadata: DspaceVersionMetadata | null | undefined, version?: string): DspaceProtocolVersionEntry | undefined;
+/**
+ * Derives the GW CORE catalog artifact URL from a `dspace-version` endpoint URL
+ * and its parsed payload.
+ */
+export declare function deriveGwCatalogArtifactUrlFromDspaceVersion(dspaceVersionUrl: string, metadata: DspaceVersionMetadata | null | undefined, version?: string): string | undefined;

package/dist/utils/dataspace-protocol.js

@@ -0,0 +1,109 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceProtocolVersions, DataspaceWellKnownPaths, GwDataspaceBindingPaths, } from '../constants/dataspace-protocol.js';
+function resolveParticipantId(input) {
+    return String(input.participantId || input.tenantId || '').trim();
+}
+function resolveSectorLikeSegment(input) {
+    return String(input.hostNetwork
+        || input.hostNetworkOrBusinessSector
+        || input.businessSector
+        || input.sector
+        || '').trim();
+}
+function hasParticipantRouteContext(input) {
+    return Boolean(resolveParticipantId(input)
+        && String(input.jurisdiction || '').trim()
+        && String(input.version || '').trim()
+        && resolveSectorLikeSegment(input));
+}
+/**
+ * Builds the GW CORE base DSP path.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/dsp`
+ */
+export function buildGwDataspaceBasePath(input = {}) {
+    if (!hasParticipantRouteContext(input)) {
+        return GwDataspaceBindingPaths.Base;
+    }
+    return `/${resolveParticipantId(input)}`
+        + `/cds-${String(input.jurisdiction).trim()}`
+        + `/${String(input.version).trim()}`
+        + `/${resolveSectorLikeSegment(input)}`
+        + GwDataspaceBindingPaths.Base;
+}
+/**
+ * Builds the canonical DSP version-discovery well-known path for GW CORE.
+ *
+ * Participant scope:
+ * - `/{participantId}/cds-{jurisdiction}/{version}/{hostNetwork|businessSector}/.well-known/dspace-version`
+ */
+export function buildGwDspaceVersionWellKnownPath(input = {}) {
+    if (!hasParticipantRouteContext(input)) {
+        return DataspaceWellKnownPaths.VersionMetadata;
+    }
+    return `/${resolveParticipantId(input)}`
+        + `/cds-${String(input.jurisdiction).trim()}`
+        + `/${String(input.version).trim()}`
+        + `/${resolveSectorLikeSegment(input)}`
+        + DataspaceWellKnownPaths.VersionMetadata;
+}
+/**
+ * Builds the project-local GW CORE DSP catalog request endpoint.
+ */
+export function buildGwCatalogRequestPath(input = {}) {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogRequestSuffix}`;
+}
+/**
+ * Builds the GW CORE catalog collection base path.
+ */
+export function buildGwCatalogCollectionPath(input = {}) {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogCollectionSuffix}`;
+}
+/**
+ * Builds the project-local GW CORE catalog artifact URL path used for public
+ * read-only autodiscovery.
+ */
+export function buildGwCatalogArtifactPath(input = {}) {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogArtifactSuffix}`;
+}
+/**
+ * Builds the project-local GW CORE dataset lookup path.
+ */
+export function buildGwCatalogDatasetPath(input = {}, datasetId = ':id') {
+    return `${buildGwDataspaceBasePath(input)}${GwDataspaceBindingPaths.CatalogDatasetsPrefix}/${datasetId}`;
+}
+/**
+ * Builds a minimal DSP version metadata payload for a given GW CORE DSP base
+ * path.
+ */
+export function buildDspaceVersionMetadata(path, version = DataspaceProtocolVersions.Current) {
+    return {
+        protocolVersions: [
+            {
+                version,
+                path,
+            },
+        ],
+    };
+}
+/**
+ * Selects the preferred advertised DSP version entry from a `dspace-version`
+ * payload.
+ */
+export function selectDspaceProtocolVersionEntry(metadata, version = DataspaceProtocolVersions.Current) {
+    const entries = metadata?.protocolVersions || [];
+    return entries.find((entry) => String(entry.version || '').trim() === String(version).trim())
+        || entries[0];
+}
+/**
+ * Derives the GW CORE catalog artifact URL from a `dspace-version` endpoint URL
+ * and its parsed payload.
+ */
+export function deriveGwCatalogArtifactUrlFromDspaceVersion(dspaceVersionUrl, metadata, version = DataspaceProtocolVersions.Current) {
+    const entry = selectDspaceProtocolVersionEntry(metadata, version);
+    if (!entry?.path)
+        return undefined;
+    const base = new URL(dspaceVersionUrl);
+    return new URL(`${String(entry.path).trim()}${GwDataspaceBindingPaths.CatalogArtifactSuffix}`, `${base.protocol}//${base.host}`).toString();
+}

package/dist/utils/index.d.ts

@@ -8,6 +8,7 @@ export * from './consent';
 export * from './did';
 export * from './did-resolution';
 export * from './dataspace-discovery';
+export * from './dataspace-protocol';
 export * from './didcomm';
 export * from './didcomm-submit';
 export * from './didcomm-submit-policy';

package/dist/utils/index.js

@@ -8,6 +8,7 @@ export * from './consent.js';
 export * from './did.js';
 export * from './did-resolution.js';
 export * from './dataspace-discovery.js';
+export * from './dataspace-protocol.js';
 export * from './didcomm.js';
 export * from './didcomm-submit.js';
 export * from './didcomm-submit-policy.js';

package/package.json

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