gdc-common-utils-ts 1.11.0 → 1.13.0

package/README.md

@@ -86,9 +86,60 @@ import { JweObject, JwtCompactParts } from 'gdc-common-utils-ts/models';
 
 ## Cross-Repo Task Docs
 
+- [docs/DATASPACE_DISCOVERY_ROADMAP.md](docs/DATASPACE_DISCOVERY_ROADMAP.md)
+  - cross-repo contract for dataspace discovery semantics, EU coverage
+    inference, shared DTOs, and parameterized examples
 - [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.
@@ -113,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/eu-countries.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ISO 3166-1 alpha-2 country codes that currently belong to the European Union.
+ *
+ * This list is intentionally kept in a runtime-neutral shared package because
+ * dataspace discovery may need to infer a broader coverage scope such as `EU`
+ * from the semantic country carried in a VC `credentialSubject`.
+ */
+export declare const EU_COUNTRY_CODES: readonly ["AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GR", "HU", "IE", "IT", "LV", "LT", "LU", "MT", "NL", "PL", "PT", "RO", "SK", "SI", "ES", "SE"];
+export type EuCountryCode = typeof EU_COUNTRY_CODES[number];
+/**
+ * Normalizes a country code into canonical uppercase ISO-2 form.
+ *
+ * @param countryCode Country code from `credentialSubject.address.addressCountry`
+ * or the flattened operational projection.
+ * @returns Uppercase ISO-2 form or an empty string when the input is blank.
+ *
+ * @example
+ * ```ts
+ * normalizeCountryCode('es');
+ * // 'ES'
+ * ```
+ */
+export declare function normalizeCountryCode(countryCode: string | undefined | null): string;
+/**
+ * Checks whether the supplied country code belongs to the current EU member set.
+ *
+ * @param countryCode ISO-2 country code to evaluate.
+ * @returns `true` when the normalized code belongs to `EU_COUNTRY_CODES`.
+ *
+ * @example
+ * ```ts
+ * isEuCountryCode('ES');
+ * // true
+ * ```
+ */
+export declare function isEuCountryCode(countryCode: string | undefined | null): boolean;

package/dist/constants/eu-countries.js

@@ -0,0 +1,69 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * ISO 3166-1 alpha-2 country codes that currently belong to the European Union.
+ *
+ * This list is intentionally kept in a runtime-neutral shared package because
+ * dataspace discovery may need to infer a broader coverage scope such as `EU`
+ * from the semantic country carried in a VC `credentialSubject`.
+ */
+export const EU_COUNTRY_CODES = Object.freeze([
+    'AT',
+    'BE',
+    'BG',
+    'HR',
+    'CY',
+    'CZ',
+    'DK',
+    'EE',
+    'FI',
+    'FR',
+    'DE',
+    'GR',
+    'HU',
+    'IE',
+    'IT',
+    'LV',
+    'LT',
+    'LU',
+    'MT',
+    'NL',
+    'PL',
+    'PT',
+    'RO',
+    'SK',
+    'SI',
+    'ES',
+    'SE',
+]);
+/**
+ * Normalizes a country code into canonical uppercase ISO-2 form.
+ *
+ * @param countryCode Country code from `credentialSubject.address.addressCountry`
+ * or the flattened operational projection.
+ * @returns Uppercase ISO-2 form or an empty string when the input is blank.
+ *
+ * @example
+ * ```ts
+ * normalizeCountryCode('es');
+ * // 'ES'
+ * ```
+ */
+export function normalizeCountryCode(countryCode) {
+    return String(countryCode || '').trim().toUpperCase();
+}
+/**
+ * Checks whether the supplied country code belongs to the current EU member set.
+ *
+ * @param countryCode ISO-2 country code to evaluate.
+ * @returns `true` when the normalized code belongs to `EU_COUNTRY_CODES`.
+ *
+ * @example
+ * ```ts
+ * isEuCountryCode('ES');
+ * // true
+ * ```
+ */
+export function isEuCountryCode(countryCode) {
+    const normalized = normalizeCountryCode(countryCode);
+    return normalized ? EU_COUNTRY_CODES.includes(normalized) : false;
+}

package/dist/constants/index.d.ts

@@ -1,8 +1,10 @@
 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';
 export * from './fhir-code-systems';
 export * from './fhir-resource-types';
 export * from './fhir-versions';

package/dist/constants/index.js

@@ -1,8 +1,10 @@
 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';
 export * from './fhir-code-systems.js';
 export * from './fhir-resource-types.js';
 export * from './fhir-versions.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/constants/schemaorg.d.ts

@@ -1,5 +1,6 @@
 import { ParameterData } from "../models/params";
 export declare enum ClaimsServiceSchemaorg {
+    areaServed = "org.schema.Service.areaServed",
     category = "org.schema.Service.category",
     identifier = "org.schema.Service.identifier",
     serviceType = "org.schema.Service.serviceType",

package/dist/constants/schemaorg.js

@@ -2,6 +2,7 @@
 // File: src/models/schemaorg.ts
 export var ClaimsServiceSchemaorg;
 (function (ClaimsServiceSchemaorg) {
+    ClaimsServiceSchemaorg["areaServed"] = "org.schema.Service.areaServed";
     ClaimsServiceSchemaorg["category"] = "org.schema.Service.category";
     ClaimsServiceSchemaorg["identifier"] = "org.schema.Service.identifier";
     ClaimsServiceSchemaorg["serviceType"] = "org.schema.Service.serviceType";

package/dist/constants/service-capabilities.d.ts

@@ -75,3 +75,8 @@ export declare function getServiceCapabilityFamily(value: string | undefined): s
  * family.
  */
 export declare function hasServiceCapabilityFamily(value: unknown, family: ServiceCapabilityFamilyValue | string): boolean;
+/**
+ * Returns whether a capability token denotes a discoverable provider/service
+ * role rather than a reader-only role.
+ */
+export declare function isProviderServiceCapability(value: string | undefined | null): boolean;

package/dist/constants/service-capabilities.js

@@ -94,3 +94,12 @@ export function hasServiceCapabilityFamily(value, family) {
         return false;
     return parseServiceCapabilityTokens(value).some((item) => getServiceCapabilityFamily(item) === normalizedFamily);
 }
+/**
+ * Returns whether a capability token denotes a discoverable provider/service
+ * role rather than a reader-only role.
+ */
+export function isProviderServiceCapability(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    return normalized === ServiceCapabilityToken.IndexProvider
+        || normalized === ServiceCapabilityToken.DigitalTwinProvider;
+}

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

@@ -0,0 +1,98 @@
+import type { HostingOperatorDiscoveryCatalog, PublishedProviderCatalogRecord } from '../models/dataspace-discovery';
+export type ExampleDataspaceCredentialSubjectInput = Readonly<{
+    did?: string;
+    serviceTypes?: readonly string[];
+    categories?: readonly string[];
+    areaServed?: readonly string[];
+    addressCountry?: string;
+}>;
+/**
+ * Builds a synthetic hosting-operator semantic `credentialSubject`.
+ *
+ * This example is parameterized on purpose: public docs/tests must not hardcode
+ * business identities when demonstrating dataspace discovery semantics.
+ *
+ * @param input Optional overrides for the synthetic subject.
+ * @returns Schema.org-shaped semantic subject with service metadata.
+ */
+export declare function buildExampleHostingOperatorCredentialSubject(input?: ExampleDataspaceCredentialSubjectInput): {
+    id: string;
+    serviceType: string;
+    category: string;
+    areaServed: {
+        '@type': string;
+        name: string;
+    }[];
+    address: {
+        addressCountry: string;
+    };
+};
+/**
+ * Builds a synthetic tenant-service semantic `credentialSubject`.
+ *
+ * @param input Optional overrides for the synthetic tenant subject.
+ * @returns Schema.org-shaped semantic subject with public service metadata.
+ */
+export declare function buildExampleTenantServiceCredentialSubject(input?: ExampleDataspaceCredentialSubjectInput): {
+    id: string;
+    serviceType: string;
+    category: string;
+    areaServed: {
+        '@type': string;
+        name: string;
+    }[];
+    address: {
+        addressCountry: string;
+    };
+};
+/**
+ * Builds the flattened `meta.claims` projection for a hosting-operator semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export declare function buildExampleHostingOperatorMetaClaims(input?: ExampleDataspaceCredentialSubjectInput): {
+    "org.schema.Service.serviceType": string | undefined;
+    "org.schema.Service.category": string;
+    "org.schema.Service.areaServed": string;
+    "org.schema.Organization.address.addressCountry": string;
+};
+/**
+ * Builds the flattened `meta.claims` projection for a tenant-service semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export declare function buildExampleTenantServiceMetaClaims(input?: ExampleDataspaceCredentialSubjectInput): {
+    "org.schema.Service.serviceType": string | undefined;
+    "org.schema.Service.category": string;
+    "org.schema.Service.areaServed": string;
+    "org.schema.Organization.address.addressCountry": string;
+};
+/**
+ * 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.
+ */
+export declare function buildExamplePublishedProviderCatalogRecord(input?: ExampleDataspaceCredentialSubjectInput): PublishedProviderCatalogRecord;
+/**
+ * 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 declare function buildExampleHostingOperatorDiscoveryCatalog(providers?: ReadonlyArray<PublishedProviderCatalogRecord>): HostingOperatorDiscoveryCatalog;

package/dist/examples/dataspace-discovery.js

@@ -0,0 +1,141 @@
+// 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_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(',');
+}
+/**
+ * Builds a synthetic hosting-operator semantic `credentialSubject`.
+ *
+ * This example is parameterized on purpose: public docs/tests must not hardcode
+ * business identities when demonstrating dataspace discovery semantics.
+ *
+ * @param input Optional overrides for the synthetic subject.
+ * @returns Schema.org-shaped semantic subject with service metadata.
+ */
+export function buildExampleHostingOperatorCredentialSubject(input = {}) {
+    const serviceTypes = input.serviceTypes || [
+        ServiceCapabilityToken.IndexProvider,
+        ServiceCapabilityToken.DigitalTwinProvider,
+    ];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU', EXAMPLE_JURISDICTION];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        id: input.did || 'did:web:host.example.org',
+        serviceType: firstOrCsv(serviceTypes),
+        category: firstOrCsv(categories),
+        areaServed: areaServed.map((name) => ({ '@type': 'AdministrativeArea', name })),
+        address: {
+            addressCountry,
+        },
+    };
+}
+/**
+ * Builds a synthetic tenant-service semantic `credentialSubject`.
+ *
+ * @param input Optional overrides for the synthetic tenant subject.
+ * @returns Schema.org-shaped semantic subject with public service metadata.
+ */
+export function buildExampleTenantServiceCredentialSubject(input = {}) {
+    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU'];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        id: input.did || 'did:web:provider.example.org',
+        serviceType: firstOrCsv(serviceTypes),
+        category: firstOrCsv(categories),
+        areaServed: areaServed.map((name) => ({ '@type': 'AdministrativeArea', name })),
+        address: {
+            addressCountry,
+        },
+    };
+}
+/**
+ * Builds the flattened `meta.claims` projection for a hosting-operator semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export function buildExampleHostingOperatorMetaClaims(input = {}) {
+    const serviceTypes = input.serviceTypes || [
+        ServiceCapabilityToken.IndexProvider,
+        ServiceCapabilityToken.DigitalTwinProvider,
+    ];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU', EXAMPLE_JURISDICTION];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens(serviceTypes),
+        [ClaimsServiceSchemaorg.category]: firstOrCsv(categories),
+        [ClaimsServiceSchemaorg.areaServed]: firstOrCsv(areaServed),
+        [ClaimsOrganizationSchemaorg.addressCountry]: addressCountry,
+    };
+}
+/**
+ * Builds the flattened `meta.claims` projection for a tenant-service semantic
+ * subject.
+ *
+ * @param input Optional overrides for the synthetic projection.
+ * @returns Flat operational claims derived from the semantic subject.
+ */
+export function buildExampleTenantServiceMetaClaims(input = {}) {
+    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU'];
+    const addressCountry = input.addressCountry || EXAMPLE_JURISDICTION;
+    return {
+        [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens(serviceTypes),
+        [ClaimsServiceSchemaorg.category]: firstOrCsv(categories),
+        [ClaimsServiceSchemaorg.areaServed]: firstOrCsv(areaServed),
+        [ClaimsOrganizationSchemaorg.addressCountry]: addressCountry,
+    };
+}
+/**
+ * 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.
+ */
+export function buildExamplePublishedProviderCatalogRecord(input = {}) {
+    const serviceTypes = input.serviceTypes || [ServiceCapabilityToken.IndexProvider];
+    const categories = input.categories || [EXAMPLE_SECTOR];
+    const areaServed = input.areaServed || ['EU'];
+    return {
+        providerDid: input.did || EXAMPLE_TENANT_SERVICE_DID,
+        serviceType: serviceTypes[0] || ServiceCapabilityToken.IndexProvider,
+        category: categories[0] || EXAMPLE_SECTOR,
+        areaServed: firstOrCsv(areaServed) || 'EU',
+        endpointUrl: EXAMPLE_PROVIDER_PUBLISHED_ENDPOINT_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,
+        discoveryUrl: EXAMPLE_HOSTING_OPERATOR_DSPACE_VERSION_URL,
+        catalogUrl: EXAMPLE_HOSTING_OPERATOR_CATALOG_ARTIFACT_URL,
+        providers: [...providers],
+    };
+}

package/dist/examples/index.d.ts

@@ -1,5 +1,6 @@
 export * from './shared';
 export * from './ica-activation-proof';
+export * from './dataspace-discovery';
 export * from './organization-controller';
 export * from './individual-controller';
 export * from './professional';

package/dist/examples/index.js

@@ -1,5 +1,6 @@
 export * from './shared.js';
 export * from './ica-activation-proof.js';
+export * from './dataspace-discovery.js';
 export * from './organization-controller.js';
 export * from './individual-controller.js';
 export * from './professional.js';

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";
@@ -31,6 +31,22 @@ export declare const EXAMPLE_SUBJECT_DID: "did:web:api.acme.org:individual:123";
 export declare const EXAMPLE_PROFESSIONAL_DID: "did:web:api.acme.org:professional:1";
 export declare const EXAMPLE_PROVIDER_ORGANIZATION_DID: "did:web:hospital.acme.org";
 export declare const EXAMPLE_PROVIDER_ORGANIZATION_URL: "https://hospital.acme.org";
+export declare const EXAMPLE_GATEWAY_PUBLIC_ORIGIN: "https://gateway.example.com";
+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_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";
+export declare const EXAMPLE_SECONDARY_PROVIDER_ALTERNATE_NAME: "reader-only";
+export declare const EXAMPLE_COVERAGE_SCOPE_EU: "EU";
+export declare const EXAMPLE_NON_EU_COUNTRY: "US";
+export declare const EXAMPLE_SECONDARY_EU_COUNTRY: "PT";
 export declare const EXAMPLE_PATIENT_DID: "did:web:patient.example";
 export declare const EXAMPLE_PROFILE_PROVIDER_DID: "did:web:provider.example.org";
 export declare const EXAMPLE_PROFILE_ORGANIZATION_DID: "did:web:org.example";
@@ -183,3 +199,10 @@ export declare function buildExampleDocumentReferenceSearchPayload(subjectDid?:
     };
 };
 export declare function cloneExample<T>(value: T): T;
+export type ExampleHostedTenantRouteContext = Readonly<{
+    alternateName: string;
+    jurisdiction: string;
+    version: string;
+    sector: string;
+}>;
+export declare function buildExampleHostedTenantBaseUrl(input: ExampleHostedTenantRouteContext): string;