kassza 0.1.0

package/agents/recipes.md

@@ -0,0 +1,217 @@
+# kassza: recipes
+
+Copy-paste starting points. Each recipe follows the rules in [pitfalls.md](./pitfalls.md).
+
+## 1. One shared client (server only)
+
+```ts
+import { createKassza } from 'kassza'
+
+export const kassza = createKassza({
+  defaults: {
+    invoice: { prefix: 'WEB', paymentDueInDays: 8, seller: { emailReplyTo: 'billing@example.hu' } },
+    receipt: { prefix: 'NYGT', paymentMethod: 'bankkártya' },
+  },
+})
+```
+
+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)
+
+```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
+  }
+}
+```
+
+The first `find` makes the webhook idempotent when the payment provider redelivers the event.
+
+## 3. Event registration: proforma → payment → invoice
+
+```ts
+const proforma = await kassza.invoices.create({
+  type: 'proforma',
+  orderNumber: `REG-${entry.id}`,
+  buyer,
+  items: [{ name: 'Nevezési díj', grossUnitPrice: 26_000, vat: 27 }],
+})
+
+const invoice = await kassza.invoices.create({
+  orderNumber: `REG-${entry.id}`,
+  proformaNumber: proforma.number,
+  paid: true,
+  buyer,
+  items: [{ name: 'Nevezési díj', grossUnitPrice: 26_000, vat: 27 }],
+})
+
+await kassza.invoices.deleteProforma({ orderNumber: `REG-${entry.id}` })
+```
+
+- `buyer` is the same buyer object on both documents.
+- Call `deleteProforma` only if the proforma was never paid and must be cancelled.
+
+## 4. Payment notification (IPN) webhook, Next.js App Router
+
+```ts
+import { ipnOkResponse, readIpnNotification } from 'kassza/ipn'
+
+export async function POST(request: Request) {
+  const ipn = await readIpnNotification(request)
+  if (ipn.isFullyPaid) await markOrderPaid({ invoiceNumber: ipn.invoiceNumber, orderNumber: ipn.orderNumber })
+  return ipnOkResponse()
+}
+```
+
+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
+
+```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 })),
+})
+
+if (sale.email) await kassza.receipts.send({ receiptNumber: receipt.number, emails: sale.email })
+```
+
+## 6. Save the PDF to S3 or Cloudflare R2 (no AWS SDK needed)
+
+```ts
+import { invoicePdfKey, s3FetchStorage, storePdf } from 'kassza/storage'
+
+const storage = s3FetchStorage({
+  bucket: 'invoices',
+  region: 'auto',
+  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+})
+
+const invoice = await kassza.invoices.create(input)
+if (invoice.pdf) {
+  const stored = await storePdf(storage, invoicePdfKey({ number: invoice.number }), invoice.pdf)
+  await db.invoice.update({ where: { orderNumber }, data: { pdfKey: stored.key } })
+}
+```
+
+Other adapters with the same interface:
+
+- `s3Storage` (AWS SDK v3 client)
+- `r2BindingStorage` (Workers binding)
+- `vercelBlobStorage`
+- `uploadthingStorage`
+- `supabaseStorage`
+- `fsStorage` from `kassza/storage/fs`
+- `memoryStorage`
+
+## 7. Serverless and edge: share the session
+
+```ts
+import { Redis } from '@upstash/redis'
+import { createKassza } from 'kassza'
+import { upstashRedisCookieStore } from 'kassza/cookie-stores'
+
+const kassza = createKassza({ cookieStore: upstashRedisCookieStore(Redis.fromEnv()) })
+```
+
+- 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.
+
+## 8. Unit tests without calling Számlázz.hu
+
+```ts
+import { createMockKassza } from 'kassza/testing'
+import { expect, test } from 'vitest'
+
+test('invoices a paid order once', async () => {
+  const kassza = createMockKassza()
+
+  await invoiceOrder(order, kassza)
+  await invoiceOrder(order, kassza)
+
+  expect(kassza.calls.filter((call) => call.method === 'invoices.create')).toHaveLength(1)
+})
+
+test('does not swallow a network failure when nothing was created', async () => {
+  const kassza = createMockKassza()
+  kassza.failNext('invoices.create')
+
+  await expect(invoiceOrder(order, kassza)).rejects.toMatchObject({ category: 'network' })
+})
+```
+
+Inject the client into your function, for example `invoiceOrder(order, kassza = defaultKassza)`, so tests can pass the mock. Mock method names match the API paths: `'invoices.create'`, `'invoices.get'` (also used by `find`), `'receipts.send'`, and so on.
+
+## 9. Fill the buyer from a tax number
+
+```ts
+import { parseHungarianTaxNumber } from 'kassza/validators'
+
+if (!parseHungarianTaxNumber(input)) throw new Error('Érvénytelen adószám')
+
+const company = await kassza.taxpayer.query(input)
+if (company.valid && company.address) {
+  buyer = {
+    name: company.name ?? '',
+    zip: company.address.postalCode,
+    city: company.address.city,
+    address: company.address.formatted.split(', ').slice(1).join(', '),
+    taxNumber: company.taxNumber?.formatted,
+  }
+}
+```
+
+## 10. Foreign currency and EU buyer
+
+```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' }],
+})
+```
+
+The exchange rate comes from MNB automatically when `exchangeRate` is omitted. Choose the VAT code together with an accountant.

package/agents/skills/kassza/SKILL.md

@@ -0,0 +1,29 @@
+---
+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.
+---
+
+# kassza: Számlázz.hu integration
+
+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.
+
+## 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.
+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.
+5. Branch on `SzamlazzError.category` and `code`, not on message text.
+6. Tests must use `createMockKassza()` from `kassza/testing`, never a real Agent key.
+
+## Checklist before finishing
+
+- [ ] The webhook or job that issues documents is idempotent: it runs `find` first, or catches `duplicate`.
+- [ ] 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()`.

package/assets/logo-wordmark.svg

@@ -0,0 +1,25 @@
+<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>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#14532D"/>
+      <stop offset="1" stop-color="#052E16"/>
+    </linearGradient>
+    <linearGradient id="paper" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#FFFDF5"/>
+      <stop offset="1" stop-color="#F3EBD3"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(24 24) scale(0.53125)">
+    <rect width="512" height="512" rx="112" fill="url(#bg)"/>
+    <path d="M146 84H366A20 20 0 0 1 386 104V428l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18V104A20 20 0 0 1 146 84Z" fill="#000" opacity=".22" transform="translate(0 10)"/>
+    <path d="M146 84H366A20 20 0 0 1 386 104V428l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18V104A20 20 0 0 1 146 84Z" fill="url(#paper)"/>
+    <path d="M170 136h40v88l76-88h50l-80 90 86 116h-50l-62-86-20 22v64h-40z" fill="#14532D"/>
+    <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>
+  <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/assets/logo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512" role="img" aria-labelledby="title">
+  <title id="title">kassza</title>
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#14532D"/>
+      <stop offset="1" stop-color="#052E16"/>
+    </linearGradient>
+    <linearGradient id="paper" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#FFFDF5"/>
+      <stop offset="1" stop-color="#F3EBD3"/>
+    </linearGradient>
+  </defs>
+  <rect width="512" height="512" rx="112" fill="url(#bg)"/>
+  <path d="M146 84H366A20 20 0 0 1 386 104V428l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18V104A20 20 0 0 1 146 84Z" fill="#000" opacity=".22" transform="translate(0 10)"/>
+  <path d="M146 84H366A20 20 0 0 1 386 104V428l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18 l-13 -18 l-13 18V104A20 20 0 0 1 146 84Z" fill="url(#paper)"/>
+  <path d="M170 136h40v88l76-88h50l-80 90 86 116h-50l-62-86-20 22v64h-40z" fill="#14532D"/>
+  <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"/>
+</svg>

package/dist/binary-B89HM03_.cjs

@@ -0,0 +1,63 @@
+//#region src/core/binary.ts
+const PDF_MAGIC = [
+	37,
+	80,
+	68,
+	70
+];
+function isPdf(bytes) {
+	if (bytes.length < PDF_MAGIC.length) return false;
+	return PDF_MAGIC.every((byte, index) => bytes[index] === byte);
+}
+const utf8Decoder = new TextDecoder("utf-8");
+const utf8Encoder = new TextEncoder();
+function decodeUtf8(bytes) {
+	return utf8Decoder.decode(bytes);
+}
+function encodeUtf8(value) {
+	return utf8Encoder.encode(value);
+}
+function base64ToBytes(base64) {
+	const clean = base64.replace(/[^A-Za-z0-9+/=_-]/g, "").replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(clean);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+const BASE64_CHUNK_SIZE = 32768;
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK_SIZE) binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK_SIZE));
+	return btoa(binary);
+}
+//#endregion
+Object.defineProperty(exports, "base64ToBytes", {
+	enumerable: true,
+	get: function() {
+		return base64ToBytes;
+	}
+});
+Object.defineProperty(exports, "bytesToBase64", {
+	enumerable: true,
+	get: function() {
+		return bytesToBase64;
+	}
+});
+Object.defineProperty(exports, "decodeUtf8", {
+	enumerable: true,
+	get: function() {
+		return decodeUtf8;
+	}
+});
+Object.defineProperty(exports, "encodeUtf8", {
+	enumerable: true,
+	get: function() {
+		return encodeUtf8;
+	}
+});
+Object.defineProperty(exports, "isPdf", {
+	enumerable: true,
+	get: function() {
+		return isPdf;
+	}
+});

package/dist/binary-D0M9U2MD.js

@@ -0,0 +1,34 @@
+//#region src/core/binary.ts
+const PDF_MAGIC = [
+	37,
+	80,
+	68,
+	70
+];
+function isPdf(bytes) {
+	if (bytes.length < PDF_MAGIC.length) return false;
+	return PDF_MAGIC.every((byte, index) => bytes[index] === byte);
+}
+const utf8Decoder = new TextDecoder("utf-8");
+const utf8Encoder = new TextEncoder();
+function decodeUtf8(bytes) {
+	return utf8Decoder.decode(bytes);
+}
+function encodeUtf8(value) {
+	return utf8Encoder.encode(value);
+}
+function base64ToBytes(base64) {
+	const clean = base64.replace(/[^A-Za-z0-9+/=_-]/g, "").replace(/-/g, "+").replace(/_/g, "/");
+	const binary = atob(clean);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+const BASE64_CHUNK_SIZE = 32768;
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK_SIZE) binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK_SIZE));
+	return btoa(binary);
+}
+//#endregion
+export { isPdf as a, encodeUtf8 as i, bytesToBase64 as n, decodeUtf8 as r, base64ToBytes as t };