beliq-sevdesk 0.1.0 → 0.2.0

package/README.md

@@ -77,6 +77,71 @@ A cron entry that runs it every 15 minutes:
 */15 * * * * SEVDESK_API_TOKEN=... BELIQ_API_KEY=... SEVDESK_TARGET_FORMATS=peppol-bis /usr/bin/beliq-sevdesk --once >> /var/log/beliq-sevdesk.log 2>&1
 ```
 
+## Run it in a container
+
+A prebuilt multi-arch image (amd64 + arm64) is published to GitHub Container
+Registry:
+
+```bash
+docker pull ghcr.io/beliq-eu/beliq-sevdesk:latest
+```
+
+The image ships only the compiled worker and `@beliq/sdk` from the public npm
+registry. No private beliq source is in it: all validation and conversion happen
+on the beliq API over HTTPS.
+
+The container's entrypoint is the worker, so arguments pass straight through. Run
+a single poll:
+
+```bash
+docker run --rm \
+  -e SEVDESK_API_TOKEN -e BELIQ_API_KEY -e SEVDESK_TARGET_FORMATS=peppol-bis \
+  -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
+the converted documents across restarts. With no arguments the container loops as
+a daemon.
+
+## Example recipes
+
+Ready-to-copy deployment recipes are in [examples/](examples/):
+
+- [docker-compose.yml](examples/docker-compose.yml) runs it as a restart-on-failure daemon.
+- [beliq-sevdesk.service](examples/beliq-sevdesk.service) + [beliq-sevdesk.timer](examples/beliq-sevdesk.timer) run it natively on a systemd timer (no Docker).
+- [github-actions-cron.yml](examples/github-actions-cron.yml) polls on a schedule from GitHub Actions, failing the run when an invoice fails.
+
+## Notify on failures
+
+Set a webhook to get a JSON report POSTed after a poll:
+
+```bash
+export SEVDESK_NOTIFY_WEBHOOK=https://hooks.example.com/your/endpoint
+# SEVDESK_NOTIFY_ON=failure (default) posts only when an invoice fails;
+# SEVDESK_NOTIFY_ON=always posts after every poll (a heartbeat, good for cron).
+```
+
+The body:
+
+```json
+{
+  "ok": false,
+  "summary": "processed 2 invoice(s): 1 valid, 1 invalid, 0 error",
+  "counts": { "valid": 1, "invalid": 1, "error": 0 },
+  "invoices": [
+    { "id": "10", "invoiceNumber": "INV-10", "classification": "valid" },
+    { "id": "11", "invoiceNumber": "INV-11", "classification": "invalid" }
+  ],
+  "polledAt": "2025-06-15T12:00:00.000Z"
+}
+```
+
+Notify is best-effort: a slow, dead, or non-2xx endpoint is logged (host only, so
+a secret in the webhook path is never printed) and never changes the exit code.
+The exit code always reflects the invoices, not the notification.
+
 ## Configuration
 
 Every setting is read from the environment; the flags below override the matching
@@ -95,6 +160,8 @@ variable.
 | `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_NOTIFY_WEBHOOK` | `--notify-webhook` | (none) | POST a JSON poll report here. Empty = no notifications. |
+| `SEVDESK_NOTIFY_ON` | | `failure` | `failure` (only on a failed invoice) or `always` (every poll). |
 | `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`. |
@@ -139,6 +206,9 @@ npm run build
 npm test              # unit tests, no network
 npm run scrub:check   # no em-dash
 
+# build the container image locally:
+docker build -t beliq-sevdesk .
+
 # live smoke against the real sevDesk + beliq APIs (skipped without creds):
 SEVDESK_API_TOKEN=... BELIQ_API_KEY=... npm run test:integration
 ```

package/dist/args.js

@@ -15,6 +15,7 @@ const VALUE_FLAGS = new Set([
     'interval',
     'api-key',
     'sevdesk-token',
+    'notify-webhook',
 ]);
 /**
  * Parse argv into flags. Hand-rolled (no dependency): the surface is small and

package/dist/config.js

@@ -51,6 +51,27 @@ function resolveProfile(raw) {
     }
     return raw;
 }
+function resolveNotifyWebhook(raw) {
+    if (!raw)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new ConfigError(`invalid notify webhook URL "${raw}"`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new ConfigError(`notify webhook must be an http(s) URL, got "${parsed.protocol}"`);
+    }
+    return raw;
+}
+function resolveNotifyOn(raw) {
+    const value = (raw ?? 'failure').trim().toLowerCase();
+    if (value === 'failure' || value === 'always')
+        return value;
+    throw new ConfigError(`invalid SEVDESK_NOTIFY_ON "${raw}". Use "failure" or "always".`);
+}
 /**
  * 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
@@ -85,5 +106,7 @@ export function resolveConfig(args, env = process.env) {
         maxRetries: parseIntEnv(env.SEVDESK_MAX_RETRIES, 4, 'max retries'),
         once: flagBool(args, 'once'),
         dryRun: flagBool(args, 'dry-run'),
+        notifyWebhook: resolveNotifyWebhook(pick(args, 'notify-webhook', env, 'SEVDESK_NOTIFY_WEBHOOK')),
+        notifyOn: resolveNotifyOn(env.SEVDESK_NOTIFY_ON),
     };
 }

package/dist/help.js

@@ -24,6 +24,7 @@ Options:
   --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)
+  --notify-webhook <url>   POST a JSON poll report here (default: SEVDESK_NOTIFY_WEBHOOK)
   -h, --help               show this help
   -v, --version            show the version
 
@@ -36,4 +37,7 @@ Exit codes (meaningful with --once):
 
 Set SEVDESK_API_TOKEN (Settings -> Advanced -> API) and BELIQ_API_KEY (beliq
 dashboard -> API Keys). The sevDesk token never leaves this environment.
+
+With a notify webhook set, SEVDESK_NOTIFY_ON=failure (default) POSTs only when an
+invoice fails; SEVDESK_NOTIFY_ON=always POSTs after every poll.
 `;

package/dist/notify.js

@@ -0,0 +1,44 @@
+/**
+ * Best-effort webhook timeout. Notify is a side channel; a slow or dead endpoint
+ * must never stall the worker or change the run's verdict.
+ */
+const NOTIFY_TIMEOUT_MS = 10_000;
+/** Host only, so a webhook that carries a secret in its path is not logged. */
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return 'invalid-url';
+    }
+}
+/**
+ * POST the poll report to the notify webhook. Best-effort by design: a non-2xx
+ * response, a network failure, or a timeout is logged (host only, never the full
+ * URL) and swallowed. This function never throws, so the exit code stays a
+ * faithful signal of the invoices themselves, not of the notification.
+ */
+export async function notify(url, report, deps) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), NOTIFY_TIMEOUT_MS);
+    try {
+        const res = await deps.fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(report),
+            signal: controller.signal,
+        });
+        if (res.ok) {
+            deps.log.info('notify', { host: safeHost(url), status: res.status });
+        }
+        else {
+            deps.log.error('notify.error', { host: safeHost(url), status: res.status });
+        }
+    }
+    catch (err) {
+        deps.log.error('notify.error', { host: safeHost(url), message: err.message });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/worker.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { IoError } from './errors.js';
 import { 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']);
 /** Seconds in a day, for the poll-window date filter. */
@@ -101,6 +102,7 @@ export async function pollOnce(config, deps) {
         fresh: fresh.length,
     });
     const counts = emptyCounts();
+    const outcomes = [];
     let highWater = state.lastInvoiceId;
     let blocked = false;
     for (const { inv, idNum } of fresh) {
@@ -117,6 +119,7 @@ export async function pollOnce(config, deps) {
             });
         }
         counts[classification]++;
+        outcomes.push({ id: inv.id, invoiceNumber: inv.invoiceNumber, classification });
         if (classification === 'error')
             blocked = true;
         else if (!blocked)
@@ -128,9 +131,32 @@ export async function pollOnce(config, deps) {
             lastPolledAt: new Date(now()).toISOString(),
         });
     }
-    deps.log.summary(formatSummary(counts, fresh.length, config.dryRun));
+    const summary = formatSummary(counts, fresh.length, config.dryRun);
+    deps.log.summary(summary);
+    await maybeNotify(config, deps, counts, outcomes, summary, now);
     return { counts, processedTo: highWater };
 }
+/**
+ * Fire the notify webhook when configured. Skipped in a dry run (a dry run has no
+ * side effects). With notifyOn=failure it POSTs only when an invoice failed; with
+ * notifyOn=always it POSTs after every poll (a heartbeat, best for --once/cron).
+ */
+async function maybeNotify(config, deps, counts, outcomes, summary, now) {
+    const url = config.notifyWebhook;
+    if (!url || config.dryRun)
+        return;
+    const failed = counts.invalid + counts.error > 0;
+    if (config.notifyOn === 'failure' && !failed)
+        return;
+    const report = {
+        ok: !failed,
+        summary,
+        counts,
+        invoices: outcomes,
+        polledAt: new Date(now()).toISOString(),
+    };
+    await notify(url, report, { fetch: deps.fetch ?? fetch, log: deps.log });
+}
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beliq-sevdesk",
-  "version": "0.1.0",
+  "version": "0.2.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",