@beliq/sdk 0.1.1 → 0.3.0

package/dist/index.js

@@ -34,6 +34,18 @@ function toBytes(input) {
 function decodeUtf8(bytes) {
   return new TextDecoder("utf-8").decode(bytes);
 }
+function decodeBase64(input) {
+  const b64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  if (typeof atob === "function") {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+  const maybeBuffer = globalThis.Buffer;
+  if (maybeBuffer) return new Uint8Array(maybeBuffer.from(b64, "base64"));
+  throw new Error("beliq: no base64 decoder available in this runtime");
+}
 var PDF_MAGIC = [37, 80, 68, 70, 45];
 function sniffContentType(bytes) {
   const isPdf = bytes.length >= PDF_MAGIC.length && PDF_MAGIC.every((b, i) => bytes[i] === b);
@@ -72,7 +84,8 @@ function buildRequest(params) {
         path: "/v1/generate",
         jsonBody: merged,
         contentType: "application/json",
-        outputKind: "binary"
+        // JSON mode returns the seal envelope; binary mode returns the raw document body.
+        ...params.sealed ? { accept: "application/json", outputKind: "json" } : { outputKind: "binary" }
       };
     }
     case "validate": {
@@ -156,8 +169,30 @@ function errorFromResponse(status, bytes) {
 
 // src/constants.ts
 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_PRESETS = [
+  { id: "xrechnung", label: "XRechnung", standard: "xrechnung", output: "xml" },
+  { id: "factur-x", label: "Factur-X", standard: "facturx", output: "pdf", facturxProfile: "en16931" },
+  { id: "zugferd", label: "ZUGFeRD", standard: "zugferd", output: "pdf" },
+  { id: "peppol-bis", label: "Peppol BIS 3.0", standard: "peppol-bis", output: "xml" },
+  { id: "nlcius", label: "NLCIUS", standard: "peppol-bis", output: "xml", profile: "netherlands-nlcius" }
+];
 var LIVE_PROFILES = ["basicwl", "en16931", "extended", "extended-ctc-fr"];
+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"]
+};
+function profilesForStandard(standard) {
+  return LIVE_PROFILES_BY_STANDARD[standard] ?? [];
+}
+function isProfileAllowedForStandard(standard, profile) {
+  const allowed = profilesForStandard(standard);
+  return allowed.length === 0 || allowed.includes(profile);
+}
 var LIVE_VALIDATE_FORMATS = ["auto", "cii", "ubl"];
 var LIVE_PARSE_FORMATS = ["auto", "cii", "ubl"];
 var LIVE_CONVERT_SOURCE_FORMATS = [
@@ -179,6 +214,9 @@ var LIVE_CONVERT_TARGET_FORMATS = [
 ];
 
 // src/transport.ts
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503]);
+var MAX_RETRY_AFTER_MS = 3e4;
+var BACKOFF_BASE_MS = 500;
 function authHeaders(config) {
   return config.auth === "bearer" ? { Authorization: `Bearer ${config.apiKey}` } : { "X-API-Key": config.apiKey };
 }
@@ -192,26 +230,86 @@ function buildUrl(baseUrl, path, query) {
   const qs = params.toString();
   return qs ? `${baseUrl}${path}?${qs}` : `${baseUrl}${path}`;
 }
+function retryDelayMs(res, attempt) {
+  const header = res?.headers.get("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+      return Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS) + Math.random() * 250;
+    }
+  }
+  const backoff = BACKOFF_BASE_MS * 2 ** attempt;
+  return backoff + Math.random() * backoff;
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 async function send(config, req) {
   const headers = { ...authHeaders(config) };
   if (req.contentType) headers["Content-Type"] = req.contentType;
+  if (req.accept) headers["Accept"] = req.accept;
   const body = req.jsonBody !== void 0 ? JSON.stringify(req.jsonBody) : req.rawBody;
-  const res = await config.fetchImpl(buildUrl(config.baseUrl, req.path, req.query), {
-    method: req.method,
-    headers,
-    body
-  });
-  const bytes = new Uint8Array(await res.arrayBuffer());
-  if (!res.ok) throw errorFromResponse(res.status, bytes);
-  return { status: res.status, headers: res.headers, bytes };
+  const url = buildUrl(config.baseUrl, req.path, req.query);
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    const controller = new AbortController();
+    const timer = config.timeoutMs > 0 ? setTimeout(() => controller.abort(), config.timeoutMs) : void 0;
+    let res;
+    try {
+      res = await config.fetchImpl(url, {
+        method: req.method,
+        headers,
+        body,
+        signal: controller.signal
+      });
+      const bytes = new Uint8Array(await res.arrayBuffer());
+      if (res.ok) return { status: res.status, headers: res.headers, bytes };
+      lastError = errorFromResponse(res.status, bytes);
+      if (!RETRYABLE_STATUSES.has(res.status) || attempt === config.maxRetries) {
+        throw lastError;
+      }
+    } catch (err) {
+      if (err instanceof BeliqApiError && !RETRYABLE_STATUSES.has(err.status)) throw err;
+      if (controller.signal.aborted) {
+        throw new BeliqApiError(
+          `beliq: request to ${req.path} exceeded ${config.timeoutMs}ms`,
+          { status: 0, code: "TIMEOUT" }
+        );
+      }
+      lastError = err;
+      if (attempt === config.maxRetries) throw err;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    await sleep(retryDelayMs(res, attempt));
+  }
+  throw lastError;
 }
 
 // src/client.ts
+var TEST_KEY_PREFIX = "blq_test_";
+function livemodeHeader(headers) {
+  const raw = headers.get("x-beliq-livemode");
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  return void 0;
+}
+function parseRulesetArtifacts(headers) {
+  const raw = headers.get("x-ruleset-artifacts");
+  if (!raw) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function generateMeta(headers) {
   return {
     schematronVersion: headers.get("x-schematron-version") ?? void 0,
     pdfKind: headers.get("x-pdf-kind") ?? void 0,
-    outputEnvelope: headers.get("x-output-envelope") ?? void 0
+    outputEnvelope: headers.get("x-output-envelope") ?? void 0,
+    rulesetSha256: headers.get("x-ruleset-sha256") ?? void 0,
+    rulesetArtifacts: parseRulesetArtifacts(headers),
+    livemode: livemodeHeader(headers)
   };
 }
 function convertMeta(headers) {
@@ -231,22 +329,32 @@ function convertMeta(headers) {
     profileDetected: headers.get("x-profile-detected") ?? void 0,
     lostElementsCount: countRaw != null ? Number(countRaw) : void 0,
     lostElements,
-    conversionTools: headers.get("x-conversion-tools") ?? void 0
+    conversionTools: headers.get("x-conversion-tools") ?? void 0,
+    livemode: livemodeHeader(headers)
   };
 }
 var Beliq = class {
   #config;
+  /**
+   * True for a live key, false for a blq_test_ sandbox key, derived from the key
+   * prefix (the same rule the server applies). Available before any request; the
+   * per-response x-beliq-livemode header is surfaced on generate/convert meta.
+   */
+  livemode;
   constructor(options) {
     if (!options?.apiKey) throw new Error("beliq: apiKey is required");
     const fetchImpl = options.fetch ?? globalThis.fetch;
     if (typeof fetchImpl !== "function") {
       throw new Error("beliq: no global fetch available; pass options.fetch");
     }
+    this.livemode = !options.apiKey.startsWith(TEST_KEY_PREFIX);
     this.#config = {
       apiKey: options.apiKey,
       baseUrl: (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
       auth: options.auth ?? "header",
-      fetchImpl
+      fetchImpl,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES
     };
   }
   /** Account, plan, and quota context for the key. Does not consume quota. */
@@ -255,14 +363,37 @@ var Beliq = class {
   }
   /** Generate a compliant e-invoice from an EN 16931 object. */
   async generate(input) {
-    const res = await send(this.#config, buildRequest({ operation: "generate", ...input }));
+    const res = await send(
+      this.#config,
+      buildRequest({ operation: "generate", ...input, sealed: input.seal })
+    );
+    const meta = generateMeta(res.headers);
+    if (input.seal) {
+      const envelope = parseEnvelope(res.bytes);
+      if (envelope?.success === false) throw errorFromResponse(res.status, res.bytes);
+      const data = envelope?.data;
+      if (!data || data.output === void 0) {
+        throw new BeliqApiError("beliq: seal response was not a JSON envelope", {
+          status: res.status
+        });
+      }
+      const bytes = decodeBase64(data.output);
+      const contentType2 = data.contentType ?? "application/octet-stream";
+      return {
+        contentType: contentType2,
+        bytes,
+        xml: contentType2.includes("xml") ? decodeUtf8(bytes) : void 0,
+        sha256: data.sha256,
+        validationResult: data.validationResult,
+        meta
+      };
+    }
     const contentType = res.headers.get("content-type") ?? "application/octet-stream";
-    const isXml = contentType.includes("xml");
     return {
       contentType,
       bytes: res.bytes,
-      xml: isXml ? decodeUtf8(res.bytes) : void 0,
-      meta: generateMeta(res.headers)
+      xml: contentType.includes("xml") ? decodeUtf8(res.bytes) : void 0,
+      meta
     };
   }
   /** Validate a document against authority-pinned rules. */
@@ -323,10 +454,16 @@ export {
   Beliq,
   BeliqApiError,
   DEFAULT_BASE_URL,
+  DEFAULT_MAX_RETRIES,
+  DEFAULT_TIMEOUT_MS,
   LIVE_CONVERT_SOURCE_FORMATS,
   LIVE_CONVERT_TARGET_FORMATS,
+  LIVE_GENERATE_PRESETS,
   LIVE_GENERATE_STANDARDS,
   LIVE_PARSE_FORMATS,
   LIVE_PROFILES,
-  LIVE_VALIDATE_FORMATS
+  LIVE_PROFILES_BY_STANDARD,
+  LIVE_VALIDATE_FORMATS,
+  isProfileAllowedForStandard,
+  profilesForStandard
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beliq/sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Official beliq SDK: generate, validate, parse, and convert EU-compliant e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules.",
   "keywords": [
     "beliq",
@@ -72,19 +72,25 @@
     "sync:spec": "node scripts/sync-spec.mjs",
     "gen:types": "node scripts/gen-types.mjs",
     "openapi:check": "node scripts/gen-types.mjs --check",
+    "spec:drift": "node scripts/check-live-drift.mjs",
     "test": "vitest run --exclude test/integration.test.ts",
     "test:integration": "vitest run test/integration.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "check:profiles": "node --experimental-strip-types scripts/check-profile-drift.mjs"
   },
   "dependencies": {},
+  "overrides": {
+    "esbuild": "^0.28.1",
+    "js-yaml": "^4.3.1"
+  },
   "devDependencies": {
+    "@eslint/js": "^10.0.0",
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.0",
+    "eslint": "^10.0.0",
     "openapi-typescript": "^7.4.0",
     "tsup": "^8.3.0",
     "typescript": "^5.5.4",
-    "vitest": "^2.1.8"
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.0.0"
   }
 }

package/dist/constants-bWOXCmJD.d.cts

@@ -1,22 +0,0 @@
-type PlainObject = Record<string, unknown>;
-declare function isPlainObject(value: unknown): value is PlainObject;
-/** Deep-merge `source` into `target` (source wins). Arrays and scalars overwrite. */
-declare function mergeDeep(target: PlainObject, source: PlainObject): PlainObject;
-/** Drop undefined/empty entries so optional query params are omitted, not sent blank. */
-declare function compactQuery(query: PlainObject): PlainObject;
-/** Document bytes a caller may pass to validate/parse/convert. */
-type DocumentInput = string | Uint8Array | ArrayBuffer | ArrayBufferView;
-declare function toBytes(input: DocumentInput): Uint8Array;
-declare function decodeUtf8(bytes: Uint8Array): string;
-/** Sniff `application/pdf` vs `application/xml` from the leading bytes. */
-declare function sniffContentType(bytes: Uint8Array): string;
-
-declare const DEFAULT_BASE_URL = "https://api.beliq.eu";
-declare const LIVE_GENERATE_STANDARDS: readonly ["xrechnung", "zugferd", "facturx", "peppol-bis"];
-declare const LIVE_PROFILES: readonly ["basicwl", "en16931", "extended", "extended-ctc-fr"];
-declare const LIVE_VALIDATE_FORMATS: readonly ["auto", "cii", "ubl"];
-declare const LIVE_PARSE_FORMATS: readonly ["auto", "cii", "ubl"];
-declare const LIVE_CONVERT_SOURCE_FORMATS: readonly ["auto", "cii", "ubl", "zugferd", "facturx", "xrechnung", "peppol-bis"];
-declare const LIVE_CONVERT_TARGET_FORMATS: readonly ["cii", "ubl", "zugferd", "facturx", "xrechnung", "peppol-bis"];
-
-export { DEFAULT_BASE_URL as D, LIVE_CONVERT_SOURCE_FORMATS as L, type PlainObject as P, type DocumentInput as a, LIVE_CONVERT_TARGET_FORMATS as b, LIVE_GENERATE_STANDARDS as c, LIVE_PARSE_FORMATS as d, LIVE_PROFILES as e, LIVE_VALIDATE_FORMATS as f, compactQuery as g, decodeUtf8 as h, isPlainObject as i, mergeDeep as m, sniffContentType as s, toBytes as t };

package/dist/constants-bWOXCmJD.d.ts

@@ -1,22 +0,0 @@
-type PlainObject = Record<string, unknown>;
-declare function isPlainObject(value: unknown): value is PlainObject;
-/** Deep-merge `source` into `target` (source wins). Arrays and scalars overwrite. */
-declare function mergeDeep(target: PlainObject, source: PlainObject): PlainObject;
-/** Drop undefined/empty entries so optional query params are omitted, not sent blank. */
-declare function compactQuery(query: PlainObject): PlainObject;
-/** Document bytes a caller may pass to validate/parse/convert. */
-type DocumentInput = string | Uint8Array | ArrayBuffer | ArrayBufferView;
-declare function toBytes(input: DocumentInput): Uint8Array;
-declare function decodeUtf8(bytes: Uint8Array): string;
-/** Sniff `application/pdf` vs `application/xml` from the leading bytes. */
-declare function sniffContentType(bytes: Uint8Array): string;
-
-declare const DEFAULT_BASE_URL = "https://api.beliq.eu";
-declare const LIVE_GENERATE_STANDARDS: readonly ["xrechnung", "zugferd", "facturx", "peppol-bis"];
-declare const LIVE_PROFILES: readonly ["basicwl", "en16931", "extended", "extended-ctc-fr"];
-declare const LIVE_VALIDATE_FORMATS: readonly ["auto", "cii", "ubl"];
-declare const LIVE_PARSE_FORMATS: readonly ["auto", "cii", "ubl"];
-declare const LIVE_CONVERT_SOURCE_FORMATS: readonly ["auto", "cii", "ubl", "zugferd", "facturx", "xrechnung", "peppol-bis"];
-declare const LIVE_CONVERT_TARGET_FORMATS: readonly ["cii", "ubl", "zugferd", "facturx", "xrechnung", "peppol-bis"];
-
-export { DEFAULT_BASE_URL as D, LIVE_CONVERT_SOURCE_FORMATS as L, type PlainObject as P, type DocumentInput as a, LIVE_CONVERT_TARGET_FORMATS as b, LIVE_GENERATE_STANDARDS as c, LIVE_PARSE_FORMATS as d, LIVE_PROFILES as e, LIVE_VALIDATE_FORMATS as f, compactQuery as g, decodeUtf8 as h, isPlainObject as i, mergeDeep as m, sniffContentType as s, toBytes as t };