gdc-sdk-node-ts 0.1.1

package/dist/node-runtime-client.js

@@ -0,0 +1,483 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildConsentClaimsSimpleWithCid } from 'gdc-common-utils-ts/utils/consent';
+import { pollUntilCompleteWithMethod } from './async-polling.js';
+import { confirmLegalOrganizationOrderWithDeps } from './host-onboarding.js';
+import { confirmIndividualOrganizationOrderWithDeps, } from './individual-onboarding.js';
+import { requestSmartTokenWithDeps } from './smart-token.js';
+import { startIndividualOrganizationWithDeps } from './individual-start.js';
+import { createOrganizationEmployeeWithDeps, grantProfessionalAccessWithDeps, ingestCommunicationAndUpdateIndexWithDeps, searchClinicalBundleWithDeps, searchLatestIpsWithDeps, upsertRelatedPersonAndPollWithDeps, } from './resource-operations.js';
+import { submitAndPollWithMethods } from './orchestration/client-port.js';
+/**
+ * Runtime-oriented HTTP client for Node backends, BFFs, and workers that need
+ * to submit GDC gateway requests and poll asynchronous responses.
+ *
+ * This class is intentionally transport-focused. It does not try to be the
+ * high-level editor of FHIR documents; that role belongs to the shared helpers
+ * re-exported from `gdc-sdk-core-ts`.
+ */
+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.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) {
+        this.tokenCache = new Map();
+        this.baseUrl = String(options.baseUrl || '').replace(/\/+$/, '');
+        this.bearerToken = String(options.bearerToken || '').trim() || undefined;
+        this.ctx = options.ctx;
+        this.defaultHeaders = options.defaultHeaders || {};
+        this.requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? 15000));
+        this.httpTraceFile = String(process.env.SDK_HTTP_TRACE_FILE || '').trim() || undefined;
+    }
+    /**
+     * Builds a canonical GDC v1 resource/action path from a route context.
+     */
+    v1Path(ctx, section, format, resourceType, action) {
+        const routeCtx = this.requireRouteContext(ctx);
+        return `/${encodeURIComponent(routeCtx.tenantId)}/cds-${encodeURIComponent(routeCtx.jurisdiction)}/v1/${encodeURIComponent(routeCtx.sector)}/${encodeURIComponent(section)}/${encodeURIComponent(format)}/${encodeURIComponent(resourceType)}/${encodeURIComponent(action)}`;
+    }
+    /**
+     * Submits a batch payload to a gateway batch endpoint.
+     */
+    async submitBatch(path, payload) {
+        return this.postJson(path, payload, 'application/didcomm-plaintext+json');
+    }
+    /**
+     * Polls a batch-response endpoint until the GW reports a terminal state.
+     */
+    async pollUntilComplete(pollPath, request, pollOptions) {
+        return pollUntilCompleteWithMethod(this.pollBatchResponse.bind(this), pollPath, request, pollOptions);
+    }
+    /**
+     * Convenience wrapper that performs submit and poll in sequence.
+     */
+    async submitAndPoll(submitPath, pollPath, payload, pollOptions) {
+        return submitAndPollWithMethods(this, submitPath, pollPath, payload, pollOptions);
+    }
+    /**
+     * Activates a legal organization in the gateway host registry using an ICA
+     * proof token already obtained by the caller.
+     */
+    async activateOrganizationInGatewayFromIcaProof(hostCtx, input, pollOptions) {
+        const thid = `activate-org-${runtimeUuid()}`;
+        const payload = {
+            thid,
+            iss: String(hostCtx.controllerDid || '').trim() || undefined,
+            aud: String(hostCtx.hostDid || '').trim() || undefined,
+            type: 'application/api+json',
+            body: {
+                vp_token: input.vpToken,
+                ...(input.controller ? { controller: input.controller } : {}),
+                data: [{
+                        type: 'Organization-activation-request-v1.0',
+                        meta: {
+                            claims: {
+                                '@context': 'org.schema',
+                                ...(input.additionalClaims || {}),
+                            },
+                        },
+                        resource: {
+                            meta: {
+                                claims: {
+                                    '@context': 'org.schema',
+                                    ...(input.additionalClaims || {}),
+                                },
+                            },
+                        },
+                    }],
+            },
+        };
+        return this.submitAndPoll(this.hostRegistryOrganizationActivatePath(hostCtx), this.hostRegistryOrganizationActivatePollPath(hostCtx), payload, pollOptions);
+    }
+    /**
+     * Confirms a host-side legal organization order after the initial activation.
+     */
+    async confirmLegalOrganizationOrder(hostCtx, input, pollOptions) {
+        return confirmLegalOrganizationOrderWithDeps({
+            input,
+            hostCtx,
+            hostRegistryOrderBatchPath: this.hostRegistryOrderBatchPath.bind(this),
+            hostRegistryOrderPollPath: this.hostRegistryOrderPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+            defaultTimeoutMs: pollOptions?.timeoutMs,
+            defaultIntervalMs: pollOptions?.intervalMs,
+        });
+    }
+    /**
+     * Creates an employee or professional entry under an existing organization tenant.
+     */
+    async createOrganizationEmployee(ctx, input, pollOptions) {
+        return createOrganizationEmployeeWithDeps(ctx, input, pollOptions, {
+            employeeBatchPath: this.employeeBatchPath.bind(this),
+            employeePollPath: this.employeePollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+        });
+    }
+    /**
+     * Starts the onboarding flow for an individual-oriented tenant or index.
+     */
+    async startIndividualOrganization(input) {
+        const routeCtx = this.routeCtxFromInput(input);
+        return startIndividualOrganizationWithDeps({
+            input,
+            routeCtx,
+            individualFamilyOrganizationBatchPath: this.individualFamilyOrganizationBatchPath.bind(this),
+            individualFamilyOrganizationPollPath: this.individualFamilyOrganizationPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+            getOfferIdFromResponse: (result) => this.extractOfferId(result.poll.body),
+            getOfferPreviewFromResponse: () => ({}),
+        });
+    }
+    /**
+     * Confirms the order returned by `startIndividualOrganization(...)`.
+     */
+    async confirmIndividualOrganizationOrder(input) {
+        const routeCtx = this.routeCtxFromInput(input);
+        return confirmIndividualOrganizationOrderWithDeps({
+            input,
+            routeCtx,
+            individualFamilyOrderBatchPath: this.individualFamilyOrderBatchPath.bind(this),
+            individualFamilyOrderPollPath: this.individualFamilyOrderPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+        });
+    }
+    /**
+     * Creates and submits a consent-oriented access grant for a professional actor.
+     */
+    async grantProfessionalAccess(ctx, input) {
+        return grantProfessionalAccessWithDeps(ctx, input, {
+            buildConsentClaimsWithCid: this.buildConsentClaimsWithCid.bind(this),
+            individualConsentR4BatchPath: this.individualConsentR4BatchPath.bind(this),
+            individualConsentR4PollPath: this.individualConsentR4PollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+        });
+    }
+    /**
+     * Requests SMART/OpenID token material through the gateway.
+     *
+     * The business inputs are typically the actor DID plus requested scopes.
+     * Route details are resolved either from `input` compatibility fields
+     * (`tenantId` / `jurisdiction` / `sector`) or from
+     * the default client route context configured in the constructor.
+     */
+    async requestSmartToken(input) {
+        const routeCtx = this.routeCtxFromInput(input);
+        return requestSmartTokenWithDeps({
+            input,
+            routeCtx,
+            baseUrl: this.baseUrl,
+            defaultTimeoutMs: undefined,
+            defaultIntervalMs: undefined,
+            identityTokenExchangePath: this.identityTokenExchangePath.bind(this),
+            identityTokenExchangePollPath: this.identityTokenExchangePollPath.bind(this),
+            identityOpenIdSmartTokenPath: this.identityOpenIdSmartTokenPath.bind(this),
+            identityOpenIdSmartTokenPollPath: this.identityOpenIdSmartTokenPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+            setTokenCache: (tokenCacheKey, token) => this.tokenCache.set(tokenCacheKey, token),
+        });
+    }
+    /**
+     * Creates or updates a `RelatedPerson` for non-employee family/caregiver
+     * roles such as a grandfather, guardian, or external caregiver.
+     */
+    async upsertRelatedPersonAndPoll(ctx, input) {
+        return upsertRelatedPersonAndPollWithDeps(ctx, input, {
+            individualRelatedPersonBatchPath: this.individualRelatedPersonBatchPath.bind(this),
+            individualRelatedPersonPollPath: this.individualRelatedPersonPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+        });
+    }
+    /**
+     * Submits a FHIR `Communication` ingestion request and polls until the
+     * GW has persisted the audit record and related projections.
+     *
+     * @param ctx Route context containing tenant/jurisdiction/sector.
+     * @param input Communication payload plus route/format options.
+     */
+    async ingestCommunicationAndUpdateIndex(ctx, input) {
+        return ingestCommunicationAndUpdateIndexWithDeps(ctx, input, {
+            individualCommunicationBatchPath: this.individualCommunicationBatchPath.bind(this),
+            individualCommunicationPollPath: this.individualCommunicationPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+        });
+    }
+    /**
+     * Alias for `ingestCommunicationAndUpdateIndex(...)`.
+     *
+     * @param ctx Route context containing tenant/jurisdiction/sector.
+     * @param input Communication payload plus route/format options.
+     */
+    async submitCommunicationAndPoll(ctx, input) {
+        return this.ingestCommunicationAndUpdateIndex(ctx, input);
+    }
+    /**
+     * Executes a clinical `Bundle/_search` through the converged runtime.
+     *
+     * @param ctx Route context containing tenant/jurisdiction/sector.
+     * @param input Search parameters such as subject, section, date and included resource types.
+     */
+    async searchClinicalBundle(ctx, input) {
+        return searchClinicalBundleWithDeps(ctx, input, {
+            bundleSearchPath: this.individualBundleSearchPath.bind(this),
+            bundleSearchPollPath: this.individualBundleSearchPollPath.bind(this),
+            submitAndPoll: this.submitAndPoll.bind(this),
+        });
+    }
+    /**
+     * Searches the latest IPS-oriented document view for a subject.
+     *
+     * Defaults the section to the IPS patient summary document and includes
+     * `Composition` plus `DocumentReference`.
+     *
+     * @param ctx Route context containing tenant/jurisdiction/sector.
+     * @param input Subject-scoped search parameters.
+     */
+    async searchLatestIps(ctx, input) {
+        return searchLatestIpsWithDeps(ctx, input, {
+            searchClinicalBundle: this.searchClinicalBundle.bind(this),
+        });
+    }
+    /**
+     * Searches a communication/document thread using `thid` and returns the
+     * indexed communication/document projections.
+     */
+    async listCommunicationThread(ctx, input) {
+        return this.searchClinicalBundle(ctx, {
+            subject: input.subject,
+            thid: input.thid,
+            includedTypes: ['Communication', 'DocumentReference', 'Composition'],
+            pollOptions: input.pollOptions,
+        });
+    }
+    buildConsentClaimsWithCid(input) {
+        return buildConsentClaimsSimpleWithCid({
+            subjectDid: input.subjectDid,
+            subjectPhone: input.subjectPhone,
+            subjectGivenName: input.subjectGivenName,
+            actor: input.actorId ?? input.actor ?? '',
+            actorRole: String(input?.actorRole || ''),
+            purpose: String(input?.purpose || ''),
+            actions: Array.isArray(input?.actions) ? input.actions : [],
+            consentIdentifier: input.consentIdentifier,
+            consentDate: input.consentDate,
+            decision: input.decision,
+            attachmentContentType: input.attachmentContentType,
+            attachmentBase64: input.attachmentBase64,
+        }, {
+            errorPrefix: 'grantProfessionalAccess:',
+            consentIdentifierFactory: () => `urn:uuid:${runtimeUuid()}`,
+        });
+    }
+    async pollBatchResponse(path, request) {
+        const response = await this.fetchWithTimeout(path, {
+            method: 'POST',
+            headers: this.buildHeaders('application/json'),
+            body: JSON.stringify(request),
+        });
+        const retryAfter = Number(response.headers.get('retry-after'));
+        return {
+            status: response.status,
+            body: await this.parseResponseBody(response),
+            retryAfterMs: Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined,
+        };
+    }
+    async postJson(path, payload, contentType) {
+        const response = await this.fetchWithTimeout(path, {
+            method: 'POST',
+            headers: this.buildHeaders(contentType),
+            body: JSON.stringify(payload),
+        });
+        return { status: response.status, location: response.headers.get('location') || undefined, body: await this.parseResponseBody(response) };
+    }
+    buildHeaders(contentType) {
+        const headers = {
+            ...this.defaultHeaders,
+            'Content-Type': contentType,
+            Accept: 'application/json, application/didcomm-plaintext+json, */*',
+        };
+        if (this.bearerToken)
+            headers.Authorization = `Bearer ${this.bearerToken}`;
+        return headers;
+    }
+    async fetchWithTimeout(path, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        const url = /^https?:\/\//.test(path) ? path : `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+        const requestBody = this.parseTraceBody(init.body);
+        const traceBase = {
+            ts: new Date().toISOString(),
+            request: {
+                url,
+                method: String(init.method || 'GET').toUpperCase(),
+                headers: this.redactTraceValue(init.headers || {}),
+                body: this.redactTraceValue(requestBody),
+            },
+        };
+        try {
+            const response = await fetch(url, { ...init, signal: controller.signal });
+            const responseClone = response.clone();
+            const responseRaw = await responseClone.text();
+            this.appendHttpTrace({
+                ...traceBase,
+                response: {
+                    status: response.status,
+                    headers: this.redactTraceValue(Object.fromEntries(response.headers.entries())),
+                    body: this.redactTraceValue(this.parseTraceRawText(responseRaw)),
+                },
+            });
+            return response;
+        }
+        catch (error) {
+            this.appendHttpTrace({
+                ...traceBase,
+                error: {
+                    name: error instanceof Error ? error.name : 'Error',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            });
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async parseResponseBody(response) {
+        const raw = await response.text();
+        if (!raw)
+            return {};
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    requireRouteContext(ctx) {
+        const resolved = ctx || this.ctx;
+        const tenantId = String(resolved?.tenantId || '').trim();
+        const jurisdiction = String(resolved?.jurisdiction || '').trim();
+        const sector = String(resolved?.sector || '').trim();
+        if (!tenantId || !jurisdiction || !sector) {
+            throw new Error('Route context is required.');
+        }
+        return { tenantId, jurisdiction, sector };
+    }
+    routeCtxFromInput(input) {
+        const tenantId = String(input.serviceProviderDid || input.tenantId || '').trim();
+        return this.requireRouteContext(tenantId && input.jurisdiction && input.sector
+            ? { tenantId, jurisdiction: input.jurisdiction, sector: input.sector }
+            : undefined);
+    }
+    hostRegistryPath(ctx, resourceType, action) {
+        const hostCtx = this.requireHostRouteContext(ctx);
+        return `/host/cds-${encodeURIComponent(hostCtx.jurisdiction)}/v1/${encodeURIComponent(hostCtx.sector)}/registry/org.schema/${encodeURIComponent(resourceType)}/${encodeURIComponent(action)}`;
+    }
+    requireHostRouteContext(ctx) {
+        const jurisdiction = String(ctx?.jurisdiction || this.ctx?.jurisdiction || '').trim();
+        const sector = String(ctx?.sector || this.ctx?.sector || '').trim();
+        if (!jurisdiction || !sector)
+            throw new Error('Host route context is required.');
+        return { jurisdiction, sector };
+    }
+    hostRegistryOrganizationActivatePath(ctx) { return this.hostRegistryPath(ctx, 'Organization', '_activate'); }
+    hostRegistryOrganizationActivatePollPath(ctx) { return this.hostRegistryPath(ctx, 'Organization', '_activate-response'); }
+    hostRegistryOrderBatchPath(ctx) { return this.hostRegistryPath(ctx, 'Order', '_batch'); }
+    hostRegistryOrderPollPath(ctx) { return this.hostRegistryPath(ctx, 'Order', '_batch-response'); }
+    employeeBatchPath(ctx) { return this.v1Path(ctx, 'entity', 'org.schema', 'Employee', '_batch'); }
+    employeePollPath(ctx) { return this.v1Path(ctx, 'entity', 'org.schema', 'Employee', '_batch-response'); }
+    individualFamilyOrganizationBatchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Organization', '_batch'); }
+    individualFamilyOrganizationPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Organization', '_batch-response'); }
+    individualFamilyOrderBatchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Order', '_batch'); }
+    individualFamilyOrderPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.schema', 'Order', '_batch-response'); }
+    individualRelatedPersonBatchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'RelatedPerson', '_batch'); }
+    individualRelatedPersonPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'RelatedPerson', '_batch-response'); }
+    individualConsentR4BatchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'Consent', '_batch'); }
+    individualConsentR4PollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'Consent', '_batch-response'); }
+    individualCommunicationBatchPath(ctx, format) { return this.v1Path(ctx, 'individual', format, 'Communication', '_batch'); }
+    individualCommunicationPollPath(ctx, format) { return this.v1Path(ctx, 'individual', format, 'Communication', '_batch-response'); }
+    individualBundleSearchPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'Bundle', '_search'); }
+    individualBundleSearchPollPath(ctx) { return this.v1Path(ctx, 'individual', 'org.hl7.fhir.r4', 'Bundle', '_search-response'); }
+    identityTokenExchangePath(ctx) {
+        return `/${encodeURIComponent('host')}/cds-${encodeURIComponent(ctx.jurisdiction)}/v1/${encodeURIComponent(ctx.sector)}/${encodeURIComponent(ctx.tenantId)}/identity/auth/_exchange`;
+    }
+    identityTokenExchangePollPath(ctx) {
+        return `/${encodeURIComponent('host')}/cds-${encodeURIComponent(ctx.jurisdiction)}/v1/${encodeURIComponent(ctx.sector)}/${encodeURIComponent(ctx.tenantId)}/identity/auth/_exchange-response`;
+    }
+    identityOpenIdSmartTokenPath(ctx) {
+        return `/${encodeURIComponent(ctx.tenantId)}/cds-${encodeURIComponent(ctx.jurisdiction)}/v1/${encodeURIComponent(ctx.sector)}/identity/openid/smart/token`;
+    }
+    identityOpenIdSmartTokenPollPath(ctx) {
+        return `/${encodeURIComponent(ctx.tenantId)}/cds-${encodeURIComponent(ctx.jurisdiction)}/v1/${encodeURIComponent(ctx.sector)}/identity/openid/smart/_batch-response`;
+    }
+    extractOfferId(body) {
+        const root = body || {};
+        const bodyNode = root.body || root;
+        const data = bodyNode.data || [];
+        const first = data[0] || {};
+        const firstMeta = first.meta || {};
+        const resource = first.resource || {};
+        const resourceMeta = resource.meta || {};
+        const claims = firstMeta.claims
+            || resourceMeta.claims
+            || {};
+        return String(claims['org.schema.Offer.identifier'] || '').trim() || undefined;
+    }
+    appendHttpTrace(entry) {
+        if (!this.httpTraceFile)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.httpTraceFile), { recursive: true });
+            fs.appendFileSync(this.httpTraceFile, `${JSON.stringify(entry)}\n`);
+        }
+        catch {
+            // Tracing must never break runtime requests.
+        }
+    }
+    parseTraceBody(body) {
+        if (body == null)
+            return undefined;
+        if (typeof body === 'string')
+            return this.parseTraceRawText(body);
+        if (body instanceof URLSearchParams)
+            return Object.fromEntries(body.entries());
+        return '[non-text-body]';
+    }
+    parseTraceRawText(raw) {
+        if (!raw)
+            return '';
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
+    redactTraceValue(value) {
+        if (value === undefined)
+            return value;
+        const serialized = JSON.stringify(value, (key, nestedValue) => {
+            if (/token|authorization|secret|password/i.test(String(key || ''))) {
+                return '[redacted]';
+            }
+            return nestedValue;
+        });
+        return serialized === undefined ? value : JSON.parse(serialized);
+    }
+}
+/**
+ * @deprecated Prefer `HttpRuntimeClient`.
+ */
+export class NodeHttpClient extends HttpRuntimeClient {
+}
+function runtimeUuid() {
+    const fromCrypto = globalThis.crypto?.randomUUID?.();
+    if (fromCrypto)
+        return fromCrypto;
+    return `fallback-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}

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

@@ -0,0 +1,47 @@
+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 { EmployeeDeviceActivationResult, EmployeeDeviceActivationRequestInput } from '../device-activation.js';
+import type { HostRouteContext, LegalOrganizationOrderInput } from '../host-onboarding.js';
+import type { IndividualOrganizationConfirmOrderInput, RouteContext } from '../individual-onboarding.js';
+import type { IndividualOrganizationBootstrapInput, IndividualOrganizationStartResult } from '../individual-start.js';
+import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-token.js';
+import type { CommunicationIngestionInput, ClinicalBundleSearchInput, DigitalTwinGenerationInput, GrantProfessionalAccessInput, GrantProfessionalAccessResult, IpsOrFhirImportInput, OrganizationEmployeeCreationInput, RelatedPersonUpsertInput } from '../resource-operations.js';
+/**
+ * Runtime-neutral actor/application client contract as exposed by the Node SDK.
+ *
+ * New code should prefer `RuntimeClient`.
+ * `NodeRuntimeClient` is kept as a compatibility alias while package surfaces
+ * converge across runtimes.
+ */
+export type RuntimeClient = {
+    activateOrganizationInGatewayFromIcaProof?: (hostCtx: HostRouteContext, input: {
+        vpToken: string;
+        controller?: ControllerBindingInput;
+        additionalClaims?: Record<string, unknown>;
+    }, pollOptions?: PollOptions) => Promise<SubmitAndPollResult>;
+    confirmLegalOrganizationOrder?: (hostCtx: HostRouteContext, input: LegalOrganizationOrderInput, pollOptions?: PollOptions) => Promise<SubmitAndPollResult>;
+    createOrganizationEmployee?: (ctx: RouteContext, input: OrganizationEmployeeCreationInput, pollOptions?: PollOptions) => Promise<SubmitAndPollResult>;
+    activateEmployeeDeviceWithActivationRequest?: (input: EmployeeDeviceActivationRequestInput) => Promise<EmployeeDeviceActivationResult>;
+    requestSmartToken?: (input: SmartTokenRequestInput) => Promise<SmartTokenExchangeResult>;
+    startIndividualOrganization?: (input: IndividualOrganizationBootstrapInput) => Promise<IndividualOrganizationStartResult>;
+    confirmIndividualOrganizationOrder?: (input: IndividualOrganizationConfirmOrderInput) => Promise<SubmitAndPollResult>;
+    ingestCommunicationAndUpdateIndex?: (ctx: RouteContext, input: CommunicationIngestionInput) => Promise<SubmitAndPollResult>;
+    grantProfessionalAccess?: (ctx: RouteContext, input: GrantProfessionalAccessInput) => Promise<GrantProfessionalAccessResult>;
+    bootstrapIndividualOrganization?: (input: IndividualOrganizationBootstrapInput) => Promise<IndividualOrganizationStartResult>;
+    importIpsOrFhirAndUpdateIndex?: (ctx: RouteContext, input: IpsOrFhirImportInput) => Promise<SubmitAndPollResult>;
+    upsertRelatedPersonAndPoll?: (ctx: RouteContext, input: RelatedPersonUpsertInput) => Promise<SubmitAndPollResult>;
+    generateDigitalTwinFromSubjectData?: (ctx: RouteContext, input: DigitalTwinGenerationInput) => Promise<SubmitAndPollResult>;
+    searchClinicalBundle?: (ctx: RouteContext, input: ClinicalBundleSearchInput) => Promise<SubmitAndPollResult>;
+    submitBatch?: (submitPath: string, payload: SubmitPayload) => Promise<SubmitResponse>;
+    pollUntilComplete?: (pollPath: string, request: AsyncPollRequest, pollOptions?: PollOptions) => Promise<PollResult>;
+    submitAndPoll?: (submitPath: string, pollPath: string, payload: SubmitPayload, pollOptions?: PollOptions) => Promise<SubmitAndPollResult>;
+};
+/**
+ * @deprecated Prefer `RuntimeClient`.
+ */
+export type NodeRuntimeClient = RuntimeClient;
+export declare function requireClientMethod<T extends keyof RuntimeClient>(client: RuntimeClient, method: T): NonNullable<RuntimeClient[T]>;
+export declare function submitAndPollWithMethods(methods: Pick<RuntimeClient, 'submitBatch' | 'pollUntilComplete'>, submitPath: string, pollPath: string, payload: SubmitPayload, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+export declare function canClientSubmitAndPoll(client: NodeRuntimeClient): boolean;
+export declare function submitAndPollWithClient(client: RuntimeClient, submitPath: string, pollPath: string, payload: SubmitPayload, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;

package/dist/orchestration/client-port.js

@@ -0,0 +1,31 @@
+export function requireClientMethod(client, method) {
+    const candidate = client[method];
+    if (typeof candidate !== 'function') {
+        throw new Error(`RuntimeClient does not implement '${String(method)}'.`);
+    }
+    return candidate.bind(client);
+}
+export async function submitAndPollWithMethods(methods, submitPath, pollPath, payload, pollOptions) {
+    const thid = requireSubmitPayloadThid(payload);
+    const submit = await requireClientMethod(methods, 'submitBatch')(submitPath, payload);
+    const poll = await requireClientMethod(methods, 'pollUntilComplete')(pollPath, { thid }, pollOptions);
+    return { submit, poll };
+}
+export function canClientSubmitAndPoll(client) {
+    return typeof client.submitAndPoll === 'function';
+}
+export async function submitAndPollWithClient(client, submitPath, pollPath, payload, pollOptions) {
+    const thid = requireSubmitPayloadThid(payload);
+    const normalizedPayload = { ...payload, thid };
+    if (canClientSubmitAndPoll(client)) {
+        return requireClientMethod(client, 'submitAndPoll')(submitPath, pollPath, normalizedPayload, pollOptions);
+    }
+    return submitAndPollWithMethods(client, submitPath, pollPath, normalizedPayload, pollOptions);
+}
+function requireSubmitPayloadThid(payload) {
+    const thid = String(payload.thid || '').trim();
+    if (!thid) {
+        throw new Error('submitAndPoll requires payload.thid.');
+    }
+    return thid;
+}

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

@@ -0,0 +1,14 @@
+import type { ControllerBindingInput } from 'gdc-common-utils-ts/models';
+import { type NodeRuntimeClient, type PollOptions, type SubmitAndPollResult, type SubmitPayload } from './client-port.js';
+import type { HostRouteContext, LegalOrganizationOrderInput } from '../host-onboarding.js';
+export declare class HostOnboardingSdk {
+    private readonly client;
+    constructor(client: NodeRuntimeClient);
+    activateOrganizationInGatewayFromIcaProof(hostCtx: HostRouteContext, input: {
+        vpToken: string;
+        controller?: ControllerBindingInput;
+        additionalClaims?: Record<string, unknown>;
+    }, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    confirmLegalOrganizationOrder(hostCtx: HostRouteContext, input: LegalOrganizationOrderInput, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+    submitAndPoll(submitPath: string, pollPath: string, payload: SubmitPayload, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+}

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

@@ -0,0 +1,15 @@
+import { requireClientMethod, submitAndPollWithClient, } from './client-port.js';
+export class HostOnboardingSdk {
+    constructor(client) {
+        this.client = client;
+    }
+    activateOrganizationInGatewayFromIcaProof(hostCtx, input, pollOptions) {
+        return requireClientMethod(this.client, 'activateOrganizationInGatewayFromIcaProof')(hostCtx, input, pollOptions);
+    }
+    confirmLegalOrganizationOrder(hostCtx, input, pollOptions) {
+        return requireClientMethod(this.client, 'confirmLegalOrganizationOrder')(hostCtx, input, pollOptions);
+    }
+    submitAndPoll(submitPath, pollPath, payload, pollOptions) {
+        return submitAndPollWithClient(this.client, submitPath, pollPath, payload, pollOptions);
+    }
+}

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

@@ -0,0 +1,54 @@
+import { type NodeRuntimeClient, type PollOptions, type SubmitAndPollResult, type SubmitPayload } from './client-port.js';
+import type { IndividualOrganizationConfirmOrderInput, RouteContext } from '../individual-onboarding.js';
+import type { IndividualOrganizationBootstrapInput, IndividualOrganizationStartResult } from '../individual-start.js';
+import type { CommunicationIngestionInput, DigitalTwinGenerationInput, GrantProfessionalAccessInput, GrantProfessionalAccessResult, IpsOrFhirImportInput, RelatedPersonUpsertInput } from '../resource-operations.js';
+import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-token.js';
+/**
+ * Individual-controller oriented facade over a `NodeRuntimeClient`.
+ *
+ * It groups the most common individual subject flows: organization/index
+ * bootstrap, consent, IPS/FHIR ingestion, digital twin generation, and token requests.
+ */
+export declare class IndividualControllerSdk {
+    private readonly client;
+    /**
+     * @param client Runtime client implementation used to submit and poll GW flows.
+     */
+    constructor(client: NodeRuntimeClient);
+    /**
+     * Starts the individual onboarding/bootstrap flow.
+     */
+    startIndividualOrganization(input: IndividualOrganizationBootstrapInput): Promise<IndividualOrganizationStartResult>;
+    /**
+     * Confirms the order returned by `startIndividualOrganization(...)`.
+     */
+    confirmIndividualOrganizationOrder(input: IndividualOrganizationConfirmOrderInput): Promise<SubmitAndPollResult>;
+    /**
+     * Grants access to a professional through a consent flow.
+     */
+    grantProfessionalAccess(ctx: RouteContext, input: GrantProfessionalAccessInput): Promise<GrantProfessionalAccessResult>;
+    /**
+     * Imports a FHIR/IPS payload and waits until it is indexed.
+     */
+    importIpsOrFhirAndUpdateIndex(ctx: RouteContext, input: IpsOrFhirImportInput): Promise<SubmitAndPollResult>;
+    /**
+     * Creates or updates a `RelatedPerson` for non-employee caregivers or family members.
+     */
+    upsertRelatedPersonAndPoll(ctx: RouteContext, input: RelatedPersonUpsertInput): Promise<SubmitAndPollResult>;
+    /**
+     * Ingests a FHIR `Communication` and waits for indexing.
+     */
+    ingestCommunicationAndUpdateIndex(ctx: RouteContext, input: CommunicationIngestionInput): Promise<SubmitAndPollResult>;
+    /**
+     * Generates a digital twin projection from subject data.
+     */
+    generateDigitalTwinFromSubjectData(ctx: RouteContext, input: DigitalTwinGenerationInput): Promise<SubmitAndPollResult>;
+    /**
+     * Requests a SMART/OpenID token for subsequent data access flows.
+     */
+    requestSmartToken(input: SmartTokenRequestInput): Promise<SmartTokenExchangeResult>;
+    /**
+     * Low-level escape hatch for direct submit/poll flows.
+     */
+    submitAndPoll(submitPath: string, pollPath: string, payload: SubmitPayload, pollOptions?: PollOptions): Promise<SubmitAndPollResult>;
+}