kassza 0.12.0 → 0.14.0

package/dist/observe/index.js

@@ -0,0 +1,303 @@
+import { i as hmacHex } from "../crypto-usDg8L2K.js";
+//#region src/observe/metrics.ts
+const DEFAULT_DURATION_BUCKETS_MS = [
+	50,
+	100,
+	250,
+	500,
+	1e3,
+	2500,
+	5e3,
+	1e4,
+	3e4,
+	6e4
+];
+const METRIC_HELP = {
+	kassza_requests_total: "Számla Agent próbálkozások száma kimenet szerint",
+	kassza_request_duration_ms: "Számla Agent próbálkozások időtartama ezredmásodpercben",
+	kassza_retries_total: "Automatikus újrapróbálások száma",
+	kassza_maintenance_total: "Karbantartás (1-es hiba) miatt elbukott kérések",
+	kassza_unexpected_response_total: "Ismeretlen formátumú Számlázz.hu válaszok",
+	kassza_store_errors_total: "Tároló (session, napló, zár, gyorsítótár) hibái",
+	kassza_warnings_total: "Figyelmeztetések fajta szerint",
+	kassza_documents_total: "Kiállított bizonylatok fajta és művelet szerint"
+};
+const NAME_PATTERN = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+const LABEL_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function escapeLabel(value) {
+	return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
+}
+function labelKey(labels) {
+	const entries = Object.entries(labels ?? {}).sort(([a], [b]) => a.localeCompare(b));
+	for (const [name] of entries) if (!LABEL_PATTERN.test(name)) throw new TypeError(`Érvénytelen metrika-címke: ${name}`);
+	return entries.map(([name, value]) => `${name}="${escapeLabel(value)}"`).join(",");
+}
+function assertName(name) {
+	if (!NAME_PATTERN.test(name)) throw new TypeError(`Érvénytelen metrikanév: ${name}`);
+}
+function series(name, key, extra) {
+	const labels = [key, extra].filter(Boolean).join(",");
+	return labels ? `${name}{${labels}}` : name;
+}
+function formatNumber(value) {
+	if (value === Number.POSITIVE_INFINITY) return "+Inf";
+	return String(value);
+}
+function createMetricsRegistry(buckets = DEFAULT_DURATION_BUCKETS_MS) {
+	const sorted = [...buckets].sort((a, b) => a - b);
+	if (sorted.some((bucket) => !Number.isFinite(bucket))) throw new TypeError("A hisztogram határai véges számok legyenek.");
+	const counters = /* @__PURE__ */ new Map();
+	const histograms = /* @__PURE__ */ new Map();
+	return {
+		counter(name, labels, value = 1) {
+			assertName(name);
+			if (!Number.isFinite(value) || value < 0) throw new TypeError(`A számláló csak nemnegatív értékkel nőhet, kapott: ${value}`);
+			const byLabels = counters.get(name) ?? /* @__PURE__ */ new Map();
+			const key = labelKey(labels);
+			byLabels.set(key, (byLabels.get(key) ?? 0) + value);
+			counters.set(name, byLabels);
+		},
+		histogram(name, value, labels) {
+			assertName(name);
+			if (!Number.isFinite(value)) throw new TypeError(`A hisztogram értéke véges szám legyen.`);
+			const byLabels = histograms.get(name) ?? /* @__PURE__ */ new Map();
+			const key = labelKey(labels);
+			const histogram = byLabels.get(key) ?? {
+				buckets: sorted.map(() => 0),
+				sum: 0,
+				count: 0
+			};
+			sorted.forEach((bound, index) => {
+				if (value <= bound) histogram.buckets[index] = (histogram.buckets[index] ?? 0) + 1;
+			});
+			histogram.sum += value;
+			histogram.count += 1;
+			byLabels.set(key, histogram);
+			histograms.set(name, byLabels);
+		},
+		renderPrometheus() {
+			const lines = [];
+			for (const name of [...counters.keys()].sort()) {
+				const help = METRIC_HELP[name];
+				if (help) lines.push(`# HELP ${name} ${help}`);
+				lines.push(`# TYPE ${name} counter`);
+				for (const [key, value] of [...counters.get(name) ?? []].sort()) lines.push(`${series(name, key)} ${formatNumber(value)}`);
+			}
+			for (const name of [...histograms.keys()].sort()) {
+				const help = METRIC_HELP[name];
+				if (help) lines.push(`# HELP ${name} ${help}`);
+				lines.push(`# TYPE ${name} histogram`);
+				for (const [key, histogram] of [...histograms.get(name) ?? []].sort()) {
+					sorted.forEach((bound, index) => {
+						lines.push(`${series(`${name}_bucket`, key, `le="${formatNumber(bound)}"`)} ${histogram.buckets[index] ?? 0}`);
+					});
+					lines.push(`${series(`${name}_bucket`, key, "le=\"+Inf\"")} ${histogram.count}`);
+					lines.push(`${series(`${name}_sum`, key)} ${formatNumber(histogram.sum)}`);
+					lines.push(`${series(`${name}_count`, key)} ${histogram.count}`);
+				}
+			}
+			return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+		},
+		reset() {
+			counters.clear();
+			histograms.clear();
+		}
+	};
+}
+//#endregion
+//#region src/observe/observe.ts
+const SPAN_STATUS_OK = 1;
+const SPAN_STATUS_ERROR = 2;
+const MAX_OPEN_SPANS = 1e3;
+const STORE_WARNINGS = /* @__PURE__ */ new Set([
+	"session",
+	"ledger",
+	"lock",
+	"dedupe",
+	"cache"
+]);
+function randomSalt() {
+	return Array.from(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function safely(run) {
+	try {
+		run();
+	} catch {
+		return;
+	}
+}
+function orderNumberOf(event) {
+	if (event.kind === "receipt") return event.document.orderNumber;
+	if (event.action === "created") return event.input.orderNumber?.trim() || void 0;
+}
+function spanKey(event) {
+	return `${event.requestId}:${event.attempt}`;
+}
+function observe(options = {}) {
+	const { logger, tracer, metrics } = options;
+	const redact = options.redact !== false;
+	const salt = options.orderRefSalt ?? randomSalt();
+	const spans = /* @__PURE__ */ new Map();
+	async function orderRef(orderNumber) {
+		if (orderNumber === void 0) return void 0;
+		if (!redact) return orderNumber;
+		return `hmac:${(await hmacHex("SHA-256", salt, orderNumber)).slice(0, 16)}`;
+	}
+	const onRequest = (event) => {
+		if (tracer) safely(() => {
+			if (spans.size >= 1e3) {
+				const oldest = spans.keys().next().value;
+				if (oldest !== void 0) {
+					spans.get(oldest)?.end();
+					spans.delete(oldest);
+				}
+			}
+			spans.set(spanKey(event), tracer.startSpan(`kassza ${event.action}`, { attributes: {
+				"kassza.action": event.action,
+				"kassza.attempt": event.attempt,
+				"kassza.request_id": event.requestId
+			} }));
+		});
+		if (options.logRequests === true) safely(() => logger?.debug?.({
+			event: "kassza.request.start",
+			...event
+		}, `kassza: ${event.action} kérés indul`));
+	};
+	const onResponse = (event) => {
+		const span = spans.get(spanKey(event));
+		if (!span) return;
+		safely(() => {
+			span.setAttribute("http.status_code", event.status);
+			span.setAttribute("kassza.response_bytes", event.responseBytes);
+			span.setAttribute("kassza.session_reused", event.sessionReused);
+		});
+	};
+	const onComplete = (event) => {
+		const key = spanKey(event);
+		const span = spans.get(key);
+		spans.delete(key);
+		const category = event.error?.category;
+		const code = event.error?.code;
+		if (span) safely(() => {
+			if (category) span.setAttribute("kassza.error.category", category);
+			if (code !== void 0) span.setAttribute("kassza.error.code", code);
+			if (event.error) {
+				span.recordException(event.error);
+				span.setStatus({
+					code: 2,
+					message: event.error.message
+				});
+			} else if (event.outcome === "error") span.setStatus({ code: 2 });
+			else span.setStatus({ code: 1 });
+			span.end();
+		});
+		if (metrics) safely(() => {
+			metrics.counter("kassza_requests_total", {
+				action: event.action,
+				outcome: event.outcome === "success" ? "success" : category ?? "error"
+			});
+			metrics.histogram("kassza_request_duration_ms", event.durationMs, { action: event.action });
+			if (event.willRetry) metrics.counter("kassza_retries_total", { action: event.action });
+			if (category === "maintenance") metrics.counter("kassza_maintenance_total");
+			if (category === "unexpected_response") metrics.counter("kassza_unexpected_response_total", { action: event.action });
+		});
+		const data = {
+			event: "kassza.request",
+			action: event.action,
+			attempt: event.attempt,
+			requestId: event.requestId,
+			outcome: event.outcome,
+			durationMs: event.durationMs,
+			willRetry: event.willRetry,
+			...category ? { errorCategory: category } : {},
+			...code === void 0 ? {} : { errorCode: code }
+		};
+		safely(() => {
+			if (event.outcome === "success") logger?.info?.(data, `kassza: ${event.action} sikeres (${event.durationMs} ms)`);
+			else logger?.warn?.(data, `kassza: ${event.action} sikertelen${category ? ` (${category})` : ""}${event.willRetry ? ", újrapróbálás" : ""}`);
+		});
+	};
+	const onWarning = (warning) => {
+		safely(() => {
+			metrics?.counter("kassza_warnings_total", { kind: warning.kind });
+			if (STORE_WARNINGS.has(warning.kind)) metrics?.counter("kassza_store_errors_total", { store: warning.kind });
+		});
+		safely(() => logger?.warn?.({
+			event: "kassza.warning",
+			kind: warning.kind,
+			...warning.action ? { action: warning.action } : {},
+			...warning.operation ? { operation: warning.operation } : {},
+			error: warning.error instanceof Error ? warning.error.message : String(warning.error)
+		}, warning.message));
+	};
+	const onDocument = async (event) => {
+		safely(() => metrics?.counter("kassza_documents_total", {
+			kind: event.kind,
+			action: event.action
+		}));
+		if (!logger?.info) return;
+		try {
+			const ref = await orderRef(orderNumberOf(event));
+			logger.info({
+				event: "kassza.document",
+				kind: event.kind,
+				action: event.action,
+				number: event.number,
+				...ref === void 0 ? {} : { orderRef: ref }
+			}, `kassza: ${event.kind} ${event.action} ${event.number}`);
+		} catch {
+			return;
+		}
+	};
+	return {
+		onRequest,
+		onResponse,
+		onComplete,
+		onWarning,
+		onDocument
+	};
+}
+const SYNC_HOOKS = [
+	"onRequest",
+	"onResponse",
+	"onError",
+	"onComplete",
+	"onWarning"
+];
+function combineSync(hooks, name) {
+	const handlers = hooks.map((hook) => hook[name]).filter((handler) => handler !== void 0);
+	if (handlers.length === 0) return void 0;
+	return (event) => {
+		let failure;
+		for (const handler of handlers) try {
+			const result = handler(event);
+			if (result instanceof Promise) result.catch(() => void 0);
+		} catch (error) {
+			failure ??= { error };
+		}
+		if (failure) throw failure.error;
+	};
+}
+function combineHooks(...hooks) {
+	const present = hooks.filter((hook) => hook !== void 0);
+	const combined = {};
+	for (const name of SYNC_HOOKS) {
+		const handler = combineSync(present, name);
+		if (handler) combined[name] = handler;
+	}
+	const documentHooks = present.map((hook) => hook.onDocument).filter((hook) => hook !== void 0);
+	if (documentHooks.length > 0) combined.onDocument = async (event) => {
+		let failure;
+		for (const hook of documentHooks) try {
+			await hook(event);
+		} catch (error) {
+			failure ??= { error };
+		}
+		if (failure) throw failure.error;
+	};
+	const mode = present.map((hook) => hook.onDocumentError).findLast((value) => value !== void 0);
+	if (mode !== void 0) combined.onDocumentError = mode;
+	return combined;
+}
+//#endregion
+export { DEFAULT_DURATION_BUCKETS_MS, MAX_OPEN_SPANS, METRIC_HELP, SPAN_STATUS_ERROR, SPAN_STATUS_OK, combineHooks, createMetricsRegistry, observe };

package/dist/once-BN_3B5OF.cjs

@@ -0,0 +1,103 @@
+const require_errors = require("./errors-EE96_6D_.cjs");
+//#region src/core/once.ts
+const DEFAULT_RECOVERY_DELAY_MS = 1e3;
+const UNCERTAIN_CATEGORIES = /* @__PURE__ */ new Set([
+	"network",
+	"timeout",
+	"partial_success",
+	"duplicate",
+	"unexpected_response",
+	"unknown"
+]);
+function isUncertainOutcome(error) {
+	return error instanceof require_errors.SzamlazzError && UNCERTAIN_CATEGORIES.has(error.category);
+}
+function resolveRecoveryDelay(value) {
+	if (value === void 0) return DEFAULT_RECOVERY_DELAY_MS;
+	if (!Number.isFinite(value) || value < 0) throw new require_errors.SzamlazzError(`A recoveryDelayMs értéke nemnegatív szám legyen, kapott: ${value}`, { category: "configuration" });
+	return value;
+}
+function wait(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+async function recoverAfterFailure(lookup, delayMs, signal, state = {}) {
+	for (let attempt = 1; attempt <= 2; attempt++) {
+		await wait(delayMs * attempt, signal);
+		let found;
+		try {
+			found = await lookup();
+		} catch (error) {
+			if (!(error instanceof require_errors.SzamlazzError)) throw error;
+			state.lookupError = error;
+			if (!error.retryable) return null;
+			found = void 0;
+		}
+		if (found) return found;
+	}
+	return null;
+}
+function unknownOutcomeError(error, reference, options = {}) {
+	const lookupError = options.lookupError;
+	const lookupNote = lookupError ? ` A visszakeresés is hibát adott (${lookupError.category}: ${lookupError.message}), ezt előbb hárítsd el.` : "";
+	return new require_errors.SzamlazzError(error.message, {
+		category: error.category,
+		code: error.code,
+		action: error.action,
+		httpStatus: error.httpStatus,
+		rawResponse: error.rawResponse,
+		details: {
+			...error.details,
+			outcome: "unknown",
+			reference,
+			...lookupError ? { lookupError: `${lookupError.category}: ${lookupError.message}` } : {}
+		},
+		hint: `Nem tudni biztosan, hogy a(z) ${reference} ${options.subject ?? "bizonylata"} elkészült-e, és a visszakeresés sem találta meg.${lookupNote} Ne állítsd ki kézzel újra: később hívd meg ugyanígy a ${options.method ?? "createOnce"}-t, az előbb visszakeres.`,
+		cause: error
+	});
+}
+//#endregion
+Object.defineProperty(exports, "DEFAULT_RECOVERY_DELAY_MS", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_RECOVERY_DELAY_MS;
+	}
+});
+Object.defineProperty(exports, "isUncertainOutcome", {
+	enumerable: true,
+	get: function() {
+		return isUncertainOutcome;
+	}
+});
+Object.defineProperty(exports, "recoverAfterFailure", {
+	enumerable: true,
+	get: function() {
+		return recoverAfterFailure;
+	}
+});
+Object.defineProperty(exports, "resolveRecoveryDelay", {
+	enumerable: true,
+	get: function() {
+		return resolveRecoveryDelay;
+	}
+});
+Object.defineProperty(exports, "unknownOutcomeError", {
+	enumerable: true,
+	get: function() {
+		return unknownOutcomeError;
+	}
+});

package/dist/once-CqqZxsXG.js

@@ -0,0 +1,74 @@
+import { r as SzamlazzError } from "./errors-DtN4g5Z9.js";
+//#region src/core/once.ts
+const DEFAULT_RECOVERY_DELAY_MS = 1e3;
+const UNCERTAIN_CATEGORIES = /* @__PURE__ */ new Set([
+	"network",
+	"timeout",
+	"partial_success",
+	"duplicate",
+	"unexpected_response",
+	"unknown"
+]);
+function isUncertainOutcome(error) {
+	return error instanceof SzamlazzError && UNCERTAIN_CATEGORIES.has(error.category);
+}
+function resolveRecoveryDelay(value) {
+	if (value === void 0) return DEFAULT_RECOVERY_DELAY_MS;
+	if (!Number.isFinite(value) || value < 0) throw new SzamlazzError(`A recoveryDelayMs értéke nemnegatív szám legyen, kapott: ${value}`, { category: "configuration" });
+	return value;
+}
+function wait(ms, signal) {
+	if (ms <= 0) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason);
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+async function recoverAfterFailure(lookup, delayMs, signal, state = {}) {
+	for (let attempt = 1; attempt <= 2; attempt++) {
+		await wait(delayMs * attempt, signal);
+		let found;
+		try {
+			found = await lookup();
+		} catch (error) {
+			if (!(error instanceof SzamlazzError)) throw error;
+			state.lookupError = error;
+			if (!error.retryable) return null;
+			found = void 0;
+		}
+		if (found) return found;
+	}
+	return null;
+}
+function unknownOutcomeError(error, reference, options = {}) {
+	const lookupError = options.lookupError;
+	const lookupNote = lookupError ? ` A visszakeresés is hibát adott (${lookupError.category}: ${lookupError.message}), ezt előbb hárítsd el.` : "";
+	return new SzamlazzError(error.message, {
+		category: error.category,
+		code: error.code,
+		action: error.action,
+		httpStatus: error.httpStatus,
+		rawResponse: error.rawResponse,
+		details: {
+			...error.details,
+			outcome: "unknown",
+			reference,
+			...lookupError ? { lookupError: `${lookupError.category}: ${lookupError.message}` } : {}
+		},
+		hint: `Nem tudni biztosan, hogy a(z) ${reference} ${options.subject ?? "bizonylata"} elkészült-e, és a visszakeresés sem találta meg.${lookupNote} Ne állítsd ki kézzel újra: később hívd meg ugyanígy a ${options.method ?? "createOnce"}-t, az előbb visszakeres.`,
+		cause: error
+	});
+}
+//#endregion
+export { unknownOutcomeError as a, resolveRecoveryDelay as i, isUncertainOutcome as n, recoverAfterFailure as r, DEFAULT_RECOVERY_DELAY_MS as t };