@formfeed/engine 0.3.10 → 0.3.12

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

@@ -0,0 +1,59 @@
+import type { DisplayCheck } from './display.js';
+import type { EinvoiceFlavour, EinvoiceOptions, EinvoiceProfile } from './schema.js';
+/**
+ * What a render says about its e-invoice (spec 17 §4.1, §5): the validator's report and the display
+ * check. One shape for the render-worker that builds it, the database row that keeps it, the API
+ * that returns it, the render log and the CLI that show it.
+ */
+/** One finding of the validator: a rule of the XML (schematron, XSD) or of PDF/A (veraPDF). */
+export interface EinvoiceMessage {
+    part: 'xml' | 'pdf';
+    severity: 'error' | 'warning';
+    /** `BR-CO-15`, `CII-SR-465`, or a clause of PDF/A such as `6.2.11.4.1-1`. */
+    rule: string | null;
+    message: string;
+    /** Where: an XPath into the XML, or the object of the PDF. */
+    location: string | null;
+}
+export interface EinvoiceValidation {
+    valid: boolean;
+    /** The rule set the XML was held to, as the validator names it. */
+    schematron: string;
+    /** `PDF/A-3b` once the file was checked; `null` when validation ended at the XML. */
+    pdfa: string | null;
+    messages: EinvoiceMessage[];
+    /** More findings than the render keeps. */
+    truncated?: boolean;
+}
+export interface EinvoiceDisplay {
+    /** The business terms looked for in the text of the PDF (`BT-1`, `BT-112`). */
+    checked: string[];
+    /** Those the text does not show. */
+    missing: string[];
+}
+/** `einvoice` of a render as the row keeps it; the API adds `xml_url`. */
+export interface EinvoiceResult {
+    profile: EinvoiceProfile;
+    flavour: EinvoiceFlavour;
+    /** The release of the specification under the flavour's name: `1.09` or `2.5`. */
+    spec_version: string;
+    validation: EinvoiceValidation | null;
+    display: EinvoiceDisplay | null;
+}
+/**
+ * A render row travels in every list and webhook, so it keeps this many findings and says when there
+ * were more. Errors go first: a report cut short must not lose the reason it failed to warnings.
+ */
+export declare const EINVOICE_MAX_MESSAGES = 50;
+export declare function capMessages(messages: readonly EinvoiceMessage[], max?: number): Pick<EinvoiceValidation, 'messages' | 'truncated'>;
+/** The result of a render that got as far as `validation` and `display` say. */
+export declare function einvoiceResult(options: Pick<EinvoiceOptions, 'profile' | 'flavour'>, specVersion: string, validation: EinvoiceValidation | null, display: DisplayCheck | null): EinvoiceResult;
+/** The names a person reads: `Factur-X` and `EN 16931` for `factur-x` and `en16931`. */
+export declare const EINVOICE_FLAVOUR_NAMES: Record<EinvoiceFlavour, string>;
+export declare const EINVOICE_PROFILE_NAMES: Record<EinvoiceProfile, string>;
+/**
+ * Where in the invoice a finding of the XML sits, for a reader who knows `_invoice` and not CII:
+ * `line 2` for anything inside the second line item, `null` where the path names no line. The XPath
+ * itself stays beside it; this only spares the reader counting brackets.
+ */
+export declare function invoiceLineOf(location: string | null): number | null;

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

@@ -0,0 +1,293 @@
+import { z } from 'zod';
+/** VAT categories of UNCL 5305 as EN 16931 uses them (spec 17 §4.3). */
+export declare const VAT_CATEGORIES: readonly ["S", "Z", "E", "AE", "K", "G", "O"];
+export type VatCategory = (typeof VAT_CATEGORIES)[number];
+export declare const invoiceSchema: z.ZodObject<{
+    number: z.ZodString;
+    issue_date: z.ZodString;
+    type_code: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    currency: z.ZodString;
+    accounting_currency: z.ZodOptional<z.ZodString>;
+    buyer_reference: z.ZodOptional<z.ZodString>;
+    order_reference: z.ZodOptional<z.ZodString>;
+    contract_reference: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        subject_code: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    period: z.ZodOptional<z.ZodObject<{
+        start: z.ZodOptional<z.ZodString>;
+        end: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    preceding_invoices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        number: z.ZodString;
+        issue_date: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    operation: z.ZodOptional<z.ZodEnum<{
+        goods: "goods";
+        services: "services";
+        mixed: "mixed";
+    }>>;
+    operation_code: z.ZodOptional<z.ZodString>;
+    seller: z.ZodObject<{
+        name: z.ZodString;
+        trading_name: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        legal_registration: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        vat_id: z.ZodOptional<z.ZodString>;
+        address: z.ZodObject<{
+            street: z.ZodOptional<z.ZodString>;
+            street2: z.ZodOptional<z.ZodString>;
+            street3: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            subdivision: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        electronic_address: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        tax_number: z.ZodOptional<z.ZodString>;
+        legal_info: z.ZodOptional<z.ZodString>;
+        vat_on_debits: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    buyer: z.ZodObject<{
+        name: z.ZodString;
+        trading_name: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        legal_registration: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        vat_id: z.ZodOptional<z.ZodString>;
+        address: z.ZodObject<{
+            street: z.ZodOptional<z.ZodString>;
+            street2: z.ZodOptional<z.ZodString>;
+            street3: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            subdivision: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        electronic_address: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        siren: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    delivery: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodObject<{
+            street: z.ZodOptional<z.ZodString>;
+            street2: z.ZodOptional<z.ZodString>;
+            street3: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            subdivision: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    lines: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        quantity: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        unit_code: z.ZodDefault<z.ZodString>;
+        net_price: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        price_base_quantity: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        net_amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        tax: z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>;
+        period: z.ZodOptional<z.ZodObject<{
+            start: z.ZodOptional<z.ZodString>;
+            end: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        allowances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            reason: z.ZodOptional<z.ZodString>;
+            reason_code: z.ZodOptional<z.ZodString>;
+            base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>>>;
+        charges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            reason: z.ZodOptional<z.ZodString>;
+            reason_code: z.ZodOptional<z.ZodString>;
+            base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>>>;
+        buyer_accounting_reference: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+        seller_item_id: z.ZodOptional<z.ZodString>;
+        buyer_item_id: z.ZodOptional<z.ZodString>;
+        standard_item_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        order_line_reference: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    allowances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        reason: z.ZodOptional<z.ZodString>;
+        reason_code: z.ZodOptional<z.ZodString>;
+        base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        tax: z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    charges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        reason: z.ZodOptional<z.ZodString>;
+        reason_code: z.ZodOptional<z.ZodString>;
+        base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        tax: z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    tax: z.ZodObject<{
+        breakdown: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            basis: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            exemption_reason: z.ZodOptional<z.ZodString>;
+            exemption_reason_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    totals: z.ZodObject<{
+        line_net: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        allowances: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        charges: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        tax_basis: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        tax_total: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        tax_total_accounting: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        grand: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        prepaid: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        rounding: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        due: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    }, z.core.$strip>;
+    payment: z.ZodOptional<z.ZodObject<{
+        means_code: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        iban: z.ZodOptional<z.ZodString>;
+        bic: z.ZodOptional<z.ZodString>;
+        account_name: z.ZodOptional<z.ZodString>;
+        reference: z.ZodOptional<z.ZodString>;
+        terms: z.ZodOptional<z.ZodString>;
+        due_date: z.ZodOptional<z.ZodString>;
+        mandate_id: z.ZodOptional<z.ZodString>;
+        creditor_id: z.ZodOptional<z.ZodString>;
+        debited_iban: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The block as a caller writes it. */
+export type InvoiceInput = z.input<typeof invoiceSchema>;
+/** The block once parsed: defaults filled in, numbers still as they came. */
+export type ParsedInvoice = z.output<typeof invoiceSchema>;
+export type ParsedParty = ParsedInvoice['seller'] | ParsedInvoice['buyer'];
+export type ParsedLine = ParsedInvoice['lines'][number];
+export declare const EINVOICE_PROFILES: readonly ["basic", "en16931"];
+export type EinvoiceProfile = (typeof EINVOICE_PROFILES)[number];
+export declare const EINVOICE_FLAVOURS: readonly ["factur-x", "zugferd"];
+export type EinvoiceFlavour = (typeof EINVOICE_FLAVOURS)[number];
+/**
+ * `post.einvoice` of a request and `settings.einvoice` of a template (spec 17 §4.1). `profile` and
+ * `flavour` are text here on purpose: a profile we do not emit (`minimum`, `xrechnung`) is answered
+ * with `einvoice_profile_unsupported` and its own explanation, not as a malformed request.
+ */
+export declare const einvoiceOptionsSchema: z.ZodObject<{
+    profile: z.ZodOptional<z.ZodString>;
+    flavour: z.ZodOptional<z.ZodString>;
+    xml: z.ZodOptional<z.ZodEnum<{
+        embedded: "embedded";
+        both: "both";
+    }>>;
+    display_check: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        strict: "strict";
+    }>>;
+}, z.core.$strict>;
+export type EinvoiceOptionsInput = z.infer<typeof einvoiceOptionsSchema>;
+/** The options with every default filled in: what the worker acts on and the render records. */
+export interface EinvoiceOptions {
+    profile: EinvoiceProfile;
+    flavour: EinvoiceFlavour;
+    xml: 'embedded' | 'both';
+    display_check: 'warn' | 'strict';
+}
+export declare const defaultEinvoiceOptions: EinvoiceOptions;
+export type ResolvedEinvoice = {
+    ok: true;
+    options: EinvoiceOptions | null;
+} | {
+    ok: false;
+    field: 'profile' | 'flavour';
+    value: string;
+    reason: string;
+};
+/**
+ * One e-invoice declaration out of its layers, earliest first (the template's settings, the
+ * request's settings, `post.einvoice`). Fields merge one by one with the later layer winning, like
+ * every other setting; `false` drops whatever was declared before it, so a request can switch a
+ * template's declaration off; `null` when nothing declares an e-invoice.
+ */
+export declare function resolveEinvoiceOptions(...layers: Array<EinvoiceOptionsInput | false | null | undefined>): ResolvedEinvoice;

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

@@ -0,0 +1,293 @@
+import { z } from 'zod';
+/** VAT categories of UNCL 5305 as EN 16931 uses them (spec 17 §4.3). */
+export declare const VAT_CATEGORIES: readonly ["S", "Z", "E", "AE", "K", "G", "O"];
+export type VatCategory = (typeof VAT_CATEGORIES)[number];
+export declare const invoiceSchema: z.ZodObject<{
+    number: z.ZodString;
+    issue_date: z.ZodString;
+    type_code: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    currency: z.ZodString;
+    accounting_currency: z.ZodOptional<z.ZodString>;
+    buyer_reference: z.ZodOptional<z.ZodString>;
+    order_reference: z.ZodOptional<z.ZodString>;
+    contract_reference: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    notes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        subject_code: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    period: z.ZodOptional<z.ZodObject<{
+        start: z.ZodOptional<z.ZodString>;
+        end: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    preceding_invoices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        number: z.ZodString;
+        issue_date: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    operation: z.ZodOptional<z.ZodEnum<{
+        goods: "goods";
+        services: "services";
+        mixed: "mixed";
+    }>>;
+    operation_code: z.ZodOptional<z.ZodString>;
+    seller: z.ZodObject<{
+        name: z.ZodString;
+        trading_name: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        legal_registration: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        vat_id: z.ZodOptional<z.ZodString>;
+        address: z.ZodObject<{
+            street: z.ZodOptional<z.ZodString>;
+            street2: z.ZodOptional<z.ZodString>;
+            street3: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            subdivision: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        electronic_address: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        tax_number: z.ZodOptional<z.ZodString>;
+        legal_info: z.ZodOptional<z.ZodString>;
+        vat_on_debits: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    buyer: z.ZodObject<{
+        name: z.ZodString;
+        trading_name: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        legal_registration: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        vat_id: z.ZodOptional<z.ZodString>;
+        address: z.ZodObject<{
+            street: z.ZodOptional<z.ZodString>;
+            street2: z.ZodOptional<z.ZodString>;
+            street3: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            subdivision: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        contact: z.ZodOptional<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            phone: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        electronic_address: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        siren: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    delivery: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        date: z.ZodOptional<z.ZodString>;
+        address: z.ZodOptional<z.ZodObject<{
+            street: z.ZodOptional<z.ZodString>;
+            street2: z.ZodOptional<z.ZodString>;
+            street3: z.ZodOptional<z.ZodString>;
+            postcode: z.ZodOptional<z.ZodString>;
+            city: z.ZodOptional<z.ZodString>;
+            country: z.ZodString;
+            subdivision: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    lines: z.ZodArray<z.ZodObject<{
+        id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        quantity: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        unit_code: z.ZodDefault<z.ZodString>;
+        net_price: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        price_base_quantity: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        net_amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        tax: z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>;
+        period: z.ZodOptional<z.ZodObject<{
+            start: z.ZodOptional<z.ZodString>;
+            end: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        allowances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            reason: z.ZodOptional<z.ZodString>;
+            reason_code: z.ZodOptional<z.ZodString>;
+            base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>>>;
+        charges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            reason: z.ZodOptional<z.ZodString>;
+            reason_code: z.ZodOptional<z.ZodString>;
+            base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>>>;
+        buyer_accounting_reference: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+        seller_item_id: z.ZodOptional<z.ZodString>;
+        buyer_item_id: z.ZodOptional<z.ZodString>;
+        standard_item_id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            value: z.ZodString;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>;
+        order_line_reference: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    allowances: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        reason: z.ZodOptional<z.ZodString>;
+        reason_code: z.ZodOptional<z.ZodString>;
+        base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        tax: z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    charges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        reason: z.ZodOptional<z.ZodString>;
+        reason_code: z.ZodOptional<z.ZodString>;
+        base_amount: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        percent: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        tax: z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+    tax: z.ZodObject<{
+        breakdown: z.ZodArray<z.ZodObject<{
+            category: z.ZodEnum<{
+                Z: "Z";
+                E: "E";
+                G: "G";
+                S: "S";
+                AE: "AE";
+                K: "K";
+                O: "O";
+            }>;
+            rate: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+            basis: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            amount: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+            exemption_reason: z.ZodOptional<z.ZodString>;
+            exemption_reason_code: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    totals: z.ZodObject<{
+        line_net: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        allowances: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        charges: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        tax_basis: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        tax_total: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        tax_total_accounting: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        grand: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+        prepaid: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        rounding: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        due: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+    }, z.core.$strip>;
+    payment: z.ZodOptional<z.ZodObject<{
+        means_code: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        iban: z.ZodOptional<z.ZodString>;
+        bic: z.ZodOptional<z.ZodString>;
+        account_name: z.ZodOptional<z.ZodString>;
+        reference: z.ZodOptional<z.ZodString>;
+        terms: z.ZodOptional<z.ZodString>;
+        due_date: z.ZodOptional<z.ZodString>;
+        mandate_id: z.ZodOptional<z.ZodString>;
+        creditor_id: z.ZodOptional<z.ZodString>;
+        debited_iban: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** The block as a caller writes it. */
+export type InvoiceInput = z.input<typeof invoiceSchema>;
+/** The block once parsed: defaults filled in, numbers still as they came. */
+export type ParsedInvoice = z.output<typeof invoiceSchema>;
+export type ParsedParty = ParsedInvoice['seller'] | ParsedInvoice['buyer'];
+export type ParsedLine = ParsedInvoice['lines'][number];
+export declare const EINVOICE_PROFILES: readonly ["basic", "en16931"];
+export type EinvoiceProfile = (typeof EINVOICE_PROFILES)[number];
+export declare const EINVOICE_FLAVOURS: readonly ["factur-x", "zugferd"];
+export type EinvoiceFlavour = (typeof EINVOICE_FLAVOURS)[number];
+/**
+ * `post.einvoice` of a request and `settings.einvoice` of a template (spec 17 §4.1). `profile` and
+ * `flavour` are text here on purpose: a profile we do not emit (`minimum`, `xrechnung`) is answered
+ * with `einvoice_profile_unsupported` and its own explanation, not as a malformed request.
+ */
+export declare const einvoiceOptionsSchema: z.ZodObject<{
+    profile: z.ZodOptional<z.ZodString>;
+    flavour: z.ZodOptional<z.ZodString>;
+    xml: z.ZodOptional<z.ZodEnum<{
+        embedded: "embedded";
+        both: "both";
+    }>>;
+    display_check: z.ZodOptional<z.ZodEnum<{
+        warn: "warn";
+        strict: "strict";
+    }>>;
+}, z.core.$strict>;
+export type EinvoiceOptionsInput = z.infer<typeof einvoiceOptionsSchema>;
+/** The options with every default filled in: what the worker acts on and the render records. */
+export interface EinvoiceOptions {
+    profile: EinvoiceProfile;
+    flavour: EinvoiceFlavour;
+    xml: 'embedded' | 'both';
+    display_check: 'warn' | 'strict';
+}
+export declare const defaultEinvoiceOptions: EinvoiceOptions;
+export type ResolvedEinvoice = {
+    ok: true;
+    options: EinvoiceOptions | null;
+} | {
+    ok: false;
+    field: 'profile' | 'flavour';
+    value: string;
+    reason: string;
+};
+/**
+ * One e-invoice declaration out of its layers, earliest first (the template's settings, the
+ * request's settings, `post.einvoice`). Fields merge one by one with the later layer winning, like
+ * every other setting; `false` drops whatever was declared before it, so a request can switch a
+ * template's declaration off; `null` when nothing declares an e-invoice.
+ */
+export declare function resolveEinvoiceOptions(...layers: Array<EinvoiceOptionsInput | false | null | undefined>): ResolvedEinvoice;

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

@@ -0,0 +1,10 @@
+import type { InvoiceInput } from './schema.cjs';
+/**
+ * A complete `_invoice` block with placeholder values, for a data set that has none yet: the editor
+ * inserts it, and the docs show it. Every value is one to replace; it is valid as it stands, so the
+ * first preview of a template that reads it renders, and passes the check.
+ *
+ * The names are the placeholders every published sample of ours uses. `issueDate` is a parameter
+ * because the engine has no clock of its own.
+ */
+export declare function invoiceSkeleton(issueDate?: string): InvoiceInput;

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

@@ -0,0 +1,10 @@
+import type { InvoiceInput } from './schema.js';
+/**
+ * A complete `_invoice` block with placeholder values, for a data set that has none yet: the editor
+ * inserts it, and the docs show it. Every value is one to replace; it is valid as it stands, so the
+ * first preview of a template that reads it renders, and passes the check.
+ *
+ * The names are the placeholders every published sample of ours uses. `issueDate` is a parameter
+ * because the engine has no clock of its own.
+ */
+export declare function invoiceSkeleton(issueDate?: string): InvoiceInput;