beliq-cli 0.2.2 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # beliq-cli
 
-Validate, generate, parse, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) from the terminal or CI, against beliq's authority-pinned, drift-checked rules.
+Validate, generate, parse, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) from the terminal or CI, through the beliq API. Every verdict states how deep its check went.
 
-The headline use is **validating e-invoices in CI**: point it at your invoice files, and a non-compliant document fails the build.
+The headline use is **validating e-invoices in CI**: point it at your invoice files, and an invalid document fails the build.
 
 ## Install
 
@@ -17,16 +17,38 @@ 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|fatturapa|facturae|eslog|ksef [--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.
+
+`convert` returns XML for every target, `facturx` and `zugferd` included: the API does not wrap an XML source into a hybrid PDF. A PDF comes back only when a hybrid PDF source already is the target, and it needs `--output`. A successful convert means the API validated the converted XML before returning it. For a `facturx` or `zugferd` target at profile `en16931` that validation is the one for plain EN 16931 CII: no Factur-X profile schema is checked. It prints no verdict and no check depth. When the engine recorded source elements with no target equivalent, the summary gives their count; a loss the engine does not detect is not counted.
+
+`parse` prints a one-line summary and, below it, each warning the API sent about what the document holds and the parsed invoice does not.
+
+## Reading a verdict
+
+```
+$ beliq validate invoice.xml
+VALID  fatturapa (profile italy-fatturapa-ordinaria-fpr12)  Schema-checked
+0 errors, 0 warnings
+```
+
+- `VALID` and `INVALID` are the API's `valid`. `valid` means the document passed the rule packs and schemas beliq runs for its format, in the versions the result names. It does not mean every recipient, validation tool or tax authority accepts it.
+- The third field is the check depth, printed as the API sends it in `verificationBadgeLabel`. [How verification works](https://docs.beliq.eu/compliance/how-verification-works/) explains each depth. Where the API sends no label, the CLI prints `check depth not stated` and names no depth.
+- For a PDF, a line says which embedded XML the verdict is about. The PDF itself is not checked.
+- When the result carries `franceCtcBlockingRuleIds`, the CLI prints the API's message for them, with the rule ids, and fails the file with exit code 1 under every `--fail-on`, also where the verdict is `VALID`. The API reports those ids beside `valid` and does not fold them into it.
+- The batch table has the same depth in its `DEPTH` column. `--json` carries every field of the API result.
+
+`generate` names the same depth in its summary, and `not validated` with `--no-verify`. The verdict is about the invoice XML, so for `--pdf` the summary says so and names the kind of PDF.
 
 ```bash
 # Validate a file, human-readable
@@ -41,8 +63,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,16 +89,18 @@ The exit code is the contract that makes it useful in scripts and CI:
 | Code | Meaning |
 |---|---|
 | 0 | success, or a valid document |
-| 1 | document invalid (`validate`, per `--fail-on`) |
+| 1 | document invalid (`validate`, per `--fail-on`), or a result that carries `franceCtcBlockingRuleIds` |
 | 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).
+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` or carries `franceCtcBlockingRuleIds`, `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` and `convert` refuse a document that fails the API's 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:
+Validate every invoice a build produces and fail on an invalid one:
 
 ```yaml
 - run: npx beliq-cli validate dist/invoices --fail-on error
@@ -82,13 +108,15 @@ Validate every invoice a build produces and fail on a non-compliant one:
     BELIQ_API_KEY: ${{ secrets.BELIQ_API_KEY }}
 ```
 
-`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`.
+`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 invalid. For a per-file step summary and job outputs on GitHub, use the Action `beliq-eu/beliq-validate-action`.
 
 ## Development
 
 ```bash
 npm install
 npm run build
+npm run typecheck     # src and tests
+npm run lint          # ESLint with type information, whole repository
 npm test              # unit tests, no network
 npm run scrub:check   # no em-dash
 BELIQ_API_KEY=... npm run test:integration   # live smoke against the real API

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,37 @@ 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 or convert carries the validation
+ * result of the document it refused 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,14 +1,18 @@
-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 { sniffContentType } from '@beliq/sdk/helpers';
 import { flagStr, oneOf, requirePositional } from '../args.js';
 import { UsageError } from '../errors.js';
 import { emitDocument } from './emit.js';
-/** Convert targets that produce a hybrid PDF rather than an XML document. */
-const PDF_TARGETS = new Set(['facturx', 'zugferd']);
+/** The targets for which the API can hand a hybrid PDF source back as a PDF. */
+const HYBRID_TARGETS = new Set(['facturx', 'zugferd']);
 /**
- * Convert a document from one EN 16931 format to another. An XML target is
- * printed to stdout (or --output); a PDF target (facturx / zugferd) must go to
- * --output. Elements the conversion could not carry across are surfaced so a
- * lossy conversion is visible.
+ * Convert a document from one EN 16931 format to another. The API returns XML
+ * for every target, facturx and zugferd included: it does not wrap an XML
+ * source into a hybrid PDF. A PDF comes back only when a hybrid PDF source
+ * already is the target, and a PDF must go to --output. A 200 means the API
+ * validated the converted XML before returning it; it carries no verdict, so
+ * no check depth is printed. The count of lost elements is what the engine
+ * recorded, and a loss it does not detect is not in it.
  */
 export async function runConvert(args, deps, io) {
     const file = requirePositional(args, 'beliq convert <file|-> --target-format <format>');
@@ -17,19 +21,30 @@ 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);
+    if (sniffContentType(bytes) === 'application/pdf' && HYBRID_TARGETS.has(targetFormat) && !flagStr(args, 'output')) {
+        throw new UsageError(`a PDF source converted to ${targetFormat} can come back as a PDF and needs --output <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';
+    const kind = result.contentType.includes('pdf') ? 'pdf' : 'xml';
     const from = result.meta.sourceFormat ? `${result.meta.sourceFormat} ` : '';
     const to = result.meta.targetFormat ?? targetFormat;
     const lost = result.meta.lostElementsCount && result.meta.lostElementsCount > 0
-        ? ` ${result.meta.lostElementsCount} element(s) could not be carried across.`
+        ? ` The engine recorded ${result.meta.lostElementsCount} source element(s) with no target equivalent.`
         : '';
+    const sandbox = result.meta.livemode === false ? ' (sandbox)' : '';
+    const checked = kind === 'pdf'
+        ? ' The API validated the embedded XML before returning it; the PDF around it was not checked.'
+        : ' The API validated the converted XML before returning it.';
     return emitDocument(io, args, {
         kind,
         bytes: result.bytes,
@@ -39,8 +54,10 @@ export async function runConvert(args, deps, io) {
             profileDetected: result.meta.profileDetected,
             lostElementsCount: result.meta.lostElementsCount,
             lostElements: result.meta.lostElements,
+            conversionTools: result.meta.conversionTools,
+            livemode: result.meta.livemode,
             contentType: result.contentType,
         },
-        summary: `Converted ${from}to ${to}.${lost}`,
+        summary: `Converted ${from}to ${to}, returned as ${kind === 'pdf' ? 'a PDF' : 'XML'}${sandbox}.${checked}${lost}`,
     });
 }

package/dist/commands/generate.js

@@ -2,10 +2,13 @@ import { LIVE_GENERATE_STANDARDS, isProfileAllowedForStandard, profilesForStanda
 import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
 import { UsageError } from '../errors.js';
 import { emitDocument } from './emit.js';
+import { checkDepth, franceBlockLines, verdictWord } from '../verdict.js';
 /**
- * Generate a compliant document from an EN 16931 invoice given as JSON. XML is
- * printed to stdout (or --output); a PDF must go to --output. verify defaults on
- * so a non-compliant document fails closed rather than being handed back.
+ * Generate a document from an EN 16931 invoice given as JSON. XML is printed to
+ * stdout (or --output); a PDF must go to --output. verify defaults on, so the
+ * API refuses a document that fails its own validation instead of handing it
+ * back. The summary names how deep that validation went. The verdict is about
+ * the invoice XML, so for a PDF the summary says so and names the kind of PDF.
  */
 export async function runGenerate(args, deps, io) {
     const file = requirePositional(args, 'beliq generate <invoice.json|-> --standard <standard>');
@@ -43,11 +46,20 @@ export async function runGenerate(args, deps, io) {
         // render theirs either way, so this is inert for them.
         template: output === 'pdf' ? 'standard' : undefined,
         verify: !flagBool(args, 'no-verify'),
-        seal,
+        // Always the JSON envelope: it is the only response that carries the
+        // verdict's check depth, and the API does the same work for either shape.
+        // --seal decides whether the hash and the verdict are printed.
+        seal: true,
     });
-    const checked = result.meta.schematronVersion
-        ? `, checked against Schematron ${result.meta.schematronVersion}`
-        : '';
+    const verdict = result.validationResult;
+    // `verified: false` is the API's statement that --no-verify skipped validation.
+    const ran = verdict?.verified !== false;
+    const schematron = ran && result.meta.schematronVersion ? `checked against Schematron ${result.meta.schematronVersion}` : '';
+    const depth = verdict === undefined ? '' : ran ? checkDepth(verdict) : 'not validated';
+    const check = [schematron, depth].filter((part) => part !== '').join(', ');
+    const pdfKind = output === 'pdf' && result.meta.pdfKind ? ` (${result.meta.pdfKind})` : '';
+    const checked = check === '' ? '' : output === 'pdf' ? `; invoice XML ${check}` : `, ${check}`;
+    const france = verdict ? franceBlockLines(verdict).map((line) => ` ${line}`).join('') : '';
     const sandbox = result.meta.livemode === false ? ' (sandbox)' : '';
     const meta = {
         output,
@@ -56,16 +68,15 @@ export async function runGenerate(args, deps, io) {
         pdfKind: result.meta.pdfKind,
         outputEnvelope: result.meta.outputEnvelope,
         livemode: result.meta.livemode,
+        verificationBadge: verdict?.verificationBadge,
+        verificationBadgeLabel: verdict?.verificationBadgeLabel,
     };
-    let summary = `Generated a ${standard} ${output} document${checked}${sandbox}.`;
+    let summary = `Generated a ${standard} ${output} document${pdfKind}${checked}${sandbox}.${france}`;
     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}`;
+        meta.validationResult = verdict;
+        summary += ` sha256 ${result.sha256}.${verdict ? ` Verdict: ${verdictWord(verdict)}.` : ''}`;
     }
     return emitDocument(io, args, { kind: output, bytes: result.bytes, meta, summary });
 }

package/dist/commands/parse.js

@@ -2,7 +2,7 @@ import { LIVE_PARSE_FORMATS } from '@beliq/sdk';
 import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
 import { EXIT } from '../exit.js';
 import { renderParseHuman } from '../format/parse.js';
-/** Parse one document into a structured EN 16931 invoice. */
+/** Parse one document into a structured EN 16931 invoice, with the API's warnings about what it did not return. */
 export async function runParse(args, deps, io) {
     const file = requirePositional(args, 'beliq parse <file|->');
     const format = oneOf(flagStr(args, 'format'), LIVE_PARSE_FORMATS, 'format');

package/dist/commands/validate.js

@@ -8,17 +8,22 @@ const FAIL_ON = ['error', 'warning'];
 // rate-limited), not one bad document. Fail fast rather than retry per file.
 const FATAL_API_STATUSES = new Set([401, 403, 429]);
 /**
- * Validate one or many documents against beliq's authority-pinned rules.
+ * Validate one or many documents. Each verdict names how deep its check went.
  *
- * 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 or carries France CTC blocking rule
+ * ids, 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 +35,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 });
-        io.stdout(json ? `${JSON.stringify(result, null, 2)}\n` : `${renderValidationHuman(result)}\n`);
+    // 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, { franceFailsFile: true })}\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

@@ -1,11 +1,18 @@
 export const EXIT = {
     /** Success, or a document that passed validation. */
     OK: 0,
-    /** A document that failed validation per the chosen --fail-on threshold. */
+    /**
+     * A document that failed validation per the chosen --fail-on threshold, or one
+     * whose result carries France CTC blocking rule ids.
+     */
     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,
@@ -13,11 +20,15 @@ export const EXIT = {
 /**
  * The CI contract: EXIT.OK when the document passes the chosen threshold,
  * EXIT.INVALID otherwise. `error` (default) fails on any error; `warning` also
- * fails on any warning.
+ * fails on any warning. A result that carries France CTC blocking rule ids
+ * fails under both: the API reports those ids beside `valid`, also where `valid`
+ * is true, so the default threshold alone would let such a result pass.
  */
 export function computeExitCode(result, failOn) {
     const errorCount = result.errors?.length ?? 0;
     const warningCount = result.warnings?.length ?? 0;
+    if ((result.franceCtcBlockingRuleIds?.length ?? 0) > 0)
+        return EXIT.INVALID;
     const failsOnError = !result.valid || errorCount > 0;
     if (failOn === 'warning')
         return failsOnError || warningCount > 0 ? EXIT.INVALID : EXIT.OK;

package/dist/format/parse.js

@@ -2,9 +2,10 @@ function plural(n, word) {
     return `${n} ${word}${n === 1 ? '' : 's'}`;
 }
 /**
- * A one-line summary of a parse: the detected syntax and profile, then the
- * invoice number, line count, and gross total. `--json` emits the full parsed
- * invoice instead.
+ * A summary of a parse: the detected syntax and profile, then the invoice
+ * number, line count, and gross total, then each warning the API sent about
+ * what the document holds and the parsed invoice does not. `--json` emits the
+ * full result instead.
  */
 export function renderParseHuman(result) {
     const invoice = result.invoice;
@@ -14,5 +15,15 @@ export function renderParseHuman(result) {
     const gross = invoice?.totalGrossAmount != null
         ? `, gross ${invoice.totalGrossAmount} ${invoice.currencyCode ?? ''}`.trimEnd()
         : '';
-    return `Parsed a ${result.format}${profile} document: ${number}, ${plural(lines, 'line')}${gross}`;
+    const head = `Parsed a ${result.format}${profile} document: ${number}, ${plural(lines, 'line')}${gross}`;
+    const warnings = result.warnings ?? [];
+    if (warnings.length === 0)
+        return head;
+    const listed = warnings.map((w) => {
+        const field = w.field ? ` (field ${w.field})` : '';
+        const terms = w.terms?.length ? ` Terms: ${w.terms.join(', ')}.` : '';
+        const elements = w.elements?.length ? ` ${plural(w.elements.length, 'element path')}; --json lists them.` : '';
+        return `- ${w.code}${field}: ${w.message}${terms}${elements}`;
+    });
+    return [head, `${plural(warnings.length, 'warning')}:`, ...listed].join('\n');
 }

package/dist/format/validate.js

@@ -1,3 +1,4 @@
+import { checkDepth, franceBlockLines, franceBlockingRuleIds, pdfInputLine, rulesetChannelLine, verdictWord, } from '../verdict.js';
 function plural(n, word) {
     return `${n} ${word}${n === 1 ? '' : 's'}`;
 }
@@ -13,42 +14,66 @@ function renderTable(headers, rows) {
     return [line(headers), ...rows.map(line)].join('\n');
 }
 /**
- * A human-readable verdict: the pass/fail line with format, profile, and
- * ruleset version, the issue counts, and an aligned table of the errors then
- * warnings. `--json` emits the raw result instead.
+ * A human-readable verdict: the API's verdict word with the format, the
+ * profile, the check depth and the ruleset version, then the issue counts, what
+ * the API says about the ruleset channel, a PDF input and a France CTC block,
+ * and an aligned table of the errors then warnings. `--json` emits the raw
+ * result instead. `franceFailsFile` adds what a France CTC block does to the
+ * exit code of `validate`; a verdict printed for a refused generate or convert
+ * leaves it out, because that run exits 3.
  */
-export function renderValidationHuman(result) {
+export function renderValidationHuman(result, opts = {}) {
     const errors = (result.errors ?? []);
     const warnings = (result.warnings ?? []);
-    const verdict = result.valid ? 'VALID' : 'INVALID';
     const profile = result.profileDetected ? ` (profile ${result.profileDetected})` : '';
-    const schematron = result.schematronVersion ? `  checked against Schematron ${result.schematronVersion}` : '';
-    const head = `${verdict}  ${result.format}${profile}${schematron}`;
+    // Nothing ran when `verified` is false, so there is no depth and no ruleset to name.
+    const ran = result.verified !== false;
+    const depth = ran ? `  ${checkDepth(result)}` : '';
+    const schematron = ran && result.schematronVersion ? `  checked against Schematron ${result.schematronVersion}` : '';
+    const head = `${verdictWord(result)}  ${result.format}${profile}${depth}${schematron}`;
     const counts = `${plural(errors.length, 'error')}, ${plural(warnings.length, 'warning')}`;
+    const france = franceBlockLines(result);
+    const notes = [
+        rulesetChannelLine(result),
+        pdfInputLine(result),
+        ...france,
+        ...(france.length > 0 && opts.franceFailsFile
+            ? ['This file is reported as failed (exit 1) under every --fail-on.']
+            : []),
+    ].filter((line) => line !== undefined);
+    const top = [head, counts, ...notes].join('\n');
     const issues = [...errors, ...warnings];
     if (issues.length === 0)
-        return `${head}\n${counts}`;
+        return top;
     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)}`;
+    return `${top}\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.
+ * counts and the check depth), a line for each file a France CTC block fails,
+ * 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})`]
+        ? ['ERROR', '-', '-', '-', `${r.file}  (${r.error})`]
         : [
             r.fails ? 'FAIL' : 'PASS',
             String((r.result.errors ?? []).length),
             String((r.result.warnings ?? []).length),
+            checkDepth(r.result),
             r.file,
         ]);
-    const table = renderTable(['STATUS', 'ERR', 'WARN', 'FILE'], cells);
+    const table = renderTable(['STATUS', 'ERR', 'WARN', 'DEPTH', 'FILE'], cells);
+    const blocked = rows.flatMap((r) => {
+        if ('error' in r)
+            return [];
+        const ids = franceBlockingRuleIds(r.result);
+        return ids.length > 0 ? [`${r.file}: France CTC blocking rule ids: ${ids.join(', ')}`] : [];
+    });
     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}`;
+    return [table, ...(blocked.length > 0 ? [blocked.join('\n')] : []), summary].join('\n\n');
 }

package/dist/help.js

@@ -7,19 +7,35 @@ 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|fatturapa|facturae|eslog|ksef [--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. For a PDF the verdict is about
+the embedded XML; the PDF itself is not checked.
+
+Each verdict carries the check depth as the API states it, or "check depth not
+stated" where the API states none. What the depths mean:
+https://docs.beliq.eu/compliance/how-verification-works/
+
+validate --france-ctc also applies the French CTC rules (BR-FR-CTC). A result
+that carries France CTC blocking rule ids fails the file with exit 1 under
+every --fail-on, also where the verdict is VALID.
+
+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.
 
+convert returns XML for every target, facturx and zugferd included. A PDF comes
+back only when a hybrid PDF source already is the target, and needs --output.
+
 --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.
@@ -29,18 +45,23 @@ 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
 
 Exit codes:
   0  success, or a valid document
-  1  document invalid (validate, per --fail-on)
+  1  document invalid (validate, per --fail-on), or France CTC blocking rule
+     ids in the result
   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
-document fails --fail-on, 3 if any file could not be checked.
+document fails --fail-on or carries France CTC blocking rule ids, 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/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/dist/resultFields.js

@@ -0,0 +1,87 @@
+export const VALIDATION_FIELDS = {
+    valid: 'text',
+    verified: 'text',
+    format: 'text',
+    profileDetected: 'text',
+    verificationBadgeLabel: 'text',
+    schematronVersion: 'text',
+    franceCtcBlockingRuleIds: 'text',
+    rulesetChannel: 'text',
+    rulesetFellBack: 'text',
+    rulesetSunsetsOn: 'text',
+    pdfInput: 'text',
+    errors: 'text',
+    warnings: 'text',
+    // The label above is the display form of these two ids.
+    verificationTier: 'json',
+    verificationBadge: 'json',
+    sha256: 'json',
+    rulesetSha256: 'json',
+    rulesetArtifacts: 'json',
+    driftCheckedAt: 'json',
+    ciusVersion: 'json',
+    peppolVersion: 'json',
+    facturxProfile: 'json',
+    facturxVersion: 'json',
+    franceCtcApplied: 'json',
+    franceCtcVersion: 'json',
+    franceExtendedCtcApplied: 'json',
+    italyFatturapaXsdBundle: 'json',
+    italyFatturapaRuntimeVersion: 'json',
+    italySdiMessaggiXsdBundle: 'json',
+    italySdiMessaggiXsdVersion: 'json',
+    spainFacturaeXsdBundle: 'json',
+    spainFacturaeRuntimeVersion: 'json',
+    sloveniaEslogXsdBundle: 'json',
+    sloveniaEslogRuntimeVersion: 'json',
+    polandKsefFa3XsdBundle: 'json',
+    polandKsefFa3RuntimeVersion: 'json',
+    romaniaRoCiusVersion: 'json',
+    netherlandsNlciusVersion: 'json',
+};
+export const PARSE_FIELDS = {
+    format: 'text',
+    profileDetected: 'text',
+    invoice: 'text',
+    warnings: 'text',
+    profileUrn: 'json',
+    businessProcessId: 'json',
+    franceCtcDetected: 'json',
+};
+/**
+ * Generate and convert build their --json object field by field, so a field
+ * can also be left out. `document` is the output itself, and `seal` fields are
+ * printed with --seal only.
+ */
+export const GENERATE_FIELDS = {
+    bytes: 'document',
+    xml: 'document',
+    contentType: 'json',
+    sha256: 'seal',
+    // The summary reads the check depth from it; the whole object is printed with --seal.
+    validationResult: 'text',
+    meta: 'json',
+};
+export const GENERATE_META_FIELDS = {
+    schematronVersion: 'text',
+    livemode: 'text',
+    pdfKind: 'text',
+    outputEnvelope: 'json',
+    rulesetSha256: 'seal',
+    // With --seal the verdict object carries the same list.
+    rulesetArtifacts: 'seal',
+};
+export const CONVERT_FIELDS = {
+    bytes: 'document',
+    contentType: 'json',
+    meta: 'json',
+};
+export const CONVERT_META_FIELDS = {
+    sourceFormat: 'text',
+    targetFormat: 'text',
+    lostElementsCount: 'text',
+    livemode: 'text',
+    profileDetected: 'json',
+    lostElements: 'json',
+    conversionTools: 'json',
+};

package/dist/verdict.js

@@ -0,0 +1,68 @@
+/**
+ * Printed where the API sent no badge label for a verdict. It names no depth,
+ * so it claims none.
+ */
+export const DEPTH_NOT_STATED = 'check depth not stated';
+/** The API's own entry in `warnings` that explains `franceCtcBlockingRuleIds`. */
+const FRANCE_BLOCK_ENTRY = 'FRANCE_CTC_FINDINGS_BLOCK_TRANSMISSION';
+/**
+ * The verdict in the API's own words. `verified: false` means no ruleset ran
+ * (generate with verify off), so neither word applies.
+ */
+export function verdictWord(result) {
+    if (result.verified === false)
+        return 'NOT VALIDATED';
+    return result.valid ? 'VALID' : 'INVALID';
+}
+/** The badge label the API sent, printed as it came, or the mark for none. */
+export function checkDepth(result) {
+    return result.verificationBadgeLabel ?? DEPTH_NOT_STATED;
+}
+/** The France CTC rule ids the API reports as ending a transmission; empty when it sent none. */
+export function franceBlockingRuleIds(result) {
+    return result.franceCtcBlockingRuleIds ?? [];
+}
+/**
+ * The lines that explain a France CTC block: the API's own message for it when
+ * the result carries one, and the rule ids unless that message already names
+ * every one of them.
+ */
+export function franceBlockLines(result) {
+    const ids = franceBlockingRuleIds(result);
+    if (ids.length === 0)
+        return [];
+    const entry = (result.warnings ?? []).find((w) => w.ruleId === FRANCE_BLOCK_ENTRY);
+    const idLine = `France CTC blocking rule ids: ${ids.join(', ')}`;
+    if (!entry)
+        return [idLine];
+    const named = new Set(entry.message.split(/[^A-Za-z0-9_-]+/));
+    return ids.every((id) => named.has(id)) ? [entry.message] : [entry.message, idLine];
+}
+/**
+ * The embedded file's name comes from the uploaded PDF. Control and format
+ * characters, line separators and the double quote are replaced, so a crafted
+ * name can neither start a line of its own nor close the quotes around it.
+ */
+function printable(name) {
+    return name.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}"]/gu, '?');
+}
+/** What the API says about a PDF input: which embedded file was read, and that the PDF was not checked. */
+export function pdfInputLine(result) {
+    const pdf = result.pdfInput;
+    if (!pdf)
+        return undefined;
+    const name = pdf.attachmentName ? ` "${printable(pdf.attachmentName)}"` : '';
+    const others = pdf.attachmentCandidates > 1
+        ? ` ${pdf.attachmentCandidates} embedded files could be taken for the invoice, and nothing compared them.`
+        : '';
+    return (`PDF input: the verdict is about the embedded XML${name} (found by ${pdf.attachmentFoundBy}). ` +
+        `The PDF itself was not checked.${others}`);
+}
+/** Which ruleset channel the API says served the request, when the result names one. */
+export function rulesetChannelLine(result) {
+    if (!result.rulesetChannel)
+        return undefined;
+    const fellBack = result.rulesetFellBack ? ', which had nothing to reach, so the latest ruleset ran' : '';
+    const sunset = result.rulesetSunsetsOn ? `; the retained ruleset is served until ${result.rulesetSunsetsOn}` : '';
+    return `Ruleset channel: ${result.rulesetChannel}${fellBack}${sunset}`;
+}

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,7 +1,7 @@
 {
   "name": "beliq-cli",
-  "version": "0.2.2",
-  "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.",
+  "version": "0.4.0",
+  "description": "beliq CLI: validate, generate, parse, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) from the terminal or CI. Every verdict states how deep its check went.",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -48,23 +48,24 @@
     "build": "npm run clean && tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
     "test": "vitest run --exclude test/integration.test.ts",
     "test:integration": "vitest run test/integration.test.ts",
     "scrub:check": "bash scripts/scrub-check.sh",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@beliq/sdk": "^0.4.0"
+    "@beliq/sdk": "^0.5.1"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.0",
+    "eslint": "^10.11.0",
+    "globals": "^17.12.0",
     "typescript": "^5.5.4",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^4.0.0"
   }
 }