dataspace-client-sdk-node 0.1.1 → 0.2.0

package/src/client.ts

@@ -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, type DidcommFetchInit } from 'gdc-common-utils-ts/utils/didcomm-submit';
+import { ClaimsOfferSchemaorg, ClaimsPersonSchemaorg } from 'gdc-common-utils-ts/constants/schemaorg';
 import {
   MedicationStatementClaimsFhirApi,
   MedicationStatementClaimsFhirApiExtended,
@@ -17,10 +20,13 @@ import type {
   GrantProfessionalAccessSimpleResult,
   DigitalTwinGenerationInput,
   EmployeeDeviceActivationInput,
+  EndpointSelector,
+  EmployeeDeviceActivationSimpleInput,
   EmployeeDeviceActivationResult,
   FamilyOrganizationSummary,
   FamilyRegistrationStatus,
   GatewayOrganizationActivationInput,
+  GatewayOrganizationActivationSimpleInput,
   HostRouteContext,
   IpsOrFhirImportInput,
   MedicationOverlapCheckInput,
@@ -28,11 +34,19 @@ import type {
   OrganizationEmployeeCreationInput,
   PollOptions,
   PollResult,
+  OfferPreview,
+  OfferInfo,
   RouteContext,
   SmartTokenExchangeInput,
   SmartTokenExchangeResult,
+  SmartTokenRequestSimpleInput,
+  LegalOrganizationOrderSimpleInput,
   SubjectOrganizationBootstrapInput,
   SubjectOrganizationBootstrapResult,
+  IndividualOrganizationBootstrapSimpleInput,
+  IndividualOrganizationBootstrapSimpleResult,
+  IndividualOrganizationStartSimpleResult,
+  IndividualOrganizationConfirmOrderSimpleInput,
   SubmitAndPollResult,
   SubmitResponse,
   V1Action,
@@ -49,6 +63,35 @@ function encode(value: string): string {
   return encodeURIComponent(value);
 }
 
+function toDidWebFromUrlOrHost(raw: string): string | undefined {
+  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: string | null): number | undefined {
+  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;
+}
+
 type CachedToken = {
   accessToken: string;
   tokenType: string;
@@ -61,6 +104,9 @@ export class DataspaceNodeClient {
   private readonly bearerToken?: string;
   private readonly defaultHeaders: Record<string, string>;
   private readonly wallet?: WalletProvider;
+  private defaultCtx?: RouteContext;
+  private defaultTimeoutMs?: number;
+  private defaultIntervalMs?: number;
   private readonly _tokenCache = new Map<string, CachedToken>();
 
   constructor(options: ClientOptions) {
@@ -68,12 +114,108 @@ export class DataspaceNodeClient {
     this.bearerToken = options.bearerToken;
     this.defaultHeaders = options.defaultHeaders ?? {};
     this.wallet = options.wallet;
+    this.defaultCtx = options.ctx;
   }
 
   public getWallet(): WalletProvider | undefined {
     return this.wallet;
   }
 
+  /**
+   * Set default route context for subsequent calls.
+   */
+  public setContext(ctx: RouteContext): this {
+    this.defaultCtx = { ...ctx };
+    return this;
+  }
+
+  /**
+   * Preferred alias for organization/tenant integration context.
+   */
+  public setContextOrg(ctx: RouteContext): this {
+    return this.setContext(ctx);
+  }
+
+  public setTenantId(tenantId: string): this {
+    const current = this.defaultCtx ?? { tenantId: '', jurisdiction: '', sector: '' };
+    this.defaultCtx = { ...current, tenantId };
+    return this;
+  }
+
+  public setJurisdiction(jurisdiction: string): this {
+    const current = this.defaultCtx ?? { tenantId: '', jurisdiction: '', sector: '' };
+    this.defaultCtx = { ...current, jurisdiction };
+    return this;
+  }
+
+  public setSector(sector: string): this {
+    const current = this.defaultCtx ?? { tenantId: '', jurisdiction: '', sector: '' };
+    this.defaultCtx = { ...current, sector };
+    return this;
+  }
+
+  public setDefaultTimeoutSeconds(seconds: number): this {
+    if (Number.isFinite(Number(seconds))) {
+      this.defaultTimeoutMs = Math.max(1, Math.floor(Number(seconds) * 1000));
+    }
+    return this;
+  }
+
+  public setDefaultIntervalSeconds(seconds: number): this {
+    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
+   */
+  public getEndpointId(selector: EndpointSelector, providerDid?: string): string {
+    const fragment = generateServiceId(selector); // #section:format:resourceType:action
+    if (providerDid) return `${providerDid}${fragment}`;
+    return fragment.replace(/^#/, '');
+  }
+
+  private resolveSimplePollOptions(timeoutSeconds?: number, intervalSeconds?: number): PollOptions | undefined {
+    const pollOptions: 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;
+  }
+
+  private requireRouteContext(ctx?: RouteContext): RouteContext {
+    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 };
+  }
+
+  private requireHostRouteContext(ctx?: HostRouteContext): HostRouteContext {
+    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 -------------------------------------------------------
 
   /**
@@ -88,13 +230,14 @@ export class DataspaceNodeClient {
    * // → /acme/cds-ES/v1/health-care/individual/org.schema/Organization/_batch
    */
   public v1Path(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     section: V1Section,
     format: string,
     resourceType: string,
     action: V1Action,
   ): string {
-    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)}`;
   }
 
   /**
@@ -104,8 +247,9 @@ export class DataspaceNodeClient {
    * The `prefix` is service-specific: `host` for GW, `publisher` for DataConv, `ica` for ICA.
    * Dedicated path methods in this SDK use `host` (GW convention).
    */
-  public tenantIdentityPath(ctx: RouteContext, prefix: string, action: string): string {
-    return `/${encode(prefix)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/${encode(ctx.tenantId)}/identity/auth/${encode(action)}`;
+  public tenantIdentityPath(ctx: RouteContext | undefined, prefix: string, action: string): string {
+    const routeCtx = this.requireRouteContext(ctx);
+    return `/${encode(prefix)}/cds-${encode(routeCtx.jurisdiction)}/v1/${encode(routeCtx.sector)}/${encode(routeCtx.tenantId)}/identity/auth/${encode(action)}`;
   }
 
   /**
@@ -115,40 +259,41 @@ export class DataspaceNodeClient {
    * Pattern: `/host/cds-{jurisdiction}/v1/{sector}/registry/org.schema/{resourceType}/{action}`
    */
   public hostRegistryPath(
-    ctx: HostRouteContext,
+    ctx: HostRouteContext | undefined,
     resourceType: string,
     action: V1Action,
   ): string {
-    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). */
-  public hostRegistryOrganizationBatchPath(ctx: HostRouteContext): string {
+  public hostRegistryOrganizationBatchPath(ctx?: HostRouteContext): string {
     return this.hostRegistryPath(ctx, 'Organization', '_batch');
   }
 
   /** Poll path: host registry Organization batch. Pair with `hostRegistryOrganizationBatchPath`. */
-  public hostRegistryOrganizationPollPath(ctx: HostRouteContext): string {
+  public hostRegistryOrganizationPollPath(ctx?: HostRouteContext): string {
     return this.hostRegistryPath(ctx, 'Organization', '_batch-response');
   }
 
   /** Submit path: activate a tenant Organization in the GW registry using a VC from ICA. */
-  public hostRegistryOrganizationActivatePath(ctx: HostRouteContext): string {
+  public hostRegistryOrganizationActivatePath(ctx?: HostRouteContext): string {
     return this.hostRegistryPath(ctx, 'Organization', '_activate');
   }
 
   /** Poll path: `_activate` response. Pair with `hostRegistryOrganizationActivatePath`. */
-  public hostRegistryOrganizationActivatePollPath(ctx: HostRouteContext): string {
+  public hostRegistryOrganizationActivatePollPath(ctx?: HostRouteContext): string {
     return this.hostRegistryPath(ctx, 'Organization', '_activate-response');
   }
 
   /** Submit path: host registry Order batch (controller-level order submission). */
-  public hostRegistryOrderBatchPath(ctx: HostRouteContext): string {
+  public hostRegistryOrderBatchPath(ctx?: HostRouteContext): string {
     return this.hostRegistryPath(ctx, 'Order', '_batch');
   }
 
   /** Poll path: host registry Order batch. Pair with `hostRegistryOrderBatchPath`. */
-  public hostRegistryOrderPollPath(ctx: HostRouteContext): string {
+  public hostRegistryOrderPollPath(ctx?: HostRouteContext): string {
     return this.hostRegistryPath(ctx, 'Order', '_batch-response');
   }
 
@@ -156,33 +301,37 @@ export class DataspaceNodeClient {
    * Submit path: individual/family Organization onboarding (`org.schema/Organization/_batch`).
    * Use for `family-registration/_create-or-resume` DIDComm payloads.
    */
-  public individualFamilyOrganizationBatchPath(ctx: RouteContext): string {
-    return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Organization/_batch`;
+  public individualFamilyOrganizationBatchPath(ctx?: RouteContext): string {
+    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`. */
-  public individualFamilyOrganizationPollPath(ctx: RouteContext): string {
-    return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Organization/_batch-response`;
+  public individualFamilyOrganizationPollPath(ctx?: RouteContext): string {
+    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`). */
-  public individualFamilyOrganizationSearchPath(ctx: RouteContext): string {
+  public individualFamilyOrganizationSearchPath(ctx?: RouteContext): string {
     return this.v1Path(ctx, 'individual', 'org.schema', 'Organization', '_search');
   }
 
   /** Poll path: individual/family Organization search. Pair with `individualFamilyOrganizationSearchPath`. */
-  public individualFamilyOrganizationSearchPollPath(ctx: RouteContext): string {
+  public individualFamilyOrganizationSearchPollPath(ctx?: RouteContext): string {
     return this.v1Path(ctx, 'individual', 'org.schema', 'Organization', '_search-response');
   }
 
   /** Submit path: individual/family Order batch (`org.schema/Order/_batch`). */
-  public individualFamilyOrderBatchPath(ctx: RouteContext): string {
-    return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Order/_batch`;
+  public individualFamilyOrderBatchPath(ctx?: RouteContext): string {
+    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`. */
-  public individualFamilyOrderPollPath(ctx: RouteContext): string {
-    return `/${encode(ctx.tenantId)}/cds-${encode(ctx.jurisdiction)}/v1/${encode(ctx.sector)}/individual/org.schema/Order/_batch-response`;
+  public individualFamilyOrderPollPath(ctx?: RouteContext): string {
+    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`). */
@@ -226,12 +375,12 @@ export class DataspaceNodeClient {
   }
 
   /** Submit path: entity Employee (`entity/org.schema/Employee/_batch`). */
-  public employeeBatchPath(ctx: RouteContext): string {
+  public employeeBatchPath(ctx?: RouteContext): string {
     return this.v1Path(ctx, 'entity', 'org.schema', 'Employee', '_batch');
   }
 
   /** Poll path: entity Employee. Pair with `employeeBatchPath`. */
-  public employeePollPath(ctx: RouteContext): string {
+  public employeePollPath(ctx?: RouteContext): string {
     return this.v1Path(ctx, 'entity', 'org.schema', 'Employee', '_batch-response');
   }
 
@@ -284,12 +433,12 @@ export class DataspaceNodeClient {
    * Submit path: identity DCR step — binds API key to service public JWK.
    * Used internally by `authenticateBackendPkceAndExchange` (step 1 of identity-exchange.v1).
    */
-  public identityDeviceDcrPath(ctx: RouteContext): string {
+  public identityDeviceDcrPath(ctx?: RouteContext): string {
     return this.tenantIdentityPath(ctx, 'host', '_dcr');
   }
 
   /** Poll path: identity DCR. Pair with `identityDeviceDcrPath`. */
-  public identityDeviceDcrPollPath(ctx: RouteContext): string {
+  public identityDeviceDcrPollPath(ctx?: RouteContext): string {
     return this.tenantIdentityPath(ctx, 'host', '_dcr-response');
   }
 
@@ -297,17 +446,17 @@ export class DataspaceNodeClient {
    * Submit path: identity token exchange — id_token → SMART bearer.
    * Used internally by `authenticateBackendPkceAndExchange` (step 4 of identity-exchange.v1).
    */
-  public identityTokenExchangePath(ctx: RouteContext): string {
+  public identityTokenExchangePath(ctx?: RouteContext): string {
     return this.tenantIdentityPath(ctx, 'host', '_exchange');
   }
 
   /** Poll path: identity token exchange. Pair with `identityTokenExchangePath`. */
-  public identityTokenExchangePollPath(ctx: RouteContext): string {
+  public identityTokenExchangePollPath(ctx?: RouteContext): string {
     return this.tenantIdentityPath(ctx, 'host', '_exchange-response');
   }
 
   /** Submit path: identity license issue (`identity/auth/_issue`). */
-  public identityLicenseIssuePath(ctx: RouteContext): string {
+  public identityLicenseIssuePath(ctx?: RouteContext): string {
     return this.tenantIdentityPath(ctx, 'host', '_issue');
   }
 
@@ -387,14 +536,16 @@ export class DataspaceNodeClient {
       ctx,
       apiKey,
       scopes,
-      endpointId = `pkce:${apiKey.slice(0, 8)}`,
+      tokenCacheKey = `pkce:${apiKey.slice(0, 8)}`,
+      endpointId,
       codeVerifier = randomUUID(),
       pollOptions,
     } = options;
 
-    const cached = this._tokenCache.get(endpointId);
+    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);
@@ -413,7 +564,7 @@ export class DataspaceNodeClient {
       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
@@ -434,7 +585,7 @@ export class DataspaceNodeClient {
     const codeBody = (codePoll.body as Record<string, unknown>) ?? {};
     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
@@ -454,7 +605,7 @@ export class DataspaceNodeClient {
     const tokenBody = (tokenPoll.body as Record<string, unknown>) ?? {};
     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
@@ -477,7 +628,7 @@ export class DataspaceNodeClient {
     const exchangeBody = (exchangePoll.body as Record<string, unknown>) ?? {};
     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');
@@ -485,22 +636,22 @@ export class DataspaceNodeClient {
     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.
    */
-  public getCachedBearerToken(endpointId: string): string | undefined {
-    const cached = this._tokenCache.get(endpointId);
+  public getCachedBearerToken(tokenCacheKey: string): string | undefined {
+    const cached = this._tokenCache.get(tokenCacheKey);
     if (cached && cached.expiresAt > Date.now() + 30_000) {
       return cached.accessToken;
     }
@@ -516,7 +667,8 @@ export class DataspaceNodeClient {
     const {
       clientId,
       scopes,
-      endpointId = `smart-backend:${clientId}`,
+      tokenCacheKey = `smart-backend:${clientId}`,
+      endpointId,
       tokenUrl,
       tokenPath = '/token',
       audience,
@@ -524,12 +676,14 @@ export class DataspaceNodeClient {
       additionalTokenFields,
     } = options;
 
-    const cached = this._tokenCache.get(endpointId);
+    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,
@@ -563,7 +717,8 @@ export class DataspaceNodeClient {
       return {
         status: 'failed',
         profile: 'smart-backend.v1',
-        endpointId,
+        tokenCacheKey: cacheKey,
+        endpointId: cacheKey,
         statusCode: response.status,
         response,
       };
@@ -575,7 +730,7 @@ export class DataspaceNodeClient {
     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,
@@ -585,7 +740,8 @@ export class DataspaceNodeClient {
     return {
       status: 'fetched',
       profile: 'smart-backend.v1',
-      endpointId,
+      tokenCacheKey: cacheKey,
+      endpointId: cacheKey,
       statusCode: response.status,
       accessToken,
       tokenType,
@@ -599,13 +755,13 @@ export class DataspaceNodeClient {
    * Exchange token payload against gateway token endpoint and cache the result.
    */
   public async requestSmartToken(input: SmartTokenExchangeInput): Promise<SmartTokenExchangeResult> {
-    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',
@@ -633,7 +789,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,
@@ -650,6 +806,73 @@ export class DataspaceNodeClient {
     };
   }
 
+  /**
+   * Friendly wrapper for SMART token request via GW identity/auth token-exchange route.
+   * Uses one object, seconds-based polling, and constructor ctx fallback.
+   */
+  public async requestSmartTokenSimple(
+    input: SmartTokenRequestSimpleInput,
+  ): Promise<SmartTokenExchangeResult> {
+    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: Record<string, unknown> = {
+      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 as Record<string, unknown>) ?? {};
+    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 ----------------------------------------------
 
   private _pkceS256Challenge(verifier: string): string {
@@ -801,6 +1024,34 @@ 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`.
+   */
+  public async submitBundle(
+    path: string,
+    payload: { thid?: string } & Record<string, unknown>,
+    options?: {
+      mode?: 'plain' | 'strict';
+      recipientEncryptionJwk?: PublicJwk;
+      walletContext?: WalletContext;
+    },
+  ): Promise<SubmitResponse> {
+    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`.
@@ -808,14 +1059,18 @@ export class DataspaceNodeClient {
    * Returns immediately with the HTTP response — pair with `pollUntilComplete` or use `submitAndPoll`.
    */
   public async submitBatch(path: string, payload: unknown): Promise<SubmitResponse> {
-    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 as Record<string, unknown>,
+      defaultHeaders: this.defaultHeaders,
+      bearerToken: this.bearerToken,
+      fetcher: (requestUrl: string, init: DidcommFetchInit) => fetch(requestUrl, init),
+    });
+    return { status: result.status, location: result.location, body: result.body };
   }
 
   /**
@@ -840,42 +1095,34 @@ 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 as Record<string, unknown>,
-    });
-
-    // 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: Record<string, string> = {
-      ...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: Record<string, unknown>) =>
+        this.wallet!.signCompactJws(walletContext, {
+          header: {
+            typ: 'application/didcomm-signed+json',
+            alg: 'ES384',
+            ...(signingJwk?.kid ? { kid: signingJwk.kid } : {}),
+          },
+          claims,
+        }),
+      encryptCompactJwe: async (compactJws: string, recipientJwk: unknown) =>
+        this.wallet!.buildCompactJwe(walletContext, {
+          plaintext: compactJws,
+          recipientJwk: recipientJwk as PublicJwk,
+          contentType: 'JWS',
+        }),
+      fetcher: (requestUrl: string, init: DidcommFetchInit) => fetch(requestUrl, init),
+    });
+    return { status: result.status, location: result.location, body: result.body };
   }
 
   /**
@@ -893,6 +1140,14 @@ export class DataspaceNodeClient {
     };
   }
 
+  /**
+   * Legacy JSON submit for non-bundle payloads (openid/token/resource JSON bodies).
+   * Keeps JSON flows explicit and semantically separated from DIDComm bundle flows.
+   */
+  public async submitLegacyJson(path: string, payload: unknown): Promise<SubmitResponse> {
+    return this.postJson(path, payload);
+  }
+
   /**
    * POST a multipart/form-data payload.
    * Use for file upload endpoints. Prefer `uploadConversionFile` for DataConversion uploads.
@@ -959,11 +1214,15 @@ export class DataspaceNodeClient {
    * Returns HTTP 202 while the job is still processing, 200 (or other) when done.
    * Prefer `pollUntilComplete` for automatic retry loops.
    */
-  public async pollBatchResponse(path: string, request: AsyncPollRequest): Promise<{ status: number; body: unknown }> {
+  public async pollBatchResponse(
+    path: string,
+    request: AsyncPollRequest,
+  ): Promise<{ status: number; body: unknown; retryAfterMs?: number }> {
     const response = await this.doPost(path, request, 'application/json');
     return {
       status: response.status,
       body: await this.parseResponseBody(response),
+      retryAfterMs: parseRetryAfterMs(response.headers.get('retry-after')),
     };
   }
 
@@ -1010,10 +1269,11 @@ export class DataspaceNodeClient {
    * (appointment, medication schedule, or another event), mapped to `based-on-display`.
    */
   public async createPhoneReminderTasks(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: CreatePhoneReminderTasksInput,
     options?: PollOptions,
   ): Promise<SubmitAndPollResult> {
+    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.');
@@ -1036,9 +1296,9 @@ export class DataspaceNodeClient {
       }
 
       const taskIdSeed = [
-        ctx.tenantId,
-        ctx.jurisdiction,
-        ctx.sector,
+        routeCtx.tenantId,
+        routeCtx.jurisdiction,
+        routeCtx.sector,
         input.subjectRef,
         input.ownerRef,
         input.focusRef,
@@ -1081,15 +1341,15 @@ 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),
+      this.individualTaskBatchPath(routeCtx),
+      this.individualTaskPollPath(routeCtx),
       payload,
       options ?? { timeoutMs: 20_000, intervalMs: 1_000 },
     );
@@ -1218,15 +1478,16 @@ export class DataspaceNodeClient {
    * Returns `null` when no matching registration exists.
    */
   public async searchFamilyOrganization(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     filters: { controllerPhone: string; usualname: string; birthDate?: string },
     options?: PollOptions,
   ): Promise<FamilyOrganizationSummary | null> {
+    const routeCtx = this.requireRouteContext(ctx);
     const thid = `search-${randomUUID()}`;
     const claims: Record<string, unknown> = {
       '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;
@@ -1235,8 +1496,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: [{
@@ -1248,8 +1509,8 @@ export class DataspaceNodeClient {
     };
 
     const result = await this.submitAndPoll(
-      this.individualFamilyOrganizationSearchPath(ctx),
-      this.individualFamilyOrganizationSearchPollPath(ctx),
+      this.individualFamilyOrganizationSearchPath(routeCtx),
+      this.individualFamilyOrganizationSearchPollPath(routeCtx),
       payload,
       options ?? { timeoutMs: 20_000, intervalMs: 1_000 },
     );
@@ -1281,7 +1542,7 @@ export class DataspaceNodeClient {
    * Activate tenant organization in GW from ICA-derived proof.
    */
   public async activateOrganizationInGatewayFromIcaProof(
-    ctx: HostRouteContext,
+    ctx: HostRouteContext | undefined,
     input: GatewayOrganizationActivationInput,
     options?: PollOptions,
   ): Promise<SubmitAndPollResult> {
@@ -1294,6 +1555,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) {
       claims['org.schema.LegalRepresentativeCredential.jwt'] = input.legalRepresentativeVc;
@@ -1304,6 +1570,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',
@@ -1322,6 +1592,227 @@ export class DataspaceNodeClient {
     );
   }
 
+  /**
+   * Friendly wrapper for legal organization activation.
+   * Accepts one object and seconds-based polling options for integrator ergonomics.
+   */
+  public async activateOrganizationInGatewaySimple(
+    input: GatewayOrganizationActivationSimpleInput,
+  ): Promise<SubmitAndPollResult> {
+    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: Record<string, unknown> = {
+      '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.
+   */
+  public async confirmLegalOrganizationOrderSimple(
+    input: LegalOrganizationOrderSimpleInput,
+  ): Promise<SubmitAndPollResult> {
+    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: Record<string, unknown> = {
+      '@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.
+   */
+  public getDidcommMessageBodyFromResponse(
+    result: SubmitAndPollResult | PollResult | unknown,
+  ): Record<string, unknown> | undefined {
+    const pollBody = (result as any)?.poll?.body ?? (result as any)?.body ?? result;
+    const didcommBody = (pollBody as any)?.body;
+    if (didcommBody && typeof didcommBody === 'object') return didcommBody as Record<string, unknown>;
+    if (pollBody && typeof pollBody === 'object' && Array.isArray((pollBody as any)?.data)) {
+      return pollBody as Record<string, unknown>;
+    }
+    return undefined;
+  }
+
+  /**
+   * Return first DIDComm business entry from a submit/poll result.
+   */
+  public getFirstDidcommDataEntryFromResponse(
+    result: SubmitAndPollResult | PollResult | unknown,
+  ): Record<string, unknown> | undefined {
+    const body = this.getDidcommMessageBodyFromResponse(result);
+    const entry = (body as any)?.data?.[0];
+    return entry && typeof entry === 'object' ? (entry as Record<string, unknown>) : undefined;
+  }
+
+  /**
+   * Extract `org.schema.Offer.identifier` from a submit/poll result.
+   *
+   * This helper normalizes canonical and legacy claim locations.
+   */
+  public getOfferIdFromResponse(result: SubmitAndPollResult | PollResult | unknown): string | undefined {
+    const entry = this.getFirstDidcommDataEntryFromResponse(result);
+    const offerId = String(
+      (entry as any)?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
+      || (entry as any)?.resource?.meta?.claims?.[ClaimsOfferSchemaorg.identifier]
+      || '',
+    ).trim();
+    return offerId || undefined;
+  }
+
+  /**
+   * Extract a UI-ready Offer preview from activation/registration responses.
+   */
+  public getOfferPreviewFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferPreview {
+    const entry = this.getFirstDidcommDataEntryFromResponse(result) as any;
+    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 as number) ? seats : undefined,
+      planName: claims[ClaimsOfferSchemaorg.itemOfferedName],
+      sku: claims[ClaimsOfferSchemaorg.itemOfferedSku],
+      paymentMethod: claims[ClaimsOfferSchemaorg.acceptedPaymentMethod],
+      checkoutUrl: claims[ClaimsOfferSchemaorg.checkoutPageURLTemplate],
+    };
+  }
+
+  /**
+   * Alias of `getOfferPreviewFromResponse` with business naming.
+   */
+  public getOfferInfoFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferInfo {
+    return this.getOfferPreviewFromResponse(result);
+  }
+
+  /**
+   * Extract activation code from response payload or claims.
+   * Supports common response shapes used in onboarding and license issuance flows.
+   */
+  public getActivationCodeFromResponse(result: SubmitAndPollResult | PollResult | unknown): string | undefined {
+    const root = (result as any)?.poll?.body || (result as any)?.body || {};
+    const byBody =
+      String(root?.activationCode || root?.body?.activationCode || '').trim();
+    if (byBody) return byBody;
+
+    const entry = this.getFirstDidcommDataEntryFromResponse(result) as any;
+    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.
+   */
+  public assertFirstDidcommEntrySuccess(
+    result: SubmitAndPollResult | PollResult | unknown,
+    contextLabel: string,
+  ): void {
+    const entry = this.getFirstDidcommDataEntryFromResponse(result) as any;
+    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.
    *
@@ -1329,7 +1820,7 @@ export class DataspaceNodeClient {
    * Step 2. Register device keys through Device/_dcr authorized by that initial token.
    */
   public async activateEmployeeDeviceWithActivationCode(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: EmployeeDeviceActivationInput,
   ): Promise<EmployeeDeviceActivationResult> {
     const exchangePayload = {
@@ -1385,17 +1876,43 @@ export class DataspaceNodeClient {
     };
   }
 
+  /**
+   * Friendly wrapper for employee/member device activation.
+   * Uses one object, seconds-based polling, and constructor ctx fallback.
+   */
+  public async activateEmployeeDeviceWithActivationCodeSimple(
+    input: EmployeeDeviceActivationSimpleInput,
+  ): Promise<EmployeeDeviceActivationResult> {
+    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.
    */
   public async createOrganizationEmployee(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: OrganizationEmployeeCreationInput,
     options?: PollOptions,
   ): Promise<SubmitAndPollResult> {
+    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: [
@@ -1409,8 +1926,8 @@ export class DataspaceNodeClient {
     });
 
     return this.submitAndPoll(
-      this.employeeBatchPath(ctx),
-      this.employeePollPath(ctx),
+      this.employeeBatchPath(routeCtx),
+      this.employeePollPath(routeCtx),
       payload,
       options,
     );
@@ -1420,7 +1937,7 @@ export class DataspaceNodeClient {
    * UC 5.1 wrapper: bootstrap subject organization context via registration + optional order confirmation.
    */
   public async bootstrapSubjectOrganizationIndex(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: SubjectOrganizationBootstrapInput,
   ): Promise<SubjectOrganizationBootstrapResult> {
     const registrationPayload = {
@@ -1454,24 +1971,151 @@ export class DataspaceNodeClient {
     return { registration, confirmation };
   }
 
+  /**
+   * Friendly wrapper (recommended step 1): register individual organization and return Offer.
+   */
+  public async startIndividualOrganizationSimple(
+    input: IndividualOrganizationBootstrapSimpleInput,
+  ): Promise<IndividualOrganizationStartSimpleResult> {
+    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: Record<string, unknown> = {
+      '@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.
+   */
+  public async confirmIndividualOrganizationOrderSimple(
+    input: IndividualOrganizationConfirmOrderSimpleInput,
+  ): Promise<SubmitAndPollResult> {
+    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: Record<string, unknown> = {
+      '@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`.
+   */
+  public async bootstrapIndividualOrganizationSimple(
+    input: IndividualOrganizationBootstrapSimpleInput,
+  ): Promise<IndividualOrganizationBootstrapSimpleResult> {
+    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.
    */
   public async importIpsOrFhirAndUpdateIndex(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: IpsOrFhirImportInput,
   ): Promise<SubmitAndPollResult> {
+    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);
   }
@@ -1481,9 +2125,10 @@ export class DataspaceNodeClient {
    * Builds canonical Consent claims and submits/polls the Consent batch.
    */
   public async grantProfessionalAccessSimple(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: GrantProfessionalAccessSimpleInput,
   ): Promise<GrantProfessionalAccessSimpleResult> {
+    const routeCtx = this.requireRouteContext(ctx);
     const built = buildConsentClaimsSimpleWithCid(
       {
         subjectDid: input.subjectDid,
@@ -1518,8 +2163,8 @@ export class DataspaceNodeClient {
       },
     };
     const consent = await this.submitAndPoll(
-      this.individualConsentR4BatchPath(ctx),
-      this.individualConsentR4PollPath(ctx),
+      this.individualConsentR4BatchPath(routeCtx),
+      this.individualConsentR4PollPath(routeCtx),
       consentPayload,
       input.pollOptions,
     );
@@ -1538,20 +2183,21 @@ export class DataspaceNodeClient {
    * UC 5.7 wrapper: generate digital twin composition from subject data.
    */
   public async generateDigitalTwinFromSubjectData(
-    ctx: RouteContext,
+    ctx: RouteContext | undefined,
     input: DigitalTwinGenerationInput,
   ): Promise<SubmitAndPollResult> {
+    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);
   }
@@ -1587,7 +2233,8 @@ export class DataspaceNodeClient {
         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));
     }
   }
 
@@ -1617,10 +2264,15 @@ export class DataspaceNodeClient {
 
   private async parseResponseBody(response: Response): Promise<unknown> {
     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;
   }
 }