kassza 0.13.0 → 0.14.0

package/dist/observe/index.cjs

@@ -0,0 +1,311 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_crypto = require("../crypto-Dpn4FHQ6.cjs");
+//#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 require_crypto.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
+exports.DEFAULT_DURATION_BUCKETS_MS = DEFAULT_DURATION_BUCKETS_MS;
+exports.MAX_OPEN_SPANS = MAX_OPEN_SPANS;
+exports.METRIC_HELP = METRIC_HELP;
+exports.SPAN_STATUS_ERROR = SPAN_STATUS_ERROR;
+exports.SPAN_STATUS_OK = SPAN_STATUS_OK;
+exports.combineHooks = combineHooks;
+exports.createMetricsRegistry = createMetricsRegistry;
+exports.observe = observe;

package/dist/observe/index.d.cts

@@ -0,0 +1,53 @@
+import { c as SzamlazzHooks } from "../context-CFNKzStE.cjs";
+//#region src/observe/metrics.d.ts
+type MetricLabels = Readonly<Record<string, string>>;
+interface Metrics {
+  counter(name: string, labels?: MetricLabels, value?: number): void;
+  histogram(name: string, value: number, labels?: MetricLabels): void;
+}
+interface MetricsRegistry extends Metrics {
+  renderPrometheus(): string;
+  reset(): void;
+}
+export declare const DEFAULT_DURATION_BUCKETS_MS: readonly number[];
+export declare const METRIC_HELP: Readonly<Record<string, string>>;
+export declare function createMetricsRegistry(buckets?: readonly number[]): MetricsRegistry;
+//#endregion
+//#region src/observe/observe.d.ts
+type LogMethod = (data: Readonly<Record<string, unknown>>, message: string) => void;
+interface ObserveLogger {
+  readonly debug?: LogMethod | undefined;
+  readonly info?: LogMethod | undefined;
+  readonly warn?: LogMethod | undefined;
+  readonly error?: LogMethod | undefined;
+}
+type SpanAttributeValue = string | number | boolean;
+interface ObserveSpan {
+  setAttribute(key: string, value: SpanAttributeValue): unknown;
+  setStatus(status: {
+    readonly code: number;
+    readonly message?: string;
+  }): unknown;
+  recordException(exception: unknown): unknown;
+  end(): unknown;
+}
+interface ObserveTracer {
+  startSpan(name: string, options?: {
+    readonly attributes?: Readonly<Record<string, SpanAttributeValue>>;
+  }): ObserveSpan;
+}
+interface ObserveOptions {
+  readonly logger?: ObserveLogger | undefined;
+  readonly tracer?: ObserveTracer | undefined;
+  readonly metrics?: Metrics | undefined;
+  readonly redact?: boolean | undefined;
+  readonly orderRefSalt?: string | undefined;
+  readonly logRequests?: boolean | undefined;
+}
+export declare const SPAN_STATUS_OK = 1;
+export declare const SPAN_STATUS_ERROR = 2;
+export declare const MAX_OPEN_SPANS = 1e3;
+export declare function observe(options?: ObserveOptions): SzamlazzHooks;
+export declare function combineHooks(...hooks: readonly (SzamlazzHooks | undefined)[]): SzamlazzHooks;
+//#endregion
+export type { LogMethod, MetricLabels, Metrics, MetricsRegistry, ObserveLogger, ObserveOptions, ObserveSpan, ObserveTracer, SpanAttributeValue };

package/dist/observe/index.d.ts

@@ -0,0 +1,53 @@
+import { c as SzamlazzHooks } from "../context-kb33TgzE.js";
+//#region src/observe/metrics.d.ts
+type MetricLabels = Readonly<Record<string, string>>;
+interface Metrics {
+  counter(name: string, labels?: MetricLabels, value?: number): void;
+  histogram(name: string, value: number, labels?: MetricLabels): void;
+}
+interface MetricsRegistry extends Metrics {
+  renderPrometheus(): string;
+  reset(): void;
+}
+export declare const DEFAULT_DURATION_BUCKETS_MS: readonly number[];
+export declare const METRIC_HELP: Readonly<Record<string, string>>;
+export declare function createMetricsRegistry(buckets?: readonly number[]): MetricsRegistry;
+//#endregion
+//#region src/observe/observe.d.ts
+type LogMethod = (data: Readonly<Record<string, unknown>>, message: string) => void;
+interface ObserveLogger {
+  readonly debug?: LogMethod | undefined;
+  readonly info?: LogMethod | undefined;
+  readonly warn?: LogMethod | undefined;
+  readonly error?: LogMethod | undefined;
+}
+type SpanAttributeValue = string | number | boolean;
+interface ObserveSpan {
+  setAttribute(key: string, value: SpanAttributeValue): unknown;
+  setStatus(status: {
+    readonly code: number;
+    readonly message?: string;
+  }): unknown;
+  recordException(exception: unknown): unknown;
+  end(): unknown;
+}
+interface ObserveTracer {
+  startSpan(name: string, options?: {
+    readonly attributes?: Readonly<Record<string, SpanAttributeValue>>;
+  }): ObserveSpan;
+}
+interface ObserveOptions {
+  readonly logger?: ObserveLogger | undefined;
+  readonly tracer?: ObserveTracer | undefined;
+  readonly metrics?: Metrics | undefined;
+  readonly redact?: boolean | undefined;
+  readonly orderRefSalt?: string | undefined;
+  readonly logRequests?: boolean | undefined;
+}
+export declare const SPAN_STATUS_OK = 1;
+export declare const SPAN_STATUS_ERROR = 2;
+export declare const MAX_OPEN_SPANS = 1e3;
+export declare function observe(options?: ObserveOptions): SzamlazzHooks;
+export declare function combineHooks(...hooks: readonly (SzamlazzHooks | undefined)[]): SzamlazzHooks;
+//#endregion
+export type { LogMethod, MetricLabels, Metrics, MetricsRegistry, ObserveLogger, ObserveOptions, ObserveSpan, ObserveTracer, SpanAttributeValue };