gdc-sdk-node-ts 0.6.2 → 0.6.4

package/README.md

@@ -73,10 +73,13 @@ Open these tests when you want to see exact method calls and exact inputs:
 - [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.
+- [tests/default-first-dataspace-discovery.101.test.mjs](tests/default-first-dataspace-discovery.101.test.mjs)
+  Portal-style `default-first` discovery with simple `getHosts(...)`,
+  `getIndexProviders(...)`, and `getDigitalTwinProviders(...)` calls.
 
 ## Dataspace Discovery Quick Map
 
-Use the Node resolver when your backend or BFF needs to:
+Use the Node discovery layer when your backend or BFF needs to:
 
 - start from preloaded hosting-operator semantics
 - fetch the canonical `/.well-known/dspace-version` entrypoint
@@ -86,24 +89,26 @@ Use the Node resolver when your backend or BFF needs to:
 Primary references:
 
 - [docs/DISCOVERY_101.md](./docs/DISCOVERY_101.md)
+- [tests/default-first-dataspace-discovery.101.test.mjs](tests/default-first-dataspace-discovery.101.test.mjs)
 - [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
+import { createDefaultFirstDataspaceDiscovery } from 'gdc-sdk-node-ts';
+import { DataspaceSectors } from 'gdc-common-utils-ts';
+import { HostNetworkTypes } from 'gdc-common-utils-ts/constants/network';
+
+const discovery = createDefaultFirstDataspaceDiscovery({
+  version: 'v1',
+  networkType: HostNetworkTypes.Test,
+  defaults,
 });
 
-const providers = await resolver.resolvePublishedProviders({
-  sector: 'animal-care',
+const providers = await discovery.getIndexProviders({
+  sector: DataspaceSectors.AnimalCare,
   jurisdiction: 'ES',
-  providerCapability: ServiceCapabilityToken.IndexProvider,
 });
 ```
 

package/dist/discovery/DefaultFirstDataspaceDiscovery.d.ts

@@ -0,0 +1,44 @@
+import type { DefaultFirstDataspaceDiscoveryOptions, GetDataspaceHostsInput, HostingOperatorMatch, PublishedProviderMatch, SimpleDataspaceDiscoveryRequest } from './types.js';
+/**
+ * High-level default-first discovery facade for portal/backend integrations.
+ *
+ * Intended usage:
+ * - configure ICA/hosting defaults once during backend startup
+ * - later ask simple questions per request:
+ *   - `getHosts({ sector, jurisdiction })`
+ *   - `getIndexProviders({ sector, jurisdiction })`
+ *   - `getDigitalTwinProviders({ sector, jurisdiction })`
+ *
+ * The facade keeps the bootstrap-plan plumbing internal so app code does not
+ * need to understand the lower-level defaults registry or resolver wiring.
+ */
+export declare class DefaultFirstDataspaceDiscovery {
+    private readonly defaultsRegistry;
+    private readonly version;
+    private readonly networkType;
+    private readonly fetcher?;
+    constructor(options: DefaultFirstDataspaceDiscoveryOptions);
+    /**
+     * Returns matching hosting operators for one `sector + jurisdiction`
+     * request using the configured default-first bootstrap policy.
+     */
+    getHosts(input: GetDataspaceHostsInput): Promise<HostingOperatorMatch[]>;
+    /**
+     * Returns published `IndexProvider` services for one `sector + jurisdiction`
+     * request.
+     */
+    getIndexProviders(input: SimpleDataspaceDiscoveryRequest): Promise<PublishedProviderMatch[]>;
+    /**
+     * Returns published `DigitalTwinProvider` services for one
+     * `sector + jurisdiction` request.
+     */
+    getDigitalTwinProviders(input: SimpleDataspaceDiscoveryRequest): Promise<PublishedProviderMatch[]>;
+    private getProviders;
+    private createResolver;
+    private buildBootstrapPlan;
+    private resolveDefaultPublishedProviders;
+}
+/**
+ * Convenience factory for the default-first portal/backend discovery facade.
+ */
+export declare function createDefaultFirstDataspaceDiscovery(options: DefaultFirstDataspaceDiscoveryOptions): DefaultFirstDataspaceDiscovery;

package/dist/discovery/DefaultFirstDataspaceDiscovery.js

@@ -0,0 +1,163 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { DataspaceCoverageScope, DataspaceDiscoverySourceMode, ServiceCapabilityToken, createDataspaceDiscoveryDefaultsRegistry, DataspaceProtocolVersions, inferCoverageScopeFromCountryCode, isProviderServiceCapability, normalizeCountryCode, } from 'gdc-common-utils-ts';
+import { HttpDataspaceResolver } from './HttpDataspaceResolver.js';
+function normalizeString(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) => normalizeString(entry)).filter(Boolean);
+    }
+    const raw = normalizeString(value);
+    if (!raw)
+        return [];
+    return raw.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+function buildCoverageTokens(areaServed, filterJurisdiction) {
+    const tokens = new Set(splitTokens(areaServed).map((token) => token.toUpperCase()));
+    const normalizedJurisdiction = normalizeCountryCode(filterJurisdiction);
+    if (normalizedJurisdiction) {
+        const inferred = inferCoverageScopeFromCountryCode(normalizedJurisdiction);
+        if (inferred)
+            tokens.add(inferred.toUpperCase());
+    }
+    return tokens;
+}
+function matchesProviderCoverage(provider, jurisdiction, coverageScope) {
+    const normalizedJurisdiction = normalizeCountryCode(jurisdiction);
+    const normalizedCoverageScope = normalizeString(coverageScope).toUpperCase();
+    if (!normalizedJurisdiction && !normalizedCoverageScope)
+        return true;
+    const tokens = buildCoverageTokens(provider.areaServed, jurisdiction);
+    if (normalizedJurisdiction && tokens.has(normalizedJurisdiction))
+        return true;
+    if (normalizedCoverageScope && tokens.has(normalizedCoverageScope))
+        return true;
+    if (normalizedCoverageScope === DataspaceCoverageScope.EuropeanUnion) {
+        return Array.from(tokens).some((token) => inferCoverageScopeFromCountryCode(token) === DataspaceCoverageScope.EuropeanUnion);
+    }
+    return false;
+}
+function matchesDefaultPublishedProvider(provider, input, providerCapability) {
+    if (!equalsIgnoreCase(provider.category, input.sector))
+        return false;
+    if (!isProviderServiceCapability(provider.serviceType))
+        return false;
+    if (!equalsIgnoreCase(provider.serviceType, providerCapability))
+        return false;
+    if (!matchesProviderCoverage(provider, input.jurisdiction, input.coverageScope))
+        return false;
+    return true;
+}
+function isDefaultsRegistry(value) {
+    return Boolean(value)
+        && typeof value === 'object'
+        && 'buildBootstrapPlan' in value
+        && typeof value.buildBootstrapPlan === 'function';
+}
+/**
+ * High-level default-first discovery facade for portal/backend integrations.
+ *
+ * Intended usage:
+ * - configure ICA/hosting defaults once during backend startup
+ * - later ask simple questions per request:
+ *   - `getHosts({ sector, jurisdiction })`
+ *   - `getIndexProviders({ sector, jurisdiction })`
+ *   - `getDigitalTwinProviders({ sector, jurisdiction })`
+ *
+ * The facade keeps the bootstrap-plan plumbing internal so app code does not
+ * need to understand the lower-level defaults registry or resolver wiring.
+ */
+export class DefaultFirstDataspaceDiscovery {
+    constructor(options) {
+        this.defaultsRegistry = isDefaultsRegistry(options.defaults)
+            ? options.defaults
+            : createDataspaceDiscoveryDefaultsRegistry(options.defaults);
+        this.version = normalizeString(options.version) || DataspaceProtocolVersions.Current;
+        this.networkType = normalizeString(options.networkType);
+        this.fetcher = options.fetcher;
+    }
+    /**
+     * Returns matching hosting operators for one `sector + jurisdiction`
+     * request using the configured default-first bootstrap policy.
+     */
+    async getHosts(input) {
+        const resolver = this.createResolver(input, input.requiredCapabilities || []);
+        return resolver.resolveHostingOperators({
+            sector: input.sector,
+            jurisdiction: input.jurisdiction,
+            coverageScope: input.coverageScope,
+            requiredCapabilities: [...(input.requiredCapabilities || [])],
+        });
+    }
+    /**
+     * Returns published `IndexProvider` services for one `sector + jurisdiction`
+     * request.
+     */
+    async getIndexProviders(input) {
+        return this.getProviders(input, ServiceCapabilityToken.IndexProvider);
+    }
+    /**
+     * Returns published `DigitalTwinProvider` services for one
+     * `sector + jurisdiction` request.
+     */
+    async getDigitalTwinProviders(input) {
+        return this.getProviders(input, ServiceCapabilityToken.DigitalTwinProvider);
+    }
+    async getProviders(input, providerCapability) {
+        const bootstrapPlan = this.buildBootstrapPlan(input, [providerCapability]);
+        const defaultPublishedProviders = this.resolveDefaultPublishedProviders(bootstrapPlan.hostingOperators, input, providerCapability);
+        if (defaultPublishedProviders.length > 0) {
+            return defaultPublishedProviders;
+        }
+        const resolver = new HttpDataspaceResolver({
+            hostingOperators: bootstrapPlan.hostingOperators,
+            fetcher: this.fetcher,
+        });
+        return resolver.resolvePublishedProviders({
+            sector: input.sector,
+            jurisdiction: input.jurisdiction,
+            coverageScope: input.coverageScope,
+            providerCapability,
+        });
+    }
+    createResolver(input, requiredCapabilities) {
+        const bootstrapPlan = this.buildBootstrapPlan(input, requiredCapabilities);
+        return new HttpDataspaceResolver({
+            hostingOperators: bootstrapPlan.hostingOperators,
+            fetcher: this.fetcher,
+        });
+    }
+    buildBootstrapPlan(input, requiredCapabilities) {
+        return this.defaultsRegistry.buildBootstrapPlan({
+            jurisdiction: input.jurisdiction,
+            version: this.version,
+            networkType: this.networkType,
+            sector: input.sector,
+            coverageScope: input.coverageScope,
+            requiredCapabilities,
+            sourceMode: DataspaceDiscoverySourceMode.DefaultFirst,
+        });
+    }
+    resolveDefaultPublishedProviders(hosts, input, providerCapability) {
+        return hosts.flatMap((host) => (host.publishedProviders || [])
+            .filter((provider) => matchesDefaultPublishedProvider(provider, input, providerCapability))
+            .map((provider) => ({
+            providerDid: provider.providerDid,
+            record: provider,
+            hostingOperator: host.record,
+            hostingOperatorDid: host.operatorDid,
+            discoveryUrl: provider.discoveryUrl || host.discoveryUrl,
+            catalogUrl: provider.catalogUrl || host.catalogUrl,
+        })));
+    }
+}
+/**
+ * Convenience factory for the default-first portal/backend discovery facade.
+ */
+export function createDefaultFirstDataspaceDiscovery(options) {
+    return new DefaultFirstDataspaceDiscovery(options);
+}

package/dist/discovery/index.d.ts

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

package/dist/discovery/index.js

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

package/dist/discovery/types.d.ts

@@ -1,4 +1,4 @@
-import type { DataspaceDiscoveryFilter, HostingOperatorDiscoveryCatalog, HostingOperatorSemanticRecord, PublishedProviderCatalogRecord, TenantServiceSemanticRecord } from 'gdc-common-utils-ts';
+import type { DataspaceDiscoveryDefaultsRegistry, DataspaceDiscoveryDefaultsRegistrySeed, DataspaceDiscoveryFilter, HostingOperatorDiscoveryCatalog, HostingOperatorSemanticRecord, PublishedProviderCatalogRecord, TenantServiceSemanticRecord } from 'gdc-common-utils-ts';
 /**
  * Input for resolving hosting operators that can serve a given dataspace use
  * case.
@@ -40,6 +40,34 @@ export type HttpDataspaceResolverOptions = Readonly<{
     fetcher?: typeof fetch;
     requestHeaders?: Record<string, string>;
 }>;
+/**
+ * Minimal request shape for portal/backend discovery calls after defaults have
+ * already been configured at startup.
+ */
+export type SimpleDataspaceDiscoveryRequest = Readonly<{
+    sector: string;
+    jurisdiction: string;
+    coverageScope?: string;
+}>;
+/**
+ * Input for retrieving eligible hosts from the default-first discovery facade.
+ */
+export type GetDataspaceHostsInput = SimpleDataspaceDiscoveryRequest & Readonly<{
+    requiredCapabilities?: readonly string[];
+}>;
+/**
+ * Construction options for the default-first portal/backend discovery facade.
+ *
+ * This API intentionally keeps startup configuration separate from the
+ * per-request `sector + jurisdiction` queries used later by frontend-facing
+ * backends.
+ */
+export type DefaultFirstDataspaceDiscoveryOptions = Readonly<{
+    version?: string;
+    networkType: string;
+    defaults?: DataspaceDiscoveryDefaultsRegistry | DataspaceDiscoveryDefaultsRegistrySeed;
+    fetcher?: typeof fetch;
+}>;
 /**
  * Normalized hosting-operator match returned by a node/BFF resolver.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -17,7 +17,7 @@
     "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.14.2",
+    "gdc-common-utils-ts": "file:../gdc-common-utils-ts",
     "gdc-sdk-core-ts": "^0.6.3"
   },
   "devDependencies": {