sos-sdk-node-ts 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.1.18 - 2026-11-03
+
+- Add a trusted Node client for subject-card provider advertisements and
+  federated authorized-subject reads. Provider failures remain visible while
+  successful directories continue to return their cards.
+- Consume `sos-data-utils-ts@0.6.21` and `sos-sdk-core-ts@0.5.4`, the exact
+  published provider-discovery contracts validated by this release.
+
 ## 0.1.17 - 2026-10-22
 
 - Consume the shared historical NCBI OBO taxonomy read compatibility used by

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export * from './server-passkey-profile.js';
 export * from './host-organization-directory-client.js';
 export * from './secure-organization-registration.js';
 export * from './portable-professional-evidence.js';
+export * from './subject-card-provider-catalog-client.js';

package/dist/index.js

@@ -11,3 +11,4 @@ export * from './server-passkey-profile.js';
 export * from './host-organization-directory-client.js';
 export * from './secure-organization-registration.js';
 export * from './portable-professional-evidence.js';
+export * from './subject-card-provider-catalog-client.js';

package/dist/subject-card-provider-catalog-client.d.ts

@@ -0,0 +1,32 @@
+import type { SubjectCardProviderDescriptor } from 'sos-data-utils-ts/subject-card-directory';
+import { type SubjectCardProviderDiscoveryFilter } from 'sos-sdk-core-ts/subject-card-provider-discovery';
+import { type AuthorizedIndividualSubject, type AuthorizedSubjectVerifiedContact } from './subject-card-directory-client.js';
+export type SosSubjectCardProviderCatalogClientOptions = Readonly<{
+    catalogUrl: string;
+    bearerToken?: string;
+    fetchImpl?: typeof fetch;
+}>;
+/** Reads public provider advertisements from a data-space JSON:API catalog. */
+export declare class SosSubjectCardProviderCatalogClient {
+    private readonly catalogUrl;
+    private readonly bearerToken?;
+    private readonly fetchImpl;
+    constructor(options: SosSubjectCardProviderCatalogClientOptions);
+    discover(filter: SubjectCardProviderDiscoveryFilter): Promise<readonly SubjectCardProviderDescriptor[]>;
+}
+export type FederatedProviderSubject = Readonly<{
+    providerId: string;
+    subject: AuthorizedIndividualSubject;
+}>;
+export type FederatedProviderSubjectResult = Readonly<{
+    subjects: readonly FederatedProviderSubject[];
+    unavailableProviderIds: readonly string[];
+}>;
+/** Queries every advertised directory independently and keeps partial success. */
+export declare function readFederatedProviderSubjects(input: Readonly<{
+    providers: readonly SubjectCardProviderDescriptor[];
+    subjectKind?: 'human' | 'animal';
+    verifiedContact: AuthorizedSubjectVerifiedContact;
+    bearerToken?: string;
+    readProvider?: (provider: SubjectCardProviderDescriptor, verifiedContact: AuthorizedSubjectVerifiedContact) => Promise<readonly AuthorizedIndividualSubject[]>;
+}>): Promise<FederatedProviderSubjectResult>;

package/dist/subject-card-provider-catalog-client.js

@@ -0,0 +1,100 @@
+import { discoverSubjectCardProviders, } from 'sos-sdk-core-ts/subject-card-provider-discovery';
+import { SosGatewaySubjectDirectoryClient, } from './subject-card-directory-client.js';
+/** Reads public provider advertisements from a data-space JSON:API catalog. */
+export class SosSubjectCardProviderCatalogClient {
+    catalogUrl;
+    bearerToken;
+    fetchImpl;
+    constructor(options) {
+        this.catalogUrl = secureUrl(options.catalogUrl);
+        this.bearerToken = optional(options.bearerToken);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async discover(filter) {
+        const url = new URL(this.catalogUrl);
+        url.searchParams.set('subjectKind', filter.subjectKind);
+        url.searchParams.set('operation', filter.operation);
+        const response = await this.fetchImpl(url, {
+            headers: {
+                Accept: 'application/vnd.api+json',
+                ...(this.bearerToken ? { Authorization: `Bearer ${this.bearerToken}` } : {}),
+            },
+        });
+        if (!response.ok)
+            throw new Error(`provider_catalog_failed:${response.status}`);
+        const body = await response.json();
+        if (!Array.isArray(body.data))
+            throw new Error('provider_catalog_response_invalid');
+        const catalog = body.data.map(entry => {
+            const row = record(entry);
+            if (row.type !== 'subject-card-provider')
+                throw new Error('provider_catalog_entry_invalid');
+            return record(row.attributes);
+        });
+        return discoverSubjectCardProviders(catalog, filter);
+    }
+}
+/** Queries every advertised directory independently and keeps partial success. */
+export async function readFederatedProviderSubjects(input) {
+    const providers = discoverSubjectCardProviders(input.providers, {
+        subjectKind: input.subjectKind ?? commonSubjectKind(input.providers),
+        operation: 'directory',
+    });
+    const readProvider = input.readProvider ?? (async (provider) => {
+        const route = parseDirectoryRoute(provider.directoryRoute);
+        const client = new SosGatewaySubjectDirectoryClient({
+            baseUrl: route.baseUrl,
+            bearerToken: input.bearerToken,
+        });
+        return client.listAuthorizedIndividualSubjects(route.context, {
+            verifiedContact: input.verifiedContact,
+        });
+    });
+    const settled = await Promise.allSettled(providers.map(provider => readProvider(provider, input.verifiedContact)));
+    const subjects = [];
+    const unavailableProviderIds = [];
+    for (const [index, result] of settled.entries()) {
+        const provider = providers[index];
+        if (result.status === 'rejected') {
+            unavailableProviderIds.push(provider.providerId);
+            continue;
+        }
+        for (const subject of result.value)
+            subjects.push(Object.freeze({ providerId: provider.providerId, subject }));
+    }
+    return Object.freeze({
+        subjects: Object.freeze(subjects),
+        unavailableProviderIds: Object.freeze(unavailableProviderIds),
+    });
+}
+function commonSubjectKind(providers) {
+    const kinds = new Set(providers.flatMap(provider => provider.subjectKinds));
+    if (kinds.size !== 1)
+        throw new Error('provider_subject_kind_filter_required');
+    return [...kinds][0];
+}
+function parseDirectoryRoute(value) {
+    const url = secureUrl(value);
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (segments.length !== 4 || !segments[1]?.startsWith('cds-') || segments[2] !== 'v1') {
+        throw new Error('provider_directory_route_invalid');
+    }
+    return Object.freeze({
+        baseUrl: url.origin,
+        context: Object.freeze({ tenantId: segments[0], jurisdiction: segments[1].slice(4), sector: segments[3] }),
+    });
+}
+function secureUrl(value) {
+    const url = new URL(value);
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local))
+        throw new Error('provider_url_insecure');
+    return url;
+}
+function optional(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sos-sdk-node-ts",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Product-neutral Node adapters shared by SOSChain, Vet and UHC runtimes",
   "license": "Apache-2.0",
   "author": "Connecting Solution & Applications Ltd",
@@ -59,6 +59,10 @@
     "./portable-professional-evidence": {
       "types": "./dist/portable-professional-evidence.d.ts",
       "default": "./dist/portable-professional-evidence.js"
+    },
+    "./subject-card-provider-catalog-client": {
+      "types": "./dist/subject-card-provider-catalog-client.d.ts",
+      "default": "./dist/subject-card-provider-catalog-client.js"
     }
   },
   "files": [
@@ -80,8 +84,8 @@
     "@simplewebauthn/server": "13.3.2",
     "gdc-common-utils-ts": "2.9.30",
     "gdc-sdk-node-ts": "2.9.32",
-    "sos-data-utils-ts": "0.6.17",
-    "sos-sdk-core-ts": "0.5.2"
+    "sos-data-utils-ts": "0.6.21",
+    "sos-sdk-core-ts": "0.5.4"
   },
   "devDependencies": {
     "@types/node": "^24.10.0",