beliq-cli 0.3.0 → 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
 
@@ -18,7 +18,7 @@ Requires Node.js >= 20.15.
 
 ```
 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 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]
@@ -30,6 +30,26 @@ 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. 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
 beliq validate invoice.xml
@@ -69,18 +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), 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` 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" } }`.
+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
@@ -88,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/cli.js

@@ -76,9 +76,10 @@ export async function main(argv, io, env = process.env) {
 }
 /**
  * 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.
+ * 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})` : '';

package/dist/commands/convert.js

@@ -1,14 +1,18 @@
 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>');
@@ -22,18 +26,25 @@ export async function runConvert(args, deps, io) {
     // 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: 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,
@@ -43,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,12 +8,13 @@ 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 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).
+ * 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.
  */
@@ -39,7 +40,7 @@ export async function runValidate(args, deps, io) {
     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`);
+        io.stdout(json ? `${JSON.stringify(result, null, 2)}\n` : `${renderValidationHuman(result, { franceFailsFile: true })}\n`);
         return computeExitCode(result, failOn);
     }
     return runBatch(files, { format, contentType, franceCtc, failOn, json }, deps, io);

package/dist/exit.js

@@ -1,7 +1,10 @@
 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,
@@ -17,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

@@ -8,7 +8,7 @@ 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] [--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 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]
@@ -16,8 +16,16 @@ Usage:
 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. A
-directory is a batch even when it holds one file. validate --france-ctc also
-applies the French CTC rules (BR-FR-CTC).
+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.
@@ -25,6 +33,9 @@ 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.
@@ -42,13 +53,15 @@ Global options:
 
 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, 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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "beliq-cli",
-  "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.",
+  "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": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.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"
   }
 }