@beliq/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,332 @@
+// src/internal.ts
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeDeep(target, source) {
+  const out = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+    if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = mergeDeep(out[key], value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function compactQuery(query) {
+  const out = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === "") continue;
+    out[key] = value;
+  }
+  return out;
+}
+function toBytes(input) {
+  if (typeof input === "string") return new TextEncoder().encode(input);
+  if (input instanceof Uint8Array) return input;
+  if (input instanceof ArrayBuffer) return new Uint8Array(input);
+  if (ArrayBuffer.isView(input)) {
+    return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+  }
+  throw new TypeError("beliq: document must be a string, Uint8Array, ArrayBuffer, or typed array");
+}
+function decodeUtf8(bytes) {
+  return new TextDecoder("utf-8").decode(bytes);
+}
+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);
+  return isPdf ? "application/pdf" : "application/xml";
+}
+
+// src/buildRequest.ts
+function isFacturxFamily(standardOrFormat) {
+  return standardOrFormat === "facturx" || standardOrFormat === "zugferd";
+}
+function withAdvancedQuery(query, advanced) {
+  const base = compactQuery(query);
+  const merged = advanced && Object.keys(advanced).length > 0 ? mergeDeep(base, advanced) : base;
+  return merged;
+}
+function buildRequest(params) {
+  switch (params.operation) {
+    case "me":
+      return { method: "GET", path: "/v1/me", outputKind: "json" };
+    case "generate": {
+      const body = {
+        standard: params.standard,
+        output: params.output ?? "xml",
+        invoice: params.invoice ?? {}
+      };
+      if (params.profile) body.profile = params.profile;
+      if (params.facturxProfile && isFacturxFamily(params.standard)) {
+        body.facturxProfile = params.facturxProfile;
+      }
+      if (typeof params.verify === "boolean") body.verify = params.verify;
+      if (params.template) body.template = params.template;
+      if (params.pdfTemplateId) body.pdfTemplateId = params.pdfTemplateId;
+      const merged = params.advanced && Object.keys(params.advanced).length > 0 ? mergeDeep(body, params.advanced) : body;
+      return {
+        method: "POST",
+        path: "/v1/generate",
+        jsonBody: merged,
+        contentType: "application/json",
+        outputKind: "binary"
+      };
+    }
+    case "validate": {
+      const query = { format: params.validateFormat };
+      if (typeof params.franceCtc === "boolean") query.franceCtc = params.franceCtc;
+      return {
+        method: "POST",
+        path: "/v1/validate",
+        query: withAdvancedQuery(query, params.advanced),
+        rawBody: params.rawBody,
+        contentType: params.rawContentType ?? "application/xml",
+        outputKind: "json"
+      };
+    }
+    case "parse":
+      return {
+        method: "POST",
+        path: "/v1/parse",
+        query: withAdvancedQuery({ format: params.parseFormat }, params.advanced),
+        rawBody: params.rawBody,
+        contentType: params.rawContentType ?? "application/xml",
+        outputKind: "json"
+      };
+    case "convert": {
+      const query = {
+        sourceFormat: params.sourceFormat,
+        targetFormat: params.targetFormat
+      };
+      if (params.targetProfile && isFacturxFamily(params.targetFormat)) {
+        query.targetProfile = params.targetProfile;
+      }
+      if (typeof params.dropFranceCtcOverlay === "boolean") {
+        query.dropFranceCtcOverlay = params.dropFranceCtcOverlay;
+      }
+      return {
+        method: "POST",
+        path: "/v1/convert",
+        query: withAdvancedQuery(query, params.advanced),
+        rawBody: params.rawBody,
+        contentType: params.rawContentType ?? "application/xml",
+        outputKind: "binary"
+      };
+    }
+  }
+}
+
+// src/errors.ts
+var BeliqApiError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(message, opts) {
+    super(message);
+    this.name = "BeliqApiError";
+    this.code = opts.code;
+    this.status = opts.status;
+    this.details = opts.details;
+  }
+};
+function parseEnvelope(bytes) {
+  let text;
+  try {
+    text = decodeUtf8(bytes);
+  } catch {
+    return null;
+  }
+  if (!text.trim()) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return isPlainObject(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function errorFromResponse(status, bytes) {
+  const envelope = parseEnvelope(bytes);
+  const err = envelope?.error;
+  const message = err?.message ?? envelope?.message ?? `beliq request failed with status ${status}`;
+  return new BeliqApiError(message, { code: err?.code, status, details: err?.details });
+}
+
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://api.beliq.eu";
+var LIVE_GENERATE_STANDARDS = ["xrechnung", "zugferd", "facturx", "peppol-bis"];
+var LIVE_PROFILES = ["basicwl", "en16931", "extended", "extended-ctc-fr"];
+var LIVE_VALIDATE_FORMATS = ["auto", "cii", "ubl"];
+var LIVE_PARSE_FORMATS = ["auto", "cii", "ubl"];
+var LIVE_CONVERT_SOURCE_FORMATS = [
+  "auto",
+  "cii",
+  "ubl",
+  "zugferd",
+  "facturx",
+  "xrechnung",
+  "peppol-bis"
+];
+var LIVE_CONVERT_TARGET_FORMATS = [
+  "cii",
+  "ubl",
+  "zugferd",
+  "facturx",
+  "xrechnung",
+  "peppol-bis"
+];
+
+// src/transport.ts
+function authHeaders(config) {
+  return config.auth === "bearer" ? { Authorization: `Bearer ${config.apiKey}` } : { "X-API-Key": config.apiKey };
+}
+function buildUrl(baseUrl, path, query) {
+  if (!query) return `${baseUrl}${path}`;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0) continue;
+    params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `${baseUrl}${path}?${qs}` : `${baseUrl}${path}`;
+}
+async function send(config, req) {
+  const headers = { ...authHeaders(config) };
+  if (req.contentType) headers["Content-Type"] = req.contentType;
+  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 };
+}
+
+// src/client.ts
+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
+  };
+}
+function convertMeta(headers) {
+  let lostElements;
+  const lostRaw = headers.get("x-lost-elements");
+  if (lostRaw) {
+    try {
+      const parsed = JSON.parse(lostRaw);
+      if (Array.isArray(parsed)) lostElements = parsed.map(String);
+    } catch {
+    }
+  }
+  const countRaw = headers.get("x-lost-elements-count");
+  return {
+    sourceFormat: headers.get("x-source-format") ?? void 0,
+    targetFormat: headers.get("x-target-format") ?? void 0,
+    profileDetected: headers.get("x-profile-detected") ?? void 0,
+    lostElementsCount: countRaw != null ? Number(countRaw) : void 0,
+    lostElements,
+    conversionTools: headers.get("x-conversion-tools") ?? void 0
+  };
+}
+var Beliq = class {
+  #config;
+  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.#config = {
+      apiKey: options.apiKey,
+      baseUrl: (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+      auth: options.auth ?? "header",
+      fetchImpl
+    };
+  }
+  /** Account, plan, and quota context for the key. Does not consume quota. */
+  async me() {
+    return this.#json({ operation: "me" });
+  }
+  /** Generate a compliant e-invoice from an EN 16931 object. */
+  async generate(input) {
+    const res = await send(this.#config, buildRequest({ operation: "generate", ...input }));
+    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)
+    };
+  }
+  /** Validate a document against authority-pinned rules. */
+  async validate(document, options = {}) {
+    return this.#json({
+      operation: "validate",
+      ...this.#rawParams(document, options),
+      validateFormat: options.format,
+      franceCtc: options.franceCtc
+    });
+  }
+  /** Parse a document into a structured EN 16931 invoice. */
+  async parse(document, options = {}) {
+    return this.#json({
+      operation: "parse",
+      ...this.#rawParams(document, options),
+      parseFormat: options.format
+    });
+  }
+  /** Convert a document between EN 16931 formats. */
+  async convert(document, options) {
+    const res = await send(
+      this.#config,
+      buildRequest({
+        operation: "convert",
+        ...this.#rawParams(document, options),
+        sourceFormat: options.sourceFormat,
+        targetFormat: options.targetFormat,
+        targetProfile: options.targetProfile,
+        dropFranceCtcOverlay: options.dropFranceCtcOverlay
+      })
+    );
+    return {
+      contentType: res.headers.get("content-type") ?? "application/octet-stream",
+      bytes: res.bytes,
+      meta: convertMeta(res.headers)
+    };
+  }
+  #rawParams(document, options) {
+    const rawBody = toBytes(document);
+    return {
+      rawBody,
+      rawContentType: options.contentType ?? sniffContentType(rawBody),
+      advanced: options.advanced
+    };
+  }
+  async #json(params) {
+    const res = await send(this.#config, buildRequest(params));
+    const envelope = parseEnvelope(res.bytes);
+    if (envelope?.success === false) throw errorFromResponse(res.status, res.bytes);
+    if (!envelope || envelope.data === void 0) {
+      throw new BeliqApiError("beliq: response was not a JSON envelope", { status: res.status });
+    }
+    return envelope.data;
+  }
+};
+export {
+  Beliq,
+  BeliqApiError,
+  DEFAULT_BASE_URL,
+  LIVE_CONVERT_SOURCE_FORMATS,
+  LIVE_CONVERT_TARGET_FORMATS,
+  LIVE_GENERATE_STANDARDS,
+  LIVE_PARSE_FORMATS,
+  LIVE_PROFILES,
+  LIVE_VALIDATE_FORMATS
+};

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@beliq/sdk",
+  "version": "0.1.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",
+    "e-invoice",
+    "einvoice",
+    "xrechnung",
+    "zugferd",
+    "factur-x",
+    "peppol",
+    "en16931",
+    "compliance",
+    "sdk"
+  ],
+  "license": "MIT",
+  "homepage": "https://beliq.eu",
+  "author": {
+    "name": "beliq",
+    "email": "hello@beliq.eu"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beliq-eu/beliq-sdk-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/beliq-eu/beliq-sdk-node/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./helpers": {
+      "import": {
+        "types": "./dist/helpers.d.ts",
+        "default": "./dist/helpers.js"
+      },
+      "require": {
+        "types": "./dist/helpers.d.cts",
+        "default": "./dist/helpers.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.15"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix",
+    "sync:spec": "node scripts/sync-spec.mjs",
+    "gen:types": "node scripts/gen-types.mjs",
+    "openapi:check": "node scripts/gen-types.mjs --check",
+    "test": "vitest run --exclude test/integration.test.ts",
+    "test:integration": "vitest run test/integration.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "openapi-typescript": "^7.4.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.8"
+  }
+}