@techstream/quark-core 1.1.0

package/README.md

@@ -0,0 +1,419 @@
+# @techstream/quark-core - The Quark Platform 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.
+
+## Philosophy
+
+`@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;
+    }
+  }
+});
+```
+
+## 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 {
+  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
+
+Core includes unit tests verifying all functionality:
+
+```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
+
+ISC - Part of the Quark Platform

package/package.json

@@ -0,0 +1,29 @@
+{
+	"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"
+	}
+}

package/src/auth/index.js

@@ -0,0 +1,127 @@
+/**
+ * @techstream/quark-core - Authentication Module
+ * Provides next-auth initialization and session management helpers
+ */
+
+import { UnauthorizedError } from "../errors.js";
+
+export * from "./password.js";
+
+/**
+ * Creates a next-auth configuration object with sensible defaults
+ * Designed to be extended by applications
+ * @param {Object} options - Configuration options
+ * @param {Array} options.providers - Next-auth providers (GitHub, Google, etc.)
+ * @param {Object} options.callbacks - next-auth callbacks (jwt, session, etc.)
+ * @param {Object} options.session - Session configuration
+ * @param {string} options.secret - NEXTAUTH_SECRET (defaults to env var)
+ * @returns {Object} Complete next-auth configuration
+ */
+export const createAuthConfig = (options = {}) => {
+	const {
+		providers = [],
+		callbacks = {},
+		session = {},
+		secret = process.env.NEXTAUTH_SECRET,
+		...rest
+	} = options;
+
+	if (!secret) {
+		throw new Error(
+			"NEXTAUTH_SECRET must be set (env var or options.secret)",
+		);
+	}
+
+	return {
+		secret,
+		providers,
+		session: {
+			strategy: "jwt",
+			maxAge: 30 * 24 * 60 * 60, // 30 days
+			updateAge: 24 * 60 * 60, // 24 hours
+			...session,
+		},
+		callbacks: {
+			async jwt({ token, user }) {
+				if (user) {
+					token.id = user.id;
+					token.email = user.email;
+					token.name = user.name;
+					token.role = user.role || "viewer";
+				}
+				return token;
+			},
+			async session({ session, token }) {
+				if (session.user) {
+					session.user.id = token.id;
+					session.user.role = token.role;
+				}
+				// Note: NextAuth v5+ includes CSRF token in session automatically
+				// For older versions, you can add: session.csrfToken = token.csrfToken;
+				return session;
+			},
+			...callbacks,
+		},
+		pages: {
+			signIn: "/auth/signin",
+			error: "/auth/error",
+		},
+		...rest,
+	};
+};
+
+/**
+ * Utility to safely get the current session (works in both server & edge)
+ * @param {Function} getSession - The next-auth getSession function
+ * @returns {Promise<Object|null>} Session object or null if not authenticated
+ */
+export const getCurrentSession = async (getSession) => {
+	try {
+		return await getSession();
+	} catch (error) {
+		console.error("Failed to get session:", error);
+		return null;
+	}
+};
+
+/**
+ * Checks if a user is authenticated
+ * @param {Object} session - Session object from next-auth
+ * @returns {boolean} True if user is authenticated
+ */
+export const isAuthenticated = (session) => {
+	return session?.user?.email;
+};
+
+/**
+ * Gets user ID from session
+ * @param {Object} session - Session object from next-auth
+ * @returns {string|null} User ID or null
+ */
+export const getUserId = (session) => {
+	return session?.user?.id || null;
+};
+
+/**
+ * Gets user email from session
+ * @param {Object} session - Session object from next-auth
+ * @returns {string|null} User email or null
+ */
+export const getUserEmail = (session) => {
+	return session?.user?.email || null;
+};
+
+/**
+ * Validates that a request has a valid session
+ * Throws UnauthorizedError if not authenticated
+ * @param {Object} session - Session object from next-auth
+ * @throws {UnauthorizedError} If session is invalid
+ * @returns {string} User ID
+ */
+export const requireAuth = (session) => {
+	const userId = getUserId(session);
+	if (!userId) {
+		throw new UnauthorizedError("Authentication required");
+	}
+	return userId;
+};

package/src/auth/password.js

@@ -0,0 +1,9 @@
+import bcrypt from "bcryptjs";
+
+export async function hashPassword(password) {
+	return bcrypt.hash(password, 12);
+}
+
+export async function verifyPassword(password, hashedPassword) {
+	return bcrypt.compare(password, hashedPassword);
+}

package/src/auth.test.js

@@ -0,0 +1,90 @@
+import assert from "node:assert";
+import { test } from "node:test";
+import {
+	createAuthConfig,
+	getUserEmail,
+	getUserId,
+	isAuthenticated,
+	requireAuth,
+} from "../src/auth/index.js";
+
+test("Auth Module", async (t) => {
+	await t.test("createAuthConfig returns valid config", () => {
+		const config = createAuthConfig({ secret: "test-secret" });
+		assert(config.session);
+		assert(config.session.strategy === "jwt");
+		assert(config.session.maxAge === 30 * 24 * 60 * 60);
+		assert.deepStrictEqual(config.providers, []);
+	});
+
+	await t.test("createAuthConfig throws when secret is missing", () => {
+		const orig = process.env.NEXTAUTH_SECRET;
+		delete process.env.NEXTAUTH_SECRET;
+		try {
+			assert.throws(
+				() => createAuthConfig(),
+				(err) =>
+					err instanceof Error &&
+					/NEXTAUTH_SECRET/.test(err.message),
+			);
+		} finally {
+			if (orig !== undefined) process.env.NEXTAUTH_SECRET = orig;
+		}
+	});
+
+	await t.test("createAuthConfig with custom options", () => {
+		const customProvider = { id: "custom" };
+		const config = createAuthConfig({
+			providers: [customProvider],
+			secret: "test-secret",
+		});
+
+		assert.deepStrictEqual(config.providers, [customProvider]);
+		assert(config.secret === "test-secret");
+	});
+
+	await t.test("isAuthenticated returns true for valid session", () => {
+		const session = {
+			user: { email: "test@example.com", id: "123" },
+		};
+		assert(isAuthenticated(session));
+	});
+
+	await t.test("isAuthenticated returns false for invalid session", () => {
+		assert(!isAuthenticated(null));
+		assert(!isAuthenticated({ user: null }));
+		assert(!isAuthenticated({ user: { email: null } }));
+	});
+
+	await t.test("getUserId extracts user ID", () => {
+		const session = { user: { id: "user-123" } };
+		assert(getUserId(session) === "user-123");
+	});
+
+	await t.test("getUserId returns null when missing", () => {
+		assert(getUserId(null) === null);
+		assert(getUserId({ user: null }) === null);
+	});
+
+	await t.test("getUserEmail extracts user email", () => {
+		const session = { user: { email: "test@example.com" } };
+		assert(getUserEmail(session) === "test@example.com");
+	});
+
+	await t.test("getUserEmail returns null when missing", () => {
+		assert(getUserEmail(null) === null);
+	});
+
+	await t.test("requireAuth returns user ID for authenticated session", () => {
+		const session = { user: { id: "user-123", email: "test@example.com" } };
+		const userId = requireAuth(session);
+		assert(userId === "user-123");
+	});
+
+	await t.test("requireAuth throws error for unauthenticated session", () => {
+		assert.throws(
+			() => requireAuth(null),
+			(err) => err instanceof Error,
+		);
+	});
+});