@beliq/sdk 0.4.2 → 0.4.5

package/CHANGELOG.md

@@ -4,6 +4,67 @@
 resolves 0.4.x and never reaches 0.5.0. Additive spec syncs ship as patches for
 that reason, and a minor is reserved for a change that needs consumers to opt in.
 
+## 0.4.5 - 2026-10-03
+
+- `LIVE_GENERATE_STANDARDS` carries all eight standards `POST /v1/generate`
+  accepts, where it had carried four. The four added are the national XSD
+  formats: `fatturapa`, `facturae`, `eslog` and `ksef`. Each is Schema-checked,
+  meaning structure only and no business rules, because its authority publishes
+  no machine-readable rule pack, and `GET /v1/rulesets` carries the badge.
+  `LIVE_PROFILES_BY_STANDARD` gains the one profile each allows: `ordinaria`
+  for `fatturapa` and `facturae`, `eracun` for `eslog`, `fa3` for `ksef`. The
+  map stays narrower than the engine in one place, the Factur-X `minimum` and
+  `basic` profiles, for FNFE-MPE source gating. `LIVE_GENERATE_PRESETS` is
+  unchanged at five entries: it mirrors what beliq.eu's own generator offers.
+- The vendored `openapi.json` carries the corrected `/v1/validate` description.
+  It had said that matching a verdict's `rulesetArtifacts` rows against the
+  `GET /v1/rulesets` catalog covers publicly-supported formats only, and that a
+  national format's components are kept off the catalog. Both were false: the
+  catalog publishes every format beliq carries and the component rows each
+  ruleset is built from.
+
+## 0.4.4 - 2026-10-02
+
+- Invoices carry additional supporting documents (BG-24) as
+  `supportingDocuments`, at most 50 of them: `id` (BT-122), which BR-52
+  requires, `description` (BT-123), `externalLocation` (BT-124) and
+  `attachment` (BT-125) with the file as base64 `content`, its `mimeCode` and
+  its `filename`. An entry can carry a URL, a file, both or neither. Output is
+  a CII `ram:AdditionalReferencedDocument` with type code 916, from the
+  Factur-X EN16931 profile up, and a UBL `cac:AdditionalDocumentReference`
+  with no document type code (UBL-SR-43 admits none here). Factur-X MINIMUM,
+  BASIC_WL and BASIC have no slot for it and drop it after the same checks, as
+  do the fatturapa, facturae, eslog and ksef targets. Content that is not
+  base64, or that decodes to no bytes, is a 400. On XRechnung BR-DE-22 refuses
+  two attachments sharing a `filename`, and DE-R-022 does the same on Peppol
+  BIS between two German parties; both compare names as written, so names
+  differing only in case pass. An attachment counts toward the 1 MiB body
+  limit of `POST /v1/generate`, and base64 takes four bytes for every three of
+  the file.
+- The `format` query parameter of `/v1/parse` now describes itself: it is
+  checked against the allowed values and otherwise ignored, because the syntax
+  is always read from the document itself. `/v1/parse` shares the invoice
+  shape and fills neither `supportingDocuments` nor the fields 0.4.3 added.
+
+## 0.4.3 - 2026-09-26
+
+Never published to npm: the release job refused the tag, because `package.json`
+read 0.4.2 at the commit it pointed at. 0.4.4 is the first release that carries
+the changes below.
+
+- Invoices can name a payee (BG-10) and a tax representative (BG-11), as
+  `payee` and `taxRepresentative`, and state `paidAmount` (BT-113) and
+  `roundingAmount` (BT-114), from which the API derives the amount due
+  (BT-115). A payee with the seller's name or registration identifier is a
+  400. With a payee, UBL output writes `paymentMeans.creditorId` (BT-90) on
+  the payee rather than the seller.
+- `typeCode` (BT-3) sets the document type code within `documentType`, such as
+  `384` for a corrected invoice. A code from the other document type's half of
+  BR-CL-01 is a 400, and the fatturapa, facturae and eslog targets answer 422
+  `DOCUMENT_TYPE_STANDARD_MISMATCH`.
+- `precedingInvoiceReference` (BG-3) is written on invoices as well as credit
+  notes. `/v1/parse` shares the invoice shape and fills none of the new fields.
+
 ## 0.4.2 - 2026-09-23
 
 - Invoices carry allowances and charges at document level (BG-20, BG-21) and
@@ -63,7 +124,7 @@ that reason, and a minor is reserved for a change that needs consumers to opt in
 - A per-attempt deadline, and transient failures are retried.
 - The transport defaults are exported from the package entry point, so a caller
   can read the timeout and retry values the SDK ships with.
-- The vendored `openapi.json` is asserted byte-identical to what beliq-api
+- The vendored `openapi.json` is asserted byte-identical to what the API
   generates, and the drift check is directional in the code rather than only in
   its comment. Ten Peppol emit error codes, the 413 responses, the verdict
   verification tier and the `/v1/me` response shape are typed; two error codes

package/README.md

@@ -171,7 +171,7 @@ try {
 `src/generated/schema.ts` is generated from a vendored copy of the published OpenAPI spec (`openapi.json`).
 
 ```bash
-npm run sync:spec      # refresh openapi.json from beliq-api / the live spec
+npm run sync:spec      # refresh openapi.json from the live spec (or BELIQ_OPENAPI_PATH)
 npm run gen:types      # regenerate src/generated/schema.ts
 npm run openapi:check  # CI drift guard: fails if the generated types are stale
 ```

package/dist/{constants-BZuNzqbV.d.cts → constants-DFGl_MXW.d.cts}

@@ -20,7 +20,13 @@ declare const DEFAULT_BASE_URL = "https://api.beliq.eu";
 declare const DEFAULT_TIMEOUT_MS = 90000;
 /** Extra attempts after the first, for 429 / 502 / 503 only. */
 declare const DEFAULT_MAX_RETRIES = 3;
-declare const LIVE_GENERATE_STANDARDS: readonly ["xrechnung", "zugferd", "facturx", "peppol-bis"];
+/**
+ * Every `standard` POST /v1/generate accepts, in the order its enum lists them.
+ * The four national formats are Schema-checked: their authority publishes a
+ * schema and no machine-readable business rules, so beliq checks structure and
+ * says so. GET /v1/rulesets carries each one's badge.
+ */
+declare const LIVE_GENERATE_STANDARDS: readonly ["xrechnung", "zugferd", "facturx", "peppol-bis", "fatturapa", "facturae", "eslog", "ksef"];
 /** A named generate target: the API `standard` plus the `profile`/`facturxProfile`/`output` it needs. */
 interface GeneratePreset {
     id: string;
@@ -50,16 +56,15 @@ declare const LIVE_PROFILES: readonly ["basicwl", "en16931", "extended", "extend
  *
  * `profile` is not a free enum: the engine pins it per standard and answers a
  * pair outside the table with `422 PROFILE_STANDARD_MISMATCH`
- * (beliq-engine `app/routes/generate.py`, ALLOWED_PROFILES_FOR_STANDARD). A
+ * (the engine's ALLOWED_PROFILES_FOR_STANDARD table). A
  * surface that offers one flat profile list therefore offers values that cannot
  * succeed: none of the Factur-X granularity values is legal for `xrechnung` or
  * `peppol-bis`, and `extended-ctc-fr` is the AFNOR XP Z12-012 France CTC overlay
  * with no ZUGFeRD-branded counterpart.
  *
- * Narrower than the engine's own table in two places, both deliberate: the
- * `minimum` and `basic` Factur-X profiles are engine-supported but withheld
- * (FNFE-MPE source gating, mirroring beliq-types SUPPORTED_FACTURX_PROFILE_IDS),
- * and the standards outside LIVE_GENERATE_STANDARDS are absent entirely.
+ * It carries every standard the API accepts. It stays narrower than the
+ * engine's table in one place: the `minimum` and `basic` Factur-X profiles are
+ * engine-supported but not offered here (FNFE-MPE source gating).
  *
  * `scripts/check-profile-drift.mjs` compares this against the engine's table.
  */
@@ -68,6 +73,10 @@ declare const LIVE_PROFILES_BY_STANDARD: {
     readonly 'peppol-bis': readonly ["peppol", "romania-ro-cius", "netherlands-nlcius"];
     readonly zugferd: readonly ["basicwl", "en16931", "extended"];
     readonly facturx: readonly ["basicwl", "en16931", "extended", "extended-ctc-fr"];
+    readonly fatturapa: readonly ["ordinaria"];
+    readonly facturae: readonly ["ordinaria"];
+    readonly eslog: readonly ["eracun"];
+    readonly ksef: readonly ["fa3"];
 };
 /** The profiles a caller may choose for `standard`; empty for an unknown standard. */
 declare function profilesForStandard(standard: string): readonly string[];

package/dist/{constants-BZuNzqbV.d.ts → constants-DFGl_MXW.d.ts}

@@ -20,7 +20,13 @@ declare const DEFAULT_BASE_URL = "https://api.beliq.eu";
 declare const DEFAULT_TIMEOUT_MS = 90000;
 /** Extra attempts after the first, for 429 / 502 / 503 only. */
 declare const DEFAULT_MAX_RETRIES = 3;
-declare const LIVE_GENERATE_STANDARDS: readonly ["xrechnung", "zugferd", "facturx", "peppol-bis"];
+/**
+ * Every `standard` POST /v1/generate accepts, in the order its enum lists them.
+ * The four national formats are Schema-checked: their authority publishes a
+ * schema and no machine-readable business rules, so beliq checks structure and
+ * says so. GET /v1/rulesets carries each one's badge.
+ */
+declare const LIVE_GENERATE_STANDARDS: readonly ["xrechnung", "zugferd", "facturx", "peppol-bis", "fatturapa", "facturae", "eslog", "ksef"];
 /** A named generate target: the API `standard` plus the `profile`/`facturxProfile`/`output` it needs. */
 interface GeneratePreset {
     id: string;
@@ -50,16 +56,15 @@ declare const LIVE_PROFILES: readonly ["basicwl", "en16931", "extended", "extend
  *
  * `profile` is not a free enum: the engine pins it per standard and answers a
  * pair outside the table with `422 PROFILE_STANDARD_MISMATCH`
- * (beliq-engine `app/routes/generate.py`, ALLOWED_PROFILES_FOR_STANDARD). A
+ * (the engine's ALLOWED_PROFILES_FOR_STANDARD table). A
  * surface that offers one flat profile list therefore offers values that cannot
  * succeed: none of the Factur-X granularity values is legal for `xrechnung` or
  * `peppol-bis`, and `extended-ctc-fr` is the AFNOR XP Z12-012 France CTC overlay
  * with no ZUGFeRD-branded counterpart.
  *
- * Narrower than the engine's own table in two places, both deliberate: the
- * `minimum` and `basic` Factur-X profiles are engine-supported but withheld
- * (FNFE-MPE source gating, mirroring beliq-types SUPPORTED_FACTURX_PROFILE_IDS),
- * and the standards outside LIVE_GENERATE_STANDARDS are absent entirely.
+ * It carries every standard the API accepts. It stays narrower than the
+ * engine's table in one place: the `minimum` and `basic` Factur-X profiles are
+ * engine-supported but not offered here (FNFE-MPE source gating).
  *
  * `scripts/check-profile-drift.mjs` compares this against the engine's table.
  */
@@ -68,6 +73,10 @@ declare const LIVE_PROFILES_BY_STANDARD: {
     readonly 'peppol-bis': readonly ["peppol", "romania-ro-cius", "netherlands-nlcius"];
     readonly zugferd: readonly ["basicwl", "en16931", "extended"];
     readonly facturx: readonly ["basicwl", "en16931", "extended", "extended-ctc-fr"];
+    readonly fatturapa: readonly ["ordinaria"];
+    readonly facturae: readonly ["ordinaria"];
+    readonly eslog: readonly ["eracun"];
+    readonly ksef: readonly ["fa3"];
 };
 /** The profiles a caller may choose for `standard`; empty for an unknown standard. */
 declare function profilesForStandard(standard: string): readonly string[];

package/dist/helpers.cjs

@@ -165,7 +165,16 @@ function buildRequest(params) {
 
 // src/constants.ts
 var DEFAULT_BASE_URL = "https://api.beliq.eu";
-var LIVE_GENERATE_STANDARDS = ["xrechnung", "zugferd", "facturx", "peppol-bis"];
+var LIVE_GENERATE_STANDARDS = [
+  "xrechnung",
+  "zugferd",
+  "facturx",
+  "peppol-bis",
+  "fatturapa",
+  "facturae",
+  "eslog",
+  "ksef"
+];
 var LIVE_GENERATE_PRESETS = [
   { id: "xrechnung", label: "XRechnung", standard: "xrechnung", output: "xml" },
   { id: "factur-x", label: "Factur-X", standard: "facturx", output: "pdf", facturxProfile: "en16931" },
@@ -178,7 +187,11 @@ var LIVE_PROFILES_BY_STANDARD = {
   xrechnung: ["xrechnung"],
   "peppol-bis": ["peppol", "romania-ro-cius", "netherlands-nlcius"],
   zugferd: ["basicwl", "en16931", "extended"],
-  facturx: ["basicwl", "en16931", "extended", "extended-ctc-fr"]
+  facturx: ["basicwl", "en16931", "extended", "extended-ctc-fr"],
+  fatturapa: ["ordinaria"],
+  facturae: ["ordinaria"],
+  eslog: ["eracun"],
+  ksef: ["fa3"]
 };
 function profilesForStandard(standard) {
   return LIVE_PROFILES_BY_STANDARD[standard] ?? [];

package/dist/helpers.d.cts

@@ -1,5 +1,5 @@
-import { P as PlainObject } from './constants-BZuNzqbV.cjs';
-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-BZuNzqbV.cjs';
+import { P as PlainObject } from './constants-DFGl_MXW.cjs';
+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';
 
 type Operation = 'me' | 'generate' | 'validate' | 'parse' | 'convert';
 /** 'json' => parse the `{ success, data }` envelope; 'binary' => return raw bytes. */

package/dist/helpers.d.ts

@@ -1,5 +1,5 @@
-import { P as PlainObject } from './constants-BZuNzqbV.js';
-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-BZuNzqbV.js';
+import { P as PlainObject } from './constants-DFGl_MXW.js';
+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';
 
 type Operation = 'me' | 'generate' | 'validate' | 'parse' | 'convert';
 /** 'json' => parse the `{ success, data }` envelope; 'binary' => return raw bytes. */

package/dist/helpers.js

@@ -122,7 +122,16 @@ function buildRequest(params) {
 
 // src/constants.ts
 var DEFAULT_BASE_URL = "https://api.beliq.eu";
-var LIVE_GENERATE_STANDARDS = ["xrechnung", "zugferd", "facturx", "peppol-bis"];
+var LIVE_GENERATE_STANDARDS = [
+  "xrechnung",
+  "zugferd",
+  "facturx",
+  "peppol-bis",
+  "fatturapa",
+  "facturae",
+  "eslog",
+  "ksef"
+];
 var LIVE_GENERATE_PRESETS = [
   { id: "xrechnung", label: "XRechnung", standard: "xrechnung", output: "xml" },
   { id: "factur-x", label: "Factur-X", standard: "facturx", output: "pdf", facturxProfile: "en16931" },
@@ -135,7 +144,11 @@ var LIVE_PROFILES_BY_STANDARD = {
   xrechnung: ["xrechnung"],
   "peppol-bis": ["peppol", "romania-ro-cius", "netherlands-nlcius"],
   zugferd: ["basicwl", "en16931", "extended"],
-  facturx: ["basicwl", "en16931", "extended", "extended-ctc-fr"]
+  facturx: ["basicwl", "en16931", "extended", "extended-ctc-fr"],
+  fatturapa: ["ordinaria"],
+  facturae: ["ordinaria"],
+  eslog: ["eracun"],
+  ksef: ["fa3"]
 };
 function profilesForStandard(standard) {
   return LIVE_PROFILES_BY_STANDARD[standard] ?? [];

package/dist/index.cjs

@@ -211,7 +211,16 @@ function errorFromResponse(status, bytes) {
 var DEFAULT_BASE_URL = "https://api.beliq.eu";
 var DEFAULT_TIMEOUT_MS = 9e4;
 var DEFAULT_MAX_RETRIES = 3;
-var LIVE_GENERATE_STANDARDS = ["xrechnung", "zugferd", "facturx", "peppol-bis"];
+var LIVE_GENERATE_STANDARDS = [
+  "xrechnung",
+  "zugferd",
+  "facturx",
+  "peppol-bis",
+  "fatturapa",
+  "facturae",
+  "eslog",
+  "ksef"
+];
 var LIVE_GENERATE_PRESETS = [
   { id: "xrechnung", label: "XRechnung", standard: "xrechnung", output: "xml" },
   { id: "factur-x", label: "Factur-X", standard: "facturx", output: "pdf", facturxProfile: "en16931" },
@@ -224,7 +233,11 @@ var LIVE_PROFILES_BY_STANDARD = {
   xrechnung: ["xrechnung"],
   "peppol-bis": ["peppol", "romania-ro-cius", "netherlands-nlcius"],
   zugferd: ["basicwl", "en16931", "extended"],
-  facturx: ["basicwl", "en16931", "extended", "extended-ctc-fr"]
+  facturx: ["basicwl", "en16931", "extended", "extended-ctc-fr"],
+  fatturapa: ["ordinaria"],
+  facturae: ["ordinaria"],
+  eslog: ["eracun"],
+  ksef: ["fa3"]
 };
 function profilesForStandard(standard) {
   return LIVE_PROFILES_BY_STANDARD[standard] ?? [];
@@ -332,6 +345,11 @@ async function send(config, req) {
 
 // src/client.ts
 var TEST_KEY_PREFIX = "blq_test_";
+function trimTrailingSlashes(url) {
+  let end = url.length;
+  while (end > 0 && url[end - 1] === "/") end--;
+  return url.slice(0, end);
+}
 function livemodeHeader(headers) {
   const raw = headers.get("x-beliq-livemode");
   if (raw === "true") return true;
@@ -396,7 +414,7 @@ var Beliq = class {
     this.livemode = !options.apiKey.startsWith(TEST_KEY_PREFIX);
     this.#config = {
       apiKey: options.apiKey,
-      baseUrl: (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      baseUrl: trimTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL),
       auth: options.auth ?? "header",
       fetchImpl,
       timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,