beliq-cli 0.2.2 → 0.3.0

package/README.md

@@ -17,16 +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]
 ```
 
+`--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. `--json` prints the raw API result (a report object in batch mode) as the only thing on stdout, so it pipes cleanly.
+`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
@@ -41,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
@@ -67,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/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,15 +7,20 @@ 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.
@@ -29,6 +34,9 @@ Global options:
   --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
 
@@ -36,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

@@ -1,8 +1,8 @@
 <?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 a known-invalid example for the gated
-     live test and for the skill walkthrough. -->
+     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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beliq-cli",
-  "version": "0.2.2",
+  "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",
@@ -61,8 +61,8 @@
   },
   "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"