beliq-sevdesk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beliq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# beliq-sevdesk
+
+A small, self-hostable worker that polls [sevDesk](https://sevdesk.de) for your
+e-invoices, converts each one to the format a counterparty actually needs, and
+validates it against beliq's authority-pinned, drift-checked rules.
+
+sevDesk generates one configured e-invoice format and trusts its own output. This
+worker adds the two things it cannot:
+
+- **Conversion.** sevDesk emits its single configured format. When a counterparty
+  needs a different one (ZUGFeRD to Peppol BIS UBL, or a French Factur-X profile),
+  the worker retargets each invoice with `beliq convert`.
+- **An independent verdict.** `beliq validate` gives an authority-pinned second
+  opinion sevDesk does not provide, catching profile-specific gaps such as BR-DE
+  rules or a missing buyer reference / Leitweg-ID for public buyers.
+
+Your **sevDesk token never leaves your environment**: the worker runs where you
+run it, reads invoices directly from sevDesk, and only sends the invoice document
+to beliq for validation and conversion.
+
+## Install
+
+```bash
+npm install -g beliq-sevdesk
+# or run without installing:
+npx beliq-sevdesk --once
+```
+
+Requires Node.js >= 20.15.
+
+## Quick start
+
+Set the two credentials, point it at the invoices you care about, and run it once:
+
+```bash
+export SEVDESK_API_TOKEN=...   # sevDesk: Settings -> Advanced -> API
+export BELIQ_API_KEY=...       # beliq dashboard -> API Keys
+export SEVDESK_TARGET_FORMATS=peppol-bis
+
+beliq-sevdesk --once
+```
+
+That polls your Open invoices from the last 30 days, converts each to Peppol BIS
+UBL (written to `./out`), validates each one, prints a one-line summary, and exits
+with a code you can gate on. Leave `SEVDESK_TARGET_FORMATS` empty to run
+validation-only (no conversion, no files written).
+
+Copy [.env.example](.env.example) to `.env` for the full set of settings.
+
+## How each invoice is processed
+
+For every invoice newer than the last one it saw (tracked by a persisted
+high-water-mark, so nothing is processed twice):
+
+1. Pull the invoice XML from sevDesk (`GET /Invoice/{id}/getXml`).
+2. Convert it to each configured target format and write the bytes to the output
+   dir as `<invoiceNumber>-<target>.<ext>` (`.pdf` for facturx / zugferd, else
+   `.xml`). Any elements a conversion could not carry across are logged.
+3. Validate the source document and classify it: `valid`, `invalid`, or `error`
+   (the pipeline threw before a verdict).
+
+The high-water-mark advances only across a leading run of invoices that got a
+verdict. An invoice that errors (and any after it in the same batch) is left for
+the next poll, which is safe because reprocessing is idempotent.
+
+## Run once, or as a daemon
+
+- `--once` polls a single time and exits. Use this from cron or CI.
+- With no `--once`, it loops, polling every `SEVDESK_POLL_INTERVAL_SECONDS`
+  (default 300) until the process is stopped.
+- `--dry-run` walks the full pipeline (real API calls, real verdicts) but writes
+  no files and persists no state. Good for a first, safe look.
+
+A cron entry that runs it every 15 minutes:
+
+```cron
+*/15 * * * * SEVDESK_API_TOKEN=... BELIQ_API_KEY=... SEVDESK_TARGET_FORMATS=peppol-bis /usr/bin/beliq-sevdesk --once >> /var/log/beliq-sevdesk.log 2>&1
+```
+
+## Configuration
+
+Every setting is read from the environment; the flags below override the matching
+variable.
+
+| Variable | Flag | Default | Description |
+|---|---|---|---|
+| `SEVDESK_API_TOKEN` | `--sevdesk-token` | (required) | sevDesk API token. |
+| `BELIQ_API_KEY` | `--api-key` | (required) | beliq API key. |
+| `SEVDESK_TARGET_FORMATS` | `--target-format` | (none) | Comma-separated convert targets. Empty = validation-only. |
+| `SEVDESK_TARGET_PROFILE` | | (none) | Factur-X / ZUGFeRD profile, for a facturx / zugferd target. |
+| `SEVDESK_INVOICE_STATUS` | `--status` | `Open` | `Draft`, `Open`, `Paid`, or a numeric code. |
+| `SEVDESK_POLL_WINDOW_DAYS` | `--poll-window-days` | `30` | Only fetch invoices dated within n days back; `0` disables. |
+| `SEVDESK_STATE_FILE` | `--state` | `.beliq-sevdesk-state.json` | The persisted high-water-mark. |
+| `SEVDESK_OUTPUT_DIR` | `--output` | `./out` | Where converted documents are written. |
+| `SEVDESK_POLL_INTERVAL_SECONDS` | `--interval` | `300` | Seconds between polls in daemon mode. |
+| `SEVDESK_PAGE_SIZE` | | `100` | Page size for the invoice listing. |
+| `SEVDESK_MAX_RETRIES` | | `4` | Retries on a sevDesk 429 / 5xx / network error. |
+| `SEVDESK_BASE_URL` | | `https://api.sevdesk.de/api/v1` | Override for a mock or a future version. |
+| `BELIQ_BASE_URL` | | `https://api.beliq.eu` | Override for a self-hosted beliq. |
+| `BELIQ_AUTH` | | `header` | How the beliq key is sent: `header` (X-API-Key) or `bearer`. |
+
+Allowed target formats: `cii`, `ubl`, `zugferd`, `facturx`, `xrechnung`,
+`peppol-bis`. Allowed profiles: `basicwl`, `en16931`, `extended`,
+`extended-ctc-fr`.
+
+## Exit codes
+
+Meaningful with `--once`, so cron and CI can act on the result:
+
+| Code | Meaning |
+|---|---|
+| 0 | every processed invoice was valid, or there was nothing to do |
+| 1 | at least one invoice failed validation |
+| 2 | config / usage error (missing token or key, bad flag or value) |
+| 3 | a sevDesk or beliq API error, or an invoice that errored mid-pipeline |
+| 4 | I/O error (unreadable state file, unwritable output) |
+
+An error (code 3) outranks an invalid document (code 1): not getting a verdict is
+worse than getting a bad one.
+
+## Logging
+
+Structured events are written to stderr, one JSON object per line, for log
+aggregation. The final human-readable summary is written to stdout, so
+`beliq-sevdesk --once | tail -1` gives you the verdict while logs stay separate.
+
+## A note on the sevDesk token
+
+The sevDesk API token is account-wide, unscoped, and does not expire. This worker
+is built so that token stays on your side: it never sends the token anywhere but
+sevDesk, and it is not a hosted service holding your credentials. Store it the way
+you store any production secret.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test              # unit tests, no network
+npm run scrub:check   # no em-dash
+
+# live smoke against the real sevDesk + beliq APIs (skipped without creds):
+SEVDESK_API_TOKEN=... BELIQ_API_KEY=... npm run test:integration
+```
+
+## License
+
+MIT

package/dist/args.js

@@ -0,0 +1,69 @@
+import { ConfigError } from './errors.js';
+/** Flags that take no value. */
+const BOOLEAN_FLAGS = new Set(['once', 'dry-run']);
+/**
+ * Flags that take a value and override the matching environment variable. The
+ * worker is env-first (it runs as a container / cron job); these are the handful
+ * worth tweaking per invocation. Everything else stays env-only (see config.ts).
+ */
+const VALUE_FLAGS = new Set([
+    'state',
+    'output',
+    'target-format',
+    'status',
+    'poll-window-days',
+    'interval',
+    'api-key',
+    'sevdesk-token',
+]);
+/**
+ * Parse argv into flags. Hand-rolled (no dependency): the surface is small and
+ * this stays pure and unit-testable. Unknown flags and any positional argument
+ * are usage errors.
+ */
+export function parseArgs(argv) {
+    const out = { flags: {}, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--help' || token === '-h') {
+            out.help = true;
+            continue;
+        }
+        if (token === '--version' || token === '-v') {
+            out.version = true;
+            continue;
+        }
+        if (!token.startsWith('--')) {
+            throw new ConfigError(`unexpected argument "${token}". Run beliq-sevdesk --help.`);
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf('=');
+        const name = eq >= 0 ? body.slice(0, eq) : body;
+        const inlineValue = eq >= 0 ? body.slice(eq + 1) : undefined;
+        if (BOOLEAN_FLAGS.has(name)) {
+            if (inlineValue !== undefined)
+                throw new ConfigError(`option --${name} takes no value`);
+            out.flags[name] = true;
+        }
+        else if (VALUE_FLAGS.has(name)) {
+            let value = inlineValue;
+            if (value === undefined) {
+                value = argv[++i];
+                if (value === undefined)
+                    throw new ConfigError(`option --${name} needs a value`);
+            }
+            out.flags[name] = value;
+        }
+        else {
+            throw new ConfigError(`unknown option --${name}`);
+        }
+    }
+    return out;
+}
+export function flagBool(args, name) {
+    return args.flags[name] === true;
+}
+export function flagStr(args, name) {
+    const value = args.flags[name];
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/beliq.js

@@ -0,0 +1,4 @@
+import { Beliq } from '@beliq/sdk';
+export function makeBeliqClient(config) {
+    return new Beliq({ apiKey: config.beliqApiKey, baseUrl: config.beliqBaseUrl, auth: config.beliqAuth });
+}

package/dist/cli.js

@@ -0,0 +1,66 @@
+import { BeliqApiError } from '@beliq/sdk';
+import { parseArgs } from './args.js';
+import { resolveConfig } from './config.js';
+import { makeBeliqClient } from './beliq.js';
+import { SevDeskClient } from './sevdesk.js';
+import { runWorker } from './worker.js';
+import { EXIT } from './exit.js';
+import { ConfigError, IoError, SevDeskApiError } from './errors.js';
+import { HELP, version } from './help.js';
+/**
+ * The entry: parse argv, handle --help / --version, resolve config, build the
+ * real sevDesk + beliq clients, run the worker, and map every error class to its
+ * exit code (see EXIT). Pure in its logger + env seams so it can be driven from a
+ * test without touching real streams. Returns the process exit code.
+ */
+export async function main(argv, log, env = process.env) {
+    let config;
+    try {
+        const args = parseArgs(argv);
+        if (args.help) {
+            log.summary(HELP);
+            return EXIT.OK;
+        }
+        if (args.version) {
+            log.summary(version());
+            return EXIT.OK;
+        }
+        config = resolveConfig(args, env);
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            log.error('usage', { message: err.message });
+            return EXIT.USAGE;
+        }
+        throw err;
+    }
+    try {
+        const sevdesk = new SevDeskClient({
+            token: config.sevdeskToken,
+            baseUrl: config.sevdeskBaseUrl,
+            maxRetries: config.maxRetries,
+        });
+        const beliq = makeBeliqClient(config);
+        return await runWorker(config, { sevdesk, beliq, log });
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            log.error('usage', { message: err.message });
+            return EXIT.USAGE;
+        }
+        if (err instanceof IoError) {
+            log.error('io', { message: err.message });
+            return EXIT.IO;
+        }
+        if (err instanceof SevDeskApiError) {
+            log.error('sevdesk', { status: err.status, message: err.message });
+            return EXIT.API;
+        }
+        if (err instanceof BeliqApiError) {
+            log.error('beliq', { status: err.status, code: err.code, message: err.message });
+            return EXIT.API;
+        }
+        log.error('unexpected', { message: err.message });
+        return 1;
+    }
+}

package/dist/config.js

@@ -0,0 +1,89 @@
+import { DEFAULT_BASE_URL, LIVE_CONVERT_TARGET_FORMATS, LIVE_PROFILES, } from '@beliq/sdk';
+import { flagBool, flagStr } from './args.js';
+import { ConfigError } from './errors.js';
+/** sevDesk default REST base. Endpoints hang off /Invoice, /Invoice/{id}/getXml. */
+export const DEFAULT_SEVDESK_BASE_URL = 'https://api.sevdesk.de/api/v1';
+/** sevDesk invoice status codes (Settings dropdown values), keyed by friendly name. */
+const STATUS_CODES = { draft: '100', open: '200', paid: '1000' };
+/** Read a non-empty trimmed value; flag wins over env. */
+function pick(args, flag, env, key) {
+    const v = (flagStr(args, flag) ?? env[key])?.trim();
+    return v ? v : undefined;
+}
+function parseIntEnv(raw, fallback, label) {
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 0) {
+        throw new ConfigError(`${label} must be a non-negative integer, got "${raw}"`);
+    }
+    return n;
+}
+function resolveStatus(raw) {
+    if (!raw)
+        return STATUS_CODES.open;
+    const lower = raw.toLowerCase();
+    if (lower in STATUS_CODES)
+        return STATUS_CODES[lower];
+    if (/^\d+$/.test(raw))
+        return raw;
+    throw new ConfigError(`invalid status "${raw}". Use Draft, Open, Paid, or a numeric sevDesk status code.`);
+}
+function resolveTargets(raw) {
+    if (!raw)
+        return [];
+    const parts = raw
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    for (const p of parts) {
+        if (!LIVE_CONVERT_TARGET_FORMATS.includes(p)) {
+            throw new ConfigError(`invalid target format "${p}". Allowed: ${LIVE_CONVERT_TARGET_FORMATS.join(', ')}`);
+        }
+    }
+    return parts;
+}
+function resolveProfile(raw) {
+    if (!raw)
+        return undefined;
+    if (!LIVE_PROFILES.includes(raw)) {
+        throw new ConfigError(`invalid target profile "${raw}". Allowed: ${LIVE_PROFILES.join(', ')}`);
+    }
+    return raw;
+}
+/**
+ * Resolve the typed worker config with precedence flag > env > default. Throws a
+ * ConfigError (mapped to EXIT.USAGE) for a missing credential or a bad value, so
+ * the worker reports a clean usage error rather than failing mid-poll. The SDK
+ * reads no environment itself, so the worker owns BELIQ_* too.
+ */
+export function resolveConfig(args, env = process.env) {
+    const sevdeskToken = pick(args, 'sevdesk-token', env, 'SEVDESK_API_TOKEN');
+    if (!sevdeskToken) {
+        throw new ConfigError('no sevDesk token. Set SEVDESK_API_TOKEN or pass --sevdesk-token (Settings -> Advanced -> API).');
+    }
+    const beliqApiKey = pick(args, 'api-key', env, 'BELIQ_API_KEY');
+    if (!beliqApiKey) {
+        throw new ConfigError('no beliq API key. Set BELIQ_API_KEY or pass --api-key. Create a key in the beliq dashboard under API Keys.');
+    }
+    const beliqAuthRaw = (env.BELIQ_AUTH ?? '').trim().toLowerCase();
+    const beliqAuth = beliqAuthRaw === 'bearer' ? 'bearer' : 'header';
+    return {
+        sevdeskToken,
+        sevdeskBaseUrl: (env.SEVDESK_BASE_URL?.trim() || DEFAULT_SEVDESK_BASE_URL).replace(/\/+$/, ''),
+        beliqApiKey,
+        beliqBaseUrl: (env.BELIQ_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+        beliqAuth,
+        targetFormats: resolveTargets(flagStr(args, 'target-format') ?? env.SEVDESK_TARGET_FORMATS),
+        targetProfile: resolveProfile(env.SEVDESK_TARGET_PROFILE?.trim()),
+        status: resolveStatus(pick(args, 'status', env, 'SEVDESK_INVOICE_STATUS')),
+        pollWindowDays: parseIntEnv(flagStr(args, 'poll-window-days') ?? env.SEVDESK_POLL_WINDOW_DAYS, 30, 'poll window (days)'),
+        stateFile: pick(args, 'state', env, 'SEVDESK_STATE_FILE') ?? '.beliq-sevdesk-state.json',
+        outputDir: pick(args, 'output', env, 'SEVDESK_OUTPUT_DIR') ?? './out',
+        intervalSeconds: parseIntEnv(flagStr(args, 'interval') ?? env.SEVDESK_POLL_INTERVAL_SECONDS, 300, 'poll interval (seconds)'),
+        pageSize: parseIntEnv(env.SEVDESK_PAGE_SIZE, 100, 'page size') || 100,
+        maxRetries: parseIntEnv(env.SEVDESK_MAX_RETRIES, 4, 'max retries'),
+        once: flagBool(args, 'once'),
+        dryRun: flagBool(args, 'dry-run'),
+    };
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/** A user-facing config or usage problem (missing token/key, bad flag, bad value). Maps to EXIT.USAGE. */
+export class ConfigError extends Error {
+}
+/** A failure reading the state file, creating the output dir, or writing a document. Maps to EXIT.IO. */
+export class IoError extends Error {
+}
+/** A non-2xx sevDesk response (after retries) or a response body we could not parse. Maps to EXIT.API. */
+export class SevDeskApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'SevDeskApiError';
+        this.status = status;
+    }
+}

package/dist/exit.js

@@ -0,0 +1,28 @@
+export const EXIT = {
+    /** Success: every processed invoice was valid, or there was nothing to do. */
+    OK: 0,
+    /** At least one invoice failed validation (the CI/Action "document failed" contract). */
+    INVALID: 1,
+    /** A config or usage problem: missing token/key, bad flag, bad value. */
+    USAGE: 2,
+    /** A sevDesk or beliq API error (bad key, quota, engine), or an invoice that errored mid-pipeline. */
+    API: 3,
+    /** A local I/O error: unreadable state file, or an output dir/file that could not be written. */
+    IO: 4,
+};
+export function emptyCounts() {
+    return { valid: 0, invalid: 0, error: 0 };
+}
+/**
+ * The run's exit code from the tallied outcomes. An error (we never got a
+ * verdict) is worse than an invalid document (a verdict of non-compliant), so it
+ * wins: EXIT.API > EXIT.INVALID > EXIT.OK. This is a faithful superset of the
+ * CLI/Action contract, where "any invoice failed" maps to a non-zero exit.
+ */
+export function summaryExitCode(counts) {
+    if (counts.error > 0)
+        return EXIT.API;
+    if (counts.invalid > 0)
+        return EXIT.INVALID;
+    return EXIT.OK;
+}

package/dist/help.js

@@ -0,0 +1,39 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export function version() {
+    const pkg = require('../package.json');
+    return pkg.version;
+}
+export const HELP = `beliq-sevdesk: poll sevDesk invoices, convert them, and validate them with beliq
+
+Usage:
+  beliq-sevdesk [--once] [--dry-run] [options]
+
+Runs a poll loop by default. With --once it polls a single time and exits with a
+code you can gate CI or cron on (see below). Configuration is read from the
+environment; the flags below override the matching variable.
+
+Options:
+  --once                    poll once and exit (default: loop as a daemon)
+  --dry-run                 walk the full pipeline but write no files and persist no state
+  --target-format <csv>     beliq convert targets, comma-separated (default: SEVDESK_TARGET_FORMATS)
+  --status <s>              Draft | Open | Paid, or a numeric code (default: SEVDESK_INVOICE_STATUS, else Open)
+  --poll-window-days <n>    only fetch invoices dated within n days back; 0 disables (default: 30)
+  --state <path>           high-water-mark file (default: SEVDESK_STATE_FILE, else .beliq-sevdesk-state.json)
+  --output <dir>           where converted documents are written (default: SEVDESK_OUTPUT_DIR, else ./out)
+  --interval <seconds>     seconds between polls in daemon mode (default: 300)
+  --sevdesk-token <token>  sevDesk API token (default: SEVDESK_API_TOKEN)
+  --api-key <key>          beliq API key (default: BELIQ_API_KEY)
+  -h, --help               show this help
+  -v, --version            show the version
+
+Exit codes (meaningful with --once):
+  0  every processed invoice was valid, or there was nothing to do
+  1  at least one invoice failed validation
+  2  config/usage error (missing token/key, bad flag or value)
+  3  a sevDesk or beliq API error, or an invoice that errored mid-pipeline
+  4  I/O error (unreadable state file, unwritable output)
+
+Set SEVDESK_API_TOKEN (Settings -> Advanced -> API) and BELIQ_API_KEY (beliq
+dashboard -> API Keys). The sevDesk token never leaves this environment.
+`;

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+import { nodeLogger } from './log.js';
+main(process.argv.slice(2), nodeLogger()).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`beliq-sevdesk: fatal: ${err.message}\n`);
+    process.exitCode = 1;
+});

package/dist/log.js

@@ -0,0 +1,10 @@
+export function nodeLogger() {
+    const emit = (level, event, fields) => {
+        process.stderr.write(`${JSON.stringify({ level, event, ...fields })}\n`);
+    };
+    return {
+        info: (event, fields) => emit('info', event, fields),
+        error: (event, fields) => emit('error', event, fields),
+        summary: (line) => process.stdout.write(`${line}\n`),
+    };
+}

package/dist/sevdesk.js

@@ -0,0 +1,167 @@
+import { SevDeskApiError } from './errors.js';
+/** A hard ceiling on pages walked per poll, so a misconfigured window can't loop forever. */
+const MAX_PAGES = 100;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8');
+function looksLikeXml(s) {
+    return s.trimStart().startsWith('<');
+}
+/**
+ * Pull the XML out of a getXml response. sevDesk's exact envelope for this
+ * endpoint is not publicly pinned (the live round-trip that confirms it is
+ * operator-gated), so this handles the documented-plausible shapes in one place:
+ * a raw XML body, `{ objects: "<xml>" }`, or `{ objects: { content, base64 } }`,
+ * with the payload optionally base64-encoded. If a live response differs, this
+ * is the single function to adjust.
+ */
+export function extractXml(contentType, text) {
+    if (contentType.includes('xml') || looksLikeXml(text))
+        return encoder.encode(text);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SevDeskApiError('getXml: response was neither XML nor JSON', 200);
+    }
+    const envelope = parsed?.objects ?? parsed;
+    let payload;
+    let base64Flag = false;
+    if (typeof envelope === 'string') {
+        payload = envelope;
+    }
+    else if (envelope && typeof envelope === 'object') {
+        const o = envelope;
+        payload = o.content ?? o.xml ?? o.file;
+        base64Flag = o.base64 === true;
+    }
+    if (typeof payload !== 'string') {
+        throw new SevDeskApiError('getXml: could not locate the XML in the response', 200);
+    }
+    if (base64Flag)
+        return new Uint8Array(Buffer.from(payload, 'base64'));
+    if (looksLikeXml(payload))
+        return encoder.encode(payload);
+    // No explicit flag and it does not look like XML: try base64, accept only if it decodes to XML.
+    try {
+        const decoded = Buffer.from(payload, 'base64');
+        if (looksLikeXml(decoder.decode(decoded)))
+            return new Uint8Array(decoded);
+    }
+    catch {
+        // fall through to treating the payload as literal text
+    }
+    return encoder.encode(payload);
+}
+function isRetryable(status) {
+    return status === 429 || status >= 500;
+}
+/** Thin sevDesk REST client over an injectable fetch, with pagination and retry/backoff. */
+export class SevDeskClient {
+    #token;
+    #baseUrl;
+    #fetch;
+    #sleep;
+    #maxRetries;
+    #baseRetryDelayMs;
+    constructor(options) {
+        if (!options.token)
+            throw new Error('sevdesk: token is required');
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new Error('sevdesk: no global fetch available; pass options.fetch');
+        }
+        this.#token = options.token;
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.#fetch = fetchImpl;
+        this.#sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.#maxRetries = options.maxRetries ?? 4;
+        this.#baseRetryDelayMs = options.baseRetryDelayMs ?? 500;
+    }
+    async listInvoices(params) {
+        const limit = params.pageSize && params.pageSize > 0 ? params.pageSize : 100;
+        const all = [];
+        for (let page = 0; page < MAX_PAGES; page++) {
+            const query = { limit, offset: page * limit };
+            if (params.status)
+                query.status = params.status;
+            if (params.startDate !== undefined)
+                query.startDate = params.startDate;
+            const { text } = await this.#request('GET', '/Invoice', query);
+            const objects = this.#parseObjects(text);
+            for (const o of objects)
+                all.push(normalizeInvoice(o));
+            if (objects.length < limit)
+                break;
+        }
+        return all;
+    }
+    async getInvoiceXml(id) {
+        const { text, contentType } = await this.#request('GET', `/Invoice/${encodeURIComponent(id)}/getXml`);
+        return extractXml(contentType, text);
+    }
+    #parseObjects(text) {
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new SevDeskApiError('sevDesk list response was not JSON', 200);
+        }
+        const objects = parsed?.objects;
+        if (!Array.isArray(objects)) {
+            throw new SevDeskApiError('sevDesk list response had no "objects" array', 200);
+        }
+        return objects;
+    }
+    async #request(method, path, query) {
+        const url = new URL(this.#baseUrl + path);
+        if (query) {
+            for (const [k, v] of Object.entries(query))
+                url.searchParams.set(k, String(v));
+        }
+        let lastError;
+        for (let attempt = 0; attempt <= this.#maxRetries; attempt++) {
+            let res;
+            try {
+                res = await this.#fetch(url.toString(), {
+                    method,
+                    headers: { Authorization: this.#token, Accept: 'application/json' },
+                });
+            }
+            catch (err) {
+                lastError = err;
+                if (attempt < this.#maxRetries) {
+                    await this.#backoff(attempt);
+                    continue;
+                }
+                throw new SevDeskApiError(`sevDesk ${method} ${path} network error: ${lastError.message}`, 0);
+            }
+            if (res.ok) {
+                return {
+                    status: res.status,
+                    text: await res.text(),
+                    contentType: res.headers.get('content-type') ?? '',
+                };
+            }
+            if (isRetryable(res.status) && attempt < this.#maxRetries) {
+                await this.#backoff(attempt);
+                continue;
+            }
+            throw new SevDeskApiError(`sevDesk ${method} ${path} failed with status ${res.status}`, res.status);
+        }
+        // Unreachable: the loop either returns or throws. Satisfies noImplicitReturns.
+        throw new SevDeskApiError(`sevDesk ${method} ${path} exhausted retries`, 0);
+    }
+    #backoff(attempt) {
+        return this.#sleep(this.#baseRetryDelayMs * 2 ** attempt);
+    }
+}
+function normalizeInvoice(raw) {
+    return {
+        ...raw,
+        id: String(raw.id),
+        invoiceNumber: raw.invoiceNumber != null ? String(raw.invoiceNumber) : undefined,
+        status: raw.status != null ? String(raw.status) : undefined,
+    };
+}

package/dist/state.js

@@ -0,0 +1,40 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { IoError } from './errors.js';
+const EMPTY = { lastInvoiceId: 0 };
+/**
+ * Load the high-water-mark. A missing file is the first-run case (start from 0).
+ * A present-but-corrupt file throws IoError rather than silently resetting to 0,
+ * which would reprocess the entire account.
+ */
+export async function loadState(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { ...EMPTY };
+        throw new IoError(`could not read state file ${path}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new IoError(`state file ${path} is not valid JSON; fix or delete it to start fresh`);
+    }
+    const lastInvoiceId = parsed?.lastInvoiceId;
+    if (typeof lastInvoiceId !== 'number' || !Number.isFinite(lastInvoiceId) || lastInvoiceId < 0) {
+        throw new IoError(`state file ${path} has no valid lastInvoiceId; fix or delete it to start fresh`);
+    }
+    const lastPolledAt = parsed.lastPolledAt;
+    return { lastInvoiceId, lastPolledAt: typeof lastPolledAt === 'string' ? lastPolledAt : undefined };
+}
+export async function saveState(path, state) {
+    try {
+        await writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+    }
+    catch (err) {
+        throw new IoError(`could not write state file ${path}: ${err.message}`);
+    }
+}

package/dist/worker.js

@@ -0,0 +1,149 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { IoError } from './errors.js';
+import { emptyCounts, summaryExitCode } from './exit.js';
+import { loadState, saveState } from './state.js';
+/** Convert targets that produce a hybrid PDF rather than a standalone XML document. */
+const PDF_TARGETS = new Set(['facturx', 'zugferd']);
+/** Seconds in a day, for the poll-window date filter. */
+const SECONDS_PER_DAY = 86_400;
+function safeName(inv) {
+    const base = inv.invoiceNumber || inv.id;
+    return base.replace(/[^A-Za-z0-9._-]/g, '_');
+}
+async function ensureDir(dir) {
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        throw new IoError(`could not create output dir ${dir}: ${err.message}`);
+    }
+}
+async function writeOutput(dir, name, bytes) {
+    const path = join(dir, name);
+    try {
+        await writeFile(path, bytes);
+    }
+    catch (err) {
+        throw new IoError(`could not write ${path}: ${err.message}`);
+    }
+}
+/**
+ * Run one invoice through the pipeline: pull its XML, convert it to each
+ * configured target (writing the bytes out), then validate the source document
+ * for an independent authority-pinned verdict sevDesk does not provide. Returns
+ * the classification; a throw here is caught by the caller and counted as an
+ * error (no verdict), leaving the high-water-mark short of this invoice so it is
+ * retried next poll.
+ */
+async function processInvoice(inv, config, deps) {
+    const xml = await deps.sevdesk.getInvoiceXml(inv.id);
+    for (const target of config.targetFormats) {
+        const result = await deps.beliq.convert(xml, {
+            targetFormat: target,
+            targetProfile: PDF_TARGETS.has(target) ? config.targetProfile : undefined,
+        });
+        const ext = PDF_TARGETS.has(target) ? 'pdf' : 'xml';
+        const file = `${safeName(inv)}-${target}.${ext}`;
+        const lostElements = result.meta.lostElementsCount ?? 0;
+        if (config.dryRun) {
+            deps.log.info('convert.dryRun', { id: inv.id, target, file, lostElements });
+        }
+        else {
+            await writeOutput(config.outputDir, file, result.bytes);
+            deps.log.info('convert', { id: inv.id, target, file, lostElements });
+        }
+    }
+    const verdict = await deps.beliq.validate(xml, {});
+    const classification = verdict.valid ? 'valid' : 'invalid';
+    deps.log.info('validate', {
+        id: inv.id,
+        number: inv.invoiceNumber,
+        valid: verdict.valid,
+        errors: verdict.errors?.length ?? 0,
+        warnings: verdict.warnings?.length ?? 0,
+        classification,
+    });
+    return classification;
+}
+function formatSummary(counts, fresh, dryRun) {
+    const prefix = dryRun ? '[dry-run] ' : '';
+    return `${prefix}processed ${fresh} invoice(s): ${counts.valid} valid, ${counts.invalid} invalid, ${counts.error} error`;
+}
+/**
+ * Poll sevDesk once: fetch invoices in the configured status/window, process
+ * only those newer than the high-water-mark (in ascending id order so the mark
+ * advances monotonically and dedupes by id), and persist the advanced mark. The
+ * mark advances only across the contiguous error-free prefix: an invoice that
+ * errors (and every invoice after it in this batch) is left for the next poll,
+ * which is safe because reprocessing is idempotent.
+ */
+export async function pollOnce(config, deps) {
+    const now = deps.now ?? (() => Date.now());
+    if (config.targetFormats.length > 0 && !config.dryRun) {
+        await ensureDir(config.outputDir);
+    }
+    const state = await loadState(config.stateFile);
+    const startDate = config.pollWindowDays > 0 ? Math.floor(now() / 1000) - config.pollWindowDays * SECONDS_PER_DAY : undefined;
+    const invoices = await deps.sevdesk.listInvoices({
+        status: config.status,
+        startDate,
+        pageSize: config.pageSize,
+    });
+    const fresh = invoices
+        .map((inv) => ({ inv, idNum: Number(inv.id) }))
+        .filter(({ idNum }) => Number.isFinite(idNum) && idNum > state.lastInvoiceId)
+        .sort((a, b) => a.idNum - b.idNum);
+    deps.log.info('poll', {
+        status: config.status,
+        since: state.lastInvoiceId,
+        listed: invoices.length,
+        fresh: fresh.length,
+    });
+    const counts = emptyCounts();
+    let highWater = state.lastInvoiceId;
+    let blocked = false;
+    for (const { inv, idNum } of fresh) {
+        let classification;
+        try {
+            classification = await processInvoice(inv, config, deps);
+        }
+        catch (err) {
+            classification = 'error';
+            deps.log.error('invoice.error', {
+                id: inv.id,
+                number: inv.invoiceNumber,
+                message: err.message,
+            });
+        }
+        counts[classification]++;
+        if (classification === 'error')
+            blocked = true;
+        else if (!blocked)
+            highWater = idNum;
+    }
+    if (!config.dryRun && highWater > state.lastInvoiceId) {
+        await saveState(config.stateFile, {
+            lastInvoiceId: highWater,
+            lastPolledAt: new Date(now()).toISOString(),
+        });
+    }
+    deps.log.summary(formatSummary(counts, fresh.length, config.dryRun));
+    return { counts, processedTo: highWater };
+}
+/**
+ * Run the worker. With --once, poll a single time and return the exit code (the
+ * CI/cron contract). Otherwise loop forever, polling every interval, until the
+ * process is signalled.
+ */
+export async function runWorker(config, deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    if (config.once) {
+        const { counts } = await pollOnce(config, deps);
+        return summaryExitCode(counts);
+    }
+    for (;;) {
+        await pollOnce(config, deps);
+        await sleep(config.intervalSeconds * 1000);
+    }
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "beliq-sevdesk",
+  "version": "0.1.0",
+  "description": "Self-hostable worker that polls sevDesk for e-invoices, converts each to the formats a counterparty needs, and validates them against beliq's authority-pinned, drift-checked rules. The sevDesk token never leaves your environment.",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "beliq",
+    "email": "hello@beliq.eu"
+  },
+  "homepage": "https://beliq.eu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beliq-eu/beliq-sevdesk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/beliq-eu/beliq-sevdesk/issues"
+  },
+  "keywords": [
+    "beliq",
+    "sevdesk",
+    "e-invoice",
+    "einvoice",
+    "xrechnung",
+    "zugferd",
+    "factur-x",
+    "peppol",
+    "en16931",
+    "validation",
+    "conversion",
+    "worker",
+    "cron"
+  ],
+  "engines": {
+    "node": ">=20.15"
+  },
+  "bin": {
+    "beliq-sevdesk": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "vitest run --exclude test/integration.test.ts",
+    "test:integration": "vitest run test/integration.test.ts",
+    "scrub:check": "bash scripts/scrub-check.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@beliq/sdk": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.8"
+  }
+}