kassza 0.12.0 → 0.13.0

package/agents/api.md

@@ -12,12 +12,14 @@ const kassza = createKassza({
   username?: string, password?: string,
   defaults?: { invoice?: InvoiceDefaults, receipt?: ReceiptDefaults },
   cookieStore?: CookieStore | false,
+  attemptLedger?: CookieStore,
   timeoutMs?: number,
   maxAttempts?: number,
   retryDelayMs?: number,
+  maintenanceCooldownMs?: number,
   fetch?: typeof fetch,
   endpoint?: string,
-  hooks?: { onRequest?, onResponse?, onError? },
+  hooks?: { onRequest?, onResponse?, onError?, onDocument? },
 })
 ```
 
@@ -27,12 +29,16 @@ 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)`.
+- `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.
 
 ## 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` |
@@ -44,6 +50,19 @@ 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? })` 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.
+
 ### CreateInvoiceInput
 
 ```ts
@@ -136,6 +155,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 +182,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`.
 
 `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 +195,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 +230,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`
 
@@ -205,3 +263,108 @@ createMockKassza({ defaults?, taxpayers?: Record<taxpayerId, TaxpayerInfo>, cred
 - `calculateInvoiceItem(input, currency?)` and `calculateReceiptItem(input, currency?)` return `ItemAmounts`.
 - `summarizeItems(items)` returns `{ netAmount, vatAmount, grossAmount, byVat }`.
 - `roundMoney(value, decimals)`, `isVatRate(value)`, `NUMERIC_VAT_RATES`, `SPECIAL_VAT_CODES`.
+
+### `kassza/storage` and `kassza/cookie-stores`
+
+- `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/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?, paidAt?, method, customer?, items?, raw }`. Amounts are in major units (12700 HUF, not minor units).
+
+```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,
+  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.
+- 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 }`.
+- `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/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,14 @@ 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. **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 +35,14 @@ 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)` |
+| `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 |
 
 ## Error categories
 
@@ -47,6 +57,9 @@ 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` |
 | `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` |

package/agents/recipes.md

@@ -17,50 +17,37 @@ export const kassza = createKassza({
 
 The client reads `SZAMLAZZ_AGENT_KEY` from the environment. Create it once per process, not once per request, so the session cookie is reused.
 
-## 2. Paid order → invoice, safely (Stripe, Barion, SimplePay webhooks)
+## 2. Paid order → invoice, exactly once (any webhook or job)
 
 ```ts
-import { isSzamlazzError } from 'kassza'
-import { kassza } from './kassza'
-
-export async function invoiceOrder(order: Order) {
-  const orderNumber = `ORDER-${order.id}`
-
-  const existing = await kassza.invoices.find({ orderNumber })
-  if (existing) return existing.header.number
-
-  try {
-    const invoice = await kassza.invoices.create({
-      orderNumber,
-      paid: true,
-      paymentMethod: 'bankkártya',
-      buyer: {
-        name: order.billingName,
-        zip: order.zip,
-        city: order.city,
-        address: order.street,
-        email: order.email,
-        taxNumber: order.taxNumber,
-      },
-      items: order.lines.map((line) => ({
-        name: line.title,
-        quantity: line.quantity,
-        grossUnitPrice: line.unitPriceHuf,
-        vat: 27,
-      })),
-    })
-    return invoice.number
-  } catch (error) {
-    if (isSzamlazzError(error) && ['network', 'timeout', 'partial_success', 'duplicate'].includes(error.category)) {
-      const created = await kassza.invoices.find({ orderNumber })
-      if (created) return created.header.number
-    }
-    throw error
-  }
+import type { Kassza } from 'kassza'
+import { kassza as defaultKassza } from './kassza'
+
+export async function invoiceOrder(order: Order, kassza: Kassza = defaultKassza) {
+  const { number } = await kassza.invoices.createOnce({
+    orderNumber: `ORDER-${order.id}`,
+    paid: true,
+    paymentMethod: 'bankkártya',
+    buyer: {
+      name: order.billingName,
+      zip: order.zip,
+      city: order.city,
+      address: order.street,
+      email: order.email,
+      taxNumber: order.taxNumber,
+    },
+    items: order.lines.map((line) => ({
+      name: line.title,
+      quantity: line.quantity,
+      grossUnitPrice: line.unitPriceHuf,
+      vat: 27,
+    })),
+  })
+  return number
 }
 ```
 
-The first `find` makes the webhook idempotent when the payment provider redelivers the event.
+`createOnce` looks the invoice up first, so a redelivered webhook gets the existing number. After a network error, a timeout or error 56 it looks the invoice up again before giving up, and it never sends the invoice twice. For Stripe, SimplePay, Barion, Revolut and PayPal, recipe 11 does all of this with a ready-made handler.
 
 ## 3. Event registration: proforma → payment → invoice
 
@@ -100,18 +87,25 @@ export async function POST(request: Request) {
 
 Set the webhook URL in Számlázz.hu under Fiók beállítások / Számlázás alapadatok. `markOrderPaid` must be idempotent, because the same notification can arrive more than once.
 
-## 5. Cash register receipt
+## 5. Point-of-sale receipt (food truck, webshop, services)
 
 ```ts
-const receipt = await kassza.receipts.create({
-  callId: `POS-${sale.id}`,
-  paymentMethod: sale.card ? 'bankkártya' : 'készpénz',
-  items: sale.lines.map((line) => ({ name: line.name, quantity: line.qty, grossUnitPrice: line.price, vat: 27 })),
-})
+const { receipt } = await kassza.receipts.createOnce(
+  {
+    orderNumber: `POS-${sale.id}`,
+    paymentMethod: sale.card ? 'bankkártya' : 'készpénz',
+    items: sale.lines.map((line) => ({ name: line.name, quantity: line.qty, grossUnitPrice: line.price, vat: line.vat })),
+  },
+  { lookupFirst: false },
+)
 
 if (sale.email) await kassza.receipts.send({ receiptNumber: receipt.number, emails: sale.email })
 ```
 
+- Agent receipts are only for activities without the online cash register obligation (rule 7 in [pitfalls.md](./pitfalls.md)): a food truck yes, a fixed shop or café no.
+- The order number is also sent as `callId`, so a second tap on the button returns the same receipt (error 338 is handled for you). `lookupFirst: false` skips the lookup before each new sale.
+- If Számlázz.hu is down, sell on a paper receipt pad and report it with `paperReceiptReport` (recipe 13).
+
 ## 6. Save the PDF to S3 or Cloudflare R2 (no AWS SDK needed)
 
 ```ts
@@ -215,3 +209,179 @@ await kassza.invoices.create({
 ```
 
 The exchange rate comes from MNB automatically when `exchangeRate` is omitted. Choose the VAT code together with an accountant.
+
+## 11. Payment provider webhook → receipt or invoice (Stripe, SimplePay, Barion, Revolut, PayPal)
+
+```ts
+// app/api/stripe/webhook/route.ts
+import { isSzamlazzError } from 'kassza'
+import { stripeWebhook } from 'kassza/payments/stripe'
+import { kassza } from '@/lib/kassza'
+
+export const POST = stripeWebhook({
+  secret: process.env.STRIPE_WEBHOOK_SECRET!,
+  apiKey: process.env.STRIPE_SECRET_KEY,
+  onPayment: async (payment) => {
+    try {
+      await kassza.issueForPayment(payment, { vat: 27 })
+    } catch (error) {
+      if (isSzamlazzError(error) && !error.retryable) {
+        await parkForHuman(payment.id, `${error.category}: ${error.message}`)
+        return
+      }
+      throw error
+    }
+  },
+})
+```
+
+- The handler verifies the signature and answers 400, 200 or 500 itself. A thrown error means 500, and the provider redelivers, which is safe: `issueForPayment` looks the document up first.
+- Catch non-retryable errors (a missing VAT rate, an incomplete billing address) and hand them to a human, otherwise the provider keeps redelivering a request that can never succeed. `parkForHuman` is your own function.
+- The same pattern works with `simplePayWebhook`, `barionWebhook`, `revolutWebhook` and `payPalWebhook`; only the credentials differ (see [api.md](./api.md)).
+- A full refund reverses the document. A partial refund is skipped on purpose: it needs a corrective document decided by a human.
+- The receipt prefix and payment method come from the client's `defaults.receipt` (recipe 1). Pass `receipt: { ... }` or `invoice: { ... }` only to override fields; a receipt prefix must never be one already used on invoices (error 336).
+
+## 12. Receipt or invoice, and an invoice after a receipt
+
+```ts
+import { chooseDocument } from 'kassza'
+
+const decision = chooseDocument({
+  grossTotal: order.total,
+  buyer: { taxNumber: order.taxNumber },
+  invoiceRequested: order.wantsInvoice,
+})
+
+if (decision.type === 'receipt') {
+  await kassza.receipts.createOnce({ orderNumber: `ORDER-${order.id}`, paymentMethod: 'bankkártya', items })
+} else {
+  await kassza.invoices.createOnce({ orderNumber: `ORDER-${order.id}`, paid: true, buyer, items })
+}
+```
+
+When a buyer asks for an invoice after getting a receipt:
+
+```ts
+const converted = await kassza.receipts.convertToInvoice({
+  receiptNumber: 'NYGT-2026-118',
+  buyer: { name: 'Példa Kft.', zip: '1111', city: 'Budapest', address: 'Fő utca 1.', taxNumber: '12345676-2-42' },
+})
+
+converted.reversal?.number
+converted.invoice.number
+```
+
+It reverses the receipt and invoices the same items, exactly once (external ID `CONV/{receiptNumber}`).
+
+## 13. NAV daily receipt report: check it, do not double-report
+
+```ts
+import { createNavReceiptClient, reconcileNavReports } from 'kassza/nav'
+import { navDailyReports } from 'kassza/reports'
+
+const nav = createNavReceiptClient({
+  environment: 'production',
+  login: process.env.NAV_LOGIN!,
+  password: process.env.NAV_PASSWORD!,
+  signatureKey: process.env.NAV_SIGNATURE_KEY!,
+  taxNumber: process.env.NAV_TAX_NUMBER!,
+})
+
+const local = navDailyReports(await receiptsBetween('2026-09-01', '2026-09-30'))
+const remote = await nav.listAllReports({ from: '2026-09-01', to: '2026-09-30' })
+const { missing, mismatched } = reconcileNavReports(local, remote)
+```
+
+- Számlázz.hu reports the receipts issued there after the NAV connection, so this client stays read-only (no `allowWrite`). Alert a human about `missing` and `mismatched` days.
+- `receiptsBetween` is your own query over stored `Receipt` objects (from `receipts.get`, `issueForPayment` results, or the data link in recipe 15).
+- Only receipts that Számlázz.hu does not know about, such as a paper pad used during an outage, are yours to submit: `nav.submitReport(paperReceiptReport({ applicableDate, entries }))` with `allowWrite: true`.
+
+## 14. Platform invoicing for many companies (delegated invoicing)
+
+```ts
+import { createKasszaPool } from 'kassza/delegation'
+import { upstashRedisCookieStore } from 'kassza/cookie-stores'
+import { Redis } from '@upstash/redis'
+
+const redis = Redis.fromEnv()
+
+export const pool = createKasszaPool({
+  resolve: async (merchantId) => {
+    const merchant = await loadMerchant(merchantId)
+    if (!merchant) return undefined
+    return { username: merchant.delegateUser, password: merchant.delegatePassword, invoicePrefix: merchant.prefix }
+  },
+  cookieStore: upstashRedisCookieStore(redis),
+  attemptLedger: upstashRedisCookieStore(redis),
+})
+
+const kassza = await pool.get('merchant-42')
+await kassza.invoices.createOnce({ orderNumber: 'BOOKING-881', buyer, items })
+```
+
+- Link each merchant once with `connectPrincipal` from `kassza/delegation`, then wait until the merchant accepts. Check with `probeDelegation` rarely: every call emails the merchant again.
+- Store the dedicated user's password encrypted. Call `pool.forget(merchantId)` when it or the prefix changes.
+
+## 15. Receive the Számlázz.hu financial data link (accounting or ERP systems)
+
+```ts
+// app/api/szamlazz/data-link/route.ts
+import { dataLinkHandler } from 'kassza/data-link'
+
+export const POST = dataLinkHandler({
+  verifyKey: async (key) => (await customerKeys()).includes(key),
+  onPush: async (push) => {
+    if (push.kind === 'invoice' || push.kind === 'incoming-invoice') {
+      const registrationNumber = await saveInvoice(push.id, push.invoice, push.deleted)
+      return { registrationNumber }
+    }
+    if (push.kind === 'bank-transaction') await saveTransaction(push.transaction)
+    if (push.kind === 'receipts') await saveReceipts(push.receipts)
+  },
+})
+```
+
+- The requests are not signed, so the key check is mandatory: `keys` or `verifyKey`.
+- Upsert invoices by `push.id`, because the same invoice arrives again after a payment or a reversal.
+- Keep `onPush` fast (save and return). A slow or failing endpoint is retried for 72 hours and can get the whole receiving system switched off by Számlázz.hu.
+
+## 16. Integration tests with the fake Számla Agent
+
+```ts
+import { createKassza } from 'kassza'
+import { createFakeAgentFetch } from 'kassza/testing'
+import { expect, test } from 'vitest'
+
+test('a lost response does not create a second invoice', async () => {
+  const agent = createFakeAgentFetch()
+  const kassza = createKassza({ agentKey: 'test-key', fetch: agent.fetch, retryDelayMs: 0 })
+  agent.fail('ghostSuccess', { action: 'createInvoice' })
+
+  const result = await kassza.invoices.createOnce(
+    { orderNumber: 'WEB-1', buyer, items },
+    { recoveryDelayMs: 0 },
+  )
+
+  expect(result.created).toBe(true)
+  expect(agent.invoices.size).toBe(1)
+})
+```
+
+The fake Agent runs the real kassza code (XML, multipart, response parsing, retries, `createOnce` recovery) against an in-memory Számla Agent. `agent.requests` shows every request kassza sent.
+
+## 17. Invoicing from an AI assistant (MCP)
+
+```json
+{
+  "mcpServers": {
+    "kassza": {
+      "command": "npx",
+      "args": ["-y", "kassza", "mcp"],
+      "env": { "SZAMLAZZ_AGENT_KEY": "..." }
+    }
+  }
+}
+```
+
+- The server is read-only by default. Add `"--allow-write"` to `args` to enable issuing and reversing; even then every write needs the confirmation code from the matching preview tool, for exactly the same input.
+- Start with a Számlázz.hu test account.

package/agents/skills/kassza/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kassza
-description: Issue Hungarian invoices, proformas and receipts through Számlázz.hu with the kassza npm package. Use when code creates, reverses, queries or emails számla, díjbekérő or nyugta documents, handles Számlázz.hu IPN webhooks, looks up Hungarian tax numbers, or mentions szamlazz.hu, Számla Agent or SZAMLAZZ_AGENT_KEY.
+description: Issue Hungarian invoices, proformas and receipts through Számlázz.hu with the kassza npm package. Use when code creates, reverses, queries or emails számla, díjbekérő or nyugta documents, turns Stripe, SimplePay, Barion, Revolut or PayPal payments into documents, handles Számlázz.hu IPN or data link webhooks, builds NAV daily receipt reports, invoices on behalf of other companies (megbízott számlázás), looks up Hungarian tax numbers, or mentions szamlazz.hu, Számla Agent or SZAMLAZZ_AGENT_KEY.
 ---
 
 # kassza: Számlázz.hu integration
@@ -9,21 +9,24 @@ Before writing code, read the package docs from `node_modules/kassza/agents/`:
 
 - `pitfalls.md`: hard rules, always read it.
 - `api.md`: exact method signatures.
-- `recipes.md`: patterns for webhooks, receipts, IPN, PDF storage, serverless and tests.
+- `recipes.md`: patterns for webhooks, payment providers, receipts, IPN, NAV reports, delegated invoicing, PDF storage, serverless and tests.
 
 ## Non-negotiable rules
 
 1. Create one server-side client with `createKassza()`. The key comes from `SZAMLAZZ_AGENT_KEY`. Never import kassza in client-side code.
-2. Set `orderNumber` on every invoice and `callId` on every receipt, derived from the order ID.
+2. Set `orderNumber` on every invoice and receipt (and `callId` on receipts), derived from the order ID.
 3. Give prices as `netUnitPrice` (B2B) or `grossUnitPrice` (B2C) together with `vat`. Do not compute item amounts, and do not pass UTC date strings.
-4. Never retry `invoices.create` or `receipts.create` yourself. On an error with category `network`, `timeout`, `partial_success` or `duplicate`, call `kassza.invoices.find({ orderNumber })` before doing anything else.
+4. Never retry `invoices.create` or `receipts.create` yourself. Prefer `invoices.createOnce()` and `receipts.createOnce()`. With plain `create`, on an error with category `network`, `timeout`, `partial_success` or `duplicate`, call `kassza.invoices.find({ orderNumber })` before doing anything else.
 5. Branch on `SzamlazzError.category` and `code`, not on message text.
-6. Tests must use `createMockKassza()` from `kassza/testing`, never a real Agent key.
+6. Tests must use `createMockKassza()` or `createFakeAgentFetch()` from `kassza/testing`, never a real Agent key.
+7. Issue Agent receipts only for activities without the online cash register obligation, and only when all four receipt conditions hold (`chooseDocument()` checks them). A fixed shop, café or restaurant needs an online cash register instead.
+8. Never submit NAV receipt reports for receipts issued in Számlázz.hu; it reports them itself. Use `kassza/nav` read-only unless the user explicitly reports a paper receipt pad.
 
 ## Checklist before finishing
 
-- [ ] The webhook or job that issues documents is idempotent: it runs `find` first, or catches `duplicate`.
+- [ ] The webhook or job that issues documents is idempotent: it uses `createOnce`, runs `find` first, or catches `duplicate`.
+- [ ] Payment provider webhooks use the `kassza/payments` handlers with `issueForPayment`, and non-retryable errors are handed to a human instead of being rethrown forever.
 - [ ] The PDF is stored (`kassza/storage`) or re-fetched with `invoices.getPdf`, not stored as base64 in the database.
 - [ ] The IPN route returns HTTP 200 (`ipnOkResponse()`) and processes notifications idempotently.
-- [ ] In serverless or edge environments, a shared `cookieStore` from `kassza/cookie-stores` is configured.
-- [ ] There is a unit test with `createMockKassza()`.
+- [ ] In serverless or edge environments, a shared `cookieStore` (and, with several processes, an `attemptLedger`) from `kassza/cookie-stores` is configured.
+- [ ] There is a unit test with `createMockKassza()`, or an integration test with `createFakeAgentFetch()`.