dataspace-client-sdk-node 0.2.2 → 0.2.4

package/README.md

@@ -4,20 +4,19 @@ Node.js SDK to consume GW/UNID async DIDComm endpoints.
 
 ## Documentation Index
 
-1. [Full API Reference](docs/API.md)
-2. [Data Model Alignment (GW + Chat + SDK)](docs/DATA_MODEL_ALIGNMENT.md)
-3. [Frontend/Backend SDK Ownership Matrix](../docs/SDK_AUTH_OWNERSHIP.md)
-4. [Developer Use-Case Cookbook (UC5 + additional patterns)](docs/DEVELOPER_USE_CASES.md)
-5. [Live Local GW UC5 E2E (no mocks)](docs/E2E_LOCAL_GW_UC5.md)
-6. [React Web Integration Guide](docs/REACT_WEB_INTEGRATION.md)
-7. [Backend Node Integration Guide](docs/BACKEND_NODE_INTEGRATION.md)
-8. [Controller Flow Step by Step](docs/CONTROLLER_FLOW_STEP_BY_STEP.md)
-9. [Legal Organization Flow Step by Step](docs/LEGAL_ORGANIZATION_FLOW_STEP_BY_STEP.md)
-10. [Practitioner Flow Step by Step](docs/PRACTITIONER_FLOW_STEP_BY_STEP.md)
-11. [Portal Backend Integration Handover](docs/PORTAL_BACKEND_INTEGRATION_HANDOVER.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. [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
 
-1. [Prompt Next Steps TODO](TODO_PROMPT_NEXT_STEPS.md)
-2. [SMART EHR Compatibility TODO](docs/TODO_SMART_EHR_COMPAT.md)
-3. [SDK Parity Map](../SDK_PARITY_MAP.md)
+1. [Prompt Next Steps TODO](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/TODO_PROMPT_NEXT_STEPS.md)
+2. [SMART EHR Compatibility TODO](https://github.com/Global-DataCare/dataspace-client-sdk-node/blob/main/docs/TODO_SMART_EHR_COMPAT.md)

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.2",
+  "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;

package/TODO_PROMPT_NEXT_STEPS.md

@@ -1,185 +0,0 @@
-# TODO / Prompt - Next Steps (dataspace-client-sdk-node)
-
-Objetivo de este backlog:
-- Mantener `dataspace-client-sdk-node` como SDK backend oficial para Node.
-- Añadir una capa wallet/KMS reutilizable para clientes backend Node (paridad conceptual con Python).
-- Evitar que servicios consumidores implementen crypto/auth ad-hoc fuera del SDK.
-
-Importante (decisión de arquitectura actual):
-- El wallet/KMS se implementa temporalmente dentro de este repo en:
-  - `src/sdk/dataspace-wallet-sdk-node/`
-- Más adelante se extraerá a repo/npm independiente (`dataspace-wallet-sdk-node`) sin romper API.
-
-## Repositorio fuente y referencias obligatorias
-
-Estas son las fuentes que el agente debe tomar como referencia técnica antes de implementar:
-
-1. Frontend / cliente app:
-- `gdc-sdk-client-ts`
-- Papel: SDK frontend/wallet UX-side (no backend custodial KMS).
-
-2. Backend gateway template:
-- `gwtemplate-node-ts`
-- Ruta clave: `src/gdc-backend-utils-node`
-- Papel: utilidades backend de crypto/KMS y contratos base.
-
-3. Backend UNID (fork operativo):
-- `gdc-unid-node-ts`
-- Papel: integración real de GW + managers + KMS runtime + flujos de negocio.
-
-4. SDK Python de referencia de paridad:
-- `connector-sdk-py`
-- Papel: referencia 1:1 de casos de uso backend.
-
-5. Orquestador de canal (consumidor actual):
-- `uhc-unid-chat-node`
-- Papel: usa SDK de alto nivel; no debe contener crypto/KMS de backend.
-
-Regla: si hay contradicción entre implementación Node actual y Python, documentar la divergencia y dejar TODO de convergencia.
-
-## Contexto que el agente debe respetar
-
-1. `uhc-unid-chat-node` y otros consumidores deben seguir usando métodos de alto nivel del SDK.
-2. Los cambios internos de path builders de identidad son breaking solo para consumidores que montan rutas a mano.
-3. Si el consumidor usa `authenticateBackendPkceAndExchange(...)`, no debe cambiar nada en su código por la migración de rutas identity.
-
-## Funcionamiento actual de backend tools + KMS (baseline)
-
-Resumen operativo esperado por el ecosistema backend:
-
-1. Capa SDK cliente (`dataspace-client-sdk-node`):
-- construye paths canónicos,
-- hace submit/poll,
-- orquesta auth backend (`_dcr -> _code -> _token -> _exchange`).
-
-2. Capa backend utils / KMS (hoy en GW/template repos):
-- `KmsService` / `DemoKmsService`,
-- interfaces de crypto (`IKmsService`, tipos JWK/JWS/JWE),
-- utilidades KEK/envelope para protección de claves y datos.
-
-3. Capa GW backend (`gdc-unid-node-ts` / `gwtemplate-node-ts`):
-- runtime multitenant,
-- provisión y resolución de claves por tenant,
-- operaciones de firma/verificación/cifrado en contexto servidor.
-
-Límite de responsabilidad:
-- `dataspace-client-sdk-node` no debe replicar managers de GW.
-- Sí debe poder exponer wallet/KMS cliente reutilizable para backends no-GW.
-
-## Definición de Hecho (DoD)
-
-1. Existe módulo wallet interno funcional con interfaz pública estable.
-2. El flujo `identity-exchange.v1` está soportado por métodos de alto nivel en Node (sin construir rutas manuales fuera del SDK).
-3. Se documenta paridad Node/Python por capability (no solo por endpoint).
-4. Hay tests que fallen si se rompe la paridad mínima acordada.
-5. README y ejemplos permiten a otro equipo integrar sin leer código interno.
-
-## Alcance técnico a implementar
-
-### A) Wallet/KMS interno (nuevo)
-
-Crear módulo en `src/sdk/dataspace-wallet-sdk-node/`:
-
-- `types.ts`
-  - `WalletContext` (`tenantId`, `jurisdiction`, `sector`, opcional `walletId`)
-  - `PublicJwk`, `PrivateKeyRef`, `SignOptions`, `EncryptOptions`, `DecryptOptions`
-  - `WalletProviderKind = 'mem' | 'seed' | 'external'`
-
-- `provider.ts`
-  - `WalletProvider` interface:
-    - `init(...)`
-    - `getPublicJwks(context)`
-    - `sign(payload, context, options)`
-    - `verify(payload, signature, jwk)`
-    - `encrypt(plaintext, recipientJwk, options)`
-    - `decrypt(ciphertext, context, options)`
-
-- `providers/memory-provider.ts`
-  - provider mínimo productivo para pruebas.
-
-- `providers/seed-provider.ts`
-  - solo para `demo/dev` (determinístico).
-  - prohibido recomendarlo para staging/prod.
-
-- `WalletClient.ts`
-  - fachada single-tenant.
-
-- `MultiWalletClient.ts`
-  - resolución por `tenantId/jurisdiction/sector`.
-
-### B) Integración en `DataspaceNodeClient`
-
-- Aceptar opcionalmente `wallet` en constructor/options.
-- Mantener compatibilidad de los métodos actuales de negocio/auth.
-- No mover lógica de dominios al wallet: wallet solo crypto/key operations.
-
-### C) Auth de alto nivel (paridad Python)
-
-Asegurar métodos de alto nivel para:
-- `authenticateBackendPkceAndExchange(...)`
-- base para `authenticateBackendSmartStandard(...)` (si el contrato backend ya está listo)
-
-Notas:
-- Internamente usar path builders canónicos nuevos.
-- Evitar exponer helpers de rutas como API pública “recomendada” para auth.
-
-## Plan de ejecución (orden obligatorio)
-
-1. Fase 1 - Contratos y estructura
-- Crear árbol `src/sdk/dataspace-wallet-sdk-node/*`.
-- Definir interfaces y tipos.
-- Añadir tests unitarios de contrato (sin integración GW todavía).
-
-2. Fase 2 - Provider mem/seed
-- Implementar `memory-provider` y `seed-provider`.
-- Añadir tests de firma/verificación y cifrado/descifrado.
-
-3. Fase 3 - Integración client
-- Conectar wallet opcional en `src/client.ts`.
-- Mantener sin breaking en usos actuales.
-
-4. Fase 4 - Paridad y documentación
-- Actualizar `SDK_PARITY_MAP.md` con estado real.
-- Actualizar `README.md` con sección “Wallet/KMS for backend clients”.
-- Añadir ejemplo runnable en `examples/`.
-
-5. Fase 5 - Puerta de extracción futura
-- Definir imports internos de forma que luego sea fácil reemplazar:
-  - `src/sdk/dataspace-wallet-sdk-node/*` -> paquete npm externo.
-
-## Tests mínimos obligatorios
-
-1. Unit tests wallet:
-- sign/verify roundtrip
-- encrypt/decrypt roundtrip
-- error handling de context faltante
-
-2. Unit tests auth orchestration:
-- secuencia `_dcr -> _code -> _token -> _exchange`
-- gestión de token cacheado vs refresh
-
-3. Regression tests identity routes:
-- verificar que internamente se usa patrón canónico
-  - `/{prefix}/cds-{j}/v1/{sector}/{tenantId}/identity/auth/{action}`
-
-4. Public API smoke:
-- import del SDK no rompe para consumidores actuales.
-
-## Criterios de seguridad
-
-- Ninguna private key en logs.
-- `seed-provider` marcado explícitamente como no apto para staging/prod.
-- Errores crypto sin volcar material sensible.
-
-## Entregables esperados del agente
-
-1. PR con código + tests + docs.
-2. Resumen de decisiones (tradeoffs) en la descripción.
-3. Tabla de estado actualizada en `SDK_PARITY_MAP.md`.
-4. Lista de pendientes para extracción a repo independiente.
-
-## Plantilla de commit sugerida
-
-- `feat(wallet): add internal dataspace-wallet-sdk-node module (mem/seed providers)`
-- `feat(auth): keep pkce high-level orchestration aligned with canonical identity routes`
-- `docs(parity): update SDK parity map and wallet roadmap`