@beliq/sdk 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,64 @@
4
4
  resolves 0.4.x and never reaches 0.5.0. Additive spec syncs ship as patches for
5
5
  that reason, and a minor is reserved for a change that needs consumers to opt in.
6
6
 
7
+ ## 0.6.0 - 2026-11-03
8
+
9
+ A minor, because code can stop compiling in two places, and a `^0.5.0` range
10
+ does not reach a minor.
11
+
12
+ - `ConvertMeta.lostElements` holds the entries of `x-lost-elements` as the API
13
+ sends them. Each is a `LostElement` with `path`, `value`, `reason`, `severity`
14
+ and `acceptableLoss`, as
15
+ https://docs.beliq.eu/api-reference/convert/#lostelement-schema describes.
16
+ Past the API's 6 KB header cap the list holds one `LostElementsTruncated`
17
+ entry, `{ truncated: true, reason? }`, instead, and `lostElementsCount` stays
18
+ the exact count. The field was typed `string[]` and held `"[object Object]"`
19
+ for every entry, so code that reads an entry as a string stops compiling.
20
+ Both types are exported.
21
+ - The vendored `openapi.json` is document `0.23.0` of the API, up from
22
+ `0.16.0`. In the generated types, `generate()`'s `invoice.spain` (Facturae)
23
+ takes only the value the engine builds for each field: `modality` `I`,
24
+ `invoiceIssuerType` `EM`, `invoiceDocumentType` `FC`, `invoiceClass` `OO`
25
+ and `taxTypeCode` `01`. `invoice.poland` (KSeF) takes only `"2"` for
26
+ `adnotacje.P_18`, `adnotacje.P_23`, `jst` and `gv`. Code that passes another
27
+ value stops compiling. The API refuses those values.
28
+ - The error code union gains `DATABASE_UNAVAILABLE`, a 503 on every route,
29
+ which the client retries like any 503. A `switch` over the code that
30
+ TypeScript checks for exhaustiveness needs the new case.
31
+ - `ValidateFormat` and `ParseFormat` take `poland_ksef_fa2`.
32
+ - `LIVE_VALIDATE_FORMATS` gains `fatturapa`, `facturae`, `eslog` and
33
+ `poland_ksef_fa3`, the four national formats `GET /v1/rulesets` lists, each
34
+ Schema-checked. A tool that builds a validate option list from it offers the
35
+ four. `LIVE_PARSE_FORMATS` stays `auto`, `cii` and `ubl`, because
36
+ `POST /v1/parse` reads CII and UBL only.
37
+ - `advanced` on `validate()`, `parse()` and `convert()` is merged into the
38
+ query. The API answers 400 `VALIDATION_ERROR` to a query key the operation
39
+ does not declare, and `err.details.fields` names it.
40
+
41
+ ## 0.5.2 - 2026-10-24
42
+
43
+ A patch: `@beliq/sdk/helpers` gains the wording for a verdict and a converted
44
+ PDF, and the vendored spec moves on two documents. No method changes.
45
+
46
+ - `verdictWord`, `checkDepth` and `DEPTH_NOT_STATED`, `franceBlockingRuleIds`,
47
+ `franceBlockLines` and `FRANCE_CTC_BLOCKING_FINDING_RULE_ID`, `pdfInputLine`
48
+ and `rulesetChannelLine` are the words beliq-cli and beliq-mcp printed from
49
+ two copies of their own. Each restates a field of `ValidationResult`.
50
+ `checkDepth` gives `verificationBadgeLabel` as it came, or
51
+ `check depth not stated` when the API sent no label, so it never names a
52
+ depth the API did not state.
53
+ - `CONVERT_PDF_LINE` says what a PDF that `convert()` returns for a `facturx`
54
+ or `zugferd` target is: the PDF as sent, with only its annotation flags
55
+ normalised for PDF/A and its container not checked, when its embedded XML
56
+ already is the target, and otherwise that PDF re-wrapped around the converted XML and passed by
57
+ veraPDF against PDF/A-3b. With a test key the PDF is watermarked after any
58
+ veraPDF check, so the line never says veraPDF checked the file returned.
59
+ - The vendored `openapi.json` is document `0.16.0` of the API, up from
60
+ `0.15.0`. Document `0.15.1` describes the PDF re-wrap in `convert()`'s
61
+ description. Document `0.16.0` gives each `previousChannel` row of
62
+ `GET /v1/rulesets` a `retained` list, in the generated `operations` type
63
+ only: the SDK has no method for that route.
64
+
7
65
  ## 0.5.1 - 2026-10-11
8
66
 
9
67
  A patch: the types gain two fields and two error codes. No method changes.
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @beliq/sdk
2
2
 
3
- Official Node/TypeScript SDK for the [beliq](https://beliq.eu) e-invoicing compliance API. Generate, validate, parse, and convert EN 16931 invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, nightly-drift-checked rules.
3
+ Official Node/TypeScript SDK for the [beliq](https://beliq.eu) API: validate, generate, convert and parse EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) from Node.js. A validation result names the rule pack that judged the document, its version and, in `verificationBadgeLabel` when the API states one, how deep the check went. [How verification works](https://docs.beliq.eu/compliance/how-verification-works/) explains each depth.
4
4
 
5
- beliq produces and checks the compliant document. Transmission (Peppol, PDP, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.
5
+ beliq produces and checks the document. Transmission (Peppol, plateforme agréée, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.
6
6
 
7
7
  ## Install
8
8
 
@@ -60,7 +60,7 @@ const generated = await beliq.generate({
60
60
  });
61
61
  console.log(generated.xml, generated.meta.schematronVersion);
62
62
 
63
- // Validate any document against authority-pinned rules.
63
+ // Validate a document. The result names the rules that ran and, when the API states one, the check depth.
64
64
  const result = await beliq.validate(generated.xml!, { format: 'auto' });
65
65
  if (!result.valid) {
66
66
  for (const issue of result.errors) console.log(issue.ruleId, issue.message);
@@ -129,7 +129,7 @@ shorter than the server's own turns completed work into an unknown outcome. Set
129
129
  | `parse(document, options?)` | POST /v1/parse | XML or PDF | `ParseResult` |
130
130
  | `convert(document, options)` | POST /v1/convert | XML or PDF | `{ contentType, bytes, meta }` |
131
131
 
132
- `document` accepts a `string`, `Uint8Array`, `Buffer`, `ArrayBuffer`, or typed array. The content type is sniffed from the bytes (PDF vs XML) unless you pass `options.contentType`. `generate` and `convert` return raw document bytes plus the response-header metadata (`schematronVersion`, `pdfKind`, `sourceFormat`/`targetFormat`, `lostElements`, `conversionTools`, `livemode`); for an XML output, `generate` also decodes `xml`.
132
+ `document` accepts a `string`, `Uint8Array`, `Buffer`, `ArrayBuffer`, or typed array. The content type is sniffed from the bytes (PDF vs XML) unless you pass `options.contentType`. `generate` and `convert` return raw document bytes plus the response-header metadata (`schematronVersion`, `pdfKind`, `sourceFormat`/`targetFormat`, `lostElements`, `conversionTools`, `livemode`); for an XML output, `generate` also decodes `xml`. Each entry of `lostElements` is a `LostElement` as https://docs.beliq.eu/api-reference/convert/#lostelement-schema describes it, except past the API's 6 KB header cap, where the list holds one `{ truncated: true, reason }` entry instead and `lostElementsCount` stays the exact count.
133
133
 
134
134
  ### Verify-it-yourself seal
135
135
 
@@ -154,6 +154,17 @@ const nlcius = LIVE_GENERATE_PRESETS.find((p) => p.id === 'nlcius');
154
154
  await beliq.generate({ standard: nlcius!.standard, profile: nlcius!.profile, invoice });
155
155
  ```
156
156
 
157
+ ### Verdict and convert wording
158
+
159
+ `@beliq/sdk/helpers` holds the words the beliq tools print for a verdict, so each tool says the same thing. `verdictWord` gives `VALID`, `INVALID`, or `NOT VALIDATED` when no ruleset ran. `checkDepth` gives `verificationBadgeLabel` as the API sent it, or `check depth not stated` when it sent none. `franceBlockLines` gives the API's explanation when `franceCtcBlockingRuleIds` is present. `pdfInputLine` and `rulesetChannelLine` restate `pdfInput` and the ruleset channel. `CONVERT_PDF_LINE` says what a PDF that `convert` returns is.
160
+
161
+ ```ts
162
+ import { checkDepth, franceBlockLines, verdictWord } from '@beliq/sdk/helpers';
163
+
164
+ const result = await beliq.validate(xml);
165
+ console.log(...franceBlockLines(result), `${verdictWord(result)} (${checkDepth(result)})`);
166
+ ```
167
+
157
168
  Every option enum is typed from the OpenAPI spec, so wrong values fail at compile time. Errors throw `BeliqApiError` with a typed `.code`, HTTP `.status`, and any `.details`:
158
169
 
159
170
  ```ts
package/dist/helpers.cjs CHANGED
@@ -20,7 +20,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/helpers.ts
21
21
  var helpers_exports = {};
22
22
  __export(helpers_exports, {
23
+ CONVERT_PDF_LINE: () => CONVERT_PDF_LINE,
23
24
  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
25
+ DEPTH_NOT_STATED: () => DEPTH_NOT_STATED,
26
+ FRANCE_CTC_BLOCKING_FINDING_RULE_ID: () => FRANCE_CTC_BLOCKING_FINDING_RULE_ID,
24
27
  LIVE_CONVERT_SOURCE_FORMATS: () => LIVE_CONVERT_SOURCE_FORMATS,
25
28
  LIVE_CONVERT_TARGET_FORMATS: () => LIVE_CONVERT_TARGET_FORMATS,
26
29
  LIVE_GENERATE_PRESETS: () => LIVE_GENERATE_PRESETS,
@@ -30,14 +33,20 @@ __export(helpers_exports, {
30
33
  LIVE_PROFILES_BY_STANDARD: () => LIVE_PROFILES_BY_STANDARD,
31
34
  LIVE_VALIDATE_FORMATS: () => LIVE_VALIDATE_FORMATS,
32
35
  buildRequest: () => buildRequest,
36
+ checkDepth: () => checkDepth,
33
37
  compactQuery: () => compactQuery,
34
38
  decodeUtf8: () => decodeUtf8,
39
+ franceBlockLines: () => franceBlockLines,
40
+ franceBlockingRuleIds: () => franceBlockingRuleIds,
35
41
  isPlainObject: () => isPlainObject,
36
42
  isProfileAllowedForStandard: () => isProfileAllowedForStandard,
37
43
  mergeDeep: () => mergeDeep,
44
+ pdfInputLine: () => pdfInputLine,
38
45
  profilesForStandard: () => profilesForStandard,
46
+ rulesetChannelLine: () => rulesetChannelLine,
39
47
  sniffContentType: () => sniffContentType,
40
- toBytes: () => toBytes
48
+ toBytes: () => toBytes,
49
+ verdictWord: () => verdictWord
41
50
  });
42
51
  module.exports = __toCommonJS(helpers_exports);
43
52
 
@@ -200,7 +209,15 @@ function isProfileAllowedForStandard(standard, profile) {
200
209
  const allowed = profilesForStandard(standard);
201
210
  return allowed.length === 0 || allowed.includes(profile);
202
211
  }
203
- var LIVE_VALIDATE_FORMATS = ["auto", "cii", "ubl"];
212
+ var LIVE_VALIDATE_FORMATS = [
213
+ "auto",
214
+ "cii",
215
+ "ubl",
216
+ "fatturapa",
217
+ "facturae",
218
+ "eslog",
219
+ "poland_ksef_fa3"
220
+ ];
204
221
  var LIVE_PARSE_FORMATS = ["auto", "cii", "ubl"];
205
222
  var LIVE_CONVERT_SOURCE_FORMATS = [
206
223
  "auto",
@@ -219,9 +236,52 @@ var LIVE_CONVERT_TARGET_FORMATS = [
219
236
  "xrechnung",
220
237
  "peppol-bis"
221
238
  ];
239
+
240
+ // src/verdict.ts
241
+ var DEPTH_NOT_STATED = "check depth not stated";
242
+ var FRANCE_CTC_BLOCKING_FINDING_RULE_ID = "FRANCE_CTC_FINDINGS_BLOCK_TRANSMISSION";
243
+ var CONVERT_PDF_LINE = "The PDF is the one sent, with only its annotation flags normalised for PDF/A, when its embedded XML already is the target: that XML was checked and the PDF container was not. Otherwise it is that PDF re-wrapped around the converted XML, returned only after veraPDF passed it against PDF/A-3b. With a test key the PDF is watermarked last, after any veraPDF check. Detail: https://docs.beliq.eu/api-reference/convert/#a-pdf-sent-for-a-zugferd-or-factur-x-target";
244
+ function verdictWord(result) {
245
+ if (result.verified === false) return "NOT VALIDATED";
246
+ return result.valid ? "VALID" : "INVALID";
247
+ }
248
+ function checkDepth(result) {
249
+ return result.verificationBadgeLabel ?? DEPTH_NOT_STATED;
250
+ }
251
+ function franceBlockingRuleIds(result) {
252
+ return result.franceCtcBlockingRuleIds ?? [];
253
+ }
254
+ function franceBlockLines(result) {
255
+ const ids = franceBlockingRuleIds(result);
256
+ if (ids.length === 0) return [];
257
+ const entry = (result.warnings ?? []).find((w) => w.ruleId === FRANCE_CTC_BLOCKING_FINDING_RULE_ID);
258
+ const idLine = `France CTC blocking rule ids: ${ids.join(", ")}`;
259
+ if (!entry) return [idLine];
260
+ const named = new Set(entry.message.split(/[^A-Za-z0-9_-]+/));
261
+ return ids.every((id) => named.has(id)) ? [entry.message] : [entry.message, idLine];
262
+ }
263
+ function printable(name) {
264
+ return name.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}"]/gu, "?");
265
+ }
266
+ function pdfInputLine(result) {
267
+ const pdf = result.pdfInput;
268
+ if (!pdf) return void 0;
269
+ const name = pdf.attachmentName ? ` "${printable(pdf.attachmentName)}"` : "";
270
+ const others = pdf.attachmentCandidates > 1 ? ` ${pdf.attachmentCandidates} embedded files could be taken for the invoice, and nothing compared them.` : "";
271
+ return `PDF input: the verdict is about the embedded XML${name} (found by ${pdf.attachmentFoundBy}). The PDF itself was not checked.${others}`;
272
+ }
273
+ function rulesetChannelLine(result) {
274
+ if (!result.rulesetChannel) return void 0;
275
+ const fellBack = result.rulesetFellBack ? ", which had nothing to reach, so the latest ruleset ran" : "";
276
+ const sunset = result.rulesetSunsetsOn ? `; the retained ruleset is served until ${result.rulesetSunsetsOn}` : "";
277
+ return `Ruleset channel: ${result.rulesetChannel}${fellBack}${sunset}`;
278
+ }
222
279
  // Annotate the CommonJS export names for ESM import in node:
223
280
  0 && (module.exports = {
281
+ CONVERT_PDF_LINE,
224
282
  DEFAULT_BASE_URL,
283
+ DEPTH_NOT_STATED,
284
+ FRANCE_CTC_BLOCKING_FINDING_RULE_ID,
225
285
  LIVE_CONVERT_SOURCE_FORMATS,
226
286
  LIVE_CONVERT_TARGET_FORMATS,
227
287
  LIVE_GENERATE_PRESETS,
@@ -231,12 +291,18 @@ var LIVE_CONVERT_TARGET_FORMATS = [
231
291
  LIVE_PROFILES_BY_STANDARD,
232
292
  LIVE_VALIDATE_FORMATS,
233
293
  buildRequest,
294
+ checkDepth,
234
295
  compactQuery,
235
296
  decodeUtf8,
297
+ franceBlockLines,
298
+ franceBlockingRuleIds,
236
299
  isPlainObject,
237
300
  isProfileAllowedForStandard,
238
301
  mergeDeep,
302
+ pdfInputLine,
239
303
  profilesForStandard,
304
+ rulesetChannelLine,
240
305
  sniffContentType,
241
- toBytes
306
+ toBytes,
307
+ verdictWord
242
308
  });
@@ -1,5 +1,6 @@
1
- import { P as PlainObject } from './constants-DFGl_MXW.cjs';
2
- export { D as DEFAULT_BASE_URL, a as DocumentInput, G as GeneratePreset, L as LIVE_CONVERT_SOURCE_FORMATS, b as LIVE_CONVERT_TARGET_FORMATS, c as LIVE_GENERATE_PRESETS, d as LIVE_GENERATE_STANDARDS, e as LIVE_PARSE_FORMATS, f as LIVE_PROFILES, g as LIVE_PROFILES_BY_STANDARD, h as LIVE_VALIDATE_FORMATS, i as compactQuery, j as decodeUtf8, k as isPlainObject, l as isProfileAllowedForStandard, m as mergeDeep, p as profilesForStandard, s as sniffContentType, t as toBytes } from './constants-DFGl_MXW.cjs';
1
+ import { P as PlainObject } from './types-Bc3c79Ss.cjs';
2
+ import { ValidationResult } from './index.cjs';
3
+ export { D as DEFAULT_BASE_URL, a as DocumentInput, G as GeneratePreset, L as LIVE_CONVERT_SOURCE_FORMATS, b as LIVE_CONVERT_TARGET_FORMATS, c as LIVE_GENERATE_PRESETS, d as LIVE_GENERATE_STANDARDS, e as LIVE_PARSE_FORMATS, f as LIVE_PROFILES, g as LIVE_PROFILES_BY_STANDARD, h as LIVE_VALIDATE_FORMATS, i as compactQuery, j as decodeUtf8, k as isPlainObject, l as isProfileAllowedForStandard, m as mergeDeep, p as profilesForStandard, s as sniffContentType, t as toBytes } from './types-Bc3c79Ss.cjs';
3
4
 
4
5
  type Operation = 'me' | 'generate' | 'validate' | 'parse' | 'convert';
5
6
  /** 'json' => parse the `{ success, data }` envelope; 'binary' => return raw bytes. */
@@ -45,4 +46,42 @@ interface BuiltRequest {
45
46
  }
46
47
  declare function buildRequest(params: BuildParams): BuiltRequest;
47
48
 
48
- export { type BuildParams, type BuiltRequest, type Operation, type OutputKind, PlainObject, type QueryValue, buildRequest };
49
+ /**
50
+ * Printed where the API sent no badge label for a verdict. It names no depth,
51
+ * so it claims none.
52
+ */
53
+ declare const DEPTH_NOT_STATED = "check depth not stated";
54
+ /**
55
+ * The `ruleId` of the API's own `info` entry in `warnings` that explains
56
+ * `franceCtcBlockingRuleIds` (https://docs.beliq.eu/api-reference/validate/).
57
+ */
58
+ declare const FRANCE_CTC_BLOCKING_FINDING_RULE_ID = "FRANCE_CTC_FINDINGS_BLOCK_TRANSMISSION";
59
+ /**
60
+ * What a PDF that `convert()` returns for a `facturx` or `zugferd` target is, in the words of
61
+ * https://docs.beliq.eu/api-reference/convert/. No documented field says which of the two paths
62
+ * ran, so the line names both. The test-key half is why it never says "veraPDF checked this
63
+ * file": the watermark comes after the check, and the watermarked file does not pass it.
64
+ */
65
+ declare const CONVERT_PDF_LINE: string;
66
+ /**
67
+ * The verdict in the API's own words. `verified: false` means no ruleset ran
68
+ * (generate with verify off), so neither word applies.
69
+ */
70
+ declare function verdictWord(result: Pick<ValidationResult, 'valid' | 'verified'>): string;
71
+ /** The badge label the API sent, as it came, or the mark for none. */
72
+ declare function checkDepth(result: Pick<ValidationResult, 'verificationBadgeLabel'>): string;
73
+ /** The France CTC rule ids the API reports as ending a transmission; empty when it sent none. */
74
+ declare function franceBlockingRuleIds(result: Pick<ValidationResult, 'franceCtcBlockingRuleIds'>): string[];
75
+ /**
76
+ * The lines that explain a France CTC block: the API's own message for it when
77
+ * the result carries one, and the rule ids unless that message already names
78
+ * every one of them.
79
+ */
80
+ declare function franceBlockLines(result: Pick<ValidationResult, 'franceCtcBlockingRuleIds' | 'warnings'>): string[];
81
+ /** What the API says about a PDF input: which embedded file was read, and that the PDF was not checked. */
82
+ declare function pdfInputLine(result: Pick<ValidationResult, 'pdfInput'>): string | undefined;
83
+ /** Which ruleset channel the API says served the request, when the result names one. */
84
+ declare function rulesetChannelLine(result: Pick<ValidationResult, 'rulesetChannel' | 'rulesetFellBack' | 'rulesetSunsetsOn'>): string | undefined;
85
+
86
+ export { CONVERT_PDF_LINE, DEPTH_NOT_STATED, FRANCE_CTC_BLOCKING_FINDING_RULE_ID, PlainObject, buildRequest, checkDepth, franceBlockLines, franceBlockingRuleIds, pdfInputLine, rulesetChannelLine, verdictWord };
87
+ export type { BuildParams, BuiltRequest, Operation, OutputKind, QueryValue };
package/dist/helpers.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- import { P as PlainObject } from './constants-DFGl_MXW.js';
2
- export { D as DEFAULT_BASE_URL, a as DocumentInput, G as GeneratePreset, L as LIVE_CONVERT_SOURCE_FORMATS, b as LIVE_CONVERT_TARGET_FORMATS, c as LIVE_GENERATE_PRESETS, d as LIVE_GENERATE_STANDARDS, e as LIVE_PARSE_FORMATS, f as LIVE_PROFILES, g as LIVE_PROFILES_BY_STANDARD, h as LIVE_VALIDATE_FORMATS, i as compactQuery, j as decodeUtf8, k as isPlainObject, l as isProfileAllowedForStandard, m as mergeDeep, p as profilesForStandard, s as sniffContentType, t as toBytes } from './constants-DFGl_MXW.js';
1
+ import { P as PlainObject } from './types-Bc3c79Ss.js';
2
+ import { ValidationResult } from './index.js';
3
+ export { D as DEFAULT_BASE_URL, a as DocumentInput, G as GeneratePreset, L as LIVE_CONVERT_SOURCE_FORMATS, b as LIVE_CONVERT_TARGET_FORMATS, c as LIVE_GENERATE_PRESETS, d as LIVE_GENERATE_STANDARDS, e as LIVE_PARSE_FORMATS, f as LIVE_PROFILES, g as LIVE_PROFILES_BY_STANDARD, h as LIVE_VALIDATE_FORMATS, i as compactQuery, j as decodeUtf8, k as isPlainObject, l as isProfileAllowedForStandard, m as mergeDeep, p as profilesForStandard, s as sniffContentType, t as toBytes } from './types-Bc3c79Ss.js';
3
4
 
4
5
  type Operation = 'me' | 'generate' | 'validate' | 'parse' | 'convert';
5
6
  /** 'json' => parse the `{ success, data }` envelope; 'binary' => return raw bytes. */
@@ -45,4 +46,42 @@ interface BuiltRequest {
45
46
  }
46
47
  declare function buildRequest(params: BuildParams): BuiltRequest;
47
48
 
48
- export { type BuildParams, type BuiltRequest, type Operation, type OutputKind, PlainObject, type QueryValue, buildRequest };
49
+ /**
50
+ * Printed where the API sent no badge label for a verdict. It names no depth,
51
+ * so it claims none.
52
+ */
53
+ declare const DEPTH_NOT_STATED = "check depth not stated";
54
+ /**
55
+ * The `ruleId` of the API's own `info` entry in `warnings` that explains
56
+ * `franceCtcBlockingRuleIds` (https://docs.beliq.eu/api-reference/validate/).
57
+ */
58
+ declare const FRANCE_CTC_BLOCKING_FINDING_RULE_ID = "FRANCE_CTC_FINDINGS_BLOCK_TRANSMISSION";
59
+ /**
60
+ * What a PDF that `convert()` returns for a `facturx` or `zugferd` target is, in the words of
61
+ * https://docs.beliq.eu/api-reference/convert/. No documented field says which of the two paths
62
+ * ran, so the line names both. The test-key half is why it never says "veraPDF checked this
63
+ * file": the watermark comes after the check, and the watermarked file does not pass it.
64
+ */
65
+ declare const CONVERT_PDF_LINE: string;
66
+ /**
67
+ * The verdict in the API's own words. `verified: false` means no ruleset ran
68
+ * (generate with verify off), so neither word applies.
69
+ */
70
+ declare function verdictWord(result: Pick<ValidationResult, 'valid' | 'verified'>): string;
71
+ /** The badge label the API sent, as it came, or the mark for none. */
72
+ declare function checkDepth(result: Pick<ValidationResult, 'verificationBadgeLabel'>): string;
73
+ /** The France CTC rule ids the API reports as ending a transmission; empty when it sent none. */
74
+ declare function franceBlockingRuleIds(result: Pick<ValidationResult, 'franceCtcBlockingRuleIds'>): string[];
75
+ /**
76
+ * The lines that explain a France CTC block: the API's own message for it when
77
+ * the result carries one, and the rule ids unless that message already names
78
+ * every one of them.
79
+ */
80
+ declare function franceBlockLines(result: Pick<ValidationResult, 'franceCtcBlockingRuleIds' | 'warnings'>): string[];
81
+ /** What the API says about a PDF input: which embedded file was read, and that the PDF was not checked. */
82
+ declare function pdfInputLine(result: Pick<ValidationResult, 'pdfInput'>): string | undefined;
83
+ /** Which ruleset channel the API says served the request, when the result names one. */
84
+ declare function rulesetChannelLine(result: Pick<ValidationResult, 'rulesetChannel' | 'rulesetFellBack' | 'rulesetSunsetsOn'>): string | undefined;
85
+
86
+ export { CONVERT_PDF_LINE, DEPTH_NOT_STATED, FRANCE_CTC_BLOCKING_FINDING_RULE_ID, PlainObject, buildRequest, checkDepth, franceBlockLines, franceBlockingRuleIds, pdfInputLine, rulesetChannelLine, verdictWord };
87
+ export type { BuildParams, BuiltRequest, Operation, OutputKind, QueryValue };
package/dist/helpers.js CHANGED
@@ -157,7 +157,15 @@ function isProfileAllowedForStandard(standard, profile) {
157
157
  const allowed = profilesForStandard(standard);
158
158
  return allowed.length === 0 || allowed.includes(profile);
159
159
  }
160
- var LIVE_VALIDATE_FORMATS = ["auto", "cii", "ubl"];
160
+ var LIVE_VALIDATE_FORMATS = [
161
+ "auto",
162
+ "cii",
163
+ "ubl",
164
+ "fatturapa",
165
+ "facturae",
166
+ "eslog",
167
+ "poland_ksef_fa3"
168
+ ];
161
169
  var LIVE_PARSE_FORMATS = ["auto", "cii", "ubl"];
162
170
  var LIVE_CONVERT_SOURCE_FORMATS = [
163
171
  "auto",
@@ -176,8 +184,51 @@ var LIVE_CONVERT_TARGET_FORMATS = [
176
184
  "xrechnung",
177
185
  "peppol-bis"
178
186
  ];
187
+
188
+ // src/verdict.ts
189
+ var DEPTH_NOT_STATED = "check depth not stated";
190
+ var FRANCE_CTC_BLOCKING_FINDING_RULE_ID = "FRANCE_CTC_FINDINGS_BLOCK_TRANSMISSION";
191
+ var CONVERT_PDF_LINE = "The PDF is the one sent, with only its annotation flags normalised for PDF/A, when its embedded XML already is the target: that XML was checked and the PDF container was not. Otherwise it is that PDF re-wrapped around the converted XML, returned only after veraPDF passed it against PDF/A-3b. With a test key the PDF is watermarked last, after any veraPDF check. Detail: https://docs.beliq.eu/api-reference/convert/#a-pdf-sent-for-a-zugferd-or-factur-x-target";
192
+ function verdictWord(result) {
193
+ if (result.verified === false) return "NOT VALIDATED";
194
+ return result.valid ? "VALID" : "INVALID";
195
+ }
196
+ function checkDepth(result) {
197
+ return result.verificationBadgeLabel ?? DEPTH_NOT_STATED;
198
+ }
199
+ function franceBlockingRuleIds(result) {
200
+ return result.franceCtcBlockingRuleIds ?? [];
201
+ }
202
+ function franceBlockLines(result) {
203
+ const ids = franceBlockingRuleIds(result);
204
+ if (ids.length === 0) return [];
205
+ const entry = (result.warnings ?? []).find((w) => w.ruleId === FRANCE_CTC_BLOCKING_FINDING_RULE_ID);
206
+ const idLine = `France CTC blocking rule ids: ${ids.join(", ")}`;
207
+ if (!entry) return [idLine];
208
+ const named = new Set(entry.message.split(/[^A-Za-z0-9_-]+/));
209
+ return ids.every((id) => named.has(id)) ? [entry.message] : [entry.message, idLine];
210
+ }
211
+ function printable(name) {
212
+ return name.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}"]/gu, "?");
213
+ }
214
+ function pdfInputLine(result) {
215
+ const pdf = result.pdfInput;
216
+ if (!pdf) return void 0;
217
+ const name = pdf.attachmentName ? ` "${printable(pdf.attachmentName)}"` : "";
218
+ const others = pdf.attachmentCandidates > 1 ? ` ${pdf.attachmentCandidates} embedded files could be taken for the invoice, and nothing compared them.` : "";
219
+ return `PDF input: the verdict is about the embedded XML${name} (found by ${pdf.attachmentFoundBy}). The PDF itself was not checked.${others}`;
220
+ }
221
+ function rulesetChannelLine(result) {
222
+ if (!result.rulesetChannel) return void 0;
223
+ const fellBack = result.rulesetFellBack ? ", which had nothing to reach, so the latest ruleset ran" : "";
224
+ const sunset = result.rulesetSunsetsOn ? `; the retained ruleset is served until ${result.rulesetSunsetsOn}` : "";
225
+ return `Ruleset channel: ${result.rulesetChannel}${fellBack}${sunset}`;
226
+ }
179
227
  export {
228
+ CONVERT_PDF_LINE,
180
229
  DEFAULT_BASE_URL,
230
+ DEPTH_NOT_STATED,
231
+ FRANCE_CTC_BLOCKING_FINDING_RULE_ID,
181
232
  LIVE_CONVERT_SOURCE_FORMATS,
182
233
  LIVE_CONVERT_TARGET_FORMATS,
183
234
  LIVE_GENERATE_PRESETS,
@@ -187,12 +238,18 @@ export {
187
238
  LIVE_PROFILES_BY_STANDARD,
188
239
  LIVE_VALIDATE_FORMATS,
189
240
  buildRequest,
241
+ checkDepth,
190
242
  compactQuery,
191
243
  decodeUtf8,
244
+ franceBlockLines,
245
+ franceBlockingRuleIds,
192
246
  isPlainObject,
193
247
  isProfileAllowedForStandard,
194
248
  mergeDeep,
249
+ pdfInputLine,
195
250
  profilesForStandard,
251
+ rulesetChannelLine,
196
252
  sniffContentType,
197
- toBytes
253
+ toBytes,
254
+ verdictWord
198
255
  };
package/dist/index.cjs CHANGED
@@ -246,7 +246,15 @@ function isProfileAllowedForStandard(standard, profile) {
246
246
  const allowed = profilesForStandard(standard);
247
247
  return allowed.length === 0 || allowed.includes(profile);
248
248
  }
249
- var LIVE_VALIDATE_FORMATS = ["auto", "cii", "ubl"];
249
+ var LIVE_VALIDATE_FORMATS = [
250
+ "auto",
251
+ "cii",
252
+ "ubl",
253
+ "fatturapa",
254
+ "facturae",
255
+ "eslog",
256
+ "poland_ksef_fa3"
257
+ ];
250
258
  var LIVE_PARSE_FORMATS = ["auto", "cii", "ubl"];
251
259
  var LIVE_CONVERT_SOURCE_FORMATS = [
252
260
  "auto",
@@ -366,6 +374,16 @@ function parseRulesetArtifacts(headers) {
366
374
  return void 0;
367
375
  }
368
376
  }
377
+ function parseLostElements(headers) {
378
+ const raw = headers.get("x-lost-elements");
379
+ if (!raw) return void 0;
380
+ try {
381
+ const parsed = JSON.parse(raw);
382
+ return Array.isArray(parsed) ? parsed : void 0;
383
+ } catch {
384
+ return void 0;
385
+ }
386
+ }
369
387
  function generateMeta(headers) {
370
388
  return {
371
389
  schematronVersion: headers.get("x-schematron-version") ?? void 0,
@@ -377,22 +395,13 @@ function generateMeta(headers) {
377
395
  };
378
396
  }
379
397
  function convertMeta(headers) {
380
- let lostElements;
381
- const lostRaw = headers.get("x-lost-elements");
382
- if (lostRaw) {
383
- try {
384
- const parsed = JSON.parse(lostRaw);
385
- if (Array.isArray(parsed)) lostElements = parsed.map(String);
386
- } catch {
387
- }
388
- }
389
398
  const countRaw = headers.get("x-lost-elements-count");
390
399
  return {
391
400
  sourceFormat: headers.get("x-source-format") ?? void 0,
392
401
  targetFormat: headers.get("x-target-format") ?? void 0,
393
402
  profileDetected: headers.get("x-profile-detected") ?? void 0,
394
403
  lostElementsCount: countRaw != null ? Number(countRaw) : void 0,
395
- lostElements,
404
+ lostElements: parseLostElements(headers),
396
405
  conversionTools: headers.get("x-conversion-tools") ?? void 0,
397
406
  livemode: livemodeHeader(headers)
398
407
  };
@@ -425,7 +434,7 @@ var Beliq = class {
425
434
  async me() {
426
435
  return this.#json({ operation: "me" });
427
436
  }
428
- /** Generate a compliant e-invoice from an EN 16931 object. */
437
+ /** Generate an e-invoice from an EN 16931 object. */
429
438
  async generate(input) {
430
439
  const res = await send(
431
440
  this.#config,
@@ -460,7 +469,7 @@ var Beliq = class {
460
469
  meta
461
470
  };
462
471
  }
463
- /** Validate a document against authority-pinned rules. */
472
+ /** Validate a document. The result names the rules that ran and, in `verificationBadgeLabel` when the API states one, the check depth. */
464
473
  async validate(document, options = {}) {
465
474
  return this.#json({
466
475
  operation: "validate",