gdc-sdk-node-ts 2.7.8 → 2.9.0

package/README.md

@@ -437,6 +437,12 @@ grant/deny operation and retains the original Communication identifier/thread.
 and `GatewayActiveConsentProvider` supplies `evaluateRequestedAccess(...)` from
 the GW Consent source of truth rather than a parallel application table.
 There is no `AccessRequest` FHIR resource or `AccessRequest.*` claim family.
+The Communication itself uses the standard FHIR `notification` category;
+`permission-request` is workflow meaning carried by the attached draft Consent,
+not a custom category. See the
+[HL7 category value set](https://www.hl7.org/fhir/valueset-communication-category.html),
+[HL7 `v3-ActReason` BTG code system](http://terminology.hl7.org/CodeSystem/v3-ActReason),
+and the [IHE compound normal/break-glass Consent example](https://profiles.ihe.net/ITI/PCF/Consent-ex-consent-advanced-normal-break-glass-restricted.json.html).
 
 ## Main Flows
 
@@ -497,6 +503,29 @@ Those belong to:
 
 ## Minimal Examples
 
+### Build the individual-controller DCR actor DID
+
+The controller consumes the licensed member seat with role `RESPRSN`. A phone
+or email stored on the Individual Organization remains contact data and does
+not consume another seat. The role keeps its full type and value in protected
+data; only the value is appended to the DID.
+
+```ts
+import { buildIndividualMemberDidWebFromPrivateIdentifiers } from 'gdc-sdk-node-ts';
+
+const individualControllerDid = buildIndividualMemberDidWebFromPrivateIdentifiers({
+  providerDidWeb: 'did:web:host.example.org:health-care:organization:taxid:VATES-B00112233',
+  secureIdTypeIndividual: 'UUID',
+  privateIdValueIndividual: 'a87e5b15-aea4-4475-9c7c-40aa88354b6f',
+  secureIdTypeMember: 'EMAIL',
+  privateIdValueMember: 'controller@example.org',
+  roleType: 'http://terminology.hl7.org/CodeSystem/v3-RoleCode',
+  roleValue: 'RESPRSN',
+});
+
+// did:web:host.example.org:health-care:organization:taxid:VATES-B00112233:individual:UUID:zG9H82pae9SCXvec3D4YKqhX8bj8F1mRgzxMEdwXXonT7BWsvsUiP2u52sWQTeESpoMee:member:zG9DrMLpQW8eoCc9Ay9AFxuMGiswgJePpbUMz9svJCZ8tKjUd4xoExgCPA5jmHc6hPATJ:RESPRSN
+```
+
 ### Use shared invitation contract from Node
 
 ```ts
@@ -699,20 +728,26 @@ modules below.
 - draft/outbox helpers
 - document facade helpers
 - `cloneImportedClinicalDocumentForDemo(...)` for an explicit editable demo
-  copy owned by an authenticated profile `actorDid`; direct summary updates
-  use that same value as `sender` and the real hosted provider-tenant DID as
-  `recipient`, never a portal alias
+  copy whose stable FHIR author/attester come from the protected
+  `clinicalCreator` export; direct summary updates use profile `actorDid` only
+  as `sender` and the real hosted provider-tenant DID as `recipient`, never a
+  portal alias
 - vital-sign helpers
 
 ### Composition provenance in clinical Bundles
 
-A document Bundle keeps `Composition.author` (who created the content) separate
-from `Composition.attester` (the registered personal or professional assignment
-that submitted/attested it). For a member or professional, the protected BFF
-profile selects only `owner` or `creator`; a `RelatedPerson` or
-`PractitionerRole` may be both author and attester when that actor created the
-content. DIDComm sender and signing keys remain audit/transport identities.
-See [Clinical writes from a Node BFF](./docs/101-BFF_CLINICAL_WRITES.md) and the
+A document Bundle keeps `Composition.author` (the organization, EHR/patient
+portal or individual that supplies the document) separate from
+`Composition.attester` (the registered personal or professional assignment
+that attested its content). A `RelatedPerson` or `PractitionerRole` is an
+attester, never a shortcut for replacing the source author. The protected BFF
+profile resolves both from its registered binding. DIDComm sender and signing
+keys remain audit/transport identities.
+The BFF never configures ledger routing or supplies channel/smart-contract
+names. GW owns that decision and returns one transaction receipt with
+per-resource CID/version evidence for a successful clinical Bundle.
+See [Clinical writes from a Node BFF](./docs/101-BFF_CLINICAL_WRITES.md),
+[multi-actor IPS export](./docs/101-MULTI_ACTOR_IPS_EXPORT.md), and the
 [gateway authorship contract](https://github.com/Global-DataCare/gwtemplate-node-ts/blob/main/docs/01-OVERVIEW-AND-GUIDES/101-01.N-AUTHENTICATED-CLINICAL-AUTHOR.md).
 
 ### Node runtime client

package/dist/individual-start.d.ts

@@ -1,3 +1,5 @@
+import { SecureIdTypesIndividual } from 'gdc-common-utils-ts';
+export { buildIndividualMemberDidWebFromPrivateIdentifiers } from 'gdc-common-utils-ts';
 import type { FamilyRegistrationStatus } from 'gdc-common-utils-ts/utils/family-organization-summary';
 import type { PollOptions, SubmitAndPollResult } from './orchestration/client-port.js';
 import type { RouteContext } from './individual-onboarding.js';
@@ -77,8 +79,10 @@ export type IndividualOrganizationStartResult = {
 export type IndividualOrganizationBootstrapIdentity = {
     /** Technical UUID returned as `Bundle.data[0].resource.id`. */
     resourceId: string;
-    /** Stable UUID-byte identifier serialized as multibase base58btc. */
-    individualId: string;
+    /** Explicit governed identifier type serialized in the hosted DID path. */
+    secureIdTypeIndividual: typeof SecureIdTypesIndividual.Uuid;
+    /** SHA3-384 multihash of the UUID's canonical 16 bytes, as base58btc multibase. */
+    secureIdValueIndividual: string;
     /** Authoritative provider DID returned by GW in `Offer.offeredBy`. */
     providerDidWeb: string;
     /** Canonical child DID built beneath the exact provider DID returned by GW. */
@@ -108,4 +112,3 @@ export declare function startIndividualOrganizationWithDeps(deps: StartIndividua
  * individual suffix and never rewrites that provider lineage.
  */
 export declare function readIndividualOrganizationBootstrapIdentity(responseBody: unknown): IndividualOrganizationBootstrapIdentity | undefined;
-export {};

package/dist/individual-start.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
 import { ClaimsOfferSchemaorg, ClaimsOrganizationSchemaorg, ClaimsPersonSchemaorg, ClaimsServiceSchemaorg, } from 'gdc-common-utils-ts/constants';
-import { buildIndividualDidWeb, encodeHexToMultibase58btc, extractPrimaryClaims, readFamilyOrganizationSummaryFromResponseBody, } from 'gdc-common-utils-ts';
+import { buildIndividualDidWeb, buildSecureIdValueIndividual, extractPrimaryClaims, readFamilyOrganizationSummaryFromResponseBody, SecureIdTypesIndividual, } from 'gdc-common-utils-ts';
+export { buildIndividualMemberDidWebFromPrivateIdentifiers } from 'gdc-common-utils-ts';
 import { GwCoreLifecycleRequestType } from './constants/lifecycle.js';
 import { resolvePollOptionsFromSeconds } from './poll-options.js';
 export async function startIndividualOrganizationWithDeps(deps) {
@@ -106,18 +107,26 @@ export function readIndividualOrganizationBootstrapIdentity(responseBody) {
     const providerDidWeb = String(claims[ClaimsOfferSchemaorg.offeredBy] || '').trim();
     if (!resourceId || !providerDidWeb)
         return undefined;
-    let individualId;
+    let secureIdValueIndividual;
     try {
-        individualId = encodeHexToMultibase58btc(resourceId);
+        secureIdValueIndividual = buildSecureIdValueIndividual({
+            secureIdTypeIndividual: SecureIdTypesIndividual.Uuid,
+            privateIdValueIndividual: resourceId,
+        });
     }
     catch {
         return undefined;
     }
     return {
         resourceId,
-        individualId,
+        secureIdTypeIndividual: SecureIdTypesIndividual.Uuid,
+        secureIdValueIndividual,
         providerDidWeb,
-        subjectDid: buildIndividualDidWeb({ providerDidWeb, individualId }),
+        subjectDid: buildIndividualDidWeb({
+            providerDidWeb,
+            secureIdTypeIndividual: SecureIdTypesIndividual.Uuid,
+            secureIdValueIndividual,
+        }),
     };
 }
 function asRecord(value) {

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

@@ -515,7 +515,9 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * The attached payload must be a `Bundle.type=batch|collection`, and the
      * exact section is carried on the outer Communication. This flow is suitable
      * for vital-sign or other explicitly section-scoped updates; it does not
-     * replace a multi-section IPS document.
+     * replace a multi-section IPS document. The terminal result may include one
+     * transaction receipt with per-resource CID/version evidence. Callers never
+     * supply or configure ledger channel or smart-contract names.
      */
     updateClinicalSection(ctx: RouteContext, input: ClinicalSectionUpdateInput): Promise<SubmitAndPollResult>;
     /**
@@ -525,7 +527,9 @@ export declare class HttpRuntimeClient implements NodeRuntimeClient {
      * `entry[0]`; its `section[].entry[]` references delimit the updated data.
      * Direct callers pass the authenticated profile `actorDid` as `sender` and
      * the real hosted provider-tenant DID as `recipient`. A stable multibase URN
-     * or portal DID/alias is never the authenticated clinical actor.
+     * or portal DID/alias is never the authenticated clinical actor. GW owns all
+     * ledger routing; callers receive evidence but never select a channel or
+     * smart contract.
      */
     updateClinicalSummary(ctx: RouteContext, input: ClinicalSummaryUpdateInput): Promise<SubmitAndPollResult>;
     /**

package/dist/node-runtime-client.js

@@ -1010,7 +1010,9 @@ export class HttpRuntimeClient {
      * The attached payload must be a `Bundle.type=batch|collection`, and the
      * exact section is carried on the outer Communication. This flow is suitable
      * for vital-sign or other explicitly section-scoped updates; it does not
-     * replace a multi-section IPS document.
+     * replace a multi-section IPS document. The terminal result may include one
+     * transaction receipt with per-resource CID/version evidence. Callers never
+     * supply or configure ledger channel or smart-contract names.
      */
     async updateClinicalSection(ctx, input) {
         return this.ingestCommunicationAndUpdateIndex(ctx, buildClinicalSectionUpdateIngestion(input));
@@ -1022,7 +1024,9 @@ export class HttpRuntimeClient {
      * `entry[0]`; its `section[].entry[]` references delimit the updated data.
      * Direct callers pass the authenticated profile `actorDid` as `sender` and
      * the real hosted provider-tenant DID as `recipient`. A stable multibase URN
-     * or portal DID/alias is never the authenticated clinical actor.
+     * or portal DID/alias is never the authenticated clinical actor. GW owns all
+     * ledger routing; callers receive evidence but never select a channel or
+     * smart contract.
      */
     async updateClinicalSummary(ctx, input) {
         return this.ingestCommunicationAndUpdateIndex(ctx, buildClinicalSummaryUpdateIngestion(input));

package/dist/resource-operations.d.ts

@@ -307,11 +307,12 @@ type ClinicalUpdateRuntimeOptions = Readonly<{
  * Updates exactly one clinical section through a scoped batch/collection.
  * A `Bundle.type = batch` may mix typed create, update, and delete entries.
  * A delete targets `ResourceType/id`, carries no resource body, and may use
- * `ifMatch` for optimistic concurrency. GW authorizes it against the creator
- * DID plus the caller's linked verified login identity; contact identifiers
- * are never written into the clinical resource.
+ * `ifMatch` for optimistic concurrency. GW authorizes it against the stored
+ * attester assignment plus the caller's registered clinical creator binding;
+ * contact identifiers are never written into the clinical resource.
  * An externally authored `urn:*` may be preserved on first import, but a local
- * controller cannot subsequently update or delete that source-authored fact.
+ * local actor cannot subsequently update or delete that source-authored fact
+ * unless an explicit successor policy applies.
  */
 export type ClinicalSectionUpdateInput = ClinicalSectionUpdateCommunicationInput & ClinicalUpdateRuntimeOptions;
 /**
@@ -319,8 +320,9 @@ export type ClinicalSectionUpdateInput = ClinicalSectionUpdateCommunicationInput
  *
  * For the direct call, `sender` is the authenticated profile's operational
  * `actorDid`, and `recipient` is the real provider-tenant DID inside the host
- * that accommodates it. Neither value is a portal alias. When the document is
- * an editable demo clone, its `Composition.author` is that same `actorDid`.
+ * that accommodates it. Neither value is a portal alias. An editable demo
+ * clone obtains its stable FHIR author/attester from the protected
+ * `clinicalCreator` export, never from that `actorDid`.
  */
 export type ClinicalSummaryUpdateInput = ClinicalUpdateCommunicationInput & ClinicalUpdateRuntimeOptions;
 export declare function buildClinicalSectionUpdateIngestion(input: ClinicalSectionUpdateInput): CommunicationIngestionInput;
@@ -407,7 +409,12 @@ export type CommunicationParticipantRuntimeSearchInput = {
 };
 /** Subject/requester filters for canonical permission-request Communications. */
 export type ProfessionalAccessRequestSearchInput = CommunicationParticipantRuntimeSearchInput;
-/** Restricts a Communication participant search to permission requests. */
+/**
+ * Restricts a Communication participant search to standard notifications.
+ * A permission request is identified by its attached draft Consent contract;
+ * it is not an invented fifth FHIR category. See
+ * https://www.hl7.org/fhir/valueset-communication-category.html
+ */
 export declare function buildProfessionalAccessRequestSearchInput(input: ProfessionalAccessRequestSearchInput): CommunicationParticipantRuntimeSearchInput;
 export type ClinicalDateRange = DateRange;
 export type ClinicalBundleSearchInput = Omit<BundleSearchQuery, 'section' | 'searchParams'> & {

package/dist/resource-operations.js

@@ -6,6 +6,7 @@ import { CommunicationClaim } from 'gdc-common-utils-ts/models/interoperable-cla
 import { BundleEditor, buildCommunicationParticipantSearchBundle, buildBlockchainArtifactDocumentReference, BundleQuery, createInteroperableResourceOperationEditor, IndividualOrganizationLifecycleEditor, LicenseOfferSearchEditor, LicenseOrderSearchEditor, InteroperableLifecycleStatuses, LicenseListSearchEditor, buildLicenseIssueEntry, buildLicensePurchaseEntry, } from 'gdc-common-utils-ts';
 import { EmployeeBundleOperations, EmployeeResourceTypes, } from 'gdc-common-utils-ts/utils/employee';
 import { DeviceAppTypes, DeviceUserClasses } from 'gdc-common-utils-ts/constants/device';
+import { CommunicationCategoryCodes } from 'gdc-common-utils-ts/constants/communication';
 import { addFhirResourceToCommunication, createCommunicationResource, buildClinicalSummaryCommunicationJob, buildPermissionRequestCommunication, createClinicalSectionUpdateOutboxJob, createClinicalSummaryUpdateOutboxJob, readClinicalSummaryOperationResult, TransportProfiles, } from 'gdc-sdk-core-ts';
 import { GwCoreLifecycleRequestMethod, GwCoreLifecycleRequestType, GwCoreLifecycleTodo, } from './constants/lifecycle.js';
 import { buildEmployeeSearchBundle, ConsentClaims, } from 'gdc-sdk-core-ts';
@@ -27,13 +28,18 @@ export function buildClinicalSummaryUpdateIngestion(input) {
         pollOptions: input.pollOptions,
     };
 }
-/** Restricts a Communication participant search to permission requests. */
+/**
+ * Restricts a Communication participant search to standard notifications.
+ * A permission request is identified by its attached draft Consent contract;
+ * it is not an invented fifth FHIR category. See
+ * https://www.hl7.org/fhir/valueset-communication-category.html
+ */
 export function buildProfessionalAccessRequestSearchInput(input) {
     return {
         ...input,
         searchParams: {
             ...input.searchParams,
-            [CommunicationClaim.Category]: 'permission-request',
+            [CommunicationClaim.Category]: CommunicationCategoryCodes.Notification.attributeValue,
         },
     };
 }
@@ -520,7 +526,7 @@ export async function requestProfessionalAccessWithDeps(routeCtx, input, deps) {
     });
     const communicationClaims = {
         ...communication.claims,
-        [CommunicationClaim.Category]: 'permission-request',
+        [CommunicationClaim.Category]: CommunicationCategoryCodes.Notification.attributeValue,
         [CommunicationClaim.NoteText]: communication.text,
     };
     const persistedCommunication = { ...communication, claims: communicationClaims };

package/dist/server-profile-session.d.ts

@@ -343,7 +343,11 @@ export declare class ServerProfileSessionManager {
     exportClinicalCreatorIps(input: Readonly<{
         ownerId: string;
         profileId: string;
-        /** Closed BFF choice: content owner or authenticated registered creator. */
+        /**
+         * Deprecated compatibility choice. The high-level clone/section helpers
+         * derive the final professional or individual-member author boundary
+         * from the returned protected binding.
+         */
         sourceAuthor?: ClinicalSourceAuthorSelection;
     }>): Promise<ClinicalCreatorIpsExport>;
     enroll(input: ServerProfileEnrollmentInput): Promise<ServerProfileRecord>;
@@ -437,10 +441,13 @@ export declare class ServerProfileSessionManager {
     private now;
 }
 /**
- * Exports the stable FHIR IPS creator attached to a server profile. The
- * optional closed selection determines whether the owner or the authenticated
- * registered creator authored the content. DIDComm sender and signing keys
- * remain transport/audit evidence and never become FHIR provenance.
+ * Exports the stable FHIR IPS source author and attester attached to a server
+ * profile. The returned protected binding lets high-level helpers use the
+ * stable legal organization URN plus PractitionerRole for professionals, or
+ * one RelatedPerson urn:uuid as both author and attester for individual
+ * members/controllers. The optional selection remains only for backwards
+ * compatibility. DIDComm sender and signing keys remain transport/audit
+ * evidence and never become FHIR provenance.
  */
 export declare function exportServerProfileClinicalCreatorIps(profile: ServerProfileRecord, options?: Readonly<{
     sourceAuthor?: ClinicalSourceAuthorSelection;

package/dist/server-profile-session.js

@@ -829,10 +829,13 @@ function requireBase64UrlSeed32(seed) {
     }
 }
 /**
- * Exports the stable FHIR IPS creator attached to a server profile. The
- * optional closed selection determines whether the owner or the authenticated
- * registered creator authored the content. DIDComm sender and signing keys
- * remain transport/audit evidence and never become FHIR provenance.
+ * Exports the stable FHIR IPS source author and attester attached to a server
+ * profile. The returned protected binding lets high-level helpers use the
+ * stable legal organization URN plus PractitionerRole for professionals, or
+ * one RelatedPerson urn:uuid as both author and attester for individual
+ * members/controllers. The optional selection remains only for backwards
+ * compatibility. DIDComm sender and signing keys remain transport/audit
+ * evidence and never become FHIR provenance.
  */
 export function exportServerProfileClinicalCreatorIps(profile, options = {}) {
     if (!profile.clinicalCreatorBinding) {

package/dist/session.d.ts

@@ -8,7 +8,7 @@ import { OrganizationEmployeeSdk } from './orchestration/organization-employee-s
 import { ProfessionalSdk } from './orchestration/professional-sdk.js';
 import { DigitalTwinSdk } from './orchestration/digital-twin-sdk.js';
 import type { RuntimeClient } from './orchestration/client-port.js';
-import { type DemoClinicalDocumentResourceIdContext } from 'gdc-sdk-core-ts';
+import { type ClinicalCreatorIpsExport, type DemoClinicalDocumentResourceIdContext } from 'gdc-sdk-core-ts';
 export type NodeCapability = Capability;
 export type NodeActorSessionContext = {
     actorKind: ActorKind;
@@ -24,6 +24,8 @@ export type NodeActorSessionContext = {
  */
 export type ActorSessionContext = NodeActorSessionContext;
 export type DemoClinicalDocumentCloneOptions = Readonly<{
+    /** Protected profile projection; supplies stable FHIR author and attester. */
+    clinicalCreator?: ClinicalCreatorIpsExport;
     createResourceId?: (context: DemoClinicalDocumentResourceIdContext) => string;
 }>;
 /**
@@ -56,9 +58,9 @@ export declare class ActorSession {
     /** Materializes the digital-twin facade for an organization employee or professional actor. */
     asDigitalTwin(): DigitalTwinSdk;
     /**
-     * Creates an editable demo copy whose `Composition.author` is this
-     * authenticated profile's operational `actorDid`. The actor is never taken
-     * from a stable multibase URN or a DID/alias supplied by a portal.
+     * Creates an editable demo copy whose stable FHIR author/attester come from
+     * `options.clinicalCreator`. This session's operational `actorDid` remains a
+     * compatibility fallback and belongs in the later write's sender field.
      */
     cloneImportedClinicalDocumentForDemo(bundle: Record<string, unknown>, options?: DemoClinicalDocumentCloneOptions): Record<string, any>;
     private requireClient;

package/dist/session.js

@@ -71,9 +71,9 @@ export class ActorSession {
         return new DigitalTwinSdk(this.requireClient(), this.actorDid);
     }
     /**
-     * Creates an editable demo copy whose `Composition.author` is this
-     * authenticated profile's operational `actorDid`. The actor is never taken
-     * from a stable multibase URN or a DID/alias supplied by a portal.
+     * Creates an editable demo copy whose stable FHIR author/attester come from
+     * `options.clinicalCreator`. This session's operational `actorDid` remains a
+     * compatibility fallback and belongs in the later write's sender field.
      */
     cloneImportedClinicalDocumentForDemo(bundle, options = {}) {
         const actorDid = String(this.actorDid || '').trim();

package/package.json

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