beliq-cli 0.2.1 → 0.3.0

package/README.md

@@ -17,14 +17,18 @@ Requires Node.js >= 20.15.
 ## Usage
 
 ```
-beliq validate <file|dir|-> [<file|dir> ...] [--format auto|cii|ubl] [--fail-on error|warning] [--json]
-beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile <p>] [--no-verify] [--output <file>] [--json]
-beliq parse    <file|->  [--format auto|cii|ubl] [--json]
-beliq convert  <file|->  --target-format cii|ubl|zugferd|facturx|xrechnung|peppol-bis [--source-format <f>] [--target-profile <p>] [--output <file>] [--json]
+beliq validate <file|dir|-> [<file|dir> ...] [--format auto|cii|ubl] [--fail-on error|warning] [--france-ctc] [--content-type <type>] [--json]
+beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile basicwl|en16931|extended|extended-ctc-fr] [--no-verify] [--seal] [--output <file>] [--json]
+beliq parse    <file|->  [--format auto|cii|ubl] [--content-type <type>] [--json]
+beliq convert  <file|->  --target-format cii|ubl|zugferd|facturx|xrechnung|peppol-bis [--source-format auto|cii|ubl|zugferd|facturx|xrechnung|peppol-bis] [--target-profile basicwl|en16931|extended|extended-ctc-fr] [--content-type <type>] [--output <file>] [--json]
 beliq me                 [--json]
 ```
 
-`validate` accepts an XML document or a ZUGFeRD/Factur-X PDF. A file argument of `-` reads from stdin. Pass several files, a shell glob, or a directory (its `.xml`/`.pdf` files, recursively) to validate a batch: you get a per-file verdict, a summary, and one exit code for the whole run. `--json` prints the raw API result (a report object in batch mode) as the only thing on stdout, so it pipes cleanly.
+`--facturx-profile` applies to `zugferd` and `facturx`; `extended-ctc-fr` is Factur-X only. `generate --seal` also returns the document's sha256 and its validation verdict, so you can prove which rules the document passed. `--content-type` sets the input's media type for `validate`, `parse` and `convert`; without it, input starting with `%PDF-` is sent as `application/pdf` and anything else as `application/xml`.
+
+`generate --pdf` returns a hybrid PDF/A-3 with the XML embedded for `zugferd` and `facturx`. `xrechnung` and `peppol-bis` have no hybrid form, so `--pdf` returns a visualization with no XML inside it, and their legal document stays the XML.
+
+`validate` accepts an XML document or a ZUGFeRD/Factur-X PDF. A file argument of `-` reads from stdin. Pass several files, a shell glob, or a directory (its `.xml`/`.pdf` files, recursively) to validate a batch: you get a per-file verdict, a summary, and one exit code for the whole run. A directory is a batch even when it holds one file, so its `--json` shape does not depend on how many invoices it contains. `--france-ctc` also applies the French CTC rules (BR-FR-CTC) to each document. `--json` prints the raw API result (a report object in batch mode) as the only thing on stdout, so it pipes cleanly.
 
 ```bash
 # Validate a file, human-readable
@@ -39,8 +43,10 @@ beliq validate ./invoices
 # Validate from a pipe, machine-readable, fail the shell on any warning too
 cat invoice.xml | beliq validate - --json --fail-on warning
 
-# Generate an XRechnung from a JSON invoice, write the XML to stdout
-beliq generate examples/invoice.json --standard xrechnung > invoice.xml
+# Generate an XRechnung from the example invoice, write the XML to stdout.
+# The example ships in the npm package; in a clone of this repository it is
+# examples/invoice.json.
+beliq generate "$(npm root -g)/beliq-cli/examples/invoice.json" --standard xrechnung > invoice.xml
 
 # Convert a CII document to a Peppol BIS UBL document
 beliq convert invoice.xml --target-format peppol-bis --output peppol.xml
@@ -65,11 +71,13 @@ The exit code is the contract that makes it useful in scripts and CI:
 | 0 | success, or a valid document |
 | 1 | document invalid (`validate`, per `--fail-on`) |
 | 2 | usage error (bad flag, missing argument, missing API key, PDF without `--output`) |
-| 3 | beliq API error (bad key, quota, engine, a rejected document) |
+| 3 | beliq API error (bad key, quota, engine, a rejected document), the API could not be reached (DNS, a refused connection, a timeout), or an unexpected error. Never a verdict on the document. |
 | 4 | I/O error (unreadable input, or an output path that already exists) |
 
 In batch mode (many files or a directory) the code covers the whole run: `0` if every file passes, `1` if a document fails `--fail-on`, `3` if any file could not be checked (unreadable, or the API errored on it).
 
+On an API error the message goes to stderr, followed by the failed rules when the API names them (`generate` refuses a document that fails its own validation with a 422 that lists them). With `--json`, stdout also gets the error as `{ "error": { "status", "code", "message", "details" } }`.
+
 ## In CI
 
 Validate every invoice a build produces and fail on a non-compliant one:

package/dist/args.js

@@ -1,8 +1,8 @@
 import { UsageError } from './errors.js';
 /** Flags that take no value. */
-const BOOLEAN_FLAGS = new Set(['json', 'pdf', 'no-verify', 'france-ctc', 'seal']);
+export const BOOLEAN_FLAGS = new Set(['json', 'pdf', 'no-verify', 'france-ctc', 'seal']);
 /** Flags that take a value (`--flag value` or `--flag=value`). */
-const VALUE_FLAGS = new Set([
+export const VALUE_FLAGS = new Set([
     'format',
     'target-format',
     'source-format',

package/dist/cli.js

@@ -4,6 +4,7 @@ import { resolveConfig } from './config.js';
 import { EXIT } from './exit.js';
 import { IoError, UsageError } from './errors.js';
 import { HELP, version } from './help.js';
+import { renderValidationHuman } from './format/validate.js';
 import { runValidate } from './commands/validate.js';
 import { runGenerate } from './commands/generate.js';
 import { runParse } from './commands/parse.js';
@@ -63,11 +64,36 @@ export async function main(argv, io, env = process.env) {
             return EXIT.IO;
         }
         if (err instanceof BeliqApiError) {
-            const code = err.code ? ` (${err.code})` : '';
-            io.stderr(`beliq: API error ${err.status}${code}: ${err.message}`);
+            reportApiError(err, args, io);
             return EXIT.API;
         }
-        io.stderr(`beliq: unexpected error: ${err.message}`);
-        return 1;
+        // Mostly a transport failure (DNS, a refused connection, TLS), which the SDK
+        // rethrows as fetch's own TypeError. None of these is a verdict on the
+        // document, and exit 1 is the "document invalid" code a CI gate reads.
+        io.stderr(`beliq: unexpected error: ${describeError(err)}`);
+        return EXIT.API;
     }
 }
+/**
+ * An API error on stderr, followed by the rules a rejected document failed when
+ * the API names them (a 422 from generate carries its validation result in
+ * `details`). With --json the error object goes to stdout as well, so a script
+ * reading stdout gets a payload on failure too.
+ */
+function reportApiError(err, args, io) {
+    const code = err.code ? ` (${err.code})` : '';
+    io.stderr(`beliq: API error ${err.status}${code}: ${err.message}`);
+    const result = err.details?.validationResult;
+    if (result && typeof result === 'object')
+        io.stderr(renderValidationHuman(result));
+    if (args.flags.json === true) {
+        const error = { status: err.status, code: err.code, message: err.message, details: err.details };
+        io.stdout(`${JSON.stringify({ error }, null, 2)}\n`);
+    }
+}
+/** The message plus its cause: fetch reports only "fetch failed" and keeps the reason in `cause`. */
+function describeError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : undefined;
+    return cause ? `${message} (${cause})` : message;
+}

package/dist/commands/convert.js

@@ -1,4 +1,4 @@
-import { LIVE_CONVERT_SOURCE_FORMATS, LIVE_CONVERT_TARGET_FORMATS, } from '@beliq/sdk';
+import { LIVE_CONVERT_SOURCE_FORMATS, LIVE_CONVERT_TARGET_FORMATS, LIVE_PROFILES, } from '@beliq/sdk';
 import { flagStr, oneOf, requirePositional } from '../args.js';
 import { UsageError } from '../errors.js';
 import { emitDocument } from './emit.js';
@@ -17,11 +17,15 @@ export async function runConvert(args, deps, io) {
         throw new UsageError(`--target-format is required (one of: ${LIVE_CONVERT_TARGET_FORMATS.join(', ')})`);
     }
     const sourceFormat = oneOf(flagStr(args, 'source-format'), LIVE_CONVERT_SOURCE_FORMATS, 'source-format');
+    // The flat list, not the per-standard one generate checks: the engine's
+    // convert route resolves a profile the same way for both hybrid targets, and
+    // the API ignores it for the others.
+    const targetProfile = oneOf(flagStr(args, 'target-profile'), LIVE_PROFILES, 'target-profile');
     const bytes = await io.readInput(file);
     const result = await deps.client.convert(bytes, {
         targetFormat: targetFormat,
         sourceFormat: sourceFormat,
-        targetProfile: flagStr(args, 'target-profile'),
+        targetProfile: targetProfile,
         contentType: flagStr(args, 'content-type'),
     });
     const kind = PDF_TARGETS.has(targetFormat) ? 'pdf' : 'xml';

package/dist/commands/generate.js

@@ -1,4 +1,4 @@
-import { LIVE_GENERATE_STANDARDS } from '@beliq/sdk';
+import { LIVE_GENERATE_STANDARDS, isProfileAllowedForStandard, profilesForStandard, } from '@beliq/sdk';
 import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
 import { UsageError } from '../errors.js';
 import { emitDocument } from './emit.js';
@@ -13,6 +13,15 @@ export async function runGenerate(args, deps, io) {
     if (!standard) {
         throw new UsageError(`--standard is required (one of: ${LIVE_GENERATE_STANDARDS.join(', ')})`);
     }
+    // The SDK drops --facturx-profile outside the Factur-X / ZUGFeRD family.
+    // Inside it the pair is pinned (extended-ctc-fr is Factur-X only) and the API
+    // answers a wrong one with 422, so fail as a usage error before the call.
+    const facturxProfile = flagStr(args, 'facturx-profile');
+    if (facturxProfile !== undefined &&
+        (standard === 'facturx' || standard === 'zugferd') &&
+        !isProfileAllowedForStandard(standard, facturxProfile)) {
+        throw new UsageError(`--facturx-profile for ${standard} must be one of: ${profilesForStandard(standard).join(', ')}`);
+    }
     const raw = await io.readInput(file);
     let invoice;
     try {
@@ -28,7 +37,11 @@ export async function runGenerate(args, deps, io) {
         standard,
         invoice,
         output,
-        facturxProfile: flagStr(args, 'facturx-profile'),
+        facturxProfile: facturxProfile,
+        // XRechnung and Peppol BIS have no hybrid PDF, and the API refuses PDF for
+        // them unless the request names a visual to render. Factur-X and ZUGFeRD
+        // render theirs either way, so this is inert for them.
+        template: output === 'pdf' ? 'standard' : undefined,
         verify: !flagBool(args, 'no-verify'),
         seal,
     });

package/dist/commands/validate.js

@@ -10,15 +10,19 @@ const FATAL_API_STATUSES = new Set([401, 403, 429]);
 /**
  * Validate one or many documents against beliq's authority-pinned rules.
  *
- * One input (a file or `-`) keeps the classic per-document output. Multiple
- * files, or a directory (its `.xml`/`.pdf` files, recursively), switch to a
- * batch: a per-file verdict, an aggregate summary, and a batch exit code (0 all
- * pass, 1 some document fails --fail-on, 3 some file could not be checked).
+ * One file (or `-`) named on its own keeps the classic per-document output.
+ * Multiple inputs, or a directory (its `.xml`/`.pdf` files, recursively), switch
+ * to a batch: a per-file verdict, an aggregate summary, and a batch exit code (0
+ * all pass, 1 some document fails --fail-on, 3 some file could not be checked).
+ * A directory stays a batch even when it holds one invoice, so the --json shape
+ * follows what was asked for rather than how many files were found.
  */
 export async function runValidate(args, deps, io) {
     const format = oneOf(flagStr(args, 'format'), LIVE_VALIDATE_FORMATS, 'format');
     const failOn = (oneOf(flagStr(args, 'fail-on'), FAIL_ON, 'fail-on') ?? 'error');
     const contentType = flagStr(args, 'content-type');
+    // Sent only when set: the API's own default decides otherwise.
+    const franceCtc = flagBool(args, 'france-ctc') ? true : undefined;
     const json = flagBool(args, 'json');
     if (args.positionals.length === 0) {
         throw new UsageError('missing file argument. Usage: beliq validate <file|dir|-> [<file|dir> ...]');
@@ -30,19 +34,26 @@ export async function runValidate(args, deps, io) {
     if (files.length > 1 && files.includes('-')) {
         throw new UsageError('cannot mix "-" (stdin) with other inputs');
     }
-    if (files.length === 1) {
-        const result = await deps.client.validate(await io.readInput(files[0]), { format, contentType });
+    // expandInputs returns a named file as given and a directory as the files
+    // inside it, so a single input that comes back unchanged was a file.
+    const single = args.positionals.length === 1 && files.length === 1 && files[0] === args.positionals[0];
+    if (single) {
+        const result = await deps.client.validate(await io.readInput(files[0]), { format, contentType, franceCtc });
         io.stdout(json ? `${JSON.stringify(result, null, 2)}\n` : `${renderValidationHuman(result)}\n`);
         return computeExitCode(result, failOn);
     }
-    return runBatch(files, { format, contentType, failOn, json }, deps, io);
+    return runBatch(files, { format, contentType, franceCtc, failOn, json }, deps, io);
 }
 async function runBatch(files, opts, deps, io) {
     const rows = [];
     for (const file of files) {
         try {
             const bytes = await io.readInput(file);
-            const result = await deps.client.validate(bytes, { format: opts.format, contentType: opts.contentType });
+            const result = await deps.client.validate(bytes, {
+                format: opts.format,
+                contentType: opts.contentType,
+                franceCtc: opts.franceCtc,
+            });
             rows.push({ file, result, fails: computeExitCode(result, opts.failOn) !== EXIT.OK });
         }
         catch (err) {

package/dist/config.js

@@ -1,6 +1,7 @@
 import { DEFAULT_BASE_URL } from '@beliq/sdk';
-import { flagStr } from './args.js';
+import { flagStr, oneOf } from './args.js';
 import { UsageError } from './errors.js';
+const AUTH_MODES = ['header', 'bearer'];
 /**
  * Resolve the typed config with precedence flag > env > default. Throws a
  * UsageError if no API key is available so the CLI reports a clean usage error
@@ -13,7 +14,9 @@ export function resolveConfig(args, env = process.env) {
         throw new UsageError('no API key. Set BELIQ_API_KEY or pass --api-key. Create a key in the beliq dashboard under API Keys.');
     }
     const baseUrl = (flagStr(args, 'base-url') ?? env.BELIQ_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    // An unknown mode is refused rather than read as `header`: a typo in
+    // `bearer` would otherwise send the key a way the caller did not ask for.
     const authRaw = (flagStr(args, 'auth') ?? env.BELIQ_AUTH ?? '').trim().toLowerCase();
-    const auth = authRaw === 'bearer' ? 'bearer' : 'header';
+    const auth = oneOf(authRaw || undefined, AUTH_MODES, 'auth (or BELIQ_AUTH)', 'header');
     return { apiKey, baseUrl, auth };
 }

package/dist/exit.js

@@ -5,7 +5,11 @@ export const EXIT = {
     INVALID: 1,
     /** A usage problem: bad flag, missing argument, missing API key, PDF without --output. */
     USAGE: 2,
-    /** The beliq API returned an error (bad key, quota, engine, a rejected document). */
+    /**
+     * The beliq API returned an error (bad key, quota, engine, a rejected
+     * document), could not be reached, or something unexpected failed. Never a
+     * verdict on the document.
+     */
     API: 3,
     /** A local I/O error: an unreadable input or an output path that already exists. */
     IO: 4,

package/dist/help.js

@@ -7,24 +7,36 @@ export function version() {
 export const HELP = `beliq: validate, generate, parse, and convert EU e-invoices
 
 Usage:
-  beliq validate <file|dir|-> [<file|dir> ...] [--format auto|cii|ubl] [--fail-on error|warning] [--json]
-  beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile <p>] [--no-verify] [--seal] [--output <file>] [--json]
-  beliq parse    <file|->  [--format auto|cii|ubl] [--json]
-  beliq convert  <file|->  --target-format cii|ubl|zugferd|facturx|xrechnung|peppol-bis [--source-format <f>] [--target-profile <p>] [--output <file>] [--json]
+  beliq validate <file|dir|-> [<file|dir> ...] [--format auto|cii|ubl] [--fail-on error|warning] [--france-ctc] [--content-type <type>] [--json]
+  beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile basicwl|en16931|extended|extended-ctc-fr] [--no-verify] [--seal] [--output <file>] [--json]
+  beliq parse    <file|->  [--format auto|cii|ubl] [--content-type <type>] [--json]
+  beliq convert  <file|->  --target-format cii|ubl|zugferd|facturx|xrechnung|peppol-bis [--source-format auto|cii|ubl|zugferd|facturx|xrechnung|peppol-bis] [--target-profile basicwl|en16931|extended|extended-ctc-fr] [--content-type <type>] [--output <file>] [--json]
   beliq me                 [--json]
 
 validate accepts an XML document or a ZUGFeRD/Factur-X PDF. Pass several files,
 a shell glob, or a directory (its .xml/.pdf files, recursively) to validate a
-batch: a per-file verdict, a summary, and one exit code for the whole run.
+batch: a per-file verdict, a summary, and one exit code for the whole run. A
+directory is a batch even when it holds one file. validate --france-ctc also
+applies the French CTC rules (BR-FR-CTC).
+
+generate --facturx-profile applies to zugferd and facturx; extended-ctc-fr is
+Factur-X only.
 
 generate --seal also returns the document sha256 and validation verdict, so you
 can prove which rules the document passed; hashing the output reproduces it.
 
+--pdf gives a hybrid PDF/A-3 with the XML embedded for zugferd and facturx.
+xrechnung and peppol-bis have no hybrid form, so --pdf returns a visualization
+with no XML inside it, and their legal document stays the XML.
+
 Global options:
   --api-key <key>   beliq API key (default: BELIQ_API_KEY)
   --base-url <url>  API base URL (default: BELIQ_BASE_URL, else https://api.beliq.eu)
   --auth <mode>     header (default, X-API-Key) or bearer
   --json            machine-readable JSON on stdout
+  --content-type <type>
+                    the input's media type (default: application/pdf when the
+                    bytes start with %PDF-, else application/xml)
   -h, --help        show this help
   -v, --version     show the version
 
@@ -32,7 +44,7 @@ Exit codes:
   0  success, or a valid document
   1  document invalid (validate, per --fail-on)
   2  usage error
-  3  beliq API error
+  3  beliq API error, the API could not be reached, or an unexpected error
   4  I/O error
 
 In batch mode the code covers the whole run: 0 if every file passes, 1 if a

package/dist/index.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 import { main } from './cli.js';
+import { EXIT } from './exit.js';
 import { nodeIO } from './io.js';
 main(process.argv.slice(2), nodeIO()).then((code) => {
     process.exitCode = code;
 }, (err) => {
     process.stderr.write(`beliq: fatal: ${err.message}\n`);
-    process.exitCode = 1;
+    process.exitCode = EXIT.API;
 });

package/examples/invalid-xrechnung.xml

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- A minimal CII (UN/CEFACT Cross Industry Invoice) carrying the XRechnung
+     guideline id but missing the Buyer reference (BT-10), which XRechnung
+     requires (rule BR-DE-15). Used as the known-invalid example in the gated
+     live test. -->
+<rsm:CrossIndustryInvoice
+    xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
+    xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
+    xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">
+  <rsm:ExchangedDocumentContext>
+    <ram:GuidelineSpecifiedDocumentContextParameter>
+      <ram:ID>urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0</ram:ID>
+    </ram:GuidelineSpecifiedDocumentContextParameter>
+  </rsm:ExchangedDocumentContext>
+  <rsm:ExchangedDocument>
+    <ram:ID>INV-2026-001</ram:ID>
+    <ram:TypeCode>380</ram:TypeCode>
+    <ram:IssueDateTime>
+      <udt:DateTimeString format="102">20260115</udt:DateTimeString>
+    </ram:IssueDateTime>
+  </rsm:ExchangedDocument>
+  <rsm:SupplyChainTradeTransaction>
+    <ram:IncludedSupplyChainTradeLineItem>
+      <ram:AssociatedDocumentLineDocument>
+        <ram:LineID>1</ram:LineID>
+      </ram:AssociatedDocumentLineDocument>
+      <ram:SpecifiedTradeProduct>
+        <ram:Name>Consulting</ram:Name>
+      </ram:SpecifiedTradeProduct>
+      <ram:SpecifiedLineTradeAgreement>
+        <ram:NetPriceProductTradePrice>
+          <ram:ChargeAmount>100.00</ram:ChargeAmount>
+        </ram:NetPriceProductTradePrice>
+      </ram:SpecifiedLineTradeAgreement>
+      <ram:SpecifiedLineTradeDelivery>
+        <ram:BilledQuantity unitCode="HUR">10</ram:BilledQuantity>
+      </ram:SpecifiedLineTradeDelivery>
+      <ram:SpecifiedLineTradeSettlement>
+        <ram:ApplicableTradeTax>
+          <ram:TypeCode>VAT</ram:TypeCode>
+          <ram:CategoryCode>S</ram:CategoryCode>
+          <ram:RateApplicablePercent>19.00</ram:RateApplicablePercent>
+        </ram:ApplicableTradeTax>
+        <ram:SpecifiedTradeSettlementLineMonetarySummation>
+          <ram:LineTotalAmount>1000.00</ram:LineTotalAmount>
+        </ram:SpecifiedTradeSettlementLineMonetarySummation>
+      </ram:SpecifiedLineTradeSettlement>
+    </ram:IncludedSupplyChainTradeLineItem>
+    <ram:ApplicableHeaderTradeAgreement>
+      <ram:SellerTradeParty>
+        <ram:Name>Seller GmbH</ram:Name>
+        <ram:PostalTradeAddress>
+          <ram:PostcodeCode>10115</ram:PostcodeCode>
+          <ram:CityName>Berlin</ram:CityName>
+          <ram:CountryID>DE</ram:CountryID>
+        </ram:PostalTradeAddress>
+        <ram:SpecifiedTaxRegistration>
+          <ram:ID schemeID="VA">DE123456789</ram:ID>
+        </ram:SpecifiedTaxRegistration>
+      </ram:SellerTradeParty>
+      <ram:BuyerTradeParty>
+        <ram:Name>Buyer GmbH</ram:Name>
+        <ram:PostalTradeAddress>
+          <ram:PostcodeCode>80331</ram:PostcodeCode>
+          <ram:CityName>Munich</ram:CityName>
+          <ram:CountryID>DE</ram:CountryID>
+        </ram:PostalTradeAddress>
+      </ram:BuyerTradeParty>
+    </ram:ApplicableHeaderTradeAgreement>
+    <ram:ApplicableHeaderTradeDelivery />
+    <ram:ApplicableHeaderTradeSettlement>
+      <ram:InvoiceCurrencyCode>EUR</ram:InvoiceCurrencyCode>
+      <ram:ApplicableTradeTax>
+        <ram:CalculatedAmount>190.00</ram:CalculatedAmount>
+        <ram:TypeCode>VAT</ram:TypeCode>
+        <ram:BasisAmount>1000.00</ram:BasisAmount>
+        <ram:CategoryCode>S</ram:CategoryCode>
+        <ram:RateApplicablePercent>19.00</ram:RateApplicablePercent>
+      </ram:ApplicableTradeTax>
+      <ram:SpecifiedTradePaymentTerms>
+        <ram:DueDateDateTime>
+          <udt:DateTimeString format="102">20260214</udt:DateTimeString>
+        </ram:DueDateDateTime>
+      </ram:SpecifiedTradePaymentTerms>
+      <ram:SpecifiedTradeSettlementHeaderMonetarySummation>
+        <ram:LineTotalAmount>1000.00</ram:LineTotalAmount>
+        <ram:TaxBasisTotalAmount>1000.00</ram:TaxBasisTotalAmount>
+        <ram:TaxTotalAmount currencyID="EUR">190.00</ram:TaxTotalAmount>
+        <ram:GrandTotalAmount>1190.00</ram:GrandTotalAmount>
+        <ram:DuePayableAmount>1190.00</ram:DuePayableAmount>
+      </ram:SpecifiedTradeSettlementHeaderMonetarySummation>
+    </ram:ApplicableHeaderTradeSettlement>
+  </rsm:SupplyChainTradeTransaction>
+</rsm:CrossIndustryInvoice>

package/examples/invoice.json

@@ -0,0 +1,64 @@
+{
+  "number": "INV-2026-001",
+  "issueDate": "2026-01-15",
+  "currencyCode": "EUR",
+  "buyerReference": "04011000-12345-06",
+  "seller": {
+    "name": "Seller GmbH",
+    "vatId": "DE123456789",
+    "contactName": "Anna Muster",
+    "email": "billing@seller.example",
+    "phone": "+49 30 1234567",
+    "address": {
+      "street": "Hauptstr. 1",
+      "city": "Berlin",
+      "postalCode": "10115",
+      "countryCode": "DE"
+    },
+    "peppol": {
+      "schemeId": "9930",
+      "id": "DE123456789"
+    }
+  },
+  "buyer": {
+    "name": "Buyer GmbH",
+    "email": "ap@buyer.example",
+    "address": {
+      "street": "Marktweg 2",
+      "city": "Munich",
+      "postalCode": "80331",
+      "countryCode": "DE"
+    },
+    "vatId": "DE987654321",
+    "peppol": {
+      "schemeId": "9930",
+      "id": "DE987654321"
+    }
+  },
+  "lines": [
+    {
+      "description": "Consulting",
+      "quantity": 10,
+      "unitCode": "HUR",
+      "unitPrice": 100,
+      "lineTotal": 1000,
+      "vatRate": 19,
+      "vatCategoryCode": "S"
+    }
+  ],
+  "taxSummary": [
+    {
+      "vatCategoryCode": "S",
+      "vatRate": 19,
+      "taxableAmount": 1000,
+      "taxAmount": 190
+    }
+  ],
+  "paymentMeans": {
+    "typeCode": "58",
+    "iban": "DE89370400440532013000"
+  },
+  "totalNetAmount": 1000,
+  "totalTaxAmount": 190,
+  "totalGrossAmount": 1190
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beliq-cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "beliq CLI: validate, generate, parse, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules, from the terminal or CI.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,8 @@
     "beliq": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "examples"
   ],
   "publishConfig": {
     "provenance": true
@@ -56,12 +57,12 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@beliq/sdk": "^0.3.0"
+    "@beliq/sdk": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
     "eslint": "^8.57.0",
     "typescript": "^5.5.4",
     "vitest": "^4.0.0"