gdc-sdk-front-ts 0.6.2 → 0.6.6

package/dist/gdc-common-utils-ts/src/utils/dataspace-discovery.d.ts

@@ -0,0 +1,235 @@
+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`.
+ *
+ * @param value Semantic `credentialSubject.serviceType` or flattened
+ * `meta.claims['org.schema.Service.serviceType']`.
+ * @returns Normalized unique service capability tokens.
+ *
+ * @example
+ * ```ts
+ * parseServiceTypeCsv('indexing.cruds,digitaltwin.rs');
+ * // ['indexing.cruds', 'digitaltwin.rs']
+ * ```
+ */
+export declare function parseServiceTypeCsv(value: unknown): string[];
+/**
+ * Parses the Schema.org `category` service dimension used as the dataspace
+ * sector vocabulary in the current profile.
+ *
+ * @param value Semantic `credentialSubject.category` or flattened
+ * `meta.claims['org.schema.Service.category']`.
+ * @returns Normalized unique sector/category values.
+ *
+ * @example
+ * ```ts
+ * parseServiceCategories('animal-care,health-care');
+ * // ['animal-care', 'health-care']
+ * ```
+ */
+export declare function parseServiceCategories(value: unknown): string[];
+/**
+ * Parses Schema.org `areaServed` values.
+ *
+ * Accepts scalar strings, CSV strings, arrays, and simple
+ * `AdministrativeArea`-like objects with `name` or `@id`.
+ *
+ * @param value Semantic `credentialSubject.areaServed` or flattened
+ * `meta.claims['org.schema.Service.areaServed']`.
+ * @returns Normalized unique coverage values.
+ *
+ * @example
+ * ```ts
+ * parseAreaServed([{ '@type': 'AdministrativeArea', name: 'EU' }, 'ES']);
+ * // ['EU', 'ES']
+ * ```
+ */
+export declare function parseAreaServed(value: unknown): string[];
+/**
+ * Infers a broader coverage scope from an ISO-2 country code.
+ *
+ * `EU` is returned only as a coverage scope. It must not be treated as a
+ * sector.
+ *
+ * @param countryCode ISO-2 country code, typically from
+ * `credentialSubject.address.addressCountry`.
+ * @returns `EU` for EU member countries, otherwise the normalized country code.
+ *
+ * @example
+ * ```ts
+ * inferCoverageScopeFromCountryCode('ES');
+ * // 'EU'
+ * ```
+ */
+export declare function inferCoverageScopeFromCountryCode(countryCode: string | undefined | null): string | undefined;
+/**
+ * Infers a coverage scope from the semantic `credentialSubject`.
+ *
+ * @param subject Semantic service object containing `address.addressCountry`.
+ * @returns Broader coverage scope such as `EU`, or the normalized country code
+ * when the country is outside the EU set.
+ */
+export declare function inferCoverageScopeFromCredentialSubject(subject: unknown): string | undefined;
+/**
+ * Extracts the shared dataspace service semantics from a VC-like payload.
+ *
+ * Source-of-truth rule:
+ * - semantic values come from `credentialSubject` first
+ * - flattened `meta.claims` is accepted as a compatibility projection/fallback
+ * - when both exist they must agree
+ *
+ * @param input VC-like payload, direct semantic object, or equivalent DTO.
+ * @returns Runtime-neutral normalized dataspace discovery semantics.
+ *
+ * @example
+ * ```ts
+ * extractDataspaceServiceSemanticRecord({
+ *   credentialSubject: {
+ *     id: 'did:web:provider.example.org',
+ *     serviceType: 'indexing.cruds',
+ *     category: 'animal-care',
+ *     areaServed: { '@type': 'AdministrativeArea', name: 'EU' },
+ *     address: { addressCountry: 'ES' },
+ *   },
+ *   meta: {
+ *     claims: {
+ *       'org.schema.Service.serviceType': 'indexing.cruds',
+ *       'org.schema.Service.category': 'animal-care',
+ *       'org.schema.Service.areaServed': 'EU',
+ *       'org.schema.Organization.address.addressCountry': 'ES',
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function extractDataspaceServiceSemanticRecord(input: unknown): DataspaceServiceSemanticRecord;
+/**
+ * Extracts a hosting-operator semantic record from a VC-like payload.
+ *
+ * @param input VC-like payload or direct semantic object.
+ * @returns Hosting-operator semantic record normalized with the common
+ * dataspace extraction rules.
+ */
+export declare function extractHostingOperatorSemanticRecord(input: unknown): HostingOperatorSemanticRecord;
+/**
+ * Extracts a tenant-service semantic record from a VC-like payload.
+ *
+ * @param input VC-like payload or direct semantic object.
+ * @returns Tenant-service semantic record normalized with the common dataspace
+ * extraction rules.
+ */
+export declare function extractTenantServiceSemanticRecord(input: unknown): TenantServiceSemanticRecord;
+/**
+ * Returns whether a normalized hosting-operator record satisfies a service
+ * autodiscovery filter.
+ */
+export declare function matchesHostingOperatorDiscoveryFilter(record: HostingOperatorSemanticRecord, filter: DataspaceDiscoveryFilter): boolean;
+/**
+ * Returns whether a published provider catalog entry satisfies a service
+ * autodiscovery filter.
+ */
+export declare function matchesPublishedProviderDiscoveryFilter(record: PublishedProviderCatalogRecord, filter: DataspaceDiscoveryFilter): boolean;
+/**
+ * Filters hosting-operator records using the shared service-autodiscovery
+ * semantics.
+ */
+export declare function filterHostingOperatorsByDiscoveryFilter(records: ReadonlyArray<HostingOperatorSemanticRecord>, filter: DataspaceDiscoveryFilter): HostingOperatorSemanticRecord[];
+/**
+ * Filters published provider entries using the shared service-autodiscovery
+ * semantics.
+ */
+export declare function filterPublishedProvidersByDiscoveryFilter(records: ReadonlyArray<PublishedProviderCatalogRecord>, filter: DataspaceDiscoveryFilter): PublishedProviderCatalogRecord[];
+/**
+ * Filters a host/operator discovery catalog down to the providers that satisfy
+ * 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;