kassza 0.13.0 → 0.15.0

package/README.en.md

@@ -0,0 +1,48 @@
+# kassza (English overview)
+
+kassza is an unofficial, zero-dependency TypeScript client for the [Számlázz.hu](https://www.szamlazz.hu) Számla Agent API, the most widely used Hungarian invoicing service. The full documentation is in Hungarian at [kasszajs.hu](https://kasszajs.hu), because the domain (Hungarian VAT, NAV reporting, receipt rules) is Hungarian. This page is a short entry point for developers who do not read Hungarian.
+
+```bash
+npm install kassza
+```
+
+```ts
+import { createKassza } from 'kassza'
+
+const kassza = createKassza() // reads SZAMLAZZ_AGENT_KEY
+
+const { number, created } = await kassza.invoices.createOnce({
+  orderNumber: 'WEB-1042',
+  paid: true,
+  buyer: { name: 'Buyer Ltd.', zip: '1111', city: 'Budapest', address: 'Fő utca 1.' },
+  items: [{ name: 'Subscription', grossUnitPrice: 12_700, vat: 27 }],
+})
+```
+
+## What it does
+
+- Invoices, proformas, advance, final and corrective invoices, delivery notes, reversals, payments, PDFs, invoice data, taxpayer lookup.
+- Receipts (nyugta): create, reverse, query, email, and convert to an invoice later.
+- Exactly-once issuing: `createOnce` looks the document up before creating it and after uncertain failures; concurrent calls are merged, and a shared lock (`createOnceLock`) prevents duplicates across serverless instances.
+- Payment providers: Stripe, SimplePay, Barion, Revolut and PayPal webhooks that issue a receipt or invoice exactly once, reverse it on a full refund, and issue corrective invoices on partial refunds.
+- NAV (Hungarian tax authority) daily receipt reports, reconciliation, and a document journal to build them from.
+- Bulk and recurring invoicing with rate limiting, a fake Számla Agent for tests, Express/NestJS adapter, observability (logs, tracing, Prometheus metrics), a CLI (`npx kassza doctor`) and an MCP server.
+- Runs on Node.js, Bun, Deno, Cloudflare Workers and edge runtimes; CI tests all four on the built package.
+- Sends no telemetry.
+
+## Rules that matter
+
+1. Never retry creating an invoice in a loop: Számlázz.hu bans accounts that do. kassza retries only safe lookups.
+2. Always set an `orderNumber`, and prefer `createOnce`.
+3. Give prices as `netUnitPrice` or `grossUnitPrice` with a VAT rate; kassza applies the official rounding rules.
+4. Errors are `SzamlazzError` with a `category` (`validation`, `duplicate`, `network`, …) and a `docsUrl` to a page about the error code.
+
+## For AI coding agents
+
+English docs for agents ship inside the package: [agents/README.md](agents/README.md), [pitfalls](agents/pitfalls.md), [API reference](agents/api.md), [recipes](agents/recipes.md), and [llms.txt](llms.txt).
+
+## Status
+
+kassza is in beta (0.x). The API may still change between minor versions; see the [changelog](CHANGELOG.md) (in Hungarian). It is not affiliated with Számlázz.hu.
+
+License: MIT.

package/README.md

@@ -6,7 +6,8 @@
 
 <p align="center">
   <b>Számlázz.hu, TypeScriptben, egyszerűbben.</b><br>
-  Nem hivatalos TypeScript wrapper a Számlázz.hu Számla Agenthez. Mind a 11 Agent művelet, 0 függőség, nulla runtime kompromisszum.
+  Nem hivatalos TypeScript wrapper a Számlázz.hu Számla Agenthez. Mind a 11 Agent művelet, 0 függőség, nulla runtime kompromisszum.<br>
+  <sub><a href="https://github.com/futozs/kassza/blob/main/README.en.md">English overview</a></sub>
 </p>
 
 <p align="center">
@@ -14,14 +15,16 @@
   <a href="https://www.npmjs.com/package/kassza"><img src="https://img.shields.io/npm/dm/kassza?label=let%C3%B6lt%C3%A9s&style=flat-square&labelColor=28313d&color=c2501a" alt="havi letöltés"></a>
   <a href="https://github.com/futozs/kassza/blob/main/package.json"><img src="https://img.shields.io/badge/f%C3%BCgg%C5%91s%C3%A9g-0-c2501a?style=flat-square&labelColor=28313d" alt="0 futásidejű függőség"></a>
   <a href="https://github.com/futozs/kassza/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/kassza?label=licenc&style=flat-square&labelColor=28313d&color=c2501a" alt="MIT licenc"></a>
-</p>
-
-<p align="center">
-  <a href="https://kasszajs.hu"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-web-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-web-light.svg" alt="Weboldal: kasszajs.hu" width="428"></picture></a>
-  <a href="https://kasszajs.hu/docs"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-docs-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-docs-light.svg" alt="Dokumentáció: 113 oldal, magyarul" width="428"></picture></a>
   <br>
-  <a href="https://kasszajs.hu/sandbox"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-sandbox-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-sandbox-light.svg" alt="Sandbox: 28 futtatható példa" width="428"></picture></a>
-  <a href="https://kasszajs.hu/docs/receptek"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-recipes-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/nav-recipes-light.svg" alt="Receptek: 11 kész integráció" width="428"></picture></a>
+  <a href="https://github.com/futozs/kassza/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/futozs/kassza/ci.yml?branch=main&label=CI&style=flat-square&labelColor=28313d" alt="CI állapota"></a>
+  <a href="https://github.com/futozs/kassza/actions/workflows/full-check.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/futozs/kassza/full-check.yml?branch=main&label=heti%20teljes%20teszt&style=flat-square&labelColor=28313d" alt="Heti teljes ellenőrzés: CI, XSD, változásfigyelő, élő e2e"></a>
+  <a href="https://github.com/futozs/kassza/actions/workflows/release.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/futozs/kassza/release.yml?branch=main&label=kiad%C3%A1s&style=flat-square&labelColor=28313d" alt="Kiadás állapota"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/futozs/kassza"><img src="https://img.shields.io/ossf-scorecard/github.com/futozs/kassza?label=OpenSSF%20Scorecard&style=flat-square&labelColor=28313d" alt="OpenSSF Scorecard pontszám"></a>
+  <br>
+  <a href="https://github.com/futozs/kassza/actions/workflows/badges.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffutozs%2Fkassza%2Fbadges%2Fcoverage-lines.json&style=flat-square&labelColor=28313d" alt="Sor-lefedettség"></a>
+  <a href="https://github.com/futozs/kassza/actions/workflows/badges.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffutozs%2Fkassza%2Fbadges%2Fcoverage-branches.json&style=flat-square&labelColor=28313d" alt="Ág-lefedettség"></a>
+  <a href="https://github.com/futozs/kassza/actions/workflows/badges.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffutozs%2Fkassza%2Fbadges%2Fcoverage-functions.json&style=flat-square&labelColor=28313d" alt="Függvény-lefedettség"></a>
+  <a href="https://github.com/futozs/kassza/actions/workflows/badges.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffutozs%2Fkassza%2Fbadges%2Fcoverage-statements.json&style=flat-square&labelColor=28313d" alt="Utasítás-lefedettség"></a>
 </p>
 
 ```bash
@@ -96,7 +99,8 @@ Ennyi. A kerekítést, a magyar dátumot, az XML-t, a session cookie-t és a hib
 | ⚙️ [Beállítás](#beállítás) | 🧾 [Nyugták](#nyugták) | 📊 [NAV nyugta-adatszolgáltatás](#nav-nyugta-adatszolgáltatás) | ⚡ [Serverless és edge](#serverless-és-edge) |
 | 🚨 [Hibakezelés](#hibakezelés) | 🏛️ [Adószám lekérdezés](#adószám-lekérdezés) | 🤝 [Megbízotti számlázás](#megbízotti-számlázás) | 🧪 [Tesztelés](#tesztelés) |
 | 🎛️ [Haladó beállítások](#haladó-beállítások) | 🔔 [Fizetési értesítés (IPN)](#fizetési-értesítés-ipn) | 🔗 [Pénzügyi adatkapcsolat](#pénzügyi-adatkapcsolat) | 🧮 [Validátorok és pénzszámítás](#validátorok-és-pénzszámítás) |
-| 🤖 [AI-val kódolsz?](#ai-val-kódolsz) | | | 💻 [Parancssor és MCP szerver](#parancssor-és-mcp-szerver) |
+| 🤖 [AI-val kódolsz?](#ai-val-kódolsz) | 🔁 [Tömeges számlázás](#tömeges-és-ismétlődő-számlázás) | 🟩 [Node.js és Express](#nodejs-és-express) | 💻 [Parancssor és MCP szerver](#parancssor-és-mcp-szerver) |
+| | | 📒 [Bizonylatnapló](#bizonylatnapló) | 📈 [Megfigyelhetőség](#megfigyelhetőség) |
 
 ## Weboldal, sandbox és receptek
 
@@ -106,7 +110,7 @@ A teljes magyar dokumentáció, a sandbox és a receptek a **[kasszajs.hu](https
   <a href="https://kasszajs.hu/sandbox?pelda=szamla"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/showcase-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/showcase-light.svg" alt="A kassza sandbox: futtatható példák, TypeScript kód és a ténylegesen elküldött XML" width="100%"></picture></a>
 </p>
 
-- 📖 **[Dokumentáció](https://kasszajs.hu/docs)**: 113 oldal magyarul. Minden Agent művelethez kérés, válasz és futtatható minta, a beállítások, a szabályok és az összes ismert hibakód.
+- 📖 **[Dokumentáció](https://kasszajs.hu/docs)**: 188 oldal magyarul. Minden Agent művelethez kérés, válasz és futtatható minta, a beállítások, a szabályok és az összes ismert hibakód.
 - ▶️ **[Sandbox](https://kasszajs.hu/sandbox)**: 28 példa, amit a böngészőben futtathatsz Agent kulcs nélkül, szimulált Számlázz.hu ellen, a ténylegesen elküldött XML-lel. A saját kódodat linkként meg is oszthatod.
 - 🍳 **[Receptek](https://kasszajs.hu/docs/receptek)**: 11 teljes, bemásolható integráció webshophoz, Stripe és IPN webhookhoz, díjbekérőhöz, pénztári nyugtához, PDF tárhelyhez, Cloudflare Workershez és tesztekhez.
 - 🤖 **[llms.txt](https://kasszajs.hu/llms.txt)**: a dokumentáció tartalomjegyzéke AI asszisztenseknek, a teljes szöveg egy fájlban: [llms-full.txt](https://kasszajs.hu/llms-full.txt).
@@ -421,6 +425,8 @@ await kassza.invoices.clearPayments('E-WEB-2026-12')
 
 A `registerPayment` egyetlen befizetést és több részletet is fogad. A `clearPayments` az összes befizetést törli a számláról.
 
+Ha ugyanaz a befizetés több helyről is érkezhet (banki értesítés, webhook), a `registerPaymentOnce({ invoiceNumber, key, amount })` egy stabil kulccsal pontosan egyszer rögzíti: a kulcsot jelölőként a befizetés leírásába teszi, és rögzítés előtt megkeresi.
+
 📖 **Dokumentáció:** [Befizetés rögzítése](https://kasszajs.hu/docs/befizetes-rogzitese) &nbsp;·&nbsp; ▶️ **Sandbox:** [Befizetések rögzítése](https://kasszajs.hu/sandbox?pelda=befizetes)
 
 </details>
@@ -579,7 +585,7 @@ if (ceg.valid) {
 }
 ```
 
-A cégadatok a NAV-tól jönnek, a cím formázva, például `1031 Budapest, Záhony utca 7.`
+A cégadatok a NAV-tól jönnek, a cím formázva, például `1031 Budapest, Záhony utca 7.` Űrlapokhoz a `taxpayerCache: { store }` beállítás közös tárolóban megjegyzi az eredményt, így ugyanaz az adószám csak egyszer megy ki.
 
 📖 **Dokumentáció:** [Adószám lekérdezés](https://kasszajs.hu/docs/adoszam-lekerdezes) &nbsp;·&nbsp; ▶️ **Sandbox:** [Adószám lekérdezése](https://kasszajs.hu/sandbox?pelda=adoszam)
 
@@ -632,6 +638,10 @@ try {
 | `network` / `timeout` / `maintenance` | Átmeneti hiba |
 | `rate_limit` | A tesztfiókban túl sok bizonylat készült rövid idő alatt (167) |
 | `attempt_limit` | Ezt a kérést már ötször sikertelenül küldték el, ezért a kassza el sem küldi |
+| `in_progress` | Egy másik folyamat éppen ugyanezt a bizonylatot állítja ki (a `createOnce` zárja) |
+| `store_unavailable` | Egy kötelezőnek beállított tároló (zár, napló) nem érhető el, a kérés el sem ment |
+
+Minden ismert hibakódnak saját oldala van; a hiba `docsUrl` mezője oda mutat, így a naplóból egy kattintás.
 
 📖 **Dokumentáció:** [Hibakezelés, hibakódok](https://kasszajs.hu/docs/alapok/hibakezeles) &nbsp;·&nbsp; ▶️ **Sandbox:** [Validációs hibák](https://kasszajs.hu/sandbox?pelda=hibakezeles-validacio)
 
@@ -649,7 +659,16 @@ const { number, created } = await kassza.invoices.createOnce({
 })
 ```
 
-Kiállítás előtt megkeresi a számlát, hálózati hiba, időtúllépés vagy 56-os hiba után pedig visszakeresi. Ha a webhook kétszer fut le, a második hívás `created: false` eredménnyel a meglévő számlát adja. Ha ugyanazt a kérést több szerver is küldheti, az `attemptLedger` opció a folyamatok között is betartja az öt próbálkozásos korlátot.
+Kiállítás előtt megkeresi a számlát, hálózati hiba, időtúllépés vagy 56-os hiba után pedig visszakeresi. Ha a webhook kétszer fut le, a második hívás `created: false` eredménnyel a meglévő számlát adja. Az egyszerre érkező, azonos rendelésre szóló hívásokat a kassza összevonja; több szerver vagy serverless példány között a `createOnceLock` közös tároló zárja véd a dupla számla ellen:
+
+```ts
+import { upstashRedisStore } from 'kassza/stores'
+
+const store = upstashRedisStore(Redis.fromEnv())
+const kassza = createKassza({ cookieStore: store, attemptLedger: store, createOnceLock: store })
+```
+
+Az `attemptLedger` a folyamatok között is betartja az öt próbálkozásos korlátot, atomikus számlálóval.
 
 📖 **Dokumentáció:** [Pontosan egyszer](https://kasszajs.hu/docs/alapok/pontosan-egyszer) &nbsp;·&nbsp; ▶️ **Sandbox:** [Pénztári nyugta, dupla gombnyomás](https://kasszajs.hu/sandbox?pelda=penztari-nyugta)
 
@@ -726,8 +745,9 @@ export const POST = stripeWebhook({
 })
 ```
 
-- Az újraküldött webhook nem állít ki második bizonylatot.
+- Az újraküldött webhook nem állít ki második bizonylatot; a `dedupe: store` opcióval a már feldolgozott eseményt a Számla Agent hívása nélkül nyugtázza.
 - Teljes visszatérítéskor a kassza sztornózza a bizonylatot.
+- Részleges visszatérítéskor számlánál visszatérítésenként egy helyesbítő számlát állít ki, a visszatérített összeget tételenként pontosan szétosztva; több áfakulcsnál és nyugtánál javaslatot ad.
 - Ugyanígy működik a `simplePayWebhook`, a `barionWebhook`, a `revolutWebhook` és a `payPalWebhook`.
 
 📖 **Dokumentáció:** [Fizetésből bizonylat](https://kasszajs.hu/docs/fizetesek)
@@ -773,6 +793,36 @@ A NAV kliens alapból csak olvas: a Számlázz.hu által jelentett nyugtákat ne
   <a href="https://kasszajs.hu/docs/nav-nyugta"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-light.svg" alt="Dokumentáció: NAV nyugta-adatszolgáltatás" height="44"></picture></a>
 </p>
 
+## Bizonylatnapló
+
+A NAV napi összesítő és a napi zárás a saját nyilvántartásodból számol, mert a Számla Agent nem listáz nyugtákat dátum szerint. A `kassza/journal` ezt a nyilvántartást adja.
+
+<details>
+<summary><b>Napló a NAV összesítőhöz</b> · <code>createJournal()</code>, <code>kvJournal()</code></summary>
+
+```ts
+import { createJournal, kvJournal } from 'kassza/journal'
+import { navDailyReports } from 'kassza/reports'
+
+const journal = createJournal(kvJournal(store))
+const kassza = createKassza({
+  hooks: { onDocument: (event) => journal.record(event), onDocumentError: 'throw' },
+})
+
+const jelentesek = navDailyReports(await journal.receipts({ from: '2026-10-01', to: '2026-10-31' }))
+```
+
+- A `trackReceipt()` és a `trackInvoice()` a kiállítás előtt befejezetlen tételt rögzít; ha a folyamat közben leáll, a `settle()` később visszakeresi és lezárja.
+- A `reconcile()` az adatkapcsolat napi nyugtaarchívumával egyeztet, és pótolja a hiányzó tételeket.
+
+📖 **Dokumentáció:** [Bizonylatnapló](https://kasszajs.hu/docs/kiegeszitok/bizonylatnaplo)
+
+</details>
+
+<p>
+  <a href="https://kasszajs.hu/docs/nav-nyugta/hatarido"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-light.svg" alt="Dokumentáció: Mi a teendő december 31. előtt?" height="44"></picture></a>
+</p>
+
 ## Megbízotti számlázás
 
 Platformoknak, amelyek sok cég nevében állítanak ki bizonylatot, a cégek saját Számlázz.hu fiókjában.
@@ -896,13 +946,13 @@ További adapterek: `s3Storage` (AWS SDK), `r2BindingStorage`, `vercelBlobStorag
 A session cookie újrahasznosítása gyorsítja a hívásokat. Serverless környezetben tedd közös tárolóba.
 
 <details>
-<summary><b>Upstash Redis</b> · <code>upstashRedisCookieStore()</code></summary>
+<summary><b>Upstash Redis</b> · <code>upstashRedisStore()</code></summary>
 
 ```ts
 import { Redis } from '@upstash/redis'
-import { upstashRedisCookieStore } from 'kassza/cookie-stores'
+import { upstashRedisStore } from 'kassza/stores'
 
-const kassza = createKassza({ cookieStore: upstashRedisCookieStore(Redis.fromEnv()) })
+const kassza = createKassza({ cookieStore: upstashRedisStore(Redis.fromEnv()) })
 ```
 
 📖 **Dokumentáció:** [Munkamenet (session cookie)](https://kasszajs.hu/docs/alapok/munkamenet) &nbsp;·&nbsp; ▶️ **Sandbox:** [Közös session több kliens között](https://kasszajs.hu/sandbox?pelda=munkamenet)
@@ -910,19 +960,23 @@ const kassza = createKassza({ cookieStore: upstashRedisCookieStore(Redis.fromEnv
 </details>
 
 <details>
-<summary><b>Cloudflare Workers</b> · <code>cloudflareKvCookieStore()</code></summary>
+<summary><b>Cloudflare Workers</b> · <code>cloudflareKvStore()</code>, <code>durableObjectStore()</code></summary>
 
 ```ts
-import { cloudflareKvCookieStore } from 'kassza/cookie-stores'
+import { cloudflareKvStore } from 'kassza/stores'
 
-const kassza = createKassza({ agentKey: env.SZAMLAZZ_AGENT_KEY, cookieStore: cloudflareKvCookieStore(env.KASSZA_KV) })
+const kassza = createKassza({ agentKey: env.SZAMLAZZ_AGENT_KEY, cookieStore: cloudflareKvStore(env.KASSZA_KV) })
 ```
 
+A KV munkamenetnek jó, de nincs benne atomikus írás: a `createOnce` zárjához és a naplóhoz Workers alatt a `durableObjectStore()` kell.
+
 📖 **Dokumentáció:** [Serverless és edge](https://kasszajs.hu/docs/kiegeszitok/serverless-es-edge)
 
 </details>
 
-Van még `ioredisCookieStore`, `nodeRedisCookieStore` és `customCookieStore` is. Ha a tároló elérhetetlen, a számlázás attól még működik.
+Van még `ioredisStore`, `nodeRedisStore` és `customStore` is (a régi `kassza/cookie-stores` nevek is működnek). A `diagnoseStore(store)` megmondja, mire alkalmas egy tároló. Ha a tároló elérhetetlen, a számlázás attól még működik.
+
+A csomag minden futtatókörnyezetben ugyanazt adja: a CI a buildelt csomagot Node.js, Bun, Deno és Cloudflare workerd alatt is lefuttatja.
 
 <p>
   <a href="https://kasszajs.hu/docs/kiegeszitok/serverless-es-edge"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-light.svg" alt="Dokumentáció: Serverless és edge" height="44"></picture></a>
@@ -1090,7 +1144,8 @@ const kassza = createKassza({
 })
 ```
 
-- Az `onDocument` minden kiállított és sztornózott bizonylat, valamint rögzített befizetés után lefut. Ha hibát dob, a bizonylat attól még elkészült.
+- Az `onDocument` minden kiállított és sztornózott bizonylat, valamint rögzített befizetés után lefut. Ha hibát dob, a bizonylat attól még elkészült; az `onDocumentError: 'throw'` beállítással ilyenkor `DocumentHookError` jön, benne a bizonylattal.
+- Az `onWarning` megkapja a korábban csendben elnyelt hibákat (tároló, hook, zár).
 - A `maintenanceCooldownMs` karbantartási hiba után ennyi ideig nem küld kérést, hanem azonnal `maintenance` hibát ad, így átválthatsz tartalék folyamatra.
 
 📖 **Dokumentáció:** [Pontosan egyszer](https://kasszajs.hu/docs/alapok/pontosan-egyszer)
@@ -1102,6 +1157,73 @@ const kassza = createKassza({
   <a href="https://kasszajs.hu/sandbox?pelda=hookok"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-sandbox-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-sandbox-light.svg" alt="Futtasd a sandboxban: Hookok és újrapróbálás" height="44"></picture></a>
 </p>
 
+## Megfigyelhetőség
+
+A kassza nem küld haza semmit. A saját rendszeredben a `kassza/observe` ad strukturált naplót, OpenTelemetry-kompatibilis tracinget és Prometheus metrikákat, függőség nélkül és titokmentesen.
+
+<details>
+<summary><b>Napló, tracing, metrikák</b> · <code>observe()</code>, <code>createMetricsRegistry()</code></summary>
+
+```ts
+import { combineHooks, createMetricsRegistry, observe } from 'kassza/observe'
+
+const metrics = createMetricsRegistry()
+const kassza = createKassza({ hooks: combineHooks(observe({ logger: console, metrics }), sajatHookok) })
+
+metrics.renderPrometheus()
+```
+
+📖 **Dokumentáció:** [Megfigyelhetőség](https://kasszajs.hu/docs/kiegeszitok/megfigyelhetoseg)
+
+</details>
+
+## Tömeges és ismétlődő számlázás
+
+Havidíj, tagdíj, bérleti díj: a `kassza/batch` idempotens kulcsokkal, sebességkorláttal és próbafuttatással állítja ki a bizonylatokat, és a Számlázz.hu korlátjánál megáll.
+
+<details>
+<summary><b>Havi számlázás</b> · <code>runBatch()</code>, <code>billingPeriodAt()</code></summary>
+
+```ts
+import { billingPeriodAt, runBatch } from 'kassza/batch'
+
+const idoszak = billingPeriodAt({ interval: 'month', anchor: '2026-01-31' }, new Date())
+const eredmeny = await runBatch(kassza, {
+  items: elofizetesek.map((elofizetes) => ({
+    key: `SUB-${elofizetes.id}-${idoszak.start}`,
+    document: () => ({ kind: 'invoice', input: szamlaElofizetesbol(elofizetes, idoszak) }),
+  })),
+  dryRun: false,
+})
+```
+
+Egy megszakadt futás újraindítva nem állít ki duplát. A hónap végi kezdőnapot csúszás nélkül kezeli.
+
+📖 **Dokumentáció:** [Tömeges és ismétlődő számlázás](https://kasszajs.hu/docs/kiegeszitok/tomeges-szamlazas)
+
+</details>
+
+## Node.js és Express
+
+A webhook-kezelők Web-szabványos `(Request) => Response` függvények. Express, NestJS és Fastify alá a `kassza/node` köti be őket, a nyers törzs (aláírás!) megőrzésével.
+
+<details>
+<summary><b>Express</b> · <code>toNodeHandler()</code></summary>
+
+```ts
+import { toNodeHandler } from 'kassza/node'
+import { stripeWebhook } from 'kassza/payments/stripe'
+
+app.post('/webhooks/stripe', toNodeHandler(stripeWebhook({ secret, onPayment })))
+app.use(express.json())
+```
+
+A webhook útvonal az `express.json()` elé kerüljön; ha egy middleware már feldolgozta a törzset, a kassza érthető hibát ad.
+
+📖 **Dokumentáció:** [Node.js, Express, NestJS](https://kasszajs.hu/docs/kiegeszitok/node-express)
+
+</details>
+
 ## Parancssor és MCP szerver
 
 <details>
@@ -1113,7 +1235,7 @@ npx kassza xml preview szamla.json
 npx kassza invoice get --order REND-1001
 ```
 
-A `doctor` ellenőrzi a Node.js-t, az Agent kulcsot, a gép óráját és a munkamenetet. Az `xml preview` kiírja a küldendő XML-t az Agent kulcs nélkül, így supportjegyhez is csatolható.
+A `doctor` ellenőrzi a Node.js-t, az Agent kulcsot, a gép óráját és a munkamenetet; a `--capabilities` az e-számla engedélyt, a `--report` titokmentes Markdown jelentést ad hibajegyhez. Az `xml preview` kiírja a küldendő XML-t az Agent kulcs nélkül, így supportjegyhez is csatolható.
 
 📖 **Dokumentáció:** [Parancssor](https://kasszajs.hu/docs/kiegeszitok/parancssor)
 
@@ -1158,6 +1280,14 @@ A weboldal is AI-barát: az [llms.txt](https://kasszajs.hu/llms.txt) a dokument
   <a href="https://kasszajs.hu/docs/kiegeszitok/ai-asszisztensek"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-dark.svg"><img src="https://raw.githubusercontent.com/futozs/kassza/main/readme/assets/button-docs-light.svg" alt="Dokumentáció: AI asszisztensek" height="44"></picture></a>
 </p>
 
+## Ki használja?
+
+A kassza nem küld semmilyen használati adatot, ezért csak az derül ki, ki használja, aki maga jelzi. Ha éles vagy kísérleti projektben használod, [írd meg egy issue-ban](https://github.com/futozs/kassza/issues/new?template=used-by.yml), és felkerülsz ide.
+
+| Projekt | Mire használja |
+| --- | --- |
+| _Légy te az első._ | |
+
 ---
 
 <p align="center">

package/agents/README.md

@@ -14,6 +14,11 @@ It also links delegated (principal) accounts through the Agent (`connectPrincipa
 - `kassza/data-link`: a receiver for the Számlázz.hu financial data link (pushed invoices, bank transactions and receipts).
 - `kassza/testing`: a mock client and a fake Számla Agent `fetch` for integration tests.
 - `kassza/mcp` and the `kassza` CLI (`npx kassza doctor`, `npx kassza mcp`).
+- `kassza/stores`: shared stores (Redis, Upstash, Cloudflare KV, Durable Object) for the session, the attempt ledger, the `createOnce` lock and webhook deduplication.
+- `kassza/journal`: a document journal for the NAV daily summary, with pending entries and reconciliation.
+- `kassza/batch`: rate-limited, restartable bulk and recurring invoicing, plus billing periods.
+- `kassza/node`: Express, NestJS and `node:http` adapter for the webhook handlers.
+- `kassza/observe`: structured logs, tracing and Prometheus metrics, with no telemetry.
 
 It runs on Node 22+, Bun, Deno, Cloudflare Workers and Vercel Edge.
 
@@ -23,7 +28,7 @@ It runs on Node 22+, Bun, Deno, Cloudflare Workers and Vercel Edge.
 2. [api.md](./api.md): every method, input and output.
 3. [recipes.md](./recipes.md): webhooks, exactly-once invoicing, receipts, IPN, PDF storage, serverless, tests, payment providers, NAV reports, delegated invoicing, data link.
 
-A ready-made Claude Code skill is in [skills/kassza/SKILL.md](./skills/kassza/SKILL.md). Copy the `skills/kassza` folder into `.claude/skills/` in the user's project.
+A ready-made Claude Code skill is in [skills/kassza/SKILL.md](./skills/kassza/SKILL.md). To move a codebase off `szamlazz.js`, use [skills/migrate-from-szamlazz-js/SKILL.md](./skills/migrate-from-szamlazz-js/SKILL.md). Copy the `skills/kassza` folder into `.claude/skills/` in the user's project.
 
 ## The five things to get right
 

package/agents/api.md

@@ -11,15 +11,18 @@ const kassza = createKassza({
   agentKey?: string,
   username?: string, password?: string,
   defaults?: { invoice?: InvoiceDefaults, receipt?: ReceiptDefaults },
-  cookieStore?: CookieStore | false,
-  attemptLedger?: CookieStore,
+  cookieStore?: KeyValueStore | false,
+  attemptLedger?: KeyValueStore,
+  attemptLedgerMode?: 'fail-open' | 'fail-closed',
+  createOnceLock?: KeyValueStore,
+  taxpayerCache?: { store: KeyValueStore, ttlSeconds?, invalidTtlSeconds? },
   timeoutMs?: number,
   maxAttempts?: number,
   retryDelayMs?: number,
   maintenanceCooldownMs?: number,
   fetch?: typeof fetch,
   endpoint?: string,
-  hooks?: { onRequest?, onResponse?, onError?, onDocument? },
+  hooks?: { onRequest?, onResponse?, onError?, onComplete?, onDocument?, onDocumentError?, onWarning? },
 })
 ```
 
@@ -29,9 +32,15 @@ const kassza = createKassza({
 - `timeoutMs` defaults to 60000.
 - `maxAttempts` defaults to 3 and is capped at 5. It applies only to operations that are safe to retry.
 - `hooks` receive events for logging. They never receive the XML payload or the key.
-- `attemptLedger` is a shared store with the `CookieStore` interface (for example `upstashRedisCookieStore(redis)` from `kassza/cookie-stores`). It counts failed attempts of identical requests across processes for a day. After 5 failures kassza throws an `attempt_limit` error without sending the request; after a human fixed the cause, call `kassza.resetAttempts(error)`.
+- `KeyValueStore` (alias `CookieStore`) is `{ get, set, delete }` plus the optional atomic `setIfAbsent`, `increment`, `deleteIfEquals`. Adapters live in `kassza/stores` (see below).
+- `attemptLedger` is a shared store. It counts failed attempts of identical requests across processes for a day, atomically when the store has `increment`. After 5 failures kassza throws an `attempt_limit` error without sending the request; after a human fixed the cause, call `kassza.resetAttempts(error)`. If the store fails, `attemptLedgerMode: 'fail-open'` (default) falls back to an in-process counter and emits `onWarning`; `'fail-closed'` throws `store_unavailable` without sending (create the adapter with `resilient: false` so read errors reach kassza).
+- `createOnceLock` is a shared store with `setIfAbsent` (Redis, Upstash, Durable Object; not Cloudflare KV). It makes `createOnce` exactly-once across processes. Calls for the same order inside one process are always merged, without any option.
+- `taxpayerCache` caches `taxpayer.query` results (valid ones for a day, invalid ones for 10 minutes; errors are never cached).
 - `maintenanceCooldownMs` defaults to 0. When set, a maintenance error (code 1) blocks all requests of the client for that long, and they fail at once with category `maintenance`.
-- `hooks.onDocument(event)` runs after every created or reversed document and every registered payment, with `{ kind: 'invoice' | 'receipt', action: 'created' | 'reversed' | 'payment', number, document }` (plus `reversedNumber` for reversals and `input` for created invoices). It is awaited, and an error thrown in it is logged, never rethrown.
+- `hooks.onDocument(event)` runs after every created or reversed document and every registered payment, with `{ kind: 'invoice' | 'receipt', action: 'created' | 'reversed' | 'payment', number, document }` (plus `reversedNumber` for reversals and `input` for created invoices). It is awaited. `hooks.onDocumentError` decides what happens when it throws: `'warn'` (default, the call still succeeds), `'throw'` (a `DocumentHookError` carrying `event`, `document` and `number` of the document that WAS created; never re-create it) or a handler `(error, event) => void`.
+- `hooks.onWarning(warning)` receives the errors kassza swallows on purpose: `{ kind: 'session' | 'ledger' | 'hook' | 'document' | 'lock' | 'dedupe' | 'cache', message, error, action?, operation? }`.
+- `hooks.onRequest`, `onResponse`, `onError` and `onComplete` events carry `{ action, attempt, requestId }`; `onResponse` adds `status`, `durationMs`, `responseBytes`, `sessionReused`; `onComplete` adds `outcome: 'success' | 'error'`, `durationMs`, `error?`, `willRetry` and fires once per attempt.
+- Retries of safe operations wait `retryDelayMs * 2^(attempt-1)` with ±20% jitter, and honour `Retry-After` (no retry when it exceeds 60 s).
 
 ## Invoices: `kassza.invoices`
 
@@ -42,6 +51,7 @@ const kassza = createKassza({
 | `preview(input: CreateInvoiceInput)` | `InvoicePreview` (PDF only, no document is created) | never |
 | `reverse(input: string \| ReverseInvoiceOptions)` | `ReversedInvoice` | never |
 | `registerPayment(input: RegisterPaymentInput)` | `RegisteredPayment` | only when `additive: false` |
+| `registerPaymentOnce({ invoiceNumber, key, amount, method?, date?, description?, taxNumber? }, options?)` | `RegisteredPaymentOnce` (`{ invoiceNumber, key, marker, created, payment?, existing? }`) | never resends; looks the payment up by its marker |
 | `clearPayments(input: string \| { invoiceNumber })` | `RegisteredPayment` | yes |
 | `getPdf(ref: InvoiceReference)` | `InvoicePdf` | yes |
 | `get(ref: InvoiceReference, { includePdf? })` | `InvoiceDetails` | yes |
@@ -52,7 +62,7 @@ const kassza = createKassza({
 
 ### createOnce
 
-`invoices.createOnce(input, { lookupFirst?, matchOrderNumber?, recoveryDelayMs?, signal? })` makes invoicing exactly-once:
+`invoices.createOnce(input, { lookupFirst?, matchOrderNumber?, recoveryDelayMs?, signal?, lock?, lockTtlSeconds?, lockWaitMs?, lockFailure? })` makes invoicing exactly-once:
 
 1. It looks the invoice up by external ID (and, with `matchOrderNumber`, by order number) and returns it if it exists.
 2. Otherwise it creates the invoice.
@@ -62,6 +72,8 @@ const kassza = createKassza({
 - `lookupFirst` and `matchOrderNumber` default to `true`.
 - It returns `InvoiceOnceResult`: `{ number, created, externalId, invoice?: CreatedInvoice, details?: InvoiceDetails }`. `created` is `false` when the invoice already existed.
 - If the outcome stays unknown, it rethrows the original error with `details.outcome: 'unknown'`. Do not create the invoice by hand then; call `createOnce` again later.
+- Concurrent calls for the same order in one process share one execution; the others get the result with `created: false`. Across processes `lock` (default: the client's `createOnceLock`, `false` disables) is held for `lockTtlSeconds` (600); a waiter polls up to `lockWaitMs` (10000) and then throws `in_progress` (respond 5xx in a webhook so it is redelivered). `lockFailure: 'throw'` (default) throws `store_unavailable` when the lock store is down; `'proceed'` continues without a lock and warns.
+- `registerPaymentOnce` writes `[kassza:{key}]` into the payment description and looks for it on the invoice before registering. If the marker cannot be read back after registering, it throws `unexpected_response` with `details.registered: 'true'`: the payment exists, do not call again.
 
 ### CreateInvoiceInput
 
@@ -187,7 +199,7 @@ Notes on the fields:
 
 ## Taxpayer: `kassza.taxpayer`
 
-`query(taxNumber: string): TaxpayerInfo` accepts `12345676`, `12345676-2-42` or `HU12345676`.
+`query(taxNumber: string): TaxpayerInfo` accepts `12345676`, `12345676-2-42` or `HU12345676`. With `taxpayerCache` the result is cached by the 8-digit taxpayer ID.
 
 `TaxpayerInfo` is `{ valid, name?, shortName?, taxNumber?: { taxpayerId, vatCode?, countyCode?, formatted? }, address?: TaxpayerAddress, addresses, incorporation?, infoDate? }`, and `TaxpayerAddress.formatted` looks like `'1031 Budapest, Záhony utca 7.'`.
 
@@ -261,13 +273,34 @@ createFakeAgentFetch(options?: FakeAgentOptions): FakeAgent
 ### `kassza/money`
 
 - `calculateInvoiceItem(input, currency?)` and `calculateReceiptItem(input, currency?)` return `ItemAmounts`.
+- `allocateRefund(items: { name, vat, grossAmount, unit?, identifier? }[], refundGross, { decimals?, refundedBefore? })` splits a refund exactly over items (Sainte-Laguë, BigInt), path-independent: refunds split into parts give the same per-item totals as one refund.
 - `summarizeItems(items)` returns `{ netAmount, vatAmount, grossAmount, byVat }`.
 - `roundMoney(value, decimals)`, `isVatRate(value)`, `NUMERIC_VAT_RATES`, `SPECIAL_VAT_CODES`.
 
-### `kassza/storage` and `kassza/cookie-stores`
+### `kassza/storage`
 
 - `storePdf(storage, key, pdf)` and `invoicePdfKey({ number })` save PDFs through adapters: `s3FetchStorage`, `s3Storage`, `r2BindingStorage`, `vercelBlobStorage`, `uploadthingStorage`, `supabaseStorage`, `memoryStorage`, and `fsStorage` from `kassza/storage/fs`.
-- Session and attempt-ledger stores: `upstashRedisCookieStore`, `ioredisCookieStore`, `nodeRedisCookieStore`, `cloudflareKvCookieStore`, `customCookieStore({ get, set, delete })`, `memoryCookieStore`.
+
+### `kassza/stores` (also `kassza/cookie-stores`)
+
+- `memoryStore()`, `upstashRedisStore(redis)`, `ioredisStore(redis)`, `nodeRedisStore(client)`, `cloudflareKvStore(namespace)`, `customStore(store)`, `resilientStore(store)`; the old `*CookieStore` names are aliases.
+- Redis adapters get the atomic operations through Lua (`eval`) when the client has it. Cloudflare KV has none: use `durableObjectStore(stub)` with `handleDurableObjectStoreRequest(this.ctx.storage, request)` inside your Durable Object class for locks and the journal on Workers.
+- Adapters are resilient by default: `get`/`set`/`delete` errors are reported to `onError` and swallowed, atomic operation errors are reported and rethrown. `resilient: false` rethrows everything.
+- `diagnoseStore(store)` returns `{ ok, capabilities, suitableFor: { session, attemptLedger, createOnceLock, journal, webhookDedupe }, latencyMs, problems }` after a round-trip with a temporary key.
+
+### `kassza/journal`
+
+```ts
+const journal = createJournal(kvJournal(store), { now? })
+createKassza({ hooks: { onDocument: (event) => journal.record(event), onDocumentError: 'throw' } })
+```
+
+- `kvJournal(store, { prefix?, retentionDays? (400), reservationTtlDays? (30) })` needs a store with `increment`; `memoryJournal()` for tests; or implement `JournalStorage` for SQL.
+- `record(event)` stores created and reversed documents (payments are ignored); idempotent by document number.
+- `trackReceipt(orderNumber, run)` / `trackInvoice(orderNumber, run)` reserve before `run` and complete after it. Definite `SzamlazzError`s release the reservation; uncertain errors and crashes leave it pending. A failed journal write after success throws `JournalWriteError` with `result`.
+- `pending(range?)` lists reservations (last 30 days by default); `settle(kassza, { range?, releaseNotFound? })` looks them up by order number and records what it finds.
+- `entries({ from, to, kind? })`, `receipts({ from, to, includeTest? })` (feed into `navDailyReports`), at most 366 days per call.
+- `reconcile(archive, { from?, to?, dryRun? })` compares with the data link receipt archive: `{ range, added, missingFromArchive, matched }`.
 
 ### `kassza/payments`
 
@@ -283,7 +316,8 @@ Webhook handlers are `(request: Request) => Promise<Response>`, usable directly
 
 - Common options: `onPayment(payment)`, `onError?(error)`, `method?` (the payment method written on the document), `maxBodyBytes?`, `fetch?`; `sandbox?` where the provider has one.
 - Responses: `400` for a bad signature or payload (never reaches `onPayment`), `200` on success (`204` for Revolut, a signed JSON for SimplePay), `500` when `onPayment` throws, so the provider redelivers.
-- `PaymentEvent` is `{ provider, kind: 'paid' | 'refunded' | 'partially-refunded' | 'failed' | 'other', id, eventId?, eventType?, orderRef?, amount?: { value, currency }, refundedAmount?, paidAt?, method, customer?, items?, raw }`. Amounts are in major units (12700 HUF, not minor units).
+- `PaymentEvent` is `{ provider, kind: 'paid' | 'refunded' | 'partially-refunded' | 'failed' | 'other', id, eventId?, eventType?, orderRef?, amount?: { value, currency }, refundedAmount?, refunds?: { id, amount, refundedBefore?, createdAt? }[], paidAt?, method, customer?, items?, raw }`. Amounts are in major units (12700 HUF, not minor units). `refunds` lists the individual refunds the provider reported (Barion and SimplePay: all; Revolut and PayPal: the current one; Stripe: the delta of `charge.refunded` keyed by the event ID).
+- `dedupe?: KeyValueStore` and `dedupeTtlSeconds?` (7 days): an event that was already processed successfully is acknowledged without calling `onPayment` again. It is marked only after `onPayment` succeeds.
 
 ```ts
 const result = await kassza.issueForPayment(payment, {
@@ -297,18 +331,36 @@ const result = await kassza.issueForPayment(payment, {
   orderNumber?: string,
   exchangeRate?, exchangeBank?,
   allowAmountMismatch?: boolean,
+  partialRefund?: 'auto' | 'proportional' | 'skip',
+  refundItems?: ({ refund, invoiceNumber, items }) => PaymentDocumentItem[] | undefined,
   receipt?: Partial<CreateReceiptInput>,
   invoice?: Partial<CreateInvoiceInput>,
 })
 ```
 
-- `paid`: chooses receipt or invoice with `chooseDocument` (override with `document`) and issues it with `createOnce`. `refunded`: reverses that document exactly once. `partially-refunded`, `failed` and `other`: skipped, because a partial refund needs a corrective document decided by a human.
+- `paid`: chooses receipt or invoice with `chooseDocument` (override with `document`) and issues it with `createOnce`. `refunded`: reverses that document exactly once. `failed` and `other`: skipped.
+- `partially-refunded`: for an invoice, one corrective invoice per refund (external ID `{orderNumber}/R-{refund}`), with the refund allocated exactly over the original items (`allocateRefund`, house-monotone, never more than an item's original amount across refunds). If the invoice has several VAT rates and no `refundItems` is given, it returns `{ kind: 'refund-proposal', ... }` instead (or allocate proportionally with `partialRefund: 'proportional'`). For a receipt it always returns a `refund-proposal`. Without `payment.refunds` it is skipped with a reason.
 - The order number defaults to `{PROVIDER}-{payment id}`, for example `STRIPE-pi_123`, so the payment and its refund share it.
 - Items come from `items`, then the provider's line items, then one item with the paid amount (`fallbackItemName`). VAT comes from `vatFor`, the provider's per-item rate, then `vat`. Without any, it throws `validation`: kassza never guesses VAT.
 - The document total must equal the paid amount, unless `allowAmountMismatch: true`.
-- It returns `{ kind: 'receipt', number, created, receipt, decision, orderNumber }`, `{ kind: 'invoice', number, created, invoice, decision, orderNumber }`, `{ kind: 'reversal', document, reversedNumber, number?, created, orderNumber }` or `{ kind: 'skipped', reason, orderNumber }`.
+- It returns `{ kind: 'receipt', number, created, receipt, decision, orderNumber }`, `{ kind: 'invoice', number, created, invoice, decision, orderNumber }`, `{ kind: 'reversal', document, reversedNumber, number?, created, orderNumber }`, `{ kind: 'correction', correctedNumber, created, corrections: { refundId, externalId, number, created, grossTotal, invoice }[], orderNumber }`, `{ kind: 'refund-proposal', document, documentNumber, refunds: { refundId, grossTotal, items }[], reason, orderNumber }` or `{ kind: 'skipped', reason, orderNumber }`.
 - `issueForPayment(api, payment, options)` from `kassza/payments` does the same with any object that has `invoices` and `receipts` (`createOnce`, `find`, `reverse`), for example a delegated client.
 
+### `kassza/batch`
+
+- `runBatch(kassza, { items: { key, document: () => ({ kind: 'invoice' | 'receipt', input }) }[], concurrency? (1, max 4), ratePerMinute? (30), dryRun?, journal?, signal?, onProgress?, recoveryDelayMs? })` issues each item with `createOnce`, using `key` as the order number, so a rerun never duplicates. It stops (marking the rest `skipped`) on `rate_limit`, `auth`, `account`, `configuration`, `maintenance`, `attempt_limit` or `store_unavailable`; other item errors land in `failed`. `dryRun` previews invoices and computes receipts locally. Returns `{ dryRun, items, created, existing, previewed, failed, skipped, stopped?, grossTotal }`.
+- `billingPeriod({ interval: 'week' | 'month' | 'quarter' | 'year', anchor, paymentDueInDays? }, index)`, `billingPeriodAt(options, date)`, `billingPeriodsBetween(options, from, to)`, `todayPeriod(options)` return `{ index, interval, start, end, dueDate?, key }` in Budapest dates; month ends never drift (Jan 31 → Feb 28/29 → Mar 31). The fulfilment date is the caller's legal decision.
+
+### `kassza/node`
+
+- `toNodeHandler(webHandler, { trustProxy?, onError? })` adapts any `(Request) => Response` handler to Express, NestJS and `node:http`. It streams the raw body (so signatures verify), uses `rawBody` (NestJS) or a Buffer `body` (`express.raw`), and throws `NodeBodyError` when `express.json()` already consumed the body. With Express `next`, errors go to `next`.
+- `toWebRequest(nodeRequest)` and `writeWebResponse(response, nodeResponse)` for Fastify or custom servers.
+
+### `kassza/observe`
+
+- `observe({ logger?, tracer?, metrics?, redact? (true), orderRefSalt?, logRequests? })` returns hooks: structured logs without secrets (order numbers as `hmac:` refs), one span per attempt (OpenTelemetry `Tracer` compatible), and metrics. `combineHooks(...hooks)` merges hook sets.
+- `createMetricsRegistry(buckets?)` is a dependency-free registry with `renderPrometheus()`. Metrics: `kassza_requests_total{action,outcome}`, `kassza_request_duration_ms{action}`, `kassza_retries_total`, `kassza_maintenance_total`, `kassza_unexpected_response_total`, `kassza_store_errors_total{store}`, `kassza_warnings_total{kind}`, `kassza_documents_total{kind,action}`.
+
 ### `kassza/delegation`
 
 ```ts

package/agents/pitfalls.md

@@ -12,7 +12,9 @@ Read this before writing any code that issues invoices or receipts. These rules
 6. **Use the test account while developing.** It allows at most 500 invoices per 10 minutes (error `167`, `rate_limit`). Never run tests against a production Agent key.
 7. **An Agent receipt is a computer-generated receipt (számítógéppel előállított nyugta).** It is not an online cash register receipt and not an e-receipt (e-nyugta). Issue it only for activities without the online cash register (OPG) obligation. Fixed-location retail (TEÁOR 47.1–47.7), restaurants and bars (56.1, 56.3, except mobile catering), accommodation (55.1–55.3), rental (77.1–77.2, 77.33), repair (95.1–95.2) and pharmacies need an online cash register or e-cash register instead. Typical valid uses: webshops, online tickets, downloadable products, food trucks and other mobile sales, services without a cash register obligation.
 8. **A receipt may replace an invoice only if all four conditions hold:** the buyer is not a taxable person or legal entity, the total is below 900 000 HUF, it is paid in full by fulfilment, and the buyer did not ask for an invoice. `chooseDocument()` applies these rules, and `issueForPayment()` uses it. If the buyer asks for an invoice later, use `receipts.convertToInvoice()`.
-9. **Never submit NAV receipt reports for receipts issued in Számlázz.hu.** Számlázz.hu reports them itself after the NAV connection, so a second submission is double reporting. The `kassza/nav` client is read-only unless you pass `allowWrite: true`; submit only reports of paper receipt pads.
+9. **In serverless or multi-process setups, give `createOnce` a shared lock.** Two concurrent deliveries of the same webhook on two instances can both see "no invoice yet". Pass `createOnceLock: store` (Redis, Upstash or Durable Object from `kassza/stores`; Cloudflare KV cannot lock). Calls inside one process are merged automatically.
+10. **If your `onDocument` hook writes a legally relevant journal, set `onDocumentError: 'throw'`.** Otherwise a failed write is only a warning and the NAV daily summary silently misses a receipt. Use `kassza/journal` for this.
+11. **Never submit NAV receipt reports for receipts issued in Számlázz.hu.** Számlázz.hu reports them itself after the NAV connection, so a second submission is double reporting. The `kassza/nav` client is read-only unless you pass `allowWrite: true`; submit only reports of paper receipt pads.
 
 ## Behaviour worth knowing
 
@@ -42,7 +44,14 @@ Read this before writing any code that issues invoices or receipts. These rules
 | Error `250` | A delegated account has not been taken over by its owner, or the delegation is not accepted | Wait for the principal; check with `probeDelegation()` rarely, never in a loop |
 | Error `167` (`rate_limit`) | Too many documents in the test account in a short time | Wait a few minutes; never retry automatically |
 | `attempt_limit` error | The same request already failed 5 times (counted across processes with `attemptLedger`) | A human fixes the cause, then `kassza.resetAttempts(error)` |
+| `attemptLedger` limits | The ledger is conservative: network and timeout failures count too, and the check (read) and the count (increment) are separate store calls, so many processes sending the *same* request at the very same moment can each pass the check | Pair it with `createOnceLock` for documents, so only one process sends at a time |
 | `maintenanceCooldownMs` | After error `1`, kassza sends nothing for the cooldown and throws `maintenance` at once | Switch to a fallback, for example a paper receipt pad |
+| `in_progress` error | Another process holds the `createOnce` lock for this order | Do not issue by hand; call `createOnce` again later (5xx in a webhook) |
+| `store_unavailable` error | The lock store (or a `fail-closed` attempt ledger) is down; nothing was sent | Restore the store, or choose `lockFailure: 'proceed'` / `attemptLedgerMode: 'fail-open'` deliberately |
+| Partial refund on a mixed-VAT invoice | `issueForPayment` returns `refund-proposal`, issues nothing | Pass `refundItems` (what was returned) or `partialRefund: 'proportional'` |
+| `registerPayment` twice | Two payments on the invoice (`additive` defaults to `true`) | Use `registerPaymentOnce({ key })` with a stable bank or payment ID |
+| `szamlaLetoltesPld` (PDF copies) | Obsolete in the XSD; Számlázz.hu ignores it, so kassza does not offer it | Nothing to do |
+| `express.json()` before a webhook route | The raw body is gone, signatures cannot be verified | Mount the route before `express.json()`, or use `express.raw()`; see `kassza/node` |
 
 ## Error categories
 
@@ -59,6 +68,8 @@ Read this before writing any code that issues invoices or receipts. These rules
 | `maintenance` | Számlázz.hu maintenance (code 1) | kassza retries lookups automatically |
 | `rate_limit` | Too many documents in the test account (code 167) | No, wait a few minutes |
 | `attempt_limit` | The request already failed 5 times; kassza did not send it | No, a human must act, then `resetAttempts` |
+| `in_progress` | Another process is issuing the same document (`createOnce` lock) | Later, by calling `createOnce` again |
+| `store_unavailable` | A required store (lock, fail-closed ledger) is down; nothing was sent | After the store is back |
 | `network` / `timeout` | Transport failure; the outcome is unknown for writes | Look up by `orderNumber` before trying again |
 | `configuration` | Missing key, bad options | No |
 | `unexpected_response` | Számlázz.hu answered in an unknown format | Report it |