kassza 0.1.0 → 0.1.2

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/kassza@0/assets/logo-wordmark.svg" alt="kassza" width="480">
+  <img src="https://raw.githubusercontent.com/futozs/kassza/main/assets/logo-wordmark.svg" alt="kassza" width="460">
 </p>
 
 <p align="center">
@@ -8,95 +8,357 @@
 </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>
+  <a href="https://www.npmjs.com/package/kassza"><img src="https://img.shields.io/npm/v/kassza?color=14532D&label=npm" alt="npm verzió"></a>
+  <a href="https://www.npmjs.com/package/kassza"><img src="https://img.shields.io/npm/dm/kassza?color=14532D&label=letöltés" alt="havi letöltés"></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">
+  <img src="https://img.shields.io/badge/TypeScript-szigorú-14532D" alt="TypeScript">
+  <img src="https://img.shields.io/npm/l/kassza?color=14532D&label=licenc" alt="MIT licenc">
 </p>
 
 ```bash
 npm i kassza
 ```
 
-Node 22+, Bun, Deno, Cloudflare Workers és Vercel Edge alatt is fut.
+```ts
+import { createKassza } from 'kassza'
+
+const kassza = createKassza()
+
+const szamla = await kassza.invoices.create({
+  buyer: { name: 'Vevő Kft.', zip: '1111', city: 'Budapest', address: 'Fő utca 1.', email: 'vevo@ceg.hu' },
+  items: [{ name: 'Webfejlesztés', quantity: 10, unit: 'óra', netUnitPrice: 15_000, vat: 27 }],
+})
+
+console.log(szamla.number, szamla.grossTotal)
+```
+
+Ennyi. A kerekítést, a magyar dátumot, az XML-t, a session cookie-t és a hibakezelést a kassza intézi, a vevő pedig e-mailben megkapja a számlát.
+
+## Miért kassza?
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/futozs/kassza/main/assets/comparison.svg" alt="Számla Agent műveletek: kassza 11, a többi csomag 2–3" width="720">
+</p>
+
+|  | **kassza** | szamlazz.js | @ribbery009/ szamlazz-ts | @halftome/ szamlazz-client | szamlazz.ts | szamlazzhu-client |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| Számla, sztornó | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Számla adatainak lekérése | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| **Nyugta** (létrehozás, sztornó, lekérdezés, kiküldés) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Befizetés rögzítése** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **PDF lekérése utólag** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Díjbekérő törlése** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| **Adószám lekérdezés (NAV)** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Runtime függőség | **0** | 6 | 6 | 1 | 7 | 3 |
+| TypeScript típusok | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
+| Edge (Workers, Vercel Edge) | ✅ | ❌ | ❌ | – | ❌ | ❌ |
+| Mock kliens teszteléshez | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| IPN webhook, validátorok, PDF tárhely | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+<sub>A műveleteket 2026 szeptemberében a publikált csomagok kódjában ellenőriztük (melyik Agent form mezőt küldik). Az Edge oszlopban ❌ az axios, tough-cookie vagy form-data függőség miatt szerepel, ezek nem futnak Workers alatt. A „–” azt jelenti, hogy nem teszteltük.</sub>
+
+## Tartalom
+
+- [Beállítás](#beállítás)
+- [Számlák](#számlák)
+- [Nyugták](#nyugták)
+- [Adószám lekérdezés](#adószám-lekérdezés)
+- [Hibakezelés](#hibakezelés)
+- [Fizetési értesítés (IPN)](#fizetési-értesítés-ipn)
+- [PDF mentése tárhelyre](#pdf-mentése-tárhelyre)
+- [Serverless és edge](#serverless-és-edge)
+- [Tesztelés](#tesztelés)
+- [Validátorok és pénzszámítás](#validátorok-és-pénzszámítás)
+- [Haladó beállítások](#haladó-beállítások)
+- [AI-val kódolsz?](#ai-val-kódolsz)
+
+## Beállítás
+
+Az Agent kulcsot a Számlázz.hu felületén, a vezérlőpult alján generálhatod.
 
-## Számla 10 sorban
+```bash
+SZAMLAZZ_AGENT_KEY=a-te-agent-kulcsod
+```
 
 ```ts
 import { createKassza } from 'kassza'
 
-const kassza = createKassza({ agentKey: process.env.SZAMLAZZ_AGENT_KEY })
+export const kassza = createKassza()
+```
+
+Az ismétlődő adatokat elég egyszer megadni:
+
+```ts
+export const kassza = createKassza({
+  agentKey: process.env.SZAMLAZZ_AGENT_KEY,
+  defaults: {
+    invoice: {
+      prefix: 'WEB',
+      paymentDueInDays: 8,
+      seller: { emailReplyTo: 'penzugy@ceg.hu', emailSubject: 'Elkészült a számlád' },
+    },
+    receipt: { prefix: 'NYGT', paymentMethod: 'bankkártya' },
+  },
+})
+
+await kassza.verifyCredentials()
+```
+
+A `verifyCredentials()` visszatérési értéke `true`, ha a kulcs jó.
+
+## Számlák
+
+### Számla
 
+```ts
 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 }],
+  orderNumber: 'REND-1001',
+  paymentMethod: 'bankkártya',
+  paid: true,
+  buyer: {
+    name: 'Vevő Kft.',
+    zip: '1111',
+    city: 'Budapest',
+    address: 'Fő utca 1.',
+    email: 'vevo@ceg.hu',
+    taxNumber: '12345678-2-42',
+  },
+  items: [
+    { name: 'Póló', quantity: 2, grossUnitPrice: 5_990, vat: 27 },
+    { name: 'Szállítás', grossUnitPrice: 1_490, vat: 27 },
+  ],
 })
 
 szamla.number
+szamla.netTotal
 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.
+- Az `orderNumber` a saját azonosítód, ezzel később vissza is keresheted a számlát.
+- A `szamla.pdf` egy `Uint8Array`.
 
-## Nyugta
+Az ár megadható nettóban vagy bruttóban, a kerekítés a hivatalos szabályok szerint történik:
 
 ```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' })
+{ name: 'Tanácsadás', netUnitPrice: 20_000, vat: 27 }
+{ name: 'Belépő', grossUnitPrice: 4_990, vat: 27 }
+{ name: 'Könyv', grossUnitPrice: 3_500, vat: 5 }
+{ name: 'Oktatás', netUnitPrice: 50_000, vat: 'AAM' }
 ```
 
-## Díjbekérő, befizetés, számla
+A nettó ár a B2B számlákhoz, a bruttó ár a B2C számlákhoz való. Az `'AAM'` alanyi adómentes tételt jelöl.
+
+### Díjbekérő, majd számla
 
 ```ts
 const dijbekero = await kassza.invoices.create({
   type: 'proforma',
-  orderNumber: 'REND-42',
+  orderNumber: 'NEV-42',
   buyer,
-  items: [{ name: 'Nevezési díj', grossUnitPrice: 26_000, vat: 27 }],
+  items,
 })
 
-const szamla = await kassza.invoices.create({ proformaNumber: dijbekero.number, orderNumber: 'REND-42', buyer, items })
-await kassza.invoices.registerPayment({ invoiceNumber: szamla.number, amount: szamla.grossTotal })
+const szamla = await kassza.invoices.create({
+  proformaNumber: dijbekero.number,
+  orderNumber: 'NEV-42',
+  paid: true,
+  buyer,
+  items,
+})
 ```
 
-## Minden más
+### Díjbekérő törlése
 
-| 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()` |
+```ts
+await kassza.invoices.deleteProforma({ orderNumber: 'NEV-42' })
+```
 
-Közös alapértékek egyszer, a kliensnél:
+### Előleg- és végszámla
 
 ```ts
-const kassza = createKassza({
-  defaults: {
-    invoice: { prefix: 'WEB', paymentDueInDays: 8, seller: { emailReplyTo: 'penzugy@ceg.hu' } },
-    receipt: { prefix: 'NYGT', paymentMethod: 'bankkártya' },
+const eloleg = await kassza.invoices.create({
+  type: 'advance',
+  orderNumber: 'PROJ-7',
+  buyer,
+  items: [{ name: 'Előleg', netUnitPrice: 300_000, vat: 27 }],
+})
+
+await kassza.invoices.create({
+  type: 'final',
+  advanceInvoiceNumber: eloleg.number,
+  orderNumber: 'PROJ-7',
+  buyer,
+  items: [
+    { name: 'Weboldal', netUnitPrice: 1_000_000, vat: 27 },
+    { name: 'Előleg levonása', quantity: -1, netUnitPrice: 300_000, vat: 27 },
+  ],
+})
+```
+
+### Helyesbítő számla
+
+```ts
+await kassza.invoices.create({
+  type: 'corrective',
+  correctedInvoiceNumber: 'E-WEB-2026-12',
+  buyer,
+  items: [{ name: 'Póló visszáru', quantity: -1, grossUnitPrice: 5_990, vat: 27 }],
+})
+```
+
+### Szállítólevél
+
+```ts
+await kassza.invoices.create({ type: 'deliveryNote', buyer, items })
+```
+
+### Devizás számla, külföldi vevő
+
+```ts
+await kassza.invoices.create({
+  currency: 'EUR',
+  language: 'en',
+  buyer: {
+    name: 'Acme GmbH',
+    country: 'Germany',
+    zip: '10115',
+    city: 'Berlin',
+    address: 'Hauptstr. 1',
+    euTaxNumber: 'DE123456789',
+    taxpayerType: 'euBusiness',
   },
+  items: [{ name: 'Consulting', quantity: 8, unit: 'hour', netUnitPrice: 95, vat: 'EUFAD37' }],
+})
+```
+
+Az árfolyam, ha nem adod meg, automatikusan az MNB aktuális árfolyama.
+
+### Előnézet, számla kiállítása nélkül
+
+```ts
+const { pdf, grossTotal } = await kassza.invoices.preview({ buyer, items })
+```
+
+### Melléklet az e-mailhez
+
+```ts
+await kassza.invoices.create({
+  buyer,
+  items,
+  attachments: [{ filename: 'aszf.pdf', content: aszfPdfBytes, contentType: 'application/pdf' }],
 })
 ```
 
-Az `agentKey` elhagyható, ha a `SZAMLAZZ_AGENT_KEY` környezeti változó be van állítva.
+Legfeljebb 5 melléklet adható meg, darabonként 2 MB.
+
+### Sztornó
+
+```ts
+const sztorno = await kassza.invoices.reverse('E-WEB-2026-12')
+```
+
+### Befizetés rögzítése
+
+```ts
+await kassza.invoices.registerPayment({ invoiceNumber: 'E-WEB-2026-12', amount: 12_700 })
+
+await kassza.invoices.registerPayment({
+  invoiceNumber: 'E-WEB-2026-13',
+  payments: [
+    { method: 'készpénz', amount: 5_000, date: '2026-09-01' },
+    { method: 'átutalás', amount: 7_700 },
+  ],
+})
+
+await kassza.invoices.clearPayments('E-WEB-2026-12')
+```
+
+A `registerPayment` egyetlen befizetést és több részletet is fogad. A `clearPayments` az összes befizetést törli a számláról.
+
+### PDF letöltése utólag
+
+```ts
+import { writeFile } from 'node:fs/promises'
+
+const { pdf } = await kassza.invoices.getPdf('E-WEB-2026-12')
+await writeFile('szamla.pdf', pdf)
+```
+
+Rendelésszám vagy külső azonosító alapján is működik: `getPdf({ orderNumber: 'REND-1001' })`, `getPdf({ externalId: 'a1b2' })`.
 
-## Hibák
+### Számla adatainak lekérése
 
-Minden hiba `SzamlazzError`, magyar üzenettel és tippel.
+```ts
+const adatok = await kassza.invoices.get({ orderNumber: 'REND-1001' })
+adatok.header.issueDate
+adatok.buyer.name
+adatok.items
+adatok.payments
+
+const talan = await kassza.invoices.find({ orderNumber: 'REND-9999' })
+```
+
+A `find` `null`-t ad, ha nincs ilyen számla, a `get` ilyenkor hibát dob.
+
+## Nyugták
+
+### Nyugta
+
+```ts
+const nyugta = await kassza.receipts.create({
+  prefix: 'NYGT',
+  paymentMethod: 'készpénz',
+  callId: 'KASSZA-2026-0001',
+  items: [
+    { name: 'Kávé', quantity: 2, grossUnitPrice: 890, vat: 27 },
+    { name: 'Kifli', grossUnitPrice: 250, vat: 5 },
+  ],
+})
+
+nyugta.number
+nyugta.totals.grossAmount
+nyugta.pdf
+```
+
+A `callId` véd a dupla nyugta ellen.
+
+### Kiküldés e-mailben
+
+```ts
+await kassza.receipts.send({ receiptNumber: nyugta.number, emails: 'vevo@ceg.hu' })
+```
+
+### Lekérdezés
+
+```ts
+const ugyanaz = await kassza.receipts.get(nyugta.number)
+const rendelesbol = await kassza.receipts.find({ orderNumber: 'REND-1001' })
+```
+
+### Sztornó
+
+```ts
+await kassza.receipts.reverse(nyugta.number)
+```
+
+## Adószám lekérdezés
+
+```ts
+const ceg = await kassza.taxpayer.query('13421739')
+
+if (ceg.valid) {
+  ceg.name
+  ceg.taxNumber?.formatted
+  ceg.address?.formatted
+}
+```
+
+A cégadatok a NAV-tól jönnek, a cím formázva, például `1031 Budapest, Záhony utca 7.`
+
+## Hibakezelés
+
+Minden hiba `SzamlazzError`, magyar üzenettel és javítási tippel.
 
 ```ts
 import { isSzamlazzError } from 'kassza'
@@ -105,46 +367,187 @@ try {
   await kassza.invoices.create(input)
 } catch (error) {
   if (!isSzamlazzError(error)) throw error
-  error.code
-  error.category
-  error.hint
-  error.isDuplicate
+
+  if (error.isDuplicate) return kassza.invoices.find({ orderNumber: input.orderNumber! })
+  if (error.category === 'validation') console.error(error.message, error.hint)
+  throw error
 }
 ```
 
-A kategóriák: `auth`, `account`, `validation`, `duplicate`, `not_found`, `partial_success`, `maintenance`, `network`, `timeout`, `configuration`, `unexpected_response`.
+- `error.code`: a Számlázz.hu hibakódja, például `57`.
+- `error.hint`: magyar javítási tipp.
+
+| `error.category` | Jelentés |
+|---|---|
+| `validation` | Hibás adat, a kérés el sem ment, vagy a Számlázz.hu elutasította |
+| `duplicate` | Ez a rendelésszám vagy `callId` már létezik |
+| `partial_success` | A számla elkészült, csak az e-mail nem ment ki. **Ne állítsd ki újra!** |
+| `not_found` | Nincs ilyen bizonylat |
+| `auth` / `account` | Rossz kulcs, lejárt előfizetés |
+| `network` / `timeout` / `maintenance` | Átmeneti hiba |
 
-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.
+Újraküldés csak ott történik magától, ahol biztonságos: lekérdezéseknél, hálózati hibánál, legfeljebb 5-ször. **Számlát a kassza soha nem küld újra.** A Számlázz.hu kitiltja azt, aki ciklusban próbálkozik. Bizonytalan hiba után a `find({ orderNumber })` megmondja, elkészült-e a számla.
 
-## Tesztelés API hívás nélkül
+## Fizetési értesítés (IPN)
+
+A Számlázz.hu értesít, ha egy számlát kifizettek. Például egy Next.js route handlerben:
 
 ```ts
-import { createMockKassza } from 'kassza/testing'
+import { ipnOkResponse, readIpnNotification } from 'kassza/ipn'
+
+export async function POST(request: Request) {
+  const ipn = await readIpnNotification(request)
+
+  if (ipn.isFullyPaid) await rendelesFizetve(ipn.orderNumber, ipn.paidAmount)
+
+  return ipnOkResponse()
+}
+```
+
+Csak a Számlázz.hu IP-címeiről jövő kérést érdemes elfogadni:
+
+```ts
+import { isSzamlazzIp } from 'kassza/ipn'
+
+isSzamlazzIp(request.headers.get('x-forwarded-for') ?? '')
+```
+
+## PDF mentése tárhelyre
+
+S3, Cloudflare R2, MinIO vagy Backblaze esetén nem kell az AWS SDK:
+
+```ts
+import { invoicePdfKey, s3FetchStorage, storePdf } from 'kassza/storage'
+
+const tarhely = s3FetchStorage({
+  bucket: 'szamlak',
+  region: 'auto',
+  endpoint: 'https://<account-id>.r2.cloudflarestorage.com',
+  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+})
 
-const kassza = createMockKassza()
 const szamla = await kassza.invoices.create(input)
-kassza.calls
-kassza.failNext('invoices.create')
+const fajl = await storePdf(tarhely, invoicePdfKey({ number: szamla.number }), szamla.pdf!)
+
+fajl.key
 ```
 
-A mock ugyanazt a validációt és kerekítést futtatja, mint az éles kliens.
+A kulcs például `szamlak/2026/09/E-WEB-2026-12.pdf` lesz.
 
-## Kiegészítők
+Fájlrendszerbe (Node):
 
-| 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 |
+```ts
+import { fsStorage } from 'kassza/storage/fs'
+
+const tarhely = fsStorage({ directory: './szamlak' })
+```
+
+További adapterek: `s3Storage` (AWS SDK), `r2BindingStorage`, `vercelBlobStorage`, `uploadthingStorage`, `supabaseStorage`, `memoryStorage`.
+
+## Serverless és edge
+
+A session cookie újrahasznosítása gyorsítja a hívásokat. Serverless környezetben tedd közös tárolóba:
+
+```ts
+import { Redis } from '@upstash/redis'
+import { upstashRedisCookieStore } from 'kassza/cookie-stores'
+
+const kassza = createKassza({ cookieStore: upstashRedisCookieStore(Redis.fromEnv()) })
+```
+
+Cloudflare Workers alatt:
+
+```ts
+import { cloudflareKvCookieStore } from 'kassza/cookie-stores'
+
+const kassza = createKassza({ agentKey: env.SZAMLAZZ_AGENT_KEY, cookieStore: cloudflareKvCookieStore(env.KASSZA_KV) })
+```
+
+Van még `ioredisCookieStore`, `nodeRedisCookieStore` és `customCookieStore` is. Ha a tároló elérhetetlen, a számlázás attól még működik.
+
+## Tesztelés
+
+A mock kliens valódi API-hívás nélkül működik, de ugyanazt a validációt és kerekítést futtatja, mint az éles kliens.
+
+```ts
+import { createMockKassza } from 'kassza/testing'
+
+test('fizetés után számlát állít ki', async () => {
+  const kassza = createMockKassza()
+
+  await fizetesKezelo(rendeles, kassza)
+
+  expect(kassza.calls.map((call) => call.method)).toEqual(['invoices.create'])
+  expect([...kassza.invoiceRecords.values()][0]?.details.totals.grossAmount).toBe(12_700)
+})
+
+test('hálózati hibánál nem számláz kétszer', async () => {
+  const kassza = createMockKassza()
+  kassza.failNext('invoices.create')
+
+  await expect(fizetesKezelo(rendeles, kassza)).rejects.toThrow()
+})
+```
+
+## Validátorok és pénzszámítás
+
+```ts
+import {
+  isValidHungarianBankAccount,
+  isValidHungarianTaxNumber,
+  parseHungarianAddress,
+} from 'kassza/validators'
+
+isValidHungarianTaxNumber('13421739-2-41')
+isValidHungarianBankAccount('11773016-11111018')
+parseHungarianAddress('1031 Budapest, Záhony utca 7.')
+```
+
+A `parseHungarianAddress` eredménye `{ zip: '1031', city: 'Budapest', address: 'Záhony utca 7.' }`. Ezen kívül van `isValidHungarianIban`, `isValidHungarianZipCode`, `isValidEuVatNumber` és `isValidEmail` is.
+
+```ts
+import { calculateInvoiceItem, calculateReceiptItem } from 'kassza/money'
+
+calculateInvoiceItem({ quantity: 3, grossUnitPrice: 500, vat: 27 })
+calculateReceiptItem({ grossUnitPrice: 1_000, vat: 27 })
+```
+
+Az első eredménye `{ netAmount: 1181, vatAmount: 319, grossAmount: 1500, ... }`, a másodiké `{ netAmount: 787.4, vatAmount: 212.6, grossAmount: 1000, ... }`.
+
+## Haladó beállítások
+
+```ts
+const kassza = createKassza({
+  timeoutMs: 30_000,
+  maxAttempts: 3,
+  hooks: {
+    onResponse: ({ action, status, durationMs }) => logger.info({ action, status, durationMs }),
+    onError: ({ action, error, willRetry }) => logger.warn({ action, code: error.code, willRetry }),
+  },
+})
+
+await kassza.invoices.getPdf('E-WEB-2026-12', { signal: AbortSignal.timeout(5_000) })
+```
+
+- A `maxAttempts` csak a lekérdezésekre vonatkozik, és legfeljebb 5 lehet.
+- A hookok soha nem kapják meg az Agent kulcsot.
+- Minden metódus fogad `AbortSignal`-t.
+
+A `resetSession()` új sessiont kér. Hívd meg, ha a Számlázz.hu fiókban megváltoztak a cégadatok:
+
+```ts
+await kassza.resetSession()
+```
 
 ## 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`.
+A csomagban van egy `agents/` mappa. Ebbő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. Szólj rá az AI-ra:
+
+> Használd a kassza csomagot, és előbb olvasd el a `node_modules/kassza/agents/README.md`-t.
+
+Claude Code-hoz kész skill is van: másold a `node_modules/kassza/agents/skills/kassza` mappát a projekted `.claude/skills/` mappájába.
 
 ---
 
-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.
+<sub>Nem hivatalos csomag, nem kapcsolódik a KBOSS.hu Kft.-hez (Számlázz.hu). A hivatalos dokumentáció a <a href="https://docs.szamlazz.hu/hu/agent/">docs.szamlazz.hu</a> oldalon érhető el. MIT licenc.</sub>

package/assets/comparison.svg

@@ -0,0 +1,39 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="344" viewBox="0 0 760 344" role="img" aria-labelledby="t d">
+  <title id="t">Számla Agent műveletek, 11-ből</title>
+  <desc id="d">kassza 11, szamlazz.js 3, @ribbery009/szamlazz-ts 3, @halftome/szamlazz-client 3, szamlazz.ts 3, szamlazzhu-client 2</desc>
+  <style>
+    text{font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif}
+    .title{fill:#111827;font-size:22px;font-weight:700}.sub{fill:#6B7280;font-size:14px}
+    .label{fill:#374151;font-size:15px}.label.hi{fill:#111827;font-weight:700}
+    .value{fill:#374151;font-size:15px;font-variant-numeric:tabular-nums}.value.hi{fill:#111827;font-weight:700}
+    .bar{fill:#9CA3AF}.bar.hi{fill:#14532D}.track{fill:#E5E7EB}.card{fill:#FFFFFF;stroke:#E5E7EB}
+    @media (prefers-color-scheme:dark){.title,.label.hi,.value.hi{fill:#F9FAFB}.sub{fill:#9CA3AF}.label,.value{fill:#D1D5DB}.bar{fill:#6B7280}.bar.hi{fill:#22C55E}.track{fill:#1F2937}.card{fill:#0D1117;stroke:#30363D}}
+  </style>
+  <rect class="card" x="0.5" y="0.5" width="759" height="343" rx="12"/>
+  <text class="title" x="16" y="34">Számla Agent műveletek, 11-ből</text>
+  <text class="sub" x="16" y="58">A csomagok publikált kódjában ellenőrizve, 2026. szeptember</text>
+  <text class="label hi" x="256" y="106" text-anchor="end">kassza</text>
+  <rect class="track" x="272" y="92" width="374" height="18" rx="4"/>
+  <rect class="bar hi" x="272" y="92" width="374" height="18" rx="4"/>
+  <text class="value hi" x="658" y="106">11/11</text>
+  <text class="label" x="256" y="144" text-anchor="end">szamlazz.js</text>
+  <rect class="track" x="272" y="130" width="374" height="18" rx="4"/>
+  <rect class="bar" x="272" y="130" width="102" height="18" rx="4"/>
+  <text class="value" x="658" y="144">3/11</text>
+  <text class="label" x="256" y="182" text-anchor="end">@ribbery009/szamlazz-ts</text>
+  <rect class="track" x="272" y="168" width="374" height="18" rx="4"/>
+  <rect class="bar" x="272" y="168" width="102" height="18" rx="4"/>
+  <text class="value" x="658" y="182">3/11</text>
+  <text class="label" x="256" y="220" text-anchor="end">@halftome/szamlazz-client</text>
+  <rect class="track" x="272" y="206" width="374" height="18" rx="4"/>
+  <rect class="bar" x="272" y="206" width="102" height="18" rx="4"/>
+  <text class="value" x="658" y="220">3/11</text>
+  <text class="label" x="256" y="258" text-anchor="end">szamlazz.ts</text>
+  <rect class="track" x="272" y="244" width="374" height="18" rx="4"/>
+  <rect class="bar" x="272" y="244" width="102" height="18" rx="4"/>
+  <text class="value" x="658" y="258">3/11</text>
+  <text class="label" x="256" y="296" text-anchor="end">szamlazzhu-client</text>
+  <rect class="track" x="272" y="282" width="374" height="18" rx="4"/>
+  <rect class="bar" x="272" y="282" width="68" height="18" rx="4"/>
+  <text class="value" x="658" y="296">2/11</text>
+</svg>

package/assets/logo-wordmark.svg

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="320" viewBox="0 0 1200 320" role="img" aria-labelledby="title">
   <title id="title">kassza</title>
-  <style>.word{fill:#14532D}.tag{fill:#4B5563}@media (prefers-color-scheme:dark){.word{fill:#4ADE80}.tag{fill:#D1D5DB}}</style>
+  <style>.tag{fill:#6B7280}</style>
   <defs>
     <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
       <stop offset="0" stop-color="#14532D"/>
@@ -19,7 +19,7 @@
     <rect x="160" y="368" width="120" height="12" rx="6" fill="#14532D" opacity=".28"/>
     <rect x="304" y="368" width="48" height="12" rx="6" fill="#F59E0B"/>
   </g>
-  <text x="340" y="196" font-family="ui-rounded, 'SF Pro Rounded', 'Nunito', 'Inter', system-ui, sans-serif" font-size="168" font-weight="800" letter-spacing="-6" class="word">kassza</text>
+  <text x="340" y="196" font-family="ui-rounded, 'SF Pro Rounded', 'Nunito', 'Inter', system-ui, sans-serif" font-size="168" font-weight="800" letter-spacing="-6" fill="url(#bg)">kassza</text>
   <rect x="348" y="226" width="96" height="14" rx="7" fill="#F59E0B"/>
   <text x="464" y="240" font-family="ui-monospace, 'SF Mono', 'JetBrains Mono', monospace" font-size="30" font-weight="500" class="tag">Számlázz.hu, TypeScriptben</text>
 </svg>

package/package.json

@@ -1,43 +1,23 @@
 {
   "name": "kassza",
-  "version": "0.1.0",
-  "private": false,
-  "description": "Számlázz.hu Számla Agent kliens TypeScripthez: számla, díjbekérő, nyugta, sztornó, befizetés, PDF, adószám. 0 függőség. Nem hivatalos.",
-  "keywords": [
-    "billing",
-    "dijbekero",
-    "e-szamla",
-    "hungary",
-    "invoice",
-    "ipn",
-    "kassza",
-    "nav",
-    "nav-online-szamla",
-    "nyugta",
-    "receipt",
-    "szamla",
-    "szamla agent",
-    "szamla-agent",
-    "szamlazz",
-    "szamlazz.hu",
-    "typescript"
-  ],
-  "license": "MIT",
+  "version": "0.1.2",
   "author": "futozs",
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/futozs/kassza.git"
   },
-  "files": [
-    "dist",
-    "agents",
-    "assets",
-    "llms.txt"
-  ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@biomejs/biome": "^2.5.13",
+    "@types/node": "^26.6.0",
+    "@vitest/coverage-v8": "^5.0.1",
+    "publint": "^0.3.24",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  },
   "exports": {
     ".": {
       "import": {
@@ -121,6 +101,40 @@
     },
     "./package.json": "./package.json"
   },
+  "bugs": {
+    "url": "https://github.com/futozs/kassza/issues"
+  },
+  "description": "Számlázz.hu Számla Agent kliens TypeScripthez: számla, díjbekérő, nyugta, sztornó, befizetés, PDF, adószám. 0 függőség. Nem hivatalos.",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "assets",
+    "llms.txt"
+  ],
+  "homepage": "https://github.com/futozs/kassza#readme",
+  "keywords": [
+    "billing",
+    "dijbekero",
+    "e-szamla",
+    "hungary",
+    "invoice",
+    "ipn",
+    "kassza",
+    "nav",
+    "nav-online-szamla",
+    "nyugta",
+    "receipt",
+    "szamla",
+    "szamla agent",
+    "szamla-agent",
+    "szamlazz",
+    "szamlazz.hu",
+    "typescript"
+  ],
+  "license": "MIT",
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
@@ -130,22 +144,14 @@
     "test:coverage": "vitest run --coverage",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "check:package": "publint && attw --pack . --profile node16",
+    "check:package": "publint --pack npm && attw --pack . --profile node16",
     "ci": "npm run lint && npm run typecheck && npm run test:coverage && npm run build && npm run check:package",
-    "changeset": "changeset",
     "xsd:fetch": "node scripts/fetch-xsd.mjs",
-    "prepublishOnly": "npm run ci"
+    "prepublishOnly": "npm run ci",
+    "release": "node scripts/release.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run"
   },
-  "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.5",
-    "@biomejs/biome": "^2.5.13",
-    "@changesets/cli": "^3.0.3",
-    "@types/node": "^26.6.0",
-    "@vitest/coverage-v8": "^5.0.1",
-    "publint": "^0.3.24",
-    "tsdown": "^0.23.0",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.1"
-  },
-  "homepage": "https://www.npmjs.com/package/kassza"
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts"
 }