@techstream/quark-core 1.1.0

package/src/email.test.js

@@ -0,0 +1,259 @@
+import assert from "node:assert";
+import { mock, test } from "node:test";
+import { createEmailService } from "./email.js";
+
+test("Email Service", async (t) => {
+	await t.test("createEmailService returns object with sendEmail method", () => {
+		const service = createEmailService();
+		assert.strictEqual(typeof service, "object");
+		assert.strictEqual(typeof service.sendEmail, "function");
+	});
+
+	await t.test("SMTP provider: uses Mailhog defaults when no SMTP_HOST set", async () => {
+		// Clear any explicit SMTP env vars
+		const origHost = process.env.SMTP_HOST;
+		const origPort = process.env.SMTP_PORT;
+		delete process.env.SMTP_HOST;
+		delete process.env.SMTP_PORT;
+
+		try {
+			const service = createEmailService({ provider: "smtp" });
+
+			// Mock nodemailer at the transport level
+			let capturedConfig = null;
+			const mockTransport = {
+				sendMail: async (opts) => {
+					return { messageId: "test-id-123", ...opts };
+				},
+			};
+
+			// We test that sendEmail resolves without error
+			// The transport is lazily created, so sendEmail triggers creation
+			// We can't easily intercept the dynamic import, but we can verify
+			// the service was created correctly
+			assert.strictEqual(typeof service.sendEmail, "function");
+		} finally {
+			if (origHost !== undefined) process.env.SMTP_HOST = origHost;
+			else delete process.env.SMTP_HOST;
+			if (origPort !== undefined) process.env.SMTP_PORT = origPort;
+			else delete process.env.SMTP_PORT;
+		}
+	});
+
+	await t.test("SMTP provider: uses explicit SMTP_HOST/SMTP_PORT when set", () => {
+		const origHost = process.env.SMTP_HOST;
+		const origPort = process.env.SMTP_PORT;
+		process.env.SMTP_HOST = "mail.example.com";
+		process.env.SMTP_PORT = "587";
+
+		try {
+			const service = createEmailService({ provider: "smtp" });
+			assert.strictEqual(typeof service.sendEmail, "function");
+		} finally {
+			if (origHost !== undefined) process.env.SMTP_HOST = origHost;
+			else delete process.env.SMTP_HOST;
+			if (origPort !== undefined) process.env.SMTP_PORT = origPort;
+			else delete process.env.SMTP_PORT;
+		}
+	});
+
+	await t.test("Resend provider: throws if RESEND_API_KEY missing", async () => {
+		const origKey = process.env.RESEND_API_KEY;
+		delete process.env.RESEND_API_KEY;
+
+		try {
+			const service = createEmailService({ provider: "resend" });
+
+			await assert.rejects(
+				() => service.sendEmail("test@example.com", "Subject", "<p>body</p>"),
+				(err) =>
+					err instanceof Error &&
+					/RESEND_API_KEY/.test(err.message),
+			);
+		} finally {
+			if (origKey !== undefined) process.env.RESEND_API_KEY = origKey;
+			else delete process.env.RESEND_API_KEY;
+		}
+	});
+
+	await t.test("Resend provider: calls fetch with correct URL, headers, and body", async () => {
+		const origKey = process.env.RESEND_API_KEY;
+		process.env.RESEND_API_KEY = "re_test_key_123";
+
+		// Mock global fetch
+		const originalFetch = globalThis.fetch;
+		let capturedUrl = null;
+		let capturedOptions = null;
+
+		globalThis.fetch = async (url, opts) => {
+			capturedUrl = url;
+			capturedOptions = opts;
+			return {
+				ok: true,
+				json: async () => ({ id: "resend-msg-id" }),
+			};
+		};
+
+		try {
+			const service = createEmailService({
+				provider: "resend",
+				from: "Test <test@example.com>",
+			});
+
+			const result = await service.sendEmail(
+				"recipient@example.com",
+				"Test Subject",
+				"<p>Hello</p>",
+				"Hello",
+			);
+
+			assert.strictEqual(capturedUrl, "https://api.resend.com/emails");
+			assert.strictEqual(capturedOptions.method, "POST");
+
+			const headers = capturedOptions.headers;
+			assert.strictEqual(headers.Authorization, "Bearer re_test_key_123");
+			assert.strictEqual(headers["Content-Type"], "application/json");
+
+			const body = JSON.parse(capturedOptions.body);
+			assert.strictEqual(body.from, "Test <test@example.com>");
+			assert.deepStrictEqual(body.to, ["recipient@example.com"]);
+			assert.strictEqual(body.subject, "Test Subject");
+			assert.strictEqual(body.html, "<p>Hello</p>");
+			assert.strictEqual(body.text, "Hello");
+
+			assert.strictEqual(result.id, "resend-msg-id");
+		} finally {
+			globalThis.fetch = originalFetch;
+			if (origKey !== undefined) process.env.RESEND_API_KEY = origKey;
+			else delete process.env.RESEND_API_KEY;
+		}
+	});
+
+	await t.test("Resend provider: throws on non-ok response", async () => {
+		const origKey = process.env.RESEND_API_KEY;
+		process.env.RESEND_API_KEY = "re_test_key_123";
+
+		const originalFetch = globalThis.fetch;
+		globalThis.fetch = async () => ({
+			ok: false,
+			statusText: "Unprocessable Entity",
+			json: async () => ({ message: "Invalid email address" }),
+		});
+
+		try {
+			const service = createEmailService({ provider: "resend" });
+
+			await assert.rejects(
+				() => service.sendEmail("bad@", "Subject", "<p>body</p>"),
+				(err) =>
+					err instanceof Error &&
+					/Resend API error/.test(err.message) &&
+					/Invalid email address/.test(err.message),
+			);
+		} finally {
+			globalThis.fetch = originalFetch;
+			if (origKey !== undefined) process.env.RESEND_API_KEY = origKey;
+			else delete process.env.RESEND_API_KEY;
+		}
+	});
+
+	await t.test("Resend provider: handles non-JSON error response", async () => {
+		const origKey = process.env.RESEND_API_KEY;
+		process.env.RESEND_API_KEY = "re_test_key_123";
+
+		const originalFetch = globalThis.fetch;
+		globalThis.fetch = async () => ({
+			ok: false,
+			statusText: "Internal Server Error",
+			json: async () => {
+				throw new Error("not json");
+			},
+		});
+
+		try {
+			const service = createEmailService({ provider: "resend" });
+
+			await assert.rejects(
+				() => service.sendEmail("test@example.com", "Subject", "<p>body</p>"),
+				(err) =>
+					err instanceof Error &&
+					/Resend API error/.test(err.message) &&
+					/Internal Server Error/.test(err.message),
+			);
+		} finally {
+			globalThis.fetch = originalFetch;
+			if (origKey !== undefined) process.env.RESEND_API_KEY = origKey;
+			else delete process.env.RESEND_API_KEY;
+		}
+	});
+
+	await t.test("default provider is smtp", () => {
+		const origProvider = process.env.EMAIL_PROVIDER;
+		delete process.env.EMAIL_PROVIDER;
+
+		try {
+			const service = createEmailService();
+			// The service should be created without error (defaults to smtp)
+			assert.strictEqual(typeof service.sendEmail, "function");
+		} finally {
+			if (origProvider !== undefined)
+				process.env.EMAIL_PROVIDER = origProvider;
+			else delete process.env.EMAIL_PROVIDER;
+		}
+	});
+
+	await t.test("respects options.from override", async () => {
+		const origKey = process.env.RESEND_API_KEY;
+		process.env.RESEND_API_KEY = "re_test_key_123";
+
+		const originalFetch = globalThis.fetch;
+		let capturedBody = null;
+
+		globalThis.fetch = async (url, opts) => {
+			capturedBody = JSON.parse(opts.body);
+			return { ok: true, json: async () => ({ id: "msg-1" }) };
+		};
+
+		try {
+			const service = createEmailService({
+				provider: "resend",
+				from: "Custom <custom@example.com>",
+			});
+
+			await service.sendEmail("to@example.com", "Sub", "<p>Hi</p>");
+			assert.strictEqual(capturedBody.from, "Custom <custom@example.com>");
+		} finally {
+			globalThis.fetch = originalFetch;
+			if (origKey !== undefined) process.env.RESEND_API_KEY = origKey;
+			else delete process.env.RESEND_API_KEY;
+		}
+	});
+
+	await t.test("input validation: rejects empty 'to'", async () => {
+		const service = createEmailService();
+		await assert.rejects(
+			() => service.sendEmail("", "Subject", "<p>body</p>"),
+			(err) => err instanceof Error && /to/.test(err.message),
+		);
+		await assert.rejects(
+			() => service.sendEmail(null, "Subject", "<p>body</p>"),
+			(err) => err instanceof Error && /to/.test(err.message),
+		);
+	});
+
+	await t.test("input validation: rejects empty 'subject'", async () => {
+		const service = createEmailService();
+		await assert.rejects(
+			() => service.sendEmail("a@b.com", "", "<p>body</p>"),
+			(err) => err instanceof Error && /subject/.test(err.message),
+		);
+	});
+
+	await t.test("input validation: rejects empty 'html'", async () => {
+		const service = createEmailService();
+		await assert.rejects(
+			() => service.sendEmail("a@b.com", "Subject", ""),
+			(err) => err instanceof Error && /html/.test(err.message),
+		);
+	});
+});

package/src/error-reporter.js

@@ -0,0 +1,266 @@
+/**
+ * @techstream/quark-core - Error Reporter Module
+ * Adapter/hook system for pluggable error reporting
+ */
+
+import { normalizeError } from "./errors.js";
+import { logger } from "./logger.js";
+
+const MAX_BREADCRUMBS = 50;
+
+/**
+ * @typedef {Object} ErrorAdapter
+ * @property {string} name - Unique adapter identifier
+ * @property {(error: Error, context: Object) => void} report - Called when an error is reported
+ * @property {(message: string, level: string, context: Object) => void} [captureMessage] - For non-error events
+ * @property {(user: Object) => void} [setUser] - Sets user context
+ * @property {(message: string, category: string, data: Object) => void} [addBreadcrumb] - Adds a breadcrumb
+ */
+
+/**
+ * @typedef {Object} Breadcrumb
+ * @property {string} message - Breadcrumb message
+ * @property {string} category - Breadcrumb category
+ * @property {Object} data - Associated data
+ * @property {string} timestamp - ISO timestamp
+ */
+
+/**
+ * Built-in adapter that logs errors via the Quark logger.
+ * @type {ErrorAdapter}
+ */
+export const consoleAdapter = {
+	name: "console",
+
+	report(error, context) {
+		const appError = normalizeError(error);
+		logger.error(appError.message, {
+			error: appError.toJSON(),
+			context,
+			stack: error.stack,
+		});
+	},
+
+	captureMessage(message, level = "info", context = {}) {
+		const logFn = logger[level] || logger.info;
+		logFn.call(logger, message, context);
+	},
+
+	setUser(_user) {
+		// Console adapter does not persist user context
+	},
+
+	addBreadcrumb(_message, _category, _data) {
+		// Console adapter does not store breadcrumbs
+	},
+};
+
+/**
+ * Error reporter with adapter registration.
+ * Distributes error reports to all registered adapters.
+ */
+export class ErrorReporter {
+	/** @type {ErrorAdapter[]} */
+	#adapters = [];
+
+	/** @type {Breadcrumb[]} */
+	#breadcrumbs = [];
+
+	/** @type {Object|null} */
+	#user = null;
+
+	constructor() {
+		this.#adapters = [consoleAdapter];
+		this.#breadcrumbs = [];
+		this.#user = null;
+	}
+
+	/**
+	 * Register an adapter
+	 * @param {ErrorAdapter} adapter - The adapter to register
+	 * @returns {void}
+	 */
+	use(adapter) {
+		if (
+			!adapter ||
+			typeof adapter.name !== "string" ||
+			typeof adapter.report !== "function"
+		) {
+			throw new Error(
+				"Adapter must have a name (string) and a report (function)",
+			);
+		}
+		this.#adapters.push(adapter);
+	}
+
+	/**
+	 * Report an error to all registered adapters
+	 * @param {Error} error - The error to report
+	 * @param {Object} [context={}] - Additional context
+	 * @returns {void}
+	 */
+	report(error, context = {}) {
+		const enrichedContext = {
+			...context,
+			...(this.#user ? { user: this.#user } : {}),
+			breadcrumbs: [...this.#breadcrumbs],
+		};
+
+		for (const adapter of this.#adapters) {
+			try {
+				adapter.report(error, enrichedContext);
+			} catch (_adapterError) {
+				// Swallow adapter errors to avoid cascading failures
+			}
+		}
+	}
+
+	/**
+	 * Capture a non-error message event
+	 * @param {string} message - The message to capture
+	 * @param {string} [level="info"] - Log level
+	 * @param {Object} [context={}] - Additional context
+	 * @returns {void}
+	 */
+	captureMessage(message, level = "info", context = {}) {
+		const enrichedContext = {
+			...context,
+			...(this.#user ? { user: this.#user } : {}),
+		};
+
+		for (const adapter of this.#adapters) {
+			try {
+				if (typeof adapter.captureMessage === "function") {
+					adapter.captureMessage(message, level, enrichedContext);
+				}
+			} catch (_adapterError) {
+				// Swallow adapter errors
+			}
+		}
+	}
+
+	/**
+	 * Set user context for subsequent reports
+	 * @param {Object} user - User information
+	 * @returns {void}
+	 */
+	setUser(user) {
+		this.#user = user;
+
+		for (const adapter of this.#adapters) {
+			try {
+				if (typeof adapter.setUser === "function") {
+					adapter.setUser(user);
+				}
+			} catch (_adapterError) {
+				// Swallow adapter errors
+			}
+		}
+	}
+
+	/**
+	 * Add a breadcrumb to the trail (circular buffer, max 50)
+	 * @param {string} message - Breadcrumb message
+	 * @param {string} [category="default"] - Breadcrumb category
+	 * @param {Object} [data={}] - Associated data
+	 * @returns {void}
+	 */
+	addBreadcrumb(message, category = "default", data = {}) {
+		/** @type {Breadcrumb} */
+		const breadcrumb = {
+			message,
+			category,
+			data,
+			timestamp: new Date().toISOString(),
+		};
+
+		if (this.#breadcrumbs.length >= MAX_BREADCRUMBS) {
+			this.#breadcrumbs.shift();
+		}
+		this.#breadcrumbs.push(breadcrumb);
+
+		for (const adapter of this.#adapters) {
+			try {
+				if (typeof adapter.addBreadcrumb === "function") {
+					adapter.addBreadcrumb(message, category, data);
+				}
+			} catch (_adapterError) {
+				// Swallow adapter errors
+			}
+		}
+	}
+
+	/**
+	 * Returns the list of registered adapters (for inspection/testing)
+	 * @returns {ErrorAdapter[]}
+	 */
+	get adapters() {
+		return [...this.#adapters];
+	}
+
+	/**
+	 * Returns the current breadcrumbs (for inspection/testing)
+	 * @returns {Breadcrumb[]}
+	 */
+	get breadcrumbs() {
+		return [...this.#breadcrumbs];
+	}
+}
+
+/**
+ * Creates a Sentry adapter factory (stub/example).
+ * Downstream projects can use this as a template to integrate Sentry.
+ *
+ * @param {Object} _options - Sentry configuration options
+ * @returns {ErrorAdapter} A Sentry adapter (stubbed)
+ *
+ * @example
+ * ```js
+ * import * as Sentry from "@sentry/node";
+ * import { errorReporter, createSentryAdapter } from "@techstream/quark-core";
+ *
+ * Sentry.init({ dsn: "https://example@sentry.io/123" });
+ * errorReporter.use(createSentryAdapter({ Sentry }));
+ * ```
+ */
+export const createSentryAdapter = (_options = {}) => {
+	return {
+		name: "sentry",
+
+		report(_error, _context) {
+			// Example Sentry integration:
+			// const { Sentry } = options;
+			// Sentry.withScope((scope) => {
+			//   if (context.user) scope.setUser(context.user);
+			//   if (context.breadcrumbs) {
+			//     for (const b of context.breadcrumbs) {
+			//       Sentry.addBreadcrumb({ message: b.message, category: b.category, data: b.data });
+			//     }
+			//   }
+			//   scope.setExtras(context);
+			//   Sentry.captureException(error);
+			// });
+		},
+
+		captureMessage(_message, _level, _context) {
+			// Example:
+			// const { Sentry } = options;
+			// Sentry.captureMessage(message, level);
+		},
+
+		setUser(_user) {
+			// Example:
+			// const { Sentry } = options;
+			// Sentry.setUser(user);
+		},
+
+		addBreadcrumb(_message, _category, _data) {
+			// Example:
+			// const { Sentry } = options;
+			// Sentry.addBreadcrumb({ message, category, data });
+		},
+	};
+};
+
+/** Global singleton error reporter instance */
+export const errorReporter = new ErrorReporter();