dataspace-client-sdk-node 0.1.1 → 0.2.0

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(/\/+$/, '');
@@ -8,21 +11,144 @@ function trimTrailingSlash(value) {
 function encode(value) {
     return encodeURIComponent(value);
 }
+function toDidWebFromUrlOrHost(raw) {
+    const v = String(raw || '').trim();
+    if (!v)
+        return undefined;
+    if (v.startsWith('did:web:'))
+        return v;
+    const host = v
+        .replace(/^https?:\/\//i, '')
+        .replace(/\/.*$/, '')
+        .trim()
+        .toLowerCase();
+    if (!host)
+        return undefined;
+    return `did:web:${host}`;
+}
+function parseRetryAfterMs(header) {
+    if (!header)
+        return undefined;
+    const raw = header.trim();
+    if (!raw)
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.floor(seconds * 1000);
+    }
+    const epochMs = Date.parse(raw);
+    if (Number.isFinite(epochMs)) {
+        const delta = epochMs - Date.now();
+        return delta > 0 ? delta : 0;
+    }
+    return undefined;
+}
 export class DataspaceNodeClient {
     baseUrl;
     bearerToken;
     defaultHeaders;
     wallet;
+    defaultCtx;
+    defaultTimeoutMs;
+    defaultIntervalMs;
     _tokenCache = new Map();
     constructor(options) {
         this.baseUrl = trimTrailingSlash(options.baseUrl);
         this.bearerToken = options.bearerToken;
         this.defaultHeaders = options.defaultHeaders ?? {};
         this.wallet = options.wallet;
+        this.defaultCtx = options.ctx;
     }
     getWallet() {
         return this.wallet;
     }
+    /**
+     * Set default route context for subsequent calls.
+     */
+    setContext(ctx) {
+        this.defaultCtx = { ...ctx };
+        return this;
+    }
+    /**
+     * Preferred alias for organization/tenant integration context.
+     */
+    setContextOrg(ctx) {
+        return this.setContext(ctx);
+    }
+    setTenantId(tenantId) {
+        const current = this.defaultCtx ?? { tenantId: '', jurisdiction: '', sector: '' };
+        this.defaultCtx = { ...current, tenantId };
+        return this;
+    }
+    setJurisdiction(jurisdiction) {
+        const current = this.defaultCtx ?? { tenantId: '', jurisdiction: '', sector: '' };
+        this.defaultCtx = { ...current, jurisdiction };
+        return this;
+    }
+    setSector(sector) {
+        const current = this.defaultCtx ?? { tenantId: '', jurisdiction: '', sector: '' };
+        this.defaultCtx = { ...current, sector };
+        return this;
+    }
+    setDefaultTimeoutSeconds(seconds) {
+        if (Number.isFinite(Number(seconds))) {
+            this.defaultTimeoutMs = Math.max(1, Math.floor(Number(seconds) * 1000));
+        }
+        return this;
+    }
+    setDefaultIntervalSeconds(seconds) {
+        if (Number.isFinite(Number(seconds))) {
+            this.defaultIntervalMs = Math.max(1, Math.floor(Number(seconds) * 1000));
+        }
+        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))) {
+            pollOptions.timeoutMs = Math.max(1, Math.floor(Number(timeoutSeconds) * 1000));
+        }
+        else if (this.defaultTimeoutMs) {
+            pollOptions.timeoutMs = this.defaultTimeoutMs;
+        }
+        if (Number.isFinite(Number(intervalSeconds))) {
+            pollOptions.intervalMs = Math.max(1, Math.floor(Number(intervalSeconds) * 1000));
+        }
+        else if (this.defaultIntervalMs) {
+            pollOptions.intervalMs = this.defaultIntervalMs;
+        }
+        return Object.keys(pollOptions).length ? pollOptions : undefined;
+    }
+    requireRouteContext(ctx) {
+        const resolved = ctx ?? this.defaultCtx;
+        const tenantId = String(resolved?.tenantId || '').trim();
+        const jurisdiction = String(resolved?.jurisdiction || '').trim();
+        const sector = String(resolved?.sector || '').trim();
+        if (!tenantId || !jurisdiction || !sector) {
+            throw new Error('Route context is required. Provide `ctx` in method call or constructor options.');
+        }
+        return { tenantId, jurisdiction, sector };
+    }
+    requireHostRouteContext(ctx) {
+        const jurisdiction = String(ctx?.jurisdiction || this.defaultCtx?.jurisdiction || '').trim();
+        const sector = String(ctx?.sector || this.defaultCtx?.sector || '').trim();
+        if (jurisdiction && sector) {
+            return { jurisdiction, sector };
+        }
+        throw new Error('Host route context is required. Provide `ctx` in method call or constructor options.ctx.');
+    }
     // ---- Path helpers -------------------------------------------------------
     /**
      * Generic GW v1 tenant route builder.
@@ -36,7 +162,8 @@ export class DataspaceNodeClient {
      * // → /acme/cds-ES/v1/health-care/individual/org.schema/Organization/_batch
      */
     v1Path(ctx, section, format, resourceType, action) {
-        return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/${encode(section)}/${encode(format)}/${encode(resourceType)}/${encode(action)}`;
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encode(routeCtx.tenantId)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/${encode(section)}/${encode(format)}/${encode(resourceType)}/${encode(action)}`;
     }
     /**
      * Generic tenant-scoped identity route builder.
@@ -46,7 +173,8 @@ export class DataspaceNodeClient {
      * Dedicated path methods in this SDK use `host` (GW convention).
      */
     tenantIdentityPath(ctx, prefix, action) {
-        return `/${encode(prefix)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/${encode(ctx.tenantId)}/identity/auth/${encode(action)}`;
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encode(prefix)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/${encode(routeCtx.tenantId)}/identity/auth/${encode(action)}`;
     }
     /**
      * Generic host registry route builder (tenant-agnostic, `host/` prefix).
@@ -55,7 +183,8 @@ export class DataspaceNodeClient {
      * Pattern: `/host/cds-{jurisdiction}/v1/{sector}/registry/org.schema/{resourceType}/{action}`
      */
     hostRegistryPath(ctx, resourceType, action) {
-        return `/host/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/registry/org.schema/${encode(resourceType)}/${encode(action)}`;
+        const hostCtx = this.requireHostRouteContext(ctx);
+        return `/host/cds-${encode(hostCtx.jurisdiction)}/v1/${encode(hostCtx.sector)}/registry/org.schema/${encode(resourceType)}/${encode(action)}`;
     }
     /** Submit path: host registry Organization batch (controller-level org registration). */
     hostRegistryOrganizationBatchPath(ctx) {
@@ -86,11 +215,13 @@ export class DataspaceNodeClient {
      * Use for `family-registration/_create-or-resume` DIDComm payloads.
      */
     individualFamilyOrganizationBatchPath(ctx) {
-        return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Organization/_batch`;
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encode(routeCtx.tenantId)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/individual/org.schema/Organization/_batch`;
     }
     /** Poll path: individual/family Organization. Pair with `individualFamilyOrganizationBatchPath`. */
     individualFamilyOrganizationPollPath(ctx) {
-        return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Organization/_batch-response`;
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encode(routeCtx.tenantId)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/individual/org.schema/Organization/_batch-response`;
     }
     /** Submit path: individual/family Organization search (`org.schema/Organization/_search`). */
     individualFamilyOrganizationSearchPath(ctx) {
@@ -102,11 +233,13 @@ export class DataspaceNodeClient {
     }
     /** Submit path: individual/family Order batch (`org.schema/Order/_batch`). */
     individualFamilyOrderBatchPath(ctx) {
-        return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Order/_batch`;
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encode(routeCtx.tenantId)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/individual/org.schema/Order/_batch`;
     }
     /** Poll path: individual/family Order. Pair with `individualFamilyOrderBatchPath`. */
     individualFamilyOrderPollPath(ctx) {
-        return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Order/_batch-response`;
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encode(routeCtx.tenantId)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/individual/org.schema/Order/_batch-response`;
     }
     /** Submit path: individual RelatedPerson (FHIR R4 API, `org.hl7.fhir.api/RelatedPerson/_batch`). */
     individualRelatedPersonBatchPath(ctx) {
@@ -269,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
@@ -285,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);
@@ -301,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({
@@ -316,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()}`;
@@ -334,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;
         }
@@ -363,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,
@@ -400,7 +536,8 @@ export class DataspaceNodeClient {
             return {
                 status: 'failed',
                 profile: 'smart-backend.v1',
-                endpointId,
+                tokenCacheKey: cacheKey,
+                endpointId: cacheKey,
                 statusCode: response.status,
                 response,
             };
@@ -410,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,
@@ -419,7 +556,8 @@ export class DataspaceNodeClient {
         return {
             status: 'fetched',
             profile: 'smart-backend.v1',
-            endpointId,
+            tokenCacheKey: cacheKey,
+            endpointId: cacheKey,
             statusCode: response.status,
             accessToken,
             tokenType,
@@ -432,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',
@@ -462,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,
@@ -477,6 +615,58 @@ export class DataspaceNodeClient {
             response,
         };
     }
+    /**
+     * Friendly wrapper for SMART token request via GW identity/auth token-exchange route.
+     * Uses one object, seconds-based polling, and constructor ctx fallback.
+     */
+    async requestSmartTokenSimple(input) {
+        const routeCtx = this.requireRouteContext(input.tenantId && input.jurisdiction && input.sector
+            ? { tenantId: input.tenantId, jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+        const normalizedScopes = Array.from(new Set((input.scopes || []).filter(Boolean))).sort();
+        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 = {
+            thid: `exchange-${randomUUID()}`,
+            grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
+            subject_token_type: 'urn:ietf:params:oauth:token-type:id_token',
+            subject_token: input.idToken,
+            scope: normalizedScopes.join(' '),
+            organization: routeCtx.tenantId,
+            ...(input.additionalClaims || {}),
+        };
+        const exchange = await this.submitAndPoll(this.identityTokenExchangePath(routeCtx), this.identityTokenExchangePollPath(routeCtx), payload, pollOptions);
+        const exchangeBody = exchange.poll.body ?? {};
+        const accessToken = String(exchangeBody.access_token || '').trim();
+        if (exchange.poll.status >= 400 || !accessToken) {
+            return {
+                status: 'failed',
+                statusCode: exchange.poll.status,
+                response: exchange.poll.body,
+            };
+        }
+        const tokenType = String(exchangeBody.token_type || 'Bearer');
+        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(tokenCacheKey, {
+            accessToken,
+            tokenType,
+            scopes: resolvedScopes,
+            expiresAt: Date.now() + expiresIn * 1000,
+        });
+        return {
+            status: 'fetched',
+            accessToken,
+            tokenType,
+            scopes: resolvedScopes,
+            statusCode: exchange.poll.status,
+            response: exchange.poll.body,
+        };
+    }
     // ---- Private auth helpers ----------------------------------------------
     _pkceS256Challenge(verifier) {
         return createHash('sha256').update(verifier).digest().toString('base64url');
@@ -593,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`.
@@ -600,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.
@@ -623,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.
@@ -672,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.
@@ -729,6 +942,7 @@ export class DataspaceNodeClient {
         return {
             status: response.status,
             body: await this.parseResponseBody(response),
+            retryAfterMs: parseRetryAfterMs(response.headers.get('retry-after')),
         };
     }
     /**
@@ -766,6 +980,7 @@ export class DataspaceNodeClient {
      * (appointment, medication schedule, or another event), mapped to `based-on-display`.
      */
     async createPhoneReminderTasks(ctx, input, options) {
+        const routeCtx = this.requireRouteContext(ctx);
         const windows = Array.isArray(input.windows) ? input.windows : [];
         if (!windows.length) {
             throw new Error('createPhoneReminderTasks requires at least one reminder window.');
@@ -785,9 +1000,9 @@ export class DataspaceNodeClient {
                 throw new Error('createPhoneReminderTasks requires remindAt in every window.');
             }
             const taskIdSeed = [
-                ctx.tenantId,
-                ctx.jurisdiction,
-                ctx.sector,
+                routeCtx.tenantId,
+                routeCtx.jurisdiction,
+                routeCtx.sector,
                 input.subjectRef,
                 input.ownerRef,
                 input.focusRef,
@@ -832,12 +1047,12 @@ export class DataspaceNodeClient {
             };
         });
         const payload = createDidcommPlainMessage({
-            iss: ctx.tenantId,
-            aud: ctx.tenantId,
+            iss: routeCtx.tenantId,
+            aud: routeCtx.tenantId,
             thid,
             body: { data },
         });
-        return this.submitAndPoll(this.individualTaskBatchPath(ctx), this.individualTaskPollPath(ctx), payload, options ?? { timeoutMs: 20_000, intervalMs: 1_000 });
+        return this.submitAndPoll(this.individualTaskBatchPath(routeCtx), this.individualTaskPollPath(routeCtx), payload, options ?? { timeoutMs: 20_000, intervalMs: 1_000 });
     }
     /** Endpoint path for medication overlap pre-check (planned GW contract). */
     individualMedicationOverlapCheckPath(ctx) {
@@ -934,11 +1149,12 @@ export class DataspaceNodeClient {
      * Returns `null` when no matching registration exists.
      */
     async searchFamilyOrganization(ctx, filters, options) {
+        const routeCtx = this.requireRouteContext(ctx);
         const thid = `search-${randomUUID()}`;
         const claims = {
             'org.schema.Organization.owner.telephone': filters.controllerPhone,
             'org.schema.Organization.alternateName': filters.usualname,
-            'org.schema.Service.category': ctx.sector,
+            'org.schema.Service.category': routeCtx.sector,
         };
         if (filters.birthDate) {
             claims['org.schema.Organization.foundingDate'] = filters.birthDate;
@@ -946,8 +1162,8 @@ export class DataspaceNodeClient {
         const payload = {
             jti: randomUUID(),
             thid,
-            iss: ctx.tenantId,
-            aud: ctx.tenantId,
+            iss: routeCtx.tenantId,
+            aud: routeCtx.tenantId,
             type: 'application/api+json',
             body: {
                 data: [{
@@ -957,7 +1173,7 @@ export class DataspaceNodeClient {
                     }],
             },
         };
-        const result = await this.submitAndPoll(this.individualFamilyOrganizationSearchPath(ctx), this.individualFamilyOrganizationSearchPollPath(ctx), payload, options ?? { timeoutMs: 20_000, intervalMs: 1_000 });
+        const result = await this.submitAndPoll(this.individualFamilyOrganizationSearchPath(routeCtx), this.individualFamilyOrganizationSearchPollPath(routeCtx), payload, options ?? { timeoutMs: 20_000, intervalMs: 1_000 });
         if (result.poll.status !== 200)
             return null;
         const entry = result.poll.body?.body?.data?.[0];
@@ -992,6 +1208,11 @@ export class DataspaceNodeClient {
             vp_token: input.vpToken,
             ...(input.additionalClaims || {}),
         };
+        const requestedMembers = Number.isFinite(Number(input.numberOfMembers))
+            ? Math.max(1, Math.floor(Number(input.numberOfMembers)))
+            : 2;
+        // Keep gateway-facing claim stable while exposing a generic SDK input.
+        claims['org.schema.Organization.numberOfEmployees'] = requestedMembers;
         if (input.organizationVc)
             claims['org.schema.OrganizationCredential.jwt'] = input.organizationVc;
         if (input.legalRepresentativeVc) {
@@ -1003,6 +1224,10 @@ export class DataspaceNodeClient {
             iss: 'did:web:controller.example.com',
             aud: 'did:web:host.example.com',
             body: {
+                // GW activation parser expects proof material at top-level DIDComm body.
+                vp_token: input.vpToken,
+                ...(input.organizationVc ? { organizationCredential: input.organizationVc } : {}),
+                ...(input.legalRepresentativeVc ? { representativeCredential: input.legalRepresentativeVc } : {}),
                 data: [
                     {
                         type: 'Organization-activation-request-v1.0',
@@ -1014,6 +1239,180 @@ export class DataspaceNodeClient {
         });
         return this.submitAndPoll(this.hostRegistryOrganizationActivatePath(ctx), this.hostRegistryOrganizationActivatePollPath(ctx), payload, options);
     }
+    /**
+     * Friendly wrapper for legal organization activation.
+     * Accepts one object and seconds-based polling options for integrator ergonomics.
+     */
+    async activateOrganizationInGatewaySimple(input) {
+        const serviceProviderDidWeb = String(input.serviceProviderDidWeb || '').trim();
+        const serviceProviderUrl = String(input.serviceProviderUrl || '').trim();
+        const controllerEmail = String(input.controllerEmail || '').trim();
+        const controllerTelephone = String(input.controllerTelephone || '').trim();
+        const controllerRole = String(input.controllerRole || '').trim();
+        const resolvedServiceDid = toDidWebFromUrlOrHost(serviceProviderDidWeb || serviceProviderUrl);
+        if (!resolvedServiceDid) {
+            throw new Error('activateOrganizationInGatewaySimple requires serviceProviderDidWeb or serviceProviderUrl.');
+        }
+        if (!controllerEmail && !controllerTelephone) {
+            throw new Error('activateOrganizationInGatewaySimple requires controllerEmail or controllerTelephone.');
+        }
+        if (!controllerRole) {
+            throw new Error('activateOrganizationInGatewaySimple requires controllerRole.');
+        }
+        const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
+        const hostCtx = this.requireHostRouteContext(input.jurisdiction && input.sector
+            ? { jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+        const implicitClaims = {
+            'org.schema.Service.category': hostCtx.sector,
+            'org.schema.Service.identifier': resolvedServiceDid,
+            ...(serviceProviderUrl ? { 'org.schema.Service.url': serviceProviderUrl } : {}),
+            [ClaimsPersonSchemaorg.hasOccupation]: controllerRole,
+            ...(controllerEmail ? { [ClaimsPersonSchemaorg.email]: controllerEmail } : {}),
+            ...(controllerTelephone ? { [ClaimsPersonSchemaorg.telephone]: controllerTelephone } : {}),
+        };
+        const activation = await this.activateOrganizationInGatewayFromIcaProof(hostCtx, {
+            vpToken: input.vpToken,
+            numberOfMembers: input.numberOfMembers,
+            organizationVc: input.organizationVc,
+            legalRepresentativeVc: input.legalRepresentativeVc,
+            regulatoryEvidence: input.regulatoryEvidence,
+            additionalClaims: { ...implicitClaims, ...(input.additionalClaims || {}) },
+        }, pollOptions);
+        this.assertFirstDidcommEntrySuccess(activation, 'activateOrganizationInGatewaySimple');
+        return activation;
+    }
+    /**
+     * Friendly wrapper for legal organization Order confirmation.
+     * Accepts one object and builds payload/paths internally.
+     */
+    async confirmLegalOrganizationOrderSimple(input) {
+        if (!String(input.offerId || '').trim()) {
+            throw new Error('confirmLegalOrganizationOrderSimple requires offerId.');
+        }
+        const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
+        const hostCtx = this.requireHostRouteContext(input.jurisdiction && input.sector
+            ? { jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+        const claims = {
+            '@context': 'org.schema',
+            'Order.acceptedOffer.identifier': input.offerId,
+            ...(input.additionalClaims || {}),
+        };
+        const payload = createDidcommPlainMessage({
+            iss: 'did:web:controller.example.com',
+            aud: 'did:web:host.example.com',
+            thid: `order-${randomUUID()}`,
+            body: {
+                data: [{
+                        type: input.dataType || 'Organization-order-request-v1.0',
+                        meta: { claims }, // legacy compatibility
+                        resource: { meta: { claims } },
+                    }],
+            },
+        });
+        const order = await this.submitAndPoll(this.hostRegistryOrderBatchPath(hostCtx), this.hostRegistryOrderPollPath(hostCtx), payload, pollOptions);
+        this.assertFirstDidcommEntrySuccess(order, 'confirmLegalOrganizationOrderSimple');
+        return order;
+    }
+    /**
+     * Normalize GW async response into DIDComm message body.
+     *
+     * Transport note:
+     * - GW poll responses are HTTP JSON envelopes
+     * - business payload lives inside DIDComm `body`
+     *
+     * This helper abstracts envelope differences so consumers do not depend on
+     * raw `poll.body.body` paths.
+     */
+    getDidcommMessageBodyFromResponse(result) {
+        const pollBody = result?.poll?.body ?? result?.body ?? result;
+        const didcommBody = pollBody?.body;
+        if (didcommBody && typeof didcommBody === 'object')
+            return didcommBody;
+        if (pollBody && typeof pollBody === 'object' && Array.isArray(pollBody?.data)) {
+            return pollBody;
+        }
+        return undefined;
+    }
+    /**
+     * Return first DIDComm business entry from a submit/poll result.
+     */
+    getFirstDidcommDataEntryFromResponse(result) {
+        const body = this.getDidcommMessageBodyFromResponse(result);
+        const entry = body?.data?.[0];
+        return entry && typeof entry === 'object' ? entry : undefined;
+    }
+    /**
+     * Extract `org.schema.Offer.identifier` from a submit/poll result.
+     *
+     * This helper normalizes canonical and legacy claim locations.
+     */
+    getOfferIdFromResponse(result) {
+        const entry = this.getFirstDidcommDataEntryFromResponse(result);
+        const offerId = String(entry?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
+            || entry?.resource?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
+            || '').trim();
+        return offerId || undefined;
+    }
+    /**
+     * Extract a UI-ready Offer preview from activation/registration responses.
+     */
+    getOfferPreviewFromResponse(result) {
+        const entry = this.getFirstDidcommDataEntryFromResponse(result);
+        const claims = entry?.meta?.claims || entry?.resource?.meta?.claims || {};
+        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[ClaimsOfferSchemaorg.price],
+            currency: claims[ClaimsOfferSchemaorg.priceCurrency],
+            seats: Number.isFinite(seats) ? seats : undefined,
+            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.
+     */
+    assertFirstDidcommEntrySuccess(result, contextLabel) {
+        const entry = this.getFirstDidcommDataEntryFromResponse(result);
+        const responseStatusRaw = entry?.response?.status;
+        const responseStatus = Number(responseStatusRaw);
+        if (!Number.isFinite(responseStatus) || responseStatus < 400)
+            return;
+        const diagnostics = String(entry?.response?.outcome?.issue?.[0]?.diagnostics
+            || entry?.response?.outcome?.issue?.[0]?.details?.text
+            || '').trim();
+        throw new Error(`${contextLabel} failed (business status=${responseStatus})${diagnostics ? `: ${diagnostics}` : ''}`);
+    }
     /**
      * Activate employee/member device by activation code exchange + DCR registration.
      *
@@ -1054,13 +1453,30 @@ export class DataspaceNodeClient {
             dcr,
         };
     }
+    /**
+     * Friendly wrapper for employee/member device activation.
+     * Uses one object, seconds-based polling, and constructor ctx fallback.
+     */
+    async activateEmployeeDeviceWithActivationCodeSimple(input) {
+        const routeCtx = this.requireRouteContext(input.tenantId && input.jurisdiction && input.sector
+            ? { tenantId: input.tenantId, jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+        const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
+        return this.activateEmployeeDeviceWithActivationCode(routeCtx, {
+            activationCode: input.activationCode,
+            idToken: input.idToken,
+            dcrPayload: input.dcrPayload,
+            pollOptions,
+        });
+    }
     /**
      * UC 5.3 wrapper: create organization employee in entity Employee batch route.
      */
     async createOrganizationEmployee(ctx, input, options) {
+        const routeCtx = this.requireRouteContext(ctx);
         const payload = createDidcommPlainMessage({
-            iss: ctx.tenantId,
-            aud: ctx.tenantId,
+            iss: routeCtx.tenantId,
+            aud: routeCtx.tenantId,
             thid: `employee-${randomUUID()}`,
             body: {
                 data: [
@@ -1072,7 +1488,7 @@ export class DataspaceNodeClient {
                 ],
             },
         });
-        return this.submitAndPoll(this.employeeBatchPath(ctx), this.employeePollPath(ctx), payload, options);
+        return this.submitAndPoll(this.employeeBatchPath(routeCtx), this.employeePollPath(routeCtx), payload, options);
     }
     /**
      * UC 5.1 wrapper: bootstrap subject organization context via registration + optional order confirmation.
@@ -1093,20 +1509,120 @@ export class DataspaceNodeClient {
         const confirmation = await this.submitAndPoll(this.individualFamilyOrderBatchPath(ctx), this.individualFamilyOrderPollPath(ctx), confirmationPayload, input.pollOptions);
         return { registration, confirmation };
     }
+    /**
+     * Friendly wrapper (recommended step 1): register individual organization and return Offer.
+     */
+    async startIndividualOrganizationSimple(input) {
+        const routeCtx = this.requireRouteContext(input.tenantId && input.jurisdiction && input.sector
+            ? { tenantId: input.tenantId, jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+        const alternateName = String(input.alternateName || '').trim();
+        if (!alternateName) {
+            throw new Error('bootstrapIndividualOrganizationSimple requires alternateName.');
+        }
+        const controllerEmail = String(input.controllerEmail || '').trim();
+        const controllerTelephone = String(input.controllerTelephone || '').trim();
+        if (!controllerEmail && !controllerTelephone) {
+            throw new Error('bootstrapIndividualOrganizationSimple requires controllerEmail or controllerTelephone.');
+        }
+        const controllerRole = String(input.controllerRole || 'org.hl7.v3.RoleCode|RESPRSN').trim();
+        const claims = {
+            '@context': 'org.schema',
+            'org.schema.Organization.alternateName': alternateName,
+            'org.schema.Service.category': routeCtx.sector,
+            [ClaimsPersonSchemaorg.hasOccupation]: controllerRole,
+            ...(controllerEmail ? { [ClaimsPersonSchemaorg.email]: controllerEmail } : {}),
+            ...(controllerTelephone ? { [ClaimsPersonSchemaorg.telephone]: controllerTelephone } : {}),
+            ...(input.additionalClaims || {}),
+        };
+        const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
+        const registrationPayload = createDidcommPlainMessage({
+            iss: routeCtx.tenantId,
+            aud: routeCtx.tenantId,
+            thid: `family-org-${randomUUID()}`,
+            body: {
+                data: [{
+                        type: 'SubjectOrg-registration-form-v1.0',
+                        meta: { claims },
+                        resource: { meta: { claims } },
+                    }],
+            },
+        });
+        const registration = await this.submitAndPoll(this.individualFamilyOrganizationBatchPath(routeCtx), this.individualFamilyOrganizationPollPath(routeCtx), registrationPayload, pollOptions);
+        this.assertFirstDidcommEntrySuccess(registration, 'startIndividualOrganizationSimple.registration');
+        const offerId = this.getOfferIdFromResponse(registration);
+        if (!offerId) {
+            throw new Error('startIndividualOrganizationSimple failed: missing offerId in registration response.');
+        }
+        return { registration, offerId, offerPreview: this.getOfferPreviewFromResponse(registration) };
+    }
+    /**
+     * Friendly wrapper (recommended step 2): confirm individual/family order from accepted offerId.
+     */
+    async confirmIndividualOrganizationOrderSimple(input) {
+        const routeCtx = this.requireRouteContext(input.tenantId && input.jurisdiction && input.sector
+            ? { tenantId: input.tenantId, jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+        const offerId = String(input.offerId || '').trim();
+        if (!offerId) {
+            throw new Error('confirmIndividualOrganizationOrderSimple requires offerId.');
+        }
+        const pollOptions = this.resolveSimplePollOptions(input.timeoutSeconds, input.intervalSeconds);
+        const orderClaims = {
+            '@context': 'org.schema',
+            'Order.acceptedOffer.identifier': offerId,
+        };
+        const confirmationPayload = createDidcommPlainMessage({
+            iss: routeCtx.tenantId,
+            aud: routeCtx.tenantId,
+            thid: `family-order-${randomUUID()}`,
+            body: {
+                data: [{
+                        type: 'Family-order-request-v1.0',
+                        meta: { claims: orderClaims },
+                        resource: { meta: { claims: orderClaims } },
+                    }],
+            },
+        });
+        const confirmation = await this.submitAndPoll(this.individualFamilyOrderBatchPath(routeCtx), this.individualFamilyOrderPollPath(routeCtx), confirmationPayload, pollOptions);
+        this.assertFirstDidcommEntrySuccess(confirmation, 'confirmIndividualOrganizationOrderSimple');
+        return confirmation;
+    }
+    /**
+     * Friendly wrapper (provisional): register + auto-confirm individual order.
+     * Prefer `startIndividualOrganizationSimple` + `confirmIndividualOrganizationOrderSimple`.
+     */
+    async bootstrapIndividualOrganizationSimple(input) {
+        const started = await this.startIndividualOrganizationSimple(input);
+        const confirmation = await this.confirmIndividualOrganizationOrderSimple({
+            tenantId: input.tenantId,
+            jurisdiction: input.jurisdiction,
+            sector: input.sector,
+            offerId: started.offerId,
+            timeoutSeconds: input.timeoutSeconds,
+            intervalSeconds: input.intervalSeconds,
+        });
+        return {
+            registration: started.registration,
+            offerId: started.offerId,
+            confirmation,
+        };
+    }
     /**
      * UC 5.5 wrapper: import IPS/FHIR composition and update subject index context.
      */
     async importIpsOrFhirAndUpdateIndex(ctx, input) {
+        const routeCtx = this.requireRouteContext(ctx);
         const payload = {
             thid: input.compositionPayload.thid || `composition-${randomUUID()}`,
             ...input.compositionPayload,
         };
         const submitPath = (input.format || 'r4') === 'api'
-            ? this.individualCompositionR4BatchPath(ctx).replace('/org.hl7.fhir.r4/', '/org.hl7.fhir.api/')
-            : this.individualCompositionR4BatchPath(ctx);
+            ? this.individualCompositionR4BatchPath(routeCtx).replace('/org.hl7.fhir.r4/', '/org.hl7.fhir.api/')
+            : this.individualCompositionR4BatchPath(routeCtx);
         const pollPath = (input.format || 'r4') === 'api'
-            ? this.individualCompositionR4PollPath(ctx).replace('/org.hl7.fhir.r4/', '/org.hl7.fhir.api/')
-            : this.individualCompositionR4PollPath(ctx);
+            ? this.individualCompositionR4PollPath(routeCtx).replace('/org.hl7.fhir.r4/', '/org.hl7.fhir.api/')
+            : this.individualCompositionR4PollPath(routeCtx);
         return this.submitAndPoll(submitPath, pollPath, payload, input.pollOptions);
     }
     /**
@@ -1114,6 +1630,7 @@ export class DataspaceNodeClient {
      * Builds canonical Consent claims and submits/polls the Consent batch.
      */
     async grantProfessionalAccessSimple(ctx, input) {
+        const routeCtx = this.requireRouteContext(ctx);
         const built = buildConsentClaimsSimpleWithCid({
             subjectDid: input.subjectDid,
             subjectPhone: input.subjectPhone,
@@ -1143,7 +1660,7 @@ export class DataspaceNodeClient {
                 ],
             },
         };
-        const consent = await this.submitAndPoll(this.individualConsentR4BatchPath(ctx), this.individualConsentR4PollPath(ctx), consentPayload, input.pollOptions);
+        const consent = await this.submitAndPoll(this.individualConsentR4BatchPath(routeCtx), this.individualConsentR4PollPath(routeCtx), consentPayload, input.pollOptions);
         return {
             thid,
             consent,
@@ -1157,16 +1674,17 @@ export class DataspaceNodeClient {
      * UC 5.7 wrapper: generate digital twin composition from subject data.
      */
     async generateDigitalTwinFromSubjectData(ctx, input) {
+        const routeCtx = this.requireRouteContext(ctx);
         const payload = {
             thid: input.compositionPayload.thid || `digital-twin-${randomUUID()}`,
             ...input.compositionPayload,
         };
         const submitPath = (input.format || 'r4') === 'api'
-            ? this.digitalTwinCompositionApiBatchPath(ctx)
-            : this.digitalTwinCompositionR4BatchPath(ctx);
+            ? this.digitalTwinCompositionApiBatchPath(routeCtx)
+            : this.digitalTwinCompositionR4BatchPath(routeCtx);
         const pollPath = (input.format || 'r4') === 'api'
-            ? this.digitalTwinCompositionApiPollPath(ctx)
-            : this.digitalTwinCompositionR4PollPath(ctx);
+            ? this.digitalTwinCompositionApiPollPath(routeCtx)
+            : this.digitalTwinCompositionR4PollPath(routeCtx);
         return this.submitAndPoll(submitPath, pollPath, payload, input.pollOptions);
     }
     /**
@@ -1196,7 +1714,8 @@ export class DataspaceNodeClient {
             if (Date.now() - startedAt > timeoutMs) {
                 throw new Error(`Polling timeout after ${attempts} attempts (${timeoutMs}ms).`);
             }
-            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            const waitMs = options?.intervalMs ?? result.retryAfterMs ?? intervalMs;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
         }
     }
     // ---- Internal HTTP helpers ---------------------------------------------
@@ -1220,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;
     }
 }