beliq-sevdesk 0.2.4 → 0.3.0

package/README.md

@@ -1,18 +1,22 @@
 # 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.
+e-invoices, validates each one against beliq's authority-pinned, drift-checked
+rules, and converts it to the formats a counterparty needs.
+
+sevDesk's API hands out an e-invoice as one XML document. On the account this
+worker was tested against in October 2026, that is UN/CEFACT CII declaring the
+XRechnung 3.0 specification. The worker adds two things:
+
+- **An independent verdict.** sevDesk checks that the fields an e-invoice needs
+  are filled before the invoice may leave draft: it refuses one without a buyer
+  reference, for example. Its API has no validation endpoint and returns no
+  validation result. `beliq validate` checks the finished document against KoSIT's XRechnung
+  rules. One case from that account: sevDesk took an IBAN that is not a correct
+  IBAN, and beliq reported it as warning `BR-DE-19`.
+- **Conversion.** When a counterparty needs another syntax or profile, the worker
+  converts each invoice with `beliq convert`. See
+  [What you can convert to](#what-you-can-convert-to).
 
 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
@@ -35,46 +39,113 @@ Set the two credentials, point it at the invoices you care about, and run it onc
 ```bash
 export SEVDESK_API_TOKEN=...   # sevDesk: Settings -> Advanced -> API
 export BELIQ_API_KEY=...       # beliq dashboard -> API Keys
-export SEVDESK_TARGET_FORMATS=peppol-bis
+export SEVDESK_TARGET_FORMATS=xrechnung
 
 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
+That polls your Open invoices from the last 30 days, validates each one, converts
+each to XRechnung in UBL syntax (written to `./out`), 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):
+For every listed invoice the worker has not finished yet (it keeps the finished
+ids in a state file, 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).
+2. Validate the document and classify it: `valid`, `invalid`, or `error` (no
+   verdict).
+3. Convert it to each configured target format and write the bytes to the output
+   dir as `<invoiceNumber>-<target>.<ext>`. The extension follows what beliq
+   returns: `.xml` for an XML document, `.pdf` for a PDF. Any elements a
+   conversion could not carry across are logged.
+
+The worker validates the document sevDesk produced. It does not validate the
+converted files, and neither does `beliq convert`: a conversion rewrites the
+syntax and the specification id, not the content. Validate a converted file
+yourself before you rely on it.
+
+Each invoice stands alone. One that fails for a reason that can pass (sevDesk or
+beliq unreachable, a spent quota, a wrong key, a full disk) is tried again on the
+next poll, and the invoices after it are still processed.
+
+If beliq refuses the document itself, because it cannot be read or because the
+conversion is not possible, the invoice is reported once and not tried again. It
+counts as `error`, unless validation already found it `invalid`. The log line
+`validate.refused` or `convert.refused` carries beliq's status and error code.
+
+An invoice that was still a draft while a newer one was processed is picked up
+on the first poll that lists it.
+
+Each invoice is checked once. On the tested account sevDesk locks an invoice when
+it is opened, so its document cannot change afterwards.
+
+sevDesk holds XML only for invoices created as e-invoices, and its invoice list
+does not say which ones those are. So the worker asks for the XML of every listed
+invoice. For a normal invoice sevDesk answers that it is not an electronic
+invoice; the worker counts it as `skipped`, logs `invoice.skipped` once and does
+not ask again. A skipped invoice does not change the exit code.
+
+### Which invoices are listed
+
+Each poll lists the invoices in the configured status whose invoice date lies
+within the last `SEVDESK_POLL_WINDOW_DAYS` days (default 30). sevDesk filters on
+the invoice date, not on when the invoice was created or opened. An invoice dated
+before the window is not listed, even when it was created or opened today:
+opening a draft does not move its invoice date. Set `SEVDESK_POLL_WINDOW_DAYS=0`
+to list every invoice in that status on every poll.
+
+An invoice is seen only while it is in the configured status. When a part
+payment is booked on an Open invoice, sevDesk moves it to another status and the
+Open list no longer returns it.
+
+### What you can convert to
+
+Measured with the XML of the tested account. Each of these came back with no lost
+elements:
+
+| Target | What comes back |
+|---|---|
+| `xrechnung` | UBL, declaring XRechnung 3.0 |
+| `ubl` | UBL, declaring plain EN 16931 |
+| `cii` | CII |
+| `zugferd`, `facturx` | CII XML with that profile's specification id. Not a PDF: sevDesk's API gives the worker XML, and beliq builds a PDF only from a PDF source. `SEVDESK_TARGET_PROFILE` picks the profile |
 
-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.
+`peppol-bis` does not work. Peppol BIS needs a Peppol endpoint identifier for the
+seller and the buyer, sevDesk's XML carries neither, and beliq does not make one
+up. beliq refuses the conversion (`CONVERSION_LOSSY_FAILCLOSED`) and the invoice
+is reported as `error`.
 
 ## 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.
+  (default 300) until the process is stopped. A poll that sevDesk fails
+  (unreachable, or an error answer after the retries) is logged as `poll.error`
+  and the next poll runs on schedule. A local fault, such as an unreadable state
+  file, ends the worker with exit code 4.
+- On SIGTERM or SIGINT the worker finishes the invoice it is working on, saves
+  its state and exits 0. Invoices it had not reached are picked up by the next
+  run.
 - `--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:
+A cron entry that runs it every 15 minutes. The settings come from a file only
+root can read, because cron writes each command line it runs to the system log:
 
 ```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
+*/15 * * * * set -a; . /etc/beliq-sevdesk.env; set +a; /usr/bin/beliq-sevdesk --once >> /var/log/beliq-sevdesk.log 2>&1
+```
+
+```bash
+# /etc/beliq-sevdesk.env, mode 600
+SEVDESK_API_TOKEN=...
+BELIQ_API_KEY=...
+SEVDESK_TARGET_FORMATS=xrechnung
 ```
 
 ## Run it in a container
@@ -95,13 +166,13 @@ a single poll:
 
 ```bash
 docker run --rm \
-  -e SEVDESK_API_TOKEN -e BELIQ_API_KEY -e SEVDESK_TARGET_FORMATS=peppol-bis \
+  -e SEVDESK_API_TOKEN -e BELIQ_API_KEY -e SEVDESK_TARGET_FORMATS=xrechnung \
   -v "$PWD/out:/app/out" -v "$PWD/state:/app/state" \
   ghcr.io/beliq-eu/beliq-sevdesk:latest --once
 ```
 
 Inside the image the state file defaults to `/app/state/state.json` and the
-output dir to `/app/out`; mount volumes there to persist the high-water-mark and
+output dir to `/app/out`; mount volumes there to persist the state file and
 the converted documents across restarts. With no arguments the container loops as
 a daemon.
 
@@ -128,8 +199,8 @@ The body:
 ```json
 {
   "ok": false,
-  "summary": "processed 2 invoice(s): 1 valid, 1 invalid, 0 error",
-  "counts": { "valid": 1, "invalid": 1, "error": 0 },
+  "summary": "processed 2 invoice(s): 1 valid, 1 invalid, 0 error, 0 skipped",
+  "counts": { "valid": 1, "invalid": 1, "error": 0, "skipped": 0 },
   "invoices": [
     { "id": "10", "invoiceNumber": "INV-10", "classification": "valid" },
     { "id": "11", "invoiceNumber": "INV-11", "classification": "invalid" }
@@ -145,7 +216,9 @@ The exit code always reflects the invoices, not the notification.
 ## Configuration
 
 Every setting is read from the environment; the flags below override the matching
-variable.
+variable. Pass the two credentials through the environment: a value given with
+`--sevdesk-token` or `--api-key` is on the command line, where every user on the
+host can read it in the process list.
 
 | Variable | Flag | Default | Description |
 |---|---|---|---|
@@ -155,7 +228,7 @@ variable.
 | `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_STATE_FILE` | `--state` | `.beliq-sevdesk-state.json` | The state file: the ids of the invoices already processed. |
 | `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. |
@@ -176,15 +249,28 @@ 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 |
+| 0 | every processed invoice was valid or skipped, 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 |
+| 3 | a sevDesk or beliq API error, an invoice that errored mid-pipeline, or a document beliq refused to validate or convert |
 | 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.
 
+## Upgrading from 0.2.x
+
+0.2.x stored one number in the state file: the highest invoice id it had
+processed. The first poll after the upgrade reads that number, marks every listed
+invoice with an id at or below it as processed, and rewrites the file as a list
+of ids. Nothing needs to be done by hand.
+
+One thing to know. 0.2.x skipped an invoice that was still a draft while a newer
+invoice was processed. The old file cannot tell such an invoice from a processed
+one, so the upgrade marks it as processed too. To have every invoice in the
+current poll window processed again, delete the state file before the first run.
+That validates and converts those invoices again and uses beliq quota for each.
+
 ## Logging
 
 Structured events are written to stderr, one JSON object per line, for log

package/dist/beliq.js

@@ -1,4 +1,22 @@
-import { Beliq } from '@beliq/sdk';
+import { Beliq, BeliqApiError } from '@beliq/sdk';
 export function makeBeliqClient(config) {
     return new Beliq({ apiKey: config.beliqApiKey, baseUrl: config.beliqBaseUrl, auth: config.beliqAuth });
 }
+const HTTP_PAYLOAD_TOO_LARGE = 413;
+const HTTP_UNPROCESSABLE = 422;
+/**
+ * True when beliq refused the document itself, so the same bytes get the same
+ * answer on every later poll. On /v1/validate and /v1/convert that is a 422
+ * (unprocessable document, or a conversion the engine will not do), a 413 (the
+ * document is over the size cap) and PARSE_FAILED, which also arrives as a 400.
+ * The status decides, not the code: VALIDATION_ERROR is a 400 for a rejected
+ * request and a 422 for a rejected document. Every other 4xx is about the
+ * caller (INVALID_API_KEY 403, QUOTA_EXCEEDED and RATE_LIMITED 429) and clears
+ * without the document changing. Codes and statuses per route:
+ * https://api.beliq.eu/openapi.json
+ */
+export function isDocumentRefusal(err) {
+    if (!(err instanceof BeliqApiError))
+        return false;
+    return err.status === HTTP_UNPROCESSABLE || err.status === HTTP_PAYLOAD_TOO_LARGE || err.code === 'PARSE_FAILED';
+}

package/dist/cli.js

@@ -11,9 +11,10 @@ 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.
+ * test without touching real streams. Returns the process exit code. Aborting
+ * `stop` ends the worker after the invoice in hand.
  */
-export async function main(argv, log, env = process.env) {
+export async function main(argv, log, env = process.env, stop) {
     let config;
     try {
         const args = parseArgs(argv);
@@ -41,7 +42,7 @@ export async function main(argv, log, env = process.env) {
             maxRetries: config.maxRetries,
         });
         const beliq = makeBeliqClient(config);
-        return await runWorker(config, { sevdesk, beliq, log });
+        return await runWorker(config, { sevdesk, beliq, log, stop });
     }
     catch (err) {
         if (err instanceof ConfigError) {

package/dist/errors.js

@@ -7,9 +7,19 @@ 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) {
+    /** What sevDesk sent with a non-2xx answer, cut to a loggable length. Empty when it sent nothing. */
+    body;
+    constructor(message, status, body = '') {
         super(message);
         this.name = 'SevDeskApiError';
         this.status = status;
+        this.body = body;
+    }
+}
+/** sevDesk has no XML for this invoice: it was not created as an e-invoice. Nothing to validate or convert. */
+export class NotAnEInvoiceError extends SevDeskApiError {
+    constructor(message, status, body = '') {
+        super(message, status, body);
+        this.name = 'NotAnEInvoiceError';
     }
 }

package/dist/exit.js

@@ -11,13 +11,14 @@ export const EXIT = {
     IO: 4,
 };
 export function emptyCounts() {
-    return { valid: 0, invalid: 0, error: 0 };
+    return { valid: 0, invalid: 0, error: 0, skipped: 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.
+ * CLI/Action contract, where "any invoice failed" maps to a non-zero exit. A
+ * skipped invoice is not a failure and does not move the exit code.
  */
 export function summaryExitCode(counts) {
     if (counts.error > 0)

package/dist/help.js

@@ -19,7 +19,7 @@ Options:
   --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)
+  --state <path>           state file, the invoice ids already processed (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)

package/dist/index.js

@@ -1,7 +1,13 @@
 #!/usr/bin/env node
 import { main } from './cli.js';
 import { nodeLogger } from './log.js';
-main(process.argv.slice(2), nodeLogger()).then((code) => {
+// Without a handler SIGTERM ends the process at once, mid-invoice and before the
+// state is saved. As PID 1 in a container it would not end the process at all.
+const stopping = new AbortController();
+for (const signal of ['SIGTERM', 'SIGINT']) {
+    process.once(signal, () => stopping.abort());
+}
+main(process.argv.slice(2), nodeLogger(), process.env, stopping.signal).then((code) => {
     process.exitCode = code;
 }, (err) => {
     process.stderr.write(`beliq-sevdesk: fatal: ${err.message}\n`);

package/dist/sevdesk.js

@@ -1,20 +1,30 @@
-import { SevDeskApiError } from './errors.js';
+import { NotAnEInvoiceError, SevDeskApiError } from './errors.js';
 /** A hard ceiling on pages walked per poll, so a misconfigured window can't loop forever. */
 const MAX_PAGES = 100;
 /** Per-attempt deadline so a stalled sevDesk connection aborts instead of hanging the poll. */
 const REQUEST_TIMEOUT_MS = 30_000;
+/** How much of a sevDesk error body goes into the error message and the log line. */
+const ERROR_BODY_MAX_CHARS = 300;
+const HTTP_BAD_REQUEST = 400;
+/**
+ * What sevDesk puts in `error.message`, with a 400, when getXml is asked for an
+ * invoice that was not created as an e-invoice. Its API documentation
+ * (https://api.sevdesk.de/openapi.yaml) lists that 400 as "Invoice was not
+ * found", but an unknown id answers 404. Both recorded from a live account:
+ * test/fixtures/sevdesk/.
+ */
+const NOT_AN_E_INVOICE_MESSAGE = 'This invoice is not an electronic invoice';
 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.
+ * Pull the XML out of a getXml response. sevDesk documents the answer as
+ * `{ objects: "<xml>" }` (https://api.sevdesk.de/openapi.yaml), and a live
+ * account answers exactly that: test/fixtures/sevdesk/getXml-e-invoice.json.
+ * The other shapes handled here (a raw XML body, `{ objects: { content, base64 } }`,
+ * a base64 payload) have not been seen from sevDesk.
  */
 export function extractXml(contentType, text) {
     if (contentType.includes('xml') || looksLikeXml(text))
@@ -96,13 +106,26 @@ export class SevDeskClient {
             for (const o of objects)
                 all.push(normalizeInvoice(o));
             if (objects.length < limit)
-                break;
+                return all;
         }
-        return all;
+        // Returning what was read so far would leave the invoices beyond the cap
+        // unprocessed with nothing to show for it.
+        throw new SevDeskApiError(`sevDesk invoice list did not end after ${MAX_PAGES} pages of ${limit}; ` +
+            'narrow it with SEVDESK_POLL_WINDOW_DAYS or raise SEVDESK_PAGE_SIZE', 200);
     }
     async getInvoiceXml(id) {
-        const { text, contentType } = await this.#request('GET', `/Invoice/${encodeURIComponent(id)}/getXml`);
-        return extractXml(contentType, text);
+        try {
+            const { text, contentType } = await this.#request('GET', `/Invoice/${encodeURIComponent(id)}/getXml`);
+            return extractXml(contentType, text);
+        }
+        catch (err) {
+            if (err instanceof SevDeskApiError &&
+                err.status === HTTP_BAD_REQUEST &&
+                err.body.includes(NOT_AN_E_INVOICE_MESSAGE)) {
+                throw new NotAnEInvoiceError(err.message, err.status, err.body);
+            }
+            throw err;
+        }
     }
     #parseObjects(text) {
         let parsed;
@@ -129,7 +152,7 @@ export class SevDeskClient {
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), this.#requestTimeoutMs);
             let res;
-            let text = '';
+            let text;
             try {
                 res = await this.#fetch(url.toString(), {
                     method,
@@ -137,8 +160,7 @@ export class SevDeskClient {
                     signal: controller.signal,
                 });
                 // Read the body under the same deadline so a stalled stream also aborts.
-                if (res.ok)
-                    text = await res.text();
+                text = await res.text();
             }
             catch (err) {
                 lastError = controller.signal.aborted
@@ -170,7 +192,8 @@ export class SevDeskClient {
                 throw new SevDeskApiError(`sevDesk ${method} ${path} returned an HTML 404: ${this.#baseUrl} is not the REST API. ` +
                     'The REST base is https://my.sevdesk.de/api/v1; check SEVDESK_BASE_URL.', res.status);
             }
-            throw new SevDeskApiError(`sevDesk ${method} ${path} failed with status ${res.status}`, res.status);
+            const body = text.trim().slice(0, ERROR_BODY_MAX_CHARS);
+            throw new SevDeskApiError(`sevDesk ${method} ${path} failed with status ${res.status}${body ? `: ${body}` : ''}`, res.status, body);
         }
         // Unreachable: the loop either returns or throws. Satisfies noImplicitReturns.
         throw new SevDeskApiError(`sevDesk ${method} ${path} exhausted retries`, 0);

package/dist/state.js

@@ -1,10 +1,12 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, rename, writeFile } from 'node:fs/promises';
 import { IoError } from './errors.js';
-const EMPTY = { lastInvoiceId: 0 };
+function invalid(path, what) {
+    return new IoError(`state file ${path} ${what}; fix or delete it to start fresh`);
+}
 /**
- * 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.
+ * Load the state. A missing file is the first-run case (nothing processed).
+ * A present-but-corrupt file throws IoError rather than silently starting
+ * empty, which would reprocess the entire account.
  */
 export async function loadState(path) {
     let text;
@@ -13,7 +15,7 @@ export async function loadState(path) {
     }
     catch (err) {
         if (err.code === 'ENOENT')
-            return { ...EMPTY };
+            return { processedIds: new Set() };
         throw new IoError(`could not read state file ${path}: ${err.message}`);
     }
     let parsed;
@@ -21,18 +23,29 @@ export async function loadState(path) {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new IoError(`state file ${path} is not valid JSON; fix or delete it to start fresh`);
+        throw invalid(path, 'is not valid JSON');
+    }
+    const { processedIds, lastInvoiceId, lastPolledAt } = (parsed ?? {});
+    const polledAt = typeof lastPolledAt === 'string' ? lastPolledAt : undefined;
+    if (processedIds !== undefined) {
+        if (!Array.isArray(processedIds) || processedIds.some((id) => typeof id !== 'string')) {
+            throw invalid(path, 'has a processedIds that is not a list of id strings');
+        }
+        return { processedIds: new Set(processedIds), lastPolledAt: polledAt };
     }
-    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`);
+        throw invalid(path, 'has neither processedIds nor a valid lastInvoiceId');
     }
-    const lastPolledAt = parsed.lastPolledAt;
-    return { lastInvoiceId, lastPolledAt: typeof lastPolledAt === 'string' ? lastPolledAt : undefined };
+    return { processedIds: new Set(), legacyLastInvoiceId: lastInvoiceId, lastPolledAt: polledAt };
 }
 export async function saveState(path, state) {
+    const processedIds = [...state.processedIds].sort((a, b) => Number(a) - Number(b));
+    // Written beside the target and renamed over it, so a crash mid-write leaves
+    // the previous file whole. A torn state file would stop every later run.
+    const partial = `${path}.tmp`;
     try {
-        await writeFile(path, `${JSON.stringify(state, null, 2)}\n`);
+        await writeFile(partial, `${JSON.stringify({ processedIds, lastPolledAt: state.lastPolledAt }, null, 2)}\n`);
+        await rename(partial, path);
     }
     catch (err) {
         throw new IoError(`could not write state file ${path}: ${err.message}`);

package/dist/worker.js

@@ -1,11 +1,20 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { IoError } from './errors.js';
-import { emptyCounts, summaryExitCode } from './exit.js';
+import { isDocumentRefusal } from './beliq.js';
+import { IoError, NotAnEInvoiceError, SevDeskApiError } from './errors.js';
+import { EXIT, emptyCounts, summaryExitCode } from './exit.js';
 import { loadState, saveState } from './state.js';
 import { notify } from './notify.js';
-/** Convert targets that produce a hybrid PDF rather than a standalone XML document. */
-const PDF_TARGETS = new Set(['facturx', 'zugferd']);
+/** Convert targets that take a Factur-X / ZUGFeRD profile. */
+const PROFILED_TARGETS = new Set(['facturx', 'zugferd']);
+/**
+ * The file extension for what beliq sent back. A conversion to facturx or
+ * zugferd is a PDF only when the source was a hybrid PDF. sevDesk's getXml gives
+ * XML, and from XML beliq returns XML, so the target's name does not decide this.
+ */
+function extensionFor(contentType) {
+    return contentType.includes('pdf') ? 'pdf' : 'xml';
+}
 /** Seconds in a day, for the poll-window date filter. */
 const SECONDS_PER_DAY = 86_400;
 function safeName(inv) {
@@ -30,22 +39,69 @@ async function writeOutput(dir, name, bytes) {
     }
 }
 /**
- * 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.
+ * Run one invoice through the pipeline: pull its XML, validate it for an
+ * independent authority-pinned verdict sevDesk does not provide, then convert it
+ * to each configured target and write the bytes out. Validation runs first so a
+ * conversion beliq refuses cannot cost the verdict.
+ *
+ * An invoice sevDesk holds no XML for is skipped for good. A refusal about the
+ * document itself is final too: the same bytes get the same answer next poll. Anything else that throws (sevDesk, the network, a spent
+ * quota, a full disk) propagates, and the caller leaves the invoice for the
+ * 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,
+    let xml;
+    try {
+        xml = await deps.sevdesk.getInvoiceXml(inv.id);
+    }
+    catch (err) {
+        if (!(err instanceof NotAnEInvoiceError))
+            throw err;
+        deps.log.info('invoice.skipped', { id: inv.id, number: inv.invoiceNumber, reason: 'not an e-invoice' });
+        return { classification: 'skipped', final: true };
+    }
+    let valid;
+    try {
+        const verdict = await deps.beliq.validate(xml, {});
+        valid = verdict.valid;
+        deps.log.info('validate', {
+            id: inv.id,
+            number: inv.invoiceNumber,
+            valid,
+            errors: verdict.errors?.length ?? 0,
+            warnings: verdict.warnings?.length ?? 0,
+            classification: valid ? 'valid' : 'invalid',
+        });
+    }
+    catch (err) {
+        if (!isDocumentRefusal(err))
+            throw err;
+        deps.log.error('validate.refused', {
+            id: inv.id,
+            number: inv.invoiceNumber,
+            status: err.status,
+            code: err.code,
+            message: err.message,
         });
-        const ext = PDF_TARGETS.has(target) ? 'pdf' : 'xml';
-        const file = `${safeName(inv)}-${target}.${ext}`;
+        return { classification: 'error', final: true };
+    }
+    let refused = false;
+    for (const target of config.targetFormats) {
+        let result;
+        try {
+            result = await deps.beliq.convert(xml, {
+                targetFormat: target,
+                targetProfile: PROFILED_TARGETS.has(target) ? config.targetProfile : undefined,
+            });
+        }
+        catch (err) {
+            if (!isDocumentRefusal(err))
+                throw err;
+            refused = true;
+            deps.log.error('convert.refused', { id: inv.id, target, status: err.status, code: err.code, message: err.message });
+            continue;
+        }
+        const file = `${safeName(inv)}-${target}.${extensionFor(result.contentType)}`;
         const lostElements = result.meta.lostElementsCount ?? 0;
         if (config.dryRun) {
             deps.log.info('convert.dryRun', { id: inv.id, target, file, lostElements });
@@ -55,29 +111,21 @@ async function processInvoice(inv, config, deps) {
             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;
+    // An invalid document keeps its verdict. A valid one that beliq would not
+    // convert is an error: the file the operator asked for does not exist.
+    if (!valid)
+        return { classification: 'invalid', final: true };
+    return { classification: refused ? 'error' : 'valid', final: true };
 }
 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`;
+    return `${prefix}processed ${fresh} invoice(s): ${counts.valid} valid, ${counts.invalid} invalid, ${counts.error} error, ${counts.skipped} skipped`;
 }
 /**
- * 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.
+ * Poll sevDesk once: fetch invoices in the configured status/window and process
+ * every one whose id is not yet in the processed set, in ascending id order.
+ * Each invoice stands alone: one that errors is left out of the set and comes
+ * back next poll, and the invoices after it are still processed.
  */
 export async function pollOnce(config, deps) {
     const now = deps.now ?? (() => Date.now());
@@ -91,50 +139,62 @@ export async function pollOnce(config, deps) {
         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);
+    const processed = new Set(state.processedIds);
+    const legacyMark = state.legacyLastInvoiceId;
+    if (legacyMark !== undefined) {
+        // A pre-0.3.0 state file holds one number. Every listed invoice at or below
+        // it counts as done, which includes drafts the old worker skipped: the mark
+        // cannot tell the two apart.
+        for (const inv of invoices) {
+            if (Number(inv.id) <= legacyMark)
+                processed.add(inv.id);
+        }
+    }
+    const known = processed.size;
+    // Keyed by id: offset paging can hand back one invoice on two pages.
+    const fresh = [...new Map(invoices.map((inv) => [inv.id, inv])).values()]
+        .filter((inv) => !processed.has(inv.id))
+        .sort((a, b) => Number(a.id) - Number(b.id));
     deps.log.info('poll', {
         status: config.status,
-        since: state.lastInvoiceId,
+        known,
         listed: invoices.length,
         fresh: fresh.length,
     });
     const counts = emptyCounts();
     const outcomes = [];
-    let highWater = state.lastInvoiceId;
-    let blocked = false;
-    for (const { inv, idNum } of fresh) {
-        let classification;
+    for (const inv of fresh) {
+        if (deps.stop?.aborted) {
+            deps.log.info('poll.stopped', { unprocessed: fresh.length - outcomes.length });
+            break;
+        }
+        let result;
         try {
-            classification = await processInvoice(inv, config, deps);
+            result = await processInvoice(inv, config, deps);
         }
         catch (err) {
-            classification = 'error';
+            result = { classification: 'error', final: false };
             deps.log.error('invoice.error', {
                 id: inv.id,
                 number: inv.invoiceNumber,
                 message: err.message,
             });
         }
-        counts[classification]++;
-        outcomes.push({ id: inv.id, invoiceNumber: inv.invoiceNumber, classification });
-        if (classification === 'error')
-            blocked = true;
-        else if (!blocked)
-            highWater = idNum;
+        counts[result.classification]++;
+        outcomes.push({ id: inv.id, invoiceNumber: inv.invoiceNumber, classification: result.classification });
+        if (result.final)
+            processed.add(inv.id);
     }
-    if (!config.dryRun && highWater > state.lastInvoiceId) {
+    if (!config.dryRun && (processed.size > state.processedIds.size || legacyMark !== undefined)) {
         await saveState(config.stateFile, {
-            lastInvoiceId: highWater,
+            processedIds: processed,
             lastPolledAt: new Date(now()).toISOString(),
         });
     }
-    const summary = formatSummary(counts, fresh.length, config.dryRun);
+    const summary = formatSummary(counts, outcomes.length, config.dryRun);
     deps.log.summary(summary);
     await maybeNotify(config, deps, counts, outcomes, summary, now);
-    return { counts, processedTo: highWater };
+    return { counts };
 }
 /**
  * Fire the notify webhook when configured. Skipped in a dry run (a dry run has no
@@ -157,19 +217,46 @@ async function maybeNotify(config, deps, counts, outcomes, summary, now) {
     };
     await notify(url, report, { fetch: deps.fetch ?? fetch, log: deps.log });
 }
+/** A timer that ends early when the worker is told to stop. */
+function sleepUntilStopped(ms, stop) {
+    return new Promise((resolve) => {
+        if (stop?.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            stop?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        stop?.addEventListener('abort', done, { once: true });
+    });
+}
 /**
  * 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.
+ * CI/cron contract). Otherwise loop, polling every interval, until deps.stop is
+ * aborted. In the loop a poll that sevDesk fails (unreachable, or an error
+ * answer after retries) is logged and the next poll runs on schedule. A local
+ * fault, such as an unreadable state file, still ends the worker: polling again
+ * cannot fix it.
  */
 export async function runWorker(config, deps) {
-    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const sleep = deps.sleep ?? ((ms) => sleepUntilStopped(ms, deps.stop));
     if (config.once) {
         const { counts } = await pollOnce(config, deps);
         return summaryExitCode(counts);
     }
-    for (;;) {
-        await pollOnce(config, deps);
+    while (!deps.stop?.aborted) {
+        try {
+            await pollOnce(config, deps);
+        }
+        catch (err) {
+            if (!(err instanceof SevDeskApiError))
+                throw err;
+            deps.log.error('poll.error', { status: err.status, message: err.message });
+        }
+        if (deps.stop?.aborted)
+            break;
         await sleep(config.intervalSeconds * 1000);
     }
+    return EXIT.OK;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beliq-sevdesk",
-  "version": "0.2.4",
+  "version": "0.3.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",
@@ -51,6 +51,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
+    "pretest": "npm run build",
     "test": "vitest run --exclude test/integration.test.ts",
     "test:integration": "vitest run test/integration.test.ts",
     "scrub:check": "bash scripts/scrub-check.sh",
@@ -60,11 +61,12 @@
     "@beliq/sdk": "^0.4.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/node": "^20.14.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^8.57.0",
+    "eslint": "^10.11.0",
+    "globals": "^17.12.0",
     "typescript": "^5.5.4",
+    "typescript-eslint": "^8.70.1",
     "vitest": "^4.0.0"
   }
 }