gdc-common-utils-ts 1.21.0 → 1.23.0

package/dist/constants/fhir-resource-types.d.ts

@@ -25,6 +25,7 @@ export declare const ResourceTypesFhirR4: Readonly<{
     readonly Flag: "Flag";
     readonly ImagingStudy: "ImagingStudy";
     readonly Immunization: "Immunization";
+    readonly Invoice: "Invoice";
     readonly Location: "Location";
     readonly MedicationStatement: "MedicationStatement";
     readonly Observation: "Observation";
@@ -59,6 +60,7 @@ export declare const FhirResourceTypes: Readonly<{
     readonly Flag: "Flag";
     readonly ImagingStudy: "ImagingStudy";
     readonly Immunization: "Immunization";
+    readonly Invoice: "Invoice";
     readonly Location: "Location";
     readonly MedicationStatement: "MedicationStatement";
     readonly Observation: "Observation";

package/dist/constants/fhir-resource-types.js

@@ -25,6 +25,7 @@ export const ResourceTypesFhirR4 = Object.freeze({
     Flag: 'Flag',
     ImagingStudy: 'ImagingStudy',
     Immunization: 'Immunization',
+    Invoice: 'Invoice',
     Location: 'Location',
     MedicationStatement: 'MedicationStatement',
     Observation: 'Observation',

package/dist/examples/index.d.ts

@@ -6,6 +6,7 @@ export * from './individual-controller';
 export * from './professional';
 export * from './employee';
 export * from './license';
+export * from './invoice';
 export * from './related-person';
 export * from './consent-access';
 export * from './relationship-access';

package/dist/examples/index.js

@@ -6,6 +6,7 @@ export * from './individual-controller.js';
 export * from './professional.js';
 export * from './employee.js';
 export * from './license.js';
+export * from './invoice.js';
 export * from './related-person.js';
 export * from './consent-access.js';
 export * from './relationship-access.js';

package/dist/examples/invoice.d.ts

@@ -0,0 +1,37 @@
+export declare const EXAMPLE_INVOICE_PDF_DOCUMENT: Readonly<{
+    readonly documentId: "invoice-001-pdf";
+    readonly contentType: "application/pdf";
+    readonly title: "invoice-001.pdf";
+    readonly description: "Human-readable invoice PDF";
+    readonly language: "en";
+    readonly dataBase64: "JVBERi0xLjQKJUZha2UgaW52b2ljZSBQREYK";
+    readonly createdAt: "2026-06-11T10:00:00Z";
+}>;
+export declare const EXAMPLE_INVOICE_JSON_DOCUMENT: Readonly<{
+    readonly documentId: "invoice-001-json";
+    readonly contentType: "application/json";
+    readonly title: "invoice-001.json";
+    readonly description: "Structured invoice JSON";
+    readonly language: "en";
+    readonly dataBase64: "eyJpbnZvaWNlSWQiOiJpbnZvaWNlLTAwMSJ9";
+    readonly createdAt: "2026-06-11T10:00:00Z";
+}>;
+export declare const EXAMPLE_INVOICE_BUNDLE: Readonly<Record<string, unknown>>;
+export declare const EXAMPLE_INVOICE_CHARGE_ITEM_ROW_A: Readonly<{
+    readonly identifier: "chargeitem-001";
+    readonly status: "billable";
+    readonly partOf: "invoice-001";
+    readonly code: "08412345678903";
+    readonly codeText: "Botella de suero salino estéril 500 mL";
+    readonly category: "medical-supplies";
+    readonly supplierProductCode: "IMP-SAL-500";
+    readonly quantity: "3|bottle";
+    readonly quantityNumber: "3";
+    readonly quantityUnit: "bottle";
+    readonly itemsPerUnit: "24";
+    readonly itemsQuantity: "500|mL";
+    readonly itemsQuantityNumber: "500";
+    readonly itemsQuantityUnit: "mL";
+}>;
+export declare const EXAMPLE_INVOICE_FHIR_CLAIMS: Readonly<import("..").InvoiceClaims>;
+export declare const EXAMPLE_INVOICE_CHARGEITEM_FHIR_CLAIMS_ROWS: readonly (import("..").InvoiceClaims & import("..").ChargeItemClaims)[];

package/dist/examples/invoice.js

@@ -0,0 +1,72 @@
+import { EXAMPLE_INVOICE_CHARGEITEM_CATEGORY, EXAMPLE_INVOICE_CHARGEITEM_CODE_TEXT, EXAMPLE_INVOICE_CHARGEITEM_IDENTIFIER, EXAMPLE_INVOICE_CHARGEITEM_ITEMS_PER_UNIT, EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY, EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_NUMBER, EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_UNIT, EXAMPLE_INVOICE_CHARGEITEM_PART_OF, EXAMPLE_INVOICE_CHARGEITEM_PRODUCT_CODE, EXAMPLE_INVOICE_CHARGEITEM_QUANTITY, EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_NUMBER, EXAMPLE_INVOICE_CHARGEITEM_STATUS, EXAMPLE_INVOICE_CHARGEITEM_SUPPLIER_PRODUCT_CODE, EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_UNIT, EXAMPLE_API_ORGANIZATION_DID, EXAMPLE_CONTENT_TYPE_APPLICATION_JSON, EXAMPLE_DOCUMENT_REFERENCE_CONTENT_TYPE_PDF, EXAMPLE_DOCUMENT_REFERENCE_LANGUAGE, EXAMPLE_LICENSE_AMOUNT, EXAMPLE_LICENSE_INVOICE_ID, EXAMPLE_LICENSE_PAYMENT_METHOD_INVOICE, EXAMPLE_LICENSE_PAYMENT_URL, EXAMPLE_LICENSE_CURRENCY, EXAMPLE_SUBJECT_DID, EXAMPLE_INVOICE_DATE, EXAMPLE_VAULT_PRIMARY_DATE_TIME, } from './shared.js';
+import { createInvoiceBundleEditor } from '../utils/invoice-bundle.js';
+export const EXAMPLE_INVOICE_PDF_DOCUMENT = Object.freeze({
+    documentId: `${EXAMPLE_LICENSE_INVOICE_ID}-pdf`,
+    contentType: EXAMPLE_DOCUMENT_REFERENCE_CONTENT_TYPE_PDF,
+    title: `${EXAMPLE_LICENSE_INVOICE_ID}.pdf`,
+    description: 'Human-readable invoice PDF',
+    language: EXAMPLE_DOCUMENT_REFERENCE_LANGUAGE,
+    dataBase64: 'JVBERi0xLjQKJUZha2UgaW52b2ljZSBQREYK',
+    createdAt: EXAMPLE_VAULT_PRIMARY_DATE_TIME,
+});
+export const EXAMPLE_INVOICE_JSON_DOCUMENT = Object.freeze({
+    documentId: `${EXAMPLE_LICENSE_INVOICE_ID}-json`,
+    contentType: EXAMPLE_CONTENT_TYPE_APPLICATION_JSON,
+    title: `${EXAMPLE_LICENSE_INVOICE_ID}.json`,
+    description: 'Structured invoice JSON',
+    language: EXAMPLE_DOCUMENT_REFERENCE_LANGUAGE,
+    dataBase64: 'eyJpbnZvaWNlSWQiOiJpbnZvaWNlLTAwMSJ9',
+    createdAt: EXAMPLE_VAULT_PRIMARY_DATE_TIME,
+});
+export const EXAMPLE_INVOICE_BUNDLE = Object.freeze(createInvoiceBundleEditor()
+    .setInvoiceId(EXAMPLE_LICENSE_INVOICE_ID)
+    .setSubjectReference(EXAMPLE_SUBJECT_DID)
+    .setIssuerReference(EXAMPLE_API_ORGANIZATION_DID)
+    .setRecipientReference(EXAMPLE_SUBJECT_DID)
+    .setIssuedAt(EXAMPLE_INVOICE_DATE)
+    .setAmount(EXAMPLE_LICENSE_AMOUNT)
+    .setCurrency(EXAMPLE_LICENSE_CURRENCY)
+    .setPaymentMethod(EXAMPLE_LICENSE_PAYMENT_METHOD_INVOICE)
+    .setPaymentUrl(EXAMPLE_LICENSE_PAYMENT_URL)
+    .setPdfDocument(EXAMPLE_INVOICE_PDF_DOCUMENT)
+    .setStructuredDocument(EXAMPLE_INVOICE_JSON_DOCUMENT)
+    .buildBundle());
+export const EXAMPLE_INVOICE_CHARGE_ITEM_ROW_A = Object.freeze({
+    identifier: EXAMPLE_INVOICE_CHARGEITEM_IDENTIFIER,
+    status: EXAMPLE_INVOICE_CHARGEITEM_STATUS,
+    partOf: EXAMPLE_INVOICE_CHARGEITEM_PART_OF,
+    code: EXAMPLE_INVOICE_CHARGEITEM_PRODUCT_CODE,
+    codeText: EXAMPLE_INVOICE_CHARGEITEM_CODE_TEXT,
+    category: EXAMPLE_INVOICE_CHARGEITEM_CATEGORY,
+    supplierProductCode: EXAMPLE_INVOICE_CHARGEITEM_SUPPLIER_PRODUCT_CODE,
+    quantity: EXAMPLE_INVOICE_CHARGEITEM_QUANTITY,
+    quantityNumber: EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_NUMBER,
+    quantityUnit: EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_UNIT,
+    itemsPerUnit: EXAMPLE_INVOICE_CHARGEITEM_ITEMS_PER_UNIT,
+    itemsQuantity: EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY,
+    itemsQuantityNumber: EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_NUMBER,
+    itemsQuantityUnit: EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_UNIT,
+});
+export const EXAMPLE_INVOICE_FHIR_CLAIMS = Object.freeze(createInvoiceBundleEditor()
+    .setInvoiceId(EXAMPLE_LICENSE_INVOICE_ID)
+    .setSubjectReference(EXAMPLE_SUBJECT_DID)
+    .setIssuerReference(EXAMPLE_API_ORGANIZATION_DID)
+    .setRecipientReference(EXAMPLE_SUBJECT_DID)
+    .setIssuedAt(EXAMPLE_INVOICE_DATE)
+    .setAmount(EXAMPLE_LICENSE_AMOUNT)
+    .setCurrency(EXAMPLE_LICENSE_CURRENCY)
+    .setPaymentMethod(EXAMPLE_LICENSE_PAYMENT_METHOD_INVOICE)
+    .setPaymentUrl(EXAMPLE_LICENSE_PAYMENT_URL)
+    .buildInvoiceClaims());
+export const EXAMPLE_INVOICE_CHARGEITEM_FHIR_CLAIMS_ROWS = Object.freeze(createInvoiceBundleEditor()
+    .setInvoiceId(EXAMPLE_LICENSE_INVOICE_ID)
+    .setSubjectReference(EXAMPLE_SUBJECT_DID)
+    .setIssuerReference(EXAMPLE_API_ORGANIZATION_DID)
+    .setRecipientReference(EXAMPLE_SUBJECT_DID)
+    .setIssuedAt(EXAMPLE_INVOICE_DATE)
+    .setAmount(EXAMPLE_LICENSE_AMOUNT)
+    .setCurrency(EXAMPLE_LICENSE_CURRENCY)
+    .setPaymentMethod(EXAMPLE_LICENSE_PAYMENT_METHOD_INVOICE)
+    .setPaymentUrl(EXAMPLE_LICENSE_PAYMENT_URL)
+    .addChargeItem(EXAMPLE_INVOICE_CHARGE_ITEM_ROW_A)
+    .buildChargeItemClaimRows());

package/dist/examples/shared.d.ts

@@ -208,6 +208,22 @@ export declare const EXAMPLE_LICENSE_PAYMENT_METHOD_INVOICE: "invoice";
 export declare const EXAMPLE_LICENSE_CHECKOUT_URL: "https://pay.example/offer-001";
 export declare const EXAMPLE_LICENSE_PAYMENT_URL: "https://pay.example/invoice-001";
 export declare const EXAMPLE_LICENSE_INVOICE_ID: "invoice-001";
+export declare const EXAMPLE_INVOICE_DATE: "2026-06-11T10:00:00Z";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_PRODUCT_CODE: "08412345678903";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_PRODUCT_NAME: "Sterile saline bottle 500 mL";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_CATEGORY: "medical-supplies";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_SUPPLIER_PRODUCT_CODE: "IMP-SAL-500";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_IDENTIFIER: "chargeitem-001";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_STATUS: "billable";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_PART_OF: "invoice-001";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_QUANTITY: "3|bottle";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_NUMBER: "3";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_UNIT: "bottle";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_CODE_TEXT: "Botella de suero salino est\u00E9ril 500 mL";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_PER_UNIT: "24";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY: "500|mL";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_NUMBER: "500";
+export declare const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_UNIT: "mL";
 export declare const EXAMPLE_LICENSE_PLAN_DEFAULT: "default";
 export declare const EXAMPLE_LICENSE_RENEWAL_CYCLE_YEARLY: "12m";
 export declare const EXAMPLE_LICENSE_SUBJECT_ID_ACTIVE: "urn:uuid:employee-controller-active-001";

package/dist/examples/shared.js

@@ -221,6 +221,22 @@ export const EXAMPLE_LICENSE_PAYMENT_METHOD_INVOICE = 'invoice';
 export const EXAMPLE_LICENSE_CHECKOUT_URL = 'https://pay.example/offer-001';
 export const EXAMPLE_LICENSE_PAYMENT_URL = 'https://pay.example/invoice-001';
 export const EXAMPLE_LICENSE_INVOICE_ID = 'invoice-001';
+export const EXAMPLE_INVOICE_DATE = '2026-06-11T10:00:00Z';
+export const EXAMPLE_INVOICE_CHARGEITEM_PRODUCT_CODE = '08412345678903';
+export const EXAMPLE_INVOICE_CHARGEITEM_PRODUCT_NAME = 'Sterile saline bottle 500 mL';
+export const EXAMPLE_INVOICE_CHARGEITEM_CATEGORY = 'medical-supplies';
+export const EXAMPLE_INVOICE_CHARGEITEM_SUPPLIER_PRODUCT_CODE = 'IMP-SAL-500';
+export const EXAMPLE_INVOICE_CHARGEITEM_IDENTIFIER = 'chargeitem-001';
+export const EXAMPLE_INVOICE_CHARGEITEM_STATUS = 'billable';
+export const EXAMPLE_INVOICE_CHARGEITEM_PART_OF = EXAMPLE_LICENSE_INVOICE_ID;
+export const EXAMPLE_INVOICE_CHARGEITEM_QUANTITY = '3|bottle';
+export const EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_NUMBER = '3';
+export const EXAMPLE_INVOICE_CHARGEITEM_QUANTITY_UNIT = 'bottle';
+export const EXAMPLE_INVOICE_CHARGEITEM_CODE_TEXT = 'Botella de suero salino estéril 500 mL';
+export const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_PER_UNIT = '24';
+export const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY = '500|mL';
+export const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_NUMBER = '500';
+export const EXAMPLE_INVOICE_CHARGEITEM_ITEMS_QUANTITY_UNIT = 'mL';
 export const EXAMPLE_LICENSE_PLAN_DEFAULT = 'default';
 export const EXAMPLE_LICENSE_RENEWAL_CYCLE_YEARLY = '12m';
 export const EXAMPLE_LICENSE_SUBJECT_ID_ACTIVE = 'urn:uuid:employee-controller-active-001';

package/dist/models/fhir-documents.d.ts

@@ -23,6 +23,10 @@ export type FhirAttachment = {
     url?: string;
     title?: string;
     creation?: string;
+    hash?: string;
+};
+export type FhirMeta = {
+    claims?: Record<string, unknown>;
 };
 export interface FhirCompositionResource {
     resourceType: 'Composition';
@@ -46,6 +50,7 @@ export interface FhirCompositionResource {
 export interface FhirDocumentReferenceResource {
     resourceType: 'DocumentReference';
     id?: string;
+    meta?: FhirMeta;
     status?: string;
     identifier?: Array<{
         system?: string;
@@ -81,9 +86,39 @@ export interface FhirDocumentReferenceResource {
         format?: FhirCoding;
     }>;
 }
+export interface FhirInvoiceResource {
+    resourceType: 'Invoice';
+    id?: string;
+    meta?: FhirMeta;
+    status?: string;
+    identifier?: Array<{
+        system?: string;
+        value?: string;
+    }>;
+    subject?: FhirReference;
+    recipient?: FhirReference;
+    issuer?: {
+        reference?: string;
+        display?: string;
+    };
+    date?: string;
+    paymentTerms?: string;
+    note?: Array<{
+        text?: string;
+    }>;
+    totalNet?: {
+        value?: number;
+        currency?: string;
+    };
+    totalGross?: {
+        value?: number;
+        currency?: string;
+    };
+}
 export interface FhirCommunicationResource {
     resourceType: 'Communication';
     id?: string;
+    meta?: FhirMeta;
     status?: string;
     category?: FhirCodeableConcept[];
     subject?: FhirReference;

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

@@ -22,3 +22,4 @@ export * from './related-person-claims';
 export * from './coverage-claims';
 export * from './clinical-impression-claims';
 export * from './task-claims';
+export * from './invoice-claims';

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

@@ -24,3 +24,4 @@ export * from './related-person-claims.js';
 export * from './coverage-claims.js';
 export * from './clinical-impression-claims.js';
 export * from './task-claims.js';
+export * from './invoice-claims.js';

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

@@ -0,0 +1,277 @@
+import type { ClaimSpec } from './types';
+/**
+ * Canonical 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.
+ */
+export declare const InvoiceClaim: {
+    /** Stable business invoice identifier. Example: `invoice-001`. */
+    readonly Identifier: "Invoice.identifier";
+    /** Invoice issue date/time. Example: `2026-06-11T10:00:00Z`. */
+    readonly Date: "Invoice.date";
+    /** Invoice lifecycle status. Example: `issued`. */
+    readonly Status: "Invoice.status";
+    /** Subject or tenant context reference. Example: `did:web:api.acme.org:individual:123`. */
+    readonly Subject: "Invoice.subject";
+    /** Billed recipient reference. Example: `did:web:portal.example.org:billing`. */
+    readonly Recipient: "Invoice.recipient";
+    /** Invoice issuer reference. Example: `did:web:api.acme.org`. */
+    readonly Issuer: "Invoice.issuer";
+    /** Human-readable issuer label. Example: `Gateway Host Services`. */
+    readonly IssuerDisplay: "Invoice.issuer-display";
+    /** Commercial payment method/terms. Example: `invoice`. */
+    readonly PaymentTerms: "Invoice.payment-terms";
+    /** Payment or settlement URL when available. Example: `https://pay.example/invoice-001`. */
+    readonly PaymentUrl: "Invoice.payment-url";
+    /** Net amount numeric value serialized as string. Example: `9.99`. */
+    readonly TotalNetValue: "Invoice.totalnet-value";
+    /** Net amount ISO currency. Example: `EUR`. */
+    readonly TotalNetCurrency: "Invoice.totalnet-currency";
+    /** Gross amount numeric value serialized as string. Example: `9.99`. */
+    readonly TotalGrossValue: "Invoice.totalgross-value";
+    /** Gross amount ISO currency. Example: `EUR`. */
+    readonly TotalGrossCurrency: "Invoice.totalgross-currency";
+};
+export type InvoiceClaimKey = typeof InvoiceClaim[keyof typeof InvoiceClaim];
+export interface InvoiceClaims {
+    [InvoiceClaim.Identifier]?: string;
+    [InvoiceClaim.Date]?: string;
+    [InvoiceClaim.Status]?: string;
+    [InvoiceClaim.Subject]?: string;
+    [InvoiceClaim.Recipient]?: string;
+    [InvoiceClaim.Issuer]?: string;
+    [InvoiceClaim.IssuerDisplay]?: string;
+    [InvoiceClaim.PaymentTerms]?: string;
+    [InvoiceClaim.PaymentUrl]?: string;
+    [InvoiceClaim.TotalNetValue]?: string;
+    [InvoiceClaim.TotalNetCurrency]?: string;
+    [InvoiceClaim.TotalGrossValue]?: string;
+    [InvoiceClaim.TotalGrossCurrency]?: string;
+}
+/**
+ * Contextualized FHIR-API-like invoice claims.
+ *
+ * Convention:
+ * - `org.hl7.fhir.api.Invoice.<concrete-parameter>`
+ * - scalar/string-friendly values only
+ * - invoice totals/payment URL remain extension-style operational claims
+ *   because not every business field maps to one native FHIR search parameter
+ */
+export declare enum InvoiceClaimsFhirApiExtended {
+    Identifier = "org.hl7.fhir.api.Invoice.identifier",
+    Date = "org.hl7.fhir.api.Invoice.date",
+    Status = "org.hl7.fhir.api.Invoice.status",
+    Subject = "org.hl7.fhir.api.Invoice.subject",
+    Recipient = "org.hl7.fhir.api.Invoice.recipient",
+    Issuer = "org.hl7.fhir.api.Invoice.issuer",
+    IssuerDisplay = "org.hl7.fhir.api.Invoice.issuer-display",
+    PaymentTerms = "org.hl7.fhir.api.Invoice.payment-terms",
+    PaymentUrl = "org.hl7.fhir.api.Invoice.payment-url",
+    TotalNetValue = "org.hl7.fhir.api.Invoice.totalnet-value",
+    TotalNetCurrency = "org.hl7.fhir.api.Invoice.totalnet-currency",
+    TotalGrossValue = "org.hl7.fhir.api.Invoice.totalgross-value",
+    TotalGrossCurrency = "org.hl7.fhir.api.Invoice.totalgross-currency"
+}
+/**
+ * Canonical non-contextualized parameter names for query builders and readers.
+ */
+export declare const InvoiceSearchParamNames: {
+    readonly Identifier: "identifier";
+    readonly Date: "date";
+    readonly Status: "status";
+    readonly Subject: "subject";
+    readonly Recipient: "recipient";
+    readonly Issuer: "issuer";
+    readonly IssuerDisplay: "issuer-display";
+    readonly PaymentTerms: "payment-terms";
+    readonly PaymentUrl: "payment-url";
+    readonly TotalNetValue: "totalnet-value";
+    readonly TotalNetCurrency: "totalnet-currency";
+    readonly TotalGrossValue: "totalgross-value";
+    readonly TotalGrossCurrency: "totalgross-currency";
+};
+/**
+ * Charge-item-level claims used when one business invoice line is represented
+ * as one claims row. The future FHIR export can compact multiple rows sharing
+ * one invoice identifier into a single `Invoice` with multiple items.
+ *
+ * Note:
+ * - FHIR `Invoice` does not expose all these details as search parameters.
+ * - `ChargeItem` is therefore modeled here as claims-first operational data.
+ */
+export declare const ChargeItemClaim: {
+    /** Stable invoice line identifier. Example: `chargeitem-001`. */
+    readonly Identifier: "ChargeItem.identifier";
+    /** Charge item lifecycle status from FHIR ChargeItemStatus. Example: `billable`. */
+    readonly Status: "ChargeItem.status";
+    /** Parent business aggregate identifier. Example: `invoice-001`. */
+    readonly PartOf: "ChargeItem.part-of";
+    /** 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`. */
+    readonly CodeText: "ChargeItem.code-text";
+    /** Normalized aggregate reporting category. Example: `medical-supplies`. */
+    readonly Category: "ChargeItem.category";
+    /** Supplier or import product code. Example: `IMP-SAL-500`. */
+    readonly SupplierProductCode: "ChargeItem.supplier-productcode";
+    /** Compact FHIR-style quantity token for search/readback. Example: `3|bottle`. */
+    readonly Quantity: "ChargeItem.quantity";
+    /** Main quantity numeric scalar serialized as string. Example: `3`. */
+    readonly QuantityNumber: "ChargeItem.quantity-number";
+    /** Main quantity unit code or label. Example: `bottle`. */
+    readonly QuantityUnit: "ChargeItem.quantity-unit";
+    /** Contained items per main unit. Example: `24`. */
+    readonly ItemsPerUnit: "ChargeItem.items-per-unit";
+    /** Compact contained-item quantity token for search/readback. Example: `500|mL`. */
+    readonly ItemsQuantity: "ChargeItem.items-quantity";
+    /** Contained item numeric quantity serialized as string. Example: `500`. */
+    readonly ItemsQuantityNumber: "ChargeItem.items-quantity-number";
+    /** Contained item UCUM-like unit. Example: `mL`. */
+    readonly ItemsQuantityUnit: "ChargeItem.items-quantity-unit";
+};
+export type ChargeItemClaimKey = typeof ChargeItemClaim[keyof typeof ChargeItemClaim];
+export interface ChargeItemClaims {
+    [ChargeItemClaim.Identifier]?: string;
+    [ChargeItemClaim.Status]?: string;
+    [ChargeItemClaim.PartOf]?: string;
+    [ChargeItemClaim.Code]?: string;
+    [ChargeItemClaim.CodeText]?: string;
+    [ChargeItemClaim.Category]?: string;
+    [ChargeItemClaim.SupplierProductCode]?: string;
+    [ChargeItemClaim.Quantity]?: string;
+    [ChargeItemClaim.QuantityNumber]?: string;
+    [ChargeItemClaim.QuantityUnit]?: string;
+    [ChargeItemClaim.ItemsPerUnit]?: string;
+    [ChargeItemClaim.ItemsQuantity]?: string;
+    [ChargeItemClaim.ItemsQuantityNumber]?: string;
+    [ChargeItemClaim.ItemsQuantityUnit]?: string;
+}
+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",
+    Code = "org.hl7.fhir.api.ChargeItem.code",
+    CodeText = "org.hl7.fhir.api.ChargeItem.code-text",
+    Category = "org.hl7.fhir.api.ChargeItem.category",
+    SupplierProductCode = "org.hl7.fhir.api.ChargeItem.supplier-productcode",
+    Quantity = "org.hl7.fhir.api.ChargeItem.quantity",
+    QuantityNumber = "org.hl7.fhir.api.ChargeItem.quantity-number",
+    QuantityUnit = "org.hl7.fhir.api.ChargeItem.quantity-unit",
+    ItemsPerUnit = "org.hl7.fhir.api.ChargeItem.items-per-unit",
+    ItemsQuantity = "org.hl7.fhir.api.ChargeItem.items-quantity",
+    ItemsQuantityNumber = "org.hl7.fhir.api.ChargeItem.items-quantity-number",
+    ItemsQuantityUnit = "org.hl7.fhir.api.ChargeItem.items-quantity-unit"
+}
+export declare const ChargeItemSearchParamNames: {
+    readonly Identifier: "identifier";
+    readonly Status: "status";
+    readonly PartOf: "part-of";
+    readonly Code: "code";
+    readonly CodeText: "code-text";
+    readonly Category: "category";
+    readonly SupplierProductCode: "supplier-productcode";
+    readonly Quantity: "quantity";
+    readonly QuantityNumber: "quantity-number";
+    readonly QuantityUnit: "quantity-unit";
+    readonly ItemsPerUnit: "items-per-unit";
+    readonly ItemsQuantity: "items-quantity";
+    readonly ItemsQuantityNumber: "items-quantity-number";
+    readonly ItemsQuantityUnit: "items-quantity-unit";
+};
+export interface InvoiceClaimsContextualized {
+    [InvoiceClaimsFhirApiExtended.Identifier]?: string;
+    [InvoiceClaimsFhirApiExtended.Date]?: string;
+    [InvoiceClaimsFhirApiExtended.Status]?: string;
+    [InvoiceClaimsFhirApiExtended.Subject]?: string;
+    [InvoiceClaimsFhirApiExtended.Recipient]?: string;
+    [InvoiceClaimsFhirApiExtended.Issuer]?: string;
+    [InvoiceClaimsFhirApiExtended.IssuerDisplay]?: string;
+    [InvoiceClaimsFhirApiExtended.PaymentTerms]?: string;
+    [InvoiceClaimsFhirApiExtended.PaymentUrl]?: string;
+    [InvoiceClaimsFhirApiExtended.TotalNetValue]?: string;
+    [InvoiceClaimsFhirApiExtended.TotalNetCurrency]?: string;
+    [InvoiceClaimsFhirApiExtended.TotalGrossValue]?: string;
+    [InvoiceClaimsFhirApiExtended.TotalGrossCurrency]?: string;
+}
+export interface ChargeItemClaimsContextualized {
+    [ChargeItemClaimsFhirApiExtended.Identifier]?: string;
+    [ChargeItemClaimsFhirApiExtended.Status]?: string;
+    [ChargeItemClaimsFhirApiExtended.PartOf]?: string;
+    [ChargeItemClaimsFhirApiExtended.Code]?: string;
+    [ChargeItemClaimsFhirApiExtended.CodeText]?: string;
+    [ChargeItemClaimsFhirApiExtended.Category]?: string;
+    [ChargeItemClaimsFhirApiExtended.SupplierProductCode]?: string;
+    [ChargeItemClaimsFhirApiExtended.Quantity]?: string;
+    [ChargeItemClaimsFhirApiExtended.QuantityNumber]?: string;
+    [ChargeItemClaimsFhirApiExtended.QuantityUnit]?: string;
+    [ChargeItemClaimsFhirApiExtended.ItemsPerUnit]?: string;
+    [ChargeItemClaimsFhirApiExtended.ItemsQuantity]?: string;
+    [ChargeItemClaimsFhirApiExtended.ItemsQuantityNumber]?: string;
+    [ChargeItemClaimsFhirApiExtended.ItemsQuantityUnit]?: string;
+}
+export declare const InvoiceClaimSpecs: ClaimSpec[];
+export declare const ChargeItemClaimSpecs: ClaimSpec[];
+export declare const InvoiceClaimToFhirPath: Record<string, string | string[]>;
+export declare function contextualizeInvoiceClaims(claims: InvoiceClaims): InvoiceClaimsContextualized;
+export declare function contextualizeChargeItemClaims(claims: ChargeItemClaims): ChargeItemClaimsContextualized;
+/**
+ * Generic low-level invoice claim accessor.
+ *
+ * Prefer the explicit `getInvoice*` helpers below from application code when
+ * you want stronger autocomplete and clearer intent at the call site.
+ */
+export declare function getInvoiceClaim(claims: InvoiceClaims | undefined, key: InvoiceClaimKey): string | undefined;
+/**
+ * Generic low-level charge item claim accessor.
+ *
+ * Prefer the explicit `getCode()`, `getCodeText()`, `getQuantityNumber()`,
+ * etc. helpers below from application code when you want stronger
+ * autocomplete and clearer intent at the call site.
+ */
+export declare function getChargeItemClaim(claims: ChargeItemClaims | undefined, key: ChargeItemClaimKey): string | undefined;
+export declare function getInvoiceIdentifier(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceDate(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceStatus(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceSubject(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceRecipient(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceIssuer(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceIssuerDisplay(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoicePaymentTerms(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoicePaymentUrl(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceTotalNetValue(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceTotalNetCurrency(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceTotalGrossValue(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getInvoiceTotalGrossCurrency(claims: InvoiceClaims | undefined): string | undefined;
+export declare function getChargeItemIdentifier(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getChargeItemStatus(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getChargeItemPartOf(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getCode(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getCodeText(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getCategory(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getSupplierProductCode(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getQuantity(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getQuantityNumber(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getQuantityUnit(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getItemsPerUnit(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getItemsQuantity(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getItemsQuantityNumber(claims: ChargeItemClaims | undefined): string | undefined;
+export declare function getItemsQuantityUnit(claims: ChargeItemClaims | undefined): string | undefined;
+export interface ChargeItemView {
+    identifier?: string;
+    status?: string;
+    partOf?: string;
+    code?: string;
+    codeText?: string;
+    category?: string;
+    supplierProductCode?: string;
+    quantity?: string;
+    quantityNumber?: string;
+    quantityUnit?: string;
+    itemsPerUnit?: string;
+    itemsQuantity?: string;
+    itemsQuantityNumber?: string;
+    itemsQuantityUnit?: string;
+}
+export declare function getChargeItemView(claims: ChargeItemClaims | undefined): ChargeItemView;
+export declare function getChargeItemList(rows: ReadonlyArray<ChargeItemClaims | (InvoiceClaims & ChargeItemClaims)> | undefined): ChargeItemView[];

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

@@ -0,0 +1,353 @@
+// 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.
+ *
+ * These claims are the claims-first source of truth. FHIR `Invoice` is one
+ * downstream projection built from them.
+ */
+export const InvoiceClaim = {
+    /** Stable business invoice identifier. Example: `invoice-001`. */
+    Identifier: 'Invoice.identifier',
+    /** Invoice issue date/time. Example: `2026-06-11T10:00:00Z`. */
+    Date: 'Invoice.date',
+    /** Invoice lifecycle status. Example: `issued`. */
+    Status: 'Invoice.status',
+    /** Subject or tenant context reference. Example: `did:web:api.acme.org:individual:123`. */
+    Subject: 'Invoice.subject',
+    /** Billed recipient reference. Example: `did:web:portal.example.org:billing`. */
+    Recipient: 'Invoice.recipient',
+    /** Invoice issuer reference. Example: `did:web:api.acme.org`. */
+    Issuer: 'Invoice.issuer',
+    /** Human-readable issuer label. Example: `Gateway Host Services`. */
+    IssuerDisplay: 'Invoice.issuer-display',
+    /** Commercial payment method/terms. Example: `invoice`. */
+    PaymentTerms: 'Invoice.payment-terms',
+    /** Payment or settlement URL when available. Example: `https://pay.example/invoice-001`. */
+    PaymentUrl: 'Invoice.payment-url',
+    /** Net amount numeric value serialized as string. Example: `9.99`. */
+    TotalNetValue: 'Invoice.totalnet-value',
+    /** Net amount ISO currency. Example: `EUR`. */
+    TotalNetCurrency: 'Invoice.totalnet-currency',
+    /** Gross amount numeric value serialized as string. Example: `9.99`. */
+    TotalGrossValue: 'Invoice.totalgross-value',
+    /** Gross amount ISO currency. Example: `EUR`. */
+    TotalGrossCurrency: 'Invoice.totalgross-currency',
+};
+/**
+ * Contextualized FHIR-API-like invoice claims.
+ *
+ * Convention:
+ * - `org.hl7.fhir.api.Invoice.<concrete-parameter>`
+ * - scalar/string-friendly values only
+ * - invoice totals/payment URL remain extension-style operational claims
+ *   because not every business field maps to one native FHIR search parameter
+ */
+export var InvoiceClaimsFhirApiExtended;
+(function (InvoiceClaimsFhirApiExtended) {
+    InvoiceClaimsFhirApiExtended["Identifier"] = "org.hl7.fhir.api.Invoice.identifier";
+    InvoiceClaimsFhirApiExtended["Date"] = "org.hl7.fhir.api.Invoice.date";
+    InvoiceClaimsFhirApiExtended["Status"] = "org.hl7.fhir.api.Invoice.status";
+    InvoiceClaimsFhirApiExtended["Subject"] = "org.hl7.fhir.api.Invoice.subject";
+    InvoiceClaimsFhirApiExtended["Recipient"] = "org.hl7.fhir.api.Invoice.recipient";
+    InvoiceClaimsFhirApiExtended["Issuer"] = "org.hl7.fhir.api.Invoice.issuer";
+    InvoiceClaimsFhirApiExtended["IssuerDisplay"] = "org.hl7.fhir.api.Invoice.issuer-display";
+    InvoiceClaimsFhirApiExtended["PaymentTerms"] = "org.hl7.fhir.api.Invoice.payment-terms";
+    InvoiceClaimsFhirApiExtended["PaymentUrl"] = "org.hl7.fhir.api.Invoice.payment-url";
+    InvoiceClaimsFhirApiExtended["TotalNetValue"] = "org.hl7.fhir.api.Invoice.totalnet-value";
+    InvoiceClaimsFhirApiExtended["TotalNetCurrency"] = "org.hl7.fhir.api.Invoice.totalnet-currency";
+    InvoiceClaimsFhirApiExtended["TotalGrossValue"] = "org.hl7.fhir.api.Invoice.totalgross-value";
+    InvoiceClaimsFhirApiExtended["TotalGrossCurrency"] = "org.hl7.fhir.api.Invoice.totalgross-currency";
+})(InvoiceClaimsFhirApiExtended || (InvoiceClaimsFhirApiExtended = {}));
+/**
+ * Canonical non-contextualized parameter names for query builders and readers.
+ */
+export const InvoiceSearchParamNames = {
+    Identifier: 'identifier',
+    Date: 'date',
+    Status: 'status',
+    Subject: 'subject',
+    Recipient: 'recipient',
+    Issuer: 'issuer',
+    IssuerDisplay: 'issuer-display',
+    PaymentTerms: 'payment-terms',
+    PaymentUrl: 'payment-url',
+    TotalNetValue: 'totalnet-value',
+    TotalNetCurrency: 'totalnet-currency',
+    TotalGrossValue: 'totalgross-value',
+    TotalGrossCurrency: 'totalgross-currency',
+};
+/**
+ * Charge-item-level claims used when one business invoice line is represented
+ * as one claims row. The future FHIR export can compact multiple rows sharing
+ * one invoice identifier into a single `Invoice` with multiple items.
+ *
+ * Note:
+ * - FHIR `Invoice` does not expose all these details as search parameters.
+ * - `ChargeItem` is therefore modeled here as claims-first operational data.
+ */
+export const ChargeItemClaim = {
+    /** Stable invoice line identifier. Example: `chargeitem-001`. */
+    Identifier: 'ChargeItem.identifier',
+    /** Charge item lifecycle status from FHIR ChargeItemStatus. Example: `billable`. */
+    Status: 'ChargeItem.status',
+    /** Parent business aggregate identifier. Example: `invoice-001`. */
+    PartOf: 'ChargeItem.part-of',
+    /** 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`. */
+    CodeText: 'ChargeItem.code-text',
+    /** Normalized aggregate reporting category. Example: `medical-supplies`. */
+    Category: 'ChargeItem.category',
+    /** Supplier or import product code. Example: `IMP-SAL-500`. */
+    SupplierProductCode: 'ChargeItem.supplier-productcode',
+    /** Compact FHIR-style quantity token for search/readback. Example: `3|bottle`. */
+    Quantity: 'ChargeItem.quantity',
+    /** Main quantity numeric scalar serialized as string. Example: `3`. */
+    QuantityNumber: 'ChargeItem.quantity-number',
+    /** Main quantity unit code or label. Example: `bottle`. */
+    QuantityUnit: 'ChargeItem.quantity-unit',
+    /** Contained items per main unit. Example: `24`. */
+    ItemsPerUnit: 'ChargeItem.items-per-unit',
+    /** Compact contained-item quantity token for search/readback. Example: `500|mL`. */
+    ItemsQuantity: 'ChargeItem.items-quantity',
+    /** Contained item numeric quantity serialized as string. Example: `500`. */
+    ItemsQuantityNumber: 'ChargeItem.items-quantity-number',
+    /** Contained item UCUM-like unit. Example: `mL`. */
+    ItemsQuantityUnit: 'ChargeItem.items-quantity-unit',
+};
+export var ChargeItemClaimsFhirApiExtended;
+(function (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["Code"] = "org.hl7.fhir.api.ChargeItem.code";
+    ChargeItemClaimsFhirApiExtended["CodeText"] = "org.hl7.fhir.api.ChargeItem.code-text";
+    ChargeItemClaimsFhirApiExtended["Category"] = "org.hl7.fhir.api.ChargeItem.category";
+    ChargeItemClaimsFhirApiExtended["SupplierProductCode"] = "org.hl7.fhir.api.ChargeItem.supplier-productcode";
+    ChargeItemClaimsFhirApiExtended["Quantity"] = "org.hl7.fhir.api.ChargeItem.quantity";
+    ChargeItemClaimsFhirApiExtended["QuantityNumber"] = "org.hl7.fhir.api.ChargeItem.quantity-number";
+    ChargeItemClaimsFhirApiExtended["QuantityUnit"] = "org.hl7.fhir.api.ChargeItem.quantity-unit";
+    ChargeItemClaimsFhirApiExtended["ItemsPerUnit"] = "org.hl7.fhir.api.ChargeItem.items-per-unit";
+    ChargeItemClaimsFhirApiExtended["ItemsQuantity"] = "org.hl7.fhir.api.ChargeItem.items-quantity";
+    ChargeItemClaimsFhirApiExtended["ItemsQuantityNumber"] = "org.hl7.fhir.api.ChargeItem.items-quantity-number";
+    ChargeItemClaimsFhirApiExtended["ItemsQuantityUnit"] = "org.hl7.fhir.api.ChargeItem.items-quantity-unit";
+})(ChargeItemClaimsFhirApiExtended || (ChargeItemClaimsFhirApiExtended = {}));
+export const ChargeItemSearchParamNames = {
+    Identifier: 'identifier',
+    Status: 'status',
+    PartOf: 'part-of',
+    Code: 'code',
+    CodeText: 'code-text',
+    Category: 'category',
+    SupplierProductCode: 'supplier-productcode',
+    Quantity: 'quantity',
+    QuantityNumber: 'quantity-number',
+    QuantityUnit: 'quantity-unit',
+    ItemsPerUnit: 'items-per-unit',
+    ItemsQuantity: 'items-quantity',
+    ItemsQuantityNumber: 'items-quantity-number',
+    ItemsQuantityUnit: 'items-quantity-unit',
+};
+export const InvoiceClaimSpecs = [
+    { key: InvoiceClaim.Identifier, meaning: 'Stable business invoice identifier.', example: 'invoice-001' },
+    { key: InvoiceClaim.Date, meaning: 'Invoice issue date/time.', example: '2026-06-11T10:00:00Z' },
+    { key: InvoiceClaim.Status, meaning: 'Invoice lifecycle status.', example: 'issued' },
+    { key: InvoiceClaim.Subject, meaning: 'Subject or tenant context reference.', example: 'did:web:api.acme.org:individual:123' },
+    { key: InvoiceClaim.Recipient, meaning: 'Billed recipient reference.', example: 'did:web:portal.example.org:billing' },
+    { key: InvoiceClaim.Issuer, meaning: 'Invoice issuer reference.', example: 'did:web:api.acme.org' },
+    { key: InvoiceClaim.IssuerDisplay, meaning: 'Human-readable issuer label.', example: 'Gateway Host Services' },
+    { key: InvoiceClaim.PaymentTerms, meaning: 'Commercial payment method/terms.', example: 'invoice' },
+    { key: InvoiceClaim.PaymentUrl, meaning: 'Payment or settlement URL when available.', example: 'https://pay.example/invoice-001' },
+    { key: InvoiceClaim.TotalNetValue, meaning: 'Net amount numeric value serialized as string.', example: '9.99' },
+    { key: InvoiceClaim.TotalNetCurrency, meaning: 'Net amount ISO currency.', example: 'EUR' },
+    { key: InvoiceClaim.TotalGrossValue, meaning: 'Gross amount numeric value serialized as string.', example: '9.99' },
+    { key: InvoiceClaim.TotalGrossCurrency, meaning: 'Gross amount ISO currency.', example: 'EUR' },
+];
+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.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' },
+    { key: ChargeItemClaim.SupplierProductCode, meaning: 'Supplier or import product code.', example: 'IMP-SAL-500' },
+    { key: ChargeItemClaim.Quantity, meaning: 'Compact FHIR-style quantity token for search/readback.', example: '3|bottle' },
+    { key: ChargeItemClaim.QuantityNumber, meaning: 'Main quantity numeric scalar serialized as string.', example: '3' },
+    { key: ChargeItemClaim.QuantityUnit, meaning: 'Main quantity unit code or label.', example: 'bottle' },
+    { key: ChargeItemClaim.ItemsPerUnit, meaning: 'Contained items per main unit.', example: '24' },
+    { key: ChargeItemClaim.ItemsQuantity, meaning: 'Compact contained-item quantity token for search/readback.', example: '500|mL' },
+    { key: ChargeItemClaim.ItemsQuantityNumber, meaning: 'Contained item numeric quantity serialized as string.', example: '500' },
+    { key: ChargeItemClaim.ItemsQuantityUnit, meaning: 'Contained item UCUM-like unit.', example: 'mL' },
+];
+export const InvoiceClaimToFhirPath = {
+    [InvoiceClaim.Identifier]: 'Invoice.identifier.value',
+    [InvoiceClaim.Date]: 'Invoice.date',
+    [InvoiceClaim.Status]: 'Invoice.status',
+    [InvoiceClaim.Subject]: 'Invoice.subject.reference',
+    [InvoiceClaim.Recipient]: 'Invoice.recipient.reference',
+    [InvoiceClaim.Issuer]: 'Invoice.issuer.reference',
+    [InvoiceClaim.IssuerDisplay]: 'Invoice.issuer.display',
+    [InvoiceClaim.PaymentTerms]: 'Invoice.paymentTerms',
+    [InvoiceClaim.PaymentUrl]: 'Invoice.note.text',
+    [InvoiceClaim.TotalNetValue]: 'Invoice.totalNet.value',
+    [InvoiceClaim.TotalNetCurrency]: 'Invoice.totalNet.currency',
+    [InvoiceClaim.TotalGrossValue]: 'Invoice.totalGross.value',
+    [InvoiceClaim.TotalGrossCurrency]: 'Invoice.totalGross.currency',
+};
+export function contextualizeInvoiceClaims(claims) {
+    return {
+        ...(claims[InvoiceClaim.Identifier] ? { [InvoiceClaimsFhirApiExtended.Identifier]: claims[InvoiceClaim.Identifier] } : {}),
+        ...(claims[InvoiceClaim.Date] ? { [InvoiceClaimsFhirApiExtended.Date]: claims[InvoiceClaim.Date] } : {}),
+        ...(claims[InvoiceClaim.Status] ? { [InvoiceClaimsFhirApiExtended.Status]: claims[InvoiceClaim.Status] } : {}),
+        ...(claims[InvoiceClaim.Subject] ? { [InvoiceClaimsFhirApiExtended.Subject]: claims[InvoiceClaim.Subject] } : {}),
+        ...(claims[InvoiceClaim.Recipient] ? { [InvoiceClaimsFhirApiExtended.Recipient]: claims[InvoiceClaim.Recipient] } : {}),
+        ...(claims[InvoiceClaim.Issuer] ? { [InvoiceClaimsFhirApiExtended.Issuer]: claims[InvoiceClaim.Issuer] } : {}),
+        ...(claims[InvoiceClaim.IssuerDisplay] ? { [InvoiceClaimsFhirApiExtended.IssuerDisplay]: claims[InvoiceClaim.IssuerDisplay] } : {}),
+        ...(claims[InvoiceClaim.PaymentTerms] ? { [InvoiceClaimsFhirApiExtended.PaymentTerms]: claims[InvoiceClaim.PaymentTerms] } : {}),
+        ...(claims[InvoiceClaim.PaymentUrl] ? { [InvoiceClaimsFhirApiExtended.PaymentUrl]: claims[InvoiceClaim.PaymentUrl] } : {}),
+        ...(claims[InvoiceClaim.TotalNetValue] ? { [InvoiceClaimsFhirApiExtended.TotalNetValue]: claims[InvoiceClaim.TotalNetValue] } : {}),
+        ...(claims[InvoiceClaim.TotalNetCurrency] ? { [InvoiceClaimsFhirApiExtended.TotalNetCurrency]: claims[InvoiceClaim.TotalNetCurrency] } : {}),
+        ...(claims[InvoiceClaim.TotalGrossValue] ? { [InvoiceClaimsFhirApiExtended.TotalGrossValue]: claims[InvoiceClaim.TotalGrossValue] } : {}),
+        ...(claims[InvoiceClaim.TotalGrossCurrency] ? { [InvoiceClaimsFhirApiExtended.TotalGrossCurrency]: claims[InvoiceClaim.TotalGrossCurrency] } : {}),
+    };
+}
+export function contextualizeChargeItemClaims(claims) {
+    return {
+        ...(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.Code] ? { [ChargeItemClaimsFhirApiExtended.Code]: claims[ChargeItemClaim.Code] } : {}),
+        ...(claims[ChargeItemClaim.CodeText] ? { [ChargeItemClaimsFhirApiExtended.CodeText]: claims[ChargeItemClaim.CodeText] } : {}),
+        ...(claims[ChargeItemClaim.Category] ? { [ChargeItemClaimsFhirApiExtended.Category]: claims[ChargeItemClaim.Category] } : {}),
+        ...(claims[ChargeItemClaim.SupplierProductCode] ? { [ChargeItemClaimsFhirApiExtended.SupplierProductCode]: claims[ChargeItemClaim.SupplierProductCode] } : {}),
+        ...(claims[ChargeItemClaim.Quantity] ? { [ChargeItemClaimsFhirApiExtended.Quantity]: claims[ChargeItemClaim.Quantity] } : {}),
+        ...(claims[ChargeItemClaim.QuantityNumber] ? { [ChargeItemClaimsFhirApiExtended.QuantityNumber]: claims[ChargeItemClaim.QuantityNumber] } : {}),
+        ...(claims[ChargeItemClaim.QuantityUnit] ? { [ChargeItemClaimsFhirApiExtended.QuantityUnit]: claims[ChargeItemClaim.QuantityUnit] } : {}),
+        ...(claims[ChargeItemClaim.ItemsPerUnit] ? { [ChargeItemClaimsFhirApiExtended.ItemsPerUnit]: claims[ChargeItemClaim.ItemsPerUnit] } : {}),
+        ...(claims[ChargeItemClaim.ItemsQuantity] ? { [ChargeItemClaimsFhirApiExtended.ItemsQuantity]: claims[ChargeItemClaim.ItemsQuantity] } : {}),
+        ...(claims[ChargeItemClaim.ItemsQuantityNumber] ? { [ChargeItemClaimsFhirApiExtended.ItemsQuantityNumber]: claims[ChargeItemClaim.ItemsQuantityNumber] } : {}),
+        ...(claims[ChargeItemClaim.ItemsQuantityUnit] ? { [ChargeItemClaimsFhirApiExtended.ItemsQuantityUnit]: claims[ChargeItemClaim.ItemsQuantityUnit] } : {}),
+    };
+}
+/**
+ * Generic low-level invoice claim accessor.
+ *
+ * Prefer the explicit `getInvoice*` helpers below from application code when
+ * you want stronger autocomplete and clearer intent at the call site.
+ */
+export function getInvoiceClaim(claims, key) {
+    return claims?.[key];
+}
+/**
+ * Generic low-level charge item claim accessor.
+ *
+ * Prefer the explicit `getCode()`, `getCodeText()`, `getQuantityNumber()`,
+ * etc. helpers below from application code when you want stronger
+ * autocomplete and clearer intent at the call site.
+ */
+export function getChargeItemClaim(claims, key) {
+    return claims?.[key];
+}
+export function getInvoiceIdentifier(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.Identifier);
+}
+export function getInvoiceDate(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.Date);
+}
+export function getInvoiceStatus(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.Status);
+}
+export function getInvoiceSubject(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.Subject);
+}
+export function getInvoiceRecipient(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.Recipient);
+}
+export function getInvoiceIssuer(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.Issuer);
+}
+export function getInvoiceIssuerDisplay(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.IssuerDisplay);
+}
+export function getInvoicePaymentTerms(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.PaymentTerms);
+}
+export function getInvoicePaymentUrl(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.PaymentUrl);
+}
+export function getInvoiceTotalNetValue(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.TotalNetValue);
+}
+export function getInvoiceTotalNetCurrency(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.TotalNetCurrency);
+}
+export function getInvoiceTotalGrossValue(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.TotalGrossValue);
+}
+export function getInvoiceTotalGrossCurrency(claims) {
+    return getInvoiceClaim(claims, InvoiceClaim.TotalGrossCurrency);
+}
+export function getChargeItemIdentifier(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.Identifier);
+}
+export function getChargeItemStatus(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.Status);
+}
+export function getChargeItemPartOf(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.PartOf);
+}
+export function getCode(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.Code);
+}
+export function getCodeText(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.CodeText);
+}
+export function getCategory(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.Category);
+}
+export function getSupplierProductCode(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.SupplierProductCode);
+}
+export function getQuantity(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.Quantity);
+}
+export function getQuantityNumber(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.QuantityNumber);
+}
+export function getQuantityUnit(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.QuantityUnit);
+}
+export function getItemsPerUnit(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.ItemsPerUnit);
+}
+export function getItemsQuantity(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.ItemsQuantity);
+}
+export function getItemsQuantityNumber(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.ItemsQuantityNumber);
+}
+export function getItemsQuantityUnit(claims) {
+    return getChargeItemClaim(claims, ChargeItemClaim.ItemsQuantityUnit);
+}
+export function getChargeItemView(claims) {
+    return {
+        identifier: getChargeItemIdentifier(claims),
+        status: getChargeItemStatus(claims),
+        partOf: getChargeItemPartOf(claims),
+        code: getCode(claims),
+        codeText: getCodeText(claims),
+        category: getCategory(claims),
+        supplierProductCode: getSupplierProductCode(claims),
+        quantity: getQuantity(claims),
+        quantityNumber: getQuantityNumber(claims),
+        quantityUnit: getQuantityUnit(claims),
+        itemsPerUnit: getItemsPerUnit(claims),
+        itemsQuantity: getItemsQuantity(claims),
+        itemsQuantityNumber: getItemsQuantityNumber(claims),
+        itemsQuantityUnit: getItemsQuantityUnit(claims),
+    };
+}
+export function getChargeItemList(rows) {
+    return Array.isArray(rows) ? rows.map((row) => getChargeItemView(row)) : [];
+}

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

@@ -2,4 +2,4 @@
  * Canonical interoperable-claims keys used by claims-first payloads.
  * Keep this separated from strict FHIR resource typings.
  */
-export * from './interoperable-claims';
+export * from './interoperable-claims/index';

package/dist/models/interoperable-claims.js

@@ -4,4 +4,4 @@
  * Canonical interoperable-claims keys used by claims-first payloads.
  * Keep this separated from strict FHIR resource typings.
  */
-export * from './interoperable-claims.js';
+export * from './interoperable-claims/index.js';

package/dist/utils/index.d.ts

@@ -46,6 +46,7 @@ export * from './individual-onboarding-editor';
 export * from './individual-onboarding-document-reference';
 export * from './individual-organization-kyc';
 export * from './individual-bundle-vault';
+export * from './invoice-bundle';
 export * from './ips-bundle-claims';
 export * from './interoperable-resource-operation';
 export * from './jwt';

package/dist/utils/index.js

@@ -46,6 +46,7 @@ export * from './individual-onboarding-editor.js';
 export * from './individual-onboarding-document-reference.js';
 export * from './individual-organization-kyc.js';
 export * from './individual-bundle-vault.js';
+export * from './invoice-bundle.js';
 export * from './ips-bundle-claims.js';
 export * from './interoperable-resource-operation.js';
 export * from './jwt.js';

package/dist/utils/invoice-bundle.d.ts

@@ -0,0 +1,82 @@
+import { ChargeItemClaims, ChargeItemClaimsContextualized, InvoiceClaims, InvoiceClaimsContextualized } from '../models/interoperable-claims/invoice-claims';
+export type InvoiceBundleDocument = Readonly<{
+    documentId: string;
+    contentType: string;
+    title: string;
+    description: string;
+    language?: string;
+    dataBase64?: string;
+    url?: string;
+    hash?: string;
+    createdAt?: string;
+}>;
+export type InvoiceChargeItemDraft = Readonly<{
+    identifier?: string;
+    status?: string;
+    partOf?: string;
+    code?: string;
+    codeText?: string;
+    category?: string;
+    supplierProductCode?: string;
+    quantity?: string;
+    quantityNumber?: string;
+    quantityUnit?: string;
+    itemsPerUnit?: string;
+    itemsQuantity?: string;
+    itemsQuantityNumber?: string;
+    itemsQuantityUnit?: string;
+}>;
+export type InvoiceBundleDraft = Readonly<{
+    invoiceId?: string;
+    subjectReference?: string;
+    issuerReference?: string;
+    issuerDisplay?: string;
+    recipientReference?: string;
+    issuedAt?: string;
+    amount?: string;
+    currency?: string;
+    paymentMethod?: string;
+    paymentUrl?: string;
+    pdfDocument?: InvoiceBundleDocument;
+    structuredDocument?: InvoiceBundleDocument;
+    chargeItems?: readonly InvoiceChargeItemDraft[];
+}>;
+export type InvoiceBundleSummary = Readonly<{
+    invoiceId?: string;
+    amount?: string;
+    currency?: string;
+    paymentMethod?: string;
+    paymentUrl?: string;
+    pdfDocumentId?: string;
+    structuredDocumentId?: string;
+}>;
+export interface InvoiceBundleEditor {
+    setInvoiceId(value: string): InvoiceBundleEditor;
+    setSubjectReference(value: string): InvoiceBundleEditor;
+    setIssuerReference(value: string): InvoiceBundleEditor;
+    setIssuerDisplay(value: string): InvoiceBundleEditor;
+    setRecipientReference(value: string): InvoiceBundleEditor;
+    setIssuedAt(value: string): InvoiceBundleEditor;
+    setAmount(value: string): InvoiceBundleEditor;
+    setCurrency(value: string): InvoiceBundleEditor;
+    setPaymentMethod(value: string): InvoiceBundleEditor;
+    setPaymentUrl(value: string): InvoiceBundleEditor;
+    setPdfDocument(value: InvoiceBundleDocument): InvoiceBundleEditor;
+    setStructuredDocument(value: InvoiceBundleDocument): InvoiceBundleEditor;
+    setChargeItems(value: readonly InvoiceChargeItemDraft[]): InvoiceBundleEditor;
+    addChargeItem(value: InvoiceChargeItemDraft): InvoiceBundleEditor;
+    getDraft(): InvoiceBundleDraft;
+    buildBundle(): Record<string, unknown>;
+    buildInvoiceClaims(): InvoiceClaims;
+    buildInvoiceClaimsContextualized(): InvoiceClaimsContextualized;
+    buildChargeItemClaimRows(): Array<InvoiceClaims & ChargeItemClaims>;
+    buildChargeItemClaimRowsContextualized(): ChargeItemClaimsContextualized[];
+    getSummary(): InvoiceBundleSummary;
+    readBundleFromResponseBody(body: unknown): Record<string, unknown> | undefined;
+}
+export declare function buildInvoiceFhirClaims(draftInput: Partial<InvoiceBundleDraft>): InvoiceClaims;
+export declare function buildInvoiceChargeItemClaimRows(draftInput: Partial<InvoiceBundleDraft>): Array<InvoiceClaims & ChargeItemClaims>;
+export declare function buildInvoiceBundle(draftInput: Partial<InvoiceBundleDraft>): Record<string, unknown>;
+export declare function extractInvoiceBundleFromResponseBody(body: unknown): Record<string, unknown> | undefined;
+export declare function readInvoiceBundleSummaryFromResponseBody(body: unknown): InvoiceBundleSummary;
+export declare function createInvoiceBundleEditor(initial?: Partial<InvoiceBundleDraft>): InvoiceBundleEditor;

package/dist/utils/invoice-bundle.js

@@ -0,0 +1,240 @@
+import { ResourceTypesFhirR4 } from '../constants/fhir-resource-types.js';
+import { ChargeItemClaim, InvoiceClaim, contextualizeChargeItemClaims, contextualizeInvoiceClaims, } from '../models/interoperable-claims/invoice-claims.js';
+function normalizeText(value) {
+    const normalized = String(value ?? '').trim();
+    return normalized || undefined;
+}
+function normalizeDocument(value) {
+    if (!value)
+        return undefined;
+    return {
+        documentId: String(value.documentId || '').trim(),
+        contentType: String(value.contentType || '').trim(),
+        title: String(value.title || '').trim(),
+        description: String(value.description || '').trim(),
+        language: normalizeText(value.language),
+        dataBase64: normalizeText(value.dataBase64),
+        url: normalizeText(value.url),
+        hash: normalizeText(value.hash),
+        createdAt: normalizeText(value.createdAt),
+    };
+}
+function cloneDraft(draft) {
+    return {
+        invoiceId: normalizeText(draft?.invoiceId),
+        subjectReference: normalizeText(draft?.subjectReference),
+        issuerReference: normalizeText(draft?.issuerReference),
+        issuerDisplay: normalizeText(draft?.issuerDisplay),
+        recipientReference: normalizeText(draft?.recipientReference),
+        issuedAt: normalizeText(draft?.issuedAt),
+        amount: normalizeText(draft?.amount),
+        currency: normalizeText(draft?.currency),
+        paymentMethod: normalizeText(draft?.paymentMethod),
+        paymentUrl: normalizeText(draft?.paymentUrl),
+        pdfDocument: normalizeDocument(draft?.pdfDocument),
+        structuredDocument: normalizeDocument(draft?.structuredDocument),
+        chargeItems: Array.isArray(draft?.chargeItems)
+            ? draft?.chargeItems.map((item) => ({
+                identifier: normalizeText(item?.identifier),
+                status: normalizeText(item?.status),
+                partOf: normalizeText(item?.partOf),
+                code: normalizeText(item?.code),
+                codeText: normalizeText(item?.codeText),
+                category: normalizeText(item?.category),
+                supplierProductCode: normalizeText(item?.supplierProductCode),
+                quantity: normalizeText(item?.quantity),
+                quantityNumber: normalizeText(item?.quantityNumber),
+                quantityUnit: normalizeText(item?.quantityUnit),
+                itemsPerUnit: normalizeText(item?.itemsPerUnit),
+                itemsQuantity: normalizeText(item?.itemsQuantity),
+                itemsQuantityNumber: normalizeText(item?.itemsQuantityNumber),
+                itemsQuantityUnit: normalizeText(item?.itemsQuantityUnit),
+            }))
+            : [],
+    };
+}
+export function buildInvoiceFhirClaims(draftInput) {
+    const draft = cloneDraft(draftInput);
+    return {
+        ...(draft.invoiceId ? { [InvoiceClaim.Identifier]: draft.invoiceId } : {}),
+        ...(draft.issuedAt ? { [InvoiceClaim.Date]: draft.issuedAt } : {}),
+        [InvoiceClaim.Status]: 'issued',
+        ...(draft.subjectReference ? { [InvoiceClaim.Subject]: draft.subjectReference } : {}),
+        ...(draft.recipientReference ? { [InvoiceClaim.Recipient]: draft.recipientReference } : {}),
+        ...(draft.issuerReference ? { [InvoiceClaim.Issuer]: draft.issuerReference } : {}),
+        ...(draft.issuerDisplay ? { [InvoiceClaim.IssuerDisplay]: draft.issuerDisplay } : {}),
+        ...(draft.paymentMethod ? { [InvoiceClaim.PaymentTerms]: draft.paymentMethod } : {}),
+        ...(draft.paymentUrl ? { [InvoiceClaim.PaymentUrl]: draft.paymentUrl } : {}),
+        ...(draft.amount ? { [InvoiceClaim.TotalNetValue]: draft.amount } : {}),
+        ...(draft.currency ? { [InvoiceClaim.TotalNetCurrency]: draft.currency } : {}),
+        ...(draft.amount ? { [InvoiceClaim.TotalGrossValue]: draft.amount } : {}),
+        ...(draft.currency ? { [InvoiceClaim.TotalGrossCurrency]: draft.currency } : {}),
+    };
+}
+export function buildInvoiceChargeItemClaimRows(draftInput) {
+    const draft = cloneDraft(draftInput);
+    const invoiceClaims = buildInvoiceFhirClaims(draft);
+    return (draft.chargeItems || []).map((item) => ({
+        ...invoiceClaims,
+        ...(item.identifier ? { [ChargeItemClaim.Identifier]: item.identifier } : {}),
+        ...((item.status || 'billable') ? { [ChargeItemClaim.Status]: item.status || 'billable' } : {}),
+        ...((item.partOf || draft.invoiceId) ? { [ChargeItemClaim.PartOf]: item.partOf || draft.invoiceId } : {}),
+        ...(item.code ? { [ChargeItemClaim.Code]: item.code } : {}),
+        ...(item.codeText ? { [ChargeItemClaim.CodeText]: item.codeText } : {}),
+        ...(item.category ? { [ChargeItemClaim.Category]: item.category } : {}),
+        ...(item.supplierProductCode ? { [ChargeItemClaim.SupplierProductCode]: item.supplierProductCode } : {}),
+        ...(item.quantity ? { [ChargeItemClaim.Quantity]: item.quantity } : {}),
+        ...(item.quantityNumber ? { [ChargeItemClaim.QuantityNumber]: item.quantityNumber } : {}),
+        ...(item.quantityUnit ? { [ChargeItemClaim.QuantityUnit]: item.quantityUnit } : {}),
+        ...(item.itemsPerUnit ? { [ChargeItemClaim.ItemsPerUnit]: item.itemsPerUnit } : {}),
+        ...(item.itemsQuantity ? { [ChargeItemClaim.ItemsQuantity]: item.itemsQuantity } : {}),
+        ...(item.itemsQuantityNumber ? { [ChargeItemClaim.ItemsQuantityNumber]: item.itemsQuantityNumber } : {}),
+        ...(item.itemsQuantityUnit ? { [ChargeItemClaim.ItemsQuantityUnit]: item.itemsQuantityUnit } : {}),
+    }));
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function buildDocumentReferenceResource(draft, document) {
+    return {
+        resourceType: ResourceTypesFhirR4.DocumentReference,
+        id: document.documentId,
+        status: 'current',
+        identifier: [{ value: document.documentId }],
+        subject: draft.subjectReference ? { reference: draft.subjectReference } : undefined,
+        date: document.createdAt || draft.issuedAt,
+        description: document.description,
+        content: [{
+                attachment: {
+                    contentType: document.contentType,
+                    data: document.dataBase64,
+                    url: document.url,
+                    title: document.title,
+                    language: document.language,
+                    creation: document.createdAt || draft.issuedAt,
+                    hash: document.hash,
+                },
+            }],
+    };
+}
+export function buildInvoiceBundle(draftInput) {
+    const draft = cloneDraft(draftInput);
+    const amountNumber = Number(draft.amount || '');
+    const normalizedAmount = Number.isFinite(amountNumber) ? amountNumber : undefined;
+    const invoiceResource = {
+        resourceType: ResourceTypesFhirR4.Invoice,
+        id: draft.invoiceId,
+        meta: { claims: buildInvoiceFhirClaims(draft) },
+        status: 'issued',
+        identifier: draft.invoiceId ? [{ value: draft.invoiceId }] : undefined,
+        subject: draft.subjectReference ? { reference: draft.subjectReference } : undefined,
+        recipient: draft.recipientReference ? { reference: draft.recipientReference } : undefined,
+        issuer: draft.issuerReference || draft.issuerDisplay
+            ? { reference: draft.issuerReference, display: draft.issuerDisplay }
+            : undefined,
+        date: draft.issuedAt,
+        paymentTerms: draft.paymentMethod,
+        note: draft.paymentUrl ? [{ text: draft.paymentUrl }] : undefined,
+        totalNet: normalizedAmount !== undefined
+            ? { value: normalizedAmount, currency: draft.currency }
+            : undefined,
+        totalGross: normalizedAmount !== undefined
+            ? { value: normalizedAmount, currency: draft.currency }
+            : undefined,
+    };
+    const entry = [{ resource: invoiceResource }];
+    if (draft.pdfDocument) {
+        entry.push({ resource: buildDocumentReferenceResource(draft, draft.pdfDocument) });
+    }
+    if (draft.structuredDocument) {
+        entry.push({ resource: buildDocumentReferenceResource(draft, draft.structuredDocument) });
+    }
+    return {
+        resourceType: ResourceTypesFhirR4.Bundle,
+        type: 'collection',
+        entry,
+    };
+}
+export function extractInvoiceBundleFromResponseBody(body) {
+    const root = asRecord(body) || {};
+    const bodyNode = asRecord(root.body) || root;
+    const data = Array.isArray(bodyNode.data) ? bodyNode.data : [];
+    for (const candidate of data) {
+        const entry = asRecord(candidate) || {};
+        const resource = asRecord(entry.resource);
+        if (!resource || resource.resourceType !== ResourceTypesFhirR4.Bundle)
+            continue;
+        const bundleEntries = Array.isArray(resource.entry) ? resource.entry : [];
+        const hasInvoice = bundleEntries.some((bundleEntry) => {
+            const nested = asRecord(bundleEntry);
+            const nestedResource = asRecord(nested?.resource);
+            return nestedResource?.resourceType === ResourceTypesFhirR4.Invoice;
+        });
+        if (hasInvoice)
+            return resource;
+    }
+    return undefined;
+}
+export function readInvoiceBundleSummaryFromResponseBody(body) {
+    const bundle = extractInvoiceBundleFromResponseBody(body);
+    const entries = Array.isArray(bundle?.entry) ? bundle.entry : [];
+    const invoice = entries
+        .map((entry) => asRecord(entry)?.resource)
+        .map((resource) => asRecord(resource))
+        .find((resource) => resource?.resourceType === ResourceTypesFhirR4.Invoice);
+    const documents = entries
+        .map((entry) => asRecord(entry)?.resource)
+        .map((resource) => asRecord(resource))
+        .filter((resource) => resource?.resourceType === ResourceTypesFhirR4.DocumentReference);
+    const pdf = documents.find((resource) => {
+        const content = Array.isArray(resource?.content) ? resource.content : [];
+        const attachment = asRecord(asRecord(content[0])?.attachment);
+        return String(attachment?.contentType || '').trim() === 'application/pdf';
+    });
+    const structured = documents.find((resource) => resource !== pdf);
+    return {
+        invoiceId: normalizeText(asRecord((Array.isArray(invoice?.identifier) ? invoice?.identifier[0] : undefined))?.value
+            || invoice?.id),
+        amount: normalizeText(asRecord(invoice?.totalGross)?.value),
+        currency: normalizeText(asRecord(invoice?.totalGross)?.currency),
+        paymentMethod: normalizeText(invoice?.paymentTerms),
+        paymentUrl: normalizeText(asRecord(Array.isArray(invoice?.note) ? invoice.note[0] : undefined)?.text),
+        pdfDocumentId: normalizeText(pdf?.id),
+        structuredDocumentId: normalizeText(structured?.id),
+    };
+}
+export function createInvoiceBundleEditor(initial) {
+    let draft = cloneDraft(initial);
+    const editor = {
+        setInvoiceId(value) { draft = cloneDraft({ ...draft, invoiceId: value }); return editor; },
+        setSubjectReference(value) { draft = cloneDraft({ ...draft, subjectReference: value }); return editor; },
+        setIssuerReference(value) { draft = cloneDraft({ ...draft, issuerReference: value }); return editor; },
+        setIssuerDisplay(value) { draft = cloneDraft({ ...draft, issuerDisplay: value }); return editor; },
+        setRecipientReference(value) { draft = cloneDraft({ ...draft, recipientReference: value }); return editor; },
+        setIssuedAt(value) { draft = cloneDraft({ ...draft, issuedAt: value }); return editor; },
+        setAmount(value) { draft = cloneDraft({ ...draft, amount: value }); return editor; },
+        setCurrency(value) { draft = cloneDraft({ ...draft, currency: value }); return editor; },
+        setPaymentMethod(value) { draft = cloneDraft({ ...draft, paymentMethod: value }); return editor; },
+        setPaymentUrl(value) { draft = cloneDraft({ ...draft, paymentUrl: value }); return editor; },
+        setPdfDocument(value) { draft = cloneDraft({ ...draft, pdfDocument: value }); return editor; },
+        setStructuredDocument(value) { draft = cloneDraft({ ...draft, structuredDocument: value }); return editor; },
+        setChargeItems(value) { draft = cloneDraft({ ...draft, chargeItems: value }); return editor; },
+        addChargeItem(value) { draft = cloneDraft({ ...draft, chargeItems: [...(draft.chargeItems || []), value] }); return editor; },
+        getDraft() { return cloneDraft(draft); },
+        buildBundle() { return buildInvoiceBundle(draft); },
+        buildInvoiceClaims() { return buildInvoiceFhirClaims(draft); },
+        buildInvoiceClaimsContextualized() { return contextualizeInvoiceClaims(buildInvoiceFhirClaims(draft)); },
+        buildChargeItemClaimRows() { return buildInvoiceChargeItemClaimRows(draft); },
+        buildChargeItemClaimRowsContextualized() {
+            return buildInvoiceChargeItemClaimRows(draft).map((row) => ({
+                ...contextualizeInvoiceClaims(row),
+                ...contextualizeChargeItemClaims(row),
+            }));
+        },
+        getSummary() { return readInvoiceBundleSummaryFromResponseBody({ data: [{ resource: buildInvoiceBundle(draft) }] }); },
+        readBundleFromResponseBody(body) { return extractInvoiceBundleFromResponseBody(body); },
+    };
+    return editor;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "publishConfig": {
     "access": "public"
   },
@@ -10,7 +10,7 @@
     "@stablelib/base64": "^1.0.1",
     "@stablelib/utf8": "^1.0.2",
     "base-x": "^4.0.0",
-    "gdc-common-utils-ts": "^1.21.0",
+    "gdc-common-utils-ts": "^1.23.0",
     "pako": "^2.1.0"
   },
   "scripts": {