gdc-sdk-node-ts 0.12.0 → 2.0.4

package/README.md

@@ -1,5 +1,15 @@
 # gdc-sdk-node-ts
 
+See [ARCHITECTURE.md](./ARCHITECTURE.md) and
+[CONTRIBUTING.md](./CONTRIBUTING.md) before adding node runtime facades,
+execution adapters, or orchestration tests.
+
+Short rule:
+
+- `101` tests must read like executable tutorials
+- shared fixtures/types belong in `gdc-common-utils-ts`, not as local literals
+  in node runtime tests
+
 Node runtime package for consuming the shared GDC SDK contracts against real
 gateway backends.
 
@@ -32,6 +42,13 @@ Important live-run rule:
 - if sandboxed runs disagree with the user's terminal, trust the user's
   terminal for live GW validation
 
+Required live validation order:
+
+1. local process E2E from real TTY
+2. local Docker image/container E2E
+3. staging E2E
+4. production image/deploy only after staging is green
+
 Architectural rule:
 
 - shared contracts and actor boundaries come from `gdc-sdk-core-ts`
@@ -46,6 +63,26 @@ If you are integrating this package for the first time, open these in order:
 1. [gdc-sdk-core-ts/docs/101-SDK_PACKAGE_BOUNDARIES.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_PACKAGE_BOUNDARIES.md)
    Why `core`, `node`, and `front` are separate packages, what belongs in each
    one, and why actor-scoped facades must stay aligned across runtimes.
+1. [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](./tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
+   Canonical live backend/BFF walkthrough on a fresh local GW lifecycle:
+   host/tenant activation, employee provisioning, individual bootstrap,
+   consent grant, professional SMART token, clinical read, and final cleanup.
+1. [tests/101-backend-profile-runtime.test.mjs](./tests/101-backend-profile-runtime.test.mjs)
+   Minimal backend-generic walkthrough for loading one actor profile,
+   registering one trusted device/runtime context, connecting to one subject
+   index, reading one subject index composition, and then materializing the
+   `IndividualController` facade from the loaded backend session.
+   That walkthrough now uses the concrete direct backend runtime over the
+   injected `RuntimeClient`, not only one abstract adapter mock, and now also
+   demonstrates in-memory `JobManager` usage plus `closeProfile(...)`.
+1. [tests/101-individual-controller-backend-runtime.test.mjs](./tests/101-individual-controller-backend-runtime.test.mjs)
+   First pragmatic backend wrapper over the generic profile runtime for the
+   current individual-controller CORE baseline:
+   load profile, start registration, confirm order, and search the clinical
+   index.
+1. [docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md](./docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md)
+   Reconciles the old consumer flow with the current CORE registration baseline
+   and separates the stable registration base from later product extensions.
 1. [docs/101-SDK_END_TO_END.md](./docs/101-SDK_END_TO_END.md)
   Ordered onboarding guide with end-to-end journeys, copy/paste snippets, and
   the recommended reading path for new backend integrators.
@@ -89,6 +126,16 @@ If you need the shortest path:
 - dataspace discovery and fallback/cache boundary:
   [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
 
+Current live teaching target:
+
+- the main executable tutorial for integrators is now:
+  [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
+- the standalone actor-profile suites still exist as focused technical slices:
+  - [tests/live-profile-runtime-individual.e2e.test.mjs](tests/live-profile-runtime-individual.e2e.test.mjs)
+  - [tests/live-profile-runtime-professional.e2e.test.mjs](tests/live-profile-runtime-professional.e2e.test.mjs)
+- the larger runtime suite remains the regression-oriented environment proof:
+  [tests/live-gw-node-runtime.e2e.test.mjs](tests/live-gw-node-runtime.e2e.test.mjs)
+
 ## Executable Usage Examples
 
 Open these tests when you want to see exact method calls and exact inputs:
@@ -107,6 +154,12 @@ Open these tests when you want to see exact method calls and exact inputs:
   SMART token request flow.
 - [tests/live-gw-node-runtime.e2e.test.mjs](tests/live-gw-node-runtime.e2e.test.mjs)
   End-to-end runtime wiring against a real GW environment.
+- [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
+  Single live BFF-oriented `101` that chains tenant, professional, individual,
+  consent, SMART, read, and cleanup in one executable conversation.
+- [tests/live-profile-runtime-individual.e2e.test.mjs](tests/live-profile-runtime-individual.e2e.test.mjs)
+  Standalone actor-profile E2E for the individual controller on an already
+  operational tenant, including scenario-owned cleanup.
 - [tests/101-dataspace-resolver.test.mjs](tests/101-dataspace-resolver.test.mjs)
   Minimal `HttpDataspaceResolver` 101 with one host and one published provider.
 - [tests/101-default-first-dataspace-discovery.test.mjs](tests/101-default-first-dataspace-discovery.test.mjs)
@@ -115,8 +168,11 @@ Open these tests when you want to see exact method calls and exact inputs:
 
 ## Live GW CORE Flow
 
+Use [tests/101-live-full-cycle-bff-runtime.e2e.test.mjs](tests/101-live-full-cycle-bff-runtime.e2e.test.mjs)
+as the canonical live `101` for backend/BFF integrators.
+
 Use [tests/live-gw-node-runtime.e2e.test.mjs](tests/live-gw-node-runtime.e2e.test.mjs)
-as the canonical runtime flow.
+as the broader runtime-regression suite.
 
 Before running that suite, read:
 
@@ -137,18 +193,23 @@ Teaching rule:
 - `LIVE_GW_E2E_EXECUTION_MODE=direct` is the current and only supported mode
   for live validation; queued app-side job management is a later phase
 
-Current live flow covered by the test suite:
+Current live `101` flow covered by the test suite:
+
+1. activate one hosted tenant / legal organization
+2. provision one professional employee through the organization controller
+3. load the individual-controller profile and bootstrap one hosted individual
+4. confirm the returned order and verify the invoice bundle projection
+5. ingest one IPS/clinical `Communication` through the individual controller
+6. grant professional consent for one patient-summary section
+7. load the professional profile and request one SMART token
+8. read the allowed IPS bundle as the professional actor
+9. clean up consent, individual, employee, tenant, and host state
+
+Run the main live `101`:
 
-1. bootstrap tenant / legal organization
-2. bootstrap doctor or controller employee
-3. bootstrap individual and grant consent for the doctor
-   default example: `INDIVIDUAL_ALTERNATE_NAME=Doraemon`
-4. ingest two IPS `Communication` bundles, each with one `MedicationStatement`
-5. read the IPS/clinical index and verify both medications are present
-6. request the consolidated IPS bundle through
-   `Bundle?type=document&composition.subject=<did>&composition.type=http://loinc.org|60591-5`
-7. verify the returned bundle document contains both medication statements
-8. persist audit/debug traces in `test-results/*.jsonl`
+```bash
+npm run test:e2e:101:live-full-cycle
+```
 
 What is still not fully covered as one single root lifecycle:
 
@@ -581,6 +642,7 @@ modules below.
 ### Node runtime client
 
 - [`NodeHttpClient`](src/node-runtime-client.ts)
+- [`NodeHttpClient.submitLegalOrganizationVerificationTransaction(...)`](src/node-runtime-client.ts)
 - [`NodeHttpClient.ingestCommunicationAndUpdateIndex(...)`](src/node-runtime-client.ts)
 - [`NodeHttpClient.submitCommunicationAndPoll(...)`](src/node-runtime-client.ts)
 - [`NodeHttpClient.searchClinicalBundle(...)`](src/node-runtime-client.ts)
@@ -608,3 +670,47 @@ modules below.
 - README explains backend-facing flows first.
 - Shared contract shapes must be documented in `gdc-sdk-core-ts`, not duplicated here.
 - Route details and GW-specific behavior belong in runtime docs and JSDoc, not in app-facing examples.
+
+## Host Onboarding Runtime Flow
+
+For legal-organization onboarding from a Node BFF/runtime, keep the host steps separate:
+
+1. new flow: `Organization/_transaction`
+2. legacy compatibility flow: `ICA _verify -> Organization/_activate`
+3. downstream business continuation: `Order/_batch`
+
+Use `OrganizationControllerSdk.submitLegalOrganizationVerificationTransaction(...)` or
+`NodeHttpClient.submitLegalOrganizationVerificationTransaction(...)` for step 1.
+
+Rules:
+
+- `_transaction` and `_activate` are different flows
+- transport/runtime communication keys stay outside the business payload
+- controller binding key stays in `body.data[].resource.controller.*`
+- do not mix this path with `requestIcaEnrollment` or Fabric
+
+Legacy compatibility coverage in the live suite:
+
+- the canonical test is `LIVE professional lifecycle on GW`
+- set `RUN_LIVE_GW_E2E_HOST_VERIFICATION_TRANSACTION=1` to exercise:
+  - `Organization/_transaction -> Order/_batch`
+- set `RUN_LIVE_GW_E2E_HOST_VERIFICATION_TRANSACTION=0` to exercise the older:
+  - `ICA _verify -> Organization/_activate -> Order/_batch`
+
+Dedicated legacy live command:
+
+```bash
+cd /Users/fernando/GITS/gdc-workspace/gdc-sdk-node-ts
+RUN_LIVE_GW_E2E=1 \
+RUN_LIVE_GW_E2E_ACTOR_CHAIN=1 \
+RUN_LIVE_GW_E2E_HOST_VERIFICATION_TRANSACTION=0 \
+LIVE_GW_E2E_SUITE=professional \
+node --test tests/live-gw-node-runtime.e2e.test.mjs
+```
+
+Live E2E legal PDF source:
+
+- local file: set `LIVE_GW_HOST_VERIFICATION_PDF_PATH=/abs/path/file.pdf`
+- public URL: set `LIVE_GW_HOST_VERIFICATION_PDF_URL=https://.../file.pdf`
+- if both are present, the live suite prefers `LIVE_GW_HOST_VERIFICATION_PDF_URL`
+- Dropbox-style links are normalized to `dl=1` direct-download mode automatically

package/dist/backend-profile-runtime.d.ts

@@ -0,0 +1,262 @@
+import type { ActorProfileDescriptor, IJobManager, ActorKind, LoadedActorProfile, ProfileLoadRequest, SubjectIndexCompositionRequest, SubjectIndexConnectionRequest, TrustedDeviceRegistrationRequest } from 'gdc-sdk-core-ts';
+import type { ActorSession } from './session.js';
+import type { RuntimeClient } from './orchestration/client-port.js';
+import { IndividualControllerSdk } from './orchestration/individual-controller-sdk.js';
+import { OrganizationControllerSdk } from './orchestration/organization-controller-sdk.js';
+import { ProfessionalSdk } from './orchestration/professional-sdk.js';
+import type { RouteContext } from './individual-onboarding.js';
+/**
+ * Result of registering one trusted backend runtime device/profile context.
+ *
+ * This is intentionally backend-generic. It does not describe one concrete
+ * channel or product flow.
+ */
+export type BackendTrustedDeviceRegistrationResult = {
+    trustedDeviceId: string;
+    status: 'registered' | 'already-trusted';
+};
+/**
+ * Result of connecting one loaded actor profile to one subject index.
+ */
+export type BackendSubjectIndexConnectionResult = {
+    subjectId: string;
+    userId: string;
+    userRoleCode: string;
+    status: 'connected' | 'already-connected';
+};
+/**
+ * Result of reading one subject index composition after the relationship is
+ * already established.
+ */
+export type BackendSubjectIndexCompositionResult = {
+    subjectId: string;
+    userId: string;
+    userRoleCode: string;
+    composition: unknown;
+};
+export declare const BackendSubjectIndexReadModes: Readonly<{
+    LatestIps: "latest-ips";
+    ClinicalBundle: "clinical-bundle";
+}>;
+export type BackendSubjectIndexReadMode = typeof BackendSubjectIndexReadModes[keyof typeof BackendSubjectIndexReadModes];
+/**
+ * Backend materialization of one loaded actor profile with runtime sessions
+ * ready to expose actor-scoped facades.
+ */
+export type BackendLoadedActorProfile = LoadedActorProfile & {
+    actorSessions: ActorSession[];
+};
+export type BackendIndividualControllerProfile = {
+    profile: BackendLoadedActorProfile;
+    session: ActorSession;
+    sdk: IndividualControllerSdk;
+};
+export type BackendOrganizationControllerProfile = {
+    profile: BackendLoadedActorProfile;
+    session: ActorSession;
+    sdk: OrganizationControllerSdk;
+};
+export type BackendProfessionalProfile = {
+    profile: BackendLoadedActorProfile;
+    session: ActorSession;
+    sdk: ProfessionalSdk;
+};
+/**
+ * Canonical backend runtime contract for loading one actor profile after
+ * authentication and then working with trusted device registration and subject
+ * index access.
+ *
+ * This surface is intentionally generic for BFF or other backend runtimes.
+ * It does not encode one product-specific interaction channel.
+ */
+export type BackendProfileRuntimeClient = {
+    loadProfile?: (input: ProfileLoadRequest) => Promise<BackendLoadedActorProfile>;
+    closeProfile?: (profileKey: string) => Promise<void>;
+    registerTrustedDevice?: (input: TrustedDeviceRegistrationRequest) => Promise<BackendTrustedDeviceRegistrationResult>;
+    connectToSubjectIndex?: (input: SubjectIndexConnectionRequest) => Promise<BackendSubjectIndexConnectionResult>;
+    getSubjectIndexComposition?: (input: SubjectIndexCompositionRequest) => Promise<BackendSubjectIndexCompositionResult>;
+};
+export type BackendProfileRuntimeAdapters = {
+    loadProfile(input: ProfileLoadRequest): Promise<LoadedActorProfile>;
+    registerTrustedDevice(input: TrustedDeviceRegistrationRequest): Promise<BackendTrustedDeviceRegistrationResult>;
+    connectToSubjectIndex(input: SubjectIndexConnectionRequest): Promise<BackendSubjectIndexConnectionResult>;
+    getSubjectIndexComposition(input: SubjectIndexCompositionRequest): Promise<BackendSubjectIndexCompositionResult>;
+};
+export type BackendProfileRuntimeOptions = {
+    /**
+     * Runtime client injected into the materialized actor sessions so backend
+     * consumers can immediately call `asIndividualController()`,
+     * `asProfessional()`, and the other actor-specific facades after
+     * `loadProfile(...)`.
+     */
+    facadeClient?: RuntimeClient;
+};
+export type BackendLoadedProfileKey = string;
+export type DirectBackendProfileRuntimeOptions = BackendProfileRuntimeOptions & {
+    /**
+     * Default route context reused by the current GW CORE subject-index fallback.
+     *
+     * This is intentionally optional because some integrators only need
+     * `loadProfile(...)` plus explicit actor facades first.
+     */
+    defaultRouteContext?: RouteContext;
+    /**
+     * Current temporary CORE-facing index read helper to use when the caller asks
+     * for one subject index composition through the profile runtime.
+     *
+     * Until GW CORE freezes one canonical public profile-runtime read contract,
+     * keep this selectable instead of hardcoding one final wording.
+     */
+    subjectIndexReadMode?: BackendSubjectIndexReadMode;
+    /**
+     * Optional override for trusted-device registration while GW CORE finalizes
+     * the backend runtime contract for that step.
+     */
+    registerTrustedDevice?: (input: TrustedDeviceRegistrationRequest) => Promise<BackendTrustedDeviceRegistrationResult>;
+    /**
+     * Optional override for backend subject-index connection while GW CORE
+     * finalizes the stable contract for that step.
+     */
+    connectToSubjectIndex?: (input: SubjectIndexConnectionRequest) => Promise<BackendSubjectIndexConnectionResult>;
+    /**
+     * Optional override for reading the subject index after connection.
+     */
+    getSubjectIndexComposition?: (input: SubjectIndexCompositionRequest) => Promise<BackendSubjectIndexCompositionResult>;
+    /**
+     * Optional custom job-manager factory. When omitted, the backend runtime
+     * creates one in-memory job manager so `loadProfile(...)` returns one
+     * complete v2 profile object immediately.
+     */
+    createJobManager?: (descriptor: ActorProfileDescriptor, input: ProfileLoadRequest) => IJobManager;
+};
+/**
+ * Default backend-generic runtime implementation backed by injected adapters.
+ *
+ * This class is the first concrete v2 slice intended for backend consumers that
+ * need one reusable actor-aware profile runtime after authentication.
+ */
+export declare class BackendProfileRuntime implements BackendProfileRuntimeClient {
+    private readonly adapters;
+    private readonly options;
+    constructor(adapters: BackendProfileRuntimeAdapters, options?: BackendProfileRuntimeOptions);
+    loadProfile(input: ProfileLoadRequest): Promise<BackendLoadedActorProfile>;
+    closeProfile(_profileKey: string): Promise<void>;
+    registerTrustedDevice(input: TrustedDeviceRegistrationRequest): Promise<BackendTrustedDeviceRegistrationResult>;
+    connectToSubjectIndex(input: SubjectIndexConnectionRequest): Promise<BackendSubjectIndexConnectionResult>;
+    getSubjectIndexComposition(input: SubjectIndexCompositionRequest): Promise<BackendSubjectIndexCompositionResult>;
+}
+/**
+ * Current concrete backend profile runtime over one injected runtime client.
+ *
+ * This is the pragmatic v2 bridge for backend consumers that already possess
+ * an authenticated `RuntimeClient` and need `loadProfile(...)` to materialize
+ * actor facades immediately against the current GW CORE contract.
+ */
+export declare class DirectBackendProfileRuntime implements BackendProfileRuntimeClient {
+    private readonly loadedProfiles;
+    private readonly options;
+    constructor(options: DirectBackendProfileRuntimeOptions);
+    loadProfile(input: ProfileLoadRequest): Promise<BackendLoadedActorProfile>;
+    closeProfile(profileKey: string): Promise<void>;
+    registerTrustedDevice(input: TrustedDeviceRegistrationRequest): Promise<BackendTrustedDeviceRegistrationResult>;
+    connectToSubjectIndex(input: SubjectIndexConnectionRequest): Promise<BackendSubjectIndexConnectionResult>;
+    getSubjectIndexComposition(input: SubjectIndexCompositionRequest): Promise<BackendSubjectIndexCompositionResult>;
+    private rememberLoadedProfile;
+    private forgetLoadedProfile;
+    private resolveLoadedProfile;
+}
+/**
+ * Preferred developer-facing factory for the current backend profile runtime.
+ *
+ * Use this helper in tutorials and app/BFF code when you already have one
+ * configured runtime client and want the canonical
+ * `loadProfile(...) -> session -> actor facade` entrypoint without exposing the
+ * concrete class name in every example.
+ */
+export declare function createBackendProfileRuntime(options: DirectBackendProfileRuntimeOptions): BackendProfileRuntimeClient;
+/**
+ * Minimal in-memory `JobManager` for backend runtimes that do not need durable
+ * persistence during one live session.
+ */
+export declare function createJobManagerInMemory(descriptor: ActorProfileDescriptor): IJobManager;
+/**
+ * Requires one backend profile-runtime method from one runtime client.
+ */
+export declare function requireBackendProfileRuntimeMethod<T extends keyof BackendProfileRuntimeClient>(client: BackendProfileRuntimeClient, method: T): NonNullable<BackendProfileRuntimeClient[T]>;
+/**
+ * Canonical backend helper for loading one actor profile after authentication.
+ */
+export declare function loadBackendProfile(client: BackendProfileRuntimeClient, input: ProfileLoadRequest): Promise<BackendLoadedActorProfile>;
+/**
+ * Canonical backend helper for closing one loaded actor profile and clearing
+ * runtime-owned in-memory state.
+ */
+export declare function closeBackendProfile(client: BackendProfileRuntimeClient, profileKey: string): Promise<void>;
+/**
+ * Canonical backend helper for registering one trusted device/runtime context.
+ */
+export declare function registerBackendTrustedDevice(client: BackendProfileRuntimeClient, input: TrustedDeviceRegistrationRequest): Promise<BackendTrustedDeviceRegistrationResult>;
+/**
+ * Canonical backend helper for connecting one actor profile to one subject
+ * index after the profile is already loaded.
+ */
+export declare function connectBackendToSubjectIndex(client: BackendProfileRuntimeClient, input: SubjectIndexConnectionRequest): Promise<BackendSubjectIndexConnectionResult>;
+/**
+ * Canonical backend helper for reading one subject index composition after the
+ * relationship is already established.
+ */
+export declare function getBackendSubjectIndexComposition(client: BackendProfileRuntimeClient, input: SubjectIndexCompositionRequest): Promise<BackendSubjectIndexCompositionResult>;
+/**
+ * Returns one materialized backend actor session by actor kind.
+ *
+ * Backend callers should use this instead of scanning `actorSessions` manually.
+ */
+export declare function requireBackendActorSession(profile: BackendLoadedActorProfile, actorKind: ActorKind): ActorSession;
+/**
+ * Returns the individual-controller session from one loaded backend profile.
+ *
+ * This helper is the first concrete bridge from the generic backend runtime to
+ * the current individual bootstrap/index use case.
+ */
+export declare function requireBackendIndividualControllerSession(profile: BackendLoadedActorProfile): ActorSession;
+/**
+ * Materializes the individual-controller facade directly from one loaded
+ * backend profile.
+ */
+export declare function requireBackendIndividualControllerSdk(profile: BackendLoadedActorProfile): IndividualControllerSdk;
+/**
+ * Returns the organization-controller session from one loaded backend profile.
+ */
+export declare function requireBackendOrganizationControllerSession(profile: BackendLoadedActorProfile): ActorSession;
+/**
+ * Materializes the organization-controller facade directly from one loaded
+ * backend profile.
+ */
+export declare function requireBackendOrganizationControllerSdk(profile: BackendLoadedActorProfile): OrganizationControllerSdk;
+/**
+ * Returns the professional session from one loaded backend profile.
+ */
+export declare function requireBackendProfessionalSession(profile: BackendLoadedActorProfile): ActorSession;
+/**
+ * Materializes the professional facade directly from one loaded backend
+ * profile.
+ */
+export declare function requireBackendProfessionalSdk(profile: BackendLoadedActorProfile): ProfessionalSdk;
+/**
+ * Loads one backend profile and resolves the individual-controller session in
+ * one step.
+ *
+ * This is the first pragmatic use-case helper on top of the generic backend
+ * profile runtime, because the current stable CORE bootstrap baseline starts
+ * from the individual-controller flow.
+ */
+export declare function loadBackendIndividualControllerProfile(client: BackendProfileRuntimeClient, input: ProfileLoadRequest): Promise<BackendIndividualControllerProfile>;
+/**
+ * Loads one backend profile and resolves the organization-controller session in
+ * one step.
+ */
+export declare function loadBackendOrganizationControllerProfile(client: BackendProfileRuntimeClient, input: ProfileLoadRequest): Promise<BackendOrganizationControllerProfile>;
+/**
+ * Loads one backend profile and resolves the professional session in one step.
+ */
+export declare function loadBackendProfessionalProfile(client: BackendProfileRuntimeClient, input: ProfileLoadRequest): Promise<BackendProfessionalProfile>;