gdc-common-utils-ts 1.8.0 → 1.10.0

package/README.md

@@ -142,6 +142,8 @@ The canonical API contract should live in JSDoc on exported code. The README act
   - This is the preferred first scope to teach when the backend only needs subject-scoped read access.
 - [`getOrganizationCredentialFromVpToken(...)`, `getLegalRepresentativeCredentialFromVpToken(...)`](src/utils/vp-token.ts)
   - Extract typed VC objects from a VP token when GW/SDK flows carry canonical proof only in `vp_token`.
+- [`docs/VP_TOKEN_101.md`](docs/VP_TOKEN_101.md)
+  - Step-by-step guide for building the canonical compact `vp_token` string from organization and representative VCs.
 - [`validateCommunicationResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
   - Validates FHIR R4 `Communication` resources.
 - [`transformCommunicationClaimsToResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)

package/dist/constants/service-capabilities.d.ts

@@ -14,9 +14,25 @@ export type ServiceCapabilityFamilyValue = typeof ServiceCapabilityFamily[keyof
  * `.rs` and `.cruds` can evolve independently across runtimes.
  */
 export declare const ServiceCapabilityToken: {
+    readonly IndexReader: "indexing.rs";
+    readonly IndexProvider: "indexing.cruds";
+    readonly DigitalTwinReader: "digitaltwin.rs";
+    readonly DigitalTwinProvider: "digitaltwin.cruds";
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
     readonly IndexingReadSearch: "indexing.rs";
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
     readonly IndexingCruds: "indexing.cruds";
+    /**
+     * @deprecated Prefer `DigitalTwinReader`.
+     */
     readonly DigitalTwinReadSearch: "digitaltwin.rs";
+    /**
+     * @deprecated Prefer `DigitalTwinProvider`.
+     */
     readonly DigitalTwinCruds: "digitaltwin.cruds";
 };
 export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof typeof ServiceCapabilityToken];
@@ -28,10 +44,18 @@ export type ServiceCapabilityTokenValue = typeof ServiceCapabilityToken[keyof ty
  * - `Reader` maps to read/search capability (`*.rs`)
  */
 export declare const ServiceCapability: {
-    readonly IndexingProvider: "indexing.cruds";
-    readonly IndexingReader: "indexing.rs";
+    readonly IndexProvider: "indexing.cruds";
+    readonly IndexReader: "indexing.rs";
     readonly DigitalTwinProvider: "digitaltwin.cruds";
     readonly DigitalTwinReader: "digitaltwin.rs";
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
+    readonly IndexingProvider: "indexing.cruds";
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
+    readonly IndexingReader: "indexing.rs";
 };
 export type ServiceCapabilityValue = typeof ServiceCapability[keyof typeof ServiceCapability];
 /**

package/dist/constants/service-capabilities.js

@@ -15,9 +15,25 @@ export const ServiceCapabilityFamily = {
  * `.rs` and `.cruds` can evolve independently across runtimes.
  */
 export const ServiceCapabilityToken = {
+    IndexReader: 'indexing.rs',
+    IndexProvider: 'indexing.cruds',
+    DigitalTwinReader: 'digitaltwin.rs',
+    DigitalTwinProvider: 'digitaltwin.cruds',
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
     IndexingReadSearch: 'indexing.rs',
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
     IndexingCruds: 'indexing.cruds',
+    /**
+     * @deprecated Prefer `DigitalTwinReader`.
+     */
     DigitalTwinReadSearch: 'digitaltwin.rs',
+    /**
+     * @deprecated Prefer `DigitalTwinProvider`.
+     */
     DigitalTwinCruds: 'digitaltwin.cruds',
 };
 /**
@@ -28,10 +44,18 @@ export const ServiceCapabilityToken = {
  * - `Reader` maps to read/search capability (`*.rs`)
  */
 export const ServiceCapability = {
-    IndexingProvider: ServiceCapabilityToken.IndexingCruds,
-    IndexingReader: ServiceCapabilityToken.IndexingReadSearch,
-    DigitalTwinProvider: ServiceCapabilityToken.DigitalTwinCruds,
-    DigitalTwinReader: ServiceCapabilityToken.DigitalTwinReadSearch,
+    IndexProvider: ServiceCapabilityToken.IndexProvider,
+    IndexReader: ServiceCapabilityToken.IndexReader,
+    DigitalTwinProvider: ServiceCapabilityToken.DigitalTwinProvider,
+    DigitalTwinReader: ServiceCapabilityToken.DigitalTwinReader,
+    /**
+     * @deprecated Prefer `IndexProvider`.
+     */
+    IndexingProvider: ServiceCapabilityToken.IndexProvider,
+    /**
+     * @deprecated Prefer `IndexReader`.
+     */
+    IndexingReader: ServiceCapabilityToken.IndexReader,
 };
 /**
  * Parses the CSV stored in `org.schema.Service.serviceType`.

package/dist/examples/organization-controller.js

@@ -26,8 +26,8 @@ export const EXAMPLE_ACTIVATE_ORGANIZATION_FROM_ICA_PROOF_INPUT = {
         [ClaimsServiceSchemaorg.identifier]: EXAMPLE_SERVICE_PUBLIC_DID,
         [ClaimsServiceSchemaorg.url]: `https://operator.example.net/acme/cds-${String(EXAMPLE_JURISDICTION).toLowerCase()}/v1/${EXAMPLE_SECTOR}`,
         [ClaimsServiceSchemaorg.serviceType]: serializeServiceCapabilityTokens([
-            ServiceCapabilityToken.IndexingCruds,
-            ServiceCapabilityToken.DigitalTwinReadSearch,
+            ServiceCapabilityToken.IndexProvider,
+            ServiceCapabilityToken.DigitalTwinReader,
         ]),
     },
 };

package/dist/models/fhir-related-person.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Canonical flat-claim constants for FHIR `RelatedPerson`.
+ *
+ * @architecture 101
+ * - Use exported constants instead of inline claim-name literals.
+ * - `ClaimsContextFhirRelatedPerson` models the stable business/search contract.
+ * - `RelatedPerson.patient` is kept as a transport/storage compatibility alias for
+ *   existing R4 payloads, while `RelatedPerson.subject` remains the shared SDK name.
+ */
+import type { SearchParameterCatalog } from './params';
+/**
+ * Canonical interoperable claims for `RelatedPerson`.
+ *
+ * The enum follows the established `ResourceType.parameter` shape used by the
+ * rest of the flat FHIR claims model.
+ */
+export declare enum ClaimsContextFhirRelatedPerson {
+    Identifier = "RelatedPerson.identifier",
+    Subject = "RelatedPerson.subject",
+    Relationship = "RelatedPerson.relationship",
+    Name = "RelatedPerson.name",
+    Email = "RelatedPerson.email",
+    Phone = "RelatedPerson.phone"
+}
+/**
+ * Legacy FHIR R4 field name still present in examples and existing stored data.
+ *
+ * New shared code should normalize from this alias into
+ * `ClaimsContextFhirRelatedPerson.Subject` when projecting business DTOs.
+ */
+export declare const FHIR_RELATED_PERSON_PATIENT_CLAIM: "RelatedPerson.patient";
+/**
+ * Legacy telecom alias preserved for older ingestion payloads.
+ */
+export declare const FHIR_RELATED_PERSON_TELECOM_CLAIM: "RelatedPerson.telecom";
+/**
+ * Optional lifecycle/status claim used by projections when present.
+ */
+export declare const FHIR_RELATED_PERSON_STATUS_CLAIM: "RelatedPerson.status";
+/**
+ * Public search parameter names exposed for `RelatedPerson`.
+ *
+ * These names are independent from the underlying flat claim keys and are the
+ * right source for client-side search UIs and future `CapabilityStatement`
+ * generation.
+ */
+export declare enum RelatedPersonSearchParameterName {
+    Identifier = "identifier",
+    Subject = "subject",
+    Relationship = "relationship",
+    Name = "name",
+    Email = "email",
+    Phone = "phone"
+}
+/**
+ * Shared searchable/indexable parameter catalog for `RelatedPerson`.
+ *
+ * `name` is the canonical flat claim key to index/query. The record key is the
+ * public search-attribute name.
+ */
+export declare const relatedPersonSearchParameterCatalog: SearchParameterCatalog<RelatedPersonSearchParameterName>;

package/dist/models/fhir-related-person.js

@@ -0,0 +1,108 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Canonical flat-claim constants for FHIR `RelatedPerson`.
+ *
+ * @architecture 101
+ * - Use exported constants instead of inline claim-name literals.
+ * - `ClaimsContextFhirRelatedPerson` models the stable business/search contract.
+ * - `RelatedPerson.patient` is kept as a transport/storage compatibility alias for
+ *   existing R4 payloads, while `RelatedPerson.subject` remains the shared SDK name.
+ */
+/**
+ * Canonical interoperable claims for `RelatedPerson`.
+ *
+ * The enum follows the established `ResourceType.parameter` shape used by the
+ * rest of the flat FHIR claims model.
+ */
+export var ClaimsContextFhirRelatedPerson;
+(function (ClaimsContextFhirRelatedPerson) {
+    ClaimsContextFhirRelatedPerson["Identifier"] = "RelatedPerson.identifier";
+    ClaimsContextFhirRelatedPerson["Subject"] = "RelatedPerson.subject";
+    ClaimsContextFhirRelatedPerson["Relationship"] = "RelatedPerson.relationship";
+    ClaimsContextFhirRelatedPerson["Name"] = "RelatedPerson.name";
+    ClaimsContextFhirRelatedPerson["Email"] = "RelatedPerson.email";
+    ClaimsContextFhirRelatedPerson["Phone"] = "RelatedPerson.phone";
+})(ClaimsContextFhirRelatedPerson || (ClaimsContextFhirRelatedPerson = {}));
+/**
+ * Legacy FHIR R4 field name still present in examples and existing stored data.
+ *
+ * New shared code should normalize from this alias into
+ * `ClaimsContextFhirRelatedPerson.Subject` when projecting business DTOs.
+ */
+export const FHIR_RELATED_PERSON_PATIENT_CLAIM = 'RelatedPerson.patient';
+/**
+ * Legacy telecom alias preserved for older ingestion payloads.
+ */
+export const FHIR_RELATED_PERSON_TELECOM_CLAIM = 'RelatedPerson.telecom';
+/**
+ * Optional lifecycle/status claim used by projections when present.
+ */
+export const FHIR_RELATED_PERSON_STATUS_CLAIM = 'RelatedPerson.status';
+/**
+ * Public search parameter names exposed for `RelatedPerson`.
+ *
+ * These names are independent from the underlying flat claim keys and are the
+ * right source for client-side search UIs and future `CapabilityStatement`
+ * generation.
+ */
+export var RelatedPersonSearchParameterName;
+(function (RelatedPersonSearchParameterName) {
+    RelatedPersonSearchParameterName["Identifier"] = "identifier";
+    RelatedPersonSearchParameterName["Subject"] = "subject";
+    RelatedPersonSearchParameterName["Relationship"] = "relationship";
+    RelatedPersonSearchParameterName["Name"] = "name";
+    RelatedPersonSearchParameterName["Email"] = "email";
+    RelatedPersonSearchParameterName["Phone"] = "phone";
+})(RelatedPersonSearchParameterName || (RelatedPersonSearchParameterName = {}));
+/**
+ * Shared searchable/indexable parameter catalog for `RelatedPerson`.
+ *
+ * `name` is the canonical flat claim key to index/query. The record key is the
+ * public search-attribute name.
+ */
+export const relatedPersonSearchParameterCatalog = {
+    [RelatedPersonSearchParameterName.Identifier]: {
+        name: ClaimsContextFhirRelatedPerson.Identifier,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Subject]: {
+        name: ClaimsContextFhirRelatedPerson.Subject,
+        type: 'reference',
+        value: undefined,
+        indexed: true,
+        claimAliases: [FHIR_RELATED_PERSON_PATIENT_CLAIM],
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Relationship]: {
+        name: ClaimsContextFhirRelatedPerson.Relationship,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Name]: {
+        name: ClaimsContextFhirRelatedPerson.Name,
+        type: 'string',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Email]: {
+        name: ClaimsContextFhirRelatedPerson.Email,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        appliesTo: ['RelatedPerson'],
+    },
+    [RelatedPersonSearchParameterName.Phone]: {
+        name: ClaimsContextFhirRelatedPerson.Phone,
+        type: 'token',
+        value: undefined,
+        indexed: true,
+        claimAliases: [FHIR_RELATED_PERSON_TELECOM_CLAIM],
+        appliesTo: ['RelatedPerson'],
+    },
+};

package/dist/models/related-profile.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Shared DTOs for portal/BFF `related profiles` projections.
+ *
+ * @architecture 101
+ * - These DTOs are frontend-facing projections, not raw FHIR payloads.
+ * - Raw search/index semantics stay in `ClaimsContextFhirRelatedPerson`.
+ * - Use exported constants for repeated source and parameter names.
+ */
+export type RelatedProfileStatus = 'active' | 'pending' | 'inactive' | 'revoked';
+export type RelatedProfileRole = 'controller' | 'caregiver' | 'related-person' | 'professional' | 'member' | 'unknown';
+export type RelatedProfileSource = 'relatedperson';
+export declare const RELATED_PROFILE_SOURCE_RELATED_PERSON: "relatedperson";
+export declare const RELATED_PROFILE_SEARCH_PARAM_ACTOR_IDENTIFIER: "actorIdentifier";
+export declare const RELATED_PROFILE_SEARCH_PARAM_SUBJECT_ID: "subjectId";
+export declare const RELATED_PROFILE_SEARCH_PARAM_RELATIONSHIP: "relationship";
+export declare const RELATED_PROFILE_SEARCH_PARAM_INCLUDE_INACTIVE: "includeInactive";
+export type RelatedProfileSearchInput = Readonly<{
+    actorIdentifier: string;
+    subjectId?: string;
+    relationship?: string;
+    includeInactive?: boolean;
+}>;
+export type RelatedProfileSummary = Readonly<{
+    relationshipId: string;
+    source: RelatedProfileSource;
+    subjectId: string;
+    actorIdentifier?: string;
+    actorDisplayName?: string;
+    actorTelecom?: string;
+    relationship?: string;
+    role: RelatedProfileRole;
+    isController: boolean;
+    status: RelatedProfileStatus;
+    claims: Record<string, unknown>;
+}>;
+export type RelatedProfileSearchResult = Readonly<{
+    actorIdentifier: string;
+    total: number;
+    data: RelatedProfileSummary[];
+}>;
+export declare const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_SEATS = 2;
+export declare const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_PRICE_EUR = "0.00";

package/dist/models/related-profile.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Shared DTOs for portal/BFF `related profiles` projections.
+ *
+ * @architecture 101
+ * - These DTOs are frontend-facing projections, not raw FHIR payloads.
+ * - Raw search/index semantics stay in `ClaimsContextFhirRelatedPerson`.
+ * - Use exported constants for repeated source and parameter names.
+ */
+export const RELATED_PROFILE_SOURCE_RELATED_PERSON = 'relatedperson';
+export const RELATED_PROFILE_SEARCH_PARAM_ACTOR_IDENTIFIER = 'actorIdentifier';
+export const RELATED_PROFILE_SEARCH_PARAM_SUBJECT_ID = 'subjectId';
+export const RELATED_PROFILE_SEARCH_PARAM_RELATIONSHIP = 'relationship';
+export const RELATED_PROFILE_SEARCH_PARAM_INCLUDE_INACTIVE = 'includeInactive';
+export const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_SEATS = 2;
+export const DEFAULT_INDIVIDUAL_MEMBER_BASELINE_PRICE_EUR = '0.00';

package/dist/utils/gateway-index-params.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Shared internal index-parameter builders used by GW managers.
+ *
+ * @architecture 101
+ * These helpers are not public FHIR search catalogs. They encapsulate internal
+ * blind-query index shapes already shared across multiple GW managers.
+ */
+import type { ParameterData } from '../models/params';
+import type { ClaimsRecord } from '../models/resource-document';
+/**
+ * Internal blind-query attribute names shared by employee/controller records.
+ */
+export declare enum GatewayEmployeeIndexAttributeName {
+    Email = "email",
+    Role = "role",
+    Kid = "kid"
+}
+type EmployeeIdentityIndexInput = Readonly<{
+    email?: string;
+    roleCode?: string;
+    kidValues?: readonly string[];
+}>;
+/**
+ * Builds the canonical blind-query index set for employee/controller records.
+ *
+ * `roleCode` is expected to be already normalized by the caller.
+ *
+ * @param input - Concrete employee/controller identity values.
+ * @returns Concrete `ParameterData[]` entries ready for HMAC protection.
+ */
+export declare function buildEmployeeIdentityIndexParameters(input: EmployeeIdentityIndexInput): ParameterData[];
+/**
+ * Materializes concrete index parameters from a shared flat-claim definition list.
+ *
+ * The returned entries keep the original definition metadata (`type`, `unique`)
+ * and only replace `value` with the concrete scalar from the claims object when
+ * present.
+ *
+ * @param claims - Flat claims object to read from.
+ * @param definitions - Shared parameter definitions.
+ * @returns Concrete entries with populated values only.
+ */
+export declare function buildClaimIndexParametersFromDefinitionList(claims: ClaimsRecord, definitions: readonly ParameterData[]): ParameterData[];
+export {};

package/dist/utils/gateway-index-params.js

@@ -0,0 +1,80 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Shared internal index-parameter builders used by GW managers.
+ *
+ * @architecture 101
+ * These helpers are not public FHIR search catalogs. They encapsulate internal
+ * blind-query index shapes already shared across multiple GW managers.
+ */
+/**
+ * Internal blind-query attribute names shared by employee/controller records.
+ */
+export var GatewayEmployeeIndexAttributeName;
+(function (GatewayEmployeeIndexAttributeName) {
+    GatewayEmployeeIndexAttributeName["Email"] = "email";
+    GatewayEmployeeIndexAttributeName["Role"] = "role";
+    GatewayEmployeeIndexAttributeName["Kid"] = "kid";
+})(GatewayEmployeeIndexAttributeName || (GatewayEmployeeIndexAttributeName = {}));
+/**
+ * Builds the canonical blind-query index set for employee/controller records.
+ *
+ * `roleCode` is expected to be already normalized by the caller.
+ *
+ * @param input - Concrete employee/controller identity values.
+ * @returns Concrete `ParameterData[]` entries ready for HMAC protection.
+ */
+export function buildEmployeeIdentityIndexParameters(input) {
+    const parameters = [];
+    if (typeof input.email === 'string' && input.email.trim().length > 0) {
+        parameters.push({
+            name: GatewayEmployeeIndexAttributeName.Email,
+            value: input.email.trim(),
+            unique: true,
+            type: 'string',
+        });
+    }
+    if (typeof input.roleCode === 'string' && input.roleCode.trim().length > 0) {
+        parameters.push({
+            name: GatewayEmployeeIndexAttributeName.Role,
+            value: input.roleCode.trim(),
+            unique: false,
+            type: 'token',
+        });
+    }
+    for (const kid of input.kidValues || []) {
+        if (typeof kid !== 'string' || kid.trim().length === 0)
+            continue;
+        parameters.push({
+            name: GatewayEmployeeIndexAttributeName.Kid,
+            value: kid.trim(),
+            unique: false,
+            type: 'string',
+        });
+    }
+    return parameters;
+}
+/**
+ * Materializes concrete index parameters from a shared flat-claim definition list.
+ *
+ * The returned entries keep the original definition metadata (`type`, `unique`)
+ * and only replace `value` with the concrete scalar from the claims object when
+ * present.
+ *
+ * @param claims - Flat claims object to read from.
+ * @param definitions - Shared parameter definitions.
+ * @returns Concrete entries with populated values only.
+ */
+export function buildClaimIndexParametersFromDefinitionList(claims, definitions) {
+    const parameters = [];
+    for (const definition of definitions) {
+        const rawValue = claims[definition.name];
+        if (typeof rawValue !== 'string' && typeof rawValue !== 'number') {
+            continue;
+        }
+        parameters.push({
+            ...definition,
+            value: rawValue,
+        });
+    }
+    return parameters;
+}

package/dist/utils/search-parameter-catalog.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Helpers for shared search-parameter catalogs.
+ *
+ * @architecture 101
+ * - Search catalogs define the public search surface by resource type.
+ * - These helpers resolve canonical contextualized claim names plus aliases.
+ * - GW managers can use the same catalog both for indexing and for future
+ *   `CapabilityStatement.searchParam` generation.
+ */
+import type { ClaimsRecord } from '../models/resource-document';
+import type { ParameterData, SearchParameterCatalog, SearchParameterDefinition } from '../models/params';
+/**
+ * Resolves the first populated value for a search parameter definition using its
+ * canonical claim name followed by any configured aliases.
+ *
+ * @param claims - Flat claims object.
+ * @param definition - Search parameter definition.
+ * @returns First populated scalar value, if any.
+ */
+export declare function resolveSearchParameterValueFromClaims(claims: ClaimsRecord, definition: SearchParameterDefinition): string | undefined;
+/**
+ * Builds index/query-ready `ParameterData` entries from a shared search catalog.
+ *
+ * Only catalog entries marked as indexable, and with a populated value in the
+ * claims object, are returned.
+ *
+ * @param claims - Flat claims object.
+ * @param catalog - Shared search parameter catalog for a resource type.
+ * @returns Concrete parameter entries with resolved values.
+ */
+export declare function buildIndexParametersFromSearchCatalog<TSearchName extends string>(claims: ClaimsRecord, catalog: SearchParameterCatalog<TSearchName>): ParameterData[];

package/dist/utils/search-parameter-catalog.js

@@ -0,0 +1,81 @@
+// Copyright 2026 Antifraud Services Inc. under the Apache License, Version 2.0.
+/**
+ * @fileoverview Helpers for shared search-parameter catalogs.
+ *
+ * @architecture 101
+ * - Search catalogs define the public search surface by resource type.
+ * - These helpers resolve canonical contextualized claim names plus aliases.
+ * - GW managers can use the same catalog both for indexing and for future
+ *   `CapabilityStatement.searchParam` generation.
+ */
+/**
+ * Trims a scalar value into a canonical optional string.
+ *
+ * @param value - Raw claim value.
+ * @returns Trimmed text or `undefined` when empty.
+ */
+function normalizeOptionalText(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+/**
+ * Resolves a flat claim using exact match first and `@context`-prefixed lookup
+ * as compatibility fallback for contextualized storage mode.
+ *
+ * @param claims - Flat claims object.
+ * @param claimName - Canonical or alias claim key.
+ * @returns Scalar value when present.
+ */
+function getContextualizedClaimValue(claims, claimName) {
+    const directValue = normalizeOptionalText(claims[claimName]);
+    if (directValue)
+        return directValue;
+    const context = normalizeOptionalText(claims['@context']);
+    if (!context)
+        return undefined;
+    const prefixedName = context.endsWith('.') ? `${context}${claimName}` : `${context}.${claimName}`;
+    return normalizeOptionalText(claims[prefixedName]);
+}
+/**
+ * Resolves the first populated value for a search parameter definition using its
+ * canonical claim name followed by any configured aliases.
+ *
+ * @param claims - Flat claims object.
+ * @param definition - Search parameter definition.
+ * @returns First populated scalar value, if any.
+ */
+export function resolveSearchParameterValueFromClaims(claims, definition) {
+    const claimNames = [definition.name, ...(definition.claimAliases || [])];
+    for (const claimName of claimNames) {
+        const normalized = getContextualizedClaimValue(claims, claimName);
+        if (normalized)
+            return normalized;
+    }
+    return undefined;
+}
+/**
+ * Builds index/query-ready `ParameterData` entries from a shared search catalog.
+ *
+ * Only catalog entries marked as indexable, and with a populated value in the
+ * claims object, are returned.
+ *
+ * @param claims - Flat claims object.
+ * @param catalog - Shared search parameter catalog for a resource type.
+ * @returns Concrete parameter entries with resolved values.
+ */
+export function buildIndexParametersFromSearchCatalog(claims, catalog) {
+    const parameters = [];
+    for (const definition of Object.values(catalog)) {
+        if (definition.indexed === false)
+            continue;
+        const value = resolveSearchParameterValueFromClaims(claims, definition);
+        if (!value)
+            continue;
+        parameters.push({
+            ...definition,
+            name: definition.name,
+            value,
+        });
+    }
+    return parameters;
+}

package/dist/utils/vp-token.d.ts

@@ -16,20 +16,47 @@ export type VpTokenPayload = {
         '@context'?: unknown;
         type?: unknown;
         holder?: string;
-        verifiableCredential: string[];
+        verifiableCredential: Array<string | Record<string, unknown>>;
         [key: string]: unknown;
     };
     [key: string]: unknown;
 };
 export type VpCredential = Record<string, unknown>;
+export type VpCredentialInput = string | Record<string, unknown>;
 export declare function generateUuidLike(): string;
 export declare function buildEpochWindow(ttlSeconds?: number): {
     iat: number;
     exp: number;
 };
 export declare function createVP(input?: Partial<VpTokenPayload>): VpTokenPayload;
-export declare function addVC(vpPayload: VpTokenPayload, vcJwt: string): VpTokenPayload;
-export declare function addVCs(vpPayload: VpTokenPayload, vcs: string[]): VpTokenPayload;
+/**
+ * Appends one VC entry to the VP payload.
+ *
+ * Accepted input forms:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ *
+ * Storage rule:
+ *
+ * - string inputs are stored as strings
+ * - object inputs are stored as objects
+ *
+ * This keeps the builder compatible with existing compact-token flows while
+ * also supporting app/runtime code that already holds the VC as parsed JSON.
+ */
+export declare function addVC(vpPayload: VpTokenPayload, vcInput: VpCredentialInput): VpTokenPayload;
+/**
+ * Appends many VC entries to the VP payload.
+ *
+ * Each entry may be:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ */
+export declare function addVCs(vpPayload: VpTokenPayload, vcs: VpCredentialInput[]): VpTokenPayload;
 /**
  * Decodes a compact VP token payload into a JSON object.
  *
@@ -67,8 +94,19 @@ export declare function getOrganizationCredentialFromVpToken(vpToken: string): V
  * @param vpToken Compact VP token or raw JSON string.
  */
 export declare function getLegalRepresentativeCredentialFromVpToken(vpToken: string): VpCredential | undefined;
-export declare function addOrganizationCredential(vpPayload: VpTokenPayload, vc: string): VpTokenPayload;
-export declare function addLegalRepresentativeCredential(vpPayload: VpTokenPayload, vc: string): VpTokenPayload;
+/**
+ * Appends an organization activation credential after validating its VC type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
+export declare function addOrganizationCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
+/**
+ * Appends a legal-representative activation credential after validating its VC
+ * type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
+export declare function addLegalRepresentativeCredential(vpPayload: VpTokenPayload, vc: VpCredentialInput): VpTokenPayload;
 export declare function prepareForSignature(header: VpTokenHeader, payload: VpTokenPayload): {
     encodedHeader: string;
     encodedPayload: string;

package/dist/utils/vp-token.js

@@ -37,19 +37,52 @@ export function createVP(input) {
     };
     return base;
 }
-export function addVC(vpPayload, vcJwt) {
-    const v = String(vcJwt || '').trim();
+/**
+ * Appends one VC entry to the VP payload.
+ *
+ * Accepted input forms:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ *
+ * Storage rule:
+ *
+ * - string inputs are stored as strings
+ * - object inputs are stored as objects
+ *
+ * This keeps the builder compatible with existing compact-token flows while
+ * also supporting app/runtime code that already holds the VC as parsed JSON.
+ */
+export function addVC(vpPayload, vcInput) {
+    if (vcInput && typeof vcInput === 'object') {
+        vpPayload.vp.verifiableCredential.push({ ...vcInput });
+        return vpPayload;
+    }
+    const v = String(vcInput || '').trim();
     if (!v)
         return vpPayload;
     vpPayload.vp.verifiableCredential.push(v);
     return vpPayload;
 }
+/**
+ * Appends many VC entries to the VP payload.
+ *
+ * Each entry may be:
+ *
+ * - compact VC JWT/JWS string
+ * - raw JSON VC string
+ * - direct VC JSON object
+ */
 export function addVCs(vpPayload, vcs) {
     for (const vc of vcs || [])
         addVC(vpPayload, vc);
     return vpPayload;
 }
 function decodeVcPayload(vc) {
+    if (vc && typeof vc === 'object') {
+        return vc;
+    }
     const raw = String(vc || '').trim();
     if (!raw)
         return undefined;
@@ -173,9 +206,20 @@ function addTypedVC(vpPayload, vc, acceptedTypes, label) {
     }
     return addVC(vpPayload, vc);
 }
+/**
+ * Appends an organization activation credential after validating its VC type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
 export function addOrganizationCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...ORGANIZATION_ACTIVATION_VC_TYPES], 'Organization');
 }
+/**
+ * Appends a legal-representative activation credential after validating its VC
+ * type.
+ *
+ * Accepts compact VC strings, raw JSON VC strings, or VC JSON objects.
+ */
 export function addLegalRepresentativeCredential(vpPayload, vc) {
     return addTypedVC(vpPayload, vc, [...REPRESENTATIVE_ACTIVATION_VC_TYPES], 'LegalRepresentative');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "publishConfig": {
     "access": "public"
   },