kassza 0.13.0 → 0.14.0

package/agents/recipes.md

@@ -136,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
 
@@ -238,7 +240,9 @@ export const POST = stripeWebhook({
 - The handler verifies the signature and answers 400, 200 or 500 itself. A thrown error means 500, and the provider redelivers, which is safe: `issueForPayment` looks the document up first.
 - Catch non-retryable errors (a missing VAT rate, an incomplete billing address) and hand them to a human, otherwise the provider keeps redelivering a request that can never succeed. `parkForHuman` is your own function.
 - The same pattern works with `simplePayWebhook`, `barionWebhook`, `revolutWebhook` and `payPalWebhook`; only the credentials differ (see [api.md](./api.md)).
-- A full refund reverses the document. A partial refund is skipped on purpose: it needs a corrective document decided by a human.
+- 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
@@ -293,7 +297,7 @@ const { missing, mismatched } = reconcileNavReports(local, remote)
 ```
 
 - Számlázz.hu reports the receipts issued there after the NAV connection, so this client stays read-only (no `allowWrite`). Alert a human about `missing` and `mismatched` days.
-- `receiptsBetween` is your own query over stored `Receipt` objects (from `receipts.get`, `issueForPayment` results, or the data link in recipe 15).
+- 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)
@@ -385,3 +389,58 @@ The fake Agent runs the real kassza code (XML, multipart, response parsing, retr
 
 - 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

@@ -21,6 +21,9 @@ Before writing code, read the package docs from `node_modules/kassza/agents/`:
 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
 

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.

package/dist/batch/index.cjs

@@ -0,0 +1,346 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors-EE96_6D_.cjs");
+const require_dates = require("../dates-CPgBodkP.cjs");
+const require_create = require("../create-CvUvLUaT.cjs");
+//#region src/batch/recurring.ts
+const INTERVALS = /* @__PURE__ */ new Set([
+	"week",
+	"month",
+	"quarter",
+	"year"
+]);
+const MONTHS = {
+	month: 1,
+	quarter: 3,
+	year: 12
+};
+function invalid$1(message) {
+	return new require_errors.SzamlazzError(message, { category: "validation" });
+}
+function parts(day) {
+	const [year, month, date] = day.split("-").map(Number);
+	return [
+		year,
+		month,
+		date
+	];
+}
+function format(year, month, day) {
+	return `${String(year).padStart(4, "0")}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+}
+function daysInMonth(year, month) {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function addDays(day, days) {
+	const [year, month, date] = parts(day);
+	return new Date(Date.UTC(year, month - 1, date + days)).toISOString().slice(0, 10);
+}
+function shift(anchor, interval, count) {
+	if (interval === "week") return addDays(anchor, count * 7);
+	const [year, month, day] = parts(anchor);
+	const total = year * 12 + (month - 1) + count * MONTHS[interval];
+	const targetYear = Math.floor(total / 12);
+	const targetMonth = total % 12 + 1;
+	return format(targetYear, targetMonth, Math.min(day, daysInMonth(targetYear, targetMonth)));
+}
+function resolve(options) {
+	if (!INTERVALS.has(options.interval)) throw invalid$1(`Ismeretlen számlázási időszak: ${String(options.interval)}`);
+	let anchor;
+	try {
+		anchor = require_dates.toAgentDate(options.anchor);
+	} catch (error) {
+		throw invalid$1(error instanceof Error ? error.message : String(error));
+	}
+	const due = options.paymentDueInDays;
+	if (due !== void 0 && (!Number.isInteger(due) || due < 0)) throw invalid$1(`A paymentDueInDays nemnegatív egész legyen, kapott: ${due}`);
+	return {
+		anchor,
+		interval: options.interval
+	};
+}
+function billingPeriod(options, index) {
+	if (!Number.isInteger(index) || index < 0) throw invalid$1(`Az időszak sorszáma nemnegatív egész legyen, kapott: ${index}`);
+	const { anchor, interval } = resolve(options);
+	const start = shift(anchor, interval, index);
+	const end = addDays(shift(anchor, interval, index + 1), -1);
+	const due = options.paymentDueInDays;
+	return {
+		index,
+		interval,
+		start,
+		end,
+		...due === void 0 ? {} : { dueDate: addDays(start, due) },
+		key: `${interval}:${start}`
+	};
+}
+function billingPeriodAt(options, date) {
+	const { anchor, interval } = resolve(options);
+	let day;
+	try {
+		day = require_dates.toAgentDate(date);
+	} catch (error) {
+		throw invalid$1(error instanceof Error ? error.message : String(error));
+	}
+	if (day < anchor) throw invalid$1(`A(z) ${day} dátum korábbi, mint az első időszak kezdete (${anchor}).`);
+	const [anchorYear, anchorMonth] = parts(anchor);
+	const [year, month] = parts(day);
+	let index = interval === "week" ? Math.floor((Date.parse(`${day}T00:00:00Z`) - Date.parse(`${anchor}T00:00:00Z`)) / 6048e5) : Math.floor(((year - anchorYear) * 12 + (month - anchorMonth)) / MONTHS[interval]);
+	while (index > 0 && shift(anchor, interval, index) > day) index -= 1;
+	while (shift(anchor, interval, index + 1) <= day) index += 1;
+	return billingPeriod(options, index);
+}
+function billingPeriodsBetween(options, from, to) {
+	const first = billingPeriodAt(options, from);
+	const last = billingPeriodAt(options, to);
+	const periods = [];
+	for (let index = first.index; index <= last.index; index++) periods.push(billingPeriod(options, index));
+	return periods;
+}
+function todayPeriod(options, now = /* @__PURE__ */ new Date()) {
+	return billingPeriodAt(options, require_dates.addBudapestDays(now, 0));
+}
+//#endregion
+//#region src/batch/run.ts
+const MAX_BATCH_CONCURRENCY = 4;
+const DEFAULT_BATCH_RATE_PER_MINUTE = 30;
+const STOPPING_CATEGORIES = /* @__PURE__ */ new Set([
+	"rate_limit",
+	"auth",
+	"account",
+	"configuration",
+	"maintenance",
+	"attempt_limit",
+	"store_unavailable"
+]);
+function invalid(message) {
+	return new require_errors.SzamlazzError(message, { category: "validation" });
+}
+function resolveConcurrency(value) {
+	if (value === void 0) return 1;
+	if (!Number.isInteger(value) || value < 1 || value > 4) throw new require_errors.SzamlazzError(`A concurrency 1 és 4 közötti egész legyen, kapott: ${value}. A Számlázz.hu a párhuzamos kérések kerülését kéri.`, { category: "configuration" });
+	return value;
+}
+function resolveRate(value) {
+	if (value === void 0) return 30;
+	if (!Number.isFinite(value) || value <= 0) throw new require_errors.SzamlazzError(`A ratePerMinute pozitív szám legyen, kapott: ${value}`, { category: "configuration" });
+	return value;
+}
+function assertKeys(items) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of items) {
+		const key = item.key?.trim();
+		if (!key) throw invalid("Minden tételhez adj meg kulcsot (key), ez lesz a rendelésszám.");
+		if (seen.has(key)) throw invalid(`A(z) ${key} kulcs kétszer szerepel a listában.`);
+		seen.add(key);
+	}
+}
+function withOrderNumber(input, key) {
+	const own = input.orderNumber?.trim();
+	if (own && own !== key) throw invalid(`A(z) ${key} tétel rendelésszáma (${own}) eltér a kulcstól. A batch a kulcsot használja rendelésszámként, hogy az újrafuttatás ne állítson ki duplát.`);
+	return {
+		...input,
+		orderNumber: key
+	};
+}
+function wait(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+function invoiceGross(result) {
+	return result.invoice?.grossTotal ?? result.details?.totals.grossAmount;
+}
+async function previewDocument(api, document, key, signal) {
+	if (document.kind === "invoice") return {
+		key,
+		status: "previewed",
+		kind: "invoice",
+		grossTotal: (await api.invoices.preview(withOrderNumber(document.input, key), { signal })).grossTotal
+	};
+	const input = withOrderNumber(document.input, key);
+	if (input.items.length === 0) throw invalid(`A(z) ${key} nyugtán nincs tétel.`);
+	const gross = require_create.calculateReceiptItems(input.items, input.currency ?? "HUF").reduce((sum, item) => sum + item.amounts.grossAmount, 0);
+	return {
+		key,
+		status: "previewed",
+		kind: "receipt",
+		grossTotal: Math.round(gross * 100) / 100
+	};
+}
+async function issueDocument(api, document, key, options) {
+	const onceOptions = {
+		signal: options.signal,
+		recoveryDelayMs: options.recoveryDelayMs
+	};
+	if (document.kind === "invoice") {
+		const input = withOrderNumber(document.input, key);
+		const run = () => api.invoices.createOnce(input, onceOptions);
+		const result = options.journal ? await options.journal.trackInvoice(key, run) : await run();
+		return {
+			key,
+			status: result.created ? "created" : "existing",
+			kind: "invoice",
+			number: result.number,
+			grossTotal: invoiceGross(result)
+		};
+	}
+	const input = withOrderNumber(document.input, key);
+	const run = () => api.receipts.createOnce(input, onceOptions);
+	const result = options.journal ? await options.journal.trackReceipt(key, run) : await run();
+	return {
+		key,
+		status: result.created ? "created" : "existing",
+		kind: "receipt",
+		number: result.receipt.number,
+		grossTotal: result.receipt.totals.grossAmount
+	};
+}
+function stopReason(error) {
+	if (!require_errors.isSzamlazzError(error) || !STOPPING_CATEGORIES.has(error.category)) return void 0;
+	return `A(z) ${error.category} hiba miatt a batch leállt, a hátralévő tételek nem futottak le: ${error.message}`;
+}
+async function runBatch(api, options) {
+	const concurrency = resolveConcurrency(options.concurrency);
+	const intervalMs = 6e4 / resolveRate(options.ratePerMinute);
+	assertKeys(options.items);
+	const dryRun = options.dryRun === true;
+	const results = new Array(options.items.length);
+	const counts = {
+		created: 0,
+		existing: 0,
+		previewed: 0,
+		failed: 0,
+		skipped: 0
+	};
+	let done = 0;
+	let cursor = 0;
+	let nextStart = Date.now();
+	const control = { stopped: void 0 };
+	const currentStop = () => control.stopped;
+	const record = (index, result) => {
+		results[index] = result;
+		counts[result.status] += 1;
+		done += 1;
+		try {
+			options.onProgress?.({
+				total: options.items.length,
+				done,
+				...counts,
+				key: result.key,
+				status: result.status
+			});
+		} catch {
+			return;
+		}
+	};
+	const processItem = async (index, item) => {
+		const key = item.key.trim();
+		try {
+			const document = await item.document();
+			const result = dryRun ? await previewDocument(api, document, key, options.signal) : await issueDocument(api, document, key, options);
+			record(index, result);
+		} catch (error) {
+			if (options.signal?.aborted && error === options.signal.reason) {
+				control.stopped ??= {
+					reason: "A batch futását megszakították.",
+					error
+				};
+				record(index, {
+					key,
+					status: "skipped",
+					reason: "Megszakítva."
+				});
+				return;
+			}
+			const reason = stopReason(error);
+			if (reason) control.stopped ??= {
+				reason,
+				error
+			};
+			record(index, {
+				key,
+				status: "failed",
+				error
+			});
+		}
+	};
+	const worker = async () => {
+		for (;;) {
+			if (control.stopped || options.signal?.aborted) return;
+			const index = cursor;
+			cursor += 1;
+			const item = options.items[index];
+			if (!item) return;
+			const delay = nextStart - Date.now();
+			nextStart = Math.max(nextStart, Date.now()) + intervalMs;
+			try {
+				await wait(delay, options.signal);
+			} catch (error) {
+				control.stopped ??= {
+					reason: "A batch futását megszakították.",
+					error
+				};
+				record(index, {
+					key: item.key.trim(),
+					status: "skipped",
+					reason: "Megszakítva."
+				});
+				return;
+			}
+			const stop = currentStop();
+			if (stop) {
+				record(index, {
+					key: item.key.trim(),
+					status: "skipped",
+					reason: stop.reason
+				});
+				return;
+			}
+			await processItem(index, item);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(concurrency, options.items.length) }, worker));
+	if (options.signal?.aborted) control.stopped ??= { reason: "A batch futását megszakították." };
+	options.items.forEach((item, index) => {
+		if (results[index]) return;
+		record(index, {
+			key: item.key.trim(),
+			status: "skipped",
+			reason: control.stopped?.reason ?? "Nem futott le."
+		});
+	});
+	const by = (status) => results.filter((result) => result.status === status);
+	const grossTotal = results.filter((result) => result.status !== "failed" && result.status !== "skipped").reduce((sum, result) => sum + (result.grossTotal ?? 0), 0);
+	return {
+		dryRun,
+		items: results,
+		created: by("created"),
+		existing: by("existing"),
+		previewed: by("previewed"),
+		failed: by("failed"),
+		skipped: by("skipped"),
+		stopped: control.stopped,
+		grossTotal: Math.round(grossTotal * 100) / 100
+	};
+}
+//#endregion
+exports.DEFAULT_BATCH_RATE_PER_MINUTE = DEFAULT_BATCH_RATE_PER_MINUTE;
+exports.MAX_BATCH_CONCURRENCY = MAX_BATCH_CONCURRENCY;
+exports.billingPeriod = billingPeriod;
+exports.billingPeriodAt = billingPeriodAt;
+exports.billingPeriodsBetween = billingPeriodsBetween;
+exports.runBatch = runBatch;
+exports.todayPeriod = todayPeriod;

package/dist/batch/index.d.cts

@@ -0,0 +1,91 @@
+import { t as DateInput } from "../dates-9zvESP0i.cjs";
+import { M as CreateInvoiceInput } from "../context-CFNKzStE.cjs";
+import { t as CreateReceiptInput } from "../types-lnKkQdot.cjs";
+import { a as ReceiptsApi, t as InvoicesApi } from "../client-SVZu25MB.cjs";
+import { n as Journal } from "../journal-DvI81Kt7.cjs";
+//#region src/batch/recurring.d.ts
+type BillingInterval = "week" | "month" | "quarter" | "year";
+interface BillingPeriodOptions {
+  readonly interval: BillingInterval;
+  readonly anchor: DateInput;
+  readonly paymentDueInDays?: number | undefined;
+}
+interface BillingPeriod {
+  readonly index: number;
+  readonly interval: BillingInterval;
+  readonly start: string;
+  readonly end: string;
+  readonly dueDate?: string | undefined;
+  readonly key: string;
+}
+export declare function billingPeriod(options: BillingPeriodOptions, index: number): BillingPeriod;
+export declare function billingPeriodAt(options: BillingPeriodOptions, date: DateInput): BillingPeriod;
+export declare function billingPeriodsBetween(options: BillingPeriodOptions, from: DateInput, to: DateInput): BillingPeriod[];
+export declare function todayPeriod(options: BillingPeriodOptions, now?: Date): BillingPeriod;
+//#endregion
+//#region src/batch/run.d.ts
+export declare const MAX_BATCH_CONCURRENCY = 4;
+export declare const DEFAULT_BATCH_RATE_PER_MINUTE = 30;
+type BatchDocument = {
+  readonly kind: "invoice";
+  readonly input: CreateInvoiceInput;
+} | {
+  readonly kind: "receipt";
+  readonly input: CreateReceiptInput;
+};
+interface BatchItem {
+  readonly key: string;
+  readonly document: () => BatchDocument | Promise<BatchDocument>;
+}
+interface BatchProgress {
+  readonly total: number;
+  readonly done: number;
+  readonly created: number;
+  readonly existing: number;
+  readonly previewed: number;
+  readonly failed: number;
+  readonly skipped: number;
+  readonly key: string;
+  readonly status: BatchItemStatus;
+}
+type BatchItemStatus = "created" | "existing" | "previewed" | "failed" | "skipped";
+interface BatchItemResult {
+  readonly key: string;
+  readonly status: BatchItemStatus;
+  readonly kind?: "invoice" | "receipt" | undefined;
+  readonly number?: string | undefined;
+  readonly grossTotal?: number | undefined;
+  readonly error?: unknown;
+  readonly reason?: string | undefined;
+}
+interface BatchResult {
+  readonly dryRun: boolean;
+  readonly items: readonly BatchItemResult[];
+  readonly created: readonly BatchItemResult[];
+  readonly existing: readonly BatchItemResult[];
+  readonly previewed: readonly BatchItemResult[];
+  readonly failed: readonly BatchItemResult[];
+  readonly skipped: readonly BatchItemResult[];
+  readonly stopped?: {
+    readonly reason: string;
+    readonly error?: unknown;
+  } | undefined;
+  readonly grossTotal: number;
+}
+interface BatchApi {
+  readonly invoices: Pick<InvoicesApi, "createOnce" | "preview">;
+  readonly receipts: Pick<ReceiptsApi, "createOnce">;
+}
+interface RunBatchOptions {
+  readonly items: readonly BatchItem[];
+  readonly concurrency?: number | undefined;
+  readonly ratePerMinute?: number | undefined;
+  readonly dryRun?: boolean | undefined;
+  readonly journal?: Journal | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly onProgress?: ((progress: BatchProgress) => void) | undefined;
+  readonly recoveryDelayMs?: number | undefined;
+}
+export declare function runBatch(api: BatchApi, options: RunBatchOptions): Promise<BatchResult>;
+//#endregion
+export type { BatchApi, BatchDocument, BatchItem, BatchItemResult, BatchItemStatus, BatchProgress, BatchResult, BillingInterval, BillingPeriod, BillingPeriodOptions, RunBatchOptions };

package/dist/batch/index.d.ts

@@ -0,0 +1,91 @@
+import { t as DateInput } from "../dates-9zvESP0i.js";
+import { M as CreateInvoiceInput } from "../context-kb33TgzE.js";
+import { t as CreateReceiptInput } from "../types-D1zDOH_F.js";
+import { a as ReceiptsApi, t as InvoicesApi } from "../client-DeWWQ-RZ.js";
+import { n as Journal } from "../journal-Y9qrIB8G.js";
+//#region src/batch/recurring.d.ts
+type BillingInterval = "week" | "month" | "quarter" | "year";
+interface BillingPeriodOptions {
+  readonly interval: BillingInterval;
+  readonly anchor: DateInput;
+  readonly paymentDueInDays?: number | undefined;
+}
+interface BillingPeriod {
+  readonly index: number;
+  readonly interval: BillingInterval;
+  readonly start: string;
+  readonly end: string;
+  readonly dueDate?: string | undefined;
+  readonly key: string;
+}
+export declare function billingPeriod(options: BillingPeriodOptions, index: number): BillingPeriod;
+export declare function billingPeriodAt(options: BillingPeriodOptions, date: DateInput): BillingPeriod;
+export declare function billingPeriodsBetween(options: BillingPeriodOptions, from: DateInput, to: DateInput): BillingPeriod[];
+export declare function todayPeriod(options: BillingPeriodOptions, now?: Date): BillingPeriod;
+//#endregion
+//#region src/batch/run.d.ts
+export declare const MAX_BATCH_CONCURRENCY = 4;
+export declare const DEFAULT_BATCH_RATE_PER_MINUTE = 30;
+type BatchDocument = {
+  readonly kind: "invoice";
+  readonly input: CreateInvoiceInput;
+} | {
+  readonly kind: "receipt";
+  readonly input: CreateReceiptInput;
+};
+interface BatchItem {
+  readonly key: string;
+  readonly document: () => BatchDocument | Promise<BatchDocument>;
+}
+interface BatchProgress {
+  readonly total: number;
+  readonly done: number;
+  readonly created: number;
+  readonly existing: number;
+  readonly previewed: number;
+  readonly failed: number;
+  readonly skipped: number;
+  readonly key: string;
+  readonly status: BatchItemStatus;
+}
+type BatchItemStatus = "created" | "existing" | "previewed" | "failed" | "skipped";
+interface BatchItemResult {
+  readonly key: string;
+  readonly status: BatchItemStatus;
+  readonly kind?: "invoice" | "receipt" | undefined;
+  readonly number?: string | undefined;
+  readonly grossTotal?: number | undefined;
+  readonly error?: unknown;
+  readonly reason?: string | undefined;
+}
+interface BatchResult {
+  readonly dryRun: boolean;
+  readonly items: readonly BatchItemResult[];
+  readonly created: readonly BatchItemResult[];
+  readonly existing: readonly BatchItemResult[];
+  readonly previewed: readonly BatchItemResult[];
+  readonly failed: readonly BatchItemResult[];
+  readonly skipped: readonly BatchItemResult[];
+  readonly stopped?: {
+    readonly reason: string;
+    readonly error?: unknown;
+  } | undefined;
+  readonly grossTotal: number;
+}
+interface BatchApi {
+  readonly invoices: Pick<InvoicesApi, "createOnce" | "preview">;
+  readonly receipts: Pick<ReceiptsApi, "createOnce">;
+}
+interface RunBatchOptions {
+  readonly items: readonly BatchItem[];
+  readonly concurrency?: number | undefined;
+  readonly ratePerMinute?: number | undefined;
+  readonly dryRun?: boolean | undefined;
+  readonly journal?: Journal | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly onProgress?: ((progress: BatchProgress) => void) | undefined;
+  readonly recoveryDelayMs?: number | undefined;
+}
+export declare function runBatch(api: BatchApi, options: RunBatchOptions): Promise<BatchResult>;
+//#endregion
+export type { BatchApi, BatchDocument, BatchItem, BatchItemResult, BatchItemStatus, BatchProgress, BatchResult, BillingInterval, BillingPeriod, BillingPeriodOptions, RunBatchOptions };