dataspace-client-sdk-node 0.1.1 → 0.1.2

package/dist/client.js

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