dataspace-client-sdk-node 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -18,6 +18,10 @@ All notable changes to this project will be documented in this file.
 - Offer/Order process clarified as part of the onboarding contract even when commercial amount is zero:
   - Offer extraction for UI review/acceptance
   - Explicit Order acceptance using offer identifier
+- Activation trust-chain contract aligned with ICA/GW:
+  - `_activate` uses `vp_token` in message payload (not as HTTP Bearer),
+  - legal representative binding relies on `org.schema.Person.memberOf.taxID` and
+    `org.schema.Person.hasCredential.material` for key continuity between `_verify` and `vp_token` signature.
 
 ### Documentation
 - Updated:
@@ -25,4 +29,3 @@ All notable changes to this project will be documented in this file.
 - Clarified:
   - `/host` + `auth` alignment with current gateway model
   - namespace symmetry with ICA (`/ica`) and DataConv (`/publisher`)
-

package/README.md

@@ -6,6 +6,7 @@ Node.js SDK to consume GW/UNID async DIDComm plain endpoints.
 **[→ Data Model Alignment (GW + Chat + SDK)](docs/DATA_MODEL_ALIGNMENT.md)**
 **[→ Frontend/Backend SDK Ownership Matrix](../docs/SDK_AUTH_OWNERSHIP.md)**
 **[→ Developer Use-Case Cookbook (UC5 + additional patterns)](docs/DEVELOPER_USE_CASES.md)**
+**[→ Live Local GW UC5 E2E (no mocks)](docs/E2E_LOCAL_GW_UC5.md)**
 **[→ React Web Integration Guide](docs/REACT_WEB_INTEGRATION.md)**
 **[→ Backend Node Integration Guide](docs/BACKEND_NODE_INTEGRATION.md)**
 **[→ Portal Backend Integration Handover](docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.md)**
@@ -295,7 +296,9 @@ Full runnable example: `examples/backend-pkce-auth.mjs`
   - `client.v1Path(ctx, section, format, resourceType, action)` for tenant routes.
   - `client.hostRegistryPath(ctx, resourceType, action)` for host registry routes.
 - Then call one of:
-  - `submitBatch(path, didcommPayload)` for DIDComm plain submit routes,
+  - `submitBundle(path, didcommPayload)` for DIDComm bundle submit routes (preferred),
+  - `submitBatch(path, didcommPayload)` (legacy alias, kept for compatibility),
+  - `submitLegacyJson(path, payload)` for non-DIDComm JSON routes,
   - `pollBatchResponse(path, { thid })` / `pollUntilComplete(...)`,
   - `postJson(path, payload)` for non-batch JSON routes.
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AsyncPollRequest, BackendPkceAuthOptions, BackendPkceAuthResult, BackendSmartAuthOptions, BackendSmartAuthResult, ClientOptions, CreatePhoneReminderTasksInput, GrantProfessionalAccessSimpleInput, GrantProfessionalAccessSimpleResult, DigitalTwinGenerationInput, EmployeeDeviceActivationInput, EmployeeDeviceActivationSimpleInput, EmployeeDeviceActivationResult, FamilyOrganizationSummary, GatewayOrganizationActivationInput, GatewayOrganizationActivationSimpleInput, HostRouteContext, IpsOrFhirImportInput, MedicationOverlapCheckInput, MedicationRegistrationInput, OrganizationEmployeeCreationInput, PollOptions, PollResult, OfferPreview, RouteContext, SmartTokenExchangeInput, SmartTokenExchangeResult, SmartTokenRequestSimpleInput, LegalOrganizationOrderSimpleInput, SubjectOrganizationBootstrapInput, SubjectOrganizationBootstrapResult, IndividualOrganizationBootstrapSimpleInput, IndividualOrganizationBootstrapSimpleResult, IndividualOrganizationStartSimpleResult, IndividualOrganizationConfirmOrderSimpleInput, SubmitAndPollResult, SubmitResponse, V1Action, V1Section } from './types.js';
+import type { AsyncPollRequest, BackendPkceAuthOptions, BackendPkceAuthResult, BackendSmartAuthOptions, BackendSmartAuthResult, ClientOptions, CreatePhoneReminderTasksInput, GrantProfessionalAccessSimpleInput, GrantProfessionalAccessSimpleResult, DigitalTwinGenerationInput, EmployeeDeviceActivationInput, EndpointSelector, EmployeeDeviceActivationSimpleInput, EmployeeDeviceActivationResult, FamilyOrganizationSummary, GatewayOrganizationActivationInput, GatewayOrganizationActivationSimpleInput, HostRouteContext, IpsOrFhirImportInput, MedicationOverlapCheckInput, MedicationRegistrationInput, OrganizationEmployeeCreationInput, PollOptions, PollResult, OfferPreview, OfferInfo, RouteContext, SmartTokenExchangeInput, SmartTokenExchangeResult, SmartTokenRequestSimpleInput, LegalOrganizationOrderSimpleInput, SubjectOrganizationBootstrapInput, SubjectOrganizationBootstrapResult, IndividualOrganizationBootstrapSimpleInput, IndividualOrganizationBootstrapSimpleResult, IndividualOrganizationStartSimpleResult, IndividualOrganizationConfirmOrderSimpleInput, SubmitAndPollResult, SubmitResponse, V1Action, V1Section } from './types.js';
 import type { WalletProvider } from './sdk/dataspace-wallet-sdk-node/provider.js';
 import type { PublicJwk, WalletContext } from './sdk/dataspace-wallet-sdk-node/types.js';
 export declare class DataspaceNodeClient {
@@ -25,6 +25,14 @@ export declare class DataspaceNodeClient {
     setSector(sector: string): this;
     setDefaultTimeoutSeconds(seconds: number): this;
     setDefaultIntervalSeconds(seconds: number): this;
+    /**
+     * Builds a deterministic endpoint id for token cache and auth/session reuse.
+     * If `providerDid` is provided, returns a full DID service id:
+     *   did:web:...#section:format:resourceType:action
+     * Otherwise returns the canonical fragment without '#':
+     *   section:format:resourceType:action
+     */
+    getEndpointId(selector: EndpointSelector, providerDid?: string): string;
     private resolveSimplePollOptions;
     private requireRouteContext;
     private requireHostRouteContext;
@@ -178,7 +186,7 @@ export declare class DataspaceNodeClient {
      * Returns the cached SMART bearer for the given endpointId if still valid (>30s remaining).
      * Returns `undefined` if not cached or expired.
      */
-    getCachedBearerToken(endpointId: string): string | undefined;
+    getCachedBearerToken(tokenCacheKey: string): string | undefined;
     /**
      * smart-backend.v1: obtain an OAuth2 backend token using client_credentials + private_key_jwt.
      */
@@ -200,6 +208,22 @@ export declare class DataspaceNodeClient {
     private signSmartBackendClientAssertion;
     private preferredJwtAlg;
     /**
+     * POST a DIDComm bundle payload.
+     * This is the preferred high-level method for DIDComm submission of
+     * FHIR/API bundles (batch, transaction, message, etc.).
+     *
+     * Returns immediately with the HTTP response — pair with `pollUntilComplete` or use `submitAndPoll`.
+     */
+    submitBundle(path: string, payload: {
+        thid?: string;
+    } & Record<string, unknown>, options?: {
+        mode?: 'plain' | 'strict';
+        recipientEncryptionJwk?: PublicJwk;
+        walletContext?: WalletContext;
+    }): Promise<SubmitResponse>;
+    /**
+     * @deprecated Use `submitBundle` instead.
+     *
      * POST a DIDComm plaintext payload to a batch submit path.
      * Use this for all `_batch` routes (family registration, observations, tasks, etc.).
      * Content-Type: `application/didcomm-plaintext+json`.
@@ -225,6 +249,11 @@ export declare class DataspaceNodeClient {
      * Content-Type: `application/json`.
      */
     postJson(path: string, payload: unknown): Promise<SubmitResponse>;
+    /**
+     * Legacy JSON submit for non-bundle payloads (openid/token/resource JSON bodies).
+     * Keeps JSON flows explicit and semantically separated from DIDComm bundle flows.
+     */
+    submitLegacyJson(path: string, payload: unknown): Promise<SubmitResponse>;
     /**
      * POST a multipart/form-data payload.
      * Use for file upload endpoints. Prefer `uploadConversionFile` for DataConversion uploads.
@@ -350,6 +379,15 @@ export declare class DataspaceNodeClient {
      * Extract a UI-ready Offer preview from activation/registration responses.
      */
     getOfferPreviewFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferPreview;
+    /**
+     * Alias of `getOfferPreviewFromResponse` with business naming.
+     */
+    getOfferInfoFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferInfo;
+    /**
+     * Extract activation code from response payload or claims.
+     * Supports common response shapes used in onboarding and license issuance flows.
+     */
+    getActivationCodeFromResponse(result: SubmitAndPollResult | PollResult | unknown): string | undefined;
     /**
      * Throws when first DIDComm entry contains a business-level error status.
      */

package/dist/client.js

@@ -1,6 +1,9 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { createDidcommPlainMessage } from './builders.js';
 import { buildConsentClaimsSimpleWithCid } from 'gdc-common-utils-ts/utils/consent';
+import { generateServiceId } from 'gdc-common-utils-ts/utils/did';
+import { submitDidcomm } from 'gdc-common-utils-ts/utils/didcomm-submit';
+import { ClaimsOfferSchemaorg, ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
 import { MedicationStatementClaimsFhirApi, MedicationStatementClaimsFhirApiExtended, } from 'gdc-common-utils-ts/models/interoperable-claims/medication-statement-claims';
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, '');
@@ -99,6 +102,19 @@ export class DataspaceNodeClient {
         }
         return this;
     }
+    /**
+     * Builds a deterministic endpoint id for token cache and auth/session reuse.
+     * If `providerDid` is provided, returns a full DID service id:
+     *   did:web:...#section:format:resourceType:action
+     * Otherwise returns the canonical fragment without '#':
+     *   section:format:resourceType:action
+     */
+    getEndpointId(selector, providerDid) {
+        const fragment = generateServiceId(selector); // #section:format:resourceType:action
+        if (providerDid)
+            return `${providerDid}${fragment}`;
+        return fragment.replace(/^#/, '');
+    }
     resolveSimplePollOptions(timeoutSeconds, intervalSeconds) {
         const pollOptions = {};
         if (Number.isFinite(Number(timeoutSeconds))) {
@@ -386,10 +402,11 @@ export class DataspaceNodeClient {
      * Results are cached in memory; re-runs automatically on expiry.
      */
     async authenticateBackendPkceAndExchange(options) {
-        const { ctx, apiKey, scopes, endpointId = `pkce:${apiKey.slice(0, 8)}`, codeVerifier = randomUUID(), pollOptions, } = options;
-        const cached = this._tokenCache.get(endpointId);
+        const { ctx, apiKey, scopes, tokenCacheKey = `pkce:${apiKey.slice(0, 8)}`, endpointId, codeVerifier = randomUUID(), pollOptions, } = options;
+        const cacheKey = String(tokenCacheKey || endpointId || '').trim() || `pkce:${apiKey.slice(0, 8)}`;
+        const cached = this._tokenCache.get(cacheKey);
         if (cached && cached.expiresAt > Date.now() + 30_000) {
-            return { status: 'cached', endpointId, accessToken: cached.accessToken, tokenType: cached.tokenType, scopes: cached.scopes };
+            return { status: 'cached', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: cached.accessToken, tokenType: cached.tokenType, scopes: cached.scopes };
         }
         const controllerPublicJwk = await this.resolveControllerPublicJwk(options);
         // Step 1: DCR – bind API key to service public key
@@ -402,7 +419,7 @@ export class DataspaceNodeClient {
         await this.submitBatch(this.identityDeviceDcrPath(ctx), dcrPayload);
         const dcrPoll = await this.pollUntilComplete(this.identityDeviceDcrPollPath(ctx), { thid: String(dcrPayload['thid']) }, pollOptions);
         if (dcrPoll.status !== 200) {
-            return { status: 'failed', step: '_dcr', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+            return { status: 'failed', step: '_dcr', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
         }
         // Step 2: Code – PKCE S256 challenge
         const codeChallenge = this._pkceS256Challenge(codeVerifier);
@@ -418,7 +435,7 @@ export class DataspaceNodeClient {
         const codeBody = codePoll.body ?? {};
         const code = String(codeBody['code'] ?? '').trim();
         if (codePoll.status !== 200 || !code) {
-            return { status: 'failed', step: '_code', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+            return { status: 'failed', step: '_code', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
         }
         // Step 3: Token – exchange code + verifier for id_token
         const tokenPayload = this._buildAuthDIDCommRequest({
@@ -433,7 +450,7 @@ export class DataspaceNodeClient {
         const tokenBody = tokenPoll.body ?? {};
         const idToken = String(tokenBody['id_token'] ?? '').trim();
         if (tokenPoll.status !== 200 || !idToken) {
-            return { status: 'failed', step: '_token', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+            return { status: 'failed', step: '_token', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
         }
         // Step 4: Exchange – id_token → SMART bearer
         const exchangeThid = `exchange-${randomUUID()}`;
@@ -451,26 +468,26 @@ export class DataspaceNodeClient {
         const exchangeBody = exchangePoll.body ?? {};
         const accessToken = String(exchangeBody['access_token'] ?? '').trim();
         if (exchangePoll.status !== 200 || !accessToken) {
-            return { status: 'failed', step: '_exchange', endpointId, accessToken: '', tokenType: 'Bearer', scopes };
+            return { status: 'failed', step: '_exchange', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken: '', tokenType: 'Bearer', scopes };
         }
         const tokenType = String(exchangeBody['token_type'] ?? 'Bearer');
         const grantedScope = String(exchangeBody['scope'] ?? '').trim();
         const grantedScopes = grantedScope ? grantedScope.split(' ').filter(Boolean) : scopes;
         const expiresIn = Number(exchangeBody['expires_in'] ?? 0);
-        this._tokenCache.set(endpointId, {
+        this._tokenCache.set(cacheKey, {
             accessToken,
             tokenType,
             scopes: grantedScopes,
             expiresAt: Date.now() + expiresIn * 1000,
         });
-        return { status: 'fetched', endpointId, accessToken, tokenType, scopes: grantedScopes };
+        return { status: 'fetched', tokenCacheKey: cacheKey, endpointId: cacheKey, accessToken, tokenType, scopes: grantedScopes };
     }
     /**
      * Returns the cached SMART bearer for the given endpointId if still valid (>30s remaining).
      * Returns `undefined` if not cached or expired.
      */
-    getCachedBearerToken(endpointId) {
-        const cached = this._tokenCache.get(endpointId);
+    getCachedBearerToken(tokenCacheKey) {
+        const cached = this._tokenCache.get(tokenCacheKey);
         if (cached && cached.expiresAt > Date.now() + 30_000) {
             return cached.accessToken;
         }
@@ -480,13 +497,15 @@ export class DataspaceNodeClient {
      * smart-backend.v1: obtain an OAuth2 backend token using client_credentials + private_key_jwt.
      */
     async authenticateBackendSmartStandard(options) {
-        const { clientId, scopes, endpointId = `smart-backend:${clientId}`, tokenUrl, tokenPath = '/token', audience, assertionTtlSeconds = 300, additionalTokenFields, } = options;
-        const cached = this._tokenCache.get(endpointId);
+        const { clientId, scopes, tokenCacheKey = `smart-backend:${clientId}`, endpointId, tokenUrl, tokenPath = '/token', audience, assertionTtlSeconds = 300, additionalTokenFields, } = options;
+        const cacheKey = String(tokenCacheKey || endpointId || '').trim() || `smart-backend:${clientId}`;
+        const cached = this._tokenCache.get(cacheKey);
         if (cached && cached.expiresAt > Date.now() + 30_000) {
             return {
                 status: 'cached',
                 profile: 'smart-backend.v1',
-                endpointId,
+                tokenCacheKey: cacheKey,
+                endpointId: cacheKey,
                 accessToken: cached.accessToken,
                 tokenType: cached.tokenType,
                 scopes: cached.scopes,
@@ -517,7 +536,8 @@ export class DataspaceNodeClient {
             return {
                 status: 'failed',
                 profile: 'smart-backend.v1',
-                endpointId,
+                tokenCacheKey: cacheKey,
+                endpointId: cacheKey,
                 statusCode: response.status,
                 response,
             };
@@ -527,7 +547,7 @@ export class DataspaceNodeClient {
         const grantedScopes = grantedScope ? grantedScope.split(' ').filter(Boolean) : scopes;
         const expiresIn = Number(body.expires_in ?? 0);
         const expiresAt = Date.now() + expiresIn * 1000;
-        this._tokenCache.set(endpointId, {
+        this._tokenCache.set(cacheKey, {
             accessToken,
             tokenType,
             scopes: grantedScopes,
@@ -536,7 +556,8 @@ export class DataspaceNodeClient {
         return {
             status: 'fetched',
             profile: 'smart-backend.v1',
-            endpointId,
+            tokenCacheKey: cacheKey,
+            endpointId: cacheKey,
             statusCode: response.status,
             accessToken,
             tokenType,
@@ -549,12 +570,12 @@ export class DataspaceNodeClient {
      * Exchange token payload against gateway token endpoint and cache the result.
      */
     async requestSmartToken(input) {
-        const endpointId = String(input.endpointId || '').trim();
-        if (!endpointId) {
-            throw new Error('requestSmartToken requires endpointId.');
+        const tokenCacheKey = String(input.tokenCacheKey || input.endpointId || '').trim();
+        if (!tokenCacheKey) {
+            throw new Error('requestSmartToken requires tokenCacheKey.');
         }
         const normalizedScopes = Array.from(new Set((input.scopes || []).filter(Boolean))).sort();
-        const cached = this._tokenCache.get(endpointId);
+        const cached = this._tokenCache.get(tokenCacheKey);
         if (cached && cached.expiresAt > Date.now() + 30_000) {
             return {
                 status: 'cached',
@@ -579,7 +600,7 @@ export class DataspaceNodeClient {
             : String(body.scope ?? '').trim().split(' ').filter(Boolean);
         const resolvedScopes = grantedScopes.length ? grantedScopes : normalizedScopes;
         const expiresIn = Number(body.expires_in ?? 0);
-        this._tokenCache.set(endpointId, {
+        this._tokenCache.set(tokenCacheKey, {
             accessToken,
             tokenType,
             scopes: resolvedScopes,
@@ -603,9 +624,9 @@ export class DataspaceNodeClient {
             ? { tenantId: input.tenantId, jurisdiction: input.jurisdiction, sector: input.sector }
             : undefined);
         const normalizedScopes = Array.from(new Set((input.scopes || []).filter(Boolean))).sort();
-        const endpointId = String(input.endpointId || `smart:${routeCtx.tenantId}:${normalizedScopes.join(',')}`).trim();
-        if (!endpointId) {
-            throw new Error('requestSmartTokenSimple requires endpointId (or non-empty scopes).');
+        const tokenCacheKey = String(input.tokenCacheKey || input.endpointId || `smart:${routeCtx.tenantId}:${normalizedScopes.join(',')}`).trim();
+        if (!tokenCacheKey) {
+            throw new Error('requestSmartTokenSimple requires tokenCacheKey (or non-empty scopes).');
         }
         const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
         const payload = {
@@ -631,7 +652,7 @@ export class DataspaceNodeClient {
         const grantedScopes = String(exchangeBody.scope || '').trim().split(' ').filter(Boolean);
         const resolvedScopes = grantedScopes.length ? grantedScopes : normalizedScopes;
         const expiresIn = Number(exchangeBody.expires_in ?? 0);
-        this._tokenCache.set(endpointId, {
+        this._tokenCache.set(tokenCacheKey, {
             accessToken,
             tokenType,
             scopes: resolvedScopes,
@@ -762,6 +783,25 @@ export class DataspaceNodeClient {
     }
     // ---- Generic batch API --------------------------------------------------
     /**
+     * POST a DIDComm bundle payload.
+     * This is the preferred high-level method for DIDComm submission of
+     * FHIR/API bundles (batch, transaction, message, etc.).
+     *
+     * Returns immediately with the HTTP response — pair with `pollUntilComplete` or use `submitAndPoll`.
+     */
+    async submitBundle(path, payload, options) {
+        const mode = options?.mode ?? 'plain';
+        if (mode === 'strict') {
+            if (!options?.recipientEncryptionJwk || !options?.walletContext) {
+                throw new Error('submitBundle strict mode requires recipientEncryptionJwk and walletContext.');
+            }
+            return this.submitBatchEncrypted(path, payload, options.recipientEncryptionJwk, options.walletContext);
+        }
+        return this.submitBatch(path, payload);
+    }
+    /**
+     * @deprecated Use `submitBundle` instead.
+     *
      * POST a DIDComm plaintext payload to a batch submit path.
      * Use this for all `_batch` routes (family registration, observations, tasks, etc.).
      * Content-Type: `application/didcomm-plaintext+json`.
@@ -769,13 +809,18 @@ export class DataspaceNodeClient {
      * Returns immediately with the HTTP response — pair with `pollUntilComplete` or use `submitAndPoll`.
      */
     async submitBatch(path, payload) {
-        const response = await this.doPost(path, payload, 'application/didcomm-plaintext+json');
-        const body = await this.parseResponseBody(response);
-        return {
-            status: response.status,
-            location: response.headers.get('location') ?? undefined,
-            body,
-        };
+        const url = /^https?:\/\//.test(path)
+            ? path
+            : `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const result = await submitDidcomm({
+            mode: 'plain',
+            url,
+            payload: payload,
+            defaultHeaders: this.defaultHeaders,
+            bearerToken: this.bearerToken,
+            fetcher: (requestUrl, init) => fetch(requestUrl, init),
+        });
+        return { status: result.status, location: result.location, body: result.body };
     }
     /**
      * Sign and encrypt a DIDComm payload (nested JWS-in-JWE) and POST to the given path.
@@ -792,40 +837,32 @@ export class DataspaceNodeClient {
         }
         const publicJwks = await this.wallet.getPublicJwks(walletContext);
         const signingJwk = publicJwks.find((jwk) => jwk.use === 'sig' || jwk.alg === 'ES384') ?? publicJwks[0];
-        // Step 1: sign payload claims as compact JWS
-        const compactJws = await this.wallet.signCompactJws(walletContext, {
-            header: {
-                typ: 'application/didcomm-signed+json',
-                alg: 'ES384',
-                ...(signingJwk?.kid ? { kid: signingJwk.kid } : {}),
-            },
-            claims: payload,
-        });
-        // Step 2: encrypt JWS string as compact JWE (RSA-OAEP-256 + A256GCM, cty: JWS)
-        const compactJwe = await this.wallet.buildCompactJwe(walletContext, {
-            plaintext: compactJws,
-            recipientJwk: recipientEncryptionJwk,
-            contentType: 'JWS',
-        });
-        // Step 3: POST the JWE token directly (not JSON-serialised)
         const url = /^https?:\/\//.test(path)
             ? path
             : `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
-        const headers = {
-            ...this.defaultHeaders,
-            'Content-Type': 'application/didcomm-encrypted+json',
-            Accept: 'application/json, application/didcomm-plaintext+json, */*',
-        };
-        if (this.bearerToken) {
-            headers.Authorization = `Bearer ${this.bearerToken}`;
-        }
-        const response = await fetch(url, { method: 'POST', headers, body: compactJwe });
-        const body = await this.parseResponseBody(response);
-        return {
-            status: response.status,
-            location: response.headers.get('location') ?? undefined,
-            body,
-        };
+        const result = await submitDidcomm({
+            mode: 'strict',
+            url,
+            payload,
+            defaultHeaders: this.defaultHeaders,
+            bearerToken: this.bearerToken,
+            recipientEncryptionJwk,
+            signCompactJws: async (claims) => this.wallet.signCompactJws(walletContext, {
+                header: {
+                    typ: 'application/didcomm-signed+json',
+                    alg: 'ES384',
+                    ...(signingJwk?.kid ? { kid: signingJwk.kid } : {}),
+                },
+                claims,
+            }),
+            encryptCompactJwe: async (compactJws, recipientJwk) => this.wallet.buildCompactJwe(walletContext, {
+                plaintext: compactJws,
+                recipientJwk: recipientJwk,
+                contentType: 'JWS',
+            }),
+            fetcher: (requestUrl, init) => fetch(requestUrl, init),
+        });
+        return { status: result.status, location: result.location, body: result.body };
     }
     /**
      * POST a plain JSON payload.
@@ -841,6 +878,13 @@ export class DataspaceNodeClient {
             body,
         };
     }
+    /**
+     * Legacy JSON submit for non-bundle payloads (openid/token/resource JSON bodies).
+     * Keeps JSON flows explicit and semantically separated from DIDComm bundle flows.
+     */
+    async submitLegacyJson(path, payload) {
+        return this.postJson(path, payload);
+    }
     /**
      * POST a multipart/form-data payload.
      * Use for file upload endpoints. Prefer `uploadConversionFile` for DataConversion uploads.
@@ -1223,9 +1267,9 @@ export class DataspaceNodeClient {
             'org.schema.Service.category': hostCtx.sector,
             'org.schema.Service.identifier': resolvedServiceDid,
             ...(serviceProviderUrl ? { 'org.schema.Service.url': serviceProviderUrl } : {}),
-            'org.schema.Person.hasOccupation': controllerRole,
-            ...(controllerEmail ? { 'org.schema.Person.email': controllerEmail } : {}),
-            ...(controllerTelephone ? { 'org.schema.Person.telephone': controllerTelephone } : {}),
+            [ClaimsPersonSchemaorg.hasOccupation]: controllerRole,
+            ...(controllerEmail ? { [ClaimsPersonSchemaorg.email]: controllerEmail } : {}),
+            ...(controllerTelephone ? { [ClaimsPersonSchemaorg.telephone]: controllerTelephone } : {}),
         };
         const activation = await this.activateOrganizationInGatewayFromIcaProof(hostCtx, {
             vpToken: input.vpToken,
@@ -1306,8 +1350,8 @@ export class DataspaceNodeClient {
      */
     getOfferIdFromResponse(result) {
         const entry = this.getFirstDidcommDataEntryFromResponse(result);
-        const offerId = String(entry?.meta?.claims?.['org.schema.Offer.identifier']
-            || entry?.resource?.meta?.claims?.['org.schema.Offer.identifier']
+        const offerId = String(entry?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
+            || entry?.resource?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
             || '').trim();
         return offerId || undefined;
     }
@@ -1317,21 +1361,44 @@ export class DataspaceNodeClient {
     getOfferPreviewFromResponse(result) {
         const entry = this.getFirstDidcommDataEntryFromResponse(result);
         const claims = entry?.meta?.claims || entry?.resource?.meta?.claims || {};
-        const seatsRaw = claims['org.schema.Offer.eligibleQuantity.value'];
+        const seatsRaw = claims[ClaimsOfferSchemaorg.eligibleQuantityValue];
         const seats = typeof seatsRaw === 'number'
             ? seatsRaw
             : (typeof seatsRaw === 'string' && seatsRaw.trim() ? Number(seatsRaw) : undefined);
         return {
             offerId: this.getOfferIdFromResponse(result),
-            amount: claims['org.schema.Offer.price'],
-            currency: claims['org.schema.Offer.priceCurrency'],
+            amount: claims[ClaimsOfferSchemaorg.price],
+            currency: claims[ClaimsOfferSchemaorg.priceCurrency],
             seats: Number.isFinite(seats) ? seats : undefined,
-            planName: claims['org.schema.Offer.itemOffered.name'],
-            sku: claims['org.schema.Offer.itemOffered.sku'],
-            paymentMethod: claims['org.schema.Offer.acceptedPaymentMethod'],
-            checkoutUrl: claims['org.schema.Offer.checkoutPageURLTemplate'],
+            planName: claims[ClaimsOfferSchemaorg.itemOfferedName],
+            sku: claims[ClaimsOfferSchemaorg.itemOfferedSku],
+            paymentMethod: claims[ClaimsOfferSchemaorg.acceptedPaymentMethod],
+            checkoutUrl: claims[ClaimsOfferSchemaorg.checkoutPageURLTemplate],
         };
     }
+    /**
+     * Alias of `getOfferPreviewFromResponse` with business naming.
+     */
+    getOfferInfoFromResponse(result) {
+        return this.getOfferPreviewFromResponse(result);
+    }
+    /**
+     * Extract activation code from response payload or claims.
+     * Supports common response shapes used in onboarding and license issuance flows.
+     */
+    getActivationCodeFromResponse(result) {
+        const root = result?.poll?.body || result?.body || {};
+        const byBody = String(root?.activationCode || root?.body?.activationCode || '').trim();
+        if (byBody)
+            return byBody;
+        const entry = this.getFirstDidcommDataEntryFromResponse(result);
+        const claims = entry?.meta?.claims || entry?.resource?.meta?.claims || {};
+        const byClaims = String(claims['org.schema.IndividualProduct.serialNumber']
+            || claims['org.schema.Offer.serialNumber']
+            || claims['activationCode']
+            || '').trim();
+        return byClaims || undefined;
+    }
     /**
      * Throws when first DIDComm entry contains a business-level error status.
      */
@@ -1463,9 +1530,9 @@ export class DataspaceNodeClient {
             '@context': 'org.schema',
             'org.schema.Organization.alternateName': alternateName,
             'org.schema.Service.category': routeCtx.sector,
-            'org.schema.Person.hasOccupation': controllerRole,
-            ...(controllerEmail ? { 'org.schema.Person.email': controllerEmail } : {}),
-            ...(controllerTelephone ? { 'org.schema.Person.telephone': controllerTelephone } : {}),
+            [ClaimsPersonSchemaorg.hasOccupation]: controllerRole,
+            ...(controllerEmail ? { [ClaimsPersonSchemaorg.email]: controllerEmail } : {}),
+            ...(controllerTelephone ? { [ClaimsPersonSchemaorg.telephone]: controllerTelephone } : {}),
             ...(input.additionalClaims || {}),
         };
         const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
@@ -1672,10 +1739,17 @@ export class DataspaceNodeClient {
     }
     async parseResponseBody(response) {
         const contentType = response.headers.get('content-type') || '';
+        const raw = await response.text();
+        if (!raw)
+            return {};
         if (contentType.includes('application/json') || contentType.includes('application/didcomm-plaintext+json')) {
-            return response.json().catch(() => ({}));
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
         }
-        const text = await response.text();
-        return text;
+        return raw;
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
 export * from './builders.js';
+export * from './vp-token.js';
 export * from './client.js';
 export * from './sdk/dataspace-wallet-sdk-node/index.js';

package/dist/index.js

@@ -4,5 +4,6 @@
 // See subjectVaultPhoneResolution.test.ts for context and migration plan.
 export * from './types.js';
 export * from './builders.js';
+export * from './vp-token.js';
 export * from './client.js';
 export * from './sdk/dataspace-wallet-sdk-node/index.js';

package/dist/types.d.ts

@@ -168,6 +168,13 @@ export type OfferPreview = {
     paymentMethod?: string;
     checkoutUrl?: string;
 };
+export type OfferInfo = OfferPreview;
+export type EndpointSelector = {
+    section: string;
+    format: string;
+    resourceType: string;
+    action: string;
+};
 /**
  * Input for organization activation in GW using ICA-derived proof material.
  *
@@ -471,6 +478,8 @@ export type BackendPkceAuthOptions = {
     /** Requested scopes for the SMART bearer token. */
     scopes: string[];
     /** Cache key for the resulting bearer token. Defaults to `pkce:<apiKey prefix>`. */
+    tokenCacheKey?: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId?: string;
     /** PKCE code verifier. Auto-generated with randomUUID if not provided. */
     codeVerifier?: string;
@@ -480,6 +489,8 @@ export type BackendPkceAuthOptions = {
 export type BackendPkceAuthResult = {
     /** `fetched`: new token obtained. `cached`: valid token already in cache. `failed`: flow error. */
     status: 'fetched' | 'cached' | 'failed';
+    tokenCacheKey: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId: string;
     accessToken: string;
     tokenType: string;
@@ -490,6 +501,8 @@ export type BackendPkceAuthResult = {
 export type BackendSmartAuthOptions = {
     clientId: string;
     scopes: string[];
+    tokenCacheKey?: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId?: string;
     tokenUrl?: string;
     tokenPath?: string;
@@ -502,6 +515,8 @@ export type BackendSmartAuthOptions = {
 export type BackendSmartAuthResult = {
     status: 'fetched' | 'cached' | 'failed';
     profile: 'smart-backend.v1';
+    tokenCacheKey: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId: string;
     accessToken?: string;
     tokenType?: string;
@@ -511,7 +526,9 @@ export type BackendSmartAuthResult = {
     response?: unknown;
 };
 export type SmartTokenExchangeInput = {
-    endpointId: string;
+    tokenCacheKey: string;
+    /** @deprecated Use `tokenCacheKey`. */
+    endpointId?: string;
     scopes: string[];
     exchangePayload: Record<string, unknown>;
     path?: string;
@@ -522,6 +539,8 @@ export type SmartTokenRequestSimpleInput = {
     sector?: string;
     idToken: string;
     scopes: string[];
+    tokenCacheKey?: string;
+    /** @deprecated Use `tokenCacheKey`. */
     endpointId?: string;
     timeoutSeconds?: number;
     intervalSeconds?: number;