npm - @techstream/quark-core - Versions diffs - 1.2.0 → 1.4.0 - Mend

@techstream/quark-core 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/package.json +33 -29
package/src/auth/index.js +1 -3
package/src/auth.test.js +1 -3
package/src/cache.test.js +1 -1
package/src/email-templates.js +134 -0
package/src/email-templates.test.js +124 -0
package/src/email.js +13 -6
package/src/email.test.js +138 -126
package/src/index.js +4 -2
package/src/mailhog.js +2 -2
package/src/rate-limiter.js +1 -1
package/.turbo/turbo-lint.log +0 -7
package/.turbo/turbo-test.log +0 -1376
package/test-imports.mjs +0 -21

package/package.json CHANGED Viewed

@@ -1,30 +1,34 @@
 {
-	"name": "@techstream/quark-core",
-	"version": "1.2.0",
-	"type": "module",
-	"main": "src/index.js",
-	"exports": {
-		".": "./src/index.js",
-		"./testing": "./src/testing/index.js"
-	},
-	"dependencies": {
-		"bcryptjs": "^3.0.3",
-		"bullmq": "^5.67.3",
-		"ioredis": "^5.9.3",
-		"next-auth": "5.0.0-beta.30",
-		"nodemailer": "^6.10.1",
-		"zod": "^4.3.6"
-	},
-	"devDependencies": {
-		"@types/node": "^24.10.12"
-	},
-	"scripts": {
-		"test": "node --test $(find src -name '*.test.js')",
-		"lint": "biome format --write && biome check --write"
-	},
-	"publishConfig": {
-		"registry": "https://registry.npmjs.org",
-		"access": "public"
-	},
-	"license": "ISC"
-}
+  "name": "@techstream/quark-core",
+  "version": "1.4.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./testing": "./src/testing/index.js"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.3",
+    "bullmq": "^5.67.3",
+    "ioredis": "^5.9.3",
+    "next-auth": "5.0.0-beta.30",
+    "nodemailer": "^6.10.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.12"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "ISC",
+  "scripts": {
+    "test": "node --test $(find src -name '*.test.js')",
+    "lint": "biome format --write && biome check --write"
+  }
+}

package/src/auth/index.js CHANGED Viewed

@@ -27,9 +27,7 @@ export const createAuthConfig = (options = {}) => {
 	} = options;
 	if (!secret) {
-		throw new Error(
-			"NEXTAUTH_SECRET must be set (env var or options.secret)",
-		);
+		throw new Error("NEXTAUTH_SECRET must be set (env var or options.secret)");
 	}
 	return {

package/src/auth.test.js CHANGED Viewed

@@ -23,9 +23,7 @@ test("Auth Module", async (t) => {
 		try {
 			assert.throws(
 				() => createAuthConfig(),
-				(err) =>
-					err instanceof Error &&
-					/NEXTAUTH_SECRET/.test(err.message),
+				(err) => err instanceof Error && /NEXTAUTH_SECRET/.test(err.message),
 			);
 		} finally {
 			if (orig !== undefined) process.env.NEXTAUTH_SECRET = orig;

package/src/cache.test.js CHANGED Viewed

@@ -31,7 +31,7 @@ function createMockRedis() {
 			expires.delete(key);
 		},
-		async scan(cursor, ...args) {
+		async scan(_cursor, ...args) {
 			// Simple mock: return all matching keys in one batch
 			const matchIdx = args.indexOf("MATCH");
 			const pattern = matchIdx !== -1 ? args[matchIdx + 1] : "*";

package/src/email-templates.js ADDED Viewed

@@ -0,0 +1,134 @@
+/**
+ * @techstream/quark-core - Email Templates
+ *
+ * Reusable HTML email templates with plain-text fallbacks.
+ * Each template function returns { subject, html, text }.
+ */
+/**
+ * Escape HTML entities to prevent XSS in user-provided values
+ * @param {string} str
+ * @returns {string}
+ */
+function escapeHtml(str) {
+	return String(str)
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#039;");
+}
+/**
+ * Shared outer layout for all emails
+ * @param {string} body - Inner HTML content
+ * @returns {string}
+ */
+function layout(body) {
+	return `<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head>
+<body style="margin:0;padding:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;background:#f4f4f5">
+  <table width="100%" cellpadding="0" cellspacing="0" style="padding:32px 16px">
+    <tr><td align="center">
+      <table width="100%" style="max-width:560px;background:#fff;border-radius:8px;border:1px solid #e4e4e7;padding:32px">
+        <tr><td>${body}</td></tr>
+      </table>
+      <p style="color:#a1a1aa;font-size:12px;margin-top:24px">
+        You received this email because an account was created with this address.
+      </p>
+    </td></tr>
+  </table>
+</body>
+</html>`;
+}
+/**
+ * Welcome email — sent after user registration
+ *
+ * @param {{ name?: string, appName?: string, loginUrl?: string }} data
+ * @returns {{ subject: string, html: string, text: string }}
+ */
+export function welcomeEmail(data = {}) {
+	const name = data.name ? escapeHtml(data.name) : "there";
+	const appName = data.appName || "Quark";
+	const loginUrl = data.loginUrl || "";
+	const buttonHtml = loginUrl
+		? `<p style="text-align:center;margin:24px 0">
+        <a href="${escapeHtml(loginUrl)}" style="display:inline-block;padding:12px 24px;background:#18181b;color:#fff;text-decoration:none;border-radius:6px;font-weight:500">
+          Sign in to ${escapeHtml(appName)}
+        </a>
+      </p>`
+		: "";
+	const html = layout(`
+    <h1 style="margin:0 0 16px;font-size:24px;color:#18181b">Welcome, ${name}!</h1>
+    <p style="color:#3f3f46;line-height:1.6;margin:0 0 16px">
+      Your account has been created successfully. You can now sign in and start using ${escapeHtml(appName)}.
+    </p>
+    ${buttonHtml}
+    <p style="color:#71717a;font-size:14px;margin:0">
+      If you didn't create this account, you can safely ignore this email.
+    </p>
+  `);
+	const text = [
+		`Welcome, ${data.name || "there"}!`,
+		"",
+		`Your account has been created successfully. You can now sign in and start using ${appName}.`,
+		...(loginUrl ? ["", `Sign in: ${loginUrl}`] : []),
+		"",
+		"If you didn't create this account, you can safely ignore this email.",
+	].join("\n");
+	return { subject: `Welcome to ${appName}!`, html, text };
+}
+/**
+ * Password reset email — sent when user requests a reset
+ *
+ * @param {{ name?: string, resetUrl: string, appName?: string, expiresIn?: string }} data
+ * @returns {{ subject: string, html: string, text: string }}
+ */
+export function passwordResetEmail(data) {
+	if (!data?.resetUrl) {
+		throw new Error("resetUrl is required for password reset email");
+	}
+	const name = data.name ? escapeHtml(data.name) : "there";
+	const appName = data.appName || "Quark";
+	const expiresIn = data.expiresIn || "1 hour";
+	const html = layout(`
+    <h1 style="margin:0 0 16px;font-size:24px;color:#18181b">Reset your password</h1>
+    <p style="color:#3f3f46;line-height:1.6;margin:0 0 16px">
+      Hi ${name}, we received a request to reset your ${escapeHtml(appName)} password.
+    </p>
+    <p style="text-align:center;margin:24px 0">
+      <a href="${escapeHtml(data.resetUrl)}" style="display:inline-block;padding:12px 24px;background:#18181b;color:#fff;text-decoration:none;border-radius:6px;font-weight:500">
+        Reset password
+      </a>
+    </p>
+    <p style="color:#71717a;font-size:14px;margin:0 0 8px">
+      This link will expire in ${escapeHtml(expiresIn)}.
+    </p>
+    <p style="color:#71717a;font-size:14px;margin:0">
+      If you didn't request this, you can safely ignore this email. Your password will not be changed.
+    </p>
+  `);
+	const text = [
+		`Reset your password`,
+		"",
+		`Hi ${data.name || "there"}, we received a request to reset your ${appName} password.`,
+		"",
+		`Reset your password: ${data.resetUrl}`,
+		"",
+		`This link will expire in ${expiresIn}.`,
+		"",
+		"If you didn't request this, you can safely ignore this email. Your password will not be changed.",
+	].join("\n");
+	return { subject: `Reset your ${appName} password`, html, text };
+}

package/src/email-templates.test.js ADDED Viewed

@@ -0,0 +1,124 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import { passwordResetEmail, welcomeEmail } from "./email-templates.js";
+test("welcomeEmail", async (t) => {
+	await t.test("returns subject, html, and text", () => {
+		const result = welcomeEmail({});
+		assert.ok(result.subject);
+		assert.ok(result.html);
+		assert.ok(result.text);
+	});
+	await t.test("uses default app name in subject", () => {
+		const result = welcomeEmail({});
+		assert.strictEqual(result.subject, "Welcome to Quark!");
+	});
+	await t.test("uses custom app name in subject", () => {
+		const result = welcomeEmail({ appName: "MyApp" });
+		assert.strictEqual(result.subject, "Welcome to MyApp!");
+	});
+	await t.test("includes user name in html when provided", () => {
+		const result = welcomeEmail({ name: "Alice" });
+		assert.ok(result.html.includes("Alice"));
+		assert.ok(result.text.includes("Alice"));
+	});
+	await t.test("uses fallback greeting when no name provided", () => {
+		const result = welcomeEmail({});
+		assert.ok(result.html.includes("there"));
+		assert.ok(result.text.includes("there"));
+	});
+	await t.test("includes login URL when provided", () => {
+		const result = welcomeEmail({ loginUrl: "https://app.test/login" });
+		assert.ok(result.html.includes("https://app.test/login"));
+		assert.ok(result.text.includes("https://app.test/login"));
+	});
+	await t.test("omits sign-in button when no login URL", () => {
+		const result = welcomeEmail({});
+		assert.ok(!result.html.includes("Sign In"));
+	});
+	await t.test("escapes HTML in user name", () => {
+		const result = welcomeEmail({ name: "<script>alert('xss')</script>" });
+		assert.ok(!result.html.includes("<script>"));
+		assert.ok(result.html.includes("&lt;script&gt;"));
+	});
+	await t.test("wraps content in html layout", () => {
+		const result = welcomeEmail({});
+		assert.ok(result.html.includes("<!DOCTYPE html>"));
+		assert.ok(result.html.includes("</html>"));
+	});
+});
+test("passwordResetEmail", async (t) => {
+	const validArgs = { resetUrl: "https://app.test/reset?token=abc123" };
+	await t.test("returns subject, html, and text", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.subject);
+		assert.ok(result.html);
+		assert.ok(result.text);
+	});
+	await t.test("throws when resetUrl is missing", () => {
+		assert.throws(() => passwordResetEmail({}), /resetUrl is required/);
+	});
+	await t.test("includes reset URL in html and text", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.html.includes(validArgs.resetUrl));
+		assert.ok(result.text.includes(validArgs.resetUrl));
+	});
+	await t.test("uses default app name", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.subject.includes("Quark"));
+	});
+	await t.test("uses custom app name", () => {
+		const result = passwordResetEmail({ ...validArgs, appName: "MyApp" });
+		assert.ok(result.subject.includes("MyApp"));
+	});
+	await t.test("includes user name when provided", () => {
+		const result = passwordResetEmail({ ...validArgs, name: "Bob" });
+		assert.ok(result.html.includes("Bob"));
+		assert.ok(result.text.includes("Bob"));
+	});
+	await t.test("uses default expiry time", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.html.includes("1 hour"));
+		assert.ok(result.text.includes("1 hour"));
+	});
+	await t.test("uses custom expiry time", () => {
+		const result = passwordResetEmail({
+			...validArgs,
+			expiresIn: "30 minutes",
+		});
+		assert.ok(result.html.includes("30 minutes"));
+		assert.ok(result.text.includes("30 minutes"));
+	});
+	await t.test("escapes HTML in user name", () => {
+		const result = passwordResetEmail({
+			...validArgs,
+			name: '<img src=x onerror="alert(1)">',
+		});
+		assert.ok(!result.html.includes("<img"));
+		assert.ok(result.html.includes("&lt;img"));
+	});
+	await t.test("wraps content in html layout", () => {
+		const result = passwordResetEmail(validArgs);
+		assert.ok(result.html.includes("<!DOCTYPE html>"));
+		assert.ok(result.html.includes("</html>"));
+	});
+});

package/src/email.js CHANGED Viewed

@@ -55,13 +55,15 @@ async function createSmtpTransport() {
 async function sendViaResend(from, to, subject, html, text) {
 	const apiKey = process.env.RESEND_API_KEY;
 	if (!apiKey) {
-		throw new Error("RESEND_API_KEY environment variable is required when EMAIL_PROVIDER=resend");
+		throw new Error(
+			"RESEND_API_KEY environment variable is required when EMAIL_PROVIDER=resend",
+		);
 	}
 	const response = await fetch("https://api.resend.com/emails", {
 		method: "POST",
 		headers: {
-			"Authorization": `Bearer ${apiKey}`,
+			Authorization: `Bearer ${apiKey}`,
 			"Content-Type": "application/json",
 		},
 		body: JSON.stringify({
@@ -75,8 +77,12 @@ async function sendViaResend(from, to, subject, html, text) {
 	});
 	if (!response.ok) {
-		const error = await response.json().catch(() => ({ message: response.statusText }));
-		throw new Error(`Resend API error: ${error.message || response.statusText}`);
+		const error = await response
+			.json()
+			.catch(() => ({ message: response.statusText }));
+		throw new Error(
+			`Resend API error: ${error.message || response.statusText}`,
+		);
 	}
 	return response.json();
@@ -84,7 +90,7 @@ async function sendViaResend(from, to, subject, html, text) {
 /**
  * Create an email service instance
- *
+ *
  * @param {Object} [options]
  * @param {string} [options.provider] - "smtp" or "resend" (defaults to EMAIL_PROVIDER env var or "smtp")
  * @param {string} [options.from] - Sender address (defaults to EMAIL_FROM env var)
@@ -92,7 +98,8 @@ async function sendViaResend(from, to, subject, html, text) {
  */
 export function createEmailService(options = {}) {
 	const provider = options.provider || process.env.EMAIL_PROVIDER || "smtp";
-	const from = options.from || process.env.EMAIL_FROM || "Quark <noreply@localhost>";
+	const from =
+		options.from || process.env.EMAIL_FROM || "Quark <noreply@localhost>";
 	let smtpTransport = null;