gdc-common-utils-ts 2.9.21 → 2.9.23

package/README.md

@@ -335,6 +335,15 @@ import {
 } from 'gdc-common-utils-ts/claims/claims-helpers-medication-statement';
 ```
 
+For every `<ResourceType>.<name>` key, canonical names are exactly the search
+parameters published in that resource's official FHIR `#search` section. Other
+keys must be identified as either FHIR standard extensions or custom
+extensions. See the complete per-resource search and extension references in
+[FHIR-like flat claim origin contract](docs/FHIR-LIKE-FLAT-CLAIMS.md).
+That contract also links the applicable IPS 2.0.1 profiles and ValueSets that
+govern supported creation fields, card presentation and coded values, plus the
+IPS Server CapabilityStatement that defines the server interaction surface.
+
 ### Models
 
 The `models` export contains the shared data shapes used by the SDKs, including:
@@ -509,9 +518,9 @@ The canonical API contract should live in JSDoc on exported code. The README act
 - [`validateCommunicationResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
   - Validates FHIR R4 `Communication` resources.
 - [`transformCommunicationClaimsToResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
-  - Converts canonical communication claims into FHIR R4 resources.
+  - Converts flat communication claims into FHIR R4 resources.
 - [`extractCommunicationClaimsFromResourceFhirR4(...)`](src/utils/communication-fhir-r4.ts)
-  - Extracts canonical claims from FHIR R4 `Communication`.
+  - Extracts flat claims from FHIR R4 `Communication`.
 - [`detectAttachmentKind(...)`](src/utils/communication-document-reference.ts)
   - Detects `fhir` / `pdf` / `png` / `jpg` / `binary` from MIME type.
 - [`buildDocumentReferenceFromCommunicationPayload(...)`](src/utils/communication-document-reference.ts)

package/dist/examples/consent-access.d.ts

@@ -4,6 +4,7 @@ export declare const EXAMPLE_INDIVIDUAL_DID_WEB: string;
 export declare const EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB: "did:web:hospital.acme.org";
 export { EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_EMAIL_RELATED_PERSON };
 export declare const EXAMPLE_CONSENT_ACCESS_JURISDICTION: "ES";
+export declare const EXAMPLE_CONSENT_ACCESS_COUNTRY_ACTOR_IDENTIFIER: string;
 /**
  * Legacy compatibility aliases kept so older docs/tests/imports continue to work
  * while the canonical variable names converge.

package/dist/examples/consent-access.js

@@ -8,6 +8,7 @@ export const EXAMPLE_INDIVIDUAL_DID_WEB = EXAMPLE_SUBJECT_DID;
 export const EXAMPLE_PROVIDER_ORGANIZATION_DID_WEB = EXAMPLE_PROVIDER_ORGANIZATION_DID;
 export { EXAMPLE_EMAIL_PROFESSIONAL, EXAMPLE_EMAIL_RELATED_PERSON };
 export const EXAMPLE_CONSENT_ACCESS_JURISDICTION = EXAMPLE_HEALTHCARE_JURISDICTION;
+export const EXAMPLE_CONSENT_ACCESS_COUNTRY_ACTOR_IDENTIFIER = `urn:iso:3166:${EXAMPLE_CONSENT_ACCESS_JURISDICTION}`;
 /**
  * Legacy compatibility aliases kept so older docs/tests/imports continue to work
  * while the canonical variable names converge.

package/dist/models/interoperable-claims/communication-claims.d.ts

@@ -1,5 +1,5 @@
 /**
- * Canonical flat claim keys for FHIR `Communication`.
+ * FHIR-like flat claim keys for FHIR `Communication`.
  *
  * Good practice note:
  * - any code, examples, scripts, or tests that write/read reusable

package/dist/models/interoperable-claims/communication-claims.js

@@ -2,7 +2,7 @@
 // Always create JSDoc, do not use strings inline in keys nor values, use types instead, and reuse the data test examples.
 // File: src/models/interoperable-claims/communication-claims.ts
 /**
- * Canonical flat claim keys for FHIR `Communication`.
+ * FHIR-like flat claim keys for FHIR `Communication`.
  *
  * Good practice note:
  * - any code, examples, scripts, or tests that write/read reusable

package/dist/models/interoperable-claims/flag-claims.d.ts

@@ -14,6 +14,23 @@ export declare const FlagClaim: {
     readonly CodeDisplay: "Flag.code-display";
     readonly PeriodStart: "Flag.period-start";
     readonly PeriodEnd: "Flag.period-end";
+    readonly Detail: "Flag.flag-detail";
+    readonly Priority: "Flag.flag-priority";
 };
 export type FlagClaimKey = typeof FlagClaim[keyof typeof FlagClaim];
+export declare const FlagStandardExtensionClaimSpecs: readonly [{
+    readonly key: "Flag.flag-detail";
+    readonly meaning: "References to information that explains the flag in more detail.";
+    readonly example: "Condition/condition-1";
+    readonly origin: "fhir-standard-extension";
+    readonly canonicalUrl: "http://hl7.org/fhir/StructureDefinition/flag-detail";
+    readonly fhirType: "Reference";
+}, {
+    readonly key: "Flag.flag-priority";
+    readonly meaning: "Alarm priority code; Must Support in the IPS Flag profile.";
+    readonly example: "http://hl7.org/fhir/flag-priority-code|PH";
+    readonly origin: "fhir-standard-extension";
+    readonly canonicalUrl: "http://hl7.org/fhir/StructureDefinition/flag-priority";
+    readonly fhirType: "CodeableConcept";
+}];
 export declare const FlagClaimSpecs: ClaimSpec[];

package/dist/models/interoperable-claims/flag-claims.js

@@ -15,8 +15,10 @@ export const FlagClaim = {
     CodeDisplay: 'Flag.code-display',
     PeriodStart: 'Flag.period-start',
     PeriodEnd: 'Flag.period-end',
+    Detail: 'Flag.flag-detail',
+    Priority: 'Flag.flag-priority',
 };
-export const FlagClaimSpecs = [
+const FlagBaseClaimSpecs = [
     { key: FlagClaim.Author, meaning: 'Author reference.', example: 'Practitioner/prac-1' },
     { key: FlagClaim.Date, meaning: 'Flag issue date/time.', example: '2026-06-01T10:00:00Z' },
     { key: FlagClaim.Encounter, meaning: 'Encounter reference.', example: 'Encounter/enc-1' },
@@ -24,10 +26,32 @@ export const FlagClaimSpecs = [
     { key: FlagClaim.Patient, meaning: 'Patient reference.', example: 'did:web:patient.example.org' },
     { key: FlagClaim.Subject, meaning: 'Canonical subject reference.', example: 'did:web:patient.example.org' },
     { key: FlagClaim.Status, meaning: 'Flag status.', example: 'active' },
-    { key: FlagClaim.Category, meaning: 'Flag category token.', example: 'http://terminology.hl7.org/CodeSystem/flag-category|safety' },
-    { key: FlagClaim.Code, meaning: 'Flag code token.', example: 'http://loinc.org|104605-1' },
+    { key: FlagClaim.Category, meaning: 'Flag category token.', example: 'http://terminology.hl7.org/CodeSystem/flag-category|contact' },
+    { key: FlagClaim.Code, meaning: 'Flag code token; distinct from the IPS Alerts section code.', example: 'http://snomed.info/sct|370388006' },
     { key: FlagClaim.CodeText, meaning: 'Local-language alert name matching resource language.', example: 'Dieta sin marisco' },
     { key: FlagClaim.CodeDisplay, meaning: 'English/international terminology display.', example: 'Shellfish free diet' },
     { key: FlagClaim.PeriodStart, meaning: 'Flag period start.', example: '2026-06-01T10:00:00Z' },
     { key: FlagClaim.PeriodEnd, meaning: 'Flag period end.', example: '2026-07-01T10:00:00Z' },
 ];
+export const FlagStandardExtensionClaimSpecs = [
+    {
+        key: FlagClaim.Detail,
+        meaning: 'References to information that explains the flag in more detail.',
+        example: 'Condition/condition-1',
+        origin: 'fhir-standard-extension',
+        canonicalUrl: 'http://hl7.org/fhir/StructureDefinition/flag-detail',
+        fhirType: 'Reference',
+    },
+    {
+        key: FlagClaim.Priority,
+        meaning: 'Alarm priority code; Must Support in the IPS Flag profile.',
+        example: 'http://hl7.org/fhir/flag-priority-code|PH',
+        origin: 'fhir-standard-extension',
+        canonicalUrl: 'http://hl7.org/fhir/StructureDefinition/flag-priority',
+        fhirType: 'CodeableConcept',
+    },
+];
+export const FlagClaimSpecs = [
+    ...FlagBaseClaimSpecs,
+    ...FlagStandardExtensionClaimSpecs,
+];

package/dist/models/interoperable-claims/index.d.ts

@@ -1,4 +1,5 @@
 export * from './types.js';
+export * from './ips-profile-catalog.js';
 export * from './composition-claims.js';
 export * from './communication-claims.js';
 export * from './document-reference-claims.js';

package/dist/models/interoperable-claims/index.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/index.ts
 export * from './types.js';
+export * from './ips-profile-catalog.js';
 export * from './composition-claims.js';
 export * from './communication-claims.js';
 export * from './document-reference-claims.js';

package/dist/models/interoperable-claims/invoice-claims.d.ts

@@ -1,6 +1,6 @@
 import type { ClaimSpec } from './types.js';
 /**
- * Canonical flat claim keys for invoice-level business data.
+ * FHIR-like flat claim keys for invoice-level business data.
  *
  * These claims are the claims-first source of truth. FHIR `Invoice` is one
  * downstream projection built from them.
@@ -107,6 +107,12 @@ export declare const ChargeItemClaim: {
     readonly Status: "ChargeItem.status";
     /** Parent business aggregate identifier. Example: `invoice-001`. */
     readonly PartOf: "ChargeItem.part-of";
+    /** Subject that received the chargeable service or item. */
+    readonly Subject: "ChargeItem.subject";
+    /** Date, date range or timing represented as the canonical search value. */
+    readonly Occurrence: "ChargeItem.occurrence";
+    /** Reference to supporting clinical or financial information. */
+    readonly SupportingInformation: "ChargeItem.supporting-information";
     /** Public code such as GTIN/UDI/barcode. Example: `08412345678903`. */
     readonly Code: "ChargeItem.code";
     /** Local-language UI/help label for the coded product. Example: `Sterile saline bottle 500 mL`. */
@@ -135,6 +141,9 @@ export interface ChargeItemClaims {
     [ChargeItemClaim.Identifier]?: string;
     [ChargeItemClaim.Status]?: string;
     [ChargeItemClaim.PartOf]?: string;
+    [ChargeItemClaim.Subject]?: string;
+    [ChargeItemClaim.Occurrence]?: string;
+    [ChargeItemClaim.SupportingInformation]?: string;
     [ChargeItemClaim.Code]?: string;
     [ChargeItemClaim.CodeText]?: string;
     [ChargeItemClaim.Category]?: string;
@@ -151,6 +160,9 @@ export declare enum ChargeItemClaimsFhirApiExtended {
     Identifier = "org.hl7.fhir.api.ChargeItem.identifier",
     Status = "org.hl7.fhir.api.ChargeItem.status",
     PartOf = "org.hl7.fhir.api.ChargeItem.part-of",
+    Subject = "org.hl7.fhir.api.ChargeItem.subject",
+    Occurrence = "org.hl7.fhir.api.ChargeItem.occurrence",
+    SupportingInformation = "org.hl7.fhir.api.ChargeItem.supporting-information",
     Code = "org.hl7.fhir.api.ChargeItem.code",
     CodeText = "org.hl7.fhir.api.ChargeItem.code-text",
     Category = "org.hl7.fhir.api.ChargeItem.category",
@@ -167,6 +179,9 @@ export declare const ChargeItemSearchParamNames: {
     readonly Identifier: "identifier";
     readonly Status: "status";
     readonly PartOf: "part-of";
+    readonly Subject: "subject";
+    readonly Occurrence: "occurrence";
+    readonly SupportingInformation: "supporting-information";
     readonly Code: "code";
     readonly CodeText: "code-text";
     readonly Category: "category";
@@ -198,6 +213,9 @@ export interface ChargeItemClaimsContextualized {
     [ChargeItemClaimsFhirApiExtended.Identifier]?: string;
     [ChargeItemClaimsFhirApiExtended.Status]?: string;
     [ChargeItemClaimsFhirApiExtended.PartOf]?: string;
+    [ChargeItemClaimsFhirApiExtended.Subject]?: string;
+    [ChargeItemClaimsFhirApiExtended.Occurrence]?: string;
+    [ChargeItemClaimsFhirApiExtended.SupportingInformation]?: string;
     [ChargeItemClaimsFhirApiExtended.Code]?: string;
     [ChargeItemClaimsFhirApiExtended.CodeText]?: string;
     [ChargeItemClaimsFhirApiExtended.Category]?: string;

package/dist/models/interoperable-claims/invoice-claims.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Conéctate Soluciones y Aplicaciones SL under the Apache License, Version 2.0.
 // File: src/models/interoperable-claims/invoice-claims.ts
 /**
- * Canonical flat claim keys for invoice-level business data.
+ * FHIR-like flat claim keys for invoice-level business data.
  *
  * These claims are the claims-first source of truth. FHIR `Invoice` is one
  * downstream projection built from them.
@@ -93,6 +93,12 @@ export const ChargeItemClaim = {
     Status: 'ChargeItem.status',
     /** Parent business aggregate identifier. Example: `invoice-001`. */
     PartOf: 'ChargeItem.part-of',
+    /** Subject that received the chargeable service or item. */
+    Subject: 'ChargeItem.subject',
+    /** Date, date range or timing represented as the canonical search value. */
+    Occurrence: 'ChargeItem.occurrence',
+    /** Reference to supporting clinical or financial information. */
+    SupportingInformation: 'ChargeItem.supporting-information',
     /** Public code such as GTIN/UDI/barcode. Example: `08412345678903`. */
     Code: 'ChargeItem.code',
     /** Local-language UI/help label for the coded product. Example: `Sterile saline bottle 500 mL`. */
@@ -121,6 +127,9 @@ export var ChargeItemClaimsFhirApiExtended;
     ChargeItemClaimsFhirApiExtended["Identifier"] = "org.hl7.fhir.api.ChargeItem.identifier";
     ChargeItemClaimsFhirApiExtended["Status"] = "org.hl7.fhir.api.ChargeItem.status";
     ChargeItemClaimsFhirApiExtended["PartOf"] = "org.hl7.fhir.api.ChargeItem.part-of";
+    ChargeItemClaimsFhirApiExtended["Subject"] = "org.hl7.fhir.api.ChargeItem.subject";
+    ChargeItemClaimsFhirApiExtended["Occurrence"] = "org.hl7.fhir.api.ChargeItem.occurrence";
+    ChargeItemClaimsFhirApiExtended["SupportingInformation"] = "org.hl7.fhir.api.ChargeItem.supporting-information";
     ChargeItemClaimsFhirApiExtended["Code"] = "org.hl7.fhir.api.ChargeItem.code";
     ChargeItemClaimsFhirApiExtended["CodeText"] = "org.hl7.fhir.api.ChargeItem.code-text";
     ChargeItemClaimsFhirApiExtended["Category"] = "org.hl7.fhir.api.ChargeItem.category";
@@ -137,6 +146,9 @@ export const ChargeItemSearchParamNames = {
     Identifier: 'identifier',
     Status: 'status',
     PartOf: 'part-of',
+    Subject: 'subject',
+    Occurrence: 'occurrence',
+    SupportingInformation: 'supporting-information',
     Code: 'code',
     CodeText: 'code-text',
     Category: 'category',
@@ -172,6 +184,9 @@ export const ChargeItemClaimSpecs = [
     { key: ChargeItemClaim.Identifier, meaning: 'Stable invoice line identifier.', example: 'chargeitem-001' },
     { key: ChargeItemClaim.Status, meaning: 'Charge item lifecycle status from FHIR ChargeItemStatus.', example: 'billable' },
     { key: ChargeItemClaim.PartOf, meaning: 'Parent business aggregate identifier.', example: 'invoice-001' },
+    { key: ChargeItemClaim.Subject, meaning: 'Subject receiving the charged item or service.', example: 'Patient/patient-1' },
+    { key: ChargeItemClaim.Occurrence, meaning: 'When the charged item or service occurred.', example: '2026-09-19' },
+    { key: ChargeItemClaim.SupportingInformation, meaning: 'Supporting clinical or financial resource reference.', example: 'Invoice/invoice-001' },
     { key: ChargeItemClaim.Code, meaning: 'Public code such as GTIN/UDI/barcode.', example: '08412345678903' },
     { key: ChargeItemClaim.CodeText, meaning: 'Local-language UI/help label for the coded product.', example: 'Botella de suero salino estéril 500 mL' },
     { key: ChargeItemClaim.Category, meaning: 'Normalized aggregate reporting category.', example: 'medical-supplies' },
@@ -221,6 +236,9 @@ export function contextualizeChargeItemClaims(claims) {
         ...(claims[ChargeItemClaim.Identifier] ? { [ChargeItemClaimsFhirApiExtended.Identifier]: claims[ChargeItemClaim.Identifier] } : {}),
         ...(claims[ChargeItemClaim.Status] ? { [ChargeItemClaimsFhirApiExtended.Status]: claims[ChargeItemClaim.Status] } : {}),
         ...(claims[ChargeItemClaim.PartOf] ? { [ChargeItemClaimsFhirApiExtended.PartOf]: claims[ChargeItemClaim.PartOf] } : {}),
+        ...(claims[ChargeItemClaim.Subject] ? { [ChargeItemClaimsFhirApiExtended.Subject]: claims[ChargeItemClaim.Subject] } : {}),
+        ...(claims[ChargeItemClaim.Occurrence] ? { [ChargeItemClaimsFhirApiExtended.Occurrence]: claims[ChargeItemClaim.Occurrence] } : {}),
+        ...(claims[ChargeItemClaim.SupportingInformation] ? { [ChargeItemClaimsFhirApiExtended.SupportingInformation]: claims[ChargeItemClaim.SupportingInformation] } : {}),
         ...(claims[ChargeItemClaim.Code] ? { [ChargeItemClaimsFhirApiExtended.Code]: claims[ChargeItemClaim.Code] } : {}),
         ...(claims[ChargeItemClaim.CodeText] ? { [ChargeItemClaimsFhirApiExtended.CodeText]: claims[ChargeItemClaim.CodeText] } : {}),
         ...(claims[ChargeItemClaim.Category] ? { [ChargeItemClaimsFhirApiExtended.Category]: claims[ChargeItemClaim.Category] } : {}),

package/dist/models/interoperable-claims/ips-profile-catalog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Executable IPS 2.0.1 field, type, obligation and terminology contract.
+ *
+ * Generated from the official `hl7.fhir.uv.ips#2.0.1` and
+ * `hl7.fhir.r4.core#4.0.1` packages. Regenerate with
+ * `scripts/generate-ips-profile-catalog.mjs`.
+ */
+import { IPS_CANONICAL_FLAT_CLAIMS_BY_RESOURCE } from './ips-profile-catalog.generated/index.js';
+export * from './ips-profile-types.js';
+export * from './ips-profile-catalog.generated/index.js';
+export type IpsResourceType = keyof typeof IPS_CANONICAL_FLAT_CLAIMS_BY_RESOURCE;
+export type IpsCanonicalFlatClaim<Resource extends IpsResourceType = IpsResourceType> = (typeof IPS_CANONICAL_FLAT_CLAIMS_BY_RESOURCE)[Resource][number];