kassza 0.12.0 → 0.14.0

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

@@ -1,11 +1,16 @@
-import { a as INVOICE_TEMPLATES, c as AGENT_ACTIONS, i as resolveInvoice, n as optionalAgentDate$1, o as TAXPAYER_TYPE_CODES, r as presentText, s as emitDocumentEvent, t as createReceiptOnce } from "./create-once-CqdYmQD8.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 parseResponseXml, B as childNumber, C as buildXmlDocument, E as createAgentResponse, F as throwIfHttpError, H as findChild, I as throwIfTextError, L as throwIfXmlFailure, M as readHeader$1, N as throwIfAnyError, O as looksLikeXml, P as throwIfHeaderError, R as unexpectedResponse, T as optionalEl, U as findChildren, V as childText, _ as createInvoiceOnce, c as RECEIPT_XSD_BASE_URL, d as requireReceiptNumber, f as validateTemplate$1, j as readDocumentHeaders, k as parseDoneText, l as optionalText$1, m as convertReceiptToInvoice, n as issueForPayment, o as createReceipt, s as parseReceiptResponse, u as receiptValidationError, w as el, z as childBoolean } from "./issue-C6Fcjvln.js";
-import { i as sessionKeyFor, n as memoryCookieStore, r as mergeSetCookies, t as SESSION_TTL_SECONDS } from "./session-rMKaJcmq.js";
-import { a as todayInBudapest, n as toAgentDate } 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-DAA7OwiO.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:";
@@ -35,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);
+		},
+		fallbackFailures(key) {
+			return local.get(key);
 		},
-		async recordFailure(key, previous) {
-			const next = previous + 1;
-			await store.set(key, String(next), ATTEMPT_LEDGER_TTL_SECONDS);
-			return next;
+		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);
 		}
 	};
@@ -60,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;
@@ -109,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}`);
@@ -164,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);
@@ -199,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);
@@ -220,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);
@@ -227,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
@@ -412,12 +572,12 @@ function sellerNode(seller) {
 function buyerLedgerNode(ledger) {
 	if (!ledger) return void 0;
 	return optionalEl("vevoFokonyv", [
-		optionalEl("konyvelesDatum", optionalAgentDate$1(ledger.bookingDate, "buyer.ledger.bookingDate")),
+		optionalEl("konyvelesDatum", optionalAgentDate(ledger.bookingDate, "buyer.ledger.bookingDate")),
 		textEl("vevoAzonosito", ledger.buyerId),
 		textEl("vevoFokonyviSzam", ledger.ledgerAccount),
 		optionalEl("folyamatosTelj", ledger.continuousFulfillment),
-		optionalEl("elszDatumTol", optionalAgentDate$1(ledger.settlementPeriodStart, "buyer.ledger.settlementPeriodStart")),
-		optionalEl("elszDatumIg", optionalAgentDate$1(ledger.settlementPeriodEnd, "buyer.ledger.settlementPeriodEnd"))
+		optionalEl("elszDatumTol", optionalAgentDate(ledger.settlementPeriodStart, "buyer.ledger.settlementPeriodStart")),
+		optionalEl("elszDatumIg", optionalAgentDate(ledger.settlementPeriodEnd, "buyer.ledger.settlementPeriodEnd"))
 	]);
 }
 function buyerNode(buyer, sendEmail) {
@@ -486,8 +646,8 @@ function itemLedgerNode(ledger, label) {
 		textEl("gazdasagiEsemAfa", ledger.vatEconomicEvent),
 		textEl("arbevetelFokonyviSzam", ledger.revenueLedgerAccount),
 		textEl("afaFokonyviSzam", ledger.vatLedgerAccount),
-		optionalEl("elszDatumTol", optionalAgentDate$1(ledger.settlementPeriodStart, `${label} settlementPeriodStart`)),
-		optionalEl("elszDatumIg", optionalAgentDate$1(ledger.settlementPeriodEnd, `${label} settlementPeriodEnd`))
+		optionalEl("elszDatumTol", optionalAgentDate(ledger.settlementPeriodStart, `${label} settlementPeriodStart`)),
+		optionalEl("elszDatumIg", optionalAgentDate(ledger.settlementPeriodEnd, `${label} settlementPeriodEnd`))
 	]);
 }
 function itemNode(item, index) {
@@ -524,6 +684,9 @@ function renderInvoiceXml(credentials, invoice, options = {}) {
 		]
 	});
 }
+function buildCreateInvoiceXml(credentials, defaults, input, now = /* @__PURE__ */ new Date()) {
+	return renderInvoiceXml(credentials, resolveInvoice(defaults, input, now));
+}
 //#endregion
 //#region src/invoices/create.ts
 function buildRequest(ctx, invoice, preview, options) {
@@ -550,455 +713,6 @@ async function previewInvoice(ctx, defaults, input, options = {}) {
 	return ctx.execute(buildRequest(ctx, invoice, true, options), (response) => parseInvoicePreviewResponse(response, items));
 }
 //#endregion
-//#region src/invoices/reference.ts
-const AGENT_XSD_BASE_URL = "https://www.szamlazz.hu/szamla/docs/xsds/";
-function validationError(message) {
-	return new SzamlazzError(message, { category: "validation" });
-}
-function requireText(value, message) {
-	const trimmed = typeof value === "string" ? value.trim() : "";
-	if (trimmed === "") throw validationError(message);
-	return trimmed;
-}
-function optionalText(value) {
-	const trimmed = value?.trim();
-	return trimmed ? trimmed : void 0;
-}
-function agentDate(input, field) {
-	try {
-		return toAgentDate(input);
-	} catch (error) {
-		const detail = error instanceof Error ? error.message : String(error);
-		throw new SzamlazzError(`Érvénytelen dátum (${field}): ${detail}`, {
-			category: "validation",
-			cause: error
-		});
-	}
-}
-function optionalAgentDate(input, field) {
-	return input === void 0 ? void 0 : agentDate(input, field);
-}
-const REFERENCE_KEYS = [
-	"invoiceNumber",
-	"orderNumber",
-	"externalId"
-];
-const REFERENCE_HINT$1 = "Add meg a számlaszámot szövegként, vagy pontosan egyet ezek közül: { invoiceNumber }, { orderNumber }, { externalId }.";
-function resolveInvoiceReference(reference) {
-	if (typeof reference === "string") return {
-		kind: "invoiceNumber",
-		value: requireText(reference, `Üres számlaszám. ${REFERENCE_HINT$1}`)
-	};
-	if (typeof reference !== "object" || reference === null) throw validationError(`Érvénytelen bizonylat-hivatkozás. ${REFERENCE_HINT$1}`);
-	const record = reference;
-	const present = REFERENCE_KEYS.filter((key) => record[key] !== void 0);
-	const [kind] = present;
-	if (kind === void 0 || present.length > 1) throw validationError(`Érvénytelen bizonylat-hivatkozás. ${REFERENCE_HINT$1}`);
-	return {
-		kind,
-		value: requireText(record[kind], `Üres ${kind} érték. ${REFERENCE_HINT$1}`)
-	};
-}
-function referenceValue(reference, kind) {
-	return reference.kind === kind ? reference.value : void 0;
-}
-function readNumericHeader(headers, name) {
-	const value = readHeader$1(headers, name);
-	if (value === void 0) return void 0;
-	const parsed = Number(value.replace(",", "."));
-	return Number.isFinite(parsed) ? parsed : void 0;
-}
-function headerSummary(response) {
-	const headers = readDocumentHeaders(response.headers);
-	return {
-		number: headers.number,
-		netTotal: headers.netTotal,
-		grossTotal: headers.grossTotal,
-		outstanding: readNumericHeader(response.headers, "szlahu_kintlevoseg"),
-		buyerAccountUrl: headers.buyerAccountUrl
-	};
-}
-function decodeResponsePdf(root, response) {
-	const encoded = childText(root, "pdf");
-	if (encoded === void 0) return void 0;
-	try {
-		return base64ToBytes(encoded);
-	} catch (error) {
-		throw new SzamlazzError("A válaszban kapott PDF nem érvényes base64.", {
-			category: "unexpected_response",
-			action: response.action,
-			httpStatus: response.status,
-			cause: error
-		});
-	}
-}
-function readInvoiceResultXml(root, response) {
-	const headers = headerSummary(response);
-	return {
-		number: childText(root, "szamlaszam") ?? headers.number,
-		netTotal: childNumber(root, "szamlanetto") ?? headers.netTotal,
-		grossTotal: childNumber(root, "szamlabrutto") ?? headers.grossTotal,
-		outstanding: childNumber(root, "kintlevoseg") ?? headers.outstanding,
-		buyerAccountUrl: childText(root, "vevoifiokurl") ?? headers.buyerAccountUrl,
-		pdf: decodeResponsePdf(root, response)
-	};
-}
-const INVOICE_RESULT_ROOT = "xmlszamlavalasz";
-function parseInvoiceResult(response) {
-	throwIfHeaderError(response);
-	if (response.isPdf) return {
-		...headerSummary(response),
-		pdf: response.body
-	};
-	throwIfTextError(response);
-	throwIfHttpError(response);
-	if (looksLikeXml(response)) {
-		const root = parseResponseXml(response);
-		throwIfXmlFailure(root, response);
-		if (root.name !== INVOICE_RESULT_ROOT || childText(root, "sikeres")?.toLowerCase() !== "true") throw unexpectedResponse(response, `${INVOICE_RESULT_ROOT} XML választ vártunk.`);
-		return readInvoiceResultXml(root, response);
-	}
-	const headers = headerSummary(response);
-	const done = parseDoneText(response.text());
-	if (done) return {
-		...headers,
-		number: done.number ?? headers.number
-	};
-	if (headers.number !== void 0) return headers;
-	throw unexpectedResponse(response);
-}
-//#endregion
-//#region src/invoices/get.ts
-const INVOICE_DOCUMENT_TYPE_CODES = {
-	invoice: "SZ",
-	proforma: "D",
-	advance: "ES",
-	final: "VS",
-	corrective: "HS",
-	reversal: "SS",
-	deliveryNote: "SL"
-};
-function buildGetInvoiceXml(credentials, reference, query = {}) {
-	const resolved = resolveInvoiceReference(reference);
-	return buildXmlDocument({
-		root: "xmlszamlaxml",
-		namespace: "http://www.szamlazz.hu/xmlszamlaxml",
-		schemaLocation: `${AGENT_XSD_BASE_URL}agentxml/xmlszamlaxml.xsd`,
-		children: [
-			...credentials,
-			optionalEl("szamlaszam", referenceValue(resolved, "invoiceNumber")),
-			optionalEl("rendelesSzam", referenceValue(resolved, "orderNumber")),
-			optionalEl("pdf", query.includePdf),
-			optionalEl("szamlaKulsoAzon", referenceValue(resolved, "externalId"))
-		]
-	});
-}
-var InvoiceReader = class {
-	response;
-	constructor(response) {
-		this.response = response;
-	}
-	missing(path) {
-		return unexpectedResponse(this.response, `Hiányzik a(z) <${path}> elem a számla XML-ből.`);
-	}
-	element(parent, name, path) {
-		const child = findChild(parent, name);
-		if (!child) throw this.missing(path);
-		return child;
-	}
-	text(parent, name, path) {
-		const value = childText(parent, name);
-		if (value === void 0) throw this.missing(`${path}/${name}`);
-		return value;
-	}
-	number(parent, name, path) {
-		const value = childNumber(parent, name);
-		if (value === void 0) throw this.missing(`${path}/${name}`);
-		return value;
-	}
-};
-function readAddress(element) {
-	if (!element) return void 0;
-	return {
-		name: childText(element, "nev"),
-		country: childText(element, "orszag"),
-		zip: childText(element, "irsz"),
-		city: childText(element, "telepules"),
-		address: childText(element, "cim")
-	};
-}
-function readSeller(root, reader) {
-	const seller = reader.element(root, "szallito", "szallito");
-	const bank = findChild(seller, "bank");
-	return {
-		id: childNumber(seller, "id"),
-		name: reader.text(seller, "nev", "szallito"),
-		address: readAddress(findChild(seller, "cim")),
-		postalAddress: readAddress(findChild(seller, "postacim")),
-		taxNumber: childText(seller, "adoszam"),
-		groupTaxNumber: childText(seller, "csoportazonosito"),
-		euTaxNumber: childText(seller, "adoszameu"),
-		bank: bank && {
-			name: childText(bank, "nev"),
-			accountNumber: childText(bank, "bankszamla")
-		}
-	};
-}
-const DOCUMENT_TYPES_BY_CODE = new Map(Object.entries(INVOICE_DOCUMENT_TYPE_CODES).map(([type, code]) => [code, type]));
-const E_INVOICE_CODES = /* @__PURE__ */ new Set([2, 3]);
-function readHeader(root, reader) {
-	const header = reader.element(root, "alap", "alap");
-	const typeCode = reader.text(header, "tipus", "alap");
-	const appearanceCode = childNumber(header, "eszamla");
-	return {
-		id: childNumber(header, "id"),
-		number: reader.text(header, "szamlaszam", "alap"),
-		economicEventId: childNumber(header, "gazdEsemAzon"),
-		sourceSystem: childNumber(header, "forras"),
-		registrationNumber: childText(header, "iktatoszam"),
-		type: DOCUMENT_TYPES_BY_CODE.get(typeCode) ?? "unknown",
-		typeCode,
-		eInvoice: appearanceCode !== void 0 && E_INVOICE_CODES.has(appearanceCode),
-		appearanceCode,
-		referencedInvoiceNumber: childText(header, "hivszamlaszam"),
-		referencedProformaNumber: childText(header, "hivdijbekszam"),
-		issueDate: reader.text(header, "kelt", "alap"),
-		fulfillmentDate: childText(header, "telj"),
-		dueDate: childText(header, "fizh"),
-		paymentMethod: childText(header, "fizmod"),
-		unifiedPaymentMethod: childText(header, "fizmodunified"),
-		cash: childBoolean(header, "keszpenz"),
-		orderNumber: childText(header, "rendelesszam"),
-		language: childText(header, "nyelv"),
-		currency: childText(header, "devizanem"),
-		exchangeBank: childText(header, "devizabank"),
-		exchangeRate: childNumber(header, "devizaarf"),
-		comment: childText(header, "megjegyzes"),
-		vatType: childText(header, "afatipus"),
-		cashAccounting: childBoolean(header, "penzforg"),
-		kata: childBoolean(header, "kata"),
-		kataLedger: childBoolean(header, "katafokonyv"),
-		email: childText(header, "email"),
-		test: childBoolean(header, "teszt"),
-		reversed: childBoolean(header, "sztornozott")
-	};
-}
-function readBuyerLedger(element) {
-	if (!element) return void 0;
-	return {
-		ledgerAccount: childText(element, "vevo"),
-		buyerId: childText(element, "vevoazon"),
-		bookingDate: childText(element, "datum"),
-		continuousFulfillment: childBoolean(element, "folyamatostelj"),
-		settlementPeriodStart: childText(element, "elszDatTol") ?? childText(element, "elszdattol"),
-		settlementPeriodEnd: childText(element, "elszDatIg") ?? childText(element, "elszdatig")
-	};
-}
-function readBuyer(root, reader) {
-	const buyer = reader.element(root, "vevo", "vevo");
-	return {
-		id: childNumber(buyer, "id"),
-		name: reader.text(buyer, "nev", "vevo"),
-		identifier: childText(buyer, "azonosito"),
-		address: readAddress(findChild(buyer, "cim")),
-		postalAddress: readAddress(findChild(buyer, "postacim")),
-		email: childText(buyer, "email"),
-		taxNumber: childText(buyer, "adoszam"),
-		groupTaxNumber: childText(buyer, "csoportazonosito"),
-		euTaxNumber: childText(buyer, "adoszameu"),
-		location: childNumber(buyer, "lokacio"),
-		privatePerson: childBoolean(buyer, "privatePersonIndicator"),
-		ledger: readBuyerLedger(findChild(buyer, "fokonyv"))
-	};
-}
-function readItemLedger(element) {
-	if (!element) return void 0;
-	return {
-		revenueLedgerAccount: childText(element, "arbevetel"),
-		vatLedgerAccount: childText(element, "afa"),
-		economicEvent: childText(element, "gazdasagiesemeny"),
-		vatEconomicEvent: childText(element, "gazdasagiesemenyafa"),
-		settlementPeriodStart: childText(element, "elszdattol"),
-		settlementPeriodEnd: childText(element, "elszdatig")
-	};
-}
-function readItem(item, reader) {
-	const path = "tetelek/tetel";
-	return {
-		name: reader.text(item, "nev", path),
-		identifier: childText(item, "azonosito"),
-		quantity: reader.number(item, "mennyiseg", path),
-		unit: childText(item, "mennyisegiegyseg"),
-		netUnitPrice: reader.number(item, "nettoegysegar", path),
-		vat: reader.number(item, "afakulcs", path),
-		vatCode: childText(item, "afatipus"),
-		netAmount: reader.number(item, "netto", path),
-		marginVatBase: childNumber(item, "arresafaalap"),
-		vatAmount: reader.number(item, "afa", path),
-		grossAmount: reader.number(item, "brutto", path),
-		comment: childText(item, "megjegyzes"),
-		position: childNumber(item, "sztetordering"),
-		ledger: readItemLedger(findChild(item, "fokonyv"))
-	};
-}
-function readLabels(element) {
-	return findChildren(element, "cimke").flatMap((label) => {
-		const value = label.text.trim();
-		return value === "" ? [] : [value];
-	});
-}
-function readFinancialItem(item, reader) {
-	const path = "qutetek/qutet";
-	return {
-		name: reader.text(item, "nev", path),
-		vat: reader.number(item, "afakulcs", path),
-		vatCode: childText(item, "afatipus"),
-		netAmount: reader.number(item, "netto", path),
-		vatAmount: reader.number(item, "afa", path),
-		grossAmount: reader.number(item, "brutto", path),
-		settlementPeriodStart: childText(item, "elszdattol"),
-		settlementPeriodEnd: childText(item, "elszdatig"),
-		vatDeduction: childNumber(item, "afalevon"),
-		labels: readLabels(findChild(item, "cimkek"))
-	};
-}
-function readTotals(root, reader) {
-	const totals = reader.element(root, "osszegek", "osszegek");
-	const total = reader.element(totals, "totalossz", "osszegek/totalossz");
-	const path = "osszegek/totalossz";
-	return {
-		netAmount: reader.number(total, "netto", path),
-		vatAmount: reader.number(total, "afa", path),
-		grossAmount: reader.number(total, "brutto", path),
-		byVat: findChildren(totals, "afakulcsossz").map((entry) => ({
-			vat: reader.number(entry, "afakulcs", "osszegek/afakulcsossz"),
-			vatCode: childText(entry, "afatipus"),
-			netAmount: reader.number(entry, "netto", "osszegek/afakulcsossz"),
-			vatAmount: reader.number(entry, "afa", "osszegek/afakulcsossz"),
-			grossAmount: reader.number(entry, "brutto", "osszegek/afakulcsossz")
-		}))
-	};
-}
-function readPayment(payment, reader) {
-	const path = "kifizetesek/kifizetes";
-	return {
-		date: reader.text(payment, "datum", path),
-		method: reader.text(payment, "jogcim", path),
-		amount: reader.number(payment, "osszeg", path),
-		comment: childText(payment, "megjegyzes"),
-		bankAccountNumber: childText(payment, "bankszamlaszam"),
-		bankTransactionId: childNumber(payment, "banktranzid"),
-		exchangeRate: childNumber(payment, "devizaarf")
-	};
-}
-function parseInvoiceDetailsXml(root, response) {
-	const reader = new InvoiceReader(response);
-	return {
-		seller: readSeller(root, reader),
-		header: readHeader(root, reader),
-		buyer: readBuyer(root, reader),
-		items: findChildren(findChild(root, "tetelek"), "tetel").map((item) => readItem(item, reader)),
-		financialItems: findChildren(findChild(root, "qutetek"), "qutet").map((item) => readFinancialItem(item, reader)),
-		labels: readLabels(findChild(root, "cimkek")),
-		totals: readTotals(root, reader),
-		payments: findChildren(findChild(root, "kifizetesek"), "kifizetes").map((payment) => readPayment(payment, reader)),
-		pdf: decodeResponsePdf(root, response)
-	};
-}
-function parseGetInvoiceResponse(response) {
-	throwIfHeaderError(response);
-	throwIfTextError(response);
-	throwIfHttpError(response);
-	const root = parseResponseXml(response);
-	throwIfXmlFailure(root, response);
-	if (root.name !== "szamla") throw unexpectedResponse(response, "A számla XML (<szamla>) helyett más válasz érkezett.");
-	return parseInvoiceDetailsXml(root, response);
-}
-async function getInvoice(ctx, reference, query = {}, options = {}) {
-	const xml = buildGetInvoiceXml(ctx.credentials, reference, query);
-	return ctx.execute({
-		action: "getInvoiceXml",
-		xml,
-		signal: options.signal,
-		safeToRetry: true
-	}, parseGetInvoiceResponse);
-}
-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(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(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) {
 	const resolved = resolveInvoiceReference(reference);
@@ -1110,8 +824,8 @@ function buildReverseInvoiceXml(credentials, input) {
 			]),
 			el("fejlec", [
 				el("szamlaszam", invoiceNumber),
-				optionalEl("keltDatum", optionalAgentDate(options.issueDate, "issueDate")),
-				optionalEl("teljesitesDatum", optionalAgentDate(options.fulfillmentDate, "fulfillmentDate")),
+				optionalEl("keltDatum", optionalAgentDate$1(options.issueDate, "issueDate")),
+				optionalEl("teljesitesDatum", optionalAgentDate$1(options.fulfillmentDate, "fulfillmentDate")),
 				optionalEl("megjegyzes", optionalText(options.comment)),
 				el("tipus", "SS"),
 				optionalEl("szamlaSablon", validateTemplate(options.template))
@@ -1455,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) {
@@ -1477,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,
@@ -1490,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,
@@ -1505,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,
@@ -1513,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,
@@ -1530,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,
@@ -1542,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,
@@ -1557,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);
@@ -1593,4 +1384,4 @@ function createKassza(options = {}) {
 	};
 }
 //#endregion
-export { ATTEMPT_LEDGER_KEY_PREFIX as a, createAgentContext as i, queryTaxpayer as n, ATTEMPT_LEDGER_TTL_SECONDS as o, getInvoicePdf as r, attemptLedgerKey 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 };