kassza 0.13.0 → 0.14.0

package/dist/{create-once-DgMtKKcG.cjs → create-once-9yxR_Er_.cjs}

@@ -1,9 +1,13 @@
-const require_errors = require("./errors-DxeuTslP.cjs");
+const require_errors = require("./errors-EE96_6D_.cjs");
 const require_binary = require("./binary-B89HM03_.cjs");
+const require_serialize = require("./serialize-CquIsxA-.cjs");
+const require_warnings = require("./warnings-DeIw5RFj.cjs");
+const require_once = require("./once-BN_3B5OF.cjs");
+const require_issue = require("./issue-Bin4tKD_.cjs");
 const require_dates = require("./dates-CPgBodkP.cjs");
 const require_vat = require("./vat-g35srbNG.cjs");
-const require_money = require("./money-BxytJW6f.cjs");
-const require_issue = require("./issue-AGRohSm7.cjs");
+const require_money = require("./money-K9j0wPit.cjs");
+const require_reference = require("./reference-BIdYMK0t.cjs");
 //#region src/core/actions.ts
 const SZAMLAZZ_AGENT_URL = "https://www.szamlazz.hu/szamla/";
 const AGENT_ACTIONS = {
@@ -23,12 +27,47 @@ const AGENT_ACTIONS = {
 const MAX_INVOICE_ATTACHMENTS = 5;
 //#endregion
 //#region src/core/document-events.ts
-async function emitDocumentEvent(hook, event) {
+var DocumentHookError = class extends Error {
+	name = "DocumentHookError";
+	event;
+	constructor(event, cause) {
+		super(`Az onDocument hook hibát dobott a(z) ${event.number} bizonylatnál. A bizonylat elkészült, csak a hook (például a napló mentése) maradt el: mentsd el újra az error.event alapján, és ne állítsd ki újra a bizonylatot.`, { cause });
+		this.event = event;
+	}
+	get number() {
+		return this.event.number;
+	}
+	get document() {
+		return this.event.document;
+	}
+};
+function isDocumentHookError(error) {
+	return error instanceof DocumentHookError;
+}
+function warnDocumentHook(onWarning, event, error) {
+	require_warnings.emitWarning(onWarning, {
+		kind: "document",
+		message: `Az onDocument hook hibát dobott a(z) ${event.number} bizonylatnál. A bizonylat elkészült, a hiba nem érinti.`,
+		error,
+		operation: `${event.kind}.${event.action}`
+	}, "console");
+}
+async function emitDocumentEvent(hook, event, options = {}) {
 	if (!hook) return;
 	try {
 		await hook(event);
 	} catch (error) {
-		console.warn(`[szamlazz] Az onDocument hook hibát dobott a(z) ${event.number} bizonylatnál. A bizonylat elkészült, a hiba nem érinti.`, error);
+		const mode = options.mode ?? "warn";
+		if (mode === "warn") {
+			warnDocumentHook(options.onWarning, event, error);
+			return;
+		}
+		if (mode === "throw") throw new DocumentHookError(event, error);
+		try {
+			await mode(error, event);
+		} catch (handlerError) {
+			throw new DocumentHookError(event, handlerError);
+		}
 	}
 }
 //#endregion
@@ -284,6 +323,176 @@ function resolveInvoice(defaults, input, now) {
 		attachments
 	};
 }
+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_reference.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_reference.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_reference.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_reference.agentDate(payment.date, "date")),
+		require_serialize.el("jogcim", require_reference.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_reference.optionalText(payment.description))
+	]);
+}
+function buildPaymentXml(credentials, request) {
+	const invoiceNumber = require_reference.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_reference.AGENT_XSD_BASE_URL}agentkifiz/xmlszamlakifiz.xsd`,
+		children: [require_serialize.el("beallitasok", [
+			...credentials,
+			require_serialize.el("szamlaszam", invoiceNumber),
+			require_serialize.optionalEl("adoszam", require_reference.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_reference.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/payment-once.ts
+const KEY_PATTERN = /^[A-Za-z0-9_.:-]{1,48}$/;
+function validation(message, hint) {
+	return new require_errors.SzamlazzError(message, {
+		category: "validation",
+		hint
+	});
+}
+function paymentMarker(key) {
+	const trimmed = key?.trim();
+	if (!trimmed || !KEY_PATTERN.test(trimmed)) throw validation(`A registerPaymentOnce kulcsa (key) 1–48 karakter legyen, csak betű, szám és _ . : - jellel, kapott: ${String(key)}`, "Használj rövid, stabil azonosítót, például a banki tranzakció vagy a fizetés azonosítóját.");
+	return `[kassza:${trimmed}]`;
+}
+function matchingPayment(details, marker) {
+	return details.payments.find((payment) => payment.comment?.includes(marker) === true);
+}
+function describe(description, marker) {
+	const text = description?.trim();
+	return text ? `${marker} ${text}` : marker;
+}
+function unreadableMarker(invoiceNumber, marker) {
+	return new require_errors.SzamlazzError(`A(z) ${invoiceNumber} számlán a befizetés rögzült, de a jelölő (${marker}) a számla lekérdezésében nem látszik, így a registerPaymentOnce nem tudja megakadályozni az ismételt rögzítést.`, {
+		category: "unexpected_response",
+		details: {
+			invoiceNumber,
+			marker,
+			registered: "true"
+		},
+		hint: "NE hívd újra ezt a rögzítést: a befizetés már rögzült. Jelezd a kassza hibajegyében; addig a befizetéseket a saját rendszeredben tartsd nyilván, és a registerPayment-et csak egyszer hívd."
+	});
+}
+const QUERY = { includePdf: false };
+async function registerPaymentOnce(api, input, options = {}, guard) {
+	const invoiceNumber = input.invoiceNumber?.trim();
+	if (!invoiceNumber) throw validation("Add meg a számla számát (invoiceNumber).");
+	if (typeof input.amount !== "number" || !Number.isFinite(input.amount) || input.amount === 0) throw validation("A befizetés összege (amount) nullától különböző véges szám legyen.");
+	const marker = paymentMarker(input.key);
+	const key = input.key.trim();
+	const delayMs = require_once.resolveRecoveryDelay(options.recoveryDelayMs);
+	const lookup = async () => {
+		return matchingPayment(await api.get(invoiceNumber, QUERY, options), marker) ?? null;
+	};
+	const base = {
+		invoiceNumber,
+		key,
+		marker
+	};
+	const run = async () => {
+		const existing = await lookup();
+		if (existing) return {
+			...base,
+			created: false,
+			existing
+		};
+		let payment;
+		try {
+			payment = await api.registerPayment({
+				invoiceNumber,
+				taxNumber: input.taxNumber,
+				additive: true,
+				amount: input.amount,
+				method: input.method ?? "átutalás",
+				date: input.date,
+				description: describe(input.description, marker)
+			}, options);
+		} catch (error) {
+			if (!require_once.isUncertainOutcome(error)) throw error;
+			const state = {};
+			const recovered = await require_once.recoverAfterFailure(lookup, delayMs, options.signal, state);
+			if (recovered) return {
+				...base,
+				created: true,
+				existing: recovered
+			};
+			throw require_once.unknownOutcomeError(error, `${invoiceNumber} számla`, {
+				subject: `${key} kulcsú befizetése`,
+				lookupError: state.lookupError,
+				method: "registerPaymentOnce"
+			});
+		}
+		const confirmed = await lookup();
+		if (!confirmed) throw unreadableMarker(invoiceNumber, marker);
+		return {
+			...base,
+			created: true,
+			payment,
+			existing: confirmed
+		};
+	};
+	return require_issue.guardOnce(guard, `payment:${JSON.stringify([invoiceNumber, key])}`, options, run, (result) => ({
+		...result,
+		created: false
+	}));
+}
 //#endregion
 //#region src/receipts/create-once.ts
 function requireOrderNumber(input) {
@@ -291,40 +500,47 @@ function requireOrderNumber(input) {
 	if (!orderNumber) throw new require_errors.SzamlazzError("A createOnce-hoz add meg a rendelésszámot (orderNumber), ez azonosítja a nyugtát.", { category: "validation" });
 	return orderNumber;
 }
-async function createReceiptOnce(api, input, options = {}) {
+async function createReceiptOnce(api, input, options = {}, guard) {
 	const orderNumber = requireOrderNumber(input);
 	const callId = input.callId?.trim() || orderNumber;
-	const delayMs = require_issue.resolveRecoveryDelay(options.recoveryDelayMs);
+	const delayMs = require_once.resolveRecoveryDelay(options.recoveryDelayMs);
 	const lookup = () => api.find({
 		orderNumber,
 		downloadPdf: input.downloadPdf
 	}, options);
-	if (options.lookupFirst !== false) {
-		const existing = await lookup();
-		if (existing) return {
-			receipt: existing,
-			created: false
-		};
-	}
-	try {
-		return {
-			receipt: await api.create({
-				...input,
-				orderNumber,
-				callId
-			}, options),
-			created: true
-		};
-	} catch (error) {
-		if (!require_issue.isUncertainOutcome(error)) throw error;
-		const recovered = await require_issue.recoverAfterFailure(lookup, delayMs, options.signal);
-		if (recovered) return {
-			receipt: recovered,
-			created: error.category !== "duplicate"
-		};
-		if (error.category === "duplicate") throw error;
-		throw require_issue.unknownOutcomeError(error, `${orderNumber} rendelés`);
-	}
+	const run = async (recheck) => {
+		if (recheck || options.lookupFirst !== false) {
+			const existing = await lookup();
+			if (existing) return {
+				receipt: existing,
+				created: false
+			};
+		}
+		try {
+			return {
+				receipt: await api.create({
+					...input,
+					orderNumber,
+					callId
+				}, options),
+				created: true
+			};
+		} catch (error) {
+			if (!require_once.isUncertainOutcome(error)) throw error;
+			const state = {};
+			const recovered = await require_once.recoverAfterFailure(lookup, delayMs, options.signal, state);
+			if (recovered) return {
+				receipt: recovered,
+				created: error.category !== "duplicate"
+			};
+			if (error.category === "duplicate" && !state.lookupError) throw error;
+			throw require_once.unknownOutcomeError(error, `${orderNumber} rendelés`, { lookupError: state.lookupError });
+		}
+	};
+	return require_issue.guardOnce(guard, `receipt:order:${orderNumber}`, options, run, (result) => ({
+		...result,
+		created: false
+	}));
 }
 //#endregion
 Object.defineProperty(exports, "AGENT_ACTIONS", {
@@ -333,6 +549,12 @@ Object.defineProperty(exports, "AGENT_ACTIONS", {
 		return AGENT_ACTIONS;
 	}
 });
+Object.defineProperty(exports, "DocumentHookError", {
+	enumerable: true,
+	get: function() {
+		return DocumentHookError;
+	}
+});
 Object.defineProperty(exports, "INVOICE_LANGUAGES", {
 	enumerable: true,
 	get: function() {
@@ -363,6 +585,12 @@ Object.defineProperty(exports, "TAXPAYER_TYPE_CODES", {
 		return TAXPAYER_TYPE_CODES;
 	}
 });
+Object.defineProperty(exports, "clearPayments", {
+	enumerable: true,
+	get: function() {
+		return clearPayments;
+	}
+});
 Object.defineProperty(exports, "createReceiptOnce", {
 	enumerable: true,
 	get: function() {
@@ -375,18 +603,42 @@ Object.defineProperty(exports, "emitDocumentEvent", {
 		return emitDocumentEvent;
 	}
 });
+Object.defineProperty(exports, "isDocumentHookError", {
+	enumerable: true,
+	get: function() {
+		return isDocumentHookError;
+	}
+});
 Object.defineProperty(exports, "optionalAgentDate", {
 	enumerable: true,
 	get: function() {
 		return optionalAgentDate;
 	}
 });
+Object.defineProperty(exports, "paymentMarker", {
+	enumerable: true,
+	get: function() {
+		return paymentMarker;
+	}
+});
 Object.defineProperty(exports, "presentText", {
 	enumerable: true,
 	get: function() {
 		return presentText;
 	}
 });
+Object.defineProperty(exports, "registerPayment", {
+	enumerable: true,
+	get: function() {
+		return registerPayment;
+	}
+});
+Object.defineProperty(exports, "registerPaymentOnce", {
+	enumerable: true,
+	get: function() {
+		return registerPaymentOnce;
+	}
+});
 Object.defineProperty(exports, "resolveInvoice", {
 	enumerable: true,
 	get: function() {

package/dist/create-once-Bh6fOWkW.d.cts

@@ -0,0 +1,20 @@
+import { G as InvoiceType, N as CreatedInvoice } from "./context-CFNKzStE.cjs";
+import { r as Receipt } from "./types-lnKkQdot.cjs";
+import { n as InvoiceDetails } from "./get-Byc9T5WO.cjs";
+//#region src/invoices/create-once.d.ts
+interface InvoiceOnceResult {
+  readonly number: string;
+  readonly created: boolean;
+  readonly externalId: string;
+  readonly invoice?: CreatedInvoice | undefined;
+  readonly details?: InvoiceDetails | undefined;
+}
+declare function invoiceOnceExternalId(type: InvoiceType, orderNumber: string): string;
+//#endregion
+//#region src/receipts/create-once.d.ts
+interface ReceiptOnceResult {
+  readonly receipt: Receipt;
+  readonly created: boolean;
+}
+//#endregion
+export { InvoiceOnceResult as n, invoiceOnceExternalId as r, ReceiptOnceResult as t };