dataspace-client-sdk-node 0.1.1 → 0.1.2

package/src/client.ts

@@ -17,10 +17,12 @@ import type {
   GrantProfessionalAccessSimpleResult,
   DigitalTwinGenerationInput,
   EmployeeDeviceActivationInput,
+  EmployeeDeviceActivationSimpleInput,
   EmployeeDeviceActivationResult,
   FamilyOrganizationSummary,
   FamilyRegistrationStatus,
   GatewayOrganizationActivationInput,
+  GatewayOrganizationActivationSimpleInput,
   HostRouteContext,
   IpsOrFhirImportInput,
   MedicationOverlapCheckInput,
@@ -28,11 +30,18 @@ import type {
   OrganizationEmployeeCreationInput,
   PollOptions,
   PollResult,
+  OfferPreview,
   RouteContext,
   SmartTokenExchangeInput,
   SmartTokenExchangeResult,
+  SmartTokenRequestSimpleInput,
+  LegalOrganizationOrderSimpleInput,
   SubjectOrganizationBootstrapInput,
   SubjectOrganizationBootstrapResult,
+  IndividualOrganizationBootstrapSimpleInput,
+  IndividualOrganizationBootstrapSimpleResult,
+  IndividualOrganizationStartSimpleResult,
+  IndividualOrganizationConfirmOrderSimpleInput,
   SubmitAndPollResult,
   SubmitResponse,
   V1Action,
@@ -49,6 +58,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 +99,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 +109,95 @@ 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;
+  }
+
+  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 +212,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 +229,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 +241,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 +283,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 +357,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 +415,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 +428,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');
   }
 
@@ -650,6 +781,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 endpointId = String(input.endpointId || `smart:${routeCtx.tenantId}:${normalizedScopes.join(',')}`).trim();
+    if (!endpointId) {
+      throw new Error('requestSmartTokenSimple requires endpointId (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(endpointId, {
+      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 {
@@ -959,11 +1157,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 +1212,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 +1239,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 +1284,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 +1421,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 +1439,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 +1452,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 +1485,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 +1498,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 +1513,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 +1535,199 @@ 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 } : {}),
+      'org.schema.Person.hasOccupation': controllerRole,
+      ...(controllerEmail ? { 'org.schema.Person.email': controllerEmail } : {}),
+      ...(controllerTelephone ? { 'org.schema.Person.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?.['org.schema.Offer.identifier']
+      || (entry as any)?.resource?.meta?.claims?.['org.schema.Offer.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['org.schema.Offer.eligibleQuantity.value'];
+    const seats =
+      typeof seatsRaw === 'number'
+        ? seatsRaw
+        : (typeof seatsRaw === 'string' && seatsRaw.trim() ? Number(seatsRaw) : undefined);
+    return {
+      offerId: this.getOfferIdFromResponse(result),
+      amount: claims['org.schema.Offer.price'],
+      currency: claims['org.schema.Offer.priceCurrency'],
+      seats: Number.isFinite(seats as number) ? seats : undefined,
+      planName: claims['org.schema.Offer.itemOffered.name'],
+      sku: claims['org.schema.Offer.itemOffered.sku'],
+      paymentMethod: claims['org.schema.Offer.acceptedPaymentMethod'],
+      checkoutUrl: claims['org.schema.Offer.checkoutPageURLTemplate'],
+    };
+  }
+
+  /**
+   * 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 +1735,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 +1791,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 +1841,8 @@ export class DataspaceNodeClient {
     });
 
     return this.submitAndPoll(
-      this.employeeBatchPath(ctx),
-      this.employeePollPath(ctx),
+      this.employeeBatchPath(routeCtx),
+      this.employeePollPath(routeCtx),
       payload,
       options,
     );
@@ -1420,7 +1852,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 +1886,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,
+      'org.schema.Person.hasOccupation': controllerRole,
+      ...(controllerEmail ? { 'org.schema.Person.email': controllerEmail } : {}),
+      ...(controllerTelephone ? { 'org.schema.Person.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 +2040,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 +2078,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 +2098,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 +2148,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));
     }
   }