kassza 0.13.0 → 0.14.0

package/dist/{client-CfaS1-Jx.js → client-Cvf-hTz_.js}

@@ -1,14 +1,16 @@
-import { c as emitDocumentEvent, i as resolveInvoice, l as AGENT_ACTIONS, n as optionalAgentDate, o as INVOICE_TEMPLATES, r as presentText, s as TAXPAYER_TYPE_CODES, t as createReceiptOnce } from "./create-once-Cz621l8r.js";
-import { a as parseErrorCode, i as isSzamlazzError, n as SzamlazzError, r as createAgentError } from "./errors-DLrb0g64.js";
+import { a as registerPayment, c as resolveInvoice, d as TAXPAYER_TYPE_CODES, h as AGENT_ACTIONS, i as clearPayments, o as optionalAgentDate, p as emitDocumentEvent, r as registerPaymentOnce, s as presentText, t as createReceiptOnce, u as INVOICE_TEMPLATES } from "./create-once-Ca2gMk1h.js";
+import { i as createAgentError, o as isSzamlazzError, r as SzamlazzError, s as parseErrorCode } from "./errors-DtN4g5Z9.js";
 import { t as base64ToBytes } from "./binary-D0M9U2MD.js";
-import { a as optionalEl, c as childNumber, d as findChildren, l as childText, n as buildXmlDocument, r as el, s as childBoolean, u as findChild } from "./serialize-DSE_o9RK.js";
-import { a as looksLikeXml, c as readDocumentHeaders, d as throwIfHeaderError, f as throwIfHttpError, h as unexpectedResponse, m as throwIfXmlFailure, n as parseReceiptResponse, o as parseDoneText, p as throwIfTextError, r as createAgentResponse, s as parseResponseXml, u as throwIfAnyError } from "./parse-C608ehqM.js";
-import { i as sessionKeyFor, n as memoryCookieStore, r as mergeSetCookies, t as SESSION_TTL_SECONDS } from "./session-rMKaJcmq.js";
-import { a as todayInBudapest } from "./dates-CXyj7Azy.js";
+import { a as optionalEl, c as childNumber, d as findChildren, l as childText, n as buildXmlDocument, r as el, s as childBoolean, u as findChild } from "./serialize-B2eFh3D-.js";
+import { a as looksLikeXml, c as readDocumentHeaders, d as throwIfHeaderError, f as throwIfHttpError, h as unexpectedResponse, m as throwIfXmlFailure, n as parseReceiptResponse, o as parseDoneText, p as throwIfTextError, r as createAgentResponse, s as parseResponseXml, u as throwIfAnyError } from "./parse-Cr7yQ3_z.js";
+import { i as sessionKeyFor, n as memoryCookieStore, r as mergeSetCookies, t as SESSION_TTL_SECONDS } from "./session-SaEEXu2N.js";
+import { t as emitWarning } from "./warnings-DwTl5J-2.js";
+import { l as createInvoiceOnce, m as guardOnce, n as issueForPayment, o as convertReceiptToInvoice } from "./issue-DMA1Nbr1.js";
 import { r as formatVatRate } from "./vat-v_dcWCto.js";
-import { i as summarizeItems } from "./money-t7uy1n91.js";
-import { _ as createInvoiceOnce, c as optionalText, d as validateTemplate$1, l as receiptValidationError, n as issueForPayment, o as createReceipt, p as convertReceiptToInvoice, s as RECEIPT_XSD_BASE_URL, u as requireReceiptNumber } from "./issue-DtSLpVdJ.js";
-import { a as optionalAgentDate$1, c as referenceValue, d as validationError, i as agentDate, l as requireText, o as optionalText$1, r as AGENT_XSD_BASE_URL, s as parseInvoiceResult, t as getInvoice, u as resolveInvoiceReference } from "./get-DT3JEgQ6.js";
+import { a as summarizeItems } from "./money-Cw457SD6.js";
+import { a as optionalText, c as requireText, i as optionalAgentDate$1, l as resolveInvoiceReference, o as parseInvoiceResult, s as referenceValue, t as AGENT_XSD_BASE_URL, u as validationError } from "./reference-B5TATqb5.js";
+import { t as getInvoice } from "./get-CZEShCcj.js";
+import { a as optionalText$1, c as validateTemplate$1, i as RECEIPT_XSD_BASE_URL, o as receiptValidationError, r as createReceipt, s as requireReceiptNumber } from "./create-CflXrPip.js";
 //#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) => emitWarning(hooks.onWarning, hookWarning(name, event.action, error)));
+	} catch (error) {
+		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 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) => 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 = mergeSetCookies(cookie, response.headers);
-			if (merged) await ignoreStoreFailure(async () => cookieStore.set(await resolveSessionKey(), merged, SESSION_TTL_SECONDS));
+			if (merged) await ignoreStoreFailure("set", request.action, async () => cookieStore.set(await resolveSessionKey(), merged, SESSION_TTL_SECONDS));
 		}
-		return createAgentResponse(request.action, response.status, response.headers, body);
+		return {
+			response: 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 SzamlazzError)) throw error;
-				if (ledger && ledgerKey !== void 0 && countsAsFailedAttempt(error)) await ignoreStoreFailure(() => ledger.recordFailure(ledgerKey, failures));
+				if (!(error instanceof 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,81 +712,6 @@ 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 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 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 validationError(`A(z) ${position}. befizetés összege (amount) nem véges szám.`);
-	return el("kifizetes", [
-		el("datum", payment.date === void 0 ? todayInBudapest() : agentDate(payment.date, "date")),
-		el("jogcim", requireText(payment.method, `Add meg a(z) ${position}. befizetés módját (method).`)),
-		el("osszeg", payment.amount),
-		optionalEl("leiras", optionalText$1(payment.description))
-	]);
-}
-function buildPaymentXml(credentials, request) {
-	const invoiceNumber = requireText(request.invoiceNumber, "Add meg a számla számát (invoiceNumber), amelyhez a befizetés tartozik.");
-	return buildXmlDocument({
-		root: "xmlszamlakifiz",
-		namespace: "http://www.szamlazz.hu/xmlszamlakifiz",
-		schemaLocation: `${AGENT_XSD_BASE_URL}agentkifiz/xmlszamlakifiz.xsd`,
-		children: [el("beallitasok", [
-			...credentials,
-			el("szamlaszam", invoiceNumber),
-			optionalEl("adoszam", optionalText$1(request.taxNumber)),
-			el("additiv", request.additive),
-			el("valaszVerzio", 2)
-		]), ...request.payments.map(paymentNode)]
-	});
-}
-function parseRegisterPaymentResponse(response, invoiceNumber) {
-	const result = 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) {
@@ -738,25 +820,25 @@ function buildReverseInvoiceXml(credentials, input) {
 				el("eszamla", options.eInvoice ?? false),
 				el("szamlaLetoltes", options.downloadPdf ?? true),
 				el("valaszVerzio", 2),
-				optionalEl("szamlaKulsoAzon", optionalText$1(options.externalId))
+				optionalEl("szamlaKulsoAzon", optionalText(options.externalId))
 			]),
 			el("fejlec", [
 				el("szamlaszam", invoiceNumber),
 				optionalEl("keltDatum", optionalAgentDate$1(options.issueDate, "issueDate")),
 				optionalEl("teljesitesDatum", optionalAgentDate$1(options.fulfillmentDate, "fulfillmentDate")),
-				optionalEl("megjegyzes", optionalText$1(options.comment)),
+				optionalEl("megjegyzes", optionalText(options.comment)),
 				el("tipus", "SS"),
 				optionalEl("szamlaSablon", validateTemplate(options.template))
 			]),
 			optionalEl("elado", [
-				optionalEl("emailReplyto", optionalText$1(email?.replyTo)),
-				optionalEl("emailTargy", optionalText$1(email?.subject)),
-				optionalEl("emailSzoveg", optionalText$1(email?.text))
+				optionalEl("emailReplyto", optionalText(email?.replyTo)),
+				optionalEl("emailTargy", optionalText(email?.subject)),
+				optionalEl("emailSzoveg", optionalText(email?.text))
 			]),
 			optionalEl("vevo", [
-				optionalEl("email", optionalText$1(buyer?.email)),
-				optionalEl("adoszam", optionalText$1(buyer?.taxNumber)),
-				optionalEl("adoszamEU", optionalText$1(buyer?.euTaxNumber))
+				optionalEl("email", optionalText(buyer?.email)),
+				optionalEl("adoszam", optionalText(buyer?.taxNumber)),
+				optionalEl("adoszamEU", optionalText(buyer?.euTaxNumber))
 			])
 		]
 	});
@@ -791,8 +873,8 @@ function normalizeInput$1(input) {
 	return typeof input === "string" ? { receiptNumber: input } : input;
 }
 function resolveIdentifier(input) {
-	const receiptNumber = optionalText(input.receiptNumber);
-	const orderNumber = optionalText(input.orderNumber);
+	const receiptNumber = optionalText$1(input.receiptNumber);
+	const orderNumber = optionalText$1(input.orderNumber);
 	if (receiptNumber === void 0 && orderNumber === void 0) throw 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 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 {
@@ -810,7 +892,7 @@ function buildGetReceiptXml(credentials, input) {
 		children: [el("beallitasok", [...credentials, el("pdfLetoltes", normalized.downloadPdf ?? true)]), el("fejlec", [
 			optionalEl("nyugtaszam", receiptNumber),
 			optionalEl("rendelesSzam", orderNumber),
-			optionalEl("hivasAzonosito", optionalText(normalized.callId)),
+			optionalEl("hivasAzonosito", optionalText$1(normalized.callId)),
 			optionalEl("pdfSablon", validateTemplate$1(normalized.template))
 		])]
 	});
@@ -839,7 +921,7 @@ function buildReverseReceiptXml(credentials, input) {
 		children: [el("beallitasok", [...credentials, el("pdfLetoltes", normalized.downloadPdf ?? true)]), el("fejlec", [
 			el("nyugtaszam", requireReceiptNumber(normalized.receiptNumber)),
 			optionalEl("pdfSablon", validateTemplate$1(normalized.template)),
-			optionalEl("hivasAzonosito", optionalText(normalized.callId))
+			optionalEl("hivasAzonosito", optionalText$1(normalized.callId))
 		])]
 	});
 }
@@ -850,7 +932,7 @@ function reverseReceipt(ctx, input, options = {}) {
 		action: "reverseReceipt",
 		xml,
 		signal: options.signal,
-		safeToRetry: optionalText(normalized.callId) !== void 0
+		safeToRetry: optionalText$1(normalized.callId) !== void 0
 	}, parseReceiptResponse);
 }
 //#endregion
@@ -872,7 +954,7 @@ function normalizeEmails(emails) {
 function buildSendReceiptXml(credentials, input) {
 	const receiptNumber = requireReceiptNumber(input.receiptNumber);
 	const emails = normalizeEmails(input.emails);
-	const replyTo = optionalText(input.replyTo);
+	const replyTo = optionalText$1(input.replyTo);
 	if (replyTo !== void 0) assertEmail(replyTo, "replyTo");
 	return buildXmlDocument({
 		root: "xmlnyugtasend",
@@ -884,7 +966,7 @@ function buildSendReceiptXml(credentials, input) {
 			el("emailKuldes", [
 				el("email", emails.join(",")),
 				optionalEl("emailReplyto", replyTo),
-				el("emailTargy", optionalText(input.subject) ?? `Nyugta ${receiptNumber}`),
+				el("emailTargy", optionalText$1(input.subject) ?? `Nyugta ${receiptNumber}`),
 				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 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) => 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 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) => createInvoiceOnce(api, input, options),
+		createOnce: (input, options) => 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 emitDocumentEvent(onDocument, {
+			await events.emit({
 				kind: "invoice",
 				action: "reversed",
 				number: document.number,
@@ -1137,7 +1270,7 @@ function createInvoicesApi(ctx, defaults, onDocument) {
 		},
 		async registerPayment(input, options) {
 			const document = await registerPayment(ctx, input, options);
-			await emitDocumentEvent(onDocument, {
+			await events.emit({
 				kind: "invoice",
 				action: "payment",
 				number: document.invoiceNumber,
@@ -1145,9 +1278,10 @@ function createInvoicesApi(ctx, defaults, onDocument) {
 			});
 			return document;
 		},
+		registerPaymentOnce: (input, options) => registerPaymentOnce(api, input, options, guard),
 		async clearPayments(input, options) {
 			const document = await clearPayments(ctx, input, options);
-			await emitDocumentEvent(onDocument, {
+			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 createReceipt(ctx, defaults, input, options);
-			await emitDocumentEvent(onDocument, {
+			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) => createReceiptOnce(api, input, options),
+		createOnce: (input, options) => createReceiptOnce(api, input, options, guard),
 		async reverse(input, options) {
 			const document = await reverseReceipt(ctx, input, options);
-			await 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) => convertReceiptToInvoice({
+		convertToInvoice: (input, options = {}) => guardOnce(guard, `convert:${input.receiptNumber?.trim() ?? ""}`, {
+			...options,
+			lock: false
+		}, () => 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);
@@ -1225,4 +1384,4 @@ function createKassza(options = {}) {
 	};
 }
 //#endregion
-export { createAgentContext as a, attemptLedgerKey as c, buildCreateInvoiceXml as i, queryTaxpayer as n, ATTEMPT_LEDGER_KEY_PREFIX as o, getInvoicePdf as r, ATTEMPT_LEDGER_TTL_SECONDS as s, createKassza as t };
+export { queryTaxpayer as a, createAgentContext as c, attemptLedgerKey as d, TAXPAYER_CACHE_KEY_PREFIX as i, ATTEMPT_LEDGER_KEY_PREFIX as l, DEFAULT_TAXPAYER_INVALID_TTL_SECONDS as n, getInvoicePdf as o, DEFAULT_TAXPAYER_TTL_SECONDS as r, buildCreateInvoiceXml as s, createKassza as t, ATTEMPT_LEDGER_TTL_SECONDS as u };