kassza 0.13.0 → 0.15.0

package/dist/{client-C-PdfL_P.cjs → client-CLFvJCVW.cjs}

@@ -1,14 +1,16 @@
-const require_create_once = require("./create-once-DgMtKKcG.cjs");
-const require_errors = require("./errors-DxeuTslP.cjs");
+const require_create_once = require("./create-once-9yxR_Er_.cjs");
+const require_errors = require("./errors-EE96_6D_.cjs");
 const require_binary = require("./binary-B89HM03_.cjs");
-const require_serialize = require("./serialize-BXOww1Uq.cjs");
-const require_parse = require("./parse-BJj-aqKy.cjs");
-const require_session = require("./session-CKOuE6Jc.cjs");
-const require_dates = require("./dates-CPgBodkP.cjs");
+const require_serialize = require("./serialize-CquIsxA-.cjs");
+const require_parse = require("./parse-DOA2XQ3e.cjs");
+const require_session = require("./session-DeM5vjvC.cjs");
+const require_warnings = require("./warnings-DeIw5RFj.cjs");
+const require_issue = require("./issue-Bin4tKD_.cjs");
 const require_vat = require("./vat-g35srbNG.cjs");
-const require_money = require("./money-BxytJW6f.cjs");
-const require_issue = require("./issue-AGRohSm7.cjs");
-const require_get = require("./get-Csm2n0rZ.cjs");
+const require_money = require("./money-K9j0wPit.cjs");
+const require_reference = require("./reference-BIdYMK0t.cjs");
+const require_get = require("./get-BdMTseh4.cjs");
+const require_create = require("./create-CvUvLUaT.cjs");
 //#region src/core/attempt-ledger.ts
 const ATTEMPT_LEDGER_TTL_SECONDS = 86400;
 const ATTEMPT_LEDGER_KEY_PREFIX = "szamlazz:attempts:";
@@ -38,17 +40,63 @@ function parseCount(value) {
 	const parsed = Number.parseInt(value, 10);
 	return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
 }
+function createLocalCounter() {
+	const counts = /* @__PURE__ */ new Map();
+	const get = (key) => {
+		const entry = counts.get(key);
+		if (!entry) return 0;
+		if (entry.expiresAt <= Date.now()) {
+			counts.delete(key);
+			return 0;
+		}
+		return entry.count;
+	};
+	return {
+		get,
+		bump(key) {
+			const count = get(key) + 1;
+			counts.delete(key);
+			counts.set(key, {
+				count,
+				expiresAt: Date.now() + ATTEMPT_LEDGER_TTL_SECONDS * 1e3
+			});
+			if (counts.size > 1e3) {
+				const oldest = counts.keys().next().value;
+				if (oldest !== void 0) counts.delete(oldest);
+			}
+		},
+		clear(key) {
+			counts.delete(key);
+		}
+	};
+}
 function createAttemptLedger(store) {
+	const local = createLocalCounter();
+	const unpersisted = createLocalCounter();
 	return {
 		async failures(key) {
-			return parseCount(await store.get(key));
+			return parseCount(await store.get(key)) + unpersisted.get(key);
 		},
-		async recordFailure(key, previous) {
-			const next = previous + 1;
-			await store.set(key, String(next), ATTEMPT_LEDGER_TTL_SECONDS);
-			return next;
+		fallbackFailures(key) {
+			return local.get(key);
+		},
+		async recordFailure(key) {
+			local.bump(key);
+			try {
+				if (store.increment) {
+					await store.increment(key, ATTEMPT_LEDGER_TTL_SECONDS);
+					return;
+				}
+				const current = parseCount(await store.get(key));
+				await store.set(key, String(current + 1), ATTEMPT_LEDGER_TTL_SECONDS);
+			} catch (error) {
+				unpersisted.bump(key);
+				throw error;
+			}
 		},
 		async reset(key) {
+			local.clear(key);
+			unpersisted.clear(key);
 			await store.delete(key);
 		}
 	};
@@ -63,6 +111,7 @@ function attemptLimitError(action, key, failures) {
 }
 const DEFAULT_SAFE_ATTEMPTS = 3;
 const DEFAULT_RETRY_DELAY_MS = 1e3;
+const RETRY_JITTER = .2;
 function readEnv(name) {
 	const value = (globalThis.process?.env)?.[name]?.trim();
 	return value ? value : void 0;
@@ -112,22 +161,49 @@ function sleep(ms, signal) {
 		signal?.addEventListener("abort", onAbort, { once: true });
 	});
 }
-async function ignoreStoreFailure(operation) {
-	try {
-		return await operation();
-	} catch {
-		return;
-	}
+function hookWarning(name, action, error) {
+	return {
+		kind: "hook",
+		message: `A(z) ${name} hook hibát dobott, a kassza figyelmen kívül hagyta.`,
+		error,
+		action,
+		operation: name
+	};
 }
-function callHook(hook, event) {
+function callHook(hooks, name, event) {
+	const hook = hooks[name];
 	if (!hook) return;
 	try {
 		const result = hook(event);
-		if (result instanceof Promise) result.catch(() => void 0);
-	} catch {
-		return;
+		if (result instanceof Promise) result.catch((error) => require_warnings.emitWarning(hooks.onWarning, hookWarning(name, event.action, error)));
+	} catch (error) {
+		require_warnings.emitWarning(hooks.onWarning, hookWarning(name, event.action, error));
 	}
 }
+function parseRetryAfter(value, now) {
+	if (value === null) return void 0;
+	const trimmed = value.trim();
+	if (/^\d+$/.test(trimmed)) return Number(trimmed) * 1e3;
+	const date = Date.parse(trimmed);
+	if (Number.isNaN(date)) return void 0;
+	return Math.max(0, date - now);
+}
+function retryDelay(baseMs, attempt, random = Math.random()) {
+	const backoff = baseMs * 2 ** (attempt - 1);
+	return Math.round(backoff * (.8 + 2 * RETRY_JITTER * random));
+}
+function resolveLedgerMode(value) {
+	if (value === void 0 || value === "fail-open" || value === "fail-closed") return value ?? "fail-open";
+	throw configurationError(`Az attemptLedgerMode értéke 'fail-open' vagy 'fail-closed' lehet, kapott: ${String(value)}`);
+}
+function storeUnavailableError(action, error) {
+	return new require_errors.SzamlazzError("A próbálkozás-napló tárolója nem érhető el, ezért a kassza nem küldte el a kérést.", {
+		category: "store_unavailable",
+		action,
+		cause: error,
+		hint: "Az attemptLedgerMode: 'fail-closed' beállítás miatt a kassza nem küld kérést, amíg a napló (például a Redis) nem elérhető. Állítsd helyre a tárolót, vagy válts 'fail-open' módra."
+	});
+}
 function clampAttempts(value) {
 	if (value === void 0) return DEFAULT_SAFE_ATTEMPTS;
 	if (!Number.isInteger(value) || value < 1) throw configurationError(`A maxAttempts értéke legalább 1 egész szám legyen, kapott: ${value}`);
@@ -167,11 +243,27 @@ function createAgentContext(options = {}) {
 		return sessionKeyPromise;
 	};
 	const hooks = options.hooks ?? {};
+	const warn = (warning) => require_warnings.emitWarning(hooks.onWarning, warning);
 	const ledger = options.attemptLedger ? createAttemptLedger(options.attemptLedger) : void 0;
+	const ledgerMode = resolveLedgerMode(options.attemptLedgerMode);
+	async function ignoreStoreFailure(operation, action, run) {
+		try {
+			return await run();
+		} catch (error) {
+			warn({
+				kind: "session",
+				message: `A session cookie tároló "${operation}" művelete sikertelen, a kérés session nélkül folytatódik.`,
+				error,
+				action,
+				operation
+			});
+			return;
+		}
+	}
 	const cooldownMs = resolveCooldown(options.maintenanceCooldownMs);
 	let blockedUntil = 0;
 	async function send(request) {
-		const cookie = cookieStore ? await ignoreStoreFailure(async () => cookieStore.get(await resolveSessionKey())) : void 0;
+		const cookie = cookieStore ? await ignoreStoreFailure("get", request.action, async () => cookieStore.get(await resolveSessionKey())) : void 0;
 		request.signal?.throwIfAborted();
 		const headers = new Headers({ Accept: "application/xml, application/pdf, text/plain, */*" });
 		if (cookie) headers.set("Cookie", cookie);
@@ -202,12 +294,15 @@ function createAgentContext(options = {}) {
 		}
 		if (cookieStore) {
 			const merged = require_session.mergeSetCookies(cookie, response.headers);
-			if (merged) await ignoreStoreFailure(async () => cookieStore.set(await resolveSessionKey(), merged, require_session.SESSION_TTL_SECONDS));
+			if (merged) await ignoreStoreFailure("set", request.action, async () => cookieStore.set(await resolveSessionKey(), merged, require_session.SESSION_TTL_SECONDS));
 		}
-		return require_parse.createAgentResponse(request.action, response.status, response.headers, body);
+		return {
+			response: require_parse.createAgentResponse(request.action, response.status, response.headers, body),
+			sessionReused: Boolean(cookie)
+		};
 	}
 	async function resetSession() {
-		if (cookieStore) await ignoreStoreFailure(async () => cookieStore.delete(await resolveSessionKey()));
+		if (cookieStore) await ignoreStoreFailure("delete", void 0, async () => cookieStore.delete(await resolveSessionKey()));
 	}
 	async function resetAttempts(key) {
 		if (ledger) await ledger.reset(key);
@@ -223,6 +318,41 @@ function createAgentContext(options = {}) {
 			}))
 		});
 	}
+	function ledgerWarning(operation, action, error) {
+		warn({
+			kind: "ledger",
+			message: `A próbálkozás-napló tárolójának "${operation}" művelete sikertelen. A kassza a folyamaton belüli számlálót használja, a folyamatok közötti védelem most nem él.`,
+			error,
+			action,
+			operation
+		});
+	}
+	async function readFailures(action, key) {
+		if (!ledger || key === void 0) return 0;
+		try {
+			return await ledger.failures(key);
+		} catch (error) {
+			if (ledgerMode === "fail-closed") throw storeUnavailableError(action, error);
+			ledgerWarning("get", action, error);
+			return ledger.fallbackFailures(key);
+		}
+	}
+	async function recordFailure(action, key) {
+		if (!ledger || key === void 0) return;
+		try {
+			await ledger.recordFailure(key);
+		} catch (error) {
+			ledgerWarning("increment", action, error);
+		}
+	}
+	async function clearFailures(action, key) {
+		if (!ledger || key === void 0) return;
+		try {
+			await ledger.reset(key);
+		} catch (error) {
+			ledgerWarning("delete", action, error);
+		}
+	}
 	function assertNoCooldown(action) {
 		const remainingMs = blockedUntil - Date.now();
 		if (remainingMs > 0) throw maintenanceCooldownError(action, remainingMs);
@@ -230,45 +360,72 @@ function createAgentContext(options = {}) {
 	async function execute(request, parse) {
 		const maxAttempts = request.safeToRetry ? safeAttempts : 1;
 		const ledgerKey = await ledgerKeyFor(request);
+		const requestId = crypto.randomUUID();
 		for (let attempt = 1;; attempt++) {
 			assertNoCooldown(request.action);
-			const failures = ledger && ledgerKey !== void 0 ? await ignoreStoreFailure(() => ledger.failures(ledgerKey)) ?? 0 : 0;
+			const failures = await readFailures(request.action, ledgerKey);
 			if (ledgerKey !== void 0 && failures >= 5) throw attemptLimitError(request.action, ledgerKey, failures);
 			const startedAt = Date.now();
-			callHook(hooks.onRequest, {
+			let retryAfterMs;
+			const base = {
 				action: request.action,
-				attempt
-			});
+				attempt,
+				requestId
+			};
+			callHook(hooks, "onRequest", base);
 			try {
-				const response = await send(request);
-				callHook(hooks.onResponse, {
-					action: request.action,
-					attempt,
+				const { response, sessionReused } = await send(request);
+				retryAfterMs = parseRetryAfter(response.headers.get("retry-after"), Date.now());
+				callHook(hooks, "onResponse", {
+					...base,
 					status: response.status,
-					durationMs: Date.now() - startedAt
+					durationMs: Date.now() - startedAt,
+					responseBytes: response.body.byteLength,
+					sessionReused
 				});
 				const result = await parse(response);
-				if (ledger && ledgerKey !== void 0 && failures > 0) await ignoreStoreFailure(() => ledger.reset(ledgerKey));
+				if (failures > 0) await clearFailures(request.action, ledgerKey);
+				callHook(hooks, "onComplete", {
+					...base,
+					outcome: "success",
+					durationMs: Date.now() - startedAt,
+					willRetry: false
+				});
 				return result;
 			} catch (error) {
-				if (!(error instanceof require_errors.SzamlazzError)) throw error;
-				if (ledger && ledgerKey !== void 0 && countsAsFailedAttempt(error)) await ignoreStoreFailure(() => ledger.recordFailure(ledgerKey, failures));
+				if (!(error instanceof require_errors.SzamlazzError)) {
+					callHook(hooks, "onComplete", {
+						...base,
+						outcome: "error",
+						durationMs: Date.now() - startedAt,
+						willRetry: false
+					});
+					throw error;
+				}
+				if (countsAsFailedAttempt(error)) await recordFailure(request.action, ledgerKey);
 				if (error.category === "maintenance" && cooldownMs > 0) blockedUntil = Date.now() + cooldownMs;
-				const willRetry = error.retryable && attempt < maxAttempts && !(error.category === "maintenance" && cooldownMs > 0);
-				callHook(hooks.onError, {
-					action: request.action,
-					attempt,
+				const willRetry = error.retryable && attempt < maxAttempts && !(error.category === "maintenance" && cooldownMs > 0) && (retryAfterMs === void 0 || retryAfterMs <= 6e4);
+				callHook(hooks, "onError", {
+					...base,
+					error,
+					willRetry
+				});
+				callHook(hooks, "onComplete", {
+					...base,
+					outcome: "error",
+					durationMs: Date.now() - startedAt,
 					error,
 					willRetry
 				});
 				if (error.category === "auth") await resetSession();
 				if (!willRetry) throw error;
-				await sleep(retryDelayMs * 2 ** (attempt - 1), request.signal);
+				await sleep(Math.max(retryDelay(retryDelayMs, attempt), retryAfterMs ?? 0), request.signal);
 			}
 		}
 	}
 	return {
 		credentials,
+		warn,
 		execute,
 		resetSession,
 		resetAttempts
@@ -555,100 +712,25 @@ async function previewInvoice(ctx, defaults, input, options = {}) {
 	const items = itemsOf(invoice);
 	return ctx.execute(buildRequest(ctx, invoice, true, options), (response) => parseInvoicePreviewResponse(response, items));
 }
-function normalizeRegisterInput(input) {
-	const payments = "payments" in input ? input.payments : [{
-		amount: input.amount,
-		method: input.method ?? "átutalás",
-		date: input.date,
-		description: input.description
-	}];
-	if (!Array.isArray(payments) || payments.length === 0) throw require_get.validationError("Adj meg legalább egy befizetést (payments). A korábbi befizetések törléséhez a clearPayments függvényt használd.");
-	if (payments.length > 5) throw require_get.validationError(`Egy kérésben legfeljebb 5 befizetés rögzíthető, kapott: ${payments.length}.`);
-	return {
-		invoiceNumber: input.invoiceNumber,
-		taxNumber: input.taxNumber,
-		additive: input.additive ?? true,
-		payments
-	};
-}
-function normalizeClearInput(input) {
-	const target = typeof input === "string" ? { invoiceNumber: input } : input;
-	return {
-		invoiceNumber: target.invoiceNumber,
-		taxNumber: target.taxNumber,
-		additive: false,
-		payments: []
-	};
-}
-function paymentNode(payment, index) {
-	const position = index + 1;
-	if (typeof payment.amount !== "number" || !Number.isFinite(payment.amount)) throw require_get.validationError(`A(z) ${position}. befizetés összege (amount) nem véges szám.`);
-	return require_serialize.el("kifizetes", [
-		require_serialize.el("datum", payment.date === void 0 ? require_dates.todayInBudapest() : require_get.agentDate(payment.date, "date")),
-		require_serialize.el("jogcim", require_get.requireText(payment.method, `Add meg a(z) ${position}. befizetés módját (method).`)),
-		require_serialize.el("osszeg", payment.amount),
-		require_serialize.optionalEl("leiras", require_get.optionalText(payment.description))
-	]);
-}
-function buildPaymentXml(credentials, request) {
-	const invoiceNumber = require_get.requireText(request.invoiceNumber, "Add meg a számla számát (invoiceNumber), amelyhez a befizetés tartozik.");
-	return require_serialize.buildXmlDocument({
-		root: "xmlszamlakifiz",
-		namespace: "http://www.szamlazz.hu/xmlszamlakifiz",
-		schemaLocation: `${require_get.AGENT_XSD_BASE_URL}agentkifiz/xmlszamlakifiz.xsd`,
-		children: [require_serialize.el("beallitasok", [
-			...credentials,
-			require_serialize.el("szamlaszam", invoiceNumber),
-			require_serialize.optionalEl("adoszam", require_get.optionalText(request.taxNumber)),
-			require_serialize.el("additiv", request.additive),
-			require_serialize.el("valaszVerzio", 2)
-		]), ...request.payments.map(paymentNode)]
-	});
-}
-function parseRegisterPaymentResponse(response, invoiceNumber) {
-	const result = require_get.parseInvoiceResult(response);
-	return {
-		invoiceNumber: result.number ?? invoiceNumber.trim(),
-		netTotal: result.netTotal,
-		grossTotal: result.grossTotal,
-		outstanding: result.outstanding,
-		buyerAccountUrl: result.buyerAccountUrl
-	};
-}
-function sendPaymentRequest(ctx, request, options) {
-	const xml = buildPaymentXml(ctx.credentials, request);
-	return ctx.execute({
-		action: "registerPayment",
-		xml,
-		signal: options.signal,
-		safeToRetry: !request.additive
-	}, (response) => parseRegisterPaymentResponse(response, request.invoiceNumber));
-}
-async function registerPayment(ctx, input, options = {}) {
-	return sendPaymentRequest(ctx, normalizeRegisterInput(input), options);
-}
-async function clearPayments(ctx, input, options = {}) {
-	return sendPaymentRequest(ctx, normalizeClearInput(input), options);
-}
 //#endregion
 //#region src/invoices/pdf.ts
 function buildInvoicePdfXml(credentials, reference) {
-	const resolved = require_get.resolveInvoiceReference(reference);
+	const resolved = require_reference.resolveInvoiceReference(reference);
 	return require_serialize.buildXmlDocument({
 		root: "xmlszamlapdf",
 		namespace: "http://www.szamlazz.hu/xmlszamlapdf",
-		schemaLocation: `${require_get.AGENT_XSD_BASE_URL}agentpdf/xmlszamlapdf.xsd`,
+		schemaLocation: `${require_reference.AGENT_XSD_BASE_URL}agentpdf/xmlszamlapdf.xsd`,
 		children: [
 			...credentials,
-			require_serialize.optionalEl("szamlaszam", require_get.referenceValue(resolved, "invoiceNumber")),
-			require_serialize.optionalEl("rendelesSzam", require_get.referenceValue(resolved, "orderNumber")),
+			require_serialize.optionalEl("szamlaszam", require_reference.referenceValue(resolved, "invoiceNumber")),
+			require_serialize.optionalEl("rendelesSzam", require_reference.referenceValue(resolved, "orderNumber")),
 			require_serialize.el("valaszVerzio", 2),
-			require_serialize.optionalEl("szamlaKulsoAzon", require_get.referenceValue(resolved, "externalId"))
+			require_serialize.optionalEl("szamlaKulsoAzon", require_reference.referenceValue(resolved, "externalId"))
 		]
 	});
 }
 function parseInvoicePdfResponse(response) {
-	const { pdf, ...rest } = require_get.parseInvoiceResult(response);
+	const { pdf, ...rest } = require_reference.parseInvoiceResult(response);
 	if (pdf === void 0 || pdf.length === 0) throw require_parse.unexpectedResponse(response, "A válasz nem tartalmaz PDF-et.");
 	return {
 		...rest,
@@ -667,12 +749,12 @@ async function getInvoicePdf(ctx, reference, options = {}) {
 const RESPONSE_ROOTS = /* @__PURE__ */ new Set(["xmlszamladbkdelvalasz", "xmlszamlavalasz"]);
 const REFERENCE_HINT = "Add meg a díjbekérő számát szövegként, vagy pontosan egyet ezek közül: { proformaNumber }, { orderNumber }.";
 function resolveProformaReference(reference) {
-	if (typeof reference === "string") return { proformaNumber: require_get.requireText(reference, `Üres díjbekérőszám. ${REFERENCE_HINT}`) };
-	if (typeof reference !== "object" || reference === null) throw require_get.validationError(`Érvénytelen díjbekérő-hivatkozás. ${REFERENCE_HINT}`);
+	if (typeof reference === "string") return { proformaNumber: require_reference.requireText(reference, `Üres díjbekérőszám. ${REFERENCE_HINT}`) };
+	if (typeof reference !== "object" || reference === null) throw require_reference.validationError(`Érvénytelen díjbekérő-hivatkozás. ${REFERENCE_HINT}`);
 	const record = reference;
 	const hasNumber = record.proformaNumber !== void 0;
-	if (hasNumber === (record.orderNumber !== void 0)) throw require_get.validationError(`Érvénytelen díjbekérő-hivatkozás. ${REFERENCE_HINT}`);
-	return hasNumber ? { proformaNumber: require_get.requireText(record.proformaNumber, `Üres proformaNumber. ${REFERENCE_HINT}`) } : { orderNumber: require_get.requireText(record.orderNumber, `Üres orderNumber. ${REFERENCE_HINT}`) };
+	if (hasNumber === (record.orderNumber !== void 0)) throw require_reference.validationError(`Érvénytelen díjbekérő-hivatkozás. ${REFERENCE_HINT}`);
+	return hasNumber ? { proformaNumber: require_reference.requireText(record.proformaNumber, `Üres proformaNumber. ${REFERENCE_HINT}`) } : { orderNumber: require_reference.requireText(record.orderNumber, `Üres orderNumber. ${REFERENCE_HINT}`) };
 }
 function buildDeleteProformaXml(credentials, reference) {
 	const resolved = resolveProformaReference(reference);
@@ -721,48 +803,48 @@ function normalizeInput$2(input) {
 }
 function validateTemplate(template) {
 	if (template === void 0 || templates.has(template)) return template;
-	throw require_get.validationError(`Ismeretlen számlasablon: ${String(template)}. Lehetséges értékek: ${require_create_once.INVOICE_TEMPLATES.join(", ")}.`);
+	throw require_reference.validationError(`Ismeretlen számlasablon: ${String(template)}. Lehetséges értékek: ${require_create_once.INVOICE_TEMPLATES.join(", ")}.`);
 }
 function buildReverseInvoiceXml(credentials, input) {
 	const options = normalizeInput$2(input);
-	const invoiceNumber = require_get.requireText(options.invoiceNumber, "Add meg a sztornózandó számla számát (invoiceNumber).");
+	const invoiceNumber = require_reference.requireText(options.invoiceNumber, "Add meg a sztornózandó számla számát (invoiceNumber).");
 	const email = options.email;
 	const buyer = options.buyer;
 	return require_serialize.buildXmlDocument({
 		root: "xmlszamlast",
 		namespace: "http://www.szamlazz.hu/xmlszamlast",
-		schemaLocation: `${require_get.AGENT_XSD_BASE_URL}agentst/xmlszamlast.xsd`,
+		schemaLocation: `${require_reference.AGENT_XSD_BASE_URL}agentst/xmlszamlast.xsd`,
 		children: [
 			require_serialize.el("beallitasok", [
 				...credentials,
 				require_serialize.el("eszamla", options.eInvoice ?? false),
 				require_serialize.el("szamlaLetoltes", options.downloadPdf ?? true),
 				require_serialize.el("valaszVerzio", 2),
-				require_serialize.optionalEl("szamlaKulsoAzon", require_get.optionalText(options.externalId))
+				require_serialize.optionalEl("szamlaKulsoAzon", require_reference.optionalText(options.externalId))
 			]),
 			require_serialize.el("fejlec", [
 				require_serialize.el("szamlaszam", invoiceNumber),
-				require_serialize.optionalEl("keltDatum", require_get.optionalAgentDate(options.issueDate, "issueDate")),
-				require_serialize.optionalEl("teljesitesDatum", require_get.optionalAgentDate(options.fulfillmentDate, "fulfillmentDate")),
-				require_serialize.optionalEl("megjegyzes", require_get.optionalText(options.comment)),
+				require_serialize.optionalEl("keltDatum", require_reference.optionalAgentDate(options.issueDate, "issueDate")),
+				require_serialize.optionalEl("teljesitesDatum", require_reference.optionalAgentDate(options.fulfillmentDate, "fulfillmentDate")),
+				require_serialize.optionalEl("megjegyzes", require_reference.optionalText(options.comment)),
 				require_serialize.el("tipus", "SS"),
 				require_serialize.optionalEl("szamlaSablon", validateTemplate(options.template))
 			]),
 			require_serialize.optionalEl("elado", [
-				require_serialize.optionalEl("emailReplyto", require_get.optionalText(email?.replyTo)),
-				require_serialize.optionalEl("emailTargy", require_get.optionalText(email?.subject)),
-				require_serialize.optionalEl("emailSzoveg", require_get.optionalText(email?.text))
+				require_serialize.optionalEl("emailReplyto", require_reference.optionalText(email?.replyTo)),
+				require_serialize.optionalEl("emailTargy", require_reference.optionalText(email?.subject)),
+				require_serialize.optionalEl("emailSzoveg", require_reference.optionalText(email?.text))
 			]),
 			require_serialize.optionalEl("vevo", [
-				require_serialize.optionalEl("email", require_get.optionalText(buyer?.email)),
-				require_serialize.optionalEl("adoszam", require_get.optionalText(buyer?.taxNumber)),
-				require_serialize.optionalEl("adoszamEU", require_get.optionalText(buyer?.euTaxNumber))
+				require_serialize.optionalEl("email", require_reference.optionalText(buyer?.email)),
+				require_serialize.optionalEl("adoszam", require_reference.optionalText(buyer?.taxNumber)),
+				require_serialize.optionalEl("adoszamEU", require_reference.optionalText(buyer?.euTaxNumber))
 			])
 		]
 	});
 }
 function parseReverseInvoiceResponse(response, originalInvoiceNumber) {
-	const result = require_get.parseInvoiceResult(response);
+	const result = require_reference.parseInvoiceResult(response);
 	if (result.number === void 0) throw require_parse.unexpectedResponse(response, "A válaszban nincs sztornó számlaszám.");
 	if (originalInvoiceNumber !== void 0 && result.number === originalInvoiceNumber.trim()) throw new require_errors.SzamlazzError(`A(z) ${result.number} bizonylat nem lett sztornózva: a Számlázz.hu az eredeti bizonylatot adta vissza.`, {
 		category: "validation",
@@ -791,10 +873,10 @@ function normalizeInput$1(input) {
 	return typeof input === "string" ? { receiptNumber: input } : input;
 }
 function resolveIdentifier(input) {
-	const receiptNumber = require_issue.optionalText(input.receiptNumber);
-	const orderNumber = require_issue.optionalText(input.orderNumber);
-	if (receiptNumber === void 0 && orderNumber === void 0) throw require_issue.receiptValidationError("A nyugta lekérdezéséhez add meg a nyugtaszámot (receiptNumber) vagy a rendelésszámot (orderNumber).");
-	if (receiptNumber !== void 0 && orderNumber !== void 0) throw require_issue.receiptValidationError("A nyugta lekérdezéséhez a nyugtaszám (receiptNumber) és a rendelésszám (orderNumber) közül csak az egyiket add meg.");
+	const receiptNumber = require_create.optionalText(input.receiptNumber);
+	const orderNumber = require_create.optionalText(input.orderNumber);
+	if (receiptNumber === void 0 && orderNumber === void 0) throw require_create.receiptValidationError("A nyugta lekérdezéséhez add meg a nyugtaszámot (receiptNumber) vagy a rendelésszámot (orderNumber).");
+	if (receiptNumber !== void 0 && orderNumber !== void 0) throw require_create.receiptValidationError("A nyugta lekérdezéséhez a nyugtaszám (receiptNumber) és a rendelésszám (orderNumber) közül csak az egyiket add meg.");
 	return {
 		receiptNumber,
 		orderNumber
@@ -806,12 +888,12 @@ function buildGetReceiptXml(credentials, input) {
 	return require_serialize.buildXmlDocument({
 		root: "xmlnyugtaget",
 		namespace: GET_RECEIPT_NAMESPACE,
-		schemaLocation: `${require_issue.RECEIPT_XSD_BASE_URL}nyugtaget/xmlnyugtaget.xsd`,
+		schemaLocation: `${require_create.RECEIPT_XSD_BASE_URL}nyugtaget/xmlnyugtaget.xsd`,
 		children: [require_serialize.el("beallitasok", [...credentials, require_serialize.el("pdfLetoltes", normalized.downloadPdf ?? true)]), require_serialize.el("fejlec", [
 			require_serialize.optionalEl("nyugtaszam", receiptNumber),
 			require_serialize.optionalEl("rendelesSzam", orderNumber),
-			require_serialize.optionalEl("hivasAzonosito", require_issue.optionalText(normalized.callId)),
-			require_serialize.optionalEl("pdfSablon", require_issue.validateTemplate(normalized.template))
+			require_serialize.optionalEl("hivasAzonosito", require_create.optionalText(normalized.callId)),
+			require_serialize.optionalEl("pdfSablon", require_create.validateTemplate(normalized.template))
 		])]
 	});
 }
@@ -835,11 +917,11 @@ function buildReverseReceiptXml(credentials, input) {
 	return require_serialize.buildXmlDocument({
 		root: "xmlnyugtast",
 		namespace: REVERSE_RECEIPT_NAMESPACE,
-		schemaLocation: `${require_issue.RECEIPT_XSD_BASE_URL}nyugtast/xmlnyugtast.xsd`,
+		schemaLocation: `${require_create.RECEIPT_XSD_BASE_URL}nyugtast/xmlnyugtast.xsd`,
 		children: [require_serialize.el("beallitasok", [...credentials, require_serialize.el("pdfLetoltes", normalized.downloadPdf ?? true)]), require_serialize.el("fejlec", [
-			require_serialize.el("nyugtaszam", require_issue.requireReceiptNumber(normalized.receiptNumber)),
-			require_serialize.optionalEl("pdfSablon", require_issue.validateTemplate(normalized.template)),
-			require_serialize.optionalEl("hivasAzonosito", require_issue.optionalText(normalized.callId))
+			require_serialize.el("nyugtaszam", require_create.requireReceiptNumber(normalized.receiptNumber)),
+			require_serialize.optionalEl("pdfSablon", require_create.validateTemplate(normalized.template)),
+			require_serialize.optionalEl("hivasAzonosito", require_create.optionalText(normalized.callId))
 		])]
 	});
 }
@@ -850,7 +932,7 @@ function reverseReceipt(ctx, input, options = {}) {
 		action: "reverseReceipt",
 		xml,
 		signal: options.signal,
-		safeToRetry: require_issue.optionalText(normalized.callId) !== void 0
+		safeToRetry: require_create.optionalText(normalized.callId) !== void 0
 	}, require_parse.parseReceiptResponse);
 }
 //#endregion
@@ -861,30 +943,30 @@ function isValidEmail(value) {
 	return EMAIL_PATTERN.test(value);
 }
 function assertEmail(value, field) {
-	if (!isValidEmail(value)) throw require_issue.receiptValidationError(`Érvénytelen e-mail cím a(z) ${field} mezőben: ${value}`);
+	if (!isValidEmail(value)) throw require_create.receiptValidationError(`Érvénytelen e-mail cím a(z) ${field} mezőben: ${value}`);
 	return value;
 }
 function normalizeEmails(emails) {
 	const list = (typeof emails === "string" ? [emails] : [...emails]).flatMap((entry) => entry.split(/[,;]/)).map((entry) => entry.trim()).filter((entry) => entry !== "");
-	if (list.length === 0) throw require_issue.receiptValidationError("Adj meg legalább egy címzett e-mail címet (emails).");
+	if (list.length === 0) throw require_create.receiptValidationError("Adj meg legalább egy címzett e-mail címet (emails).");
 	return list.map((email) => assertEmail(email, "emails"));
 }
 function buildSendReceiptXml(credentials, input) {
-	const receiptNumber = require_issue.requireReceiptNumber(input.receiptNumber);
+	const receiptNumber = require_create.requireReceiptNumber(input.receiptNumber);
 	const emails = normalizeEmails(input.emails);
-	const replyTo = require_issue.optionalText(input.replyTo);
+	const replyTo = require_create.optionalText(input.replyTo);
 	if (replyTo !== void 0) assertEmail(replyTo, "replyTo");
 	return require_serialize.buildXmlDocument({
 		root: "xmlnyugtasend",
 		namespace: SEND_RECEIPT_NAMESPACE,
-		schemaLocation: `${require_issue.RECEIPT_XSD_BASE_URL}nyugtasend/xmlnyugtasend.xsd`,
+		schemaLocation: `${require_create.RECEIPT_XSD_BASE_URL}nyugtasend/xmlnyugtasend.xsd`,
 		children: [
 			require_serialize.el("beallitasok", credentials),
 			require_serialize.el("fejlec", [require_serialize.el("nyugtaszam", receiptNumber)]),
 			require_serialize.el("emailKuldes", [
 				require_serialize.el("email", emails.join(",")),
 				require_serialize.optionalEl("emailReplyto", replyTo),
-				require_serialize.el("emailTargy", require_issue.optionalText(input.subject) ?? `Nyugta ${receiptNumber}`),
+				require_serialize.el("emailTargy", require_create.optionalText(input.subject) ?? `Nyugta ${receiptNumber}`),
 				require_serialize.optionalEl("emailSzoveg", input.text?.trim() ? input.text : void 0)
 			])
 		]
@@ -1087,6 +1169,54 @@ async function queryTaxpayer(ctx, taxNumber, options = {}) {
 	}, parseQueryTaxpayerResponse);
 }
 //#endregion
+//#region src/taxpayer/cache.ts
+const TAXPAYER_CACHE_KEY_PREFIX = "szamlazz:taxpayer:";
+const DEFAULT_TAXPAYER_TTL_SECONDS = 86400;
+const DEFAULT_TAXPAYER_INVALID_TTL_SECONDS = 600;
+function positiveSeconds(value, fallback, field) {
+	if (value === void 0) return fallback;
+	if (!Number.isFinite(value) || value < 1) throw new require_errors.SzamlazzError(`A(z) ${field} legalább 1 másodperc legyen, kapott: ${String(value)}`, { category: "configuration" });
+	return Math.ceil(value);
+}
+function parseCached(value) {
+	if (typeof value !== "string" || value === "") return void 0;
+	try {
+		const parsed = JSON.parse(value);
+		if (typeof parsed !== "object" || parsed === null) return void 0;
+		const info = parsed;
+		return typeof info.valid === "boolean" && Array.isArray(info.addresses) ? info : void 0;
+	} catch {
+		return;
+	}
+}
+function cachedTaxpayerQuery(query, options, warn) {
+	const ttl = positiveSeconds(options.ttlSeconds, DEFAULT_TAXPAYER_TTL_SECONDS, "ttlSeconds");
+	const invalidTtl = positiveSeconds(options.invalidTtlSeconds, 600, "invalidTtlSeconds");
+	const report = (operation, error) => warn?.({
+		kind: "cache",
+		message: `Az adószám-gyorsítótár "${operation}" művelete sikertelen, a kassza a Számlázz.hu-tól kérdez.`,
+		error,
+		action: "queryTaxpayer",
+		operation
+	});
+	return async (taxNumber, requestOptions) => {
+		const key = `${TAXPAYER_CACHE_KEY_PREFIX}${toTaxpayerId(taxNumber)}`;
+		try {
+			const cached = parseCached(await options.store.get(key));
+			if (cached) return cached;
+		} catch (error) {
+			report("get", error);
+		}
+		const info = await query(taxNumber, requestOptions);
+		try {
+			await options.store.set(key, JSON.stringify(info), info.valid ? ttl : invalidTtl);
+		} catch (error) {
+			report("set", error);
+		}
+		return info;
+	};
+}
+//#endregion
 //#region src/client.ts
 const CREDENTIAL_PROBE_INVOICE_NUMBER = "KASSZA-CREDENTIAL-PROBE-0";
 async function nullIfNotFound(promise) {
@@ -1109,11 +1239,14 @@ function invoiceNumberOf(input) {
 function receiptNumberOf(input) {
 	return typeof input === "string" ? input : input.receiptNumber;
 }
-function createInvoicesApi(ctx, defaults, onDocument) {
+function createDocumentEmitter(hook, options) {
+	return { emit: (event) => require_create_once.emitDocumentEvent(hook, event, options) };
+}
+function createInvoicesApi(ctx, defaults, events, guard) {
 	const api = {
 		async create(input, options) {
 			const document = await createInvoice(ctx, defaults, input, options);
-			await require_create_once.emitDocumentEvent(onDocument, {
+			await events.emit({
 				kind: "invoice",
 				action: "created",
 				number: document.number,
@@ -1122,11 +1255,11 @@ function createInvoicesApi(ctx, defaults, onDocument) {
 			});
 			return document;
 		},
-		createOnce: (input, options) => require_issue.createInvoiceOnce(api, input, options),
+		createOnce: (input, options) => require_issue.createInvoiceOnce(api, input, options, guard),
 		preview: (input, options) => previewInvoice(ctx, defaults, input, options),
 		async reverse(input, options) {
 			const document = await reverseInvoice(ctx, input, options);
-			await require_create_once.emitDocumentEvent(onDocument, {
+			await events.emit({
 				kind: "invoice",
 				action: "reversed",
 				number: document.number,
@@ -1136,8 +1269,8 @@ function createInvoicesApi(ctx, defaults, onDocument) {
 			return document;
 		},
 		async registerPayment(input, options) {
-			const document = await registerPayment(ctx, input, options);
-			await require_create_once.emitDocumentEvent(onDocument, {
+			const document = await require_create_once.registerPayment(ctx, input, options);
+			await events.emit({
 				kind: "invoice",
 				action: "payment",
 				number: document.invoiceNumber,
@@ -1145,9 +1278,10 @@ function createInvoicesApi(ctx, defaults, onDocument) {
 			});
 			return document;
 		},
+		registerPaymentOnce: (input, options) => require_create_once.registerPaymentOnce(api, input, options, guard),
 		async clearPayments(input, options) {
-			const document = await clearPayments(ctx, input, options);
-			await require_create_once.emitDocumentEvent(onDocument, {
+			const document = await require_create_once.clearPayments(ctx, input, options);
+			await events.emit({
 				kind: "invoice",
 				action: "payment",
 				number: document.invoiceNumber,
@@ -1162,11 +1296,20 @@ function createInvoicesApi(ctx, defaults, onDocument) {
 	};
 	return api;
 }
-function createReceiptsApi(ctx, defaults, invoices, onDocument) {
+function convertedJoin(result) {
+	return {
+		receipt: result.receipt,
+		invoice: {
+			...result.invoice,
+			created: false
+		}
+	};
+}
+function createReceiptsApi(ctx, defaults, invoices, events, guard) {
 	const api = {
 		async create(input, options) {
-			const document = await require_issue.createReceipt(ctx, defaults, input, options);
-			await require_create_once.emitDocumentEvent(onDocument, {
+			const document = await require_create.createReceipt(ctx, defaults, input, options);
+			await events.emit({
 				kind: "receipt",
 				action: "created",
 				number: document.number,
@@ -1174,10 +1317,10 @@ function createReceiptsApi(ctx, defaults, invoices, onDocument) {
 			});
 			return document;
 		},
-		createOnce: (input, options) => require_create_once.createReceiptOnce(api, input, options),
+		createOnce: (input, options) => require_create_once.createReceiptOnce(api, input, options, guard),
 		async reverse(input, options) {
 			const document = await reverseReceipt(ctx, input, options);
-			await require_create_once.emitDocumentEvent(onDocument, {
+			await events.emit({
 				kind: "receipt",
 				action: "reversed",
 				number: document.number,
@@ -1189,22 +1332,38 @@ function createReceiptsApi(ctx, defaults, invoices, onDocument) {
 		get: (input, options) => getReceipt(ctx, input, options),
 		find: (input, options) => nullIfNotFound(getReceipt(ctx, input, options)),
 		send: (input, options) => sendReceipt(ctx, input, options),
-		convertToInvoice: (input, options) => require_issue.convertReceiptToInvoice({
+		convertToInvoice: (input, options = {}) => require_issue.guardOnce(guard, `convert:${input.receiptNumber?.trim() ?? ""}`, {
+			...options,
+			lock: false
+		}, () => require_issue.convertReceiptToInvoice({
 			receipts: api,
 			invoices
-		}, input, options)
+		}, input, options), convertedJoin)
 	};
 	return api;
 }
+function onceScopeOf(ctx) {
+	return ctx.credentials.map((node) => `${node.name}=${String(node.content)}`).join("\n");
+}
 function createKassza(options = {}) {
 	const ctx = createAgentContext(options);
-	const onDocument = options.hooks?.onDocument;
-	const invoices = createInvoicesApi(ctx, options.defaults?.invoice ?? {}, onDocument);
-	const receipts = createReceiptsApi(ctx, options.defaults?.receipt ?? {}, invoices, onDocument);
+	const events = createDocumentEmitter(options.hooks?.onDocument, {
+		mode: options.hooks?.onDocumentError,
+		onWarning: options.hooks?.onWarning
+	});
+	const guard = {
+		scope: onceScopeOf(ctx),
+		lock: options.createOnceLock,
+		warn: ctx.warn
+	};
+	const directQuery = (taxNumber, requestOptions) => queryTaxpayer(ctx, taxNumber, requestOptions);
+	const taxpayerQuery = options.taxpayerCache ? cachedTaxpayerQuery(directQuery, options.taxpayerCache, ctx.warn) : directQuery;
+	const invoices = createInvoicesApi(ctx, options.defaults?.invoice ?? {}, events, guard);
+	const receipts = createReceiptsApi(ctx, options.defaults?.receipt ?? {}, invoices, events, guard);
 	return {
 		invoices,
 		receipts,
-		taxpayer: { query: (taxNumber, requestOptions) => queryTaxpayer(ctx, taxNumber, requestOptions) },
+		taxpayer: { query: taxpayerQuery },
 		async verifyCredentials(requestOptions) {
 			try {
 				await getInvoicePdf(ctx, CREDENTIAL_PROBE_INVOICE_NUMBER, requestOptions);
@@ -1237,6 +1396,24 @@ Object.defineProperty(exports, "ATTEMPT_LEDGER_TTL_SECONDS", {
 		return ATTEMPT_LEDGER_TTL_SECONDS;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_TAXPAYER_INVALID_TTL_SECONDS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_TAXPAYER_INVALID_TTL_SECONDS;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_TAXPAYER_TTL_SECONDS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_TAXPAYER_TTL_SECONDS;
+	}
+});
+Object.defineProperty(exports, "TAXPAYER_CACHE_KEY_PREFIX", {
+	enumerable: true,
+	get: function() {
+		return TAXPAYER_CACHE_KEY_PREFIX;
+	}
+});
 Object.defineProperty(exports, "attemptLedgerKey", {
 	enumerable: true,
 	get: function() {