gdc-sdk-node-ts 2.4.4 → 2.4.8

package/README.md

@@ -640,6 +640,11 @@ modules below.
 - [`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/digital-twin.ts`](src/digital-twin.ts)
+  - types: `DigitalTwinSearchInput`, `DigitalTwinSelectionInput`, `DigitalTwinResearchTag`, `DigitalTwinMaterializationInput`
+  - functions: `searchDigitalTwinsWithDeps(...)`, `saveDigitalTwinSelectionWithDeps(...)`, `materializeDigitalTwinWithDeps(...)`
+- [`src/orchestration/digital-twin-sdk.ts`](src/orchestration/digital-twin-sdk.ts)
+  - class: `DigitalTwinSdk` (`requestSmartToken`, `search`, `saveSelection`, `materialize`)
 - [`src/session.ts`](src/session.ts)
   - types: `NodeCapability`, `NodeActorSessionContext`, `ActorSessionContext`
   - classes: `ActorSession`, `NodeActorSession`

package/dist/digital-twin.d.ts

@@ -0,0 +1,109 @@
+import { CompositionClaim } from 'gdc-common-utils-ts/models';
+import type { MetaTagCoding } from 'gdc-common-utils-ts/models/confidential-storage';
+import type { RouteContext } from './individual-onboarding.js';
+import type { PollOptions, SubmitAndPollResult } from './orchestration/client-port.js';
+export type DigitalTwinFhirFormat = 'org.hl7.fhir.r4' | 'org.hl7.fhir.api';
+/** Search parameters added by the digital-twin Composition profile. */
+export declare const DigitalTwinSearchParameter: Readonly<{
+    Section: "section";
+    MetaTag: "Composition.meta-tag";
+}>;
+export type DigitalTwinSearchInput = {
+    /** SMART bearer used for this research operation. */
+    accessToken?: string;
+    thid?: string;
+    format?: DigitalTwinFhirFormat;
+    resourceType?: string;
+    filters?: Readonly<Record<string, string | readonly string[] | undefined>>;
+    pollOptions?: PollOptions;
+};
+/** One pseudonymous Composition returned by a digital-twin search. */
+export type DigitalTwinSearchMatch = Record<string, unknown> & {
+    id?: string;
+    [CompositionClaim.Subject]: string;
+    [CompositionClaim.Section]?: string;
+    meta?: {
+        tag?: DigitalTwinResearchTag[];
+    };
+};
+/** High-level search result; GW transport envelopes remain available for diagnostics. */
+export type DigitalTwinSearchResult = {
+    total: number;
+    matches: DigitalTwinSearchMatch[];
+    operation: SubmitAndPollResult;
+};
+export type DigitalTwinMaterializationInput = {
+    /** SMART bearer used for this research operation. */
+    accessToken?: string;
+    twinSubjectId: string;
+    thid?: string;
+    format?: DigitalTwinFhirFormat;
+    sections?: readonly string[];
+    sent?: string;
+    pollOptions?: PollOptions;
+};
+/** Ledger-safe employee-defined marker attached to a research working copy. */
+export type DigitalTwinResearchTag = Required<Pick<MetaTagCoding, 'system' | 'code'>> & Pick<MetaTagCoding, 'version' | 'userSelected'> & {
+    /** Stable position/name for the tag in the Composition metadata. */
+    id?: string;
+};
+/**
+ * Saves a researcher-owned Composition working selection for one twin.
+ *
+ * This does not mutate the canonical twin or copy clinical data. The record
+ * stores the pseudonymous subject, section, author and ledger-safe tags used
+ * to recover the researcher's working set later.
+ */
+export type DigitalTwinSelectionInput = {
+    accessToken?: string;
+    twinSubjectId: string;
+    section: string;
+    tags: readonly DigitalTwinResearchTag[];
+    /**
+     * Operational hosted employee DID. High-level callers should omit this:
+     * `DigitalTwinSdk` binds it to the authenticated actor session.
+     */
+    authorDid?: string;
+    /** Optional FHIR logical id for this saved selection. A UUID is generated when omitted. */
+    selectionId?: string;
+    /** @deprecated Use `selectionId`; retained for low-level compatibility. */
+    compositionId?: string;
+    documentType?: string;
+    date?: string;
+    thid?: string;
+    format?: DigitalTwinFhirFormat;
+    pollOptions?: PollOptions;
+};
+/**
+ * Builds one opaque FHIR logical id for a saved working selection.
+ *
+ * Ownership remains in the standard `Composition.author` claim. Reopening a
+ * a saved collection uses `meta.tag` plus that author; no non-FHIR branch
+ * claims or employee hashes in tag systems exist.
+ */
+export declare function buildDigitalTwinSelectionIdentifier(input: Readonly<{
+    selectionId?: string;
+}>): Readonly<{
+    selectionId: string;
+    compositionId: string;
+}>;
+export type DigitalTwinRuntimeDeps = {
+    digitalTwinSearchPath: (ctx: RouteContext, format: DigitalTwinFhirFormat, resourceType: string) => string;
+    digitalTwinSearchPollPath: (ctx: RouteContext, format: DigitalTwinFhirFormat, resourceType: string) => string;
+    digitalTwinCommunicationBatchPath: (ctx: RouteContext, format: DigitalTwinFhirFormat) => string;
+    digitalTwinCommunicationPollPath: (ctx: RouteContext, format: DigitalTwinFhirFormat) => string;
+    digitalTwinCompositionBatchPath: (ctx: RouteContext, format: DigitalTwinFhirFormat) => string;
+    digitalTwinCompositionPollPath: (ctx: RouteContext, format: DigitalTwinFhirFormat) => string;
+    submitAndPoll: (submitPath: string, pollPath: string, payload: {
+        thid: string;
+        body: Record<string, unknown>;
+    }, pollOptions?: PollOptions) => Promise<SubmitAndPollResult>;
+};
+/** Opens the GW async response and exposes the matched Compositions directly. */
+export declare function readDigitalTwinSearchResult(operation: SubmitAndPollResult): DigitalTwinSearchResult;
+/** Persists one tagged researcher working copy through `digitaltwin/Composition/_batch`. */
+export declare function saveDigitalTwinSelectionWithDeps(ctx: RouteContext, input: DigitalTwinSelectionInput, deps: DigitalTwinRuntimeDeps): Promise<SubmitAndPollResult>;
+/** Searches the tenant digital-twin index through its public asynchronous route. */
+export declare function searchDigitalTwinsWithDeps(ctx: RouteContext, input: DigitalTwinSearchInput, deps: DigitalTwinRuntimeDeps): Promise<SubmitAndPollResult>;
+/** Materializes one selected pseudonymous twin as a research summary Bundle. */
+export declare function materializeDigitalTwinWithDeps(ctx: RouteContext, input: DigitalTwinMaterializationInput, deps: DigitalTwinRuntimeDeps): Promise<SubmitAndPollResult>;

package/dist/digital-twin.js

@@ -0,0 +1,181 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { randomUUID } from 'node:crypto';
+import { HealthcareDocumentTypes } from 'gdc-common-utils-ts/constants';
+import { CompositionClaim } from 'gdc-common-utils-ts/models';
+/** Search parameters added by the digital-twin Composition profile. */
+export const DigitalTwinSearchParameter = Object.freeze({
+    Section: 'section',
+    MetaTag: 'Composition.meta-tag',
+});
+/**
+ * Builds one opaque FHIR logical id for a saved working selection.
+ *
+ * Ownership remains in the standard `Composition.author` claim. Reopening a
+ * a saved collection uses `meta.tag` plus that author; no non-FHIR branch
+ * claims or employee hashes in tag systems exist.
+ */
+export function buildDigitalTwinSelectionIdentifier(input) {
+    const selectionId = String(input.selectionId || '').trim() || randomUUID();
+    if (!/^[A-Za-z0-9.-]{1,64}$/.test(selectionId)) {
+        throw new Error('Digital twin selectionId must be a valid FHIR logical id.');
+    }
+    return Object.freeze({
+        selectionId,
+        compositionId: selectionId,
+    });
+}
+function normalizeResearchTags(tags) {
+    if (!Array.isArray(tags) || tags.length === 0)
+        throw new Error('At least one research tag is required.');
+    const normalized = tags.map((tag, index) => {
+        const system = String(tag?.system || '').trim();
+        const code = String(tag?.code || '').trim();
+        if (!system || !code)
+            throw new Error('Each research tag requires system and code.');
+        return {
+            id: String(tag.id || `Composition.meta.tag[${index}]`).trim(),
+            system,
+            code,
+            ...(tag.version ? { version: String(tag.version) } : {}),
+            ...(typeof tag.userSelected === 'boolean' ? { userSelected: tag.userSelected } : {}),
+        };
+    });
+    if (new Set(normalized.map((tag) => tag.id)).size !== normalized.length) {
+        throw new Error('Research tag ids must be unique within one selection.');
+    }
+    return normalized;
+}
+/** Opens the GW async response and exposes the matched Compositions directly. */
+export function readDigitalTwinSearchResult(operation) {
+    const body = operation?.poll?.body;
+    const responseEntries = Array.isArray(body?.data)
+        ? body.data
+        : Array.isArray(body?.entry)
+            ? body.entry
+            : [];
+    const responseEntry = responseEntries.find((entry) => {
+        const resource = entry?.resource;
+        return Boolean(resource && typeof resource === 'object' && Array.isArray(resource.data));
+    });
+    if (!responseEntry?.resource || !Array.isArray(responseEntry.resource.data)) {
+        throw new Error('Digital twin search did not return a Composition result set.');
+    }
+    const matches = responseEntry.resource.data;
+    const parsedTotal = Number(responseEntry.resource.total);
+    return {
+        total: Number.isFinite(parsedTotal) ? parsedTotal : matches.length,
+        matches,
+        operation,
+    };
+}
+/** Persists one tagged researcher working copy through `digitaltwin/Composition/_batch`. */
+export async function saveDigitalTwinSelectionWithDeps(ctx, input, deps) {
+    const twinSubjectId = String(input.twinSubjectId || '').trim();
+    const section = String(input.section || '').trim();
+    const authorDid = String(input.authorDid || '').trim();
+    if (!twinSubjectId)
+        throw new Error('twinSubjectId is required.');
+    if (!section)
+        throw new Error('Digital twin selection section is required.');
+    if (!authorDid)
+        throw new Error('Digital twin selection authorDid is required.');
+    const format = input.format || 'org.hl7.fhir.r4';
+    const thid = String(input.thid || randomUUID());
+    const selectionIdentifier = buildDigitalTwinSelectionIdentifier({
+        selectionId: input.selectionId || input.compositionId,
+    });
+    const compositionId = selectionIdentifier.compositionId;
+    const tags = normalizeResearchTags(input.tags);
+    const claims = {
+        '@context': format,
+        '@type': 'Composition:ResearcherWorkingSelection',
+        [CompositionClaim.Identifier]: compositionId,
+        [CompositionClaim.Subject]: twinSubjectId,
+        [CompositionClaim.Section]: section,
+        [CompositionClaim.Type]: input.documentType || HealthcareDocumentTypes.IPS.attributeValue,
+        [CompositionClaim.Author]: authorDid,
+        [CompositionClaim.Date]: input.date || new Date().toISOString(),
+    };
+    const resource = {
+        resourceType: 'Composition',
+        id: compositionId,
+        meta: { claims, tag: tags },
+    };
+    const entry = {
+        type: 'Composition',
+        resource,
+        request: { method: 'POST', url: `digitaltwin/${format}/Composition` },
+    };
+    return deps.submitAndPoll(deps.digitalTwinCompositionBatchPath(ctx, format), deps.digitalTwinCompositionPollPath(ctx, format), {
+        thid,
+        body: format === 'org.hl7.fhir.api'
+            ? { resourceType: 'Bundle', type: 'batch', data: [entry] }
+            : { resourceType: 'Bundle', type: 'batch', entry: [entry] },
+    }, input.pollOptions);
+}
+/** Searches the tenant digital-twin index through its public asynchronous route. */
+export async function searchDigitalTwinsWithDeps(ctx, input, deps) {
+    const format = input.format || 'org.hl7.fhir.r4';
+    const resourceType = String(input.resourceType || 'Composition').trim();
+    if (!resourceType)
+        throw new Error('Digital twin resourceType is required.');
+    const parameters = Object.entries(input.filters || {}).flatMap(([name, value]) => {
+        const values = Array.isArray(value) ? value : value === undefined ? [] : [value];
+        return values.map((item) => ({ name, valueString: String(item) }));
+    });
+    const thid = String(input.thid || randomUUID());
+    const body = format === 'org.hl7.fhir.api'
+        ? {
+            data: [{
+                    type: `${resourceType}-search-request-v1.0`,
+                    resource: { resourceType: 'Parameters', parameter: parameters },
+                    meta: {
+                        claims: Object.fromEntries([
+                            ['@context', format],
+                            ...parameters.map((parameter) => [parameter.name, parameter.valueString]),
+                        ]),
+                    },
+                }],
+        }
+        : { resourceType: 'Parameters', parameter: parameters };
+    return deps.submitAndPoll(deps.digitalTwinSearchPath(ctx, format, resourceType), deps.digitalTwinSearchPollPath(ctx, format, resourceType), {
+        thid,
+        body,
+    }, input.pollOptions);
+}
+/** Materializes one selected pseudonymous twin as a research summary Bundle. */
+export async function materializeDigitalTwinWithDeps(ctx, input, deps) {
+    const twinSubjectId = String(input.twinSubjectId || '').trim();
+    if (!twinSubjectId)
+        throw new Error('twinSubjectId is required.');
+    const format = input.format || 'org.hl7.fhir.r4';
+    const thid = String(input.thid || randomUUID());
+    const parameters = [
+        { name: 'subject', valueString: twinSubjectId },
+        ...(input.sections || []).map((section) => ({ name: 'section', valueString: String(section) })),
+    ];
+    const encodedParameters = Buffer.from(JSON.stringify({
+        resourceType: 'Parameters',
+        parameter: parameters,
+    }), 'utf8').toString('base64');
+    return deps.submitAndPoll(deps.digitalTwinCommunicationBatchPath(ctx, format), deps.digitalTwinCommunicationPollPath(ctx, format), {
+        thid,
+        body: {
+            resourceType: 'Bundle',
+            type: 'batch',
+            entry: [{
+                    request: { method: 'POST', url: `digitaltwin/${format}/Communication` },
+                    resource: {
+                        resourceType: 'Communication',
+                        status: 'completed',
+                        subject: { reference: twinSubjectId },
+                        sent: input.sent || new Date().toISOString(),
+                        payload: [{
+                                contentReference: { reference: `digitaltwin/${format}/ResearchSubject/$summary` },
+                                contentAttachment: { contentType: 'application/fhir+json', data: encodedParameters },
+                            }],
+                    },
+                }],
+        },
+    }, input.pollOptions);
+}

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export * from './fhir-r5-subscription-runtime.js';
 export * from './order-offer-summary.js';
 export * from './organization-license-order.js';
 export * from './resource-operations.js';
+export * from './digital-twin.js';
+export * from './operational-actor-did.js';
 export * from './profile-workspace.js';
 export * from './UserProfileIndexStore.js';
 export * from './wallet-backed-job-manager.js';
@@ -44,5 +46,6 @@ export * from './orchestration/individual-controller-sdk.js';
 export * from './orchestration/individual-member-sdk.js';
 export * from './orchestration/personal-sdk.js';
 export * from './orchestration/professional-sdk.js';
+export * from './orchestration/digital-twin-sdk.js';
 export * from './legacy-compat.js';
 export * from './local-terminology-bff.js';

package/dist/index.js

@@ -25,6 +25,8 @@ export * from './fhir-r5-subscription-runtime.js';
 export * from './order-offer-summary.js';
 export * from './organization-license-order.js';
 export * from './resource-operations.js';
+export * from './digital-twin.js';
+export * from './operational-actor-did.js';
 export * from './profile-workspace.js';
 export * from './UserProfileIndexStore.js';
 export * from './wallet-backed-job-manager.js';
@@ -45,5 +47,6 @@ export * from './orchestration/individual-controller-sdk.js';
 export * from './orchestration/individual-member-sdk.js';
 export * from './orchestration/personal-sdk.js';
 export * from './orchestration/professional-sdk.js';
+export * from './orchestration/digital-twin-sdk.js';
 export * from './legacy-compat.js';
 export * from './local-terminology-bff.js';

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

@@ -19,6 +19,7 @@ import type { OrganizationEmployeeLifecycleRecord } from 'gdc-common-utils-ts/mo
 import type { NodeRuntimeClient, PollOptions, PollResult, SubmitAndPollResult, SubmitPayload, SubmitResponse } from './orchestration/client-port.js';
 import { type FhirR5SubscriptionBatchInput } from './fhir-r5-subscription-runtime.js';
 import type { FhirR5SubscriptionTopic } from 'gdc-common-utils-ts/models/fhir-r5-subscription';
+import { type DigitalTwinMaterializationInput, type DigitalTwinSearchInput, type DigitalTwinSelectionInput } from './digital-twin.js';
 export type HttpRuntimeClientOptions = {
     baseUrl: string;
     bearerToken?: string;
@@ -512,6 +513,12 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * @param input Search parameters such as subject, section, date and included resource types.
      */
     searchClinicalBundle(ctx: RouteContext, input: ClinicalBundleSearchInput): Promise<SubmitAndPollResult>;
+    /** Searches tenant digital twins using coded, pseudonymous research claims. */
+    searchDigitalTwins(ctx: RouteContext, input: DigitalTwinSearchInput): Promise<SubmitAndPollResult>;
+    /** Saves one tagged researcher working copy without mutating the canonical twin. */
+    saveDigitalTwinSelection(ctx: RouteContext, input: DigitalTwinSelectionInput): Promise<SubmitAndPollResult>;
+    /** Materializes one selected pseudonymous research subject as a summary Bundle. */
+    materializeDigitalTwin(ctx: RouteContext, input: DigitalTwinMaterializationInput): Promise<SubmitAndPollResult>;
     /**
      * Searches the latest IPS-oriented document view for a subject.
      *

package/dist/node-runtime-client.js

@@ -21,6 +21,7 @@ import { buildGrantProfessionalAccessClaimsWithCid } from './runtime-consent.js'
 import { RuntimeClientPaths } from './runtime-client-paths.js';
 import { runtimeUuid, wrapBundleAsGatewayTransactionMessage } from './runtime-message.js';
 import { submitFhirR5SubscriptionBatchWithDeps, submitFhirR5SubscriptionTopicBatchWithDeps, } from './fhir-r5-subscription-runtime.js';
+import { materializeDigitalTwinWithDeps, saveDigitalTwinSelectionWithDeps, searchDigitalTwinsWithDeps, } from './digital-twin.js';
 const bootstrapFacade = createBootstrapFacade();
 /**
  * Runtime-oriented HTTP client for Node backends, BFFs, and workers that need
@@ -908,12 +909,15 @@ export class HttpRuntimeClient {
      * Applies the configured wire profile to a direct subject-index search.
      * This is compatibility/specialized plumbing, not the primary summary read.
      */
-    async submitClinicalMessageAndPoll(submitPath, pollPath, payload, profile, pollOptions) {
+    async submitClinicalMessageAndPoll(submitPath, pollPath, payload, profile, pollOptions, accessToken) {
+        const transportConfig = accessToken
+            ? { ...this.transportConfig, bearerToken: accessToken }
+            : this.transportConfig;
         const renderedSubmit = await renderGatewayMessageRequest(payload, profile, this.secureTransportAdapter);
-        const submit = await postRenderedWithRuntimeConfig(this.transportConfig, submitPath, renderedSubmit);
+        const submit = await postRenderedWithRuntimeConfig(transportConfig, submitPath, renderedSubmit);
         const poll = await pollUntilCompleteWithMethod(async (path, request) => {
             const renderedPoll = await renderTransportPollRequest(request.thid, profile, this.secureTransportAdapter);
-            const response = await postRenderedWithRuntimeConfig(this.transportConfig, path, renderedPoll);
+            const response = await postRenderedWithRuntimeConfig(transportConfig, path, renderedPoll);
             return {
                 status: response.status,
                 body: response.status === 202
@@ -986,6 +990,42 @@ export class HttpRuntimeClient {
             submitAndPoll: (submitPath, pollPath, payload, pollOptions) => this.submitClinicalMessageAndPoll(submitPath, pollPath, payload, input.transportProfile || this.transportProfile, pollOptions),
         });
     }
+    /** Searches tenant digital twins using coded, pseudonymous research claims. */
+    async searchDigitalTwins(ctx, input) {
+        return searchDigitalTwinsWithDeps(ctx, input, {
+            digitalTwinSearchPath: this.paths.digitalTwinSearchPath.bind(this.paths),
+            digitalTwinSearchPollPath: this.paths.digitalTwinSearchPollPath.bind(this.paths),
+            digitalTwinCompositionBatchPath: this.paths.digitalTwinCompositionBatchPath.bind(this.paths),
+            digitalTwinCompositionPollPath: this.paths.digitalTwinCompositionPollPath.bind(this.paths),
+            digitalTwinCommunicationBatchPath: this.paths.digitalTwinCommunicationBatchPath.bind(this.paths),
+            digitalTwinCommunicationPollPath: this.paths.digitalTwinCommunicationPollPath.bind(this.paths),
+            submitAndPoll: (submitPath, pollPath, payload, pollOptions) => this.submitClinicalMessageAndPoll(submitPath, pollPath, payload, this.transportProfile, pollOptions, input.accessToken),
+        });
+    }
+    /** Saves one tagged researcher working copy without mutating the canonical twin. */
+    async saveDigitalTwinSelection(ctx, input) {
+        return saveDigitalTwinSelectionWithDeps(ctx, input, {
+            digitalTwinSearchPath: this.paths.digitalTwinSearchPath.bind(this.paths),
+            digitalTwinSearchPollPath: this.paths.digitalTwinSearchPollPath.bind(this.paths),
+            digitalTwinCompositionBatchPath: this.paths.digitalTwinCompositionBatchPath.bind(this.paths),
+            digitalTwinCompositionPollPath: this.paths.digitalTwinCompositionPollPath.bind(this.paths),
+            digitalTwinCommunicationBatchPath: this.paths.digitalTwinCommunicationBatchPath.bind(this.paths),
+            digitalTwinCommunicationPollPath: this.paths.digitalTwinCommunicationPollPath.bind(this.paths),
+            submitAndPoll: (submitPath, pollPath, payload, pollOptions) => this.submitClinicalMessageAndPoll(submitPath, pollPath, payload, this.transportProfile, pollOptions, input.accessToken),
+        });
+    }
+    /** Materializes one selected pseudonymous research subject as a summary Bundle. */
+    async materializeDigitalTwin(ctx, input) {
+        return materializeDigitalTwinWithDeps(ctx, input, {
+            digitalTwinSearchPath: this.paths.digitalTwinSearchPath.bind(this.paths),
+            digitalTwinSearchPollPath: this.paths.digitalTwinSearchPollPath.bind(this.paths),
+            digitalTwinCompositionBatchPath: this.paths.digitalTwinCompositionBatchPath.bind(this.paths),
+            digitalTwinCompositionPollPath: this.paths.digitalTwinCompositionPollPath.bind(this.paths),
+            digitalTwinCommunicationBatchPath: this.paths.digitalTwinCommunicationBatchPath.bind(this.paths),
+            digitalTwinCommunicationPollPath: this.paths.digitalTwinCommunicationPollPath.bind(this.paths),
+            submitAndPoll: (submitPath, pollPath, payload, pollOptions) => this.submitClinicalMessageAndPoll(submitPath, pollPath, payload, this.transportProfile, pollOptions, input.accessToken),
+        });
+    }
     /**
      * Searches the latest IPS-oriented document view for a subject.
      *

package/dist/operational-actor-did.d.ts

@@ -0,0 +1,14 @@
+/** Minimal DID document shape required for portal-alias resolution. */
+export type OperationalActorDidDocument = Readonly<{
+    id: string;
+    alsoKnownAs?: readonly string[];
+}>;
+/**
+ * Resolves a public portal/vanity DID to the canonical hosted operational DID.
+ *
+ * `alsoKnownAs` proves only alias continuity. Authentication and authorization
+ * still come from the verified employee credential and SMART token. The
+ * returned primary `id` is the value used in ActorSession and internal GW
+ * requests.
+ */
+export declare function resolveOperationalActorDid(publicActorDid: string, resolveDidDocument: (did: string) => Promise<OperationalActorDidDocument>): Promise<string>;

package/dist/operational-actor-did.js

@@ -0,0 +1,26 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * Resolves a public portal/vanity DID to the canonical hosted operational DID.
+ *
+ * `alsoKnownAs` proves only alias continuity. Authentication and authorization
+ * still come from the verified employee credential and SMART token. The
+ * returned primary `id` is the value used in ActorSession and internal GW
+ * requests.
+ */
+export async function resolveOperationalActorDid(publicActorDid, resolveDidDocument) {
+    const requestedDid = String(publicActorDid || '').trim();
+    if (!requestedDid.startsWith('did:'))
+        throw new Error('A public actor DID is required.');
+    const document = await resolveDidDocument(requestedDid);
+    const operationalDid = String(document?.id || '').trim();
+    if (!operationalDid.startsWith('did:web:')) {
+        throw new Error('Resolved employee identity must have a hosted did:web primary id.');
+    }
+    if (operationalDid !== requestedDid) {
+        const aliases = (document.alsoKnownAs || []).map((value) => String(value || '').trim());
+        if (!aliases.includes(requestedDid)) {
+            throw new Error('Resolved DID document does not bind the requested public actor alias.');
+        }
+    }
+    return operationalDid;
+}

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

@@ -17,6 +17,7 @@ import type { FhirR5SubscriptionBatchInput } from '../fhir-r5-subscription-runti
 import type { EnsureFamilyOrganizationRegistrationInput, EnsureFamilyOrganizationRegistrationResult } from '../family-organization-registration.js';
 import type { OrganizationLicenseOrderConfirmInput } from '../organization-license-order.js';
 import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-token.js';
+import type { DigitalTwinMaterializationInput, DigitalTwinSearchInput, DigitalTwinSelectionInput } from '../digital-twin.js';
 import type { CommunicationIngestionInput, BlockchainArtifactRegistrationInput, CommunicationParticipantRuntimeSearchInput, ClinicalBundleSearchInput, ClinicalSectionUpdateInput, ClinicalSummaryReadResult, ClinicalSummaryRequestInput, ClinicalSummaryUpdateInput, VitalSignBatchCommunicationFromSearchResponseInput, DigitalTwinGenerationInput, GrantProfessionalAccessInput, GrantProfessionalAccessResult, IndividualMemberLifecycleInput, IndividualMemberLicenseAddInput, IndividualMemberLicenseInvitationInput, IndividualMemberLicenseTransitionInput, IpsOrFhirImportInput, OrganizationEmployeeCreationInput, OrganizationEmployeeLicenseInvitationInput, OrganizationEmployeeLifecycleInput, OrganizationEmployeeSearchInput, ProfessionalAccessRequestInput, ProfessionalAccessRequestResult, RevokeProfessionalAccessInput, RevokeProfessionalAccessResult, RelatedPersonUpsertInput } from '../resource-operations.js';
 /**
  * Shared node-runtime activation input.
@@ -125,6 +126,9 @@ export type RuntimeClient = {
     upsertRelatedPersonAndPoll?: (ctx: RouteContext, input: RelatedPersonUpsertInput) => Promise<SubmitAndPollResult>;
     generateDigitalTwinFromSubjectData?: (ctx: RouteContext, input: DigitalTwinGenerationInput) => Promise<SubmitAndPollResult>;
     searchClinicalBundle?: (ctx: RouteContext, input: ClinicalBundleSearchInput) => Promise<SubmitAndPollResult>;
+    searchDigitalTwins?: (ctx: RouteContext, input: DigitalTwinSearchInput) => Promise<SubmitAndPollResult>;
+    saveDigitalTwinSelection?: (ctx: RouteContext, input: DigitalTwinSelectionInput) => Promise<SubmitAndPollResult>;
+    materializeDigitalTwin?: (ctx: RouteContext, input: DigitalTwinMaterializationInput) => Promise<SubmitAndPollResult>;
     getLatestIps?: (ctx: RouteContext, input: Omit<ClinicalBundleSearchInput, 'includedTypes'>) => Promise<SubmitAndPollResult>;
     submitBatch?: (submitPath: string, payload: SubmitPayload) => Promise<SubmitResponse>;
     pollUntilComplete?: (pollPath: string, request: AsyncPollRequest, pollOptions?: PollOptions) => Promise<PollResult>;

package/dist/orchestration/digital-twin-sdk.d.ts

@@ -0,0 +1,30 @@
+import type { RouteContext } from '../individual-onboarding.js';
+import type { SmartTokenExchangeResult, SmartTokenRequestInput } from '../smart-token.js';
+import type { DigitalTwinMaterializationInput, DigitalTwinSelectionInput, DigitalTwinSearchInput, DigitalTwinSearchResult } from '../digital-twin.js';
+import { type NodeRuntimeClient, type SubmitAndPollResult } from './client-port.js';
+/** Public research facade for licensed digital-twin access. */
+export declare class DigitalTwinSdk {
+    private readonly client;
+    private smartAccessToken?;
+    private researcherDid?;
+    constructor(client: NodeRuntimeClient, actorDid?: string);
+    /** Requests the SMART token used by subsequent digital-twin operations. */
+    requestSmartToken(input: SmartTokenRequestInput): Promise<SmartTokenExchangeResult>;
+    /** Searches pseudonymous records and exposes matched Compositions directly. */
+    search(ctx: RouteContext, input: DigitalTwinSearchInput): Promise<DigitalTwinSearchResult>;
+    /**
+     * Saves a tagged researcher-owned working selection for one matching twin.
+     * The canonical clinical twin is never modified.
+     */
+    saveSelection(ctx: RouteContext, input: DigitalTwinSelectionInput): Promise<SubmitAndPollResult>;
+    /** Reopens only this employee's saved selections for one exact custom tag. */
+    searchSelections(ctx: RouteContext, input: Omit<DigitalTwinSearchInput, 'filters'> & {
+        section: string;
+        tag: Readonly<{
+            system: string;
+            code: string;
+        }>;
+    }): Promise<DigitalTwinSearchResult>;
+    /** Materializes one selected research subject through `ResearchSubject/$summary`. */
+    materialize(ctx: RouteContext, input: DigitalTwinMaterializationInput): Promise<SubmitAndPollResult>;
+}

package/dist/orchestration/digital-twin-sdk.js

@@ -0,0 +1,100 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+import { HealthcareConsentPurposes, ServiceCapability } from 'gdc-common-utils-ts/constants';
+import { CompositionClaim } from 'gdc-common-utils-ts/models';
+import { DigitalTwinSearchParameter, readDigitalTwinSearchResult } from '../digital-twin.js';
+import { requireClientMethod } from './client-port.js';
+/** Public research facade for licensed digital-twin access. */
+export class DigitalTwinSdk {
+    constructor(client, actorDid) {
+        this.client = client;
+        this.researcherDid = String(actorDid || '').trim() || undefined;
+    }
+    /** Requests the SMART token used by subsequent digital-twin operations. */
+    async requestSmartToken(input) {
+        const requestedActorDid = String(input.actorDid || '').trim() || undefined;
+        if (this.researcherDid && requestedActorDid && requestedActorDid !== this.researcherDid) {
+            throw new Error('DigitalTwinSdk actorDid must match the actor session.');
+        }
+        const actorDid = this.researcherDid || requestedActorDid;
+        const result = await requireClientMethod(this.client, 'requestSmartToken')({
+            ...input,
+            actorDid,
+            purpose: input.purpose || HealthcareConsentPurposes.Research,
+            scopes: input.scopes?.length ? input.scopes : [ServiceCapability.DigitalTwinReader],
+        });
+        if (result.accessToken)
+            this.smartAccessToken = result.accessToken;
+        if (actorDid)
+            this.researcherDid = actorDid;
+        return result;
+    }
+    /** Searches pseudonymous records and exposes matched Compositions directly. */
+    async search(ctx, input) {
+        const filters = { ...(input.filters || {}) };
+        const isPrivateSelectionSearch = Object.keys(filters).some((name) => {
+            const normalized = String(name || '').trim().toLowerCase();
+            return normalized === 'composition.meta-tag' || normalized === 'composition.meta.tag';
+        });
+        if (isPrivateSelectionSearch) {
+            if (!this.researcherDid) {
+                throw new Error('Digital twin working-selection search requires an operational actor DID.');
+            }
+            const requestedAuthor = filters[CompositionClaim.Author];
+            const requestedAuthors = Array.isArray(requestedAuthor)
+                ? requestedAuthor.map(String)
+                : requestedAuthor === undefined
+                    ? []
+                    : [String(requestedAuthor)];
+            if (requestedAuthors.some((author) => author !== this.researcherDid)) {
+                throw new Error('Digital twin selection author filter must match the actor session.');
+            }
+            filters[CompositionClaim.Author] = this.researcherDid;
+        }
+        const operation = await requireClientMethod(this.client, 'searchDigitalTwins')(ctx, {
+            ...input,
+            filters,
+            accessToken: input.accessToken || this.smartAccessToken,
+        });
+        return readDigitalTwinSearchResult(operation);
+    }
+    /**
+     * Saves a tagged researcher-owned working selection for one matching twin.
+     * The canonical clinical twin is never modified.
+     */
+    saveSelection(ctx, input) {
+        const requestedAuthorDid = String(input.authorDid || '').trim() || undefined;
+        if (this.researcherDid && requestedAuthorDid && requestedAuthorDid !== this.researcherDid) {
+            throw new Error('Digital twin selection authorDid must match the actor session.');
+        }
+        return requireClientMethod(this.client, 'saveDigitalTwinSelection')(ctx, {
+            ...input,
+            authorDid: this.researcherDid || requestedAuthorDid,
+            accessToken: input.accessToken || this.smartAccessToken,
+        });
+    }
+    /** Reopens only this employee's saved selections for one exact custom tag. */
+    searchSelections(ctx, input) {
+        const section = String(input.section || '').trim();
+        const system = String(input.tag?.system || '').trim();
+        const code = String(input.tag?.code || '').trim();
+        if (!section)
+            throw new Error('Digital twin selection section is required.');
+        if (!system || !code)
+            throw new Error('Digital twin selection tag requires system and code.');
+        const { section: _section, tag: _tag, ...searchInput } = input;
+        return this.search(ctx, {
+            ...searchInput,
+            filters: {
+                [DigitalTwinSearchParameter.Section]: section,
+                [DigitalTwinSearchParameter.MetaTag]: `${system}|${code}`,
+            },
+        });
+    }
+    /** Materializes one selected research subject through `ResearchSubject/$summary`. */
+    materialize(ctx, input) {
+        return requireClientMethod(this.client, 'materializeDigitalTwin')(ctx, {
+            ...input,
+            accessToken: input.accessToken || this.smartAccessToken,
+        });
+    }
+}

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

@@ -117,7 +117,8 @@ export declare class IndividualControllerSdk {
      */
     searchCommunicationParticipants(ctx: RouteContext, input: CommunicationParticipantRuntimeSearchInput): Promise<SubmitAndPollResult>;
     /**
-     * Generates a digital twin projection from subject data.
+     * Explicitly packages subject data for a study/transfer flow.
+     * Normal clinical ingestion is projected into the tenant research index by GW.
      */
     generateDigitalTwinFromSubjectData(ctx: RouteContext, input: DigitalTwinGenerationInput): Promise<SubmitAndPollResult>;
     /**

package/dist/orchestration/individual-controller-sdk.js

@@ -175,7 +175,8 @@ export class IndividualControllerSdk {
         return requireClientMethod(this.client, 'searchCommunicationParticipants')(ctx, input);
     }
     /**
-     * Generates a digital twin projection from subject data.
+     * Explicitly packages subject data for a study/transfer flow.
+     * Normal clinical ingestion is projected into the tenant research index by GW.
      */
     generateDigitalTwinFromSubjectData(ctx, input) {
         assertFacadeCapability(this.capabilities, ActorCapabilities.IndividualGenerateDigitalTwin, ActorKinds.IndividualController, 'generateDigitalTwinFromSubjectData');

package/dist/orchestration/personal-sdk.d.ts

@@ -28,7 +28,7 @@ export declare class PersonalSdk {
     registerBlockchainArtifactAndUpdateIndex(ctx: RouteContext, input: BlockchainArtifactRegistrationInput): Promise<SubmitAndPollResult>;
     /** Searches indexed communication channel records by subject and participant identifiers. */
     searchCommunicationParticipants(ctx: RouteContext, input: CommunicationParticipantRuntimeSearchInput): Promise<SubmitAndPollResult>;
-    /** Triggers digital twin generation from subject data. */
+    /** Explicitly packages subject data for a study/transfer; normal ingestion is projected by GW. */
     generateDigitalTwinFromSubjectData(ctx: RouteContext, input: DigitalTwinGenerationInput): Promise<SubmitAndPollResult>;
     /** Searches indexed clinical bundles for the current subject/controller context. */
     searchClinicalBundle(ctx: RouteContext, input: ClinicalBundleSearchInput): Promise<SubmitAndPollResult>;

package/dist/orchestration/personal-sdk.js

@@ -50,7 +50,7 @@ export class PersonalSdk {
     searchCommunicationParticipants(ctx, input) {
         return requireClientMethod(this.client, 'searchCommunicationParticipants')(ctx, input);
     }
-    /** Triggers digital twin generation from subject data. */
+    /** Explicitly packages subject data for a study/transfer; normal ingestion is projected by GW. */
     generateDigitalTwinFromSubjectData(ctx, input) {
         return requireClientMethod(this.client, 'generateDigitalTwinFromSubjectData')(ctx, input);
     }

package/dist/organization-registration-authorization.d.ts

@@ -0,0 +1,16 @@
+import type { VerifiableCredentialV2 } from 'gdc-common-utils-ts/models/verifiable-credential';
+import type { IWallet, WalletExecutionContext, WalletKeySelection } from 'gdc-sdk-core-ts';
+/** Input required to add one human-authorizer proof to the out-of-band VC. */
+export type SignOrganizationRegistrationAuthorizationInput = Readonly<{
+    credential: VerifiableCredentialV2;
+    wallet: IWallet;
+    context: WalletExecutionContext;
+    key: WalletKeySelection;
+    verificationMethod: string;
+    createdAt?: string;
+}>;
+/**
+ * Adds one detached JWS proof made by the already-unlocked professional
+ * profile. The browser never receives the private key or clear wallet seed.
+ */
+export declare function signOrganizationRegistrationAuthorizationCredential(input: SignOrganizationRegistrationAuthorizationInput): Promise<VerifiableCredentialV2>;

package/dist/organization-registration-authorization.js

@@ -0,0 +1,34 @@
+import { canonicalizeOrganizationRegistrationAuthorizationCredential, } from 'gdc-common-utils-ts/utils/organization-registration-authorization';
+/**
+ * Adds one detached JWS proof made by the already-unlocked professional
+ * profile. The browser never receives the private key or clear wallet seed.
+ */
+export async function signOrganizationRegistrationAuthorizationCredential(input) {
+    if (!input.wallet.signDetachedJws) {
+        throw new Error('Wallet does not support detached organization authorization proofs.');
+    }
+    const verificationMethod = String(input.verificationMethod || '').trim();
+    if (!verificationMethod)
+        throw new Error('Organization authorization proof requires verificationMethod.');
+    const payload = canonicalizeOrganizationRegistrationAuthorizationCredential(input.credential);
+    const jws = await input.wallet.signDetachedJws(input.context, {
+        payload,
+        header: { typ: 'application/vc+ld+json' },
+        key: input.key,
+    });
+    const existingProofs = Array.isArray(input.credential.proof)
+        ? input.credential.proof
+        : input.credential.proof
+            ? [input.credential.proof]
+            : [];
+    return {
+        ...input.credential,
+        proof: [...existingProofs, {
+                type: 'JsonWebSignature2020',
+                created: input.createdAt || new Date().toISOString(),
+                proofPurpose: 'contractAgreement',
+                verificationMethod,
+                jws,
+            }],
+    };
+}

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

@@ -84,6 +84,12 @@ export declare class RuntimeClientPaths {
     fhirR5SubscriptionPollPath(ctx: RouteContext, section: 'entity' | 'individual'): string;
     individualBundleSearchPath(ctx: RouteContext): string;
     individualBundleSearchPollPath(ctx: RouteContext): string;
+    digitalTwinSearchPath(ctx: RouteContext, format: string, resourceType: string): string;
+    digitalTwinSearchPollPath(ctx: RouteContext, format: string, resourceType: string): string;
+    digitalTwinCompositionBatchPath(ctx: RouteContext, format: string): string;
+    digitalTwinCompositionPollPath(ctx: RouteContext, format: string): string;
+    digitalTwinCommunicationBatchPath(ctx: RouteContext, format: string): string;
+    digitalTwinCommunicationPollPath(ctx: RouteContext, format: string): string;
     identityTokenExchangePath(ctx: RouteContext): string;
     identityTokenExchangePollPath(ctx: RouteContext): string;
     identityDeviceDcrPath(ctx: RouteContext): string;

package/dist/runtime-client-paths.js

@@ -98,6 +98,12 @@ export class RuntimeClientPaths {
     fhirR5SubscriptionPollPath(ctx, section) { return this.v1Path(ctx, section, 'org.hl7.fhir.r5', 'Subscription', '_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'); }
+    digitalTwinSearchPath(ctx, format, resourceType) { return this.v1Path(ctx, 'digitaltwin', format, resourceType, '_search'); }
+    digitalTwinSearchPollPath(ctx, format, resourceType) { return this.v1Path(ctx, 'digitaltwin', format, resourceType, '_batch-response'); }
+    digitalTwinCompositionBatchPath(ctx, format) { return this.v1Path(ctx, 'digitaltwin', format, 'Composition', '_batch'); }
+    digitalTwinCompositionPollPath(ctx, format) { return this.v1Path(ctx, 'digitaltwin', format, 'Composition', '_batch-response'); }
+    digitalTwinCommunicationBatchPath(ctx, format) { return this.v1Path(ctx, 'digitaltwin', format, 'Communication', '_batch'); }
+    digitalTwinCommunicationPollPath(ctx, format) { return this.v1Path(ctx, 'digitaltwin', format, 'Communication', '_batch-response'); }
     identityTokenExchangePath(ctx) { return buildIdentityTokenExchangePath(ctx); }
     identityTokenExchangePollPath(ctx) { return buildIdentityTokenExchangePollPath(ctx); }
     identityDeviceDcrPath(ctx) { return buildIdentityDeviceDcrPath(ctx); }

package/dist/session.d.ts

@@ -6,6 +6,7 @@ import { PersonalSdk } from './orchestration/personal-sdk.js';
 import { OrganizationControllerSdk } from './orchestration/organization-controller-sdk.js';
 import { OrganizationEmployeeSdk } from './orchestration/organization-employee-sdk.js';
 import { ProfessionalSdk } from './orchestration/professional-sdk.js';
+import { DigitalTwinSdk } from './orchestration/digital-twin-sdk.js';
 import type { RuntimeClient } from './orchestration/client-port.js';
 export type NodeCapability = Capability;
 export type NodeActorSessionContext = {
@@ -47,6 +48,8 @@ export declare class ActorSession {
     asPersonal(): PersonalSdk;
     asIndividualMember(): IndividualMemberSdk;
     asProfessional(): ProfessionalSdk;
+    /** Materializes the digital-twin facade for an organization employee or professional actor. */
+    asDigitalTwin(): DigitalTwinSdk;
     private requireClient;
 }
 /**
@@ -68,4 +71,5 @@ export declare class NodeActorSession {
     asPersonal(): PersonalSdk;
     asIndividualMember(): IndividualMemberSdk;
     asProfessional(): ProfessionalSdk;
+    asDigitalTwin(): DigitalTwinSdk;
 }

package/dist/session.js

@@ -7,6 +7,7 @@ import { PersonalSdk } from './orchestration/personal-sdk.js';
 import { OrganizationControllerSdk } from './orchestration/organization-controller-sdk.js';
 import { OrganizationEmployeeSdk } from './orchestration/organization-employee-sdk.js';
 import { ProfessionalSdk } from './orchestration/professional-sdk.js';
+import { DigitalTwinSdk } from './orchestration/digital-twin-sdk.js';
 /**
  * Preferred neutral actor session abstraction for runtime packages.
  *
@@ -61,6 +62,13 @@ export class ActorSession {
         this.assertActorKind(ActorKinds.Professional);
         return new ProfessionalSdk(this.requireClient());
     }
+    /** Materializes the digital-twin facade for an organization employee or professional actor. */
+    asDigitalTwin() {
+        if (this.actorKind !== ActorKinds.OrganizationEmployee && this.actorKind !== ActorKinds.Professional) {
+            throw new Error(`ActorSession is '${this.actorKind}' and cannot use digital-twin research operations.`);
+        }
+        return new DigitalTwinSdk(this.requireClient(), this.actorDid);
+    }
     requireClient() {
         if (!this.client) {
             throw new Error('ActorSession requires a runtime client to materialize actor facades.');
@@ -88,4 +96,5 @@ export class NodeActorSession {
     asPersonal() { return this.inner.asPersonal(); }
     asIndividualMember() { return this.inner.asIndividualMember(); }
     asProfessional() { return this.inner.asProfessional(); }
+    asDigitalTwin() { return this.inner.asDigitalTwin(); }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-sdk-node-ts",
-  "version": "2.4.4",
+  "version": "2.4.8",
   "description": "Next-generation Node runtime package for the GDC SDK family",
   "license": "Apache-2.0",
   "author": "Antifraud Services Inc.",
@@ -37,7 +37,7 @@
     "test:e2e:live-gw:clean": "bash ./scripts/run-live-gw-clean.sh"
   },
   "dependencies": {
-    "gdc-common-utils-ts": "2.5.6",
+    "gdc-common-utils-ts": "2.5.7",
     "gdc-sdk-core-ts": "~2.3.18"
   },
   "devDependencies": {