gdc-sdk-node-ts 0.12.0 → 2.0.2

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.
 
@@ -46,6 +56,22 @@ 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-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 +115,22 @@ If you need the shortest path:
 - dataspace discovery and fallback/cache boundary:
   [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
 
+Immediate live validation target:
+
+- the next profile-runtime validation must be treated as an actor-profile suite,
+  not as a replay of the GW CORE platform lifecycle
+- the standalone current entry point for that is:
+  [tests/live-profile-runtime-individual.e2e.test.mjs](tests/live-profile-runtime-individual.e2e.test.mjs)
+- it should begin with `loadProfile(...)` for the target actor and then prove:
+  - `startIndividualOrganization(...)`
+  - `confirmIndividualOrganizationOrder(...)`
+  - the canonical current index/`Composition` read helper
+- if that actor flow creates lifecycle-owned state, `disable` / `purge` belong
+  at the end of that scenario as cleanup
+- until that live proof exists, treat `getLatestIps(...)` and
+  `searchClinicalBundle(...)` as candidate read contracts, not yet final
+  wording
+
 ## Executable Usage Examples
 
 Open these tests when you want to see exact method calls and exact inputs:
@@ -107,6 +149,9 @@ 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/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)
@@ -581,6 +626,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 +654,21 @@ 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. `Organization/_transaction`
+2. legacy `Organization/_activate` after ICA `_verify`
+3. `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

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

@@ -0,0 +1,214 @@
+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 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;
+};
+/**
+ * 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;
+}
+/**
+ * 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;
+/**
+ * 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>;