gdc-common-utils-ts 1.14.9 → 1.14.13

package/dist/utils/convert-shared.js

@@ -0,0 +1,179 @@
+// Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
+// File: src/utils/convert-shared.ts
+export function isPlainObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+export function codingFromValue(value) {
+    if (!value)
+        return undefined;
+    const [system, code] = value.split('|');
+    if (!code)
+        return [{ code: system }];
+    return [{ system, code }];
+}
+export function codingToValue(coding) {
+    if (!coding?.code)
+        return undefined;
+    return coding.system ? `${coding.system}|${coding.code}` : coding.code;
+}
+export function referenceToValue(reference) {
+    return reference?.reference;
+}
+export function referenceListToCsv(references) {
+    const values = (references || [])
+        .map((item) => item?.reference)
+        .filter((item) => Boolean(item));
+    return values.length ? values.join(',') : undefined;
+}
+export function codingListToCsv(codings) {
+    const values = (codings || [])
+        .map((item) => codingToValue(item))
+        .filter((item) => Boolean(item));
+    return values.length ? values.join(',') : undefined;
+}
+export function requireClaim(claims, key) {
+    const value = claims[key];
+    if (!value)
+        throw new Error(`Missing required claim: ${key}`);
+    return value;
+}
+export function requireSubjectIdentifier(value, key) {
+    if (!value.startsWith('urn:') && !value.startsWith('did:web:')) {
+        throw new Error(`Invalid ${key}: expected urn:* or did:web:*`);
+    }
+}
+export function requireDidWeb(value, key) {
+    if (!value.startsWith('did:web:')) {
+        throw new Error(`Invalid ${key}: expected did:web:*`);
+    }
+}
+function stringifyClaimLeaf(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return undefined;
+}
+function flattenClaimPath(prefix, value, out) {
+    const primitive = stringifyClaimLeaf(value);
+    if (primitive !== undefined) {
+        out[prefix] = primitive;
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            out[`${prefix}#type`] = typeof value;
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            flattenClaimPath(`${prefix}[${index}]`, entry, out);
+        });
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [key, nestedValue] of Object.entries(value)) {
+            if (key === 'meta' && isPlainObject(nestedValue) && 'claims' in nestedValue) {
+                const nestedMeta = { ...nestedValue };
+                delete nestedMeta.claims;
+                if (Object.keys(nestedMeta).length === 0)
+                    continue;
+                flattenClaimPath(`${prefix}.${key}`, nestedMeta, out);
+                continue;
+            }
+            flattenClaimPath(`${prefix}.${key}`, nestedValue, out);
+        }
+    }
+}
+function parseClaimPath(path) {
+    const segments = [];
+    const re = /([^[.\]]+)|\[(\d+)\]/g;
+    let match;
+    while ((match = re.exec(path)) !== null) {
+        if (match[1])
+            segments.push(match[1]);
+        else if (match[2])
+            segments.push(Number(match[2]));
+    }
+    return segments;
+}
+function coerceClaimLeaf(value, typeHint) {
+    if (typeHint === 'boolean')
+        return value === 'true';
+    if (typeHint === 'number')
+        return Number(value);
+    return value;
+}
+function assignInflatedPath(target, path, value, typeHint) {
+    const segments = parseClaimPath(path);
+    if (segments.length === 0)
+        return;
+    let cursor = target;
+    for (let index = 0; index < segments.length; index += 1) {
+        const segment = segments[index];
+        const nextSegment = segments[index + 1];
+        const isLast = index === segments.length - 1;
+        if (typeof segment === 'number') {
+            if (!Array.isArray(cursor))
+                return;
+            if (isLast) {
+                cursor[segment] = coerceClaimLeaf(value, typeHint);
+                return;
+            }
+            if (cursor[segment] === undefined)
+                cursor[segment] = typeof nextSegment === 'number' ? [] : {};
+            cursor = cursor[segment];
+            continue;
+        }
+        if (!isPlainObject(cursor))
+            return;
+        if (isLast) {
+            cursor[segment] = coerceClaimLeaf(value, typeHint);
+            return;
+        }
+        if (cursor[segment] === undefined)
+            cursor[segment] = typeof nextSegment === 'number' ? [] : {};
+        cursor = cursor[segment];
+    }
+}
+/**
+ * Generic structural fallback for unsupported resources.
+ */
+export function fhirResourceToFlatClaims(resource, context = 'org.hl7.fhir.r4') {
+    if (!resource?.resourceType) {
+        throw new Error('FHIR resource must define resourceType.');
+    }
+    const out = { '@context': context };
+    for (const [key, value] of Object.entries(resource)) {
+        if (key === 'resourceType')
+            continue;
+        flattenClaimPath(`${resource.resourceType}.${key}`, value, out);
+    }
+    return out;
+}
+/**
+ * Generic structural regeneration for unsupported resources.
+ */
+export function flatClaimsToFhirResource(claims) {
+    const typeHints = new Map();
+    for (const [key, value] of Object.entries(claims || {})) {
+        if (key.endsWith('#type') && typeof value === 'string') {
+            typeHints.set(key.slice(0, -5), value);
+        }
+    }
+    const entries = Object.entries(claims || {}).filter(([key, value]) => key !== '@context' && !key.endsWith('#type') && value !== undefined);
+    const firstClaimKey = entries[0]?.[0];
+    if (!firstClaimKey || !firstClaimKey.includes('.')) {
+        throw new Error('Flat claims must contain at least one contextualized resource claim.');
+    }
+    const resourceType = firstClaimKey.split('.')[0];
+    const resource = { resourceType };
+    for (const [key, value] of entries) {
+        if (typeof value !== 'string')
+            continue;
+        if (!key.startsWith(`${resourceType}.`))
+            continue;
+        assignInflatedPath(resource, key.slice(resourceType.length + 1), value, typeHints.get(key));
+    }
+    return resource;
+}

package/dist/utils/coverage-claim-helpers.d.ts

@@ -0,0 +1,10 @@
+import { type GenericInteroperableClaims } from './claim-list-helpers.js';
+export type CoverageInteroperableClaims = GenericInteroperableClaims;
+export declare function getCoverageClaimList(claims: CoverageInteroperableClaims, claimKey: string): string[];
+export declare function setCoverageClaimList(claims: CoverageInteroperableClaims, claimKey: string, values: string | readonly string[]): CoverageInteroperableClaims;
+export declare function addCoverageClaimList(claims: CoverageInteroperableClaims, claimKey: string, values: string | readonly string[]): CoverageInteroperableClaims;
+export declare function removeCoverageClaimList(claims: CoverageInteroperableClaims, claimKey: string, values: string | readonly string[]): CoverageInteroperableClaims;
+export declare function getCoverageIdentifier(claims: CoverageInteroperableClaims): string;
+export declare function setCoverageIdentifier(claims: CoverageInteroperableClaims, value: string): CoverageInteroperableClaims;
+export declare function getCoveragePayorList(claims: CoverageInteroperableClaims): string[];
+export declare function setCoveragePayorList(claims: CoverageInteroperableClaims, values: string | readonly string[]): CoverageInteroperableClaims;

package/dist/utils/coverage-claim-helpers.js

@@ -0,0 +1,26 @@
+import { CoverageClaim } from '../models/interoperable-claims/coverage-claims.js';
+import { addClaimValues, getClaimValues, normalizeClaimScalar, removeClaimValues, setClaimValues, } from './claim-list-helpers.js';
+export function getCoverageClaimList(claims, claimKey) {
+    return getClaimValues(claims, claimKey);
+}
+export function setCoverageClaimList(claims, claimKey, values) {
+    return setClaimValues(claims, claimKey, values);
+}
+export function addCoverageClaimList(claims, claimKey, values) {
+    return addClaimValues(claims, claimKey, values);
+}
+export function removeCoverageClaimList(claims, claimKey, values) {
+    return removeClaimValues(claims, claimKey, values);
+}
+export function getCoverageIdentifier(claims) {
+    return normalizeClaimScalar(claims[CoverageClaim.Identifier]);
+}
+export function setCoverageIdentifier(claims, value) {
+    return { ...claims, [CoverageClaim.Identifier]: normalizeClaimScalar(value) };
+}
+export function getCoveragePayorList(claims) {
+    return getCoverageClaimList(claims, CoverageClaim.Payor);
+}
+export function setCoveragePayorList(claims, values) {
+    return setCoverageClaimList(claims, CoverageClaim.Payor, values);
+}

package/dist/utils/diagnostic-report-claim-helpers.d.ts

@@ -0,0 +1,12 @@
+import { type GenericInteroperableClaims } from './claim-list-helpers.js';
+export type DiagnosticReportInteroperableClaims = GenericInteroperableClaims;
+export declare function getDiagnosticReportClaimList(claims: DiagnosticReportInteroperableClaims, claimKey: string): string[];
+export declare function setDiagnosticReportClaimList(claims: DiagnosticReportInteroperableClaims, claimKey: string, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function addDiagnosticReportClaimList(claims: DiagnosticReportInteroperableClaims, claimKey: string, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function removeDiagnosticReportClaimList(claims: DiagnosticReportInteroperableClaims, claimKey: string, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportIdentifier(claims: DiagnosticReportInteroperableClaims): string;
+export declare function setDiagnosticReportIdentifier(claims: DiagnosticReportInteroperableClaims, value: string): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims): string[];
+export declare function setDiagnosticReportResultList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;
+export declare function getDiagnosticReportContainedDocumentIdentifierList(claims: DiagnosticReportInteroperableClaims): string[];
+export declare function setDiagnosticReportContainedDocumentIdentifierList(claims: DiagnosticReportInteroperableClaims, values: string | readonly string[]): DiagnosticReportInteroperableClaims;

package/dist/utils/diagnostic-report-claim-helpers.js

@@ -0,0 +1,32 @@
+import { DiagnosticReportClaim } from '../models/interoperable-claims/diagnostic-report-claims.js';
+import { addClaimValues, getClaimValues, normalizeClaimScalar, removeClaimValues, setClaimValues, } from './claim-list-helpers.js';
+export function getDiagnosticReportClaimList(claims, claimKey) {
+    return getClaimValues(claims, claimKey);
+}
+export function setDiagnosticReportClaimList(claims, claimKey, values) {
+    return setClaimValues(claims, claimKey, values);
+}
+export function addDiagnosticReportClaimList(claims, claimKey, values) {
+    return addClaimValues(claims, claimKey, values);
+}
+export function removeDiagnosticReportClaimList(claims, claimKey, values) {
+    return removeClaimValues(claims, claimKey, values);
+}
+export function getDiagnosticReportIdentifier(claims) {
+    return normalizeClaimScalar(claims[DiagnosticReportClaim.Identifier]);
+}
+export function setDiagnosticReportIdentifier(claims, value) {
+    return { ...claims, [DiagnosticReportClaim.Identifier]: normalizeClaimScalar(value) };
+}
+export function getDiagnosticReportResultList(claims) {
+    return getDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result);
+}
+export function setDiagnosticReportResultList(claims, values) {
+    return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.Result, values);
+}
+export function getDiagnosticReportContainedDocumentIdentifierList(claims) {
+    return getDiagnosticReportClaimList(claims, DiagnosticReportClaim.ContainedDocuments);
+}
+export function setDiagnosticReportContainedDocumentIdentifierList(claims, values) {
+    return setDiagnosticReportClaimList(claims, DiagnosticReportClaim.ContainedDocuments, values);
+}

package/dist/utils/encounter-claim-helpers.d.ts

@@ -0,0 +1,10 @@
+import { type GenericInteroperableClaims } from './claim-list-helpers.js';
+export type EncounterInteroperableClaims = GenericInteroperableClaims;
+export declare function getEncounterClaimList(claims: EncounterInteroperableClaims, claimKey: string): string[];
+export declare function setEncounterClaimList(claims: EncounterInteroperableClaims, claimKey: string, values: string | readonly string[]): EncounterInteroperableClaims;
+export declare function addEncounterClaimList(claims: EncounterInteroperableClaims, claimKey: string, values: string | readonly string[]): EncounterInteroperableClaims;
+export declare function removeEncounterClaimList(claims: EncounterInteroperableClaims, claimKey: string, values: string | readonly string[]): EncounterInteroperableClaims;
+export declare function getEncounterIdentifier(claims: EncounterInteroperableClaims): string;
+export declare function setEncounterIdentifier(claims: EncounterInteroperableClaims, value: string): EncounterInteroperableClaims;
+export declare function getEncounterParticipantList(claims: EncounterInteroperableClaims): string[];
+export declare function setEncounterParticipantList(claims: EncounterInteroperableClaims, values: string | readonly string[]): EncounterInteroperableClaims;

package/dist/utils/encounter-claim-helpers.js

@@ -0,0 +1,26 @@
+import { EncounterClaim } from '../models/interoperable-claims/encounter-claims.js';
+import { addClaimValues, getClaimValues, normalizeClaimScalar, removeClaimValues, setClaimValues, } from './claim-list-helpers.js';
+export function getEncounterClaimList(claims, claimKey) {
+    return getClaimValues(claims, claimKey);
+}
+export function setEncounterClaimList(claims, claimKey, values) {
+    return setClaimValues(claims, claimKey, values);
+}
+export function addEncounterClaimList(claims, claimKey, values) {
+    return addClaimValues(claims, claimKey, values);
+}
+export function removeEncounterClaimList(claims, claimKey, values) {
+    return removeClaimValues(claims, claimKey, values);
+}
+export function getEncounterIdentifier(claims) {
+    return normalizeClaimScalar(claims[EncounterClaim.Identifier]);
+}
+export function setEncounterIdentifier(claims, value) {
+    return { ...claims, [EncounterClaim.Identifier]: normalizeClaimScalar(value) };
+}
+export function getEncounterParticipantList(claims) {
+    return getEncounterClaimList(claims, EncounterClaim.Participant);
+}
+export function setEncounterParticipantList(claims, values) {
+    return setEncounterClaimList(claims, EncounterClaim.Participant, values);
+}

package/dist/utils/fhir-cid.d.ts

@@ -34,6 +34,31 @@ export type ClaimsCidResult = {
     canonicalJson: string;
     digestHex: string;
 };
+export type ClaimsContentHashOptions = {
+    /**
+     * Excludes JSON-LD envelope keys such as `@context`, `@type`, and `@id`.
+     * Default: true.
+     */
+    stripJsonLdEnvelope?: boolean;
+    /**
+     * Excludes transport/storage identifiers such as `id`, `*.id`,
+     * `identifier`, `*.identifier`, and `*.identifier.value`.
+     *
+     * This is the recommended default for clinical document/resource dedupe
+     * because those identifiers often reflect transport or logical identity,
+     * not semantic content.
+     *
+     * Default: true.
+     */
+    stripIdentifiers?: boolean;
+    /**
+     * Excludes claim keys that already carry a derived content version such as
+     * `*.meta.versionId`.
+     *
+     * Default: true.
+     */
+    stripVersionClaims?: boolean;
+};
 export type FhirCidVersionMapping = {
     resourceType?: string;
     resourceId?: string;
@@ -44,7 +69,31 @@ export type FhirCidVersionMapping = {
 export declare function canonicalizeFhirResource(resource: Record<string, unknown>, options?: FhirCanonicalizationOptions): string;
 export declare function buildCidV1FromCanonicalJson(canonicalJson: string, multicodecCode?: number): FhirCidResult;
 export declare function canonicalizeClaimsForCid(claims: Record<string, unknown>): string;
+/**
+ * Canonicalizes flat claims into deterministic JSON suitable for semantic
+ * content hashing.
+ *
+ * This differs from `canonicalizeClaimsForCid(...)` because it is designed for
+ * deduplication/versioning of clinical content, not for preserving logical
+ * identifiers. By default it removes:
+ *
+ * - JSON-LD envelope keys such as `@context`
+ * - transport/storage identifiers such as `id` and `identifier`
+ * - derived version keys such as `*.meta.versionId`
+ *
+ * The resulting object is sorted alphanumerically and serialized with stable
+ * key ordering so the same semantic content always yields the same hash.
+ */
+export declare function canonicalizeClaimsForContentHash(claims: Record<string, unknown>, options?: ClaimsContentHashOptions): string;
 export declare function claimsToCid(claims: Record<string, unknown>): ClaimsCidResult;
+/**
+ * Builds a content-addressed CID from flat claims after removing envelope,
+ * identifier, and version fields that should not affect semantic equality.
+ *
+ * Use this helper when the question is "does this document/resource content
+ * already exist?" rather than "what is the logical identifier of this object?".
+ */
+export declare function claimsToContentCid(claims: Record<string, unknown>, options?: ClaimsContentHashOptions): ClaimsCidResult;
 export declare function assignCidToClaimsId(claims: Record<string, unknown>): {
     claims: Record<string, unknown>;
     cid: string;

package/dist/utils/fhir-cid.js

@@ -95,6 +95,65 @@ export function canonicalizeClaimsForCid(claims) {
     }, 0);
     return JSON.stringify(normalized);
 }
+function shouldStripClaimKeyForContentHash(key, options) {
+    const normalizedKey = String(key || '').trim();
+    if (!normalizedKey)
+        return false;
+    if (options.stripJsonLdEnvelope && (normalizedKey === '@context'
+        || normalizedKey === '@type'
+        || normalizedKey === '@id')) {
+        return true;
+    }
+    const lowerKey = normalizedKey.toLowerCase();
+    if (options.stripVersionClaims && lowerKey.endsWith('.meta.versionid')) {
+        return true;
+    }
+    if (!options.stripIdentifiers)
+        return false;
+    if (lowerKey === 'id'
+        || lowerKey.endsWith('.id')
+        || lowerKey === 'identifier'
+        || lowerKey.endsWith('.identifier')
+        || lowerKey.endsWith('.identifier.value')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Canonicalizes flat claims into deterministic JSON suitable for semantic
+ * content hashing.
+ *
+ * This differs from `canonicalizeClaimsForCid(...)` because it is designed for
+ * deduplication/versioning of clinical content, not for preserving logical
+ * identifiers. By default it removes:
+ *
+ * - JSON-LD envelope keys such as `@context`
+ * - transport/storage identifiers such as `id` and `identifier`
+ * - derived version keys such as `*.meta.versionId`
+ *
+ * The resulting object is sorted alphanumerically and serialized with stable
+ * key ordering so the same semantic content always yields the same hash.
+ */
+export function canonicalizeClaimsForContentHash(claims, options = {}) {
+    const normalizedOptions = {
+        stripJsonLdEnvelope: options.stripJsonLdEnvelope ?? true,
+        stripIdentifiers: options.stripIdentifiers ?? true,
+        stripVersionClaims: options.stripVersionClaims ?? true,
+    };
+    const stripped = {};
+    for (const [key, value] of Object.entries(claims || {})) {
+        if (shouldStripClaimKeyForContentHash(key, normalizedOptions)) {
+            continue;
+        }
+        stripped[key] = value;
+    }
+    const normalized = canonicalizeValue(stripped, {
+        stripMetaVersionId: false,
+        stripNarrativeText: false,
+        stripNestedElementIds: false,
+    }, 0);
+    return JSON.stringify(normalized);
+}
 export function claimsToCid(claims) {
     const canonicalJson = canonicalizeClaimsForCid(claims);
     const cidData = buildCidV1FromCanonicalJson(canonicalJson, DEFAULT_MULTICODEC_DAG_JSON);
@@ -104,6 +163,22 @@ export function claimsToCid(claims) {
         digestHex: cidData.digestHex,
     };
 }
+/**
+ * Builds a content-addressed CID from flat claims after removing envelope,
+ * identifier, and version fields that should not affect semantic equality.
+ *
+ * Use this helper when the question is "does this document/resource content
+ * already exist?" rather than "what is the logical identifier of this object?".
+ */
+export function claimsToContentCid(claims, options = {}) {
+    const canonicalJson = canonicalizeClaimsForContentHash(claims, options);
+    const cidData = buildCidV1FromCanonicalJson(canonicalJson, DEFAULT_MULTICODEC_DAG_JSON);
+    return {
+        cid: cidData.cid,
+        canonicalJson,
+        digestHex: cidData.digestHex,
+    };
+}
 export function assignCidToClaimsId(claims) {
     const out = JSON.parse(JSON.stringify(claims || {}));
     const { cid } = claimsToCid(out);

package/dist/utils/index.d.ts

@@ -4,13 +4,11 @@ export * from './base-convert';
 export * from './baseN';
 export * from './bundle';
 export * from './bundle-query';
+export * from '../claims';
 export * from './content';
-export * from './claim-list-helpers';
+export * from '../convert';
+export * from './bundle-document-builder';
 export * from './consent';
-export * from './consent-claim-helpers';
-export * from './condition-claim-helpers';
-export * from './medication-claim-helpers';
-export * from './allergy-intolerance-claim-helpers';
 export * from './did';
 export * from './did-resolution';
 export * from './dataspace-discovery';
@@ -23,7 +21,6 @@ export * from './discovery-normalization';
 export * from './format-converter';
 export * from './fhir-cid';
 export * from './communication-fhir-r4';
-export * from './communication-claim-helpers';
 export * from './communication-document-reference';
 export * from './communication-bundle-document-request';
 export * from './communication-identity';
@@ -32,6 +29,7 @@ export * from './clinical-resource-converters';
 export * from './clinical-resource-view';
 export * from './fhir-validator';
 export * from './individual-form-pdf';
+export * from './ips-bundle-claims';
 export * from './jwt';
 export * from './manager-error';
 export * from './multibase58';

package/dist/utils/index.js

@@ -4,13 +4,11 @@ export * from './base-convert.js';
 export * from './baseN.js';
 export * from './bundle.js';
 export * from './bundle-query.js';
+export * from '../claims/index.js';
 export * from './content.js';
-export * from './claim-list-helpers.js';
+export * from '../convert/index.js';
+export * from './bundle-document-builder.js';
 export * from './consent.js';
-export * from './consent-claim-helpers.js';
-export * from './condition-claim-helpers.js';
-export * from './medication-claim-helpers.js';
-export * from './allergy-intolerance-claim-helpers.js';
 export * from './did.js';
 export * from './did-resolution.js';
 export * from './dataspace-discovery.js';
@@ -23,7 +21,6 @@ export * from './discovery-normalization.js';
 export * from './format-converter.js';
 export * from './fhir-cid.js';
 export * from './communication-fhir-r4.js';
-export * from './communication-claim-helpers.js';
 export * from './communication-document-reference.js';
 export * from './communication-bundle-document-request.js';
 export * from './communication-identity.js';
@@ -32,6 +29,7 @@ export * from './clinical-resource-converters.js';
 export * from './clinical-resource-view.js';
 export * from './fhir-validator.js';
 export * from './individual-form-pdf.js';
+export * from './ips-bundle-claims.js';
 export * from './jwt.js';
 export * from './manager-error.js';
 export * from './multibase58.js';

package/dist/utils/ips-bundle-claims.d.ts

@@ -0,0 +1,52 @@
+import type { BundleEntry, BundleEntryResource } from '../models/bundle.js';
+export declare const DEFAULT_META_CLAIM_TAG_SYSTEM = "urn:gdc:fhir:meta-claim";
+export type BundleLike = Readonly<{
+    resourceType?: string;
+    type?: string;
+    entry?: readonly BundleEntry[];
+    data?: readonly BundleEntry[];
+}>;
+export type ResourceMetaClaimsExtraction = Readonly<{
+    resourceType: string;
+    fullUrl?: string;
+    claims: Record<string, unknown>;
+}>;
+export type FhirMetaTagCoding = Readonly<{
+    system: string;
+    code: string;
+    display?: string;
+}>;
+/**
+ * Removes the versioned/contextualized FHIR prefix from a flattened claim key.
+ *
+ * Examples:
+ * - `org.hl7.fhir.r4.Immunization.vaccine-code` -> `Immunization.vaccine-code`
+ * - `org.hl7.fhir.api.MedicationStatement.subject` -> `MedicationStatement.subject`
+ * - `Consent.identifier` -> `Consent.identifier`
+ */
+export declare function toVersionAgnosticMetaClaimKey(claimKey: string): string;
+/**
+ * Extracts all `resource.meta.claims` blocks from a FHIR/JSON:API bundle.
+ *
+ * This is intentionally claims-first: only resources that already carry
+ * `resource.meta.claims` are returned.
+ */
+export declare function extractResourceMetaClaimsFromBundle(bundle: BundleLike): ResourceMetaClaimsExtraction[];
+/**
+ * Builds FHIR `meta.tag[]` codings from a flat claims record.
+ *
+ * The generated `code` is version-agnostic so UI/frontends can use the same
+ * tag keys across `org.hl7.fhir.r4.*` and `org.hl7.fhir.api.*` payloads.
+ */
+export declare function createFhirMetaTagsFromClaims(claims: Record<string, unknown>, options?: Readonly<{
+    system?: string;
+    includeContext?: boolean;
+}>): FhirMetaTagCoding[];
+/**
+ * Returns a shallow resource copy whose `meta.tag[]` is derived from
+ * `resource.meta.claims`.
+ */
+export declare function withDerivedFhirMetaTagsFromClaims<T extends BundleEntryResource>(resource: T, options?: Readonly<{
+    system?: string;
+    includeContext?: boolean;
+}>): T;