kassza 0.12.0 → 0.14.0

package/agents/README.md

@@ -6,23 +6,37 @@
 - Receipts (nyugta): create, reverse, get, send by email.
 - Taxpayer lookup from the NAV database.
 
+It also links delegated (principal) accounts through the Agent (`connectPrincipal` in `kassza/delegation`), and ships these modules:
+
+- `kassza/payments`: Stripe, SimplePay, Barion, Revolut and PayPal webhooks that issue a receipt or invoice exactly once, and reverse it on refund.
+- `kassza/reports` and `kassza/nav`: the NAV daily receipt report (mandatory since 2026-09-01), reconciliation with NAV, and a NAV receipt interface client.
+- `kassza/delegation`: invoicing on behalf of many companies, each in its own Számlázz.hu account.
+- `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.
 
 ## Read in this order
 
 1. [pitfalls.md](./pitfalls.md): hard rules. Follow them or you will create duplicate or invalid tax documents.
 2. [api.md](./api.md): every method, input and output.
-3. [recipes.md](./recipes.md): webhooks, idempotent invoicing, receipts, IPN, PDF storage, serverless, tests.
+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
 
 1. Create the client once, on the server only: `createKassza()`. It reads `SZAMLAZZ_AGENT_KEY`.
-2. Always set `orderNumber` on invoices and `callId` on receipts, derived from the order ID.
+2. Always set `orderNumber` on invoices and receipts (and `callId` on receipts), derived from the order ID.
 3. Give prices as `netUnitPrice` or `grossUnitPrice` plus `vat`, and never compute net, VAT or gross yourself.
-4. Never retry `create` in a loop. After a `network`, `timeout`, `partial_success` or `duplicate` error, call `invoices.find({ orderNumber })`.
-5. In tests, use `createMockKassza()` from `kassza/testing` instead of the real API.
+4. Never retry `create` in a loop. Prefer `invoices.createOnce()` and `receipts.createOnce()`: they look the document up, create it, and look it up again after an uncertain failure. With plain `create`, after a `network`, `timeout`, `partial_success` or `duplicate` error, call `invoices.find({ orderNumber })`.
+5. In tests, use `createMockKassza()` or `createFakeAgentFetch()` from `kassza/testing` instead of the real API.
 
 ## Minimal example
 
@@ -31,13 +45,15 @@ import { createKassza } from 'kassza'
 
 const kassza = createKassza()
 
-const invoice = await kassza.invoices.create({
+const { number, created } = await kassza.invoices.createOnce({
   orderNumber: 'ORDER-1001',
   buyer: { name: 'Vevő Kft.', zip: '1111', city: 'Budapest', address: 'Fő utca 1.', email: 'vevo@example.hu' },
   items: [{ name: 'Termék', quantity: 2, grossUnitPrice: 12_700, vat: 27 }],
 })
 ```
 
+`created` is `false` when an earlier call (a redelivered webhook, a retried job) already issued the invoice.
+
 ## Vocabulary
 
 | Hungarian | kassza |
@@ -57,3 +73,7 @@ const invoice = await kassza.invoices.create({
 | áfakulcs | vat |
 | nettó / bruttó egységár | netUnitPrice / grossUnitPrice |
 | Agent kulcs | agentKey |
+| megbízó / megbízott | principal / delegate |
+| pénztárgép-köteles | cashRegisterRequired |
+| napi összesítő (NAV) | navDailyReports |
+| pénzügyi adatkapcsolat | data link |

package/agents/api.md

@@ -11,13 +11,18 @@ const kassza = createKassza({
   agentKey?: string,
   username?: string, password?: string,
   defaults?: { invoice?: InvoiceDefaults, receipt?: ReceiptDefaults },
-  cookieStore?: CookieStore | false,
+  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? },
+  hooks?: { onRequest?, onResponse?, onError?, onComplete?, onDocument?, onDocumentError?, onWarning? },
 })
 ```
 
@@ -27,15 +32,26 @@ 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.
+- `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. `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`
 
 | Method | Returns | Retried automatically |
 |---|---|---|
 | `create(input: CreateInvoiceInput)` | `CreatedInvoice` | never |
+| `createOnce(input: CreateInvoiceInput, options?: CreateOnceOptions)` | `InvoiceOnceResult` | never resends; looks the invoice up instead |
 | `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 |
@@ -44,6 +60,21 @@ const kassza = createKassza({
 
 `InvoiceReference` is `string` (the invoice number), `{ invoiceNumber }`, `{ orderNumber }`, or `{ externalId }`. When several documents share an order number, the latest one is returned.
 
+### createOnce
+
+`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.
+3. After an uncertain failure (`network`, `timeout`, `partial_success`, `duplicate`, `unexpected_response`, `unknown`) it looks the invoice up twice more, after `recoveryDelayMs` (default 1000, doubled for the second lookup).
+
+- `orderNumber` is required. The external ID defaults to the order number with a suffix per type: `/D` proforma, `/E` advance, `/V` final, `/H` corrective, `/SZL` delivery note, none for a normal invoice. Pass `externalId` to override it.
+- `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
 
 ```ts
@@ -136,6 +167,8 @@ Notes on the fields:
 | Method | Returns | Retried automatically |
 |---|---|---|
 | `create(input: CreateReceiptInput)` | `Receipt` | only with `callId` |
+| `createOnce(input: CreateReceiptInput, options?: CreateOnceOptions)` | `{ receipt: Receipt, created: boolean }` | only with `callId` (defaults to `orderNumber`) |
+| `convertToInvoice(input: ConvertReceiptInput, options?: CreateOnceOptions)` | `ConvertedReceipt` | never resends; looks the invoice up instead |
 | `reverse(input: string \| { receiptNumber, callId?, downloadPdf?, template? })` | `Receipt` | only with `callId` |
 | `get(input: string \| { receiptNumber } \| { orderNumber }, + downloadPdf?)` | `Receipt` | yes |
 | `find(same as get)` | `Receipt \| null` | yes |
@@ -161,9 +194,12 @@ Notes on the fields:
 
 `Receipt` is `{ id, number, callId?, type: 'receipt' | 'reversal', isReversed, reversedReceiptNumber?, issueDate, paymentMethod, currency, orderNumber?, items, payments, totals: { netAmount, vatAmount, grossAmount, byVat }, pdf? }`.
 
+- `receipts.createOnce` requires `orderNumber`, uses it as `callId` unless you give one, looks the receipt up by order number first (skip with `lookupFirst: false`), and after error 338 or another uncertain failure returns the receipt that already exists.
+- `receipts.convertToInvoice({ receiptNumber, buyer, orderNumber?, prefix?, comment?, language?, template?, seller?, eInvoice?, downloadPdf?, vatMapping?, allowAlreadyReversed? })` reverses the receipt and issues an invoice for the same items to `buyer`, exactly once. It returns `{ receipt, reversal?, invoice: InvoiceOnceResult }`. The invoice external ID is `CONV/{receiptNumber}`. Receipt-only VAT codes (`ÁKK`, `MAA`, `EU`, `EUK`) need a `vatMapping` entry, chosen with an accountant.
+
 ## Taxpayer: `kassza.taxpayer`
 
-`query(taxNumber: string): TaxpayerInfo` accepts `12345678`, `12345678-2-42` or `HU12345678`.
+`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.'`.
 
@@ -171,6 +207,29 @@ Notes on the fields:
 
 - `kassza.verifyCredentials(): Promise<boolean>` returns `false` for a wrong key and throws for account problems.
 - `kassza.resetSession()` clears the session. Call it after changing account data in Számlázz.hu.
+- `kassza.resetAttempts(errorOrKey)` clears the `attemptLedger` counter of an `attempt_limit` error (or of its `details.attemptKey`).
+- `kassza.issueForPayment(payment, options?)` issues a receipt or invoice for a `PaymentEvent`, exactly once. See `kassza/payments` below.
+
+## Receipt or invoice: `chooseDocument`
+
+```ts
+import { chooseDocument } from 'kassza'
+
+const decision = chooseDocument({
+  grossTotal: 18_990,
+  currency: 'HUF',
+  exchangeRate?: number,
+  buyer?: { taxNumber?, euTaxNumber?, isBusiness? },
+  paidByFulfillment?: boolean,
+  invoiceRequested?: boolean,
+  cashRegisterRequired?: boolean,
+})
+```
+
+- It returns `{ type: 'receipt' | 'invoice' | 'cash-register', reasons: string[], grossTotalHuf }` and makes no network call.
+- `invoice` means at least one of the four receipt conditions fails: a business buyer, a total of 900 000 HUF or more, not paid by fulfilment (`paidByFulfillment: false`), or `invoiceRequested: true`. `reasons` says which, in Hungarian.
+- `cash-register` means a receipt would be due, but the activity needs an online cash register (`cashRegisterRequired: true`), so an Agent receipt must not be issued. An invoice is still allowed.
+- Foreign currency totals need `exchangeRate`, because the limit is in HUF.
 
 ## Subpath modules
 
@@ -183,6 +242,17 @@ createMockKassza({ defaults?, taxpayers?: Record<taxpayerId, TaxpayerInfo>, cred
 - A `MockKassza` has the same interface as `Kassza`, plus `calls`, `invoiceRecords`, `receiptRecords`, `failNext(method, error?)` and `reset()`.
 - The method names used in `calls` and `failNext` look like `'invoices.create'` and `'receipts.send'`.
 - The mock runs the real validation and rounding, and throws the same error codes: 7, 335, 338 and 339.
+- `createMockKassza({ hooks: { onDocument } })` fires the same document events as the real client.
+
+```ts
+createFakeAgentFetch(options?: FakeAgentOptions): FakeAgent
+```
+
+- A fake Számla Agent behind a `fetch`: pass `agent.fetch` to the real `createKassza({ agentKey, fetch: agent.fetch, retryDelayMs: 0 })`. It parses the real request XML, numbers documents, applies the Számlázz.hu rules (259–261, 336–340, 363–365, 395, 152, 202, 524, 7, 335, 339, 53, 57, 3) and answers in the real response formats.
+- `FakeAgent` is `{ fetch, requests, invoices, receipts, fail(fault, { action?, times? }), acceptDelegation(taxNumber), reset() }`.
+- Faults: `'ghostSuccess'` (created, but the response is lost), `'timeout'`, `'networkError'`, `'serverError'`, `'maintenance'`, `'partialSuccess'` (56), `'testAccountLimit'` (167), `'duplicateCallId'` (338), `'duplicateOrderNumber'` (152), or `{ code, message?, afterSuccess? }`.
+- Options: `now`, `agentKeys` and `users` (strict authentication), `testAccount` (default `true`), `invoicePrefixes`, `defaultInvoicePrefix` (default `KASSZA`), `receiptPrefixes`, `rejectDuplicateOrderNumbers` (`boolean` or `{ invoices?, receipts? }`), `seller`, `taxpayers`, `principals` (`{ [taxNumber]: 'owned' | 'unowned' }`), `faults`.
+- Use the mock for business logic, and the fake Agent for webhooks, retries and `createOnce` recovery.
 
 ### `kassza/ipn`
 
@@ -203,5 +273,150 @@ createMockKassza({ defaults?, taxpayers?: Record<taxpayerId, TaxpayerInfo>, cred
 ### `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`
+
+- `storePdf(storage, key, pdf)` and `invoicePdfKey({ number })` save PDFs through adapters: `s3FetchStorage`, `s3Storage`, `r2BindingStorage`, `vercelBlobStorage`, `uploadthingStorage`, `supabaseStorage`, `memoryStorage`, and `fsStorage` from `kassza/storage/fs`.
+
+### `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`
+
+Webhook handlers are `(request: Request) => Promise<Response>`, usable directly as Next.js route handlers, in Hono or in Workers. Each one verifies the request, turns it into a `PaymentEvent` and calls `onPayment`:
+
+| Import | Handler | Required options |
+|---|---|---|
+| `kassza/payments/stripe` | `stripeWebhook` | `secret` (string or array for rotation); optional `apiKey` to load line items and refunds |
+| `kassza/payments/simplepay` | `simplePayWebhook` | `secretKey` or `merchants` |
+| `kassza/payments/barion` | `barionWebhook` | `posKey` |
+| `kassza/payments/revolut` | `revolutWebhook` | `secret`, `apiKey` |
+| `kassza/payments/paypal` | `payPalWebhook` | `webhookId`, `clientId`, `clientSecret` |
+
+- 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?, 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, {
+  vat?: VatRate,
+  vatFor?: (item: PaymentLineItem) => VatRate,
+  items?: PaymentDocumentItem[],
+  fallbackItemName?: string,
+  document?: 'auto' | 'receipt' | 'invoice',
+  buyer?: InvoiceBuyer,
+  buyerIsBusiness?, invoiceRequested?, cashRegisterRequired?,
+  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. `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 }`, `{ 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
+connectPrincipal({ principal, user }, { agentKey?, verifyTaxNumber?, ... }): Promise<ConnectPrincipalResult>
+probeDelegation({ username, password, ... }): Promise<DelegationProbeResult>
+createDelegateKassza({ username, password, invoicePrefix, receiptPrefix?, defaults?, ... }): Kassza
+createKasszaPool({ resolve, maxClients?, ... }): KasszaPool
+```
+
+- `connectPrincipal` (the Agent call `action-agent_ceg_mb`) creates or links a principal's account. `principal` is `{ name, taxNumber, invoicePrefix, zip, city, address, email, postalAddress?, bankName?, bankAccount?, replyToEmail?, cashAccountingFrom?, cashAccountingTo?, kataFrom?, kataTo? }`; `user` is the dedicated user `{ email, password (8–128 characters), firstName, lastName? }`. The tax number must pass the checksum, and the prefix is at most 5 uppercase letters or digits.
+- Its `status` is `'account-created'`, `'owner-invite-resent'`, `'join-request-sent'`, `'join-request-resent'` or `'unknown'`. Every call emails the principal again, so never call it in a loop.
+- `probeDelegation` signs in as the dedicated user and returns `state`: `'active'`, `'awaiting-approval'` (error 3), `'awaiting-owner-registration'` (error 250) or `'multi-account-user'` (error 164). It also re-sends the owner invitation, so call it rarely.
+- `createDelegateKassza` returns a normal `Kassza` that authenticates as the dedicated user and sends the principal's prefix on every document.
+- `createKasszaPool({ resolve: (principalId) => credentials | undefined })` caches clients per principal (LRU, `maxClients` default 100): `get(principalId)`, `forget(principalId)`, `clear()`, `size`.
+- `suggestedPrefix(error)` reads the prefix Számlázz.hu suggests in error 356.
+
+### `kassza/reports`
+
+- `navDailyReports(receipts: Receipt[], { includeTest?, vatCategory?, series? }): NavReceiptReport[]` builds the NAV daily receipt report: one entry per day, receipt series and currency, with `applicableDate`, `series`, `serialNumber` (the first receipt number), `currency`, `exchangeRate`, `vatCategories: [{ vat, saleDocument, modifyingDocument }]`, `total`, `numberOfSaleDocument`, `numberOfModifyingDocument`, `receiptNumbers`. Test-account receipts are skipped unless `includeTest`.
+- `dailyClose(receipts, { includeTest? })` returns per-day totals by payment method and VAT rate.
+- `navVatCategory(vat)` maps a VAT rate to the NAV category (`0%`, `5%`, `18%`, `27%`, `Alanyi adómentes`, `Egyéb`); `describeNavReport(report)` gives a one-line Hungarian summary.
+
+### `kassza/nav`
+
+```ts
+const nav = createNavReceiptClient({
+  environment: 'test' | 'production',
+  login, password | passwordHash, signatureKey, taxNumber,
+  softwareName?, allowWrite?: boolean, timeoutMs?, fetch?,
+})
+```
+
+- Reads: `listReports({ from, to, page?, pageSize? })`, `listAllReports({ from, to })`, `getReport(id)`, `listSoftware()`, `vatCategories()`, `currencies()`.
+- Writes (`submitReport(data)`, `modifyReport(id, data)`, `invalidateReport(id)`, `registerSoftware(name?)`) throw `write_blocked` unless `allowWrite: true`. Never submit receipts that Számlázz.hu reports.
+- `reconcileNavReports(local, remote)` compares local daily reports (for example `navDailyReports()` output) with `listAllReports()` and returns `{ matched, mismatched, missing, unexpected }`.
+- `paperReceiptReport({ applicableDate, currency?, exchangeRate?, entries: [{ number, vat, gross, modifying? }] })` builds the daily report of a paper receipt pad, the one thing you submit yourself.
+- Errors are `NavReceiptError` with `category`, `code`, `hint` and field errors.
+
+### `kassza/data-link`
+
+```ts
+export const POST = dataLinkHandler({
+  keys?: string[],
+  verifyKey?: (key, push) => boolean | 'KEY_ERR' | 'KEY_DEL' | Promise<...>,
+  onPush: (push) => void | { registrationNumber?, keyError? },
+  onError?, maxBodyBytes?,
+})
+```
+
+- Receives the Számlázz.hu financial data link (PUSH). Either `keys` or `verifyKey` is required, because the requests are not signed; the key is in the `X-Szamlazzhu-Key` header.
+- `push.kind` is `'invoice'` or `'incoming-invoice'` (`{ id, invoice: InvoiceDetails, deleted }`), `'bank-transaction'` (`{ transaction }`) or `'receipts'` (`{ receipts: [{ receipt, issuerTaxNumber? }] }`).
+- The handler builds the required response XML. Return `registrationNumber` to store your filing number for invoices. Use the `id` field as the key: the same invoice can arrive again after a payment or reversal.
+- `400` for bad XML (Számlázz.hu retries), `500` when `onPush` throws (retries for 72 hours), `KEY_ERR` for an unknown key, `KEY_DEL` to switch the link off for that customer.
+
+### `kassza/mcp` and the CLI
+
+- `createKasszaMcpServer({ ...KasszaOptions, allowWrite?, confirmationSecret?, confirmationTtlMs? })` is a runtime-neutral Model Context Protocol server; `connect()` returns `{ handle(message), handleLine(line) }`.
+- `npx kassza mcp` runs it over stdio. Tools: `preview_invoice`, `preview_receipt`, `preview_reversal`, `get_invoice`, `get_receipt`, `query_taxpayer`, `nav_daily_summary`, and with `--allow-write` (or `KASSZA_MCP_ALLOW_WRITE=1`) `create_invoice`, `create_receipt`, `reverse_invoice`, `reverse_receipt`. Write tools need the confirmation code returned by the matching preview tool for exactly the same input.
+- Other commands: `kassza doctor` (Node, time zone, key, clock skew, session), `kassza verify`, `kassza xml preview <file.json>` (the XML kassza would send, with the key masked), `kassza invoice get`, `kassza receipt get`, `kassza nav summary --file receipts.json`. Exit codes: 0 success, 1 error, 2 usage.

package/agents/pitfalls.md

@@ -5,11 +5,16 @@ Read this before writing any code that issues invoices or receipts. These rules
 ## Hard rules
 
 1. **Never retry creating an invoice or receipt in a loop.** Számlázz.hu bans accounts that resend requests. kassza already retries only when it is safe to do so. Do not wrap `invoices.create` in your own retry loop.
-2. **After an uncertain failure, look the document up before creating it again.** A timeout, a network error, or error `56` (`partial_success`) can mean the invoice was created anyway. Always set an `orderNumber`, and on those errors call `kassza.invoices.find({ orderNumber })` first.
+2. **After an uncertain failure, look the document up before creating it again.** A timeout, a network error, or error `56` (`partial_success`) can mean the invoice was created anyway. Always set an `orderNumber`, and on those errors call `kassza.invoices.find({ orderNumber })` first. `invoices.createOnce()` and `receipts.createOnce()` do this for you.
 3. **Do not compute item amounts yourself.** Pass `netUnitPrice` (B2B) or `grossUnitPrice` (B2C) plus `vat`, and kassza applies the official rounding rules. Hand-computed floats cause errors 259–264, and on receipts 261 and 363–365.
 4. **Never use `new Date().toISOString().slice(0, 10)` for invoice dates.** Between midnight and 02:00 Budapest time it returns yesterday, which gives error 352. Leave dates out (kassza defaults to today in `Europe/Budapest`) or pass a `Date`.
 5. **The Agent key is a secret and must be lowercase.** Read it from `SZAMLAZZ_AGENT_KEY` on the server only, and never ship it to a browser bundle. kassza rejects keys containing uppercase letters before sending anything.
-6. **Use the test account while developing.** It allows at most 500 invoices per 10 minutes. Never run tests against a production Agent key.
+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. **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
 
@@ -32,7 +37,21 @@ Read this before writing any code that issues invoices or receipts. These rules
 | IPN webhook | Retried every 3 minutes, at most 10 times; only the latest one per invoice is sent | Respond with HTTP 200 quickly and process idempotently |
 | IPN source check | `isSzamlazzIp` checks the rightmost `x-forwarded-for` entry, the address your nearest proxy saw; the left side is client-controlled | Behind several proxies pass `{ trustedProxies: n }`; never feed it a header that no proxy of yours writes |
 | `buyer.groupTaxNumber`, item `dataDeletionCode` | Documented on docs.szamlazz.hu, but missing from the downloadable `xmlszamla.xsd` (and `torloKod` from `xmlnyugtacreate.xsd`) | Use them only when needed; if you get error 57, remove them |
-| NAV receipt data reporting | Mandatory since 2026-09-01, with a grace period until 2026-12-31 | No code change needed yet; watch the kassza changelog |
+| NAV receipt data reporting | Mandatory since 2026-09-01, with a grace period until 2026-12-31; Számlázz.hu reports the receipts issued there after the NAV connection | Check with `navDailyReports()` and `reconcileNavReports()`; report only paper receipts yourself |
+| Receipts and the NAV Online data connection | Számlázz.hu issues receipts only from accounts where the NAV Online data connection is set up | Set it up in Számlázz.hu before the first receipt |
+| Error `524` | The receipt prefix is not enabled in the account | Enable it under Beállítások / Előtagok |
+| Error `491` | KATA protection blocks documents to businesses | Leave out the buyer's tax number, or a human disables the protection |
+| 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
 
@@ -47,6 +66,11 @@ Read this before writing any code that issues invoices or receipts. These rules
 | `not_found` | The document does not exist | No |
 | `partial_success` | The document exists, but a side effect (email) failed | No |
 | `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 |
+| `unknown` | An error code kassza does not know; the original message is kept | No, read `code` and `message` |