Skip to main content
Introducing packages.sweber.dev
Documentation menuAPI

API

All exports of @sweberdev/summand, @sweberdev/summand/xpath, @sweberdev/summand/rules-check, @sweberdev/summand/batch and @sweberdev/summand/cli, with their stability.

Every export is documented with TSDoc in the package, so your editor shows the same text. A test checks that this page lists exactly the exports of the package.

Stability

Exports are either stable or advanced. Stable exports follow SemVer: a breaking change needs a new major version. Advanced exports are marked @beta in TSDoc and in the tables below: they expose internals (the compiled rule and schema formats, the XML node tree, the XPath engine) and may change in a minor release, with a note in the changelog. Deprecated exports keep working until the next major version. The details are in the stability policy.

@sweberdev/summand

Functions and constants

ExportDescription
validateInvoice(input, options?)Validates XML (string or bytes) or a ZUGFeRD / Factur-X PDF. Synchronous, never throws for bad input. Returns a ValidationResult. See Validating invoices.
ruleSetsFor(detection, options?)The rule sets "auto" would apply
detect(doc)Syntax and profile of a parsed document, or "not-an-invoice" / "zugferd-1"
profileFor(specificationId)Profile for a BT-24 value
summarize(doc, syntax)InvoiceSummary of a parsed invoice
decodeXml(bytes)Decodes XML bytes by BOM or XML declaration
extractInvoiceXml(bytes){ xml, name, info } of the invoice embedded in a PDF, or undefined. Throws PdfError for unreadable PDFs.
readPdf(bytes)Embedded files and XMP information of a PDF. Throws PdfError.
isPdf(bytes)Whether bytes are a PDF
PdfErrorError class of readPdf and extractInvoiceXml
isValidLeitwegId(id), parseLeitwegId(id), leitwegCheckDigits(coarse, fine?)Leitweg-ID helpers
RULE_SETS, ruleSetInfo(id?)Default version of each bundled rule set: metadata (version, release, publisher, source, licence, rule count). ruleSetInfo(id, version) returns one bundled version (or undefined), ruleSetInfo({ versions: "all" }) lists every bundled version. See Rule sets and versions.
validateSchema(doc, schema, { lang? })Validates a parsed document against "ubl-2.1", "cii-d16b" or a compiled SchemaModel; lang: "de" for German messages. Returns SchemaFinding[].
SCHEMASBundled XML Schemas (metadata)

Types

ExportDescription
ValidationResult, ValidationMessage, ValidateOptions, Severity, InvoiceInputInput, options and result of validateInvoice
Profile, ProfileId, Syntax, Detection, DetectionErrorResult of detect and profileFor
InvoiceSummaryKey facts of an invoice
PdfInfo, EmbeddedFileResult of readPdf
LeitwegIdResult of parseLeitwegId
RuleSetId, RuleSetInfo, RuleSetInfoOptionsBundled rule sets and the options of ruleSetInfo
RuleSetFamily, RuleSetSelectorWhat the ruleSets option accepts: "en16931", "xrechnung", a syntax-specific id, each optionally with @version
SchemaId, SchemaInfo, SchemaFinding, SchemaFindingKind, ValidateSchemaOptionsXML Schema validation

Deprecated

Nothing is deprecated in 2.0.0. What 2.0.0 removed is listed in Migrating to 2.0.

Advanced (@beta)

For custom Schematron rules and your own tooling on the parsed XML. These may change in a minor release.

ExportDescription
compileSchematron(source, { id, includes? })Compiles a Schematron schema to a JSON rule set
runSchematron(set, doc, options?)Runs a rule set against a parsed document
ruleSet(id, version?)The compiled rules of a bundled rule set (default version unless version is given)
parseXml(text), stringValue(node), nodePath(node), XmlErrorThe XML parser and helpers for its node tree
CompiledRuleSet, RunOptions, SchematronFinding, FlagTypes of the Schematron engine
SchemaModelCompiled XML Schema
XNodeNode of a parsed XML document

@sweberdev/summand/xpath

The XPath 2.0 engine for Schematron. Everything here is advanced (@beta).

ExportDescription
select(expression, node, namespaces?, variables?)Evaluates an XPath 2.0 expression
parseXPath(expression, namespaces), evaluate(ast, env)Lower-level parse and evaluate
builtinFunctions, xpathRegex(pattern, flags)Function library and XSD regex translation
atomize(sequence), stringOf(item), ebv(sequence), isNode(item)Value helpers
Decimal, Untyped, XDate, XPathError, XPathSyntaxErrorValues and errors
Ast, Atomic, Env, Item, Sequence, XPathFunctionTypes

@sweberdev/summand/rules-check

ExportDescription
checkRuleSets({ fetch?, timeoutMs?, token? })Asks the public GitHub release lists whether newer releases of the bundled rule sets exist. Resolves to one RuleSetCheck (id, version, status, latest?, reason?) per rule set and never throws for network errors.
RuleSetCheck, RuleSetCheckStatus, RuleSetCheckOptions, FetchLikeTypes

Not part of the main entry point, so browser bundles do not include it.

@sweberdev/summand/batch

Node.js only (worker threads and the file system). Browsers call validateInvoice per file, see Validating many invoices.

ExportDescription
validateMany(inputs, options?)Validates many invoices with a bounded worker pool. Returns a BatchRun: an async iterable of results in input order, plus toArray(). Never throws per input. Options: all ValidateOptions, concurrency (default min(4, cores)), signal.
BatchInput, BatchResult, BatchError, BatchRun, ValidateManyOptionsTypes

@sweberdev/summand/cli

ExportDescription
runCli(argv, io?, { fetch? })Runs the CLI and resolves to the exit code. fetch is only used by rules --check. See CLI and the exit codes.
CliIoThe { out, err } functions runCli writes to

Command line

ItemDescription
summand validate <files...>Options --json, --rule-sets <list>, --strict-extended, --no-schema, --no-leitweg, --warnings-as-errors, --quiet, --lang <en|de>
summand extract <file.pdf>Option --out <file.xml> (-o)
summand leitweg <id>
summand rulesOptions --json, --check, --fail-on-outdated
summand --versionPrints the version
Exit codes0, 1, 2 and 3, see Error codes