@beliq/sdk 0.7.3 → 0.7.4

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,24 @@
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.7.4 - 2026-11-16
8
+
9
+ - A `429` carrying `DOCUMENT_CEILING_REACHED` is thrown at once and not
10
+ retried, like `QUOTA_EXCEEDED`, and `retryClass` returns `none` for it,
11
+ where it returned `count`. The API sends it when an org on usage billing
12
+ reaches its extra-document cap, or the ceiling above its monthly quota,
13
+ with a `Retry-After` to the end of the billing window. Raising the cap or
14
+ the plan clears it sooner. Before, the client retried it up to
15
+ `maxRetries` times.
16
+ - `ApiErrorCode` gains `DOCUMENT_CEILING_REACHED`, and the four admission
17
+ codes of the API document 0.27.0: `DOCUMENT_PROFILE_NOT_ACCEPTED`,
18
+ `FLOW_OUTSIDE_FRENCH_PERIMETER`, `RECIPIENT_ADDRESS_INVALID` and
19
+ `SEND_CANNOT_COMPOSE_FOR_NETWORK`.
20
+ - The README and the `package.json` description open with one sentence on
21
+ what beliq is.
22
+ - The vendored `openapi.json` is document `0.28.1` of the API, up from
23
+ `0.26.0`.
24
+
7
25
  ## 0.7.3 - 2026-11-08
8
26
 
9
27
  - `retryClass(error)` says how the client's retry loop treats a failure:
@@ -328,8 +346,8 @@ the changes below.
328
346
  currency) are typed on the invoice.
329
347
  - A scheduled ruleset change reports its capabilities.
330
348
  - The README's quick-start invoice is one the API accepts as-is.
331
- - An em-dash scrub gate runs over the whole tree before publish, and the
332
- release workflow carries job timeouts and refuses a tag that is not on `main`.
349
+ - The release workflow carries job timeouts and refuses a tag that is not on
350
+ `main`.
333
351
  - The `js-yaml` override floor is raised above GHSA-2883-xcg3-v3hh.
334
352
 
335
353
  ## 0.3.1 - 2026-09-02
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # @beliq/sdk
2
2
 
3
+ beliq is the platform for European e-invoicing: one API to generate, validate, convert and parse e-invoices, with the rule pack, version and check depth on its verdicts.
4
+
3
5
  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
6
 
5
7
  beliq produces and checks the document. Transmission (Peppol, plateforme agréée, KSeF, SDI), archiving, and tax-authority reporting stay with your access point.
@@ -115,7 +117,7 @@ numbers.
115
117
  | `503` `ENGINE_UNAVAILABLE`, and any other `502` or `503` with a beliq error code | up to `maxRetries` times |
116
118
  | A certificate that fails verification: a `cause.code` from Node's [X509 certificate error codes](https://nodejs.org/api/tls.html#x509-certificate-error-codes), or `ERR_TLS_CERT_ALTNAME_INVALID` | never |
117
119
  | Any other thrown error, such as a connection lost after the request was sent, or an OpenSSL error (`ERR_SSL_*`), which can come after the send too | up to `maxRetries` times |
118
- | `429` `QUOTA_EXCEEDED`, `504`, this client's own timeout, and every other status | never |
120
+ | `429` `QUOTA_EXCEEDED` or `DOCUMENT_CEILING_REACHED`, `504`, this client's own timeout, and every other status | never |
119
121
 
120
122
  Every wait follows the server's `Retry-After` in full, plus up to 250 ms of
121
123
  jitter. Without one, the client backs off exponentially from 500 ms with jitter,
@@ -212,10 +214,11 @@ What a retry costs:
212
214
  mean the work is still running on beliq's side, and a retry runs the same
213
215
  document again from the start, so it would likely run out of time again.
214
216
 
215
- A `429` carrying `QUOTA_EXCEEDED` is not retried either. `RATE_LIMITED` and
216
- `ACCOUNT_THROTTLED` clear on their own, but a spent monthly allowance only returns
217
- when your billing window turns, so the error is raised straight away and names the
218
- cause instead of sleeping against it.
217
+ A `429` carrying `QUOTA_EXCEEDED` or `DOCUMENT_CEILING_REACHED` is not retried
218
+ either. `RATE_LIMITED` and `ACCOUNT_THROTTLED` clear on their own, but a spent
219
+ monthly allowance, or the extra-document ceiling above it, does not return before
220
+ your billing window turns unless you raise your cap or your plan. So the error is
221
+ raised straight away and names the cause instead of sleeping against it.
219
222
 
220
223
  The default deadline is generous because beliq runs the full Schematron rule set
221
224
  over each document, and a generate or validate can legitimately take tens of
@@ -313,7 +316,6 @@ npm install
313
316
  npm run build # tsup: dual ESM + CJS + d.ts
314
317
  npm run typecheck
315
318
  npm run lint
316
- npm run scrub:check # no em-dash in any tracked file
317
319
  npm test # unit tests (no network)
318
320
  BELIQ_API_KEY=blq_xxx npm run test:integration # hits the live API; draws quota
319
321
  ```
@@ -1,6 +1,6 @@
1
- import { P as PlainObject } from './types-B-aV1djO.cjs';
1
+ import { P as PlainObject } from './types-u5eeJLoG.cjs';
2
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-B-aV1djO.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-u5eeJLoG.cjs';
4
4
 
5
5
  type Operation = 'me' | 'generate' | 'validate' | 'parse' | 'convert';
6
6
  /** 'json' => parse the `{ success, data }` envelope; 'binary' => return raw bytes. */
package/dist/helpers.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { P as PlainObject } from './types-B-aV1djO.js';
1
+ import { P as PlainObject } from './types-u5eeJLoG.js';
2
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-B-aV1djO.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-u5eeJLoG.js';
4
4
 
5
5
  type Operation = 'me' | 'generate' | 'validate' | 'parse' | 'convert';
6
6
  /** 'json' => parse the `{ success, data }` envelope; 'binary' => return raw bytes. */
package/dist/index.cjs CHANGED
@@ -299,7 +299,10 @@ var LIVE_CONVERT_TARGET_FORMATS = [
299
299
  ];
300
300
 
301
301
  // src/transport.ts
302
- var QUOTA_EXHAUSTED_CODE = "QUOTA_EXCEEDED";
302
+ var QUOTA_EXHAUSTED_CODES = /* @__PURE__ */ new Set([
303
+ "QUOTA_EXCEEDED",
304
+ "DOCUMENT_CEILING_REACHED"
305
+ ]);
303
306
  var DATABASE_UNAVAILABLE_CODE = "DATABASE_UNAVAILABLE";
304
307
  var BEFORE_SEND_CODES = /* @__PURE__ */ new Set([
305
308
  "ECONNREFUSED",
@@ -343,7 +346,7 @@ function isCertificateFailure(code) {
343
346
  return CERTIFICATE_ERROR_CODES.has(code) || code === "ERR_TLS_CERT_ALTNAME_INVALID";
344
347
  }
345
348
  function classifyStatus(status, code) {
346
- if (status === 429) return code === QUOTA_EXHAUSTED_CODE ? "none" : "count";
349
+ if (status === 429) return code !== void 0 && QUOTA_EXHAUSTED_CODES.has(code) ? "none" : "count";
347
350
  if (status !== 502 && status !== 503) return "none";
348
351
  if (!code) return "budget";
349
352
  return status === 503 && code === DATABASE_UNAVAILABLE_CODE ? "budget" : "count";
package/dist/index.d.cts CHANGED
@@ -1,6 +1,6 @@
1
- import { A as AccountInfo, S as Standard, I as Invoice, n as GenerateProfile, F as FacturxProfile, V as ValidationResult, R as RulesetArtifact, a as DocumentInput, o as ValidateFormat, q as RulesetChannel, r as ParseFormat, u as ParseResult, C as ConvertTargetFormat, v as ConvertSourceFormat, w as ApiErrorCode } from './types-B-aV1djO.cjs';
1
+ import { A as AccountInfo, S as Standard, I as Invoice, n as GenerateProfile, F as FacturxProfile, V as ValidationResult, R as RulesetArtifact, a as DocumentInput, o as ValidateFormat, q as RulesetChannel, r as ParseFormat, u as ParseResult, C as ConvertTargetFormat, v as ConvertSourceFormat, w as ApiErrorCode } from './types-u5eeJLoG.cjs';
2
2
  import { PlainObject } from './helpers.cjs';
3
- export { x as ApiError, D as DEFAULT_BASE_URL, y as DEFAULT_MAX_RETRIES, z as DEFAULT_RETRY_BUDGET_MS, B as DEFAULT_TIMEOUT_MS, E as GenerateBody, G as GeneratePreset, H as GenerateResponse, 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, J as ParseWarning, K as ParseWarningCode, M as Severity, N as ValidationFormat, O as ValidationIssue, l as isProfileAllowedForStandard, p as profilesForStandard } from './types-B-aV1djO.cjs';
3
+ export { x as ApiError, D as DEFAULT_BASE_URL, y as DEFAULT_MAX_RETRIES, z as DEFAULT_RETRY_BUDGET_MS, B as DEFAULT_TIMEOUT_MS, E as GenerateBody, G as GeneratePreset, H as GenerateResponse, 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, J as ParseWarning, K as ParseWarningCode, M as Severity, N as ValidationFormat, O as ValidationIssue, l as isProfileAllowedForStandard, p as profilesForStandard } from './types-u5eeJLoG.cjs';
4
4
 
5
5
  interface BeliqOptions {
6
6
  /** API key from the beliq dashboard (API Keys). */
@@ -22,10 +22,11 @@ interface BeliqOptions {
22
22
  timeoutMs?: number;
23
23
  /**
24
24
  * Extra attempts after the first for the failures retried by count (default
25
- * 3): a 429 other than `QUOTA_EXCEEDED`, a 502 or 503 carrying any beliq error
26
- * code but a 503 `DATABASE_UNAVAILABLE`, and any thrown error but a connection
27
- * that could not be opened, such as a connection lost after the request was
28
- * sent. When you set it, it bounds every retry, so 0 disables retrying.
25
+ * 3): a 429 other than `QUOTA_EXCEEDED` and `DOCUMENT_CEILING_REACHED`, a
26
+ * 502 or 503 carrying any beliq error code but a 503 `DATABASE_UNAVAILABLE`,
27
+ * and any thrown error but a connection that could not be opened, such as a
28
+ * connection lost after the request was sent. When you set it, it bounds
29
+ * every retry, so 0 disables retrying.
29
30
  */
30
31
  maxRetries?: number;
31
32
  /**
@@ -221,14 +222,15 @@ declare class BeliqApiError extends Error {
221
222
  * answered, or the pod that held the connection is gone), and a connection that
222
223
  * could not be opened.
223
224
  *
224
- * `count`: retried up to `maxRetries` times. A 429 other than `QUOTA_EXCEEDED`,
225
- * since each one counts toward the account's throttle; a 502 or 503 with any
226
- * other beliq code, `ENGINE_UNAVAILABLE` included, since an engine timeout
227
- * answers that code too and a budget would run the same slow document dozens of
228
- * times; and a thrown error that may have come after the request was sent.
229
- * beliq may have run and charged that request, but it does not charge a repeat
230
- * of a charged request within 15 minutes, up to 10 repeats (beliq's own values,
231
- * which no standard sets), and every attempt sends the same bytes.
225
+ * `count`: retried up to `maxRetries` times. A 429 other than `QUOTA_EXCEEDED`
226
+ * and `DOCUMENT_CEILING_REACHED`, since each one counts toward the account's
227
+ * throttle; a 502 or 503 with any other beliq code, `ENGINE_UNAVAILABLE`
228
+ * included, since an engine timeout answers that code too and a budget would run
229
+ * the same slow document dozens of times; and a thrown error that may have come
230
+ * after the request was sent. beliq may have run and charged that request, but
231
+ * it does not charge a repeat of a charged request within 15 minutes, up to 10
232
+ * repeats (beliq's own values, which no standard sets), and every attempt sends
233
+ * the same bytes.
232
234
  *
233
235
  * `none`: not retried. A 504 and this client's own timeout mean the work may
234
236
  * still be running on beliq's side, and a repeat runs the same document again
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { A as AccountInfo, S as Standard, I as Invoice, n as GenerateProfile, F as FacturxProfile, V as ValidationResult, R as RulesetArtifact, a as DocumentInput, o as ValidateFormat, q as RulesetChannel, r as ParseFormat, u as ParseResult, C as ConvertTargetFormat, v as ConvertSourceFormat, w as ApiErrorCode } from './types-B-aV1djO.js';
1
+ import { A as AccountInfo, S as Standard, I as Invoice, n as GenerateProfile, F as FacturxProfile, V as ValidationResult, R as RulesetArtifact, a as DocumentInput, o as ValidateFormat, q as RulesetChannel, r as ParseFormat, u as ParseResult, C as ConvertTargetFormat, v as ConvertSourceFormat, w as ApiErrorCode } from './types-u5eeJLoG.js';
2
2
  import { PlainObject } from './helpers.js';
3
- export { x as ApiError, D as DEFAULT_BASE_URL, y as DEFAULT_MAX_RETRIES, z as DEFAULT_RETRY_BUDGET_MS, B as DEFAULT_TIMEOUT_MS, E as GenerateBody, G as GeneratePreset, H as GenerateResponse, 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, J as ParseWarning, K as ParseWarningCode, M as Severity, N as ValidationFormat, O as ValidationIssue, l as isProfileAllowedForStandard, p as profilesForStandard } from './types-B-aV1djO.js';
3
+ export { x as ApiError, D as DEFAULT_BASE_URL, y as DEFAULT_MAX_RETRIES, z as DEFAULT_RETRY_BUDGET_MS, B as DEFAULT_TIMEOUT_MS, E as GenerateBody, G as GeneratePreset, H as GenerateResponse, 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, J as ParseWarning, K as ParseWarningCode, M as Severity, N as ValidationFormat, O as ValidationIssue, l as isProfileAllowedForStandard, p as profilesForStandard } from './types-u5eeJLoG.js';
4
4
 
5
5
  interface BeliqOptions {
6
6
  /** API key from the beliq dashboard (API Keys). */
@@ -22,10 +22,11 @@ interface BeliqOptions {
22
22
  timeoutMs?: number;
23
23
  /**
24
24
  * Extra attempts after the first for the failures retried by count (default
25
- * 3): a 429 other than `QUOTA_EXCEEDED`, a 502 or 503 carrying any beliq error
26
- * code but a 503 `DATABASE_UNAVAILABLE`, and any thrown error but a connection
27
- * that could not be opened, such as a connection lost after the request was
28
- * sent. When you set it, it bounds every retry, so 0 disables retrying.
25
+ * 3): a 429 other than `QUOTA_EXCEEDED` and `DOCUMENT_CEILING_REACHED`, a
26
+ * 502 or 503 carrying any beliq error code but a 503 `DATABASE_UNAVAILABLE`,
27
+ * and any thrown error but a connection that could not be opened, such as a
28
+ * connection lost after the request was sent. When you set it, it bounds
29
+ * every retry, so 0 disables retrying.
29
30
  */
30
31
  maxRetries?: number;
31
32
  /**
@@ -221,14 +222,15 @@ declare class BeliqApiError extends Error {
221
222
  * answered, or the pod that held the connection is gone), and a connection that
222
223
  * could not be opened.
223
224
  *
224
- * `count`: retried up to `maxRetries` times. A 429 other than `QUOTA_EXCEEDED`,
225
- * since each one counts toward the account's throttle; a 502 or 503 with any
226
- * other beliq code, `ENGINE_UNAVAILABLE` included, since an engine timeout
227
- * answers that code too and a budget would run the same slow document dozens of
228
- * times; and a thrown error that may have come after the request was sent.
229
- * beliq may have run and charged that request, but it does not charge a repeat
230
- * of a charged request within 15 minutes, up to 10 repeats (beliq's own values,
231
- * which no standard sets), and every attempt sends the same bytes.
225
+ * `count`: retried up to `maxRetries` times. A 429 other than `QUOTA_EXCEEDED`
226
+ * and `DOCUMENT_CEILING_REACHED`, since each one counts toward the account's
227
+ * throttle; a 502 or 503 with any other beliq code, `ENGINE_UNAVAILABLE`
228
+ * included, since an engine timeout answers that code too and a budget would run
229
+ * the same slow document dozens of times; and a thrown error that may have come
230
+ * after the request was sent. beliq may have run and charged that request, but
231
+ * it does not charge a repeat of a charged request within 15 minutes, up to 10
232
+ * repeats (beliq's own values, which no standard sets), and every attempt sends
233
+ * the same bytes.
232
234
  *
233
235
  * `none`: not retried. A 504 and this client's own timeout mean the work may
234
236
  * still be running on beliq's side, and a repeat runs the same document again
package/dist/index.js CHANGED
@@ -257,7 +257,10 @@ var LIVE_CONVERT_TARGET_FORMATS = [
257
257
  ];
258
258
 
259
259
  // src/transport.ts
260
- var QUOTA_EXHAUSTED_CODE = "QUOTA_EXCEEDED";
260
+ var QUOTA_EXHAUSTED_CODES = /* @__PURE__ */ new Set([
261
+ "QUOTA_EXCEEDED",
262
+ "DOCUMENT_CEILING_REACHED"
263
+ ]);
261
264
  var DATABASE_UNAVAILABLE_CODE = "DATABASE_UNAVAILABLE";
262
265
  var BEFORE_SEND_CODES = /* @__PURE__ */ new Set([
263
266
  "ECONNREFUSED",
@@ -301,7 +304,7 @@ function isCertificateFailure(code) {
301
304
  return CERTIFICATE_ERROR_CODES.has(code) || code === "ERR_TLS_CERT_ALTNAME_INVALID";
302
305
  }
303
306
  function classifyStatus(status, code) {
304
- if (status === 429) return code === QUOTA_EXHAUSTED_CODE ? "none" : "count";
307
+ if (status === 429) return code !== void 0 && QUOTA_EXHAUSTED_CODES.has(code) ? "none" : "count";
305
308
  if (status !== 502 && status !== 503) return "none";
306
309
  if (!code) return "budget";
307
310
  return status === 503 && code === DATABASE_UNAVAILABLE_CODE ? "budget" : "count";