From 29ea9fafd8228cc9edf8bf2cfc4dfca79b46e6ea Mon Sep 17 00:00:00 2001 From: Marco Date: Thu, 23 Jul 2026 12:12:51 +0000 Subject: [PATCH] Phase 4: Mustang EN16931/PDF-A-3 validation in CI Adds a Gitea Actions workflow that generates realistic e-invoice fixtures (multi-VAT-rate original invoice, Storno, Gutschrift) and validates them against the reference Mustang validator on every push, catching a broken EN16931 mapping before it reaches production instead of relying on manual spot-checks. --- .gitea/workflows/validate-einvoice.yml | 46 +++ .gitignore | 1 + README.md | 11 + package-lock.json | 504 +++++++++++++++++++++++++ package.json | 4 +- scripts/generate-einvoice-fixtures.mts | 109 ++++++ 6 files changed, 674 insertions(+), 1 deletion(-) create mode 100644 .gitea/workflows/validate-einvoice.yml create mode 100644 scripts/generate-einvoice-fixtures.mts diff --git a/.gitea/workflows/validate-einvoice.yml b/.gitea/workflows/validate-einvoice.yml new file mode 100644 index 0000000..dd84833 --- /dev/null +++ b/.gitea/workflows/validate-einvoice.yml @@ -0,0 +1,46 @@ +name: Validate e-invoices + +# Phase 4 of the e-invoicing migration (see the payload repo's memory notes +# on the full 6-phase plan) — generates a small set of realistic Factur-X +# fixtures (scripts/generate-einvoice-fixtures.mts: multi-VAT-rate original +# invoice, Stornorechnung, Gutschrift) and validates them with Mustang, the +# reference ZUGFeRD/Factur-X/EN16931 + PDF/A-3 validator. Runs on the +# self-hosted vps-runner (git.mk360.de's own Gitea Actions runner, Docker +# execution mode) — see /home/marco/dev/docker/docker-compose.yml's +# act_runner service comment for the trust-boundary notes. +on: + push: + pull_request: + +jobs: + mustang: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 24 + + - name: Install dependencies + run: npm ci + + - name: Generate e-invoice fixtures + run: npm run fixtures:einvoice + + - uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: "21" + + - name: Download Mustang-CLI + run: | + curl -fsSL -o mustang-cli.jar https://github.com/ZUGFeRD/mustangproject/releases/download/core-2.24.0/Mustang-CLI-2.24.0.jar + echo "e4904ffa0afdce3f5836dceb927c440a05ed5d60386fdd37e17a4b2f7652edbf mustang-cli.jar" | sha256sum -c - + + # validateExpectValid recursively checks every file under -d and + # exits non-zero if any of them fails EN16931/PDF-A-3 conformance — + # covers all 3 fixtures (original invoice, Stornorechnung, + # Gutschrift) in one call. + - name: Validate fixtures against EN16931 (Mustang) + run: java -Xmx1G -Dfile.encoding=UTF-8 -jar mustang-cli.jar --no-notices --action validateExpectValid -d .mustang-fixtures diff --git a/.gitignore b/.gitignore index c2658d7..caa315d 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ node_modules/ +.mustang-fixtures/ diff --git a/README.md b/README.md index 793fda7..9e98c33 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,8 @@ One canonical implementation, consumed by both repos, makes this class of drift **2026-07-23, Phase 3: actual e-invoicing.** `renderInvoiceEInvoice()`/`renderCorrectionInvoiceEInvoice()` (in `einvoice/`) produce a ZUGFeRD/Factur-X hybrid PDF/A-3 with an embedded EN16931 XML instead of a plain PDF — see "E-invoicing" below. +**2026-07-23, Phase 4: CI validation.** `.gitea/workflows/validate-einvoice.yml` runs on every push/PR (via git.mk360.de's own self-hosted Gitea Actions runner) — see "CI validation (Mustang)" below. + ## How this is consumed Not published to npm — installed as a git dependency: @@ -51,3 +53,12 @@ Ships raw TypeScript/TSX source (no build step) via `main`/`types` pointing stra - Payment means: included whenever `seller.iban` is set (matching the visual PDF footer's own "always show it" behavior since Phase 2), with a `PaymentMeansCode` mapped from the order's actual `paymentMethodTitle` (`Überweisung` → `30` credit transfer, `Kreditkarte` → `48`, `PayPal` → `68`, anything unrecognized → `1` "Instrument not defined" — a payment method added in Payload doesn't need a matching code deploy here to keep e-invoice generation working). - **`einvoice/countryCode.ts`** — `sellerCountry`/`order.country` are free text ("Deutschland"), not an ISO-3166 select field, but EN16931 wants a fixed two-letter code. Small closed mapping (DACH region only, this shop's actual shipping footprint), falling back to `DE`. - **Library: `@e-invoice-eu/core`**, format `'Factur-X-EN16931'` (the ZUGFeRD "Comfort" profile, the minimum EN16931-compliant level). Verified by actually generating a sample invoice from `SAMPLE_INVOICE_ORDER` and inflating the embedded XML stream out of the resulting PDF/A-3 by hand (the library ships no attachment-reading API of its own to check this against) — confirmed correct `CrossIndustryInvoice` XML, EN16931 guideline reference, per-rate tax breakdown, and payment means, not just "it didn't throw." + +## CI validation (Mustang) + +Every push/PR runs `.gitea/workflows/validate-einvoice.yml` against git.mk360.de's own self-hosted Gitea Actions runner (`vps-runner`, registered on the same VPS as Gitea/Payload — see `/home/marco/dev/docker/docker-compose.yml`'s `act_runner` service): + +1. `npm run fixtures:einvoice` (`scripts/generate-einvoice-fixtures.mts`) renders 3 PDFs into `.mustang-fixtures/` (gitignored, regenerated every run) — an original invoice with **two simultaneous VAT rates (19%+7%) plus a discount and shipping cost together** (the combination `SAMPLE_INVOICE_ORDER` doesn't cover), plus a Storno and a Gutschrift against the same order. +2. [Mustang-CLI](https://www.mustangproject.org/commandline/) (the reference ZUGFeRD/Factur-X validator, `--action validateExpectValid -d .mustang-fixtures`) checks all 3 for EN16931 + PDF/A-3 conformance in one call. Non-zero exit fails the job. The jar is downloaded pinned to a specific release + sha256 (`core-2.24.0`) rather than a floating `latest` tag, right in the workflow — no Docker image for Mustang is actively maintained by the upstream project itself, so downloading the jar directly into a `setup-java` step was simpler and more trustworthy than depending on a third-party wrapper image. + +Run the same check locally with `npm run fixtures:einvoice`, then point a locally-downloaded `Mustang-CLI-*.jar` at `.mustang-fixtures/` yourself — useful for iterating on `buildEInvoiceData.ts` without waiting on a CI round-trip. diff --git a/package-lock.json b/package-lock.json index c310476..2c858a2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,6 +16,7 @@ "@types/react": "^19", "eslint": "^9", "react": "^19.2.4", + "tsx": "^4.19.2", "typescript": "^5", "vitest": "^4.1.10" }, @@ -133,6 +134,448 @@ "tslib": "^2.4.0" } }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz", + "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz", + "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz", + "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz", + "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz", + "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz", + "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz", + "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz", + "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz", + "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz", + "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz", + "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz", + "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz", + "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz", + "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz", + "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz", + "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz", + "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz", + "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz", + "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz", + "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz", + "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz", + "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz", + "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz", + "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz", + "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz", + "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, "node_modules/@esgettext/runtime": { "version": "1.3.10", "resolved": "https://registry.npmjs.org/@esgettext/runtime/-/runtime-1.3.10.tgz", @@ -1526,6 +1969,48 @@ "dev": true, "license": "MIT" }, + "node_modules/esbuild": { + "version": "0.28.1", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz", + "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.1", + "@esbuild/android-arm": "0.28.1", + "@esbuild/android-arm64": "0.28.1", + "@esbuild/android-x64": "0.28.1", + "@esbuild/darwin-arm64": "0.28.1", + "@esbuild/darwin-x64": "0.28.1", + "@esbuild/freebsd-arm64": "0.28.1", + "@esbuild/freebsd-x64": "0.28.1", + "@esbuild/linux-arm": "0.28.1", + "@esbuild/linux-arm64": "0.28.1", + "@esbuild/linux-ia32": "0.28.1", + "@esbuild/linux-loong64": "0.28.1", + "@esbuild/linux-mips64el": "0.28.1", + "@esbuild/linux-ppc64": "0.28.1", + "@esbuild/linux-riscv64": "0.28.1", + "@esbuild/linux-s390x": "0.28.1", + "@esbuild/linux-x64": "0.28.1", + "@esbuild/netbsd-arm64": "0.28.1", + "@esbuild/netbsd-x64": "0.28.1", + "@esbuild/openbsd-arm64": "0.28.1", + "@esbuild/openbsd-x64": "0.28.1", + "@esbuild/openharmony-arm64": "0.28.1", + "@esbuild/sunos-x64": "0.28.1", + "@esbuild/win32-arm64": "0.28.1", + "@esbuild/win32-ia32": "0.28.1", + "@esbuild/win32-x64": "0.28.1" + } + }, "node_modules/escape-string-regexp": { "version": "4.0.0", "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz", @@ -3081,6 +3566,25 @@ "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", "license": "0BSD" }, + "node_modules/tsx": { + "version": "4.23.1", + "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.23.1.tgz", + "integrity": "sha512-GQHnkIfxyx1wYCOS/wonik5MVRZU9hi1TEZmzGZSCJB1y9YgoZ8H6itNE/u4suE+yLmOzuE4E5S4TZ/ZX2wcWQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "~0.28.0" + }, + "bin": { + "tsx": "dist/cli.mjs" + }, + "engines": { + "node": ">=18.0.0" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + } + }, "node_modules/type-check": { "version": "0.4.0", "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz", diff --git a/package.json b/package.json index d26ee78..bf76a81 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,8 @@ "scripts": { "typecheck": "tsc --noEmit", "test": "vitest run", - "lint": "eslint ." + "lint": "eslint .", + "fixtures:einvoice": "tsx scripts/generate-einvoice-fixtures.mts" }, "peerDependencies": { "@react-pdf/renderer": "^4.0.0", @@ -31,6 +32,7 @@ "@types/react": "^19", "eslint": "^9", "react": "^19.2.4", + "tsx": "^4.19.2", "typescript": "^5", "vitest": "^4.1.10" }, diff --git a/scripts/generate-einvoice-fixtures.mts b/scripts/generate-einvoice-fixtures.mts new file mode 100644 index 0000000..eaba71e --- /dev/null +++ b/scripts/generate-einvoice-fixtures.mts @@ -0,0 +1,109 @@ +// Generates a small set of realistic Factur-X-EN16931 PDFs into +// .mustang-fixtures/ (gitignored) — run by CI (see +// .gitea/workflows/validate-einvoice.yml) as the input to Mustang's own +// EN16931/PDF-A-3 conformance check. Kept as a separate script rather than +// re-exporting SAMPLE_INVOICE_ORDER's single-VAT-rate fixture, so this can +// exercise the shapes that fixture doesn't: multiple simultaneous VAT +// rates, a discount + shipping cost together, and both correction-invoice +// kinds (Storno = full reversal, Gutschrift = partial return). +import { writeFile, mkdir } from "node:fs/promises"; +import { renderInvoiceEInvoice, renderCorrectionInvoiceEInvoice } from "../src/einvoice/index.js"; +import type { InvoiceOrder } from "../src/invoicePdf.js"; +import type { CorrectionInvoiceOrder } from "../src/correctionInvoicePdf.js"; +import type { InvoiceSeller } from "../src/seller.js"; + +const OUT_DIR = new URL("../.mustang-fixtures/", import.meta.url); + +// A fully-populated seller — including bankName/iban/bic and the +// registered-legal-form fields — so the generated XML exercises every +// optional branch buildEInvoiceData.ts has (PaymentMeans, register +// court/number, managing director), not just the sole-proprietorship +// minimum this shop's own production data happens to use today. +const SELLER: InvoiceSeller = { + sellerName: "Mustang Test GmbH", + sellerStreet: "Teststraße 1", + sellerZip: "10115", + sellerCity: "Berlin", + sellerCountry: "Deutschland", + sellerEmail: "rechnung@example.com", + vatId: "DE123456789", + taxRatePercent: 19, + bankName: "Test Bank", + iban: "DE89370400440532013000", + bic: "COBADEFFXXX", + registerCourt: "Amtsgericht Berlin (Charlottenburg)", + registerNumber: "HRB 123456", + managingDirector: "Max Mustermann", +}; + +// Two simultaneous VAT rates (19% + 7%) plus a discount and a nonzero +// shipping cost — the combination SAMPLE_INVOICE_ORDER doesn't cover, and +// exactly where a tax-breakdown/rounding bug would first show up. +const ORDER: InvoiceOrder = { + orderNumber: "#EP-MUSTANG-0001", + invoiceNumber: "RE-MUSTANG-0001", + invoiceIssuedAt: new Date().toISOString(), + customerFirstName: "Erika", + customerLastName: "Musterfrau", + deliveryMethod: "address", + street: "Kundenweg 2", + zip: "80331", + city: "München", + country: "Deutschland", + paymentMethodTitle: "Kreditkarte", + items: [ + { productName: "ToDo-Karten – Set", quantity: 2, unitPrice: 12.9, taxRatePercent: 19, bundleContents: null }, + { productName: "Fachbuch – Produktivität", quantity: 1, unitPrice: 24.0, taxRatePercent: 7, bundleContents: null }, + ], + subtotal: 49.8, + shippingCost: 4.95, + discountAmount: 5, + discountCode: "MUSTANG5", + total: 49.75, +}; + +const CORRECTION_ORDER: CorrectionInvoiceOrder = { + orderNumber: ORDER.orderNumber, + invoiceNumber: ORDER.invoiceNumber, + invoiceIssuedAt: ORDER.invoiceIssuedAt, + correctionInvoiceNumber: "RK-MUSTANG-0001", + correctionInvoiceIssuedAt: new Date().toISOString(), + customerFirstName: ORDER.customerFirstName, + customerLastName: ORDER.customerLastName, + deliveryMethod: ORDER.deliveryMethod, + street: ORDER.street, + zip: ORDER.zip, + city: ORDER.city, + country: ORDER.country, + items: [ + { productName: "ToDo-Karten – Set", quantity: 2, unitPrice: 12.9, taxRatePercent: 19, bundleContents: null, returnQuantity: 1 }, + { productName: "Fachbuch – Produktivität", quantity: 1, unitPrice: 24.0, taxRatePercent: 7, bundleContents: null, returnQuantity: 0 }, + ], + subtotal: ORDER.subtotal, + shippingCost: ORDER.shippingCost, + discountAmount: ORDER.discountAmount, + total: ORDER.total, +}; + +async function main() { + await mkdir(OUT_DIR, { recursive: true }); + + const invoice = await renderInvoiceEInvoice(ORDER, SELLER); + await writeFile(new URL("original-invoice.pdf", OUT_DIR), invoice); + + // Storno: every item at full ordered quantity (resolveLineItems ignores + // returnQuantity for this kind) — CORRECTION_ORDER's returnQuantity + // values are only meaningful for the Gutschrift render below. + const storno = await renderCorrectionInvoiceEInvoice("storno", CORRECTION_ORDER, SELLER); + await writeFile(new URL("stornorechnung.pdf", OUT_DIR), storno); + + const gutschrift = await renderCorrectionInvoiceEInvoice("gutschrift", CORRECTION_ORDER, SELLER); + await writeFile(new URL("gutschrift.pdf", OUT_DIR), gutschrift); + + console.log(`Wrote 3 e-invoice fixtures to ${OUT_DIR.pathname}`); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +});