@formfeed/engine 0.3.11 → 0.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/engine",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "The Formfeed template engine (Jinja2, Liquid, Handlebars) for the browser and Node.",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,8 @@
     "marked": "^18.0.11",
     "n2words": "^6.1.2",
     "nunjucks": "^3.2.4",
-    "qrcode": "^1.5.4"
+    "qrcode": "^1.5.4",
+    "zod": "^4.5.4"
   },
   "keywords": [
     "formfeed",

package/types/frame/text-edit.d.cts

@@ -9,7 +9,14 @@
  * in place, chips are atomic, and Enter, Tab or leaving the element commit
  * (`formfeed:edit-commit`), Escape cancels. The frame never writes the template: it only sends what
  * the user typed. Ctrl+B, Ctrl+I and Ctrl+U format nothing here; on the design stage they are passed
- * on (`formfeed:edit-style`), where they switch the style of the whole layer.
+ * on (`formfeed:edit-style`), where they switch the style of the whole layer. A session the editor
+ * asks for is not opened once the user has left this window for the app (`formfeed:edit-cancel`):
+ * opening it takes the focus, and that belongs to where the user went.
+ *
+ * A preview document says which one it is (`doc`, from its `formfeed:document` meta) and when its
+ * elements are in place (`formfeed:edit-ready`). The editor renders a moment before the frame takes
+ * the new document, and a click in that moment is about a document on its way out: the editor waits
+ * for the next one and has the frame ask for the same text there (`formfeed:edit-open`).
  */
 /** An item as the frame shows it: chips carry the text to display. */
 export type FrameItem = {

package/types/frame/text-edit.d.ts

@@ -9,7 +9,14 @@
  * in place, chips are atomic, and Enter, Tab or leaving the element commit
  * (`formfeed:edit-commit`), Escape cancels. The frame never writes the template: it only sends what
  * the user typed. Ctrl+B, Ctrl+I and Ctrl+U format nothing here; on the design stage they are passed
- * on (`formfeed:edit-style`), where they switch the style of the whole layer.
+ * on (`formfeed:edit-style`), where they switch the style of the whole layer. A session the editor
+ * asks for is not opened once the user has left this window for the app (`formfeed:edit-cancel`):
+ * opening it takes the focus, and that belongs to where the user went.
+ *
+ * A preview document says which one it is (`doc`, from its `formfeed:document` meta) and when its
+ * elements are in place (`formfeed:edit-ready`). The editor renders a moment before the frame takes
+ * the new document, and a click in that moment is about a document on its way out: the editor waits
+ * for the next one and has the frame ask for the same text there (`formfeed:edit-open`).
  */
 /** An item as the frame shows it: chips carry the text to display. */
 export type FrameItem = {

package/types/index.d.cts

@@ -25,11 +25,13 @@ export { canvasDocument, flowDocument, pagedDocument, pageNumberSpans, paperOf,
 export type { PagedOptions, PreviewOptions, PreviewOverflow, RenderedDraft, } from './lib/preview.cjs';
 export { annotateSourcePositions, editAttribute, parseSourceAttribute, sourceAttribute, } from './lib/source-positions.cjs';
 export type { AnnotateOptions, SourceFile, SourceLocation, } from './lib/source-positions.cjs';
-export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, translationItems, translationText, } from './lib/source-edit.cjs';
+export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, regionPosition, translationItems, translationText, } from './lib/source-edit.cjs';
 export type { ApplyResult, ChipKind, EditableRegion, EditItem, RegionChip, RegionLookup, RegionPart, RegionRefusal, } from './lib/source-edit.cjs';
 export { resolveTranslation, translationTarget } from './lib/translation.cjs';
 export { DESIGN_LIMITS, DESIGN_VERSION, dataPathPattern, defaultLayer, designBytes, designOutputHash, designStarters, emitDesign, emptyDesign, genericFamily, googleFont, googleFonts, googleFontsUrl, imageIsEmpty, layerIdPattern, nearestWeight, nextLayerId, parseDesign, } from './lib/design/index.cjs';
 export type { BarcodeLayer, BarcodeSymbology, Binding, CanvasSize, DesignDocument, DesignLayer, DesignStarter, EmittedDesign, FontChoice, GoogleFont, ImageLayer, ImageSource, LayerBase, LayerType, Paint, ParsedDesign, QrLayer, Shadow, ShapeLayer, Stroke, TextFormat, TextItem, TextLayer, TextStyle, } from './lib/design/index.cjs';
+export { CII_GUIDELINES, CODE_LIST_RELEASE, DISPLAY_TERMS, EINVOICE_FLAVOURS, EINVOICE_FLAVOUR_NAMES, EINVOICE_MAX_MESSAGES, EINVOICE_PROFILES, EINVOICE_PROFILE_NAMES, EINVOICE_SPEC_VERSIONS, EINVOICE_XML_NAME, INVOICE_DATA_KEY, VAT_CATEGORIES, capMessages, checkInvoice, defaultEinvoiceOptions, displayCheck, displayMissingText, einvoiceOptionsSchema, einvoiceResult, einvoiceXml, htmlText, invoiceAmountText, invoiceLineOf, invoicePathSegments, invoiceSchema, invoiceSkeleton, invoiceToCii, locateJsonPath, resolveEinvoiceOptions, shownAmounts, } from './lib/einvoice/index.cjs';
+export type { CheckOptions, DisplayCheck, DisplayValue, EinvoiceDisplay, EinvoiceFlavour, EinvoiceMessage, EinvoiceOptions, EinvoiceOptionsInput, EinvoiceProfile, EinvoiceResult, EinvoiceValidation, EinvoiceXml, Identifier, Invoice, InvoiceAddress, InvoiceAllowance, InvoiceBreakdown, InvoiceCheck, InvoiceInput, InvoiceLine, InvoiceParty, InvoiceProblem, InvoiceProblemCode, InvoiceTax, JsonLocation, ResolvedEinvoice, VatCategory, } from './lib/einvoice/index.cjs';
 export { encodeTemplateText } from './lib/source-edit.cjs';
 export type { Dictionaries } from './lib/translation.cjs';
 export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, HeaderFooterSettings, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.cjs';

package/types/index.d.ts

@@ -25,11 +25,13 @@ export { canvasDocument, flowDocument, pagedDocument, pageNumberSpans, paperOf,
 export type { PagedOptions, PreviewOptions, PreviewOverflow, RenderedDraft, } from './lib/preview.js';
 export { annotateSourcePositions, editAttribute, parseSourceAttribute, sourceAttribute, } from './lib/source-positions.js';
 export type { AnnotateOptions, SourceFile, SourceLocation, } from './lib/source-positions.js';
-export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, translationItems, translationText, } from './lib/source-edit.js';
+export { applyRegionEdit, chipValues, editableRegion, editableRegionAt, findRegionAgain, regionChips, regionItems, regionPosition, translationItems, translationText, } from './lib/source-edit.js';
 export type { ApplyResult, ChipKind, EditableRegion, EditItem, RegionChip, RegionLookup, RegionPart, RegionRefusal, } from './lib/source-edit.js';
 export { resolveTranslation, translationTarget } from './lib/translation.js';
 export { DESIGN_LIMITS, DESIGN_VERSION, dataPathPattern, defaultLayer, designBytes, designOutputHash, designStarters, emitDesign, emptyDesign, genericFamily, googleFont, googleFonts, googleFontsUrl, imageIsEmpty, layerIdPattern, nearestWeight, nextLayerId, parseDesign, } from './lib/design/index.js';
 export type { BarcodeLayer, BarcodeSymbology, Binding, CanvasSize, DesignDocument, DesignLayer, DesignStarter, EmittedDesign, FontChoice, GoogleFont, ImageLayer, ImageSource, LayerBase, LayerType, Paint, ParsedDesign, QrLayer, Shadow, ShapeLayer, Stroke, TextFormat, TextItem, TextLayer, TextStyle, } from './lib/design/index.js';
+export { CII_GUIDELINES, CODE_LIST_RELEASE, DISPLAY_TERMS, EINVOICE_FLAVOURS, EINVOICE_FLAVOUR_NAMES, EINVOICE_MAX_MESSAGES, EINVOICE_PROFILES, EINVOICE_PROFILE_NAMES, EINVOICE_SPEC_VERSIONS, EINVOICE_XML_NAME, INVOICE_DATA_KEY, VAT_CATEGORIES, capMessages, checkInvoice, defaultEinvoiceOptions, displayCheck, displayMissingText, einvoiceOptionsSchema, einvoiceResult, einvoiceXml, htmlText, invoiceAmountText, invoiceLineOf, invoicePathSegments, invoiceSchema, invoiceSkeleton, invoiceToCii, locateJsonPath, resolveEinvoiceOptions, shownAmounts, } from './lib/einvoice/index.js';
+export type { CheckOptions, DisplayCheck, DisplayValue, EinvoiceDisplay, EinvoiceFlavour, EinvoiceMessage, EinvoiceOptions, EinvoiceOptionsInput, EinvoiceProfile, EinvoiceResult, EinvoiceValidation, EinvoiceXml, Identifier, Invoice, InvoiceAddress, InvoiceAllowance, InvoiceBreakdown, InvoiceCheck, InvoiceInput, InvoiceLine, InvoiceParty, InvoiceProblem, InvoiceProblemCode, InvoiceTax, JsonLocation, ResolvedEinvoice, VatCategory, } from './lib/einvoice/index.js';
 export { encodeTemplateText } from './lib/source-edit.js';
 export type { Dictionaries } from './lib/translation.js';
 export type { AssembleExtras, AssembleInput, AssembleVendor, FontFace, HeaderFooterSettings, RenderedDocument, TemplateKind, TemplateSettings, VersionSource, } from './lib/assemble.js';

package/types/lib/assemble.d.cts

@@ -1,4 +1,5 @@
 import type { BrandContext } from './brand.cjs';
+import type { EinvoiceOptionsInput } from './einvoice/schema.cjs';
 import type { EngineId, RenderContext } from './types.cjs';
 /** Template settings (spec 01 §3); every field optional, `defaultSettings()` fills the rest. */
 export interface HeaderFooterSettings {
@@ -70,6 +71,13 @@ export interface TemplateSettings {
         text?: string;
         opacity?: number;
     } | null;
+    /**
+     * The template is an invoice template (spec 17 §4.1): every PDF rendered from it carries the
+     * e-invoice built from the `_invoice` block of the data. A request's `settings.einvoice` and
+     * `post.einvoice` merge over this field by field (`resolveEinvoiceOptions`); `false` there
+     * switches it off for one request.
+     */
+    einvoice?: EinvoiceOptionsInput | false | null;
     /**
      * The visual editor's document (plan 16 §4.1, `DesignDocument` once `parseDesign` accepted it). It
      * is authoring data: nothing renders it, the version's HTML and CSS are what it emitted.

package/types/lib/assemble.d.ts

@@ -1,4 +1,5 @@
 import type { BrandContext } from './brand.js';
+import type { EinvoiceOptionsInput } from './einvoice/schema.js';
 import type { EngineId, RenderContext } from './types.js';
 /** Template settings (spec 01 §3); every field optional, `defaultSettings()` fills the rest. */
 export interface HeaderFooterSettings {
@@ -70,6 +71,13 @@ export interface TemplateSettings {
         text?: string;
         opacity?: number;
     } | null;
+    /**
+     * The template is an invoice template (spec 17 §4.1): every PDF rendered from it carries the
+     * e-invoice built from the `_invoice` block of the data. A request's `settings.einvoice` and
+     * `post.einvoice` merge over this field by field (`resolveEinvoiceOptions`); `false` there
+     * switches it off for one request.
+     */
+    einvoice?: EinvoiceOptionsInput | false | null;
     /**
      * The visual editor's document (plan 16 §4.1, `DesignDocument` once `parseDesign` accepted it). It
      * is authoring data: nothing renders it, the version's HTML and CSS are what it emitted.

package/types/lib/einvoice/check.d.cts

@@ -0,0 +1,181 @@
+import { type EinvoiceProfile, type VatCategory } from './schema.cjs';
+/**
+ * Reads an `_invoice` block against EN 16931 (spec 17 §4.3): the shape first, then the rules a
+ * request can be held to before anything is rendered. What comes out is either the invoice with
+ * every number as exact decimal text, ready for the XML, or the list of what is wrong, each finding
+ * with the field and the rule it breaks.
+ *
+ * Nothing is computed for the caller and nothing is rounded into place. A total that is a cent off
+ * is a finding, because an e-invoice whose XML disagrees with the seller's books is a tax problem,
+ * and correcting it here would hide exactly that.
+ *
+ * The full rule set (the official schematron, some 430 assertions) runs in the sidecar on every
+ * document. This is the part worth knowing early: it needs no JVM, so the gateway answers a bad
+ * request at once, and the editor and the CLI say the same thing offline.
+ */
+export interface InvoiceProblem {
+    /** What kind of finding, for a caller that words it in its own language. */
+    code: InvoiceProblemCode;
+    /** The field inside `_invoice`, dotted, list items as `lines[1]` (zero-based). */
+    path: string;
+    /** The rule of EN 16931 (`BR-CO-15`) or of the French specifications (`BR-FR-10`), where one applies. */
+    rule?: string;
+    /** The same in English, naming the field and the rule. */
+    message: string;
+    /** The values `message` was built from. */
+    args: Record<string, string | number>;
+}
+export type InvoiceProblemCode = 'missing' | 'invalid' | 'not_a_number' | 'decimals' | 'negative' | 'code_list' | 'date' | 'date_order' | 'scheme_required' | 'vat_id_prefix' | 'iban' | 'sum' | 'breakdown_missing' | 'breakdown_duplicate' | 'rate_required' | 'rate_positive' | 'rate_zero' | 'rate_forbidden' | 'amount_zero' | 'exemption_reason_required' | 'exemption_reason_forbidden' | 'seller_tax_id_required' | 'buyer_tax_id_required' | 'vat_id_forbidden' | 'only_category' | 'delivery_required' | 'account_required' | 'means_code_required' | 'due_or_terms_required' | 'seller_identifier_required' | 'siren_mismatch' | 'fr_seller_siren' | 'fr_buyer_siren' | 'fr_operation' | 'fr_vat_on_debits' | 'profile';
+export interface Identifier {
+    value: string;
+    scheme?: string;
+}
+export interface InvoiceAddress {
+    street?: string;
+    street2?: string;
+    street3?: string;
+    postcode?: string;
+    city?: string;
+    country: string;
+    subdivision?: string;
+}
+export interface InvoiceParty {
+    name: string;
+    trading_name?: string;
+    id?: Identifier;
+    legal_registration?: Identifier;
+    vat_id?: string;
+    address: InvoiceAddress;
+    contact?: {
+        name?: string;
+        phone?: string;
+        email?: string;
+    };
+    electronic_address?: Required<Identifier>;
+}
+export interface InvoiceAllowance {
+    amount: string;
+    reason?: string;
+    reason_code?: string;
+    base_amount?: string;
+    percent?: string;
+}
+export interface InvoiceTax {
+    category: VatCategory;
+    /** Percent as decimal text; absent for category O only. */
+    rate?: string;
+}
+export interface InvoiceLine {
+    id: string;
+    name: string;
+    description?: string;
+    quantity: string;
+    unit_code: string;
+    net_price: string;
+    price_base_quantity?: string;
+    net_amount: string;
+    tax: InvoiceTax;
+    period?: {
+        start?: string;
+        end?: string;
+    };
+    allowances: InvoiceAllowance[];
+    charges: InvoiceAllowance[];
+    buyer_accounting_reference?: string;
+    note?: string;
+    seller_item_id?: string;
+    buyer_item_id?: string;
+    standard_item_id?: Identifier;
+    order_line_reference?: string;
+}
+export interface InvoiceBreakdown extends InvoiceTax {
+    basis: string;
+    amount: string;
+    exemption_reason?: string;
+    exemption_reason_code?: string;
+}
+/**
+ * An invoice that passed: every amount is decimal text with at most two places, every code is in
+ * its list, and the totals add up. The XML is written from this and from nothing else.
+ */
+export interface Invoice {
+    number: string;
+    issue_date: string;
+    type_code: string;
+    currency: string;
+    accounting_currency?: string;
+    buyer_reference?: string;
+    order_reference?: string;
+    contract_reference?: string;
+    notes: Array<{
+        text: string;
+        subject_code?: string;
+    }>;
+    period?: {
+        start?: string;
+        end?: string;
+    };
+    preceding_invoices: Array<{
+        number: string;
+        issue_date?: string;
+    }>;
+    /** The business process (BT-23); French invoices carry their billing framework here. */
+    business_process?: string;
+    seller: InvoiceParty & {
+        tax_number?: string;
+        legal_info?: string;
+        vat_on_debits?: boolean;
+    };
+    buyer: InvoiceParty;
+    delivery?: {
+        name?: string;
+        date?: string;
+        address?: InvoiceAddress;
+    };
+    lines: InvoiceLine[];
+    allowances: Array<InvoiceAllowance & {
+        tax: InvoiceTax;
+    }>;
+    charges: Array<InvoiceAllowance & {
+        tax: InvoiceTax;
+    }>;
+    breakdown: InvoiceBreakdown[];
+    totals: {
+        line_net: string;
+        allowances?: string;
+        charges?: string;
+        tax_basis: string;
+        tax_total: string;
+        tax_total_accounting?: string;
+        grand: string;
+        prepaid?: string;
+        rounding?: string;
+        due: string;
+    };
+    payment?: {
+        means_code?: string;
+        iban?: string;
+        bic?: string;
+        account_name?: string;
+        reference?: string;
+        terms?: string;
+        due_date?: string;
+        mandate_id?: string;
+        creditor_id?: string;
+        debited_iban?: string;
+    };
+}
+export type InvoiceCheck = {
+    ok: true;
+    invoice: Invoice;
+    problems: [];
+} | {
+    ok: false;
+    invoice: null;
+    problems: InvoiceProblem[];
+};
+export interface CheckOptions {
+    /** The profile the XML will be written in; `basic` cannot carry everything `en16931` can. */
+    profile?: EinvoiceProfile;
+}
+export declare function checkInvoice(data: unknown, options?: CheckOptions): InvoiceCheck;

package/types/lib/einvoice/check.d.ts

@@ -0,0 +1,181 @@
+import { type EinvoiceProfile, type VatCategory } from './schema.js';
+/**
+ * Reads an `_invoice` block against EN 16931 (spec 17 §4.3): the shape first, then the rules a
+ * request can be held to before anything is rendered. What comes out is either the invoice with
+ * every number as exact decimal text, ready for the XML, or the list of what is wrong, each finding
+ * with the field and the rule it breaks.
+ *
+ * Nothing is computed for the caller and nothing is rounded into place. A total that is a cent off
+ * is a finding, because an e-invoice whose XML disagrees with the seller's books is a tax problem,
+ * and correcting it here would hide exactly that.
+ *
+ * The full rule set (the official schematron, some 430 assertions) runs in the sidecar on every
+ * document. This is the part worth knowing early: it needs no JVM, so the gateway answers a bad
+ * request at once, and the editor and the CLI say the same thing offline.
+ */
+export interface InvoiceProblem {
+    /** What kind of finding, for a caller that words it in its own language. */
+    code: InvoiceProblemCode;
+    /** The field inside `_invoice`, dotted, list items as `lines[1]` (zero-based). */
+    path: string;
+    /** The rule of EN 16931 (`BR-CO-15`) or of the French specifications (`BR-FR-10`), where one applies. */
+    rule?: string;
+    /** The same in English, naming the field and the rule. */
+    message: string;
+    /** The values `message` was built from. */
+    args: Record<string, string | number>;
+}
+export type InvoiceProblemCode = 'missing' | 'invalid' | 'not_a_number' | 'decimals' | 'negative' | 'code_list' | 'date' | 'date_order' | 'scheme_required' | 'vat_id_prefix' | 'iban' | 'sum' | 'breakdown_missing' | 'breakdown_duplicate' | 'rate_required' | 'rate_positive' | 'rate_zero' | 'rate_forbidden' | 'amount_zero' | 'exemption_reason_required' | 'exemption_reason_forbidden' | 'seller_tax_id_required' | 'buyer_tax_id_required' | 'vat_id_forbidden' | 'only_category' | 'delivery_required' | 'account_required' | 'means_code_required' | 'due_or_terms_required' | 'seller_identifier_required' | 'siren_mismatch' | 'fr_seller_siren' | 'fr_buyer_siren' | 'fr_operation' | 'fr_vat_on_debits' | 'profile';
+export interface Identifier {
+    value: string;
+    scheme?: string;
+}
+export interface InvoiceAddress {
+    street?: string;
+    street2?: string;
+    street3?: string;
+    postcode?: string;
+    city?: string;
+    country: string;
+    subdivision?: string;
+}
+export interface InvoiceParty {
+    name: string;
+    trading_name?: string;
+    id?: Identifier;
+    legal_registration?: Identifier;
+    vat_id?: string;
+    address: InvoiceAddress;
+    contact?: {
+        name?: string;
+        phone?: string;
+        email?: string;
+    };
+    electronic_address?: Required<Identifier>;
+}
+export interface InvoiceAllowance {
+    amount: string;
+    reason?: string;
+    reason_code?: string;
+    base_amount?: string;
+    percent?: string;
+}
+export interface InvoiceTax {
+    category: VatCategory;
+    /** Percent as decimal text; absent for category O only. */
+    rate?: string;
+}
+export interface InvoiceLine {
+    id: string;
+    name: string;
+    description?: string;
+    quantity: string;
+    unit_code: string;
+    net_price: string;
+    price_base_quantity?: string;
+    net_amount: string;
+    tax: InvoiceTax;
+    period?: {
+        start?: string;
+        end?: string;
+    };
+    allowances: InvoiceAllowance[];
+    charges: InvoiceAllowance[];
+    buyer_accounting_reference?: string;
+    note?: string;
+    seller_item_id?: string;
+    buyer_item_id?: string;
+    standard_item_id?: Identifier;
+    order_line_reference?: string;
+}
+export interface InvoiceBreakdown extends InvoiceTax {
+    basis: string;
+    amount: string;
+    exemption_reason?: string;
+    exemption_reason_code?: string;
+}
+/**
+ * An invoice that passed: every amount is decimal text with at most two places, every code is in
+ * its list, and the totals add up. The XML is written from this and from nothing else.
+ */
+export interface Invoice {
+    number: string;
+    issue_date: string;
+    type_code: string;
+    currency: string;
+    accounting_currency?: string;
+    buyer_reference?: string;
+    order_reference?: string;
+    contract_reference?: string;
+    notes: Array<{
+        text: string;
+        subject_code?: string;
+    }>;
+    period?: {
+        start?: string;
+        end?: string;
+    };
+    preceding_invoices: Array<{
+        number: string;
+        issue_date?: string;
+    }>;
+    /** The business process (BT-23); French invoices carry their billing framework here. */
+    business_process?: string;
+    seller: InvoiceParty & {
+        tax_number?: string;
+        legal_info?: string;
+        vat_on_debits?: boolean;
+    };
+    buyer: InvoiceParty;
+    delivery?: {
+        name?: string;
+        date?: string;
+        address?: InvoiceAddress;
+    };
+    lines: InvoiceLine[];
+    allowances: Array<InvoiceAllowance & {
+        tax: InvoiceTax;
+    }>;
+    charges: Array<InvoiceAllowance & {
+        tax: InvoiceTax;
+    }>;
+    breakdown: InvoiceBreakdown[];
+    totals: {
+        line_net: string;
+        allowances?: string;
+        charges?: string;
+        tax_basis: string;
+        tax_total: string;
+        tax_total_accounting?: string;
+        grand: string;
+        prepaid?: string;
+        rounding?: string;
+        due: string;
+    };
+    payment?: {
+        means_code?: string;
+        iban?: string;
+        bic?: string;
+        account_name?: string;
+        reference?: string;
+        terms?: string;
+        due_date?: string;
+        mandate_id?: string;
+        creditor_id?: string;
+        debited_iban?: string;
+    };
+}
+export type InvoiceCheck = {
+    ok: true;
+    invoice: Invoice;
+    problems: [];
+} | {
+    ok: false;
+    invoice: null;
+    problems: InvoiceProblem[];
+};
+export interface CheckOptions {
+    /** The profile the XML will be written in; `basic` cannot carry everything `en16931` can. */
+    profile?: EinvoiceProfile;
+}
+export declare function checkInvoice(data: unknown, options?: CheckOptions): InvoiceCheck;

package/types/lib/einvoice/cii.d.cts

@@ -0,0 +1,18 @@
+import type { Invoice } from './check.cjs';
+import type { EinvoiceProfile } from './schema.cjs';
+/**
+ * A checked invoice as Cross Industry Invoice XML, the syntax ZUGFeRD and Factur-X embed (spec 17
+ * §3, §5). The element order is the schema's: the XSD of a profile is a sequence, and an element in
+ * the wrong place fails before any business rule is looked at.
+ *
+ * The output is a function of the invoice and the profile alone. No date of writing, no generator
+ * comment, no locale: two renders of the same data embed the same bytes, and the golden files in
+ * `fixtures/` pin them.
+ */
+/** The identifier a document names its profile by (BT-24). */
+export declare const CII_GUIDELINES: Record<EinvoiceProfile, string>;
+/** The name the XML has inside the PDF, under either of the specification's two names. */
+export declare const EINVOICE_XML_NAME = "factur-x.xml";
+export declare function invoiceToCii(invoice: Invoice, options: {
+    profile: EinvoiceProfile;
+}): string;

package/types/lib/einvoice/cii.d.ts

@@ -0,0 +1,18 @@
+import type { Invoice } from './check.js';
+import type { EinvoiceProfile } from './schema.js';
+/**
+ * A checked invoice as Cross Industry Invoice XML, the syntax ZUGFeRD and Factur-X embed (spec 17
+ * §3, §5). The element order is the schema's: the XSD of a profile is a sequence, and an element in
+ * the wrong place fails before any business rule is looked at.
+ *
+ * The output is a function of the invoice and the profile alone. No date of writing, no generator
+ * comment, no locale: two renders of the same data embed the same bytes, and the golden files in
+ * `fixtures/` pin them.
+ */
+/** The identifier a document names its profile by (BT-24). */
+export declare const CII_GUIDELINES: Record<EinvoiceProfile, string>;
+/** The name the XML has inside the PDF, under either of the specification's two names. */
+export declare const EINVOICE_XML_NAME = "factur-x.xml";
+export declare function invoiceToCii(invoice: Invoice, options: {
+    profile: EinvoiceProfile;
+}): string;

package/types/lib/einvoice/codes.generated.d.cts

@@ -0,0 +1,14 @@
+/** The Factur-X release these lists were taken from. */
+export declare const CODE_LIST_RELEASE = "1.09.2";
+/** Invoice type code (BT-3), UNTDID 1001. 62 codes. */
+export declare const documentTypeCodes: ReadonlySet<string>;
+/** Country codes (BT-40, BT-55, BT-80), ISO 3166-1 alpha-2. 253 codes. */
+export declare const countryCodes: ReadonlySet<string>;
+/** Units of measure (BT-130, BT-150), UN/ECE Recommendation 20 with 21. 2162 codes. */
+export declare const unitCodes: ReadonlySet<string>;
+/** Electronic address schemes (BT-34, BT-49), the EAS list. 102 codes. */
+export declare const electronicAddressSchemes: ReadonlySet<string>;
+/** Currencies (BT-5, BT-6), ISO 4217. 178 codes. */
+export declare const currencyCodes: ReadonlySet<string>;
+/** Payment means (BT-81), UNTDID 4461. 84 codes. */
+export declare const paymentMeansCodes: ReadonlySet<string>;

package/types/lib/einvoice/codes.generated.d.ts

@@ -0,0 +1,14 @@
+/** The Factur-X release these lists were taken from. */
+export declare const CODE_LIST_RELEASE = "1.09.2";
+/** Invoice type code (BT-3), UNTDID 1001. 62 codes. */
+export declare const documentTypeCodes: ReadonlySet<string>;
+/** Country codes (BT-40, BT-55, BT-80), ISO 3166-1 alpha-2. 253 codes. */
+export declare const countryCodes: ReadonlySet<string>;
+/** Units of measure (BT-130, BT-150), UN/ECE Recommendation 20 with 21. 2162 codes. */
+export declare const unitCodes: ReadonlySet<string>;
+/** Electronic address schemes (BT-34, BT-49), the EAS list. 102 codes. */
+export declare const electronicAddressSchemes: ReadonlySet<string>;
+/** Currencies (BT-5, BT-6), ISO 4217. 178 codes. */
+export declare const currencyCodes: ReadonlySet<string>;
+/** Payment means (BT-81), UNTDID 4461. 84 codes. */
+export declare const paymentMeansCodes: ReadonlySet<string>;

package/types/lib/einvoice/decimal.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Exact decimals for an invoice. Totals are compared to the cent and written into the XML as text,
+ * so nothing here goes through floating-point arithmetic: a value is read once into its decimal
+ * text and from there into a `bigint` of the smallest unit the comparison needs.
+ */
+/**
+ * The decimal text of a JSON number or a numeric string, without an exponent and without trailing
+ * zeros; `null` when it is not a plain decimal.
+ *
+ * A number is taken at fifteen significant digits, which is every digit a double holds exactly: a
+ * request built with ordinary arithmetic sends `0.30000000000000004` for thirty cents, and refusing
+ * that as "more than two decimals" would punish the language, not the invoice. A string is taken
+ * as written, since whoever sends `"0.300000000000000004"` typed those digits.
+ */
+export declare function decimalText(value: unknown): string | null;
+/** How many decimal places a decimal text carries. */
+export declare function decimalPlaces(text: string): number;
+/**
+ * A decimal text as an integer of `10^-scale` units. The text must not carry more places than
+ * `scale`; callers check that first and name the field, because that is a finding about the data.
+ */
+export declare function toUnits(text: string, scale: number): bigint;
+/** Integer units back to decimal text with exactly `places` decimals (`376040n, 2` → `3760.40`). */
+export declare function fromUnits(units: bigint, scale: number, places?: number): string;
+/** A decimal text padded to at least `min` decimals, as the XML writes amounts (`3760.4` → `3760.40`). */
+export declare function withPlaces(text: string, min: number): string;
+/** `value / divisor`, rounded half away from zero, as the standard rounds a VAT amount. */
+export declare function divideRounded(value: bigint, divisor: bigint): bigint;
+export declare const abs: (value: bigint) => bigint;

package/types/lib/einvoice/decimal.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Exact decimals for an invoice. Totals are compared to the cent and written into the XML as text,
+ * so nothing here goes through floating-point arithmetic: a value is read once into its decimal
+ * text and from there into a `bigint` of the smallest unit the comparison needs.
+ */
+/**
+ * The decimal text of a JSON number or a numeric string, without an exponent and without trailing
+ * zeros; `null` when it is not a plain decimal.
+ *
+ * A number is taken at fifteen significant digits, which is every digit a double holds exactly: a
+ * request built with ordinary arithmetic sends `0.30000000000000004` for thirty cents, and refusing
+ * that as "more than two decimals" would punish the language, not the invoice. A string is taken
+ * as written, since whoever sends `"0.300000000000000004"` typed those digits.
+ */
+export declare function decimalText(value: unknown): string | null;
+/** How many decimal places a decimal text carries. */
+export declare function decimalPlaces(text: string): number;
+/**
+ * A decimal text as an integer of `10^-scale` units. The text must not carry more places than
+ * `scale`; callers check that first and name the field, because that is a finding about the data.
+ */
+export declare function toUnits(text: string, scale: number): bigint;
+/** Integer units back to decimal text with exactly `places` decimals (`376040n, 2` → `3760.40`). */
+export declare function fromUnits(units: bigint, scale: number, places?: number): string;
+/** A decimal text padded to at least `min` decimals, as the XML writes amounts (`3760.4` → `3760.40`). */
+export declare function withPlaces(text: string, min: number): string;
+/** `value / divisor`, rounded half away from zero, as the standard rounds a VAT amount. */
+export declare function divideRounded(value: bigint, divisor: bigint): bigint;
+export declare const abs: (value: bigint) => bigint;