dataspace-client-sdk-node 0.1.1 → 0.1.2

package/dist/types.d.ts

@@ -158,6 +158,16 @@ export type FamilyOrganizationSummary = {
     missingFields?: string[];
     updatedAt?: string;
 };
+export type OfferPreview = {
+    offerId?: string;
+    amount?: string;
+    currency?: string;
+    seats?: number;
+    planName?: string;
+    sku?: string;
+    paymentMethod?: string;
+    checkoutUrl?: string;
+};
 /**
  * Input for organization activation in GW using ICA-derived proof material.
  *
@@ -166,11 +176,40 @@ export type FamilyOrganizationSummary = {
  */
 export type GatewayOrganizationActivationInput = {
     vpToken: string;
+    /** Generic requested seats/members for initial offer sizing. Defaults to 2. */
+    numberOfMembers?: number;
+    organizationVc?: string;
+    legalRepresentativeVc?: string;
+    regulatoryEvidence?: Record<string, unknown>;
+    /** @deprecated Prefer `numberOfMembers` and explicit input fields. */
+    additionalClaims?: Record<string, unknown>;
+};
+export type GatewayOrganizationActivationSimpleInput = {
+    jurisdiction?: string;
+    sector?: string;
+    vpToken: string;
+    serviceProviderDidWeb?: string;
+    serviceProviderUrl?: string;
+    controllerEmail?: string;
+    controllerTelephone?: string;
+    controllerRole: string;
+    numberOfMembers?: number;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
     organizationVc?: string;
     legalRepresentativeVc?: string;
     regulatoryEvidence?: Record<string, unknown>;
     additionalClaims?: Record<string, unknown>;
 };
+export type LegalOrganizationOrderSimpleInput = {
+    jurisdiction?: string;
+    sector?: string;
+    offerId: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+    dataType?: string;
+    additionalClaims?: Record<string, unknown>;
+};
 /**
  * Input for device activation based on activation code exchange + DCR.
  */
@@ -180,6 +219,16 @@ export type EmployeeDeviceActivationInput = {
     dcrPayload: Record<string, unknown>;
     pollOptions?: PollOptions;
 };
+export type EmployeeDeviceActivationSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    activationCode: string;
+    idToken: string;
+    dcrPayload: Record<string, unknown>;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+};
 /**
  * Result of device activation flow.
  *
@@ -217,6 +266,36 @@ export type SubjectOrganizationBootstrapResult = {
     registration: SubmitAndPollResult;
     confirmation?: SubmitAndPollResult;
 };
+export type IndividualOrganizationBootstrapSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    alternateName: string;
+    controllerEmail?: string;
+    controllerTelephone?: string;
+    controllerRole?: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+    additionalClaims?: Record<string, unknown>;
+};
+export type IndividualOrganizationBootstrapSimpleResult = {
+    registration: SubmitAndPollResult;
+    offerId: string;
+    confirmation: SubmitAndPollResult;
+};
+export type IndividualOrganizationStartSimpleResult = {
+    registration: SubmitAndPollResult;
+    offerId: string;
+    offerPreview: OfferPreview;
+};
+export type IndividualOrganizationConfirmOrderSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    offerId: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+};
 /**
  * Input for UC 5.5 IPS/FHIR import and index update.
  */
@@ -367,6 +446,8 @@ export type ClientOptions = {
     bearerToken?: string;
     defaultHeaders?: Record<string, string>;
     wallet?: WalletProvider;
+    /** Optional default tenant context so calls can omit ctx repeatedly. */
+    ctx?: RouteContext;
 };
 /**
  * Options for identity-exchange.v1 backend PKCE + token exchange flow.
@@ -435,6 +516,17 @@ export type SmartTokenExchangeInput = {
     exchangePayload: Record<string, unknown>;
     path?: string;
 };
+export type SmartTokenRequestSimpleInput = {
+    tenantId?: string;
+    jurisdiction?: string;
+    sector?: string;
+    idToken: string;
+    scopes: string[];
+    endpointId?: string;
+    timeoutSeconds?: number;
+    intervalSeconds?: number;
+    additionalClaims?: Record<string, unknown>;
+};
 export type SmartTokenExchangeResult = {
     status: 'fetched' | 'cached' | 'failed';
     accessToken?: string;

package/docs/BACKEND_NODE_INTEGRATION.md

@@ -0,0 +1,122 @@
+# Backend Node Integration
+
+This guide is backend-only and uses `dataspace-client-sdk-node`.
+
+Recommended initialization:
+
+```ts
+const client = new DataspaceNodeClient({
+  baseUrl,
+  bearerToken,
+  ctx: { tenantId, jurisdiction, sector },
+});
+```
+
+Alternative (mutable context):
+
+```ts
+const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+client.setContextOrg({ tenantId, jurisdiction, sector });
+client.setDefaultTimeoutSeconds(12);
+client.setDefaultIntervalSeconds(2);
+```
+
+## Flow A. Legal Organization Onboarding (B2B)
+
+1. Receive from frontend: `jurisdiction`, `sector`, `vpToken`.
+2. Activate in GW:
+   - SDK method: `activateOrganizationInGatewaySimple(...)` (recommended)
+   - SDK method: `activateOrganizationInGatewayFromIcaProof(...)` (advanced)
+3. Complete legal organization order (always; amount may be `0`) using `offerId` returned by activation response.
+   - `hostRegistryOrderBatchPath(...)`
+   - `hostRegistryOrderPollPath(...)`
+   - `submitAndPoll(...)`
+4. Run DCR/token bootstrap:
+   - `activateEmployeeDeviceWithActivationCodeSimple(...)` (recommended)
+   - `activateEmployeeDeviceWithActivationCode(...)` (advanced)
+   - `requestSmartTokenSimple(...)` (recommended)
+   - `requestSmartToken(...)` (advanced)
+   - `authenticateBackendPkceAndExchange(...)` or `authenticateBackendSmartStandard(...)`
+
+### Custom backend code example: activate endpoint
+
+```ts
+app.post('/api/onboarding/legal/activate', async (req, res) => {
+  const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+  client.setContextOrg({
+    tenantId: req.body.tenantId,
+    jurisdiction: req.body.jurisdiction,
+    sector: req.body.sector,
+  });
+  const activation = await client.activateOrganizationInGatewaySimple({
+    vpToken: req.body.vpToken,
+    serviceProviderDidWeb: req.body.serviceProviderDidWeb, // or serviceProviderUrl
+    serviceProviderUrl: req.body.serviceProviderUrl,
+    controllerEmail: req.body.controllerEmail,
+    controllerTelephone: req.body.controllerTelephone, // optional alternative to email
+    controllerRole: req.body.controllerRole,
+    numberOfMembers: req.body.numberOfMembers ?? 2,
+  });
+  const offerId = client.getOfferIdFromResponse(activation);
+  if (!offerId) throw new Error('Offer id missing in activation response');
+  const offer = client.getOfferPreviewFromResponse(activation);
+  // Use `offer` to render amount/currency/description to user before acceptance.
+  const order = await client.confirmLegalOrganizationOrderSimple({
+    offerId,
+  });
+  res.json({ activation, offerId, order });
+});
+```
+
+Async UX note:
+- `submitAndPoll` is convenient but returns final state.
+- If you need progress updates, call lower-level `submitBatch` + `pollUntilComplete`
+  and stream step transitions to frontend.
+
+## Flow B. Personal Organization Onboarding (individual/family)
+
+1. Receive registration payload from frontend.
+2. Start registration and extract offer:
+   - SDK method: `startIndividualOrganizationSimple(...)` (recommended)
+3. Frontend shows offer and user accepts.
+4. Confirm order:
+   - SDK method: `confirmIndividualOrganizationOrderSimple(...)` (recommended)
+5. Provisional one-shot helper (auto-order, for legacy/fork scenarios):
+   - SDK method: `bootstrapIndividualOrganizationSimple(...)` (provisional)
+3. Continue consent/clinical lifecycle as needed:
+   - `grantProfessionalAccessSimple(...)`
+   - `importIpsOrFhirAndUpdateIndex(...)`
+   - `requestSmartTokenSimple(...)` (recommended)
+   - `requestSmartToken(...)` (advanced)
+   - `generateDigitalTwinFromSubjectData(...)`
+
+### Custom backend code example: personal register endpoint
+
+```ts
+app.post('/api/onboarding/personal/register', async (req, res) => {
+  const client = new DataspaceNodeClient({ baseUrl, bearerToken });
+  const ctx = {
+    tenantId: req.body.tenantId,
+    jurisdiction: req.body.jurisdiction,
+    sector: req.body.sector,
+  };
+
+  const started = await client.startIndividualOrganizationSimple({
+    alternateName: req.body.alternateName,
+    controllerEmail: req.body.controllerEmail,
+    controllerTelephone: req.body.controllerTelephone,
+    controllerRole: req.body.controllerRole || 'org.hl7.v3.RoleCode|RESPRSN',
+  });
+  // Return offer to frontend for explicit acceptance UX.
+  // Later, call confirmIndividualOrganizationOrderSimple({ offerId: started.offerId }).
+  res.json(started);
+});
+```
+
+## References
+
+- `examples/e2e-bootstrap-tenant.mjs`
+- `examples/host-activate-and-employee.mjs`
+- `examples/e2e-individual-flow.mjs`
+- `tests/uc5-org-onboarding.flow.test.mjs`
+- `tests/uc5-subject-data.flow.test.mjs`

package/docs/DATA_MODEL_ALIGNMENT.md

@@ -1,31 +1,55 @@
-# Data Model Alignment (GW + Chat + SDK)
+# Data Model Alignment (GW + ICA + DataConv + SDK)
 
-Alignment reference for SDK consumers and backend integrators.
+Reference alignment for SDK consumers and backend integrators.
 
-## Business vs Infra Sector
+## API Namespace Alignment
 
-- Infra host onboarding uses network routing sector (`HOST_REGISTRY_SECTOR`).
+- Gateway onboarding and operational flows use `/host/...` with `auth`-based security (OIDC + smart token post-DCR).
+- ICA flows use `/ica/...` namespace.
+- DataConv flows use `/publisher/...` namespace.
+- SDK helpers should abstract these prefixes so integrators do not rebuild paths manually.
+
+## Business Sector vs Host Registry Sector
+
+- Host onboarding/routing can use infrastructure/network sector (`HOST_REGISTRY_SECTOR`).
 - Tenant runtime model uses business sector (`SECTOR`).
-- Canonical tenant vault ID:
+- Canonical tenant vault ID format:
   - `<SECTOR>_<tenantId>`
   - Example: `health-care_acme`
 
+## Legal Organization Activation Inputs
+
+- `vp_token` is the primary proof artifact.
+- Organization VC can be extracted from the VP (`LegalOrganizationCredential` / `OrganizationCredential`).
+- Representative VC is optional depending on policy, but contact/role claims are still required for controller bootstrap.
+- Controller contact supports both:
+  - `org.schema.Person.email`
+  - `org.schema.Person.telephone`
+- Do not document phone-only assumptions as general contract.
+
+## Offer/Order Commercial Contract
+
+- Offer/Order remains part of the onboarding business flow even when amount is `0`.
+- SDK should expose helpers to:
+  - extract offer identifier from activation/orderable claims
+  - expose offer preview fields (amount, currency, description) for UI confirmation
+- Backend should send Order acceptance explicitly using `Order.acceptedOffer.identifier`.
+
 ## Individual Organization Model
 
-- Section: `<prefix>_individual`
-- Doc ID: `org.schema.Organization.identifier.value` (UUID)
+- Section naming: `<prefix>_individual`.
+- Canonical individual org identifier: `org.schema.Organization.identifier.value` (UUID).
+- Contact model is the same as legal org onboarding: email or telephone.
 
 ## Search Contract (`searchFamilyOrganization`)
 
 - Input mapping:
   - `controllerPhone` -> `org.schema.Organization.owner.telephone`
+  - `controllerEmail` -> `org.schema.Organization.owner.email`
   - `usualname` -> `org.schema.Organization.alternateName`
   - `birthDate` -> `org.schema.Organization.foundingDate` (optional)
 
-## Voice Phone Contract
-
-- Preferred claim for subject call target:
-  - `org.schema.Organization.telephone`
-- Fallback claim:
-  - `org.schema.Organization.owner.telephone`
+## Voice/Phone Use Case Notes
 
+- Voice agents may prioritize `telephone` for call target resolution.
+- Generic portal/web integrations must support both email and telephone identity channels.

package/docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.md

@@ -0,0 +1,335 @@
+# Portal Backend Integration Handover
+
+Target audience: team implementing a portal backend that integrates with GW via `dataspace-client-sdk-node`.
+
+## 1) What this SDK does vs does not do
+
+`dataspace-client-sdk-node` does:
+- build GW paths
+- submit/poll async DIDComm plain flows
+- provide high-level wrappers for common UC5 steps
+
+`dataspace-client-sdk-node` does not do:
+- ICA UX orchestration in browser
+- wallet UX/signing UX for end-users
+- generic OIDC4VP UI flow control
+
+`vp_token` source:
+- produced by your identity/wallet flow (usually ICA/OIDC4VP side)
+- then passed to backend and used in GW `_activate`
+
+## 2) Responsibility split
+
+1. Portal frontend:
+   - UX, contract signature flow, identity/wallet flow
+   - obtains `vpToken`
+   - sends onboarding payloads to portal backend
+2. Portal backend (this integration):
+   - uses this SDK to call GW
+   - executes end-to-end business order and polling
+3. GW backend:
+   - validates proofs, processes onboarding, authorization and data access contracts
+
+### Recommended SDK initialization
+
+Initialize once with default context to avoid repeating `tenantId/jurisdiction/sector`:
+
+```ts
+const client = new DataspaceNodeClient({
+  baseUrl,
+  bearerToken,
+  ctx: { tenantId, jurisdiction, sector },
+});
+```
+
+## 3) Legal organization onboarding (complete, numbered)
+
+Canonical order:
+`_verify -> _activate -> Offer -> Order -> DCR -> token`
+
+### Step 1. Frontend obtains `vpToken`
+
+Expected backend input:
+- `jurisdiction` (required)
+- `sector` (required)
+- `vpToken` (required)
+- `numberOfMembers` (optional, generic; default `2`)
+
+Notes:
+- `jurisdiction` is explicit route context. It is not inferred from VAT.
+- `sector` is explicit route context. It is not inferred from DID.
+
+Set once in client:
+
+```ts
+client.setContextOrg({ tenantId, jurisdiction, sector });
+client.setDefaultTimeoutSeconds(120);
+client.setDefaultIntervalSeconds(2);
+```
+
+### Step 2. Backend activates organization in GW
+
+Preferred SDK method (friendly):
+- `activateOrganizationInGatewaySimple(...)`
+
+```ts
+const activation = await client.activateOrganizationInGatewaySimple({
+  vpToken,
+  serviceProviderDidWeb, // or serviceProviderUrl (SDK maps URL -> did:web:<host>)
+  controllerEmail, // or controllerTelephone
+  controllerRole,  // e.g. ISCO-08|1112
+  numberOfMembers,     // optional, default 2
+});
+```
+
+Advanced equivalent (less friendly, same behavior):
+- `activateOrganizationInGatewayFromIcaProof(ctx, input, pollOptions)`
+
+```ts
+const activation = await client.activateOrganizationInGatewayFromIcaProof(
+  { jurisdiction, sector },
+  {
+    vpToken,
+    numberOfMembers,
+  },
+  { timeoutMs: 120000, intervalMs: 2000 },
+);
+```
+
+Default behavior:
+- if `numberOfMembers` is not provided, SDK defaults to `2`
+  (controller + one operational employee).
+
+### Step 3. Backend extracts `offerId` from `_activate` response
+
+Use SDK helper:
+- `client.getOfferIdFromResponse(activation)`
+
+Extract offer preview fields from the first DIDComm entry via:
+- `client.getFirstDidcommDataEntryFromResponse(activation)`
+- or directly as UI object: `client.getOfferPreviewFromResponse(activation)`
+
+Expected offer claims (GW examples/contracts):
+- `org.schema.Offer.identifier`
+- `org.schema.Offer.price`
+- `org.schema.Offer.priceCurrency`
+- `org.schema.Offer.eligibleQuantity.value`
+- `org.schema.Offer.itemOffered.name`
+- `org.schema.Offer.itemOffered.sku`
+- `org.schema.Offer.acceptedPaymentMethod`
+- `org.schema.Offer.checkoutPageURLTemplate`
+
+Recommended UI mapping helper:
+- `client.getOfferPreviewFromResponse(activation)` ->
+  `{ offerId, amount, currency, seats, planName, sku, paymentMethod, checkoutUrl }`
+
+### Step 4. Backend executes legal organization order (always)
+
+Even with `0` amount, Order is still required.
+
+Preferred SDK method (friendly):
+- `confirmLegalOrganizationOrderSimple(...)`
+
+```ts
+const legalOrgOrder = await client.confirmLegalOrganizationOrderSimple({
+  offerId,
+});
+```
+
+Advanced equivalent (less friendly):
+- `hostRegistryOrderBatchPath(...)`
+- `hostRegistryOrderPollPath(...)`
+- `submitAndPoll(...)`
+
+Example:
+
+```ts
+const offerId = client.getOfferIdFromResponse(activation);
+if (!offerId) throw new Error('Offer id missing in activation response.');
+
+const legalOrgOrder = await client.submitAndPoll(
+  client.hostRegistryOrderBatchPath({ jurisdiction, sector }),
+  client.hostRegistryOrderPollPath({ jurisdiction, sector }),
+  {
+    thid: `order-${Date.now()}`,
+    body: {
+      data: [{
+        type: 'Organization-order-request-v1.0',
+        meta: { claims: { 'Order.acceptedOffer.identifier': offerId } },
+      }],
+    },
+  },
+);
+```
+
+### Step 4.1 UX requirement: show offer summary before order
+
+Portal UX should present:
+1. Offer identifier
+2. Total amount and currency (if provided)
+3. Product/license summary
+4. Acceptance action (user confirms, then backend sends Order)
+
+Even if amount is `0`, user acceptance and Order submission still happen.
+
+### Step 5. Backend creates doctor employee
+
+SDK method:
+- `createOrganizationEmployee(...)`
+
+```ts
+const employee = await client.createOrganizationEmployee(
+  { tenantId, jurisdiction, sector },
+  {
+    employeeClaims: {
+      '@context': 'org.schema',
+      'org.schema.Person.email': 'doctor@example.com',
+      'org.schema.Person.hasOccupation': 'ISCO-08|2211',
+    },
+  },
+);
+```
+
+### Step 6. Backend activates doctor device (DCR path)
+
+SDK method:
+- `activateEmployeeDeviceWithActivationCodeSimple(...)` (recommended)
+- `activateEmployeeDeviceWithActivationCode(...)` (advanced)
+
+```ts
+const device = await client.activateEmployeeDeviceWithActivationCodeSimple({
+  activationCode,
+  idToken: doctorUserIdToken,
+  dcrPayload: {
+    application_type: 'web',
+    token_endpoint_auth_method: 'private_key_jwt',
+    jwks: { keys: [doctorPublicJwk] },
+  },
+});
+```
+
+### Step 7. Backend obtains SMART token for authorized access
+
+SDK method:
+- `requestSmartTokenSimple(...)` (recommended)
+- `requestSmartToken(...)` (advanced)
+
+```ts
+const smart = await client.requestSmartTokenSimple({
+  idToken: doctorUserIdToken,
+  endpointId: 'doctor-portal',
+  scopes: ['organization/Composition.rs'],
+});
+```
+
+## 4) Individual subject onboarding + access grant (doctor reads index)
+
+### Step 8. Register personal organization + family order
+
+SDK method:
+- `bootstrapSubjectOrganizationIndex(...)`
+
+```ts
+const subjectBootstrap = await client.bootstrapSubjectOrganizationIndex(
+  { tenantId, jurisdiction, sector },
+  {
+    registrationPayload,
+    confirmationPayload, // include accepted offer id
+  },
+);
+```
+
+### Step 9. Grant doctor consent to read subject index/data
+
+SDK method:
+- `grantProfessionalAccessSimple(...)`
+
+```ts
+await client.grantProfessionalAccessSimple(
+  { tenantId, jurisdiction, sector },
+  {
+    subjectDid: subjectDidWeb,
+    actor: { identifier: doctorDidWeb },
+    actorRole: 'Practitioner',
+    purpose: 'TREAT',
+    actions: ['organization/Composition.rs'],
+  },
+);
+```
+
+### Step 10. Doctor uses SMART token to read permitted resources
+
+Use bearer returned by step 7 in subsequent resource calls.
+
+## 5) Minimal backend request contracts from frontend
+
+Legal activate request:
+
+```json
+{
+  "jurisdiction": "ES",
+  "sector": "health-care",
+  "vpToken": "<vp_token>"
+}
+```
+
+Personal register request:
+
+```json
+{
+  "tenantId": "acme",
+  "jurisdiction": "ES",
+  "sector": "health-care",
+  "registrationPayload": {},
+  "confirmationPayload": {}
+}
+```
+
+## 6) Primary SDK methods checklist
+
+1. `activateOrganizationInGatewayFromIcaProof`
+2. extract `offerId` from activation response
+3. `submitAndPoll` + `hostRegistryOrderBatchPath` / `hostRegistryOrderPollPath`
+4. `createOrganizationEmployee`
+5. `activateEmployeeDeviceWithActivationCodeSimple`
+6. `requestSmartTokenSimple`
+7. `bootstrapSubjectOrganizationIndex`
+8. `grantProfessionalAccessSimple`
+
+## 7) Async/poll UX pattern (important)
+
+All onboarding operations are async (`submit` + `poll`).
+
+Recommended backend pattern per step:
+1. Emit status `submitted` after POST returns `202`.
+2. Poll until completion.
+3. Emit status `completed` or `failed` with diagnostics.
+
+Polling interval behavior:
+- if caller sets `intervalMs`, that value is forced.
+- if caller does not set `intervalMs`, SDK uses backend `Retry-After` when present.
+- fallback default is `2000ms`.
+
+Recommended portal UX states:
+1. `Verifying identity proof`
+2. `Activating organization`
+3. `Offer available` (show price/summary)
+4. `Waiting for acceptance`
+5. `Submitting order`
+6. `Creating employee`
+7. `Activating device`
+8. `Token ready`
+
+Implementation note:
+- If you need real-time UX updates, expose backend progress via SSE/WebSocket.
+- If not, frontend can poll your backend orchestration endpoint for step status.
+
+## 8) References
+
+- `docs/BACKEND_NODE_INTEGRATION.md`
+- `docs/REACT_WEB_INTEGRATION.md`
+- `docs/DEVELOPER_USE_CASES.md`
+- `docs/API.md`
+- `examples/e2e-bootstrap-tenant.mjs`
+- `tests/uc5-org-onboarding.flow.test.mjs`
+- `tests/uc5-subject-data.flow.test.mjs`