From e3d575e73b6c453311e44643af975827d9fcecb4 Mon Sep 17 00:00:00 2001 From: Marco Date: Fri, 31 Jul 2026 13:00:04 +0000 Subject: [PATCH] Add customer-onboarding section to README New clients licensing this module need setup steps (git dependency, transpilePackages, peer deps, which VAT/e-invoicing flags to wire up) up front, not buried in the changelog below. Co-Authored-By: Claude Sonnet 5 --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 17a2cfd..2f61699 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,23 @@ Shared invoice / correction-invoice (Stornorechnung, Gutschrift) PDF generation - `einfach-produktiv` (the Next.js storefront — generates the original invoice at checkout, plus on-demand re-downloads of both document types) - `payload` (the Payload CMS backend — generates the authoritative Stornorechnung/Gutschrift the moment an order's status changes) +## Onboarding a new client with this module + +This package is the reference example for "modular, separately licensable" pieces of this stack — module + paid integration per client, not a hosted SaaS. To bring a new client onto it: + +1. **Install as a git dependency**, not from npm (see "How this is consumed" below): + ```json + "@einfach-produktiv/invoicing": "git+https://git.mk360.de/Marco/einfach-produktiv-invoicing.git#main" + ``` + Pin to `#main` unless the client needs a specific historical version — there's no separate release/tag process today, `main` is always the current shipping state. +2. **Add it to `transpilePackages`** in the consumer's `next.config.ts` — it ships raw TS/TSX, no build step (see "How this is consumed"). +3. **Provide `react` and `@react-pdf/renderer`** yourself — both are peer dependencies, not bundled. +4. **Feed it structured seller/order data** matching `InvoiceSeller`/`InvoiceOrder`/`CorrectionInvoiceOrder` (see `src/seller.ts`, `src/invoicePdf.tsx`) — this package renders PDFs and computes tax breakdowns, it does not fetch or own any of that data itself. Decide upfront: does this client need Kleinunternehmerregelung (§19 UStG)? Cross-border VAT exemption (innergemeinschaftliche Lieferung)? Both are supported but each needs the *consuming* app's own checkout logic to detect and pass the right flag (see "VAT exemption"/"Kleinunternehmerregelung" sections below) — this package never decides either on its own. +5. **Decide whether the client needs e-invoicing** (ZUGFeRD/Factur-X, mandatory for German B2B from 2027 onward) — if yes, wire up `renderInvoiceEInvoice`/`renderCorrectionInvoiceEInvoice` (see "E-invoicing" below) instead of the plain PDF renderers; if the client only sells B2C for now, the plain renderers are sufficient and simpler. +6. **Known gotcha to check for this specific client**: if their `company-settings.iban` might ever be unset, fix the `@e-invoice-eu/core` crash noted at the end of "E-invoicing" below *before* going live — it currently only doesn't affect the original tenant because their IBAN is always set. + +Everything below this point is the module's own development history/changelog and technical reference — read it for the "why" behind any given behavior, not as a first-time setup guide. + ## Why this exists Before this package, `taxBreakdown.ts` and `correctionInvoicePdf.tsx` were hand-duplicated between both repos ("kept in sync by eye"). That drifted in three concrete, customer-visible ways before this package fixed it: