gdc-sdk-node-ts 2.0.10 → 2.0.11

package/README.md

@@ -63,50 +63,42 @@ 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.
 2. [docs/101-SDK_INTEGRATION.md](./docs/101-SDK_INTEGRATION.md)
-   Real backend setup, imports, `initializeCommunicationIdentity(...)`,
-   `new NodeHttpClient(...)`, route context, facade selection, and live method
-   usage.
-3. [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
+   Real backend setup plus the public runtime entrypoints:
+   `HostOnboardingSdk`, `OrganizationControllerSdk`,
+   `IndividualControllerSdk`, `ProfessionalSdk`, and route-context usage.
+3. [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.
+4. [docs/101-LIVE_GW_LOCAL.md](./docs/101-LIVE_GW_LOCAL.md)
    Exact TTY/local/Docker commands for running the SDK against a real local GW
    CORE, including tenant bootstrap and employee-seat setup.
-4. [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
+5. [docs/101-DISCOVERY.md](./docs/101-DISCOVERY.md)
    Node/BFF dataspace discovery, hosting-operator resolution, provider
    resolution, and the correct integration boundary for fallback and cache.
-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)
+6. [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. [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)
+7. [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)
+8. [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.
-8. [gdc-common-utils-ts/docs/101-LIFECYCLE.md](https://github.com/Global-DataCare/gdc-common-utils-ts/blob/main/docs/101-LIFECYCLE.md)
+9. [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)
+10. [tests/101-backend-profile-runtime.test.mjs](./tests/101-backend-profile-runtime.test.mjs)
+   Technical runtime slice for profile/device/session orchestration internals.
+   Read this after the public actor SDK guides, not before them.
+11. [tests/101-individual-controller-backend-runtime.test.mjs](./tests/101-individual-controller-backend-runtime.test.mjs)
+   Technical wrapper slice around the generic profile runtime. This is not the
+   main onboarding path for new integrators.
+12. [docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md](./docs/V2_INDIVIDUAL_REGISTRATION_RECONCILIATION.md)
+   Historical reconciliation note for the current CORE registration baseline.
+13. [docs/NEXT_STEPS.md](./docs/NEXT_STEPS.md)
    Follow-up scope after GW CORE live validation, including the future user job
    manager boundary.
 
@@ -114,6 +106,9 @@ If you need the shortest path:
 
 - main onboarding guide:
   [docs/101-SDK_END_TO_END.md](./docs/101-SDK_END_TO_END.md)
+- first public actor surfaces:
+  `HostOnboardingSdk`, `OrganizationControllerSdk`,
+  `IndividualControllerSdk`, `ProfessionalSdk`
 - GW CORE app identity:
   `appId` mandatory, `appVersion` optional with default `v1.0`
 - backend technical identity:
@@ -130,7 +125,7 @@ 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:
+- the standalone actor-profile suites still exist only 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:

package/dist/individual-onboarding.js

@@ -1,6 +1,13 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { resolvePollOptionsFromSeconds } from './poll-options.js';
 export async function confirmIndividualOrganizationOrderWithDeps(deps) {
+    /**
+     * Programming rule:
+     * - `offerId` here must come from the commercial individual/family bootstrap
+     *   response
+     * - this helper must not be used for embedded legacy individual registration
+     *   responses that do not mint an Offer
+     */
     const offerId = String(deps.input.offerId || '').trim();
     if (!offerId) {
         throw new Error('confirmIndividualOrganizationOrder requires offerId.');

package/dist/individual-start.js

@@ -64,6 +64,15 @@ export async function startIndividualOrganizationWithDeps(deps) {
     });
     const registration = await deps.submitAndPoll(deps.individualFamilyOrganizationBatchPath(deps.routeCtx), deps.individualFamilyOrganizationPollPath(deps.routeCtx), registrationPayload, pollOptions);
     deps.assertFirstDidcommEntrySuccess?.(registration, 'startIndividualOrganization.registration');
+    /**
+     * Commercial contract for this SDK path:
+     * - this helper targets the family/individual commercial bootstrap flow
+     * - the registration response must expose one Offer identifier
+     * - the caller must later confirm that Offer through `Order/_batch`
+     *
+     * This helper must therefore fail fast if the underlying GW route behaves
+     * like the embedded non-commercial individual registration flow instead.
+     */
     const offerId = deps.getOfferIdFromResponse(registration);
     if (!offerId) {
         throw new Error('startIndividualOrganization failed: missing offerId in registration response.');

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

@@ -125,6 +125,12 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * - `_transaction` is the new host onboarding step
      * - this runtime does not chain `_activate` after `_transaction`
      * - `_activate` remains available only for the older ICA `_verify` based flow
+     *
+     * Commercial contract:
+     * - the final poll response is expected to mint
+     *   `meta.claims['org.schema.Offer.identifier']`
+     * - callers should then pass that exact value to
+     *   `confirmLegalOrganizationOrder(...)`
      */
     submitLegalOrganizationVerificationTransaction(hostCtx: HostRouteContext, input: NodeLegalOrganizationVerificationTransactionInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     /**
@@ -135,6 +141,7 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * - reuse the same signed evidence/controller binding contract as `_transaction`
      * - do not create a new Offer
      * - expect GW CORE to reissue one controller activation code in the response
+     * - do not call `confirmLegalOrganizationOrder(...)` after this flow
      */
     submitLegalOrganizationIssue(hostCtx: HostRouteContext, input: NodeLegalOrganizationVerificationTransactionInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     /**
@@ -162,10 +169,19 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      *   headers instead of plaintext `meta`
      * - this mirrored metadata is transport fallback only; the canonical
      *   activation contract remains `body.vp_token` plus `body.controller.*`
+     *
+     * Commercial contract:
+     * - legacy `_activate` is still expected to mint
+     *   `meta.claims['org.schema.Offer.identifier']`
+     * - callers should then pass that exact value to
+     *   `confirmLegalOrganizationOrder(...)`
      */
     activateOrganizationInGatewayFromIcaProof(hostCtx: HostRouteContext, input: NodeOrganizationActivationInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     /**
      * Confirms a host-side legal organization order after the initial activation.
+     *
+     * Use this only when the previous flow actually returned one canonical Offer
+     * identifier. `_transaction` and legacy `_activate` do; `_issue` does not.
      */
     confirmLegalOrganizationOrder(hostCtx: HostRouteContext, input: LegalOrganizationOrderInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     /**
@@ -244,6 +260,15 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
     confirmOrganizationLicenseOrder(ctx: RouteContext, input: OrganizationLicenseOrderConfirmInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     /**
      * Starts the onboarding flow for an individual-oriented tenant or index.
+     *
+     * Commercial contract:
+     * - this SDK method targets the family/individual commercial bootstrap flow
+     * - the registration poll response is expected to return one Offer id
+     * - callers should then confirm it through
+     *   `confirmIndividualOrganizationOrder(...)`
+     *
+     * This is distinct from embedded legacy individual registration helpers in
+     * GW CORE that may persist an individual record without minting an Offer.
      */
     startIndividualOrganization(input: IndividualOrganizationBootstrapInput): Promise<IndividualOrganizationStartResult>;
     /**

package/dist/node-runtime-client.js

@@ -113,6 +113,12 @@ export class HttpRuntimeClient {
      * - `_transaction` is the new host onboarding step
      * - this runtime does not chain `_activate` after `_transaction`
      * - `_activate` remains available only for the older ICA `_verify` based flow
+     *
+     * Commercial contract:
+     * - the final poll response is expected to mint
+     *   `meta.claims['org.schema.Offer.identifier']`
+     * - callers should then pass that exact value to
+     *   `confirmLegalOrganizationOrder(...)`
      */
     async submitLegalOrganizationVerificationTransaction(hostCtx, input, pollOptions) {
         const thid = `organization-verification-transaction-${runtimeUuid()}`;
@@ -134,6 +140,7 @@ export class HttpRuntimeClient {
      * - reuse the same signed evidence/controller binding contract as `_transaction`
      * - do not create a new Offer
      * - expect GW CORE to reissue one controller activation code in the response
+     * - do not call `confirmLegalOrganizationOrder(...)` after this flow
      */
     async submitLegalOrganizationIssue(hostCtx, input, pollOptions) {
         const thid = `organization-issue-${runtimeUuid()}`;
@@ -182,6 +189,12 @@ export class HttpRuntimeClient {
      *   headers instead of plaintext `meta`
      * - this mirrored metadata is transport fallback only; the canonical
      *   activation contract remains `body.vp_token` plus `body.controller.*`
+     *
+     * Commercial contract:
+     * - legacy `_activate` is still expected to mint
+     *   `meta.claims['org.schema.Offer.identifier']`
+     * - callers should then pass that exact value to
+     *   `confirmLegalOrganizationOrder(...)`
      */
     async activateOrganizationInGatewayFromIcaProof(hostCtx, input, pollOptions) {
         const thid = `activate-org-${runtimeUuid()}`;
@@ -230,6 +243,9 @@ export class HttpRuntimeClient {
     }
     /**
      * Confirms a host-side legal organization order after the initial activation.
+     *
+     * Use this only when the previous flow actually returned one canonical Offer
+     * identifier. `_transaction` and legacy `_activate` do; `_issue` does not.
      */
     async confirmLegalOrganizationOrder(hostCtx, input, pollOptions) {
         return confirmLegalOrganizationOrderWithDeps({
@@ -440,6 +456,15 @@ export class HttpRuntimeClient {
     }
     /**
      * Starts the onboarding flow for an individual-oriented tenant or index.
+     *
+     * Commercial contract:
+     * - this SDK method targets the family/individual commercial bootstrap flow
+     * - the registration poll response is expected to return one Offer id
+     * - callers should then confirm it through
+     *   `confirmIndividualOrganizationOrder(...)`
+     *
+     * This is distinct from embedded legacy individual registration helpers in
+     * GW CORE that may persist an individual record without minting an Offer.
      */
     async startIndividualOrganization(input) {
         const routeCtx = this.routeCtxFromInput(input);

package/dist/orchestration/host-onboarding-sdk.d.ts

@@ -8,6 +8,12 @@ export declare class HostOnboardingSdk implements HostingControllerFacade {
     /**
      * Submits the legal organization activation proof and required declared
      * service capabilities to GW CORE.
+     *
+     * Commercial contract:
+     * - this legacy `_activate` facade must return one canonical Offer in
+     *   `meta.claims['org.schema.Offer.identifier']`
+     * - callers are expected to pass that Offer to
+     *   `confirmLegalOrganizationOrder(...)`
      */
     activateOrganizationInGatewayFromIcaProof(hostCtx: HostRouteContext, input: NodeOrganizationActivationInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
     confirmLegalOrganizationOrder(hostCtx: HostRouteContext, input: LegalOrganizationOrderInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;

package/dist/orchestration/host-onboarding-sdk.js

@@ -11,6 +11,12 @@ export class HostOnboardingSdk {
     /**
      * Submits the legal organization activation proof and required declared
      * service capabilities to GW CORE.
+     *
+     * Commercial contract:
+     * - this legacy `_activate` facade must return one canonical Offer in
+     *   `meta.claims['org.schema.Offer.identifier']`
+     * - callers are expected to pass that Offer to
+     *   `confirmLegalOrganizationOrder(...)`
      */
     activateOrganizationInGatewayFromIcaProof(hostCtx, input, pollOptions) {
         assertFacadeCapability(this.capabilities, ActorCapabilities.HostingActivateOrganization, ActorKinds.HostOnboarding, 'activateOrganizationInGatewayFromIcaProof');

package/dist/organization-controller-recovery.js

@@ -1,6 +1,12 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { activateEmployeeDeviceWithActivationCodeWithDeps } from './device-activation.js';
 export async function recoverOrganizationControllerWithIssueWithDeps(deps) {
+    /**
+     * Existing-tenant controller recovery contract:
+     * - `Organization/_issue` is expected to reissue controller activation
+     *   material only
+     * - this flow must not depend on a new commercial Offer or Order step
+     */
     const issue = await deps.submitLegalOrganizationIssue(deps.hostCtx, deps.input.issueInput, deps.input.issuePollOptions);
     const activationCode = readActivationCodeFromIssueResult(issue);
     if (!activationCode) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -35,8 +35,8 @@
     "test:e2e:live-gw:clean": "bash ./scripts/run-live-gw-clean.sh"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "^2.0.15",
-    "gdc-sdk-core-ts": "^2.0.9"
+    "gdc-common-utils-ts": "^2.0.17",
+    "gdc-sdk-core-ts": "^2.0.10"
   },
   "devDependencies": {
     "@types/node": "^20.14.10",