gdc-sdk-node-ts 0.2.1 → 0.3.0

package/README.md

@@ -1,176 +1,360 @@
 # gdc-sdk-node-ts
 
-Target Node runtime package for the converged GDC SDK family.
-
-Key docs:
-
-- [CHANGELOG.md](CHANGELOG.md)
-- [SECURITY.md](SECURITY.md)
-- [TEST_CORE.md](TEST_CORE.md)
-- [SDK_INTEGRATION_101.md](SDK_INTEGRATION_101.md)
-
-Current status:
-
-- package created
-- build/test baseline created
-- migration target from `dataspace-client-sdk-node` completed for live runtime path
-- runtime contract skeleton declared
-- actor-scoped node session bridge implemented
-- first actor-scoped orchestration facades implemented on top of `GdcNodeRuntimeClient`
-- shared async submit/poll helpers implemented for converged Node orchestration
-- live GW E2E migrated here with `gdc-sdk-node-ts` runtime client only, with JSONL debug/HTTP trace artifacts under `test-results/`
-
-Not migrated yet:
-
-- full wallet/runtime adapter parity from legacy package
-- secure E2E script parity in this package
-- full live use-case parity matrix vs legacy suite
-
-Live validation:
-
-- `npm run test:e2e:live-gw`
-- core coverage summary for memory/thesis justification: `TEST_CORE.md`
-- optional:
-  - `BASE_URL=http://127.0.0.1:8000`
-  - `RUN_LIVE_GW_E2E_IPS_INGESTION=1`
-  - `LIVE_GW_NODE_E2E_DEBUG=1`
-- artifacts:
-  - `test-results/live-gw-node-runtime-debug-*.jsonl`
-  - `test-results/live-gw-http-trace-*.jsonl`
-
-Runtime migration note:
-
-- the live E2E in this package no longer imports `dataspace-client-sdk-node`
-- actor-scoped facades now run on the in-package `GdcNodeHttpClient`
-- remaining migration scope is parity hardening, not runtime ownership
-- this package now consumes the published `gdc-common-utils-ts` `^1.4.22` line; the sibling checkout is only needed for source browsing and optional local cross-repo work
-
-Role in the transition:
-
-- `gdc-sdk-core-ts` will own shared actor/capability contracts
-- `gdc-sdk-node-ts` will own Node runtime adapters and backend-facing orchestration
-- `dataspace-client-sdk-node` is now the legacy source repo for migration, not the final name
-
-Reusable payload source of truth:
-
-- [../gdc-common-utils-ts/src/examples/organization-controller.ts](../gdc-common-utils-ts/src/examples/organization-controller.ts)
-  - `_activate`, legal order, employee creation, employee device activation
-- [../gdc-common-utils-ts/src/examples/individual-controller.ts](../gdc-common-utils-ts/src/examples/individual-controller.ts)
-  - individual bootstrap, consent, search, communication ingestion, digital twin
-- [../gdc-common-utils-ts/src/examples/professional.ts](../gdc-common-utils-ts/src/examples/professional.ts)
-  - SMART token and clinical access request examples
-  - reusable professional role/permission scenarios by section and expected FHIR types
-  - reusable consent-vs-smart matrices for actor targeting by email, organization, or jurisdiction
-- [../gdc-common-utils-ts/src/examples/shared.ts](../gdc-common-utils-ts/src/examples/shared.ts)
-  - shared route contexts and helper builders
-- [../gdc-common-utils-ts/src/examples/api-flow-examples.ts](../gdc-common-utils-ts/src/examples/api-flow-examples.ts)
-  - preferred compatibility aggregator when one import surface is needed without using the overloaded term `contract`
-- [tests/fixtures/ica-vp-minimal.json](tests/fixtures/ica-vp-minimal.json)
-  - minimal VP fixture used by live GW onboarding/smart flows
-
-CORE vs extension note:
-
-- shared CORE examples are email-first for individual/controller bootstrap
-- `subjectPhone`, `subjectGivenName`, and phone-first controller onboarding are compatibility or extension concerns, not required CORE GW contract fields
-- route `tenantId` examples use identifier-style values such as `acme-id`, not friendly alternate names
-- individual/family bootstrap uses `org.schema.Organization.owner.*` claims for the human owner/controller
-- legal organization activation uses `Person` representative semantics plus VC `memberOf` / `hasOccupation`
+Node runtime package for consuming the shared GDC SDK contracts against real
+gateway backends.
+
+Use this package when your backend needs to:
+
+- call GW APIs
+- submit/poll async operations
+- orchestrate onboarding, consent, communication, and search flows
+- consume the shared relationship invitation/acceptance contracts from
+  `gdc-sdk-core-ts`
+
+This package is for runtime execution. It is not the place where the canonical
+business contract is defined.
+
+## Start Here
+
+If you are integrating this package for the first time, open these in order:
+
+1. [docs/SDK_END_TO_END_101.md](./docs/SDK_END_TO_END_101.md)
+   Ordered onboarding guide with end-to-end journeys, copy/paste snippets, and
+   the recommended reading path for new backend integrators.
+2. [docs/SDK_INTEGRATION_101.md](./docs/SDK_INTEGRATION_101.md)
+   Real backend setup, imports, `initializeCommunicationIdentity(...)`,
+   `new NodeHttpClient(...)`, route context, facade selection, and live method
+   usage.
+3. [gdc-sdk-core-ts/docs/SDK_FLOWS_101.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/docs/SDK_FLOWS_101.md)
+   Actor split and business-flow map across organization, individual,
+   permissions, invitation, import, and SMART flows.
+4. [gdc-common-utils-ts/src/examples/](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/tree/main/src/examples)
+   Shared payload values used by the docs and tests.
+5. [gdc-common-utils-ts/docs/LIFECYCLE_101.md](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/docs/LIFECYCLE_101.md)
+   Canonical `enable/disable/delete` semantics and copy/paste placeholders.
+
+If you need the shortest path:
+
+- main onboarding guide:
+  [docs/SDK_END_TO_END_101.md](./docs/SDK_END_TO_END_101.md)
+- GW CORE app identity:
+  `appId` mandatory, `appVersion` optional with default `v1.0`
+- backend technical identity:
+  [`initializeCommunicationIdentity(...)`](./docs/SDK_INTEGRATION_101.md)
+- runtime client:
+  [`NodeHttpClient`](src/node-runtime-client.ts)
+- step-by-step runtime usage:
+  [docs/SDK_INTEGRATION_101.md](./docs/SDK_INTEGRATION_101.md)
+
+## Executable Usage Examples
+
+Open these tests when you want to see exact method calls and exact inputs:
+
+- [tests/host-onboarding.test.mjs](tests/host-onboarding.test.mjs)
+  Organization activation and order confirmation.
+- [tests/individual-start.test.mjs](tests/individual-start.test.mjs)
+  Individual organization start flow.
+- [tests/individual-onboarding.test.mjs](tests/individual-onboarding.test.mjs)
+  Individual order/offer confirmation flow.
+- [tests/device-activation.test.mjs](tests/device-activation.test.mjs)
+  Employee activation code and activation request flows.
+- [tests/resource-operations.test.mjs](tests/resource-operations.test.mjs)
+  Related person upsert, communication ingestion, search, and access grants.
+- [tests/smart-token.test.mjs](tests/smart-token.test.mjs)
+  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.
+
+## Actor Split And Runtime Scope
+
+This package must be understandable from the same actor split used by the
+shared contracts:
+
+- organization controller
+- organization employee / professional member
+- individual controller
+- individual member / self
+- related person
+- professional with consented access
+
+The Node runtime layer is where those shared flows are executed against GW.
+That includes organization onboarding, employee creation, individual bootstrap,
+permission grants, `RelatedPerson` upserts, SMART token requests, and clinical
+data ingestion/search.
+
+## Flow Families
+
+- organization activation and order/offer confirmation
+- employee creation and employee activation
+- individual organization start and order confirmation
+- related person upsert
+- professional access grant
+- invitation / OTP / relationship PIN runtime wiring
+- permission-request `Communication`
+- communication ingestion and search
+- SMART token retrieval
+
+## Main Flows
+
+### 1. Controller invites a related person or professional
+
+Typical backend sequence:
+
+1. build shared invitation payload with `gdc-sdk-core-ts`
+2. send it through the node runtime client or your backend adapter
+3. persist or return the invitation state to portal/app
+
+What matters here:
+
+- this package executes the runtime call
+- `gdc-sdk-core-ts` defines the payload shape
+- callers should not hardcode route families in app code
+
+### 2. Invitee accepts the relationship
+
+Typical backend sequence:
+
+1. start OTP challenge
+2. confirm OTP
+3. set relationship PIN if required
+4. activate the relationship channel
+
+Shared contract builders come from `gdc-sdk-core-ts`; this package is where a
+Node backend wires them to real runtime operations.
+
+### 3. Consent-aware communication and search
+
+Use this package when your backend needs to:
+
+- ingest `Communication`
+- search clinical bundles
+- request SMART tokens
+- grant access
+- create or update `RelatedPerson`
+
+## What This Package Owns
+
+- Node runtime client
+- submit/poll orchestration
+- actor-scoped node sessions
+- backend-facing orchestration helpers
+
+## What This Package Does Not Own
+
+- the canonical invitation/OTP/PIN contract
+- UNID-specific reminder runtime semantics
+- frontend session UX
+
+Those belong to:
+
+- `gdc-sdk-core-ts` for shared contracts
+- runtime extensions such as UNID/UHC for product-specific behavior
+- `gdc-sdk-front-ts` for frontend-facing consumption
+
+## Minimal Examples
+
+### Use shared invitation contract from Node
+
+```ts
+import {
+  createRelationshipChannelInvitationInput,
+  RelationshipAccessActorKinds,
+  RelationshipEnrollmentChannels,
+  type RelationshipChannelInvitationInput,
+} from 'gdc-sdk-core-ts';
+import {
+  buildIndividualDidWeb,
+  HealthcareActorRoles,
+  HealthcareConsentPurposes,
+} from 'gdc-common-utils-ts';
+
+const tenantId = 'acme-id';
+const jurisdiction = 'ES';
+const sector = 'health-care';
+const providerOrganizationDid = subjectProfile.organizationDid;
+const subjectLocalId = subjectProfile.subjectId;
+const subjectId = buildIndividualDidWeb({
+  organizationDidWeb: providerOrganizationDid,
+  subjectId: subjectLocalId,
+});
+const professionalEmail = invitedProfessional.email;
+
+const invitationInput: RelationshipChannelInvitationInput = {
+  tenantId,
+  jurisdiction,
+  sector,
+  subjectId,
+  subjectKind: 'person',
+  actorKind: RelationshipAccessActorKinds.Professional,
+  actorIdentifier: professionalEmail,
+  actorRole: HealthcareActorRoles.Physician,
+  deliveryChannel: RelationshipEnrollmentChannels.Email,
+  deliveryTarget: professionalEmail,
+  purpose: HealthcareConsentPurposes.Treatment,
+  relationshipLabel: 'primary-physician',
+  phonePinOptional: false,
+};
+
+const invitation = createRelationshipChannelInvitationInput(invitationInput);
+```
+
+The backend should obtain those variables from:
+
+- tenant route selection
+- target subject identifier
+- invited actor identity
+- selected enrollment channel
+- intended purpose/relationship label
+
+### Request SMART token and search bundle
+
+```ts
+import { NodeHttpClient } from 'gdc-sdk-node-ts';
+import {
+  EXAMPLE_LATEST_IPS_SEARCH_INPUT,
+} from 'gdc-common-utils-ts/examples/individual-controller';
+import { HealthcareBasicSections } from 'gdc-common-utils-ts/constants/healthcare';
+import { buildSmartCompositionReadScope } from 'gdc-common-utils-ts/utils/smart-scope';
+
+const client = new NodeHttpClient({ baseUrl: process.env.BASE_URL! });
+
+const subjectDid = EXAMPLE_LATEST_IPS_SEARCH_INPUT.subject;
+
+const token = await client.requestSmartToken({
+  ctx,
+  actorDid: 'did:web:doctor.example.org:employee:001',
+  subjectDid,
+  scopes: [
+    buildSmartCompositionReadScope({
+      subjectDid,
+      sections: HealthcareBasicSections.PatientSummaryDocument.claim,
+    }),
+  ],
+  idToken: '...',
+});
+
+const result = await client.searchClinicalBundle(ctx, {
+  subject: subjectDid,
+});
+```
+
+Teaching rule:
+
+- start with the composition read scope when the actor only needs subject-scoped read access
+- add `SmartGatewayScopesFhirR4.ConsentCruds` only if the backend also needs consent management operations
+
+## Shared Contract Sources
+
+- [gdc-sdk-core-ts/README.md](https://github.com/Global-DataCare/gdc-sdk-core-ts/blob/main/README.md)
+- [gdc-common-utils-ts/docs/CONSENT_ACCESS_101.md](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/docs/CONSENT_ACCESS_101.md)
+
+Reusable payload examples:
+
+- [gdc-common-utils-ts/src/examples/organization-controller.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/organization-controller.ts)
+- [gdc-common-utils-ts/src/examples/individual-controller.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/individual-controller.ts)
+- [gdc-common-utils-ts/src/examples/professional.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/professional.ts)
+- [gdc-common-utils-ts/src/examples/shared.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/shared.ts)
+- [gdc-common-utils-ts/src/examples/lifecycle.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/lifecycle.ts)
+- [gdc-common-utils-ts/src/examples/api-flow-examples.ts](https://gitlab.dev.accuro.es/idi/espacio-de-datos/global-datacare/gdc-common-utils-ts/-/blob/main/src/examples/api-flow-examples.ts)
 
 ## API Index
 
-The canonical API contract should live in JSDoc on exported code. The README is the linked index.
-
-### Core document helpers re-exported from `gdc-sdk-core-ts`
-
-- [`createCommunicationResource(...)`](../gdc-sdk-core-ts/src/communication-resource-helpers.ts)
-  - Creates a minimal FHIR `Communication` resource.
-  - Main params: `subject`, `sender?`, `recipient?`, `sent?`, `status?`, `category?`, `noteText?`, `claims?`.
-- [`addFhirResourceToCommunication(...)`](../gdc-sdk-core-ts/src/communication-resource-helpers.ts)
-  - Attaches a FHIR resource to `Communication.payload`, optionally wrapped as `DocumentReference`.
-  - Main params: `communication`, `resource`, `noteText?`, `asDocumentReference?`, `attachmentTitle?`, `attachmentContentType?`, `documentDescription?`, `documentDate?`, `documentSubject?`.
-- [`addClaimsResourceToCommunication(...)`](../gdc-sdk-core-ts/src/communication-resource-helpers.ts)
-  - Attaches a claims-only pseudo-resource using `meta.claims`.
-  - Main params: `communication`, `resourceType`, `claims`, `options?`.
-- [`buildCommunicationBatchMessage(...)`](../gdc-sdk-core-ts/src/communication-resource-helpers.ts)
-  - Wraps a FHIR `Communication` into a GW-ready batch envelope.
-  - Main params: `communication`, `thid?`, `jti?`, `iss?`, `aud?`, `requestUrl?`, `entryType?`, `messageType?`, `fhirVersion?`.
-- [`createCommunicationFacade()`](../gdc-sdk-core-ts/src/communication-document-facade.ts)
-  - Creates the high-level document access facade.
-- [`getDocumentFromCommunication(...)`](../gdc-sdk-core-ts/src/communication-document-facade.ts)
-  - Resolves the first attached document and hides direct attachment vs `DocumentReference`.
-- [`createFhirDocumentFacade(...)`](../gdc-sdk-core-ts/src/communication-document-facade.ts)
-  - Exposes `getBundle()`, `getSections()`, `getResources(resourceType?)`, `getByDates(resourceType, start, end?)`, `getContainingTextOrDisplay(resourceType, text)`.
-- [`createCommunicationDraft(...)`](../gdc-sdk-core-ts/src/communication-draft.ts)
-  - Starts an in-memory communication draft.
-- [`addFhirResourceToDraft(...)`](../gdc-sdk-core-ts/src/communication-draft.ts)
-  - Appends a concrete FHIR resource to the draft.
-- [`addClaimsResourceToDraft(...)`](../gdc-sdk-core-ts/src/communication-draft.ts)
-  - Appends a claims-only pseudo-resource to the draft.
-- [`createOutboxJobFromDraft(...)`](../gdc-sdk-core-ts/src/communication-draft.ts)
-  - Freezes the draft into a transport-oriented outbox job.
-- [`updateOutboxJobStatus(...)`](../gdc-sdk-core-ts/src/communication-draft.ts)
-  - Updates the outbox job status and transport result metadata.
-- [`groupConsentsForControllerView(...)`](../gdc-sdk-core-ts/src/consent-access.ts)
-  - Aggregates all active consent rules for one subject and groups them by actor-specific, organization, jurisdiction, and phone-extension target.
-- [`evaluateRequestedAccess(...)`](../gdc-sdk-core-ts/src/consent-access.ts)
-  - Evaluates effective permission coverage with first-tier precedence for concrete email matches, then organization and jurisdiction coverage.
-- [`getMissingPermissions(...)`](../gdc-sdk-core-ts/src/consent-access.ts)
-  - Extracts deterministic missing section/resource-type coverage for a SMART request.
-- [`buildPermissionRequestCommunication(...)`](../gdc-sdk-core-ts/src/consent-access.ts)
-  - Builds the canonical `Communication` payload used to request additional subject-controlled access.
-- [`buildPermissionRequestCommunicationLookupQuery(...)`](../gdc-sdk-core-ts/src/consent-access.ts)
-  - Builds a subject-scoped lookup query for recovering the permission request by `Communication.identifier`, `thid`, or `DocumentReference.contenthash`.
-- [`IOutboxRepository`](../gdc-sdk-core-ts/src/communication-outbox.ts)
-- [`OutboxRepositoryMemory`](../gdc-sdk-core-ts/src/communication-outbox.ts)
-- [`createHeartRateObservation(...)`](../gdc-sdk-core-ts/src/vital-signs.ts)
-- [`createBodyTemperatureObservation(...)`](../gdc-sdk-core-ts/src/vital-signs.ts)
-- [`createBloodPressureObservation(...)`](../gdc-sdk-core-ts/src/vital-signs.ts)
+## Full Public Surface
+
+This package exports the full `gdc-sdk-core-ts` surface plus the Node runtime
+modules below.
+
+- [`src/runtime-contracts.ts`](src/runtime-contracts.ts)
+  - types/constants: `LegacyNodeSourcePackage`, `NodeRuntimeMode`, `NodeInteropMode`, `TenantContext`, `NodeOperatorContext`, `NodeFetchLike`, `NodeRuntimeConfig`, `NodePackageStatus`, `GDC_SDK_NODE_STATUS`
+- [`src/identity-bootstrap.ts`](src/identity-bootstrap.ts)
+  - function: `initializeCommunicationIdentity(...)`
+- [`src/async-polling.ts`](src/async-polling.ts)
+  - types: `AcceptedPollResponse`
+  - function: `pollUntilCompleteWithMethod(...)`
+- [`src/poll-options.ts`](src/poll-options.ts)
+  - re-export: `resolvePollOptionsFromSeconds(...)`
+- [`src/host-onboarding.ts`](src/host-onboarding.ts)
+  - types: `HostRouteContext`, `LegalOrganizationOrderInput`
+  - function: `confirmLegalOrganizationOrderWithDeps(...)`
+- [`src/individual-start.ts`](src/individual-start.ts)
+  - types: `IndividualOrganizationBootstrapInput`, `OfferPreview`, `IndividualOrganizationStartResult`
+  - function: `startIndividualOrganizationWithDeps(...)`
+- [`src/individual-onboarding.ts`](src/individual-onboarding.ts)
+  - types: `RouteContext`, `IndividualOrganizationConfirmOrderInput`
+  - function: `confirmIndividualOrganizationOrderWithDeps(...)`
+- [`src/device-activation.ts`](src/device-activation.ts)
+  - types: `EmployeeDeviceActivationInput`, `EmployeeDeviceActivationRequestInput`, `EmployeeDeviceActivationResult`
+  - functions: `activateEmployeeDeviceWithActivationCodeWithDeps(...)`, `activateEmployeeDeviceWithActivationRequestWithDeps(...)`
+- [`src/smart-token.ts`](src/smart-token.ts)
+  - types: `SmartTokenRequestInput`, `SmartTokenExchangeResult`
+  - function: `requestSmartTokenWithDeps(...)`
+- [`src/resource-operations.ts`](src/resource-operations.ts)
+  - types: `OrganizationEmployeeCreationInput`, `IpsOrFhirImportInput`, `RelatedPersonUpsertInput`, `CommunicationIngestionInput`, `ClinicalDateRange`, `ClinicalBundleSearchInput`, `ConsentActorTargetInput`, `GrantProfessionalAccessInput`, `GrantProfessionalAccessResult`, `DigitalTwinGenerationInput`
+  - functions: `createOrganizationEmployeeWithDeps(...)`, `importIpsOrFhirAndUpdateIndexWithDeps(...)`, `upsertRelatedPersonAndPollWithDeps(...)`, `ingestCommunicationAndUpdateIndexWithDeps(...)`, `searchClinicalBundleWithDeps(...)`, `searchLatestIpsWithDeps(...)`, `grantProfessionalAccessWithDeps(...)`, `generateDigitalTwinFromSubjectDataWithDeps(...)`
+- [`src/session.ts`](src/session.ts)
+  - types: `NodeCapability`, `NodeActorSessionContext`, `ActorSessionContext`
+  - classes: `ActorSession`, `NodeActorSession`
+- [`src/node-runtime-client.ts`](src/node-runtime-client.ts)
+  - types: `HttpRuntimeClientOptions`, `NodeHttpClientOptions`
+  - classes: `HttpRuntimeClient`, `NodeHttpClient`
+- [`src/gdc-session-bridge.ts`](src/gdc-session-bridge.ts)
+  - functions: `createNodeActorSessionsFromFacades(...)`, `createNodeActorSessionFromFacade(...)`, `createNodeActorSessionsFromDescriptor(...)`, `createNodeActorSessionFromDescriptor(...)`, `createActorSessionsFromFacades(...)`, `createActorSessionFromFacade(...)`, `createActorSessionsFromDescriptor(...)`, `createActorSessionFromDescriptor(...)`
+- [`src/orchestration/client-port.ts`](src/orchestration/client-port.ts)
+  - types: `RuntimeClient`, `NodeRuntimeClient`
+  - functions: `requireClientMethod(...)`, `submitAndPollWithMethods(...)`, `canClientSubmitAndPoll(...)`, `submitAndPollWithClient(...)`
+- [`src/orchestration/host-onboarding-sdk.ts`](src/orchestration/host-onboarding-sdk.ts)
+  - class: `HostOnboardingSdk`
+- [`src/orchestration/organization-controller-sdk.ts`](src/orchestration/organization-controller-sdk.ts)
+  - class: `OrganizationControllerSdk`
+- [`src/orchestration/organization-employee-sdk.ts`](src/orchestration/organization-employee-sdk.ts)
+  - class: `OrganizationEmployeeSdk`
+- [`src/orchestration/individual-controller-sdk.ts`](src/orchestration/individual-controller-sdk.ts)
+  - class: `IndividualControllerSdk`
+- [`src/orchestration/individual-member-sdk.ts`](src/orchestration/individual-member-sdk.ts)
+  - class: `IndividualMemberSdk`
+- [`src/orchestration/personal-sdk.ts`](src/orchestration/personal-sdk.ts)
+  - class: `PersonalSdk`
+- [`src/orchestration/professional-sdk.ts`](src/orchestration/professional-sdk.ts)
+  - class: `ProfessionalSdk`
+- [`src/legacy-compat.ts`](src/legacy-compat.ts)
+  - compatibility aliases for simplified helpers, runtime classes, and legacy names such as `GdcNodeActorSession` and `GdcNodeHttpClient`
+
+### Re-exported shared helpers from `gdc-sdk-core-ts`
+
+- consent access helpers
+- relationship invitation/acceptance builders
+- communication/document builders
+- draft/outbox helpers
+- document facade helpers
+- vital-sign helpers
 
 ### Node runtime client
 
 - [`NodeHttpClient`](src/node-runtime-client.ts)
-  - Main runtime class for submit/poll orchestration against the GW.
 - [`NodeHttpClient.ingestCommunicationAndUpdateIndex(...)`](src/node-runtime-client.ts)
-  - Sends a `Communication` ingestion request and polls until indexed.
-  - Main params: `ctx`, `input.communicationPayload`, `input.pathFormatSegment?`, `input.autoConvertClaimsToFhirR4?`, `input.pollOptions?`.
 - [`NodeHttpClient.submitCommunicationAndPoll(...)`](src/node-runtime-client.ts)
-  - Alias of `ingestCommunicationAndUpdateIndex(...)`.
 - [`NodeHttpClient.searchClinicalBundle(...)`](src/node-runtime-client.ts)
-  - Executes clinical `Bundle/_search`.
-  - Main params: `ctx`, `input.subject`, `input.section?`, `input.date?`, `input.includedTypes?`, `input.code?`, `input.category?`, `input.author?`, `input.pollOptions?`.
 - [`NodeHttpClient.searchLatestIps(...)`](src/node-runtime-client.ts)
-  - Shortcut for latest IPS-oriented document search.
 - [`NodeHttpClient.grantProfessionalAccess(...)`](src/node-runtime-client.ts)
-  - Sends a consent-grant flow for a professional actor.
 - [`NodeHttpClient.requestSmartToken(...)`](src/node-runtime-client.ts)
-  - Requests SMART/OpenID token material through the GW.
-  - Main params: `input.actorDid`, `input.subjectDid`, `input.scopes`, `input.idToken`, optional `input.vpToken`, and optional route compatibility fields when the client was not initialized with a default `ctx`.
 
 ### Runtime configuration
 
 - [`NodeRuntimeConfig`](src/runtime-contracts.ts)
-  - Includes `interopMode?`, `persistencePolicy?`, and `outboxRepositoryFactory?` so node runtimes can declare `demo`/`compat`/`strict` mode and choose `memory` vs `server-remote` persistence explicitly.
-- [`initializeCommunicationIdentityFromSeed(...)`](src/identity-bootstrap.ts)
-  - Node SDK wrapper for the shared technical communication identity bootstrap helper from `gdc-common-utils-ts`.
+- [`initializeCommunicationIdentity(...)`](src/identity-bootstrap.ts)
 
 ### Low-level orchestration helpers
 
 - [`createOrganizationEmployeeWithDeps(...)`](src/resource-operations.ts)
-  - Creates an employee/person batch payload for CORE GW using canonical `org.schema.Person.*` claims.
 - [`importIpsOrFhirAndUpdateIndexWithDeps(...)`](src/resource-operations.ts)
 - [`upsertRelatedPersonAndPollWithDeps(...)`](src/resource-operations.ts)
-  - Creates or updates a `RelatedPerson` for family/caregiver roles outside employee/controller flows.
 - [`ingestCommunicationAndUpdateIndexWithDeps(...)`](src/resource-operations.ts)
 - [`searchClinicalBundleWithDeps(...)`](src/resource-operations.ts)
 - [`searchLatestIpsWithDeps(...)`](src/resource-operations.ts)
 - [`grantProfessionalAccessWithDeps(...)`](src/resource-operations.ts)
-  - Builds a consent grant where actor targeting should normally be passed as canonical `Consent.actor-identifier` input: a `did:web`, email, `tel:+...`, country code, or comma-separated list of those values.
-
-These functions are runtime-oriented building blocks. For application-level document handling, prefer the re-exported communication/document helpers from `gdc-sdk-core-ts`.
 
-### Documentation rule
+## Documentation Rule
 
-- JSDoc on exported code is canonical.
-- README entries should link to source and summarize the most important parameters.
-- If you add a public method/function, document it in JSDoc first and then add it here.
-- If a public payload shape is used in tests or docs, keep its reusable example in the relevant module under [`../gdc-common-utils-ts/src/examples/`](../gdc-common-utils-ts/src/examples/) and link that specific flow file from the relevant markdown section.
+- 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.

package/dist/gdc-session-bridge.d.ts

@@ -1,4 +1,4 @@
-import { type ActorKind, type ActorFacadeDescriptor, type ActorSessionDescriptor } from '../../gdc-sdk-core-ts/dist/index.js';
+import { type ActorKind, type ActorFacadeDescriptor, type ActorSessionDescriptor } from 'gdc-sdk-core-ts';
 import { ActorSession, NodeActorSession } from './session.js';
 import type { RuntimeClient } from './orchestration/client-port.js';
 export declare function createNodeActorSessionsFromFacades(facades: ActorFacadeDescriptor[], client?: RuntimeClient): NodeActorSession[];

package/dist/gdc-session-bridge.js

@@ -1,5 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-import { expandActorSessionDescriptorToFacades, filterCapabilitiesForActor, } from '../../gdc-sdk-core-ts/dist/index.js';
+import { expandActorSessionDescriptorToFacades, filterCapabilitiesForActor, } from 'gdc-sdk-core-ts';
 import { ActorSession, NodeActorSession } from './session.js';
 const capabilityMap = {
     'organization.create_employee': 'organization.create_employee',

package/dist/identity-bootstrap.d.ts

@@ -26,5 +26,9 @@ import { type CommunicationIdentityBootstrapOptions, type CommunicationIdentityB
  * @param options Stable seed/bootstrap options. See the shared
  * `CommunicationIdentityBootstrapOptions` JSDoc in `gdc-common-utils-ts`.
  */
-export declare function initializeCommunicationIdentityFromSeed(options: CommunicationIdentityBootstrapOptions): Promise<CommunicationIdentityBootstrapResult>;
+export declare function initializeCommunicationIdentity(options: CommunicationIdentityBootstrapOptions): Promise<CommunicationIdentityBootstrapResult>;
+/**
+ * @deprecated Use `initializeCommunicationIdentity(...)`.
+ */
+export declare const initializeCommunicationIdentityFromSeed: typeof initializeCommunicationIdentity;
 export type { CommunicationIdentityBootstrapOptions as NodeSdkCommunicationIdentityBootstrapOptions, CommunicationIdentityBootstrapResult as NodeSdkCommunicationIdentityBootstrapResult, } from 'gdc-common-utils-ts/utils/communication-identity';

package/dist/identity-bootstrap.js

@@ -1,5 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-import { initializeCommunicationIdentityFromSeed as initializeSharedCommunicationIdentityFromSeed, } from 'gdc-common-utils-ts/utils/communication-identity';
+import { initializeCommunicationIdentityFromSeed as initializeSharedCommunicationIdentity, } from 'gdc-common-utils-ts/utils/communication-identity';
 /**
  * Node SDK convenience wrapper for the shared technical communication identity
  * bootstrap helper defined in `gdc-common-utils-ts`.
@@ -27,6 +27,10 @@ import { initializeCommunicationIdentityFromSeed as initializeSharedCommunicatio
  * @param options Stable seed/bootstrap options. See the shared
  * `CommunicationIdentityBootstrapOptions` JSDoc in `gdc-common-utils-ts`.
  */
-export async function initializeCommunicationIdentityFromSeed(options) {
-    return initializeSharedCommunicationIdentityFromSeed(options);
+export async function initializeCommunicationIdentity(options) {
+    return initializeSharedCommunicationIdentity(options);
 }
+/**
+ * @deprecated Use `initializeCommunicationIdentity(...)`.
+ */
+export const initializeCommunicationIdentityFromSeed = initializeCommunicationIdentity;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export * from '../../gdc-sdk-core-ts/dist/index.js';
+export * from 'gdc-sdk-core-ts';
 export * from './runtime-contracts.js';
 export * from './identity-bootstrap.js';
 export * from './async-polling.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-export * from '../../gdc-sdk-core-ts/dist/index.js';
+export * from 'gdc-sdk-core-ts';
 export * from './runtime-contracts.js';
 export * from './identity-bootstrap.js';
 export * from './async-polling.js';

package/dist/lifecycle-examples.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Re-export canonical lifecycle examples for Node runtime consumers.
+ *
+ * The Node SDK must not hardcode its own copies of lifecycle payload examples.
+ * Import and reuse the shared `gdc-common-utils-ts` source instead.
+ */
+export * from 'gdc-common-utils-ts/examples/lifecycle';

package/dist/lifecycle-examples.js

@@ -0,0 +1,8 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Re-export canonical lifecycle examples for Node runtime consumers.
+ *
+ * The Node SDK must not hardcode its own copies of lifecycle payload examples.
+ * Import and reuse the shared `gdc-common-utils-ts` source instead.
+ */
+export * from 'gdc-common-utils-ts/examples/lifecycle';

package/dist/node-runtime-client.d.ts

@@ -1,4 +1,6 @@
 import type { ControllerBindingInput } from 'gdc-common-utils-ts/models';
+import type { AppInfo } from 'gdc-sdk-core-ts';
+import { type ResolvedAppInfo } from 'gdc-sdk-core-ts';
 import { type HostRouteContext } from './host-onboarding.js';
 import { type IndividualOrganizationConfirmOrderInput, type RouteContext } from './individual-onboarding.js';
 import { type SmartTokenRequestInput } from './smart-token.js';
@@ -10,6 +12,14 @@ import type { NodeRuntimeClient, PollOptions, PollResult, SubmitAndPollResult, S
 export type HttpRuntimeClientOptions = {
     baseUrl: string;
     bearerToken?: string;
+    /**
+     * Host app identity required by GW CORE.
+     *
+     * `appId` is mandatory when you want the SDK to inject canonical `AppId` and
+     * `AppVersion` headers automatically. `appVersion` is optional and defaults
+     * to `v1.0`.
+     */
+    appInfo?: AppInfo;
     /**
      * Optional default tenant route context reused by methods such as
      * `requestSmartToken(...)` when callers do not want to repeat
@@ -34,6 +44,7 @@ export type NodeHttpClientOptions = HttpRuntimeClientOptions;
 export declare class HttpRuntimeClient implements NodeRuntimeClient {
     private readonly baseUrl;
     private readonly bearerToken?;
+    private readonly resolvedAppInfo?;
     private readonly ctx?;
     private readonly defaultHeaders;
     private readonly requestTimeoutMs;
@@ -43,11 +54,21 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * @param options.baseUrl Gateway base URL without trailing slash.
      * @param options.interopMode Optional runtime interoperability mode from the SDK config layer (`demo`, `compat`, `strict`).
      * @param options.bearerToken Optional bearer token reused for direct HTTP calls.
+     * @param options.appInfo Optional GW CORE app identity. When present, the
+     * client injects `AppId` and `AppVersion` into all outgoing requests.
      * @param options.ctx Optional default route context.
      * @param options.defaultHeaders Optional static headers appended to every request.
      * @param options.requestTimeoutMs Optional per-request timeout in milliseconds.
      */
     constructor(options: HttpRuntimeClientOptions);
+    /**
+     * Returns the canonical GW CORE app identity resolved by the Node client.
+     */
+    getResolvedAppInfo(): ResolvedAppInfo | undefined;
+    /**
+     * Returns the standard GW CORE headers currently injected by the Node client.
+     */
+    getAppHeaders(): Record<'AppId' | 'AppVersion', string> | undefined;
     /**
      * Builds a canonical GDC v1 resource/action path from a route context.
      */

package/dist/node-runtime-client.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import fs from 'node:fs';
 import path from 'node:path';
+import { buildAppHeaders, resolveAppInfo, } from 'gdc-sdk-core-ts';
 import { buildConsentClaimsSimpleWithCid } from 'gdc-common-utils-ts/utils/consent';
 import { pollUntilCompleteWithMethod } from './async-polling.js';
 import { confirmLegalOrganizationOrderWithDeps } from './host-onboarding.js';
@@ -22,6 +23,8 @@ export class HttpRuntimeClient {
      * @param options.baseUrl Gateway base URL without trailing slash.
      * @param options.interopMode Optional runtime interoperability mode from the SDK config layer (`demo`, `compat`, `strict`).
      * @param options.bearerToken Optional bearer token reused for direct HTTP calls.
+     * @param options.appInfo Optional GW CORE app identity. When present, the
+     * client injects `AppId` and `AppVersion` into all outgoing requests.
      * @param options.ctx Optional default route context.
      * @param options.defaultHeaders Optional static headers appended to every request.
      * @param options.requestTimeoutMs Optional per-request timeout in milliseconds.
@@ -30,11 +33,29 @@ export class HttpRuntimeClient {
         this.tokenCache = new Map();
         this.baseUrl = String(options.baseUrl || '').replace(/\/+$/, '');
         this.bearerToken = String(options.bearerToken || '').trim() || undefined;
+        this.resolvedAppInfo = options.appInfo ? resolveAppInfo(options.appInfo) : undefined;
         this.ctx = options.ctx;
-        this.defaultHeaders = options.defaultHeaders || {};
+        this.defaultHeaders = {
+            ...(this.resolvedAppInfo ? buildAppHeaders(this.resolvedAppInfo) : {}),
+            ...(options.defaultHeaders || {}),
+        };
         this.requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? 15000));
         this.httpTraceFile = String(process.env.SDK_HTTP_TRACE_FILE || '').trim() || undefined;
     }
+    /**
+     * Returns the canonical GW CORE app identity resolved by the Node client.
+     */
+    getResolvedAppInfo() {
+        return this.resolvedAppInfo ? { ...this.resolvedAppInfo } : undefined;
+    }
+    /**
+     * Returns the standard GW CORE headers currently injected by the Node client.
+     */
+    getAppHeaders() {
+        if (!this.resolvedAppInfo)
+            return undefined;
+        return buildAppHeaders(this.resolvedAppInfo);
+    }
     /**
      * Builds a canonical GDC v1 resource/action path from a route context.
      */

package/dist/orchestration/client-port.d.ts

@@ -1,6 +1,6 @@
 import type { ControllerBindingInput } from 'gdc-common-utils-ts/models';
-import type { AsyncPollRequest, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse } from '../../../gdc-sdk-core-ts/dist/index.js';
-export type { AsyncPollRequest, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse, } from '../../../gdc-sdk-core-ts/dist/index.js';
+import type { AsyncPollRequest, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse } from 'gdc-sdk-core-ts';
+export type { AsyncPollRequest, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse, } from 'gdc-sdk-core-ts';
 import type { EmployeeDeviceActivationResult, EmployeeDeviceActivationRequestInput } from '../device-activation.js';
 import type { HostRouteContext, LegalOrganizationOrderInput } from '../host-onboarding.js';
 import type { IndividualOrganizationConfirmOrderInput, RouteContext } from '../individual-onboarding.js';

package/dist/orchestration/individual-member-sdk.d.ts

@@ -8,7 +8,7 @@ export declare class IndividualMemberSdk {
     /**
      * Creates or updates the member/caregiver `RelatedPerson` relationship to the subject.
      */
-    upsertRelatedPersonAndPoll(ctx: RouteContext, input: RelatedPersonUpsertInput): Promise<import("./client-port.js").SubmitAndPollResult>;
+    upsertRelatedPersonAndPoll(ctx: RouteContext, input: RelatedPersonUpsertInput): Promise<import("gdc-sdk-core-ts/dist/polling-model.js").SubmitAndPollResult>;
     /**
      * Requests a SMART token for a non-employee actor such as a `RelatedPerson`
      * caregiver, guardian, or family member.

package/dist/poll-options.d.ts

@@ -1 +1 @@
-export { resolvePollOptionsFromSeconds } from '../../gdc-sdk-core-ts/dist/index.js';
+export { resolvePollOptionsFromSeconds } from 'gdc-sdk-core-ts';

package/dist/poll-options.js

@@ -1,2 +1,2 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
-export { resolvePollOptionsFromSeconds } from '../../gdc-sdk-core-ts/dist/index.js';
+export { resolvePollOptionsFromSeconds } from 'gdc-sdk-core-ts';

package/dist/resource-operations.d.ts

@@ -1,4 +1,4 @@
-import type { BundleSearchQuery, CommunicationInput, DateRange } from '../../gdc-sdk-core-ts/dist/index.js';
+import type { BundleSearchQuery, CommunicationInput, DateRange } from 'gdc-sdk-core-ts';
 import type { SubmitAndPollResult } from './orchestration/client-port.js';
 import type { RouteContext } from './individual-onboarding.js';
 export type OrganizationEmployeeCreationInput = {

package/dist/runtime-contracts.d.ts

@@ -1,5 +1,5 @@
 import type { NodeOperatorNetworkType } from 'gdc-common-utils-ts/constants/network';
-import type { DataPersistencePolicy } from '../../gdc-sdk-core-ts/dist/index.js';
+import type { DataPersistencePolicy } from 'gdc-sdk-core-ts';
 export type LegacyNodeSourcePackage = never;
 /**
  * Deployment/runtime form factor of the Node SDK host process itself.

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-import type { ActorKind, Capability } from '../../gdc-sdk-core-ts/dist/index.js';
+import type { ActorKind, Capability } from 'gdc-sdk-core-ts';
 import { HostOnboardingSdk } from './orchestration/host-onboarding-sdk.js';
 import { IndividualControllerSdk } from './orchestration/individual-controller-sdk.js';
 import { IndividualMemberSdk } from './orchestration/individual-member-sdk.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -17,7 +17,8 @@
     "test:e2e:live-gw": "npm run build && RUN_LIVE_GW_E2E=1 node --test tests/live-gw-node-runtime.e2e.test.mjs"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "^1.5.1"
+    "gdc-common-utils-ts": "^1.6.0",
+    "gdc-sdk-core-ts": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",