@techstream/quark-core 1.1.0 → 1.4.0

package/README.md

@@ -1,419 +1,41 @@
-# @techstream/quark-core - The Quark Platform Core
+# @techstream/quark-core
 
-The central "plumbing" package for the Quark platform. Every Quark application inherits this core infrastructure, providing database access, authentication, job queuing, and error handling out of the box.
+Shared infrastructure for the Quark platform — authentication, job queues, error handling, and utilities.
 
-## Philosophy
+## What's Included
 
-`@techstream/quark-core` provides **opinionated, zero-configuration defaults** for common infrastructure concerns:
-
-- **Database**: Prisma ORM with singleton pattern
-- **Authentication**: Next-auth helpers with sensible defaults
-- **Job Queue**: BullMQ integration for background jobs
-- **Error Handling**: Standardized, serializable error types
-- **Utilities**: Common functions for retries, validation, etc.
-
-Applications **inherit these tools** but can **extend and override** them as needed.
-
-## Core Principles
-
-### What Goes in Core
-
-✅ **Belongs in Core:**
-- Infrastructure-level utilities (DB, Auth, Queue, Errors)
-- Patterns that every app needs
-- Zero-configuration defaults
-- Type definitions
-- Provider-agnostic helpers
-
-❌ **Does NOT belong in Core:**
-- Application-specific business logic
-- Domain models (use Prisma schema instead)
-- UI components (use @techstream/quark-ui)
-- Config-specific settings (use environment variables)
-
-### What Gets "Ejected"
-
-The "ejection" pattern allows apps to customize Core defaults:
-
-```javascript
-// Import core helpers
-import { createAuthConfig, createQueue } from "@techstream/quark-core";
-
-// Override/extend with app-specific config
-export const authConfig = createAuthConfig({
-  providers: [GitHubProvider(...)],
-  callbacks: {
-    async jwt({ token, user }) {
-      // Custom JWT logic
-      return token;
-    }
-  }
-});
-```
+- **Authentication** — Next-auth helpers (`createAuthConfig`, `requireAuth`, password hashing)
+- **Job Queue** — BullMQ integration (`createQueue`, `createWorker`, `addJob`)
+- **Errors** — Standardized error types (`ValidationError`, `NotFoundError`, `UnauthorizedError`, etc.)
+- **Utilities** — `retryAsync`, `deepMerge`, `randomString`, `sanitizeId`, `measureTime`, `memoize`
+- **Validation** — Zod-based request body validation
+- **Redis / Mailhog** — Connection helpers for Redis and Mailhog
 
 ## Usage
 
-### Database Client
-
-Access the Prisma singleton client:
-
-```javascript
-import { createDbClient } from "@techstream/quark-core";
-
-const db = createDbClient();
-
-const user = await db.user.findUnique({
-  where: { id: "123" }
-});
-```
-
-In development, the client automatically attaches to `globalThis` to prevent hot-reload issues.
-
-### Authentication
-
-Create a next-auth configuration with defaults:
-
-```javascript
-import { createAuthConfig, getCurrentSession, getUserId } from "@techstream/quark-core";
-
-export const authConfig = createAuthConfig({
-  providers: [GitHubProvider({ ... })],
-});
-
-// In a server action/API route:
-import { getSession } from "next-auth/react";
-
-const session = await getCurrentSession(getSession);
-if (!session) {
-  throw new UnauthorizedError();
-}
-
-const userId = getUserId(session);
-```
-
-#### Available Auth Functions
-
-- `createAuthConfig(options)` - Creates next-auth config
-- `getCurrentSession(getSession)` - Safely retrieves session
-- `isAuthenticated(session)` - Checks if session is valid
-- `getUserId(session)` - Extracts user ID
-- `getUserEmail(session)` - Extracts user email
-- `requireAuth(session)` - Throws error if not authenticated
-
-### Job Queue
-
-Initialize background job processing:
-
-```javascript
-import { createQueue, createWorker, addJob } from "@techstream/quark-core";
-
-// Create a queue
-const emailQueue = createQueue("emails", {
-  redis: {
-    host: process.env.REDIS_HOST,
-    port: process.env.REDIS_PORT,
-  },
-  defaultJobOptions: {
-    attempts: 3,
-    backoff: {
-      type: "exponential",
-      delay: 2000,
-    },
-  }
-});
-
-// Process jobs
-createWorker("emails", async (job) => {
-  await sendEmail(job.data);
-  return { success: true };
-});
-
-// Add a job
-await addJob(emailQueue, "send-email", {
-  to: "user@example.com",
-  subject: "Welcome!",
-});
-```
-
-#### Available Queue Functions
-
-- `createQueue(name, options)` - Creates a BullMQ queue
-- `createWorker(queueName, handler, options)` - Creates a job processor
-- `addJob(queue, jobName, data, jobOptions)` - Adds a job to queue
-- `getJobStatus(job)` - Gets job status/progress
-- `clearQueue(queue)` - Clears all jobs from queue
-- `closeAllQueues()` - Gracefully closes all queues
-- `checkQueueHealth()` - Checks Redis connectivity
-
-### Error Handling
-
-Use standardized error types:
-
 ```javascript
 import {
+  createAuthConfig,
+  requireAuth,
+  createQueue,
+  createWorker,
+  addJob,
   ValidationError,
-  UnauthorizedError,
-  NotFoundError,
-  AppError,
-  logError,
-  normalizeError,
-} from "@techstream/quark-core";
-
-// Throw specific errors
-if (!email) {
-  throw new ValidationError("Email is required");
-}
-
-if (!session) {
-  throw new UnauthorizedError("Please log in");
-}
-
-if (!user) {
-  throw new NotFoundError("User not found");
-}
-
-// Error types automatically serialize to JSON:
-// {
-//   "name": "ValidationError",
-//   "message": "Email is required",
-//   "code": "VALIDATION_ERROR",
-//   "statusCode": 400,
-//   "timestamp": "2026-02-04T10:00:00.000Z"
-// }
-
-// Handle errors with context
-try {
-  await someOperation();
-} catch (error) {
-  logError(error, { userId: "123", context: "email_signup" });
-}
-```
-
-#### Available Error Types
-
-- `AppError` - Base class (500)
-- `ValidationError` - Bad input (400)
-- `UnauthorizedError` - Not authenticated (401)
-- `ForbiddenError` - Not authorized (403)
-- `NotFoundError` - Resource missing (404)
-- `ConflictError` - Resource conflict (409)
-- `RateLimitError` - Too many requests (429)
-- `DatabaseError` - Database issue (500)
-- `ServiceError` - External service failure (502)
-
-### Utilities
-
-Common helper functions:
-
-```javascript
-import {
   retryAsync,
-  validateEnv,
-  deepMerge,
-  randomString,
-  sanitizeId,
-  measureTime,
-  memoize,
 } from "@techstream/quark-core";
-
-// Retry with exponential backoff
-const result = await retryAsync(
-  () => fetchFromExternalAPI(),
-  {
-    maxAttempts: 5,
-    initialDelay: 1000,
-    onRetry: ({ attempt, delay }) => {
-      console.log(`Retry ${attempt} after ${delay}ms`);
-    }
-  }
-);
-
-// Validate environment
-validateEnv(["DATABASE_URL", "REDIS_HOST"]);
-
-// Merge configurations
-const config = deepMerge(defaults, userConfig);
-
-// Generate IDs
-const id = randomString(12);
-
-// Sanitize for URLs
-const slug = sanitizeId("Hello World"); // "hello-world"
-
-// Measure performance
-const { result, duration } = await measureTime(async () => {
-  return await expensiveOperation();
-});
-console.log(`Completed in ${duration}ms`);
-
-// Cache results
-const getCachedUser = memoize(
-  (id) => db.user.findUnique({ where: { id } }),
-  60000 // 1 minute TTL
-);
-```
-
-## Environment Configuration
-
-Core respects these environment variables:
-
-```bash
-# Database
-DATABASE_URL=postgresql://...
-
-# Redis/Queue
-REDIS_HOST=localhost
-REDIS_PORT=6379
-REDIS_DB=0
-
-# Application URL
-APP_URL=http://localhost:3000
-
-# Authentication
-NEXTAUTH_SECRET=your-secret-key
-
-# Node
-NODE_ENV=development
 ```
 
-## Testing Core
+All modules are re-exported from the package root. See JSDoc comments on each function for options and usage details.
 
-Core includes unit tests verifying all functionality:
+## Testing
 
 ```bash
 cd packages/core
 pnpm test
 ```
 
-See [Core Tests](./test/) for examples.
-
-## Extending Core
-
-### Custom Error Types
-
-```javascript
-import { AppError } from "@techstream/quark-core";
-
-export class PaymentError extends AppError {
-  constructor(message, code = "PAYMENT_FAILED") {
-    super(message, 402, code);
-  }
-}
-```
-
-### Custom Queue Handlers
-
-```javascript
-import { createWorker } from "@techstream/quark-core";
-
-createWorker("analytics", async (job) => {
-  await trackEvent(job.data);
-}, {
-  concurrency: 10,
-  redis: {
-    host: "redis-prod.internal",
-    port: 6379,
-  }
-});
-```
-
-### Middleware & Hooks
-
-```javascript
-import { createDbClient } from "@techstream/quark-core";
-
-const db = createDbClient({
-  middleware: [
-    {
-      $use: async (params, next) => {
-        const before = Date.now();
-        const result = await next(params);
-        const after = Date.now();
-        console.log(`${params.model}.${params.action} took ${after - before}ms`);
-        return result;
-      },
-    },
-  ],
-});
-```
-
-## Architecture
-
-```
-@techstream/quark-core/
-├── src/
-│   ├── index.js          # Main exports
-│   ├── auth/
-│   │   ├── index.js      # Next-auth helpers
-│   │   └── password.js   # Password hashing (bcryptjs)
-│   ├── queue/
-│   │   └── index.js      # BullMQ integration
-│   ├── errors.js         # Error types & utilities
-│   ├── redis.js          # Redis URL & config helpers
-│   ├── mailhog.js        # Mailhog SMTP/UI config helpers
-│   ├── validation.js     # Zod request body validation
-│   ├── utils.js          # Common helpers
-│   ├── types.js          # JSDoc type definitions
-│   ├── auth.test.js      # Auth tests
-│   ├── errors.test.js    # Error tests
-│   └── utils.test.js     # Utils tests
-└── package.json
-```
-
-## Migration Path from Existing Apps
-
-If you're migrating from an existing app:
-
-1. **Keep your current setup** - Core is not required
-2. **Extract shared patterns** - Move common code to Core
-3. **Test independently** - Ensure Core works standalone
-4. **Adopt gradually** - Start using Core utilities piece by piece
-5. **Eject where needed** - Override defaults in your app
-
-Example migration:
-
-```javascript
-// Before: app-specific auth.js
-export const authConfig = { ... };
-
-// After: inherit and extend from Core
-import { createAuthConfig } from "@techstream/quark-core";
-
-export const authConfig = createAuthConfig({
-  providers: [...],  // add app-specific providers
-});
-```
-
-## Troubleshooting
-
-### Prisma Client Issues
-
-**"Cannot find Prisma Client"**
-- Ensure `@prisma/client` is installed: `pnpm install`
-- Run `pnpm db:generate` to build Prisma client
-
-### Queue Connection Issues
-
-**"Redis connection refused"**
-- Check REDIS_HOST and REDIS_PORT
-- Ensure Redis is running: `docker-compose up redis`
-
-### Auth Issues
-
-**"NEXTAUTH_SECRET is not set"**
-- Set in production: `export NEXTAUTH_SECRET=<random-string>`
-- Or pass via `createAuthConfig({ secret: '...' })`
-
-## Contributing
-
-When adding features to Core:
-
-1. ✅ **Add comprehensive JSDoc comments**
-2. ✅ **Create unit tests** in `*.test.js`
-3. ✅ **Update this README**
-4. ✅ **Keep it framework-agnostic** where possible
-5. ✅ **Document configuration options**
-
-## License
+## Support
 
-ISC - Part of the Quark Platform
+For issues, questions, and discussions:
+- 🐛 [Issue Tracker](https://github.com/Bobnoddle/quark/issues)
+- 💬 [Discussions](https://github.com/Bobnoddle/quark/discussions)

package/package.json

@@ -1,29 +1,34 @@
 {
-	"name": "@techstream/quark-core",
-	"version": "1.1.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"
-	}
-}
+  "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

@@ -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

@@ -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

@@ -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

@@ -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, "&")
+		.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 };
+}