kassza 0.12.0 → 0.14.0

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
@@ -142,19 +136,21 @@ Other adapters with the same interface:
 - `fsStorage` from `kassza/storage/fs`
 - `memoryStorage`
 
-## 7. Serverless and edge: share the session
+## 7. Serverless and edge: share the session, the ledger and the lock
 
 ```ts
 import { Redis } from '@upstash/redis'
 import { createKassza } from 'kassza'
-import { upstashRedisCookieStore } from 'kassza/cookie-stores'
+import { upstashRedisStore } from 'kassza/stores'
 
-const kassza = createKassza({ cookieStore: upstashRedisCookieStore(Redis.fromEnv()) })
+const store = upstashRedisStore(Redis.fromEnv())
+const kassza = createKassza({ cookieStore: store, attemptLedger: store, createOnceLock: store })
 ```
 
-- On Cloudflare Workers, use `cloudflareKvCookieStore(env.KASSZA_KV)`.
-- Other stores: `ioredisCookieStore`, `nodeRedisCookieStore`, `customCookieStore({ get, set, delete })`.
-- If the store fails, kassza simply continues without a session.
+- `createOnceLock` prevents a duplicate invoice when two instances process the same order at the same time.
+- On Cloudflare Workers, `cloudflareKvStore(env.KASSZA_KV)` is fine for the session, but locks and the journal need `durableObjectStore(stub)` (KV has no atomic write).
+- Other stores: `ioredisStore`, `nodeRedisStore`, `customStore({ get, set, delete })`. `diagnoseStore(store)` tells what a store is suitable for.
+- If the session store fails, kassza continues without a session and reports it to `hooks.onWarning`.
 
 ## 8. Unit tests without calling Számlázz.hu
 
@@ -215,3 +211,236 @@ 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 of an invoice issues one corrective invoice per refund; with several VAT rates (and always for receipts) it returns a `refund-proposal` instead, unless you pass `refundItems` or `partialRefund: 'proportional'`.
+- Add `dedupe: store` to acknowledge redelivered events without calling Számla Agent again.
+- Under Express or NestJS, wrap the handler: `app.post(path, toNodeHandler(stripeWebhook({ ... })))` from `kassza/node`, mounted before `express.json()`.
+- 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.
+- Get the receipts from `kassza/journal`: `journal.receipts({ from, to })` (see recipe 18). Without it you need your own query over stored `Receipt` objects.
+- 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.
+
+## 18. Receipt journal for the NAV daily summary
+
+```ts
+import { createKassza } from 'kassza'
+import { createJournal, kvJournal } from 'kassza/journal'
+import { navDailyReports } from 'kassza/reports'
+import { upstashRedisStore } from 'kassza/stores'
+
+const store = upstashRedisStore(Redis.fromEnv())
+export const journal = createJournal(kvJournal(store))
+export const kassza = createKassza({
+  createOnceLock: store,
+  hooks: { onDocument: (event) => journal.record(event), onDocumentError: 'throw' },
+})
+
+await journal.trackReceipt(order.id, () => kassza.receipts.createOnce({ orderNumber: order.id, items }))
+const reports = navDailyReports(await journal.receipts({ from: '2026-10-01', to: '2026-10-31' }))
+await journal.settle(kassza)
+```
+
+- `trackReceipt` leaves a pending entry when the outcome is unknown; schedule `journal.settle(kassza)` (for example daily) to resolve them.
+- `journal.reconcile(push.receipts)` with the data link archive adds receipts the journal missed.
+
+## 19. Monthly subscription invoicing
+
+```ts
+import { billingPeriodAt, runBatch } from 'kassza/batch'
+
+const period = billingPeriodAt({ interval: 'month', anchor: '2026-01-31', paymentDueInDays: 8 }, new Date())
+const result = await runBatch(kassza, {
+  items: subscriptions.map((subscription) => ({
+    key: `SUB-${subscription.id}-${period.start}`,
+    document: () => ({ kind: 'invoice', input: invoiceFor(subscription, period) }),
+  })),
+  journal,
+})
+if (result.stopped) alertHuman(result.stopped.reason)
+```
+
+- Run it from your scheduler (Vercel Cron, Workers Cron). A rerun reports already issued items as `existing`.
+- Try `dryRun: true` first: invoices are previewed by Számlázz.hu, nothing is created.
+
+## 20. Observability without telemetry
+
+```ts
+import { combineHooks, createMetricsRegistry, observe } from 'kassza/observe'
+
+export const metrics = createMetricsRegistry()
+export const kassza = createKassza({
+  hooks: combineHooks(observe({ logger, tracer, metrics }), { onDocument: (event) => journal.record(event) }),
+})
+```
+
+- Expose `metrics.renderPrometheus()` on an internal endpoint. Alert on `kassza_store_errors_total` and `kassza_unexpected_response_total`.

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,27 @@ 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.
+9. In serverless or multi-instance deployments, pass a shared `createOnceLock` store from `kassza/stores` (Redis, Upstash or Durable Object; not Cloudflare KV), so two instances cannot issue the same order twice.
+10. When `onDocument` writes a journal used for NAV reports (`kassza/journal`), set `onDocumentError: 'throw'` so a missed write is never silent.
+11. Under Express or NestJS, wrap webhook handlers with `toNodeHandler` from `kassza/node` and mount them before `express.json()`.
 
 ## 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()`.

package/agents/skills/migrate-from-szamlazz-js/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: migrate-from-szamlazz-js
+description: Migrate a codebase from the szamlazz.js npm package to kassza. Use when the user asks to replace, upgrade or migrate away from szamlazz.js, or when code imports Client, Invoice, Buyer, Seller or Item from 'szamlazz.js' and the user wants kassza instead.
+---
+
+# Migrate from szamlazz.js to kassza
+
+Read `node_modules/kassza/agents/pitfalls.md` and `api.md` first.
+
+## Find the usage
+
+Search for `from 'szamlazz.js'`, `require('szamlazz.js')`, `new Client(`, `issueInvoice(`, `getInvoiceData(` and `reverseInvoice(`. List every call site to the user before editing.
+
+## Mapping
+
+| szamlazz.js | kassza |
+|---|---|
+| `new Client({ authToken })` | one shared `createKassza({ agentKey })` (or `SZAMLAZZ_AGENT_KEY`) |
+| `requestInvoiceDownload`, `eInvoice`, `timeout` | `downloadPdf`, `eInvoice` (per invoice or in `defaults.invoice`), `timeoutMs` |
+| `new Seller({ bank: { name, accountNumber }, email: { replyToAddress, subject, message } })` | `seller: { bank, bankAccount, emailReplyTo, emailSubject, emailText }` |
+| `new Buyer({ ..., postAddress })` | plain object `buyer: { name, zip, city, address, taxNumber?, postal? }` |
+| `new Item({ label, ... })` | `{ name, quantity, unit, vat, netUnitPrice | grossUnitPrice }` |
+| `client.issueInvoice(new Invoice({...}))` | `kassza.invoices.createOnce({ orderNumber, ... })` |
+| `prepaymentInvoice: true` | `type: 'advance'` |
+| `adjustmentInvoiceNumber` | `type: 'corrective', correctedInvoiceNumber` |
+| `PaymentMethods.*`, `Currencies.*`, `Languages.*` | plain strings: `'átutalás'`, `'HUF'`, `'hu'` |
+| `getInvoiceData({ invoiceId | orderNumber, pdf })` | `invoices.get(number | { orderNumber }, { includePdf })` or `find(...)` |
+| `reverseInvoice({ invoiceId, eInvoice, requestInvoiceDownload })` | `invoices.reverse({ invoiceNumber, eInvoice, downloadPdf })` |
+| result `invoiceId`, string totals, `customerAccountUrl`, Buffer `pdf` | `number`, numeric totals, `buyerAccountUrl`, `Uint8Array` `pdf` |
+
+## Rules while migrating
+
+1. Every invoice gets an `orderNumber` from the user's order ID, and is issued with `createOnce`. Ask if no stable order ID exists.
+2. Delete any custom retry loop around invoice creation. kassza never resends a create.
+3. Keep `netUnitPrice` or `grossUnitPrice` as the user had it; never convert prices by hand.
+4. Replace string totals parsing (`Number(result.grossTotal)`) with the numeric fields.
+5. Replace error handling on message text with `isSzamlazzError(error)` and `error.category`.
+6. Update tests to `createMockKassza()` or `createFakeAgentFetch()` from `kassza/testing`.
+7. Remove `szamlazz.js` from `package.json` only after the user confirms every call site was migrated.