kassza 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 futozs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/npm/kassza@0/assets/logo-wordmark.svg" alt="kassza" width="480">
+</p>
+
+<p align="center">
+  <b>Számlázz.hu, TypeScriptben, egyszerűbben.</b><br>
+  Számla, díjbekérő, nyugta, sztornó, befizetés, PDF, adószám. Mind a 11 Agent művelet, 0 függőség.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/kassza"><img src="https://img.shields.io/npm/v/kassza?color=14532D" alt="npm"></a>
+  <a href="https://www.npmjs.com/package/kassza"><img src="https://img.shields.io/npm/dm/kassza?color=14532D" alt="letöltések"></a>
+  <img src="https://img.shields.io/badge/függőség-0-14532D" alt="0 függőség">
+  <img src="https://img.shields.io/npm/l/kassza?color=14532D" alt="MIT">
+</p>
+
+```bash
+npm i kassza
+```
+
+Node 22+, Bun, Deno, Cloudflare Workers és Vercel Edge alatt is fut.
+
+## Számla 10 sorban
+
+```ts
+import { createKassza } from 'kassza'
+
+const kassza = createKassza({ agentKey: process.env.SZAMLAZZ_AGENT_KEY })
+
+const szamla = await kassza.invoices.create({
+  buyer: { name: 'Vevő Kft.', zip: '1111', city: 'Budapest', address: 'Fő utca 1.', email: 'vevo@example.hu' },
+  items: [{ name: 'Webfejlesztés', quantity: 10, unit: 'óra', netUnitPrice: 15_000, vat: 27 }],
+})
+
+szamla.number
+szamla.grossTotal
+szamla.pdf
+```
+
+Ha van e-mail cím, a Számlázz.hu ki is küldi a számlát. A kerekítést, a magyar dátumot és az XML-t a csomag intézi.
+
+## Nyugta
+
+```ts
+const nyugta = await kassza.receipts.create({
+  prefix: 'NYGT',
+  paymentMethod: 'bankkártya',
+  items: [{ name: 'Kávé', grossUnitPrice: 890, vat: 27 }],
+})
+
+await kassza.receipts.send({ receiptNumber: nyugta.number, emails: 'vevo@example.hu' })
+```
+
+## Díjbekérő, befizetés, számla
+
+```ts
+const dijbekero = await kassza.invoices.create({
+  type: 'proforma',
+  orderNumber: 'REND-42',
+  buyer,
+  items: [{ name: 'Nevezési díj', grossUnitPrice: 26_000, vat: 27 }],
+})
+
+const szamla = await kassza.invoices.create({ proformaNumber: dijbekero.number, orderNumber: 'REND-42', buyer, items })
+await kassza.invoices.registerPayment({ invoiceNumber: szamla.number, amount: szamla.grossTotal })
+```
+
+## Minden más
+
+| Mit | Hogyan |
+|---|---|
+| Előleg-, vég-, helyesbítő számla, szállítólevél | `type: 'advance' \| 'final' \| 'corrective' \| 'deliveryNote'` |
+| Bruttó ár (B2C) vagy nettó ár (B2B) | `grossUnitPrice` vagy `netUnitPrice` |
+| Devizás számla | `currency: 'EUR'` (az árfolyam alapból MNB) |
+| Előnézeti PDF, bizonylat nélkül | `kassza.invoices.preview(input)` |
+| Sztornó | `kassza.invoices.reverse('E-2026-12')` |
+| PDF utólag | `kassza.invoices.getPdf({ orderNumber: 'REND-42' })` |
+| Teljes számla adatai | `kassza.invoices.get(...)` vagy `find(...)` (`null`, ha nincs) |
+| Díjbekérő törlése | `kassza.invoices.deleteProforma({ orderNumber: 'REND-42' })` |
+| Nyugta sztornó, lekérdezés | `kassza.receipts.reverse(...)`, `get(...)`, `find(...)` |
+| Cégadatok adószámból (NAV) | `kassza.taxpayer.query('13421739')` |
+| Jó-e az Agent kulcs? | `kassza.verifyCredentials()` |
+
+Közös alapértékek egyszer, a kliensnél:
+
+```ts
+const kassza = createKassza({
+  defaults: {
+    invoice: { prefix: 'WEB', paymentDueInDays: 8, seller: { emailReplyTo: 'penzugy@ceg.hu' } },
+    receipt: { prefix: 'NYGT', paymentMethod: 'bankkártya' },
+  },
+})
+```
+
+Az `agentKey` elhagyható, ha a `SZAMLAZZ_AGENT_KEY` környezeti változó be van állítva.
+
+## Hibák
+
+Minden hiba `SzamlazzError`, magyar üzenettel és tippel.
+
+```ts
+import { isSzamlazzError } from 'kassza'
+
+try {
+  await kassza.invoices.create(input)
+} catch (error) {
+  if (!isSzamlazzError(error)) throw error
+  error.code
+  error.category
+  error.hint
+  error.isDuplicate
+}
+```
+
+A kategóriák: `auth`, `account`, `validation`, `duplicate`, `not_found`, `partial_success`, `maintenance`, `network`, `timeout`, `configuration`, `unexpected_response`.
+
+A csomag magától csak ott próbálkozik újra, ahol ez biztonságos: lekérdezésnél, hálózati hibánál és karbantartásnál, legfeljebb 5-ször. Számlát soha nem küld újra. A Számlázz.hu kitiltja azt, aki ciklusban próbálkozik.
+
+## Tesztelés API hívás nélkül
+
+```ts
+import { createMockKassza } from 'kassza/testing'
+
+const kassza = createMockKassza()
+const szamla = await kassza.invoices.create(input)
+kassza.calls
+kassza.failNext('invoices.create')
+```
+
+A mock ugyanazt a validációt és kerekítést futtatja, mint az éles kliens.
+
+## Kiegészítők
+
+| Import | Mire jó |
+|---|---|
+| `kassza/ipn` | Fizetési értesítés (IPN) webhook: `readIpnNotification(request)` |
+| `kassza/validators` | Adószám, bankszámla, IBAN, irányítószám, cím, EU adószám ellenőrzés |
+| `kassza/money` | Nettó/bruttó/áfa számítás a hivatalos kerekítési szabályokkal |
+| `kassza/storage` | PDF mentése S3, R2, Vercel Blob, UploadThing, Supabase tárhelyre |
+| `kassza/storage/fs` | PDF mentése fájlrendszerbe (Node) |
+| `kassza/cookie-stores` | Session megosztás serverlessben: Upstash, Redis, Cloudflare KV |
+| `kassza/testing` | Mock kliens unit tesztekhez |
+
+## AI-val kódolsz?
+
+A csomagban van egy `agents/` mappa, amiből a Claude Code, a Cursor, a Copilot és a többi asszisztens megtudja, hogyan kell jól használni a kasszát, és mik a buktatók. Mutasd meg neki: `node_modules/kassza/agents/README.md`.
+
+---
+
+Nem hivatalos csomag, nem kapcsolódik a KBOSS.hu Kft.-hez (Számlázz.hu). Hivatalos dokumentáció: [docs.szamlazz.hu](https://docs.szamlazz.hu/hu/agent/). MIT licenc.

package/agents/README.md

@@ -0,0 +1,59 @@
+# kassza for AI coding agents
+
+`kassza` is a zero-dependency TypeScript client for the Számlázz.hu Számla Agent API, the most widely used Hungarian invoicing service. It covers all 11 Agent operations:
+
+- Invoices: create (invoice, proforma, advance, final, corrective, delivery note), preview, reverse, register payment, PDF, full invoice data, delete proforma.
+- Receipts (nyugta): create, reverse, get, send by email.
+- Taxpayer lookup from the NAV database.
+
+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.
+
+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.
+
+## 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.
+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.
+
+## Minimal example
+
+```ts
+import { createKassza } from 'kassza'
+
+const kassza = createKassza()
+
+const invoice = await kassza.invoices.create({
+  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 }],
+})
+```
+
+## Vocabulary
+
+| Hungarian | kassza |
+|---|---|
+| számla | invoice |
+| díjbekérő | proforma |
+| előlegszámla / végszámla | advance / final |
+| helyesbítő számla | corrective |
+| szállítólevél | deliveryNote |
+| sztornó | reverse / reversal |
+| nyugta | receipt |
+| befizetés, jóváírás | payment |
+| rendelésszám | orderNumber |
+| hívásazonosító | callId |
+| számlaszám előtag | prefix |
+| adószám / közösségi adószám | taxNumber / euTaxNumber |
+| áfakulcs | vat |
+| nettó / bruttó egységár | netUnitPrice / grossUnitPrice |
+| Agent kulcs | agentKey |

package/agents/api.md

@@ -0,0 +1,206 @@
+# kassza: API reference for coding agents
+
+All types are exported from `kassza`, so import them instead of redefining them. Every method throws `SzamlazzError` on failure and accepts an optional last argument `{ signal?: AbortSignal }`.
+
+## Client
+
+```ts
+import { createKassza } from 'kassza'
+
+const kassza = createKassza({
+  agentKey?: string,
+  username?: string, password?: string,
+  defaults?: { invoice?: InvoiceDefaults, receipt?: ReceiptDefaults },
+  cookieStore?: CookieStore | false,
+  timeoutMs?: number,
+  maxAttempts?: number,
+  retryDelayMs?: number,
+  fetch?: typeof fetch,
+  endpoint?: string,
+  hooks?: { onRequest?, onResponse?, onError? },
+})
+```
+
+- `agentKey` falls back to the `SZAMLAZZ_AGENT_KEY` environment variable.
+- `username` and `password` are legacy credentials; prefer the Agent key.
+- `cookieStore` defaults to an in-memory store; `false` disables session reuse.
+- `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.
+
+## Invoices: `kassza.invoices`
+
+| Method | Returns | Retried automatically |
+|---|---|---|
+| `create(input: CreateInvoiceInput)` | `CreatedInvoice` | never |
+| `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` |
+| `clearPayments(input: string \| { invoiceNumber })` | `RegisteredPayment` | yes |
+| `getPdf(ref: InvoiceReference)` | `InvoicePdf` | yes |
+| `get(ref: InvoiceReference, { includePdf? })` | `InvoiceDetails` | yes |
+| `find(ref: InvoiceReference, { includePdf? })` | `InvoiceDetails \| null` | yes |
+| `deleteProforma(ref: string \| { proformaNumber } \| { orderNumber })` | `void` | never |
+
+`InvoiceReference` is `string` (the invoice number), `{ invoiceNumber }`, `{ orderNumber }`, or `{ externalId }`. When several documents share an order number, the latest one is returned.
+
+### CreateInvoiceInput
+
+```ts
+{
+  type?: 'invoice' | 'proforma' | 'advance' | 'deliveryNote'
+       | 'final' | 'corrective',
+  advanceInvoiceNumber?: string,
+  correctedInvoiceNumber?: string,
+
+  buyer: {
+    name: string, zip: string, city: string, address: string,
+    country?, email?, sendEmail?, taxNumber?, euTaxNumber?, groupTaxNumber?,
+    taxpayerType?: 'hungarianTaxNumber' | 'euBusiness' | 'nonEuBusiness' | 'noTaxNumber' | 'unknown',
+    postal?: { name?, country?, zip?, city?, address? },
+    identifier?, phone?, comment?, signatoryName?, ledger?,
+  },
+  items: Array<{
+    name: string,
+    vat: VatRate,
+    quantity?: number,
+    unit?: string,
+    netUnitPrice?: number,
+    grossUnitPrice?: number,
+    netAmount?, vatAmount?, grossAmount?,
+    identifier?, comment?, ledger?, dataDeletionCode?, marginVatBase?,
+  }>,
+
+  issueDate?: Date | 'YYYY-MM-DD',
+  fulfillmentDate?, dueDate?, paymentDueInDays?: number,
+  paymentMethod?: string,
+  currency?: string,
+  exchangeRate?: number,
+  exchangeBank?: string,
+  language?: 'hu' | 'en' | 'de' | 'it' | 'ro' | 'sk' | 'hr' | 'fr' | 'es' | 'cz' | 'pl' | 'bg' | 'nl' | 'ru' | 'si',
+  orderNumber?: string,
+  proformaNumber?: string,
+  externalId?: string,
+  prefix?: string,
+  comment?, paid?: boolean,
+  eInvoice?: boolean,
+  downloadPdf?: boolean,
+  seller?: { bank?, bankAccount?, emailReplyTo?, emailSubject?, emailText?, signatoryName? },
+  template?: 'SzlaMost' | 'SzlaAlap' | 'SzlaNoEnv' | 'Szla8cm' | 'SzlaTomb' | 'SzlaFuvarlevelesAlap',
+  attachments?: Array<{ filename, content: Uint8Array | ArrayBuffer | Blob | string, contentType? }>,
+  waybill?, simpleItems?, euVat?, marginVat?, paymentCorrection?, logoExtra?,
+}
+```
+
+Notes on the fields:
+
+- `type` defaults to `'invoice'`. `'final'` optionally takes `advanceInvoiceNumber`, and `'corrective'` requires `correctedInvoiceNumber`.
+- In `items`:
+  - `quantity` defaults to 1 and may be negative on final or corrective invoices.
+  - `unit` defaults to `'db'`.
+  - Give exactly one of `netUnitPrice` (B2B, net-based rounding) and `grossUnitPrice` (B2C, gross-based rounding).
+  - Use `netAmount`, `vatAmount` and `grossAmount` only to override the calculation, and give all three.
+- All dates default to today in `Europe/Budapest`.
+- `paymentMethod` defaults to `'Átutalás'`.
+- `currency` defaults to `'HUF'`. For other currencies, `exchangeBank` defaults to MNB, and `exchangeRate` is required unless the bank is MNB.
+- `orderNumber` is your ID. Always set it, because it enables `find` and deduplication.
+- `proformaNumber` links the invoice to the proforma it was paid from. `externalId` is an ID for lookups.
+- `prefix` must be registered in the Számlázz.hu account (error 202).
+- `eInvoice` defaults to `false`, and `downloadPdf` defaults to `true`.
+- `attachments` allows at most 5 files, 2 MB each, and they are sent only by email.
+
+`VatRate` is one of 0, 5, 18, 27 (plus the other rates allowed by Számlázz.hu) or one of `'TAM' | 'AAM' | 'EUT' | 'EUKT' | 'F.AFA' | 'K.AFA' | 'TAHK' | 'HO' | 'EUE' | 'EUFADE' | 'EUFAD37' | 'ATK' | 'NAM' | 'EAM' | 'KBAUK' | 'KBAET'`.
+
+`CreatedInvoice` is `{ number, netTotal, grossTotal, outstanding?, buyerAccountUrl?, pdf?: Uint8Array, items: ItemAmounts[] }`.
+
+### RegisterPaymentInput
+
+```ts
+{ invoiceNumber, amount, method?: string, date?, description?, additive? }
+{ invoiceNumber, payments: Array<{ amount, method, date?, description? }>, additive?, taxNumber? }
+```
+
+- The single-payment form defaults `method` to `'átutalás'` and `date` to today.
+- The multi-payment form accepts at most 5 payments.
+- `additive` defaults to `true`, which appends to earlier payments; `false` replaces them.
+
+### ReverseInvoiceOptions
+
+```ts
+{ invoiceNumber, issueDate?, fulfillmentDate?, comment?, template?, eInvoice?, downloadPdf?, externalId?,
+  email?: { replyTo?, subject?, text? }, buyer?: { email?, taxNumber?, euTaxNumber? } }
+```
+
+## Receipts: `kassza.receipts`
+
+| Method | Returns | Retried automatically |
+|---|---|---|
+| `create(input: CreateReceiptInput)` | `Receipt` | only with `callId` |
+| `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 |
+| `send({ receiptNumber, emails: string \| string[], replyTo?, subject?, text? })` | `void` | never |
+
+```ts
+{
+  prefix: string,
+  paymentMethod: string,
+  items: Array<{ name, vat: VatRate | 'ÁKK' | 'MAA' | 'EU' | 'EUK', quantity?, unit?,
+                 netUnitPrice? | grossUnitPrice?, identifier?, comment?, ledger? }>,
+  callId?: string,
+  orderNumber?, comment?, currency?, exchangeRate?, exchangeBank?,
+  payments?: Array<{ method, amount, description? }>,
+  template?: 'A' | 'N' | 'J' | 'L', downloadPdf?,
+}
+```
+
+- `prefix` accepts uppercase letters and digits only. Give it in the input or in `defaults.receipt`.
+- `paymentMethod` has no default: `'készpénz'`, `'bankkártya'` or anything else must be given here or in `defaults.receipt`.
+- `callId` is an idempotency key; set it from your order ID.
+- If you pass `payments`, their sum must equal the gross total.
+
+`Receipt` is `{ id, number, callId?, type: 'receipt' | 'reversal', isReversed, reversedReceiptNumber?, issueDate, paymentMethod, currency, orderNumber?, items, payments, totals: { netAmount, vatAmount, grossAmount, byVat }, pdf? }`.
+
+## Taxpayer: `kassza.taxpayer`
+
+`query(taxNumber: string): TaxpayerInfo` accepts `12345678`, `12345678-2-42` or `HU12345678`.
+
+`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.'`.
+
+## Other
+
+- `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.
+
+## Subpath modules
+
+### `kassza/testing`
+
+```ts
+createMockKassza({ defaults?, taxpayers?: Record<taxpayerId, TaxpayerInfo>, credentialsValid?, now?: () => Date }): MockKassza
+```
+
+- 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.
+
+### `kassza/ipn`
+
+- `readIpnNotification(request: Request): Promise<IpnNotification>`, for Next.js route handlers, Hono, Workers and similar.
+- `parseIpnNotification(body: string | URLSearchParams | FormData | Record<string, string>): IpnNotification`
+- `IpnNotification` is `{ invoiceNumber, proformaNumber?, orderNumber?, grossTotal, paidAmount, paymentMethod?, paymentDate?, isFullyPaid, raw }`.
+- `ipnOkResponse(): Response`
+- `isSzamlazzIp(ip)` and `SZAMLAZZ_OUTBOUND_IPS`.
+
+### `kassza/validators`
+
+- Tax number: `parseHungarianTaxNumber`, `isValidHungarianTaxNumber` (CDV check), `isValidHungarianTaxpayerId`, `isValidHungarianGroupTaxNumber`.
+- Bank account: `parseHungarianBankAccount`, `isValidHungarianBankAccount`, `formatHungarianBankAccount`, `isValidHungarianIban`.
+- Address: `isValidHungarianZipCode`, `parseHungarianAddress('1234 Budapest, Fő utca 1.')` returns `{ zip, city, address, district? }`.
+- Other: `isValidEuVatNumber`, `normalizeEuVatNumber`, `isValidEmail`, `normalizeEmail`, `isValidAgentKey`.
+
+### `kassza/money`
+
+- `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`.

package/agents/pitfalls.md

@@ -0,0 +1,52 @@
+# kassza: rules and pitfalls
+
+Read this before writing any code that issues invoices or receipts. These rules come from the official Számlázz.hu docs and from production incidents. Breaking them produces invalid tax documents, duplicate invoices, or a banned API key.
+
+## 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.
+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.
+
+## Behaviour worth knowing
+
+| Situation | What happens | What to do |
+|---|---|---|
+| Buyer has an `email` | `sendEmail` defaults to `true`, so Számlázz.hu emails the invoice | Set `buyer.sendEmail: false` to suppress it |
+| Error `71` / `152` (`duplicate`) | The account forbids repeating an order number; the document probably exists already | `find({ orderNumber })` and reuse it |
+| Error `56` (`partial_success`) | The invoice was created, but the notification email failed | Do **not** create it again |
+| Error `7` | Lookup found nothing (or a required field is missing) | `find()` returns `null` for this |
+| Error `202` | The invoice prefix is not registered in the account | Add it under Beállítások / Előtagok, or remove `prefix` |
+| Error `136` | The subscription has expired or is unpaid | A human has to log in to szamlazz.hu |
+| Error `54` | E-invoicing is not enabled in the account | Use `eInvoice: false` (the default) |
+| Receipt prefix | Uppercase letters and digits only, and it must not be a prefix already used on invoices (336, 337) | Use a dedicated prefix such as `NYGT` |
+| Receipt `callId` | Idempotency key; resending the same `callId` returns error 338 instead of a duplicate | Always set it from your order ID |
+| Final invoice (`type: 'final'`) | Needs `advanceInvoiceNumber` or the same `orderNumber` as the advance invoice | Only one final invoice per advance invoice |
+| `invoices.get` / XML query | Works only for outgoing invoices issued in Számlázz.hu | Use `getPdf` for the PDF only |
+| Reversing a proforma or delivery note | Számlázz.hu returns the original document and reverses nothing; kassza throws a `validation` error | Use `invoices.deleteProforma` instead |
+| `registerPayment` | `additive` defaults to `true` and appends to earlier payments | Use `clearPayments` to wipe them |
+| Session cookie | Expires after 90 minutes of inactivity; the in-memory store is per process | In serverless, pass a shared `cookieStore` from `kassza/cookie-stores` |
+| 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` trusts the first `x-forwarded-for` entry | Use it only behind a proxy you control |
+| `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 |
+
+## Error categories
+
+`SzamlazzError.category` is one of:
+
+| Category | Meaning | Retry? |
+|---|---|---|
+| `auth` | Wrong key, or a browser session is interfering | No, fix the credentials |
+| `account` | Subscription, e-invoice, or data-deletion-code settings | No, a human must act |
+| `validation` | The request is wrong (client-side or server-side check) | No, fix the input |
+| `duplicate` | Order number or `callId` already used | No, look the document up |
+| `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 |
+| `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 |