gdc-common-utils-ts 1.24.0 → 1.24.3

package/dist/examples/ica-activation-proof.d.ts

@@ -24,6 +24,13 @@ export declare const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID: "urn:ietf:params:oau
 export declare const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID: "host:node-operator-es";
 export declare const EXAMPLE_ORGANIZATION_TAX_ID: "ESB00112233";
 export declare const EXAMPLE_REPRESENTATIVE_ROLE_CODE: "RESPRSN";
+export declare const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_CODE: "1120";
+export declare const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER: "urn:ilo:ilostat:isco-08:1120";
+export declare const EXAMPLE_REPRESENTATIVE_IDENTIFIER: "IDCES-99999999R";
+export declare const EXAMPLE_REPRESENTATIVE_EMAIL: "legal.rep@example.org";
+export declare const EXAMPLE_REPRESENTATIVE_SUBJECT_URN: "urn:person:identifier:IDCES-99999999R";
+export declare const EXAMPLE_REPRESENTATIVE_SAME_AS: "urn:multibase:zControllerHash";
+export declare const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_DID: "did:web:provider.example:health-care:organization:taxid:VATES-ESB00112233";
 export declare const EXAMPLE_ORGANIZATION_ID: "ESB00112233";
 export declare const EXAMPLE_ACTIVATION_AUTHORIZED_CATEGORY: "health-care";
 export declare const EXAMPLE_ACTIVATION_AUTHORIZED_SERVICE_TYPE: "organization/Composition.cruds";
@@ -45,18 +52,18 @@ export declare const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL: Rea
     '@context': string[];
     type: ("VerifiableCredential" | "LegalRepresentativeCredential")[];
     credentialSubject: {
-        id: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
+        id: "urn:person:identifier:IDCES-99999999R";
         memberOf: {
             taxID: "ESB00112233";
         };
         hasOccupation: {
-            identifier: {
-                value: "RESPRSN";
-            };
+            identifier: "urn:ilo:ilostat:isco-08:1120";
         };
         hasCredential: {
             material: "urn:ietf:params:oauth:jwk-thumbprint:sha-256:Q0ZfM0V4YW1wbGVUaHVtYnByaW50X2Jhc2U2NHVybA";
         };
+        identifier: "IDCES-99999999R";
+        sameAs: "urn:multibase:zControllerHash";
     };
 }>;
 export declare const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD: Readonly<{

package/dist/examples/ica-activation-proof.js

@@ -30,6 +30,13 @@ export const EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID = `${UrnPrefixes.JwkThumbprin
 export const EXAMPLE_PRESENTATION_AUDIENCE_HOST_ID = 'host:node-operator-es';
 export const EXAMPLE_ORGANIZATION_TAX_ID = 'ESB00112233';
 export const EXAMPLE_REPRESENTATIVE_ROLE_CODE = 'RESPRSN';
+export const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_CODE = '1120';
+export const EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER = 'urn:ilo:ilostat:isco-08:1120';
+export const EXAMPLE_REPRESENTATIVE_IDENTIFIER = 'IDCES-99999999R';
+export const EXAMPLE_REPRESENTATIVE_EMAIL = 'legal.rep@example.org';
+export const EXAMPLE_REPRESENTATIVE_SUBJECT_URN = `urn:person:identifier:${EXAMPLE_REPRESENTATIVE_IDENTIFIER}`;
+export const EXAMPLE_REPRESENTATIVE_SAME_AS = 'urn:multibase:zControllerHash';
+export const EXAMPLE_ORG_ACTIVATION_ORGANIZATION_DID = 'did:web:provider.example:health-care:organization:taxid:VATES-ESB00112233';
 export const EXAMPLE_ORGANIZATION_ID = EXAMPLE_ORGANIZATION_TAX_ID;
 export const EXAMPLE_ACTIVATION_AUTHORIZED_CATEGORY = DataspaceSectors.HealthCare;
 export const EXAMPLE_ACTIVATION_AUTHORIZED_SERVICE_TYPE = ServiceCapability.IndexProvider;
@@ -57,18 +64,18 @@ export const EXAMPLE_ORG_ACTIVATION_LEGAL_REPRESENTATIVE_CREDENTIAL = Object.fre
         ActivationCredentialTypes.LegalRepresentativeCredential,
     ],
     credentialSubject: {
-        id: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
+        id: EXAMPLE_REPRESENTATIVE_SUBJECT_URN,
         memberOf: {
             taxID: EXAMPLE_ORGANIZATION_TAX_ID,
         },
         hasOccupation: {
-            identifier: {
-                value: EXAMPLE_REPRESENTATIVE_ROLE_CODE,
-            },
+            identifier: EXAMPLE_REPRESENTATIVE_ISCO08_ROLE_IDENTIFIER,
         },
         hasCredential: {
             material: EXAMPLE_ORG_CONTROLLER_SIGNING_KEY_ID,
         },
+        identifier: EXAMPLE_REPRESENTATIVE_IDENTIFIER,
+        sameAs: EXAMPLE_REPRESENTATIVE_SAME_AS,
     },
 });
 export const EXAMPLE_ORG_ACTIVATION_PROOF_VP_PAYLOAD = Object.freeze({

package/dist/examples/shared.d.ts

@@ -187,6 +187,15 @@ export declare const EXAMPLE_CONSENT_OPERATION_THREAD_ID: "thread-consent-exampl
 export declare const EXAMPLE_CONSENT_PERIOD_START: "2026-05-20T00:00:00Z";
 export declare const EXAMPLE_COMMUNICATION_UUID: "urn:uuid:communication-example-001";
 export declare const EXAMPLE_COMMUNICATION_IDENTIFIER: "urn:uuid:communication-example-001";
+export declare const EXAMPLE_COMMUNICATION_THREAD_ID: "thread-communication-example-001";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID: string;
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID: "did:web:provider.example.org";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID: string;
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER: "family.owner@example.org";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT: "nurse.oncall@example.org";
+export declare const EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT: "+34600111222";
+export declare const EXAMPLE_COMMUNICATION_SEARCH_CATEGORY: string;
+export declare const EXAMPLE_COMMUNICATION_SEARCH_TOPIC: "care-plan-follow-up";
 export declare const EXAMPLE_IPS_BUNDLE_NOTE_TEXT: "IPS ingestion request";
 export declare const EXAMPLE_CONTENT_TYPE_APPLICATION_JSON: "application/json";
 export declare const EXAMPLE_CONTENT_TYPE_FHIR_JSON: "application/fhir+json";

package/dist/examples/shared.js

@@ -226,6 +226,15 @@ export const EXAMPLE_CONSENT_OPERATION_THREAD_ID = 'thread-consent-example-001';
 export const EXAMPLE_CONSENT_PERIOD_START = '2026-05-20T00:00:00Z';
 export const EXAMPLE_COMMUNICATION_UUID = 'urn:uuid:communication-example-001';
 export const EXAMPLE_COMMUNICATION_IDENTIFIER = EXAMPLE_COMMUNICATION_UUID;
+export const EXAMPLE_COMMUNICATION_THREAD_ID = 'thread-communication-example-001';
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID = EXAMPLE_SUBJECT_DID;
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID = EXAMPLE_TENANT_SERVICE_DID;
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID = EXAMPLE_RELATED_PERSON_MEMBER_DID;
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER = 'family.owner@example.org';
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT = 'nurse.oncall@example.org';
+export const EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT = '+34600111222';
+export const EXAMPLE_COMMUNICATION_SEARCH_CATEGORY = CommunicationCategoryCodes.Notification.attributeValue;
+export const EXAMPLE_COMMUNICATION_SEARCH_TOPIC = 'care-plan-follow-up';
 export const EXAMPLE_IPS_BUNDLE_NOTE_TEXT = 'IPS ingestion request';
 export const EXAMPLE_CONTENT_TYPE_APPLICATION_JSON = 'application/json';
 export const EXAMPLE_CONTENT_TYPE_FHIR_JSON = 'application/fhir+json';

package/dist/models/confidential-storage.d.ts

@@ -39,6 +39,11 @@ export interface AuditInfo {
     updated?: string;
     /** True if removed/deactivated (deactivation time is typically `updated`). */
     deactivated?: boolean;
+    /**
+     * Optional lightweight lifecycle disposition copied outside encrypted
+     * content, for example `purged`.
+     */
+    disposition?: string;
     /** Name of the channel/network where the data is audited/anchored. */
     channel?: string;
     /** Base58/Base64Url transaction identifier, depending on the attestation layer. */
@@ -46,6 +51,34 @@ export interface AuditInfo {
     /** Transaction timestamp (ISO 8601). */
     txTime?: string;
 }
+/**
+ * Public runtime projection kept outside encrypted `content`.
+ *
+ * These values are not the canonical business payload. They are copied or
+ * generated from the protected content so runtime flows can answer lightweight
+ * queries without hydrating the confidential JWE blob.
+ *
+ * Rules:
+ * - Keep this object strictly minimal.
+ * - Only place data here when it is intentionally public or deployment-safe.
+ * - Never treat these fields as the source of truth if the encrypted content
+ *   carries the canonical value.
+ */
+export interface PublicInfo {
+    /**
+     * Optional lightweight role or technical marker copied outside encrypted
+     * content for routing, gating, or lifecycle inspection.
+     *
+     * This is a convenience projection for lookup. The canonical role still
+     * belongs to the protected business payload and/or indexed attributes.
+     *
+     * Example:
+     * - hosting may copy a synthetic bootstrap-controller marker here so tenant
+     *   lifecycle scans can ignore that technical employee without hydrating the
+     *   confidential JWE payload.
+     */
+    role?: string;
+}
 /**
  * Defines the structure of an attribute to be indexed for blind, searchable queries.
  * @see https://identity.foundation/confidential-storage/#indexed-attributes
@@ -157,6 +190,19 @@ export interface ConfidentialStorageDoc {
     tag?: MetaTagCoding[];
     /** Policy-dependent research/analytics metadata, kept outside encrypted `content`. */
     research?: ResearchInfo;
+    /**
+     * Optional public runtime projection copied or generated for lightweight
+     * reads outside encrypted `content`.
+     *
+     * This object is intended for lookup, routing, and operational gating.
+     * It must not become a second canonical payload.
+     *
+     * Typical usage:
+     * - copy a small public or deployment-safe value out of protected content
+     * - or generate a technical marker needed for lightweight runtime scans
+     * - never treat this object as the source of truth for business semantics
+     */
+    public?: PublicInfo;
 }
 /**
  * Represents a document whose sensitive content has been decrypted and is held

package/dist/utils/activation-policy.d.ts

@@ -1,4 +1,4 @@
-export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_DID_WEB' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'REPRESENTATIVE_TAXID_MISMATCH';
+export type ActivationRepresentativePolicyErrorCode = 'MISSING_REPRESENTATIVE_SUBJECT_ID' | 'MISSING_REPRESENTATIVE_ROLE_RESPRSN' | 'MISSING_REPRESENTATIVE_CREDENTIAL_BINDING' | 'REPRESENTATIVE_TAXID_MISMATCH';
 export type ActivationServiceAuthorizationPolicyErrorCode = 'MISSING_ORGANIZATION_SERVICE_CATEGORY' | 'MISSING_ORGANIZATION_SERVICE_TYPE' | 'UNAUTHORIZED_ORGANIZATION_SERVICE_CATEGORY' | 'UNAUTHORIZED_ORGANIZATION_SERVICE_TYPE';
 export type ActivationRepresentativePolicyError = {
     code: ActivationRepresentativePolicyErrorCode;
@@ -56,12 +56,37 @@ export declare function hasRoleCode(roleCode: string | undefined, requiredCode?:
  * @param representativeCredential Candidate representative credential.
  */
 export declare function extractRepresentativeCredentialBinding(representativeCredential: unknown): string | undefined;
+/**
+ * Extracts the representative subject identifier from `credentialSubject.id`.
+ *
+ * ICA currently models the natural person with a stable person URN while the
+ * controller/bootstrap continuity is carried in sibling claims such as
+ * `sameAs` and `hasCredential`. Activation policy must therefore accept the
+ * canonical person URN form and must not require a representative `did:web`.
+ *
+ * @param representativeCredential Candidate representative credential.
+ */
+export declare function extractRepresentativeSubjectId(representativeCredential: unknown): string | undefined;
 /**
  * Extracts a `did:web:` identifier from a VC-like credential.
  *
  * @param credential Candidate credential.
  */
 export declare function extractDidWebFromCredential(credential: unknown): string | undefined;
+/**
+ * Checks whether the representative role expresses the activation-controller
+ * semantics accepted by GW.
+ *
+ * Compatibility rules:
+ * - historical GW payloads may still use HL7/FHIR `RESPRSN`
+ * - current ICA person credentials may encode the legal representative role as
+ *   ISCO-08 `1120`, either tokenized (`ISCO-08|1120`) or as the canonical
+ *   ILO URN (`urn:ilo:ilostat:isco-08:1120`)
+ *
+ * @param roleCode Candidate role token extracted from the credential.
+ * @param requiredCode Required GW compatibility code, defaults to `RESPRSN`.
+ */
+export declare function hasActivationRepresentativeRole(roleCode: string | undefined, requiredCode?: string): boolean;
 /**
  * Extracts the categories authorized by an ICA-issued organization credential.
  *

package/dist/utils/activation-policy.js

@@ -141,6 +141,24 @@ function extractCredentialBindingValue(value) {
         || '').trim();
     return candidate || undefined;
 }
+/**
+ * Extracts the representative subject identifier from `credentialSubject.id`.
+ *
+ * ICA currently models the natural person with a stable person URN while the
+ * controller/bootstrap continuity is carried in sibling claims such as
+ * `sameAs` and `hasCredential`. Activation policy must therefore accept the
+ * canonical person URN form and must not require a representative `did:web`.
+ *
+ * @param representativeCredential Candidate representative credential.
+ */
+export function extractRepresentativeSubjectId(representativeCredential) {
+    const obj = asObject(representativeCredential);
+    if (!obj)
+        return undefined;
+    const subject = extractCredentialSubject(obj);
+    const subjectId = String(subject?.id || '').trim();
+    return subjectId || undefined;
+}
 /**
  * Extracts a `did:web:` identifier from a VC-like credential.
  *
@@ -154,6 +172,27 @@ export function extractDidWebFromCredential(credential) {
     const didCandidate = String(subject?.id || obj.id || '').trim();
     return didCandidate.startsWith('did:web:') ? didCandidate : undefined;
 }
+/**
+ * Checks whether the representative role expresses the activation-controller
+ * semantics accepted by GW.
+ *
+ * Compatibility rules:
+ * - historical GW payloads may still use HL7/FHIR `RESPRSN`
+ * - current ICA person credentials may encode the legal representative role as
+ *   ISCO-08 `1120`, either tokenized (`ISCO-08|1120`) or as the canonical
+ *   ILO URN (`urn:ilo:ilostat:isco-08:1120`)
+ *
+ * @param roleCode Candidate role token extracted from the credential.
+ * @param requiredCode Required GW compatibility code, defaults to `RESPRSN`.
+ */
+export function hasActivationRepresentativeRole(roleCode, requiredCode = 'RESPRSN') {
+    if (hasRoleCode(roleCode, requiredCode))
+        return true;
+    const normalized = String(roleCode || '').trim().toUpperCase();
+    if (!normalized)
+        return false;
+    return /(?:^|[|:])1120$/.test(normalized);
+}
 /**
  * Extracts the categories authorized by an ICA-issued organization credential.
  *
@@ -273,13 +312,13 @@ export function isMemberDidWebUnderOwner(memberDidWeb, ownerDidWeb) {
  */
 export function validateActivationRepresentativePolicy(input) {
     const errors = [];
-    const representativeDid = input.representativeCredential
-        ? extractDidWebFromCredential(input.representativeCredential)
+    const representativeSubjectId = input.representativeCredential
+        ? extractRepresentativeSubjectId(input.representativeCredential)
         : undefined;
-    if (input.representativeCredential && !representativeDid) {
+    if (input.representativeCredential && !representativeSubjectId) {
         errors.push({
-            code: 'MISSING_REPRESENTATIVE_DID_WEB',
-            message: 'ICA-issued representative credential is missing credentialSubject.id did:web.',
+            code: 'MISSING_REPRESENTATIVE_SUBJECT_ID',
+            message: 'ICA-issued representative credential is missing credentialSubject.id.',
         });
     }
     if (!input.representativeCredential)
@@ -293,10 +332,10 @@ export function validateActivationRepresentativePolicy(input) {
         });
     }
     const roleCode = extractRepresentativeRoleCode(input.representativeCredential);
-    if (!hasRoleCode(roleCode, input.requiredRoleCode || 'RESPRSN')) {
+    if (!hasActivationRepresentativeRole(roleCode, input.requiredRoleCode || 'RESPRSN')) {
         errors.push({
             code: 'MISSING_REPRESENTATIVE_ROLE_RESPRSN',
-            message: 'ICA-issued representative credential must include Responsible Party role (RESPRSN) in credentialSubject.hasOccupation.',
+            message: 'ICA-issued representative credential must include legal representative role semantics (RESPRSN or ISCO-08 1120) in credentialSubject.hasOccupation.',
         });
     }
     const binding = extractRepresentativeCredentialBinding(input.representativeCredential);

package/dist/utils/activation-request.d.ts

@@ -22,7 +22,18 @@ export interface BuildOrganizationActivationRequestInput {
 export interface BuildControllerBindingInputInput {
     /** Public DID to publish or bind for the controller/person. */
     did?: string;
-    /** Additional public alias such as `mailto:`. */
+    /**
+     * Additional public alias for the controller/person.
+     *
+     * Canonical examples:
+     * - `urn:multibase:z...` for an email-derived ICA/GW binding
+     * - `tel:+34600111222` for a phone identifier
+     * - `did:web:...` or another stable public identifier
+     *
+     * Do not use `mailto:` when the source value is an email for ICA/GW
+     * interoperability. Start from the plain email and normalize it first with
+     * `normalizeSameAsHash(...)`.
+     */
     sameAs?: string;
     /** Primary controller signing key. */
     publicSignKey?: Record<string, unknown>;
@@ -54,6 +65,14 @@ export interface BuildOrganizationBindingInputInput {
  *
  * so the caller does not have to manually shape `controller.publicKeyJwk` and
  * `controller.jwks`.
+ *
+ * ICA/GW interoperability note:
+ * - callers that start from a raw email should first normalize it with
+ *   `normalizeSameAsHash(...)` before assigning `sameAs`
+ * - keep the raw email separately in activation claims when GW still needs it
+ *   for internal admin/bootstrap records
+ * - do not send `mailto:` as the canonical controller alias when the binding
+ *   source is an email address
  */
 export declare function buildControllerBindingInput(input: BuildControllerBindingInputInput): ControllerBindingInput;
 /**

package/dist/utils/activation-request.js

@@ -23,6 +23,14 @@ function normalizeJwkSet(publicKeys) {
  *
  * so the caller does not have to manually shape `controller.publicKeyJwk` and
  * `controller.jwks`.
+ *
+ * ICA/GW interoperability note:
+ * - callers that start from a raw email should first normalize it with
+ *   `normalizeSameAsHash(...)` before assigning `sameAs`
+ * - keep the raw email separately in activation claims when GW still needs it
+ *   for internal admin/bootstrap records
+ * - do not send `mailto:` as the canonical controller alias when the binding
+ *   source is an email address
  */
 export function buildControllerBindingInput(input) {
     const jwks = normalizeJwkSet(input.publicKeys);

package/dist/utils/communication-participant-search-test-data.d.ts

@@ -0,0 +1,17 @@
+import type { CommunicationParticipantProjection, CommunicationParticipantSearchInput } from './communication-participant-search';
+/**
+ * Shared communication-participant search input fixture reused across GW/SDK
+ * tests.
+ */
+export declare function buildExampleCommunicationParticipantSearchInput(overrides?: Partial<CommunicationParticipantSearchInput>): CommunicationParticipantSearchInput;
+/**
+ * Shared stored projection fixture that mirrors the shape persisted by GW
+ * communication-channel projections.
+ */
+export declare function buildExampleCommunicationParticipantProjection(overrides?: Partial<CommunicationParticipantProjection & {
+    id?: string;
+    thid?: string;
+}>): CommunicationParticipantProjection & {
+    id: string;
+    thid: string;
+};

package/dist/utils/communication-participant-search-test-data.js

@@ -0,0 +1,39 @@
+import { EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT, EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER, EXAMPLE_COMMUNICATION_SEARCH_CATEGORY, EXAMPLE_COMMUNICATION_SEARCH_TOPIC, EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID, EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID, EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT, EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID, EXAMPLE_COMMUNICATION_THREAD_ID, } from '../examples/shared.js';
+import { CommunicationClaim } from '../models/interoperable-claims/communication-claims.js';
+/**
+ * Shared communication-participant search input fixture reused across GW/SDK
+ * tests.
+ */
+export function buildExampleCommunicationParticipantSearchInput(overrides = {}) {
+    return {
+        subject: EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID,
+        userActorId: [EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID, EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_USER],
+        targetActorId: [EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT, EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT],
+        searchParams: {
+            [CommunicationClaim.Category]: EXAMPLE_COMMUNICATION_SEARCH_CATEGORY,
+            [CommunicationClaim.Topic]: EXAMPLE_COMMUNICATION_SEARCH_TOPIC,
+        },
+        ...overrides,
+    };
+}
+/**
+ * Shared stored projection fixture that mirrors the shape persisted by GW
+ * communication-channel projections.
+ */
+export function buildExampleCommunicationParticipantProjection(overrides = {}) {
+    return {
+        id: 'communication-participant-record-001',
+        thid: EXAMPLE_COMMUNICATION_THREAD_ID,
+        subject: EXAMPLE_COMMUNICATION_PARTICIPANT_SEARCH_SUBJECT_DID,
+        sender: EXAMPLE_COMMUNICATION_PARTICIPANT_SENDER_DID,
+        sent: '2026-06-15T10:00:00Z',
+        category: EXAMPLE_COMMUNICATION_SEARCH_CATEGORY,
+        topic: EXAMPLE_COMMUNICATION_SEARCH_TOPIC,
+        recipients: [
+            EXAMPLE_COMMUNICATION_PARTICIPANT_USER_DID,
+            EXAMPLE_COMMUNICATION_PARTICIPANT_EMAIL_RECIPIENT,
+            EXAMPLE_COMMUNICATION_PARTICIPANT_TEL_RECIPIENT,
+        ],
+        ...overrides,
+    };
+}

package/dist/utils/communication-participant-search.d.ts

@@ -0,0 +1,108 @@
+import { buildSearchBundle, type FhirParametersResource, type SearchParameterPrimitive } from './fhir-search.js';
+/**
+ * Canonical participant-token prefixes used by communication search helpers.
+ */
+export declare const CommunicationParticipantPrefixes: Readonly<{
+    readonly Did: "did:";
+    readonly Email: "email:";
+    readonly Mailto: "mailto:";
+    readonly Tel: "tel:";
+    readonly Phone: "phone:";
+    readonly Wildcard: "*";
+}>;
+/**
+ * Canonical parameter names supported by `Communication/_search`.
+ */
+export declare const CommunicationParticipantSearchParameterNames: Readonly<{
+    readonly Subject: "subject";
+    readonly Actor: "actor";
+    readonly Sender: "sender";
+    readonly Recipient: "recipient";
+    readonly User: "user";
+    readonly Target: "target";
+    readonly PeriodStart: "period-start";
+    readonly PeriodEnd: "period-end";
+    readonly Page: "page";
+    readonly Count: "count";
+}>;
+/**
+ * Backward-compatible aliases still accepted while callers migrate to the
+ * canonical control names.
+ */
+export declare const CommunicationParticipantSearchParameterAliases: Readonly<{
+    readonly SentFrom: "sent-from";
+    readonly SentTo: "sent-to";
+}>;
+/**
+ * Indexed-attribute names used by communication projections.
+ */
+export declare const CommunicationParticipantIndexNames: Readonly<{
+    readonly Subject: "Communication.subject";
+    readonly Participant: "Communication.participant-token";
+    readonly Sender: "Communication.sender-token";
+    readonly Recipient: "Communication.recipient-token";
+}>;
+export type CommunicationParticipantTokenInput = string | readonly string[] | undefined | null;
+export type CommunicationParticipantSearchInput = {
+    /**
+     * Canonical claims-like search parameters keyed by reusable claim constants
+     * such as `CommunicationClaim.Sender`, `CommunicationClaim.Recipient`,
+     * `CommunicationClaim.Category`, or `CommunicationClaim.Topic`.
+     */
+    searchParams?: Readonly<Record<string, SearchParameterPrimitive | undefined>>;
+    subject?: CommunicationParticipantTokenInput;
+    actorId?: CommunicationParticipantTokenInput;
+    senderActorId?: CommunicationParticipantTokenInput;
+    recipientActorId?: CommunicationParticipantTokenInput;
+    userActorId?: CommunicationParticipantTokenInput;
+    targetActorId?: CommunicationParticipantTokenInput;
+    periodStart?: string;
+    periodEnd?: string;
+    sentFrom?: string;
+    sentTo?: string;
+    page?: number;
+    count?: number;
+};
+export type CommunicationParticipantSearchCriteria = {
+    subjectActorIds: string[];
+    anySubject: boolean;
+    actorIds: string[];
+    anyActor: boolean;
+    senderActorIds: string[];
+    anySender: boolean;
+    recipientActorIds: string[];
+    anyRecipient: boolean;
+    userActorIds: string[];
+    anyUser: boolean;
+    targetActorIds: string[];
+    anyTarget: boolean;
+    claimSearchParams: Readonly<Record<string, string[]>>;
+    periodStart?: string;
+    periodEnd?: string;
+    page: number;
+    count?: number;
+};
+export type CommunicationParticipantProjection = {
+    subject?: unknown;
+    sender?: unknown;
+    recipients?: unknown;
+    from?: unknown;
+    to?: unknown;
+    sent?: unknown;
+    category?: unknown;
+    topic?: unknown;
+};
+export type CommunicationParticipantIndexedAttribute = {
+    name: string;
+    value: string;
+    unique?: boolean;
+};
+export declare function normalizeCommunicationParticipantToken(value: unknown): string;
+export declare function normalizeCommunicationParticipantTokenList(value: unknown): string[];
+export declare function isCommunicationParticipantWildcardToken(value: unknown): boolean;
+export declare function buildCommunicationParticipantSearchParameters(input: CommunicationParticipantSearchInput): FhirParametersResource;
+export declare function buildCommunicationParticipantSearchBundle(input: CommunicationParticipantSearchInput): ReturnType<typeof buildSearchBundle>;
+export declare function parseCommunicationParticipantSearchCriteria(input: Record<string, unknown> | FhirParametersResource | undefined): CommunicationParticipantSearchCriteria;
+export declare function buildCommunicationParticipantIndexAttributes(projection: CommunicationParticipantProjection): CommunicationParticipantIndexedAttribute[];
+export declare function matchesCommunicationParticipantSearch(projection: CommunicationParticipantProjection, criteria: CommunicationParticipantSearchCriteria): boolean;
+export declare function paginateCommunicationParticipantMatches<T>(records: readonly T[], criteria: Pick<CommunicationParticipantSearchCriteria, 'page' | 'count'>): T[];