dataspace-client-sdk-node 0.2.3 → 0.2.4

package/README.md

@@ -4,16 +4,17 @@ Node.js SDK to consume GW/UNID async DIDComm endpoints.
 
 ## Documentation Index
 
-1. [Full API Reference](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/API.md)
-2. [Data Model Alignment (GW + Chat + SDK)](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/DATA_MODEL_ALIGNMENT.md)
-3. [Developer Use-Case Cookbook (UC5 + additional patterns)](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/DEVELOPER_USE_CASES.md)
-4. [Live Local GW UC5 E2E (no mocks)](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/E2E_LOCAL_GW_UC5.md)
-5. [React Web Integration Guide](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/REACT_WEB_INTEGRATION.md)
+1. [Legal Organization Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/LEGAL_ORGANIZATION_FLOW_STEP_BY_STEP.md)
+2. [Practitioner Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/PRACTITIONER_FLOW_STEP_BY_STEP.md)
+3. [Personal Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/PERSONAL_FLOW_STEP_BY_STEP.md)
+4. [Controller Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/CONTROLLER_FLOW_STEP_BY_STEP.md)
+5. [Live Local GW UC5 E2E (no mocks)](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/E2E_LOCAL_GW_UC5.md)
 6. [Backend Node Integration Guide](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/BACKEND_NODE_INTEGRATION.md)
-7. [Controller Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/CONTROLLER_FLOW_STEP_BY_STEP.md)
-8. [Legal Organization Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/LEGAL_ORGANIZATION_FLOW_STEP_BY_STEP.md)
-9. [Practitioner Flow Step by Step](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/PRACTITIONER_FLOW_STEP_BY_STEP.md)
-10. [Portal Backend Integration Handover](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.md)
+7. [Full API Reference](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/API.md)
+8. [Developer Use-Case Cookbook (secondary examples)](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/DEVELOPER_USE_CASES.md)
+9. [Data Model Alignment (GW + Chat + SDK)](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/DATA_MODEL_ALIGNMENT.md)
+10. [React Web Integration Guide](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/REACT_WEB_INTEGRATION.md)
+11. [Portal Backend Integration Handover](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.md)
 
 ## TODO and Roadmap
 

package/docs/API.md

@@ -139,10 +139,10 @@ type CreatePhoneReminderTasksInput = {
   windows: Array<{ offsetMinutes: number; remindAt: string }>; // remindAt = ISO-8601
   locale?: string;
   callSid?: string;
-  notificationPhone?: string;
-  controllerPhone?: string;
-  subjectRef: string;   // e.g. 'Person/+34600000001'
-  ownerRef: string;     // e.g. 'RelatedPerson/+34699999999'
+  notificationPhone?: string; // optional legacy/fallback only
+  controllerPhone?: string;   // optional legacy/fallback only
+  subjectRef: string;   // e.g. 'Person/subject-uuid' or 'Person/mailto:subject@example.com'
+  ownerRef: string;     // e.g. 'RelatedPerson/controller-uuid' or 'RelatedPerson/mailto:controller@example.com'
   focusRef: string;     // e.g. 'Appointment/2026-05-10T10:00:00.000Z'
   reminderSummary?: string;
   description?: string;
@@ -252,7 +252,7 @@ const ctx: RouteContext = { tenantId: 'acme', jurisdiction: 'ES', sector: 'healt
 
 // Register or resume a family organization
 const payload = createDidcommPlainMessage({
-  iss: '+34600000001',
+  iss: 'mailto:controller@example.com',
   aud: 'did:web:api.acme.org',
   body: {
     data: [{
@@ -260,9 +260,9 @@ const payload = createDidcommPlainMessage({
       meta: {
         claims: {
           '@context': 'org.schema',
-          'org.schema.Organization.telephone': '+34611111111', // notification phone (subject)
-          'org.schema.Organization.creator': '+34600000001',   // controller phone
-          'org.schema.Organization.owner.telephone': '+34600000001', // controller (indexed)
+          'org.schema.Organization.email': 'subject@example.com', // subject contact (primary)
+          'org.schema.Organization.creator': 'mailto:controller@example.com', // controller (primary)
+          'org.schema.Organization.owner.email': 'controller@example.com', // controller (indexed)
           'org.schema.Organization.alternateName': 'Maria',          // usualname (indexed)
           'org.schema.Service.category': 'health-care',
           'org.schema.Organization.addressCountry': 'ES',
@@ -667,6 +667,8 @@ console.log(poll.status, poll.attempts);
 ### `createPhoneReminderTasks`
 
 Creates one reminder `Task` per reminder window via `individual/Task/_batch`.
+Primary identity channels are `subjectRef` and `ownerRef` (UUID/email/DID references).
+`notificationPhone` and `controllerPhone` are optional compatibility fields.
 
 Each window maps to one deterministic task ID (SHA-256 of routing context + refs + `remindAt`).
 
@@ -686,10 +688,8 @@ const result = await client.createPhoneReminderTasks(ctx, {
     { offsetMinutes: 60,    remindAt: '2026-05-10T09:00:00.000Z' }, // 1 hour before
   ],
   locale: 'es-ES',
-  notificationPhone: '+34611111111',
-  controllerPhone: '+34600000001',
-  subjectRef: 'Person/+34611111111',
-  ownerRef: 'RelatedPerson/+34600000001',
+  subjectRef: 'Person/subject-uuid',
+  ownerRef: 'RelatedPerson/controller-uuid',
   focusRef: 'Appointment/2026-05-10T10:00:00.000Z',
   reminderSummary: '10/05 10:00 | Hospital San Juan | Consulta cardiología',
   maxAttempts: 3,
@@ -702,7 +702,8 @@ console.log(result.poll.status); // 200 if all tasks created
 
 ### `searchFamilyOrganization`
 
-Search for an existing family organization by controller phone + usualname. Returns `null` when not found.
+Legacy helper: search an existing family organization by controller phone + usualname.
+For portal onboarding, use email-based registration flow docs (`PERSONAL_FLOW_STEP_BY_STEP.md`).
 
 ```ts
 searchFamilyOrganization(

package/docs/DEVELOPER_USE_CASES.md

@@ -19,7 +19,7 @@ const client = new DataspaceNodeClient({
 });
 
 const ctx = {
-  tenantId: 'acme',
+  tenantId: 'VATES-B00112233',
   jurisdiction: 'ES',
   sector: 'health-care',
 };
@@ -126,7 +126,7 @@ Scope namespace note:
 
 ```ts
 const consent = await client.grantProfessionalAccessSimple(ctx, {
-  subjectPhone: '+34600111222',
+  subjectDid: 'did:web:subject.example.com',
   subjectGivenName: 'Ana',
   actor: { identifier: 'did:web:hospital.example.com' },
   actorRole: 'Practitioner',
@@ -201,7 +201,7 @@ await client.grantProfessionalAccessSimple(ctx, {
 });
 ```
 
-### C) Actor by email/phone + role
+### C) Actor by email + role (portal-first)
 
 ```ts
 await client.grantProfessionalAccessSimple(ctx, {
@@ -213,15 +213,7 @@ await client.grantProfessionalAccessSimple(ctx, {
 });
 ```
 
-```ts
-await client.grantProfessionalAccessSimple(ctx, {
-  subjectDid: 'did:web:subject.example.com',
-  actor: { phone: '+34600111222' }, // maps to urn:tel:+34600111222
-  actorRole: 'Practitioner',
-  purpose: 'TREAT',
-  actions: ['organization/AppointmentResponse.cruds'],
-});
-```
+Phone-based actor identifiers are supported for compatibility flows, but email/DID are the primary portal channels.
 
 ### D) Jurisdiction + role (explicit claims)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dataspace-client-sdk-node",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Node.js SDK for DIDComm plain batch + async polling flows",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",

package/src/types.ts

@@ -436,7 +436,15 @@ export type CreatePhoneReminderTasksInput = {
    * in backend task execution. Provide this only for audit/fallback/optimization.
    */
   controllerPhone?: string;
+  /**
+   * Canonical subject reference (preferred): UUID/resource reference, email-based ref, or DID ref.
+   * Example: `Person/subject-uuid`, `Person/mailto:subject@example.com`, `Person/did:web:...`.
+   */
   subjectRef: string;
+  /**
+   * Canonical owner/controller reference (preferred): UUID/resource reference, email-based ref, or DID ref.
+   * Example: `RelatedPerson/controller-uuid`, `RelatedPerson/mailto:controller@example.com`.
+   */
   ownerRef: string;
   focusRef: string;
   subjectDisplay?: string;