beliq-cli 0.1.0 → 0.2.0

package/README.md

@@ -17,19 +17,25 @@ Requires Node.js >= 20.15.
 ## Usage
 
 ```
-beliq validate <file|->  [--format auto|cii|ubl] [--fail-on error|warning] [--content-type <mime>] [--json]
+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 me                 [--json]
 ```
 
-A file argument of `-` reads from stdin. `--json` prints the raw API result 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. `--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
 beliq validate invoice.xml
 
+# Validate a hybrid ZUGFeRD/Factur-X PDF (the embedded XML is checked)
+beliq validate invoice.pdf
+
+# Validate a whole folder of invoices (its .xml and .pdf files, recursively)
+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
 
@@ -62,17 +68,19 @@ The exit code is the contract that makes it useful in scripts and CI:
 | 3 | beliq API error (bad key, quota, engine, a rejected 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).
+
 ## In CI
 
 Validate every invoice a build produces and fail on a non-compliant one:
 
 ```yaml
-- run: npx beliq-cli validate "dist/invoices/*.xml" --fail-on error
+- run: npx beliq-cli validate dist/invoices --fail-on error
   env:
     BELIQ_API_KEY: ${{ secrets.BELIQ_API_KEY }}
 ```
 
-For a first-class GitHub Action with a per-file step summary, see `beliq-eu/beliq-validate-action`.
+`beliq validate` takes a directory, so this validates every `.xml`/`.pdf` invoice under `dist/invoices` in one run and fails the step if any is non-compliant. For a per-file step summary and job outputs on GitHub, use the Action `beliq-eu/beliq-validate-action`.
 
 ## Development
 

package/dist/args.js

@@ -1,6 +1,6 @@
 import { UsageError } from './errors.js';
 /** Flags that take no value. */
-const BOOLEAN_FLAGS = new Set(['json', 'pdf', 'no-verify', 'france-ctc']);
+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([
     'format',

package/dist/commands/generate.js

@@ -23,26 +23,36 @@ export async function runGenerate(args, deps, io) {
         throw new UsageError(`${what} is not valid JSON; generate takes an EN 16931 invoice as JSON`);
     }
     const output = flagBool(args, 'pdf') ? 'pdf' : 'xml';
+    const seal = flagBool(args, 'seal');
     const result = await deps.client.generate({
         standard,
         invoice,
         output,
         facturxProfile: flagStr(args, 'facturx-profile'),
         verify: !flagBool(args, 'no-verify'),
+        seal,
     });
     const checked = result.meta.schematronVersion
         ? `, checked against Schematron ${result.meta.schematronVersion}`
         : '';
-    return emitDocument(io, args, {
-        kind: output,
-        bytes: result.bytes,
-        meta: {
-            output,
-            contentType: result.contentType,
-            schematronVersion: result.meta.schematronVersion,
-            pdfKind: result.meta.pdfKind,
-            outputEnvelope: result.meta.outputEnvelope,
-        },
-        summary: `Generated a ${standard} ${output} document${checked}.`,
-    });
+    const sandbox = result.meta.livemode === false ? ' (sandbox)' : '';
+    const meta = {
+        output,
+        contentType: result.contentType,
+        schematronVersion: result.meta.schematronVersion,
+        pdfKind: result.meta.pdfKind,
+        outputEnvelope: result.meta.outputEnvelope,
+        livemode: result.meta.livemode,
+    };
+    let summary = `Generated a ${standard} ${output} document${checked}${sandbox}.`;
+    if (seal) {
+        meta.sha256 = result.sha256;
+        meta.rulesetSha256 = result.meta.rulesetSha256;
+        meta.validationResult = result.validationResult;
+        const verdict = result.validationResult
+            ? ` Validation ${result.validationResult.valid ? 'passed' : 'failed'}.`
+            : '';
+        summary += ` sha256 ${result.sha256}.${verdict}`;
+    }
+    return emitDocument(io, args, { kind: output, bytes: result.bytes, meta, summary });
 }

package/dist/commands/validate.js

@@ -1,25 +1,79 @@
-import { LIVE_VALIDATE_FORMATS } from '@beliq/sdk';
-import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
-import { computeExitCode } from '../exit.js';
-import { renderValidationHuman } from '../format/validate.js';
+import { LIVE_VALIDATE_FORMATS, BeliqApiError } from '@beliq/sdk';
+import { flagBool, flagStr, oneOf } from '../args.js';
+import { EXIT, computeExitCode } from '../exit.js';
+import { UsageError } from '../errors.js';
+import { renderValidationHuman, renderBatchHuman } from '../format/validate.js';
 const FAIL_ON = ['error', 'warning'];
+// API statuses that mean the whole batch is doomed (bad key, forbidden, or
+// rate-limited), not one bad document. Fail fast rather than retry per file.
+const FATAL_API_STATUSES = new Set([401, 403, 429]);
 /**
- * Validate one document against beliq's authority-pinned rules. Prints the
- * verdict (human table or, with --json, the raw ValidationResult) and returns
- * the CI exit code: 0 if it passes the --fail-on threshold, 1 if it fails.
+ * 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).
  */
 export async function runValidate(args, deps, io) {
-    const file = requirePositional(args, 'beliq validate <file|->');
     const format = oneOf(flagStr(args, 'format'), LIVE_VALIDATE_FORMATS, 'format');
     const failOn = (oneOf(flagStr(args, 'fail-on'), FAIL_ON, 'fail-on') ?? 'error');
-    const bytes = await io.readInput(file);
-    const result = await deps.client.validate(bytes, {
-        format: format,
-        contentType: flagStr(args, 'content-type'),
-    });
-    if (flagBool(args, 'json'))
-        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
-    else
-        io.stdout(`${renderValidationHuman(result)}\n`);
-    return computeExitCode(result, failOn);
+    const contentType = flagStr(args, 'content-type');
+    const json = flagBool(args, 'json');
+    if (args.positionals.length === 0) {
+        throw new UsageError('missing file argument. Usage: beliq validate <file|dir|-> [<file|dir> ...]');
+    }
+    const files = await io.expandInputs(args.positionals);
+    if (files.length === 0) {
+        throw new UsageError(`no .xml or .pdf files found in: ${args.positionals.join(', ')}`);
+    }
+    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 });
+        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);
+}
+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 });
+            rows.push({ file, result, fails: computeExitCode(result, opts.failOn) !== EXIT.OK });
+        }
+        catch (err) {
+            if (err instanceof BeliqApiError && FATAL_API_STATUSES.has(err.status))
+                throw err;
+            rows.push({ file, error: errorMessage(err) });
+        }
+    }
+    io.stdout(opts.json ? `${JSON.stringify(batchReport(rows), null, 2)}\n` : `${renderBatchHuman(rows)}\n`);
+    if (rows.some((r) => 'error' in r))
+        return EXIT.API;
+    if (rows.some((r) => 'result' in r && r.fails))
+        return EXIT.INVALID;
+    return EXIT.OK;
+}
+function errorMessage(err) {
+    if (err instanceof BeliqApiError) {
+        const code = err.code ? ` (${err.code})` : '';
+        return `API error ${err.status}${code}: ${err.message}`;
+    }
+    return err.message;
+}
+function batchReport(rows) {
+    const results = rows.map((r) => 'error' in r
+        ? { file: r.file, status: 'error', message: r.error }
+        : { file: r.file, status: r.fails ? 'fail' : 'pass', ...r.result });
+    return {
+        total: rows.length,
+        passed: rows.filter((r) => 'result' in r && !r.fails).length,
+        failed: rows.filter((r) => 'result' in r && r.fails).length,
+        errored: rows.filter((r) => 'error' in r).length,
+        results,
+    };
 }

package/dist/format/validate.js

@@ -31,3 +31,24 @@ export function renderValidationHuman(result) {
     const rows = issues.map((i) => [i.severity, i.ruleId, i.location || '-', i.message]);
     return `${head}\n${counts}\n\n${renderTable(['SEVERITY', 'RULE', 'LOCATION', 'MESSAGE'], rows)}`;
 }
+/**
+ * A batch verdict: a per-file table (PASS / FAIL / ERROR with error and warning
+ * counts) and a one-line summary. The exit code, not this text, is the CI
+ * contract; this is the human view.
+ */
+export function renderBatchHuman(rows) {
+    const cells = rows.map((r) => 'error' in r
+        ? ['ERROR', '-', '-', `${r.file}  (${r.error})`]
+        : [
+            r.fails ? 'FAIL' : 'PASS',
+            String((r.result.errors ?? []).length),
+            String((r.result.warnings ?? []).length),
+            r.file,
+        ]);
+    const table = renderTable(['STATUS', 'ERR', 'WARN', 'FILE'], cells);
+    const passed = rows.filter((r) => 'result' in r && !r.fails).length;
+    const failed = rows.filter((r) => 'result' in r && r.fails).length;
+    const errored = rows.filter((r) => 'error' in r).length;
+    const summary = `${plural(rows.length, 'file')}: ${passed} passed, ${failed} failed, ${errored} errored`;
+    return `${table}\n\n${summary}`;
+}

package/dist/help.js

@@ -7,12 +7,19 @@ export function version() {
 export const HELP = `beliq: validate, generate, parse, and convert EU e-invoices
 
 Usage:
-  beliq validate <file|->  [--format auto|cii|ubl] [--fail-on error|warning] [--content-type <mime>] [--json]
-  beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile <p>] [--no-verify] [--output <file>] [--json]
+  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 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.
+
+generate --seal also returns the document sha256 and validation verdict, so you
+can prove which rules the document passed; hashing the output reproduces it.
+
 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)
@@ -28,6 +35,9 @@ Exit codes:
   3  beliq API error
   4  I/O error
 
+In batch mode 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.
+
 A file argument of "-" reads from stdin. Set BELIQ_API_KEY (or pass --api-key)
 with a key from the beliq dashboard; the free tier is enough to evaluate.
 `;

package/dist/io.js

@@ -1,4 +1,5 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile, stat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
 import { IoError } from './errors.js';
 async function readStdin() {
     const chunks = [];
@@ -34,5 +35,46 @@ export function nodeIO() {
                 throw new IoError(`could not write ${path}: ${err.message}`);
             }
         },
+        async expandInputs(paths) {
+            const out = [];
+            const seen = new Set();
+            const add = (p) => {
+                if (!seen.has(p)) {
+                    seen.add(p);
+                    out.push(p);
+                }
+            };
+            for (const p of paths) {
+                if (p === '-') {
+                    add('-');
+                    continue;
+                }
+                let info;
+                try {
+                    info = await stat(p);
+                }
+                catch (err) {
+                    throw new IoError(`could not read ${p}: ${err.message}`);
+                }
+                if (!info.isDirectory()) {
+                    add(p);
+                    continue;
+                }
+                let entries;
+                try {
+                    entries = await readdir(p, { recursive: true, withFileTypes: true });
+                }
+                catch (err) {
+                    throw new IoError(`could not read directory ${p}: ${err.message}`);
+                }
+                const found = entries
+                    .filter((e) => e.isFile() && /\.(xml|pdf)$/i.test(e.name))
+                    .map((e) => join(e.parentPath, e.name))
+                    .sort();
+                for (const f of found)
+                    add(f);
+            }
+            return out;
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beliq-cli",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -56,7 +56,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@beliq/sdk": "^0.1.1"
+    "@beliq/sdk": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",