dataspace-client-sdk-node 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased] - 2026-05-04
+
+### Added
+- Data model alignment guide updated for cross-service namespace consistency:
+  - Gateway: `/host/...` (with `auth` security model)
+  - ICA: `/ica/...`
+  - DataConv: `/publisher/...`
+- Explicit integration guidance that SDK consumers should use SDK path helpers instead of manually composing host prefixes/routes.
+
+### Changed
+- Contact identity contract for onboarding/controller flows is now documented as dual-channel:
+  - Email (`org.schema.Person.email`)
+  - Telephone (`org.schema.Person.telephone`
+- Offer/Order process clarified as part of the onboarding contract even when commercial amount is zero:
+  - Offer extraction for UI review/acceptance
+  - Explicit Order acceptance using offer identifier
+
+### Documentation
+- Updated:
+  - `docs/DATA_MODEL_ALIGNMENT.md`
+- Clarified:
+  - `/host` + `auth` alignment with current gateway model
+  - namespace symmetry with ICA (`/ica`) and DataConv (`/publisher`)
+

package/README.md

@@ -6,6 +6,46 @@ Node.js SDK to consume GW/UNID async DIDComm plain endpoints.
 **[→ Data Model Alignment (GW + Chat + SDK)](docs/DATA_MODEL_ALIGNMENT.md)**
 **[→ Frontend/Backend SDK Ownership Matrix](../docs/SDK_AUTH_OWNERSHIP.md)**
 **[→ Developer Use-Case Cookbook (UC5 + additional patterns)](docs/DEVELOPER_USE_CASES.md)**
+**[→ React Web Integration Guide](docs/REACT_WEB_INTEGRATION.md)**
+**[→ Backend Node Integration Guide](docs/BACKEND_NODE_INTEGRATION.md)**
+**[→ Portal Backend Integration Handover](docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.md)**
+
+## Onboarding flows (split by business case)
+
+Do not mix these two flows in the same narrative:
+
+1. Legal Organization Onboarding (B2B/tenant/controller)
+2. Personal Organization Onboarding (individual/family/subject)
+
+### 1) Legal Organization Onboarding (B2B/tenant/controller)
+
+Canonical order when ICA proof is involved:
+
+1. ICA proof/verification (`_verify`, external to this SDK).
+2. GW activation in host registry: `Organization/_activate`.
+3. Offer/Order phase for legal organization onboarding (always; if amount is 0, no payment step).
+4. Device onboarding (DCR): `identity/openid/Device/_dcr`.
+5. Post-DCR token exchange / SMART authorization for protected API calls.
+
+Node SDK helpers:
+- `activateOrganizationInGatewayFromIcaProof(...)` (UC5.2)
+- `activateEmployeeDeviceWithActivationCode(...)` (UC5.4)
+- `authenticateBackendPkceAndExchange(...)` or `authenticateBackendSmartStandard(...)`
+
+### 2) Personal Organization Onboarding (individual/family/subject)
+
+Canonical order:
+
+1. Personal/family registration: `individual/org.schema/Organization/_batch`.
+2. Offer acceptance/order confirmation: `individual/org.schema/Order/_batch`.
+3. Continue with consent + subject data workflows.
+
+Node SDK helper:
+- `bootstrapSubjectOrganizationIndex(...)` (UC5.1: registration + optional order confirmation)
+
+See:
+- `docs/DEVELOPER_USE_CASES.md` (UC5.1..UC5.7)
+- `docs/E2E_BOOTSTRAP.md` (host activation bootstrap)
 
 ## Scope
 - Generic async batch client (`_batch` + `_batch-response`) and JSON POST helper.

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AsyncPollRequest, BackendPkceAuthOptions, BackendPkceAuthResult, BackendSmartAuthOptions, BackendSmartAuthResult, ClientOptions, CreatePhoneReminderTasksInput, GrantProfessionalAccessSimpleInput, GrantProfessionalAccessSimpleResult, DigitalTwinGenerationInput, EmployeeDeviceActivationInput, EmployeeDeviceActivationResult, FamilyOrganizationSummary, GatewayOrganizationActivationInput, HostRouteContext, IpsOrFhirImportInput, MedicationOverlapCheckInput, MedicationRegistrationInput, OrganizationEmployeeCreationInput, PollOptions, PollResult, RouteContext, SmartTokenExchangeInput, SmartTokenExchangeResult, SubjectOrganizationBootstrapInput, SubjectOrganizationBootstrapResult, SubmitAndPollResult, SubmitResponse, V1Action, V1Section } from './types.js';
+import type { AsyncPollRequest, BackendPkceAuthOptions, BackendPkceAuthResult, BackendSmartAuthOptions, BackendSmartAuthResult, ClientOptions, CreatePhoneReminderTasksInput, GrantProfessionalAccessSimpleInput, GrantProfessionalAccessSimpleResult, DigitalTwinGenerationInput, EmployeeDeviceActivationInput, EmployeeDeviceActivationSimpleInput, EmployeeDeviceActivationResult, FamilyOrganizationSummary, GatewayOrganizationActivationInput, GatewayOrganizationActivationSimpleInput, HostRouteContext, IpsOrFhirImportInput, MedicationOverlapCheckInput, MedicationRegistrationInput, OrganizationEmployeeCreationInput, PollOptions, PollResult, OfferPreview, RouteContext, SmartTokenExchangeInput, SmartTokenExchangeResult, SmartTokenRequestSimpleInput, LegalOrganizationOrderSimpleInput, SubjectOrganizationBootstrapInput, SubjectOrganizationBootstrapResult, IndividualOrganizationBootstrapSimpleInput, IndividualOrganizationBootstrapSimpleResult, IndividualOrganizationStartSimpleResult, IndividualOrganizationConfirmOrderSimpleInput, SubmitAndPollResult, SubmitResponse, V1Action, V1Section } from './types.js';
 import type { WalletProvider } from './sdk/dataspace-wallet-sdk-node/provider.js';
 import type { PublicJwk, WalletContext } from './sdk/dataspace-wallet-sdk-node/types.js';
 export declare class DataspaceNodeClient {
@@ -6,9 +6,28 @@ export declare class DataspaceNodeClient {
     private readonly bearerToken?;
     private readonly defaultHeaders;
     private readonly wallet?;
+    private defaultCtx?;
+    private defaultTimeoutMs?;
+    private defaultIntervalMs?;
     private readonly _tokenCache;
     constructor(options: ClientOptions);
     getWallet(): WalletProvider | undefined;
+    /**
+     * Set default route context for subsequent calls.
+     */
+    setContext(ctx: RouteContext): this;
+    /**
+     * Preferred alias for organization/tenant integration context.
+     */
+    setContextOrg(ctx: RouteContext): this;
+    setTenantId(tenantId: string): this;
+    setJurisdiction(jurisdiction: string): this;
+    setSector(sector: string): this;
+    setDefaultTimeoutSeconds(seconds: number): this;
+    setDefaultIntervalSeconds(seconds: number): this;
+    private resolveSimplePollOptions;
+    private requireRouteContext;
+    private requireHostRouteContext;
     /**
      * Generic GW v1 tenant route builder.
      * Use this for any section/format/resourceType/action combination not covered
@@ -20,7 +39,7 @@ export declare class DataspaceNodeClient {
      * client.v1Path(ctx, 'individual', 'org.schema', 'Organization', '_batch')
      * // → /acme/cds-ES/v1/health-care/individual/org.schema/Organization/_batch
      */
-    v1Path(ctx: RouteContext, section: V1Section, format: string, resourceType: string, action: V1Action): string;
+    v1Path(ctx: RouteContext | undefined, section: V1Section, format: string, resourceType: string, action: V1Action): string;
     /**
      * Generic tenant-scoped identity route builder.
      * Pattern: `/{prefix}/cds-{jurisdiction}/v1/{sector}/{tenantId}/identity/auth/{action}`
@@ -28,41 +47,41 @@ export declare 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).
      */
-    tenantIdentityPath(ctx: RouteContext, prefix: string, action: string): string;
+    tenantIdentityPath(ctx: RouteContext | undefined, prefix: string, action: string): string;
     /**
      * Generic host registry route builder (tenant-agnostic, `host/` prefix).
      * Use for controller-level registry operations (Organization activate, Order, etc.).
      *
      * Pattern: `/host/cds-{jurisdiction}/v1/{sector}/registry/org.schema/{resourceType}/{action}`
      */
-    hostRegistryPath(ctx: HostRouteContext, resourceType: string, action: V1Action): string;
+    hostRegistryPath(ctx: HostRouteContext | undefined, resourceType: string, action: V1Action): string;
     /** Submit path: host registry Organization batch (controller-level org registration). */
-    hostRegistryOrganizationBatchPath(ctx: HostRouteContext): string;
+    hostRegistryOrganizationBatchPath(ctx?: HostRouteContext): string;
     /** Poll path: host registry Organization batch. Pair with `hostRegistryOrganizationBatchPath`. */
-    hostRegistryOrganizationPollPath(ctx: HostRouteContext): string;
+    hostRegistryOrganizationPollPath(ctx?: HostRouteContext): string;
     /** Submit path: activate a tenant Organization in the GW registry using a VC from ICA. */
-    hostRegistryOrganizationActivatePath(ctx: HostRouteContext): string;
+    hostRegistryOrganizationActivatePath(ctx?: HostRouteContext): string;
     /** Poll path: `_activate` response. Pair with `hostRegistryOrganizationActivatePath`. */
-    hostRegistryOrganizationActivatePollPath(ctx: HostRouteContext): string;
+    hostRegistryOrganizationActivatePollPath(ctx?: HostRouteContext): string;
     /** Submit path: host registry Order batch (controller-level order submission). */
-    hostRegistryOrderBatchPath(ctx: HostRouteContext): string;
+    hostRegistryOrderBatchPath(ctx?: HostRouteContext): string;
     /** Poll path: host registry Order batch. Pair with `hostRegistryOrderBatchPath`. */
-    hostRegistryOrderPollPath(ctx: HostRouteContext): string;
+    hostRegistryOrderPollPath(ctx?: HostRouteContext): string;
     /**
      * Submit path: individual/family Organization onboarding (`org.schema/Organization/_batch`).
      * Use for `family-registration/_create-or-resume` DIDComm payloads.
      */
-    individualFamilyOrganizationBatchPath(ctx: RouteContext): string;
+    individualFamilyOrganizationBatchPath(ctx?: RouteContext): string;
     /** Poll path: individual/family Organization. Pair with `individualFamilyOrganizationBatchPath`. */
-    individualFamilyOrganizationPollPath(ctx: RouteContext): string;
+    individualFamilyOrganizationPollPath(ctx?: RouteContext): string;
     /** Submit path: individual/family Organization search (`org.schema/Organization/_search`). */
-    individualFamilyOrganizationSearchPath(ctx: RouteContext): string;
+    individualFamilyOrganizationSearchPath(ctx?: RouteContext): string;
     /** Poll path: individual/family Organization search. Pair with `individualFamilyOrganizationSearchPath`. */
-    individualFamilyOrganizationSearchPollPath(ctx: RouteContext): string;
+    individualFamilyOrganizationSearchPollPath(ctx?: RouteContext): string;
     /** Submit path: individual/family Order batch (`org.schema/Order/_batch`). */
-    individualFamilyOrderBatchPath(ctx: RouteContext): string;
+    individualFamilyOrderBatchPath(ctx?: RouteContext): string;
     /** Poll path: individual/family Order. Pair with `individualFamilyOrderBatchPath`. */
-    individualFamilyOrderPollPath(ctx: RouteContext): string;
+    individualFamilyOrderPollPath(ctx?: RouteContext): string;
     /** Submit path: individual RelatedPerson (FHIR R4 API, `org.hl7.fhir.api/RelatedPerson/_batch`). */
     individualRelatedPersonBatchPath(ctx: RouteContext): string;
     /** Poll path: individual RelatedPerson. Pair with `individualRelatedPersonBatchPath`. */
@@ -80,9 +99,9 @@ export declare class DataspaceNodeClient {
     /** Poll path: individual Task. Pair with `individualTaskBatchPath`. */
     individualTaskPollPath(ctx: RouteContext): string;
     /** Submit path: entity Employee (`entity/org.schema/Employee/_batch`). */
-    employeeBatchPath(ctx: RouteContext): string;
+    employeeBatchPath(ctx?: RouteContext): string;
     /** Poll path: entity Employee. Pair with `employeeBatchPath`. */
-    employeePollPath(ctx: RouteContext): string;
+    employeePollPath(ctx?: RouteContext): string;
     /** Submit path: individual Person legacy format (`individual/org.schema/Person/_batch`). Use for older flows; prefer Organization for family onboarding. */
     individualLegacyPersonBatchPath(ctx: RouteContext): string;
     /** Submit path: individual Consent (FHIR R4, `org.hl7.fhir.r4/Consent/_batch`). */
@@ -105,18 +124,18 @@ export declare class DataspaceNodeClient {
      * Submit path: identity DCR step — binds API key to service public JWK.
      * Used internally by `authenticateBackendPkceAndExchange` (step 1 of identity-exchange.v1).
      */
-    identityDeviceDcrPath(ctx: RouteContext): string;
+    identityDeviceDcrPath(ctx?: RouteContext): string;
     /** Poll path: identity DCR. Pair with `identityDeviceDcrPath`. */
-    identityDeviceDcrPollPath(ctx: RouteContext): string;
+    identityDeviceDcrPollPath(ctx?: RouteContext): string;
     /**
      * Submit path: identity token exchange — id_token → SMART bearer.
      * Used internally by `authenticateBackendPkceAndExchange` (step 4 of identity-exchange.v1).
      */
-    identityTokenExchangePath(ctx: RouteContext): string;
+    identityTokenExchangePath(ctx?: RouteContext): string;
     /** Poll path: identity token exchange. Pair with `identityTokenExchangePath`. */
-    identityTokenExchangePollPath(ctx: RouteContext): string;
+    identityTokenExchangePollPath(ctx?: RouteContext): string;
     /** Submit path: identity license issue (`identity/auth/_issue`). */
-    identityLicenseIssuePath(ctx: RouteContext): string;
+    identityLicenseIssuePath(ctx?: RouteContext): string;
     /**
      * Submit path: SMART token step — code + code_verifier → id_token.
      * Used internally by `authenticateBackendPkceAndExchange` (step 3 of identity-exchange.v1).
@@ -168,6 +187,11 @@ export declare class DataspaceNodeClient {
      * Exchange token payload against gateway token endpoint and cache the result.
      */
     requestSmartToken(input: SmartTokenExchangeInput): Promise<SmartTokenExchangeResult>;
+    /**
+     * Friendly wrapper for SMART token request via GW identity/auth token-exchange route.
+     * Uses one object, seconds-based polling, and constructor ctx fallback.
+     */
+    requestSmartTokenSimple(input: SmartTokenRequestSimpleInput): Promise<SmartTokenExchangeResult>;
     private _pkceS256Challenge;
     private _buildAuthDIDCommRequest;
     private resolveControllerPublicJwk;
@@ -231,6 +255,7 @@ export declare class DataspaceNodeClient {
     pollBatchResponse(path: string, request: AsyncPollRequest): Promise<{
         status: number;
         body: unknown;
+        retryAfterMs?: number;
     }>;
     /**
      * Submit a DIDComm batch payload and poll until the async job completes.
@@ -260,7 +285,7 @@ export declare class DataspaceNodeClient {
      * `reminderSummary` is the contextual summary of what the reminder refers to
      * (appointment, medication schedule, or another event), mapped to `based-on-display`.
      */
-    createPhoneReminderTasks(ctx: RouteContext, input: CreatePhoneReminderTasksInput, options?: PollOptions): Promise<SubmitAndPollResult>;
+    createPhoneReminderTasks(ctx: RouteContext | undefined, input: CreatePhoneReminderTasksInput, options?: PollOptions): Promise<SubmitAndPollResult>;
     /** Endpoint path for medication overlap pre-check (planned GW contract). */
     individualMedicationOverlapCheckPath(ctx: RouteContext): string;
     /**
@@ -281,7 +306,7 @@ export declare class DataspaceNodeClient {
      *
      * Returns `null` when no matching registration exists.
      */
-    searchFamilyOrganization(ctx: RouteContext, filters: {
+    searchFamilyOrganization(ctx: RouteContext | undefined, filters: {
         controllerPhone: string;
         usualname: string;
         birthDate?: string;
@@ -289,35 +314,92 @@ export declare class DataspaceNodeClient {
     /**
      * Activate tenant organization in GW from ICA-derived proof.
      */
-    activateOrganizationInGatewayFromIcaProof(ctx: HostRouteContext, input: GatewayOrganizationActivationInput, options?: PollOptions): Promise<SubmitAndPollResult>;
+    activateOrganizationInGatewayFromIcaProof(ctx: HostRouteContext | undefined, input: GatewayOrganizationActivationInput, options?: PollOptions): Promise<SubmitAndPollResult>;
+    /**
+     * Friendly wrapper for legal organization activation.
+     * Accepts one object and seconds-based polling options for integrator ergonomics.
+     */
+    activateOrganizationInGatewaySimple(input: GatewayOrganizationActivationSimpleInput): Promise<SubmitAndPollResult>;
+    /**
+     * Friendly wrapper for legal organization Order confirmation.
+     * Accepts one object and builds payload/paths internally.
+     */
+    confirmLegalOrganizationOrderSimple(input: LegalOrganizationOrderSimpleInput): Promise<SubmitAndPollResult>;
+    /**
+     * 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: SubmitAndPollResult | PollResult | unknown): Record<string, unknown> | undefined;
+    /**
+     * Return first DIDComm business entry from a submit/poll result.
+     */
+    getFirstDidcommDataEntryFromResponse(result: SubmitAndPollResult | PollResult | unknown): Record<string, unknown> | undefined;
+    /**
+     * Extract `org.schema.Offer.identifier` from a submit/poll result.
+     *
+     * This helper normalizes canonical and legacy claim locations.
+     */
+    getOfferIdFromResponse(result: SubmitAndPollResult | PollResult | unknown): string | undefined;
+    /**
+     * Extract a UI-ready Offer preview from activation/registration responses.
+     */
+    getOfferPreviewFromResponse(result: SubmitAndPollResult | PollResult | unknown): OfferPreview;
+    /**
+     * Throws when first DIDComm entry contains a business-level error status.
+     */
+    assertFirstDidcommEntrySuccess(result: SubmitAndPollResult | PollResult | unknown, contextLabel: string): void;
     /**
      * Activate employee/member device by activation code exchange + DCR registration.
      *
      * Step 1. Exchange activation code using user id_token to obtain an initial access token.
      * Step 2. Register device keys through Device/_dcr authorized by that initial token.
      */
-    activateEmployeeDeviceWithActivationCode(ctx: RouteContext, input: EmployeeDeviceActivationInput): Promise<EmployeeDeviceActivationResult>;
+    activateEmployeeDeviceWithActivationCode(ctx: RouteContext | undefined, input: EmployeeDeviceActivationInput): Promise<EmployeeDeviceActivationResult>;
+    /**
+     * Friendly wrapper for employee/member device activation.
+     * Uses one object, seconds-based polling, and constructor ctx fallback.
+     */
+    activateEmployeeDeviceWithActivationCodeSimple(input: EmployeeDeviceActivationSimpleInput): Promise<EmployeeDeviceActivationResult>;
     /**
      * UC 5.3 wrapper: create organization employee in entity Employee batch route.
      */
-    createOrganizationEmployee(ctx: RouteContext, input: OrganizationEmployeeCreationInput, options?: PollOptions): Promise<SubmitAndPollResult>;
+    createOrganizationEmployee(ctx: RouteContext | undefined, input: OrganizationEmployeeCreationInput, options?: PollOptions): Promise<SubmitAndPollResult>;
     /**
      * UC 5.1 wrapper: bootstrap subject organization context via registration + optional order confirmation.
      */
-    bootstrapSubjectOrganizationIndex(ctx: RouteContext, input: SubjectOrganizationBootstrapInput): Promise<SubjectOrganizationBootstrapResult>;
+    bootstrapSubjectOrganizationIndex(ctx: RouteContext | undefined, input: SubjectOrganizationBootstrapInput): Promise<SubjectOrganizationBootstrapResult>;
+    /**
+     * Friendly wrapper (recommended step 1): register individual organization and return Offer.
+     */
+    startIndividualOrganizationSimple(input: IndividualOrganizationBootstrapSimpleInput): Promise<IndividualOrganizationStartSimpleResult>;
+    /**
+     * Friendly wrapper (recommended step 2): confirm individual/family order from accepted offerId.
+     */
+    confirmIndividualOrganizationOrderSimple(input: IndividualOrganizationConfirmOrderSimpleInput): Promise<SubmitAndPollResult>;
+    /**
+     * Friendly wrapper (provisional): register + auto-confirm individual order.
+     * Prefer `startIndividualOrganizationSimple` + `confirmIndividualOrganizationOrderSimple`.
+     */
+    bootstrapIndividualOrganizationSimple(input: IndividualOrganizationBootstrapSimpleInput): Promise<IndividualOrganizationBootstrapSimpleResult>;
     /**
      * UC 5.5 wrapper: import IPS/FHIR composition and update subject index context.
      */
-    importIpsOrFhirAndUpdateIndex(ctx: RouteContext, input: IpsOrFhirImportInput): Promise<SubmitAndPollResult>;
+    importIpsOrFhirAndUpdateIndex(ctx: RouteContext | undefined, input: IpsOrFhirImportInput): Promise<SubmitAndPollResult>;
     /**
      * UC 5.6 consent helper from minimal frontend fields.
      * Builds canonical Consent claims and submits/polls the Consent batch.
      */
-    grantProfessionalAccessSimple(ctx: RouteContext, input: GrantProfessionalAccessSimpleInput): Promise<GrantProfessionalAccessSimpleResult>;
+    grantProfessionalAccessSimple(ctx: RouteContext | undefined, input: GrantProfessionalAccessSimpleInput): Promise<GrantProfessionalAccessSimpleResult>;
     /**
      * UC 5.7 wrapper: generate digital twin composition from subject data.
      */
-    generateDigitalTwinFromSubjectData(ctx: RouteContext, input: DigitalTwinGenerationInput): Promise<SubmitAndPollResult>;
+    generateDigitalTwinFromSubjectData(ctx: RouteContext | undefined, input: DigitalTwinGenerationInput): Promise<SubmitAndPollResult>;
     /**
      * Poll a `_*-response` path repeatedly until the status is no longer 202.
      * Default: 60s timeout, 2s interval.