@formfeed/engine 0.3.11 → 0.3.12

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

@@ -0,0 +1,43 @@
+import type { Invoice } from './check.cjs';
+/**
+ * The display check (spec 17 §5.2). In a hybrid invoice the XML is the invoice, and a PDF that shows
+ * other details can count as a second one. Nothing makes a template print `_invoice`: one that adds
+ * up its own totals, or shows another field's number, renders without complaint. So the text of the
+ * finished PDF is searched for what the XML says: the invoice number and the totals.
+ *
+ * It finds a value that is missing, not a wrong one printed beside the right one. It is a net, not
+ * a proof, and it errs towards "shown": signs are ignored, because a credit note prints as negative
+ * what its XML states as positive, and a number counts in either notation, `1.234,56` or `1,234.56`.
+ *
+ * One function for the worker (the text the sidecar extracts), the editor (the preview's text) and
+ * the CLI, so all three agree on what "shown" means.
+ */
+export interface DisplayValue {
+    /** The business term of EN 16931, `BT-112`. */
+    term: string;
+    /** Where the value sits in `_invoice`. */
+    path: string;
+    /** The value as the XML states it. */
+    value: string;
+    shown: boolean;
+}
+export interface DisplayCheck {
+    /** The terms that were looked for, in the order they were checked. */
+    checked: string[];
+    /** Those of them the text does not show. */
+    missing: string[];
+    values: DisplayValue[];
+}
+/** What a term is called where a message names it. */
+export declare const DISPLAY_TERMS: Record<string, string>;
+/**
+ * Every amount the text shows, in cents and without its sign. A run of digits and separators is
+ * read each way it can be read: `3.760` is three thousand seven hundred and sixty and also three
+ * point seven six, and `8 120,00` is both that number and `120,00` after an `8`. A line break never
+ * joins two numbers, so a page number above a total does not become part of it.
+ */
+export declare function shownAmounts(text: string): Set<bigint>;
+/** The text of a PDF (one string, or one per page) against the invoice its XML states. */
+export declare function displayCheck(text: string | readonly string[], invoice: Invoice): DisplayCheck;
+/** The values a check did not find, as one sentence for a problem or a warning; `null` when all are shown. */
+export declare function displayMissingText(check: DisplayCheck): string | null;

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

@@ -0,0 +1,43 @@
+import type { Invoice } from './check.js';
+/**
+ * The display check (spec 17 §5.2). In a hybrid invoice the XML is the invoice, and a PDF that shows
+ * other details can count as a second one. Nothing makes a template print `_invoice`: one that adds
+ * up its own totals, or shows another field's number, renders without complaint. So the text of the
+ * finished PDF is searched for what the XML says: the invoice number and the totals.
+ *
+ * It finds a value that is missing, not a wrong one printed beside the right one. It is a net, not
+ * a proof, and it errs towards "shown": signs are ignored, because a credit note prints as negative
+ * what its XML states as positive, and a number counts in either notation, `1.234,56` or `1,234.56`.
+ *
+ * One function for the worker (the text the sidecar extracts), the editor (the preview's text) and
+ * the CLI, so all three agree on what "shown" means.
+ */
+export interface DisplayValue {
+    /** The business term of EN 16931, `BT-112`. */
+    term: string;
+    /** Where the value sits in `_invoice`. */
+    path: string;
+    /** The value as the XML states it. */
+    value: string;
+    shown: boolean;
+}
+export interface DisplayCheck {
+    /** The terms that were looked for, in the order they were checked. */
+    checked: string[];
+    /** Those of them the text does not show. */
+    missing: string[];
+    values: DisplayValue[];
+}
+/** What a term is called where a message names it. */
+export declare const DISPLAY_TERMS: Record<string, string>;
+/**
+ * Every amount the text shows, in cents and without its sign. A run of digits and separators is
+ * read each way it can be read: `3.760` is three thousand seven hundred and sixty and also three
+ * point seven six, and `8 120,00` is both that number and `120,00` after an `8`. A line break never
+ * joins two numbers, so a page number above a total does not become part of it.
+ */
+export declare function shownAmounts(text: string): Set<bigint>;
+/** The text of a PDF (one string, or one per page) against the invoice its XML states. */
+export declare function displayCheck(text: string | readonly string[], invoice: Invoice): DisplayCheck;
+/** The values a check did not find, as one sentence for a problem or a warning; `null` when all are shown. */
+export declare function displayMissingText(check: DisplayCheck): string | null;

package/types/lib/einvoice/html-text.d.cts

@@ -0,0 +1,17 @@
+/**
+ * The text of a rendered HTML document, for the display check before anything is rendered to PDF
+ * (spec 17 §5.2, §8): the editor holds the preview's document against the invoice, and the CLI the
+ * document it renders locally. The render itself checks the text of the finished PDF, which the
+ * sidecar extracts; this is the early warning, and it reads the markup, not the page.
+ *
+ * So it does not know what CSS hides or generates. What it must get right is where one number ends
+ * and the next begins: two table cells are two amounts, and an amount set in two `<span>`s is one.
+ * Elements that flow in a line join their text; every other element ends the line.
+ *
+ * No DOM is used: the engine runs in a Worker and in Node as well as in the browser.
+ */
+/**
+ * The text a reader of `html` sees, as far as the markup says: comments, scripts and styles left
+ * out, references decoded, and a line break wherever an element that is not inline starts or ends.
+ */
+export declare function htmlText(html: string): string;

package/types/lib/einvoice/html-text.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The text of a rendered HTML document, for the display check before anything is rendered to PDF
+ * (spec 17 §5.2, §8): the editor holds the preview's document against the invoice, and the CLI the
+ * document it renders locally. The render itself checks the text of the finished PDF, which the
+ * sidecar extracts; this is the early warning, and it reads the markup, not the page.
+ *
+ * So it does not know what CSS hides or generates. What it must get right is where one number ends
+ * and the next begins: two table cells are two amounts, and an amount set in two `<span>`s is one.
+ * Elements that flow in a line join their text; every other element ends the line.
+ *
+ * No DOM is used: the engine runs in a Worker and in Node as well as in the browser.
+ */
+/**
+ * The text a reader of `html` sees, as far as the markup says: comments, scripts and styles left
+ * out, references decoded, and a line break wherever an element that is not inline starts or ends.
+ */
+export declare function htmlText(html: string): string;

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

@@ -0,0 +1,45 @@
+/**
+ * `@formfeed/engine/einvoice` (spec 17): the `_invoice` block, the rules it is held to, the CII XML
+ * written from it and the display check. No template engine is imported here and nothing of Node,
+ * so the gateway Worker, the render-worker, the editor and the CLI all run the same code: what the
+ * API refuses, the editor has already said.
+ */
+import { type Invoice, type InvoiceProblem } from './check.cjs';
+import type { EinvoiceFlavour, EinvoiceProfile } from './schema.cjs';
+export { checkInvoice, type CheckOptions, type Identifier, type Invoice, type InvoiceAddress, type InvoiceAllowance, type InvoiceBreakdown, type InvoiceCheck, type InvoiceLine, type InvoiceParty, type InvoiceProblem, type InvoiceProblemCode, type InvoiceTax, } from './check.cjs';
+export { CII_GUIDELINES, EINVOICE_XML_NAME, invoiceToCii } from './cii.cjs';
+export { CODE_LIST_RELEASE } from './codes.generated.cjs';
+export { DISPLAY_TERMS, displayCheck, displayMissingText, shownAmounts, type DisplayCheck, type DisplayValue, } from './display.cjs';
+export { EINVOICE_FLAVOURS, EINVOICE_PROFILES, VAT_CATEGORIES, defaultEinvoiceOptions, einvoiceOptionsSchema, invoiceSchema, resolveEinvoiceOptions, type EinvoiceFlavour, type EinvoiceOptions, type EinvoiceOptionsInput, type EinvoiceProfile, type InvoiceInput, type ResolvedEinvoice, type VatCategory, } from './schema.cjs';
+export { invoicePathSegments, locateJsonPath, type JsonLocation, } from './locate.cjs';
+export { EINVOICE_FLAVOUR_NAMES, EINVOICE_MAX_MESSAGES, EINVOICE_PROFILE_NAMES, capMessages, einvoiceResult, invoiceLineOf, type EinvoiceDisplay, type EinvoiceMessage, type EinvoiceResult, type EinvoiceValidation, } from './report.cjs';
+export { htmlText } from './html-text.cjs';
+export { invoiceSkeleton } from './skeleton.cjs';
+/** Where the invoice sits in the render data. */
+export declare const INVOICE_DATA_KEY = "_invoice";
+/**
+ * The release of the specification the XML is written for, under each of its two names: ZUGFeRD 2.5
+ * and Factur-X 1.09 are one document. The sidecar pins the same release (its validator is what a
+ * file is held to); `codes.generated.ts` carries that release's code lists.
+ */
+export declare const EINVOICE_SPEC_VERSIONS: Record<EinvoiceFlavour, string>;
+/**
+ * An amount of a checked `Invoice` as the XML writes it and a reader expects it: `3760.40`. The
+ * invoice itself keeps the digits it was given (`3760.4`), which is one value all the same.
+ */
+export declare function invoiceAmountText(amount: string): string;
+export type EinvoiceXml = {
+    ok: true;
+    xml: string;
+    invoice: Invoice;
+} | {
+    ok: false;
+    problems: InvoiceProblem[];
+};
+/**
+ * The `_invoice` block of some render data as XML: checked, then written. A block that is absent is
+ * one finding, since a template that declares an e-invoice cannot render without one.
+ */
+export declare function einvoiceXml(data: unknown, options: {
+    profile: EinvoiceProfile;
+}): EinvoiceXml;

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

@@ -0,0 +1,45 @@
+/**
+ * `@formfeed/engine/einvoice` (spec 17): the `_invoice` block, the rules it is held to, the CII XML
+ * written from it and the display check. No template engine is imported here and nothing of Node,
+ * so the gateway Worker, the render-worker, the editor and the CLI all run the same code: what the
+ * API refuses, the editor has already said.
+ */
+import { type Invoice, type InvoiceProblem } from './check.js';
+import type { EinvoiceFlavour, EinvoiceProfile } from './schema.js';
+export { checkInvoice, type CheckOptions, type Identifier, type Invoice, type InvoiceAddress, type InvoiceAllowance, type InvoiceBreakdown, type InvoiceCheck, type InvoiceLine, type InvoiceParty, type InvoiceProblem, type InvoiceProblemCode, type InvoiceTax, } from './check.js';
+export { CII_GUIDELINES, EINVOICE_XML_NAME, invoiceToCii } from './cii.js';
+export { CODE_LIST_RELEASE } from './codes.generated.js';
+export { DISPLAY_TERMS, displayCheck, displayMissingText, shownAmounts, type DisplayCheck, type DisplayValue, } from './display.js';
+export { EINVOICE_FLAVOURS, EINVOICE_PROFILES, VAT_CATEGORIES, defaultEinvoiceOptions, einvoiceOptionsSchema, invoiceSchema, resolveEinvoiceOptions, type EinvoiceFlavour, type EinvoiceOptions, type EinvoiceOptionsInput, type EinvoiceProfile, type InvoiceInput, type ResolvedEinvoice, type VatCategory, } from './schema.js';
+export { invoicePathSegments, locateJsonPath, type JsonLocation, } from './locate.js';
+export { EINVOICE_FLAVOUR_NAMES, EINVOICE_MAX_MESSAGES, EINVOICE_PROFILE_NAMES, capMessages, einvoiceResult, invoiceLineOf, type EinvoiceDisplay, type EinvoiceMessage, type EinvoiceResult, type EinvoiceValidation, } from './report.js';
+export { htmlText } from './html-text.js';
+export { invoiceSkeleton } from './skeleton.js';
+/** Where the invoice sits in the render data. */
+export declare const INVOICE_DATA_KEY = "_invoice";
+/**
+ * The release of the specification the XML is written for, under each of its two names: ZUGFeRD 2.5
+ * and Factur-X 1.09 are one document. The sidecar pins the same release (its validator is what a
+ * file is held to); `codes.generated.ts` carries that release's code lists.
+ */
+export declare const EINVOICE_SPEC_VERSIONS: Record<EinvoiceFlavour, string>;
+/**
+ * An amount of a checked `Invoice` as the XML writes it and a reader expects it: `3760.40`. The
+ * invoice itself keeps the digits it was given (`3760.4`), which is one value all the same.
+ */
+export declare function invoiceAmountText(amount: string): string;
+export type EinvoiceXml = {
+    ok: true;
+    xml: string;
+    invoice: Invoice;
+} | {
+    ok: false;
+    problems: InvoiceProblem[];
+};
+/**
+ * The `_invoice` block of some render data as XML: checked, then written. A block that is absent is
+ * one finding, since a template that declares an e-invoice cannot render without one.
+ */
+export declare function einvoiceXml(data: unknown, options: {
+    profile: EinvoiceProfile;
+}): EinvoiceXml;

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

@@ -0,0 +1,21 @@
+import type { Position } from '../types.cjs';
+/**
+ * Where a finding sits in the JSON a data set is written as, so that the editor can mark the place
+ * and the CLI can print `data/default.json:38:5` instead of a path to count out by hand.
+ *
+ * `JSON.parse` keeps no positions, so the text is walked here. It only has to find its way through
+ * JSON that already parsed, not to judge it: anything unexpected ends the walk and the answer is
+ * what was reached until then.
+ */
+export interface JsonLocation extends Position {
+    /** How many segments of the path exist in the text; fewer than asked means the rest is missing. */
+    depth: number;
+}
+/** `lines[1].tax.rate` as the keys and indexes it names. */
+export declare function invoicePathSegments(path: string): Array<string | number>;
+/**
+ * The position of `path` in `text`: of the key (or the list item) the path ends on, or, when the
+ * text does not go that far, of the deepest part that is there. A field that is missing is thereby
+ * marked at the object it is missing from. `null` when the text has no value at all.
+ */
+export declare function locateJsonPath(text: string, path: ReadonlyArray<string | number>): JsonLocation | null;

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

@@ -0,0 +1,21 @@
+import type { Position } from '../types.js';
+/**
+ * Where a finding sits in the JSON a data set is written as, so that the editor can mark the place
+ * and the CLI can print `data/default.json:38:5` instead of a path to count out by hand.
+ *
+ * `JSON.parse` keeps no positions, so the text is walked here. It only has to find its way through
+ * JSON that already parsed, not to judge it: anything unexpected ends the walk and the answer is
+ * what was reached until then.
+ */
+export interface JsonLocation extends Position {
+    /** How many segments of the path exist in the text; fewer than asked means the rest is missing. */
+    depth: number;
+}
+/** `lines[1].tax.rate` as the keys and indexes it names. */
+export declare function invoicePathSegments(path: string): Array<string | number>;
+/**
+ * The position of `path` in `text`: of the key (or the list item) the path ends on, or, when the
+ * text does not go that far, of the deepest part that is there. A field that is missing is thereby
+ * marked at the object it is missing from. `null` when the text has no value at all.
+ */
+export declare function locateJsonPath(text: string, path: ReadonlyArray<string | number>): JsonLocation | null;

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

@@ -0,0 +1,59 @@
+import type { DisplayCheck } from './display.cjs';
+import type { EinvoiceFlavour, EinvoiceOptions, EinvoiceProfile } from './schema.cjs';
+/**
+ * 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/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;