dataspace-client-sdk-node 0.1.2 → 0.2.1

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;

package/dist/vp-token.d.ts

@@ -0,0 +1,37 @@
+export type VpTokenHeader = {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [key: string]: unknown;
+};
+export type VpTokenPayload = {
+    iss: string;
+    sub?: string;
+    aud?: string;
+    jti?: string;
+    iat?: number;
+    exp?: number;
+    nonce?: string;
+    vp: {
+        '@context'?: unknown;
+        type?: unknown;
+        holder?: string;
+        verifiableCredential: string[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+export declare function generateUuidLike(): string;
+export declare function buildEpochWindow(ttlSeconds?: number): {
+    iat: number;
+    exp: number;
+};
+export declare function createVP(input?: Partial<VpTokenPayload>): VpTokenPayload;
+export declare function addVC(vpPayload: VpTokenPayload, vcJwt: string): VpTokenPayload;
+export declare function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
+    encodedHeader: string;
+    encodedPayload: string;
+    signingInput: string;
+};
+export declare function prepareBytesForSignature(header: VpTokenHeader, payload: VpTokenPayload): Uint8Array;
+export declare function buildVpTokenCompact(encodedHeader: string, encodedPayload: string, signatureBase64Url: string): string;

package/dist/vp-token.js

@@ -0,0 +1,56 @@
+function toB64UrlJson(input) {
+    return Buffer.from(JSON.stringify(input), 'utf-8').toString('base64url');
+}
+function fallbackId() {
+    const rand = Math.random().toString(36).slice(2, 10);
+    return `id-${Date.now()}-${rand}`;
+}
+export function generateUuidLike() {
+    const fn = globalThis?.crypto?.randomUUID;
+    if (typeof fn === 'function')
+        return fn.call(globalThis.crypto);
+    return fallbackId();
+}
+export function buildEpochWindow(ttlSeconds = 300) {
+    const iat = Math.floor(Date.now() / 1000);
+    return { iat, exp: iat + Math.max(1, Math.floor(ttlSeconds)) };
+}
+export function createVP(input) {
+    const ttl = input?.exp && input?.iat ? undefined : buildEpochWindow(300);
+    const jti = input?.jti || generateUuidLike();
+    const nonce = input?.nonce || generateUuidLike();
+    return {
+        iss: String(input?.iss || ''),
+        sub: input?.sub,
+        aud: input?.aud,
+        jti,
+        iat: input?.iat ?? ttl?.iat,
+        exp: input?.exp ?? ttl?.exp,
+        nonce,
+        vp: {
+            '@context': ['https://www.w3.org/2018/credentials/v1'],
+            type: ['VerifiablePresentation'],
+            holder: input?.vp?.holder || input?.iss || '',
+            verifiableCredential: [],
+            ...(input?.vp || {}),
+        },
+    };
+}
+export function addVC(vpPayload, vcJwt) {
+    const v = String(vcJwt || '').trim();
+    if (v)
+        vpPayload.vp.verifiableCredential.push(v);
+    return vpPayload;
+}
+export function prepareForSignature(header, payload) {
+    const encodedHeader = toB64UrlJson(header);
+    const encodedPayload = toB64UrlJson(payload);
+    return { encodedHeader, encodedPayload, signingInput: `${encodedHeader}.${encodedPayload}` };
+}
+export function prepareBytesForSignature(header, payload) {
+    const { signingInput } = prepareForSignature(header, payload);
+    return new TextEncoder().encode(signingInput);
+}
+export function buildVpTokenCompact(encodedHeader, encodedPayload, signatureBase64Url) {
+    return `${encodedHeader}.${encodedPayload}.${String(signatureBase64Url || '').trim()}`;
+}

package/docs/API.md

@@ -478,22 +478,33 @@ const token = client.getCachedBearerToken('pkce:my-api-key');
 
 ## Transport methods
 
-### `submitBatch`
+### `submitBundle`
 
-POST a DIDComm plaintext payload (`application/didcomm-plaintext+json`).
+POST a DIDComm bundle payload. Preferred API for FHIR/API bundle operations.
 
 ```ts
-submitBatch(path: string, payload: unknown): Promise<SubmitResponse>
+submitBundle(
+  path: string,
+  payload: { thid?: string } & Record<string, unknown>,
+  options?: {
+    mode?: 'plain' | 'strict';
+    recipientEncryptionJwk?: PublicJwk;
+    walletContext?: WalletContext;
+  },
+): Promise<SubmitResponse>
 ```
 
 ```ts
-const { status, location } = await client.submitBatch(
+const { status, location } = await client.submitBundle(
   client.individualTaskBatchPath(ctx),
   payload,
+  { mode: 'plain' },
 );
 // location header contains the poll URL
 ```
 
+`submitBatch(...)` remains available as a legacy alias for compatibility.
+
 ---
 
 ### `submitBatchEncrypted`
@@ -531,6 +542,10 @@ POST a plain JSON body (`application/json`). Use for token endpoints and API key
 postJson(path: string, payload: unknown): Promise<SubmitResponse>
 ```
 
+### `submitLegacyJson`
+
+Alias of `postJson(...)` for explicit non-bundle JSON submits (openid/token/resource payloads).
+
 ```ts
 const response = await client.postJson('/host/admin/api-keys', {
   agent: { email: 'service@example.com' },