gdc-sdk-node-ts 0.9.1 → 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.
 
@@ -14,6 +24,24 @@ Use this package when your backend needs to:
 This package is for runtime execution. It is not the place where the canonical
 business contract is defined.
 
+Important test-harness boundary:
+
+- `gdc-sdk-node-ts` is not the product BFF
+- the live E2E suite simulates a controlled `virtual API` with a BFF-like role
+  only to validate GW CORE lifecycles end to end
+- the current live suites run with the future `user job manager` queue disabled,
+  so every high-level call goes directly through that controlled `virtual API`
+- app-side job queues, offline retry, local vault/read models, and the future
+  user job manager are separate follow-up concerns
+
+Important live-run rule:
+
+- the canonical live E2E result must come from the user's real terminal/TTY
+- do not assume an AI agent sandbox has equivalent localhost, Docker, DNS, or
+  GCP connectivity
+- if sandboxed runs disagree with the user's terminal, trust the user's
+  terminal for live GW validation
+
 Architectural rule:
 
 - shared contracts and actor boundaries come from `gdc-sdk-core-ts`
@@ -28,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.
@@ -44,10 +88,16 @@ If you are integrating this package for the first time, open these in order:
 5. [gdc-sdk-core-ts/docs/101-SDK_FLOWS.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/101-SDK_FLOWS.md)
    Actor split and business-flow map across organization, individual,
    permissions, invitation, import, and SMART flows.
-6. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
+6. [gwtemplate-node-ts/docs/PORTAL_API_TO_GW_CORE.md](https://github.com/Global-DataCare/gwtemplate-node-ts/blob/main/docs/PORTAL_API_TO_GW_CORE.md)
+   Canonical portal/BFF functional map over GW CORE, including the domain
+   split between `employees`, `related persons`, `members`, and `consents`.
+7. [gdc-common-utils-ts/src/examples/](https://github.com/Global-DataCare/gdc-common-utils-ts/tree/main/src/examples)
    Shared payload values used by the docs and tests.
-7. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
+8. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
    Canonical `enable/disable/delete` semantics and copy/paste placeholders.
+9. [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
+   Follow-up scope after GW CORE live validation, including the future user job
+   manager boundary.
 
 If you need the shortest path:
 
@@ -65,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:
@@ -83,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)
@@ -98,12 +167,20 @@ Before running that suite, read:
 
 - [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
 
+Execution requirement:
+
+- run the live suite from a real user terminal/TTY
+- if an AI agent is assisting, it should prefer a long-lived TTY process and
+  avoid treating sandbox-local connectivity failures as product failures
+
 Teaching rule:
 
 - defaults come from `gdc-common-utils-ts/examples`
 - override with env vars only when your tenant, bearer, or route is different
 - local GW default is `http://127.0.0.1:3000`
 - Docker-exposed GW can be overridden with `BASE_URL=http://127.0.0.1:8000`
+- `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:
 
@@ -118,6 +195,47 @@ Current live flow covered by the test suite:
 7. verify the returned bundle document contains both medication statements
 8. persist audit/debug traces in `test-results/*.jsonl`
 
+What is still not fully covered as one single root lifecycle:
+
+- initial organization license listing
+- extra-seat activation after the portal-side fictitious payment confirmation
+- relisting licenses after seat activation
+- one employee bundle with employee `A` and employee `B`
+- selective disable/purge validation across both employees
+- consent escalation from partial IPS access to broader IPS access
+- final cleanup of consent, individual, remaining employees, and tenant
+
+Current invoice/readback behavior:
+
+- both host and individual `Order/_batch-response` flows now return the flat
+  compatibility claims and an embedded invoice `Bundle`
+- the invoice bundle contains one FHIR `Invoice`, one PDF
+  `DocumentReference`, and one structured JSON/XML `DocumentReference`
+- live suites can read that bundle back through the same high-level response
+  body that the virtual API exposes to the simulated front
+
+Current runtime boundary:
+
+- `OrganizationControllerSdk.confirmOrganizationLicenseOrder(...)` now uses the
+  public host `Order/_batch` route used by GW CORE for portal-managed
+  post-payment seat activation
+- the long root lifecycle is still not fully closed because the suite does not
+  yet orchestrate the whole `license list -> pay -> confirm -> relist -> two
+  employees -> selective purge -> cleanup` dialogue as one single test
+
+The exact pending release-readiness checklist lives in:
+
+- [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
+
+Optional live lifecycle extension:
+
+- set `RUN_LIVE_GW_E2E_INDIVIDUAL_LIFECYCLE=1` to extend the same suite with
+  `disableIndividual(...)` + `purgeIndividual(...)` against the real
+  `gwtemplate-node-ts` runtime contract
+- this extra block is intentionally separate from the default happy path
+  because it changes lifecycle state and should only run when that tenant/test
+  subject is disposable
+
 Shared example source of truth:
 
 - tenant/route/controller/professional defaults:
@@ -141,6 +259,20 @@ Run the full live runtime baseline:
 npm run test:e2e:live-gw
 ```
 
+Select one live transport profile from the same Node entrypoint:
+
+```bash
+npm run test:e2e:live-gw:didcomm-plain
+npm run test:e2e:live-gw:legacy-fhir
+npm run test:e2e:live-gw:all
+```
+
+Profile note:
+
+- `didcomm-plain` is the current live baseline implemented by the Node runtime client
+- `legacy-fhir` exercises raw `application/fhir+json` async batch submission for `org.hl7.fhir.*`
+- `all` runs every implemented profile from the same suite file
+
 Run the IPS ingestion/search branch as well:
 
 ```bash
@@ -494,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)
@@ -521,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>;