@techstream/quark-create-app 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techstream/quark-create-app",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "bin": {
     "quark-create-app": "src/index.js",

package/src/index.js

@@ -475,6 +475,24 @@ PORT=3000
 
 # --- Worker Configuration ---
 WORKER_CONCURRENCY=5
+
+# --- File Storage Configuration ---
+# Storage provider: "local" (default) or "s3" (S3-compatible, e.g. Cloudflare R2)
+STORAGE_PROVIDER=local
+# Local storage directory (only used when STORAGE_PROVIDER=local)
+# STORAGE_LOCAL_DIR=./uploads
+
+# S3 / Cloudflare R2 Configuration (only used when STORAGE_PROVIDER=s3)
+# S3_BUCKET=your-bucket-name
+# S3_REGION=auto
+# S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+# S3_ACCESS_KEY_ID=your-access-key
+# S3_SECRET_ACCESS_KEY=your-secret-key
+# S3_PUBLIC_URL=https://your-public-bucket-domain.com
+
+# --- Upload Limits ---
+# UPLOAD_MAX_SIZE=10485760
+# UPLOAD_ALLOWED_TYPES=image/jpeg,image/png,image/gif,image/webp,image/avif,image/svg+xml,application/pdf
 `;
 			await fs.writeFile(
 				path.join(targetDir, ".env.example"),
@@ -540,6 +558,9 @@ PORT=${webPort}
 
 # --- Worker Configuration ---
 WORKER_CONCURRENCY=5
+
+# --- File Storage ---
+STORAGE_PROVIDER=local
 `;
 			await fs.writeFile(path.join(targetDir, ".env"), envContent);
 			console.log(

package/templates/base-project/apps/web/src/app/api/files/[id]/route.js

@@ -0,0 +1,89 @@
+/**
+ * Single File API
+ * GET    /api/files/[id] - Download / serve a file
+ * DELETE /api/files/[id] - Delete a file (owner or admin only)
+ */
+
+import {
+	createStorage,
+	ForbiddenError,
+	NotFoundError,
+	withCsrfProtection,
+} from "@techstream/quark-core";
+import { file } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { requireAuth } from "@/lib/auth-middleware";
+import { handleError } from "../../error-handler";
+
+/**
+ * GET /api/files/[id]
+ * Serve / download a file by its database ID.
+ * Public endpoint (no auth required) — access control is by knowledge of ID.
+ */
+export async function GET(_request, { params }) {
+	try {
+		const { id } = await params;
+
+		const record = await file.findById(id);
+		if (!record) {
+			throw new NotFoundError("File not found");
+		}
+
+		const storage = createStorage();
+		const { body, contentType } = await storage.get(record.storageKey);
+
+		const headers = new Headers();
+		headers.set("Content-Type", contentType || record.mimeType);
+		headers.set("Content-Length", String(body.length));
+		headers.set("Cache-Control", "public, max-age=31536000, immutable");
+
+		// Inline display for images; attachment download for everything else
+		const isImage = record.mimeType.startsWith("image/");
+		const safeName = record.originalName.replace(/[\\"\r\n]/g, "_");
+		const encodedName = encodeURIComponent(record.originalName);
+		headers.set(
+			"Content-Disposition",
+			isImage
+				? `inline; filename="${safeName}"; filename*=UTF-8''${encodedName}`
+				: `attachment; filename="${safeName}"; filename*=UTF-8''${encodedName}`,
+		);
+
+		return new Response(body, { status: 200, headers });
+	} catch (error) {
+		return handleError(error);
+	}
+}
+
+/**
+ * DELETE /api/files/[id]
+ * Delete a file. Only the uploader or an admin can delete.
+ */
+export const DELETE = withCsrfProtection(async (_request, { params }) => {
+	try {
+		const session = await requireAuth();
+		const { id } = await params;
+
+		const record = await file.findById(id);
+		if (!record) {
+			throw new NotFoundError("File not found");
+		}
+
+		// Authorization: uploader or admin
+		const isOwner = record.uploadedById === session.user.id;
+		const isAdmin = session.user.role === "admin";
+		if (!isOwner && !isAdmin) {
+			throw new ForbiddenError("You can only delete your own files");
+		}
+
+		// Remove from storage
+		const storage = createStorage();
+		await storage.delete(record.storageKey);
+
+		// Remove database record
+		await file.delete(record.id);
+
+		return NextResponse.json({ message: "File deleted" });
+	} catch (error) {
+		return handleError(error);
+	}
+});

package/templates/base-project/apps/web/src/app/api/files/route.js

@@ -0,0 +1,132 @@
+/**
+ * File Upload API
+ * POST /api/files - Upload a file (multipart/form-data)
+ * GET  /api/files - List current user's files
+ */
+
+import {
+	createStorage,
+	generateStorageKey,
+	parseMultipart,
+	validateFile,
+} from "@techstream/quark-core";
+import { file } from "@techstream/quark-db";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import { requireAuth } from "@/lib/auth-middleware";
+import { handleError } from "../error-handler";
+
+const paginationSchema = z.object({
+	page: z.coerce.number().int().min(1).default(1),
+	limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+
+/**
+ * POST /api/files
+ * Upload one or more files via multipart/form-data.
+ * Requires authentication.
+ */
+export async function POST(request) {
+	try {
+		const session = await requireAuth();
+
+		// Parse multipart body
+		const { files: parsedFiles } = await parseMultipart(request);
+
+		if (parsedFiles.length === 0) {
+			return NextResponse.json(
+				{ message: "No files provided" },
+				{ status: 400 },
+			);
+		}
+
+		const storage = createStorage();
+		const results = [];
+
+		for (const parsed of parsedFiles) {
+			// Validate each file
+			const validation = validateFile({
+				filename: parsed.filename,
+				mimeType: parsed.mimeType,
+				size: parsed.size,
+				buffer: parsed.buffer,
+			});
+
+			if (!validation.valid) {
+				return NextResponse.json(
+					{ message: validation.error, filename: parsed.filename },
+					{ status: 422 },
+				);
+			}
+
+			// Generate storage key and upload
+			const storageKey = generateStorageKey(parsed.filename);
+
+			await storage.put(storageKey, parsed.buffer, {
+				contentType: parsed.mimeType,
+			});
+
+			// Save metadata to database
+			const record = await file.create({
+				filename: storageKey.split("/").pop(),
+				originalName: parsed.filename,
+				mimeType: parsed.mimeType,
+				size: parsed.size,
+				storageKey,
+				storageProvider: storage.provider,
+				uploadedById: session.user.id,
+			});
+
+			results.push({
+				id: record.id,
+				originalName: record.originalName,
+				mimeType: record.mimeType,
+				size: record.size,
+				url: `/api/files/${record.id}`,
+				createdAt: record.createdAt,
+			});
+		}
+
+		const status = results.length === 1 ? 201 : 200;
+		const body = results.length === 1 ? results[0] : { files: results };
+
+		return NextResponse.json(body, { status });
+	} catch (error) {
+		return handleError(error);
+	}
+}
+
+/**
+ * GET /api/files
+ * List files uploaded by the current user.
+ */
+export async function GET(request) {
+	try {
+		const session = await requireAuth();
+
+		const { searchParams } = new URL(request.url);
+		const { page, limit } = paginationSchema.parse({
+			page: searchParams.get("page") ?? undefined,
+			limit: searchParams.get("limit") ?? undefined,
+		});
+
+		const skip = (page - 1) * limit;
+		const files = await file.findByUploader(session.user.id, {
+			skip,
+			take: limit,
+		});
+
+		const mapped = files.map((f) => ({
+			id: f.id,
+			originalName: f.originalName,
+			mimeType: f.mimeType,
+			size: f.size,
+			url: `/api/files/${f.id}`,
+			createdAt: f.createdAt,
+		}));
+
+		return NextResponse.json(mapped);
+	} catch (error) {
+		return handleError(error);
+	}
+}

package/templates/base-project/apps/worker/src/handlers/email.js

@@ -0,0 +1,100 @@
+/**
+ * Email Job Handlers
+ * Processes email-related background jobs
+ */
+
+import {
+	createEmailService,
+	passwordResetEmail,
+	welcomeEmail,
+} from "@techstream/quark-core";
+import { prisma } from "@techstream/quark-db";
+import { JOB_NAMES } from "@techstream/quark-jobs";
+
+const emailService = createEmailService();
+
+/**
+ * Job handler for SEND_WELCOME_EMAIL
+ * @param {import("bullmq").Job} bullJob
+ * @param {import("@techstream/quark-core").Logger} logger
+ */
+export async function handleSendWelcomeEmail(bullJob, logger) {
+	const { userId } = bullJob.data;
+
+	if (!userId) {
+		throw new Error("userId is required for SEND_WELCOME_EMAIL job");
+	}
+
+	logger.info(`Sending welcome email for user ${userId}`, {
+		job: JOB_NAMES.SEND_WELCOME_EMAIL,
+		userId,
+	});
+
+	const userRecord = await prisma.user.findUnique({
+		where: { id: userId },
+		select: { email: true, name: true },
+	});
+
+	if (!userRecord?.email) {
+		throw new Error(`User ${userId} not found or has no email`);
+	}
+
+	const template = welcomeEmail({
+		name: userRecord.name,
+		loginUrl: process.env.APP_URL
+			? `${process.env.APP_URL}/api/auth/signin`
+			: undefined,
+	});
+
+	await emailService.sendEmail(
+		userRecord.email,
+		template.subject,
+		template.html,
+		template.text,
+	);
+
+	return { success: true, userId, email: userRecord.email };
+}
+
+/**
+ * Job handler for SEND_RESET_PASSWORD_EMAIL
+ * @param {import("bullmq").Job} bullJob
+ * @param {import("@techstream/quark-core").Logger} logger
+ */
+export async function handleSendResetPasswordEmail(bullJob, logger) {
+	const { userId, resetUrl } = bullJob.data;
+
+	if (!userId || !resetUrl) {
+		throw new Error(
+			"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
+		);
+	}
+
+	logger.info(`Sending password reset email for user ${userId}`, {
+		job: JOB_NAMES.SEND_RESET_PASSWORD_EMAIL,
+		userId,
+	});
+
+	const userRecord = await prisma.user.findUnique({
+		where: { id: userId },
+		select: { email: true, name: true },
+	});
+
+	if (!userRecord?.email) {
+		throw new Error(`User ${userId} not found or has no email`);
+	}
+
+	const template = passwordResetEmail({
+		name: userRecord.name,
+		resetUrl,
+	});
+
+	await emailService.sendEmail(
+		userRecord.email,
+		template.subject,
+		template.html,
+		template.text,
+	);
+
+	return { success: true, userId, email: userRecord.email };
+}

package/templates/base-project/apps/worker/src/handlers/files.js

@@ -0,0 +1,59 @@
+/**
+ * File Job Handlers
+ * Processes file-related background jobs (cleanup, etc.)
+ */
+
+import { createStorage } from "@techstream/quark-core";
+import { file } from "@techstream/quark-db";
+import { JOB_NAMES } from "@techstream/quark-jobs";
+
+/**
+ * Job handler for CLEANUP_ORPHANED_FILES
+ * Deletes files with no owner that are older than a retention period.
+ *
+ * @param {import("bullmq").Job} bullJob
+ * @param {import("@techstream/quark-core").Logger} logger
+ */
+export async function handleCleanupOrphanedFiles(bullJob, logger) {
+	const retentionHours = bullJob.data?.retentionHours || 24;
+	const cutoff = new Date(Date.now() - retentionHours * 60 * 60 * 1000);
+
+	logger.info("Starting orphaned file cleanup", {
+		job: JOB_NAMES.CLEANUP_ORPHANED_FILES,
+		retentionHours,
+		cutoff: cutoff.toISOString(),
+	});
+
+	const orphaned = await file.findOlderThan(cutoff);
+
+	if (orphaned.length === 0) {
+		logger.info("No orphaned files to clean up");
+		return { success: true, deleted: 0 };
+	}
+
+	const storage = createStorage();
+	let deleted = 0;
+	const errors = [];
+
+	for (const record of orphaned) {
+		try {
+			await storage.delete(record.storageKey);
+			await file.delete(record.id);
+			deleted++;
+		} catch (err) {
+			errors.push({ id: record.id, error: err.message });
+			logger.warn(`Failed to delete file ${record.id}: ${err.message}`);
+		}
+	}
+
+	logger.info(
+		`Orphaned file cleanup complete: ${deleted}/${orphaned.length} deleted`,
+		{
+			deleted,
+			total: orphaned.length,
+			errors: errors.length,
+		},
+	);
+
+	return { success: true, deleted, total: orphaned.length, errors };
+}

package/templates/base-project/apps/worker/src/handlers/index.js

@@ -0,0 +1,18 @@
+/**
+ * Job Handler Registry
+ * Maps job names to their handler functions.
+ * Each handler receives (bullJob, logger) and returns a result object.
+ */
+
+import { JOB_NAMES } from "@techstream/quark-jobs";
+import {
+	handleSendResetPasswordEmail,
+	handleSendWelcomeEmail,
+} from "./email.js";
+import { handleCleanupOrphanedFiles } from "./files.js";
+
+export const jobHandlers = {
+	[JOB_NAMES.SEND_WELCOME_EMAIL]: handleSendWelcomeEmail,
+	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: handleSendResetPasswordEmail,
+	[JOB_NAMES.CLEANUP_ORPHANED_FILES]: handleCleanupOrphanedFiles,
+};

package/templates/base-project/apps/worker/src/index.js

@@ -5,163 +5,87 @@
  */
 
 import {
-	createEmailService,
 	createLogger,
+	createQueue,
 	createWorker,
-	passwordResetEmail,
-	welcomeEmail,
 } from "@techstream/quark-core";
 import { prisma } from "@techstream/quark-db";
 import { JOB_NAMES, JOB_QUEUES } from "@techstream/quark-jobs";
+import { jobHandlers } from "./handlers/index.js";
 
 const logger = createLogger("worker");
 
 // Store workers for graceful shutdown
 const workers = [];
 
-// Initialize email service
-const emailService = createEmailService();
-
 /**
- * Job handler for SEND_WELCOME_EMAIL
- * @param {Job} bullJob - BullMQ job object
+ * Generic queue processor — dispatches jobs to registered handlers
+ * @param {string} queueName
  */
-async function handleSendWelcomeEmail(bullJob) {
-	const { userId } = bullJob.data;
-
-	if (!userId) {
-		throw new Error("userId is required for SEND_WELCOME_EMAIL job");
-	}
-
-	logger.info(`Sending welcome email for user ${userId}`, {
-		job: JOB_NAMES.SEND_WELCOME_EMAIL,
-		userId,
-	});
-
-	const userRecord = await prisma.user.findUnique({
-		where: { id: userId },
-		select: { email: true, name: true },
-	});
-
-	if (!userRecord?.email) {
-		throw new Error(`User ${userId} not found or has no email`);
-	}
-
-	const template = welcomeEmail({
-		name: userRecord.name,
-		loginUrl: process.env.APP_URL
-			? `${process.env.APP_URL}/api/auth/signin`
-			: undefined,
-	});
-
-	await emailService.sendEmail(
-		userRecord.email,
-		template.subject,
-		template.html,
-		template.text,
+function createQueueWorker(queueName) {
+	const queueWorker = createWorker(
+		queueName,
+		async (bullJob) => {
+			const handler = jobHandlers[bullJob.name];
+
+			if (!handler) {
+				throw new Error(`No handler registered for job: ${bullJob.name}`);
+			}
+
+			return handler(bullJob, logger);
+		},
+		{
+			concurrency: parseInt(process.env.WORKER_CONCURRENCY || "5", 10),
+		},
 	);
 
-	return { success: true, userId, email: userRecord.email };
-}
-
-/**
- * Job handler for SEND_RESET_PASSWORD_EMAIL
- * @param {Job} bullJob - BullMQ job object
- */
-async function handleSendResetPasswordEmail(bullJob) {
-	const { userId, resetUrl } = bullJob.data;
+	workers.push(queueWorker);
 
-	if (!userId || !resetUrl) {
-		throw new Error(
-			"userId and resetUrl are required for SEND_RESET_PASSWORD_EMAIL job",
-		);
-	}
-
-	logger.info(`Sending password reset email for user ${userId}`, {
-		job: JOB_NAMES.SEND_RESET_PASSWORD_EMAIL,
-		userId,
+	queueWorker.on("completed", (job, result) => {
+		logger.info(`Job ${job.id} (${job.name}) completed`, { result });
 	});
 
-	const userRecord = await prisma.user.findUnique({
-		where: { id: userId },
-		select: { email: true, name: true },
-	});
-
-	if (!userRecord?.email) {
-		throw new Error(`User ${userId} not found or has no email`);
-	}
-
-	const template = passwordResetEmail({
-		name: userRecord.name,
-		resetUrl,
+	queueWorker.on("failed", (job, error) => {
+		logger.error(
+			`Job ${job.id} (${job.name}) failed after ${job.attemptsMade} attempts`,
+			{
+				error: error.message,
+				jobName: job.name,
+				attemptsMade: job.attemptsMade,
+			},
+		);
 	});
 
-	await emailService.sendEmail(
-		userRecord.email,
-		template.subject,
-		template.html,
-		template.text,
+	logger.info(
+		`Queue "${queueName}" worker started (concurrency: ${queueWorker.opts.concurrency})`,
 	);
 
-	return { success: true, userId, email: userRecord.email };
+	return queueWorker;
 }
 
-/**
- * Initialize job handlers
- * Maps job names to their handler functions
- */
-const jobHandlers = {
-	[JOB_NAMES.SEND_WELCOME_EMAIL]: handleSendWelcomeEmail,
-	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: handleSendResetPasswordEmail,
-};
-
 /**
  * Start the worker service
- * Creates workers for all queues and registers handlers
  */
 async function startWorker() {
 	logger.info("Starting Quark Worker Service");
 
 	try {
-		// Create worker for email queue
-		const emailQueueWorker = createWorker(
-			JOB_QUEUES.EMAIL,
-			async (bullJob) => {
-				const handler = jobHandlers[bullJob.name];
-
-				if (!handler) {
-					throw new Error(`No handler registered for job: ${bullJob.name}`);
-				}
+		// Register a worker for each queue
+		for (const queueName of Object.values(JOB_QUEUES)) {
+			createQueueWorker(queueName);
+		}
 
-				return handler(bullJob);
-			},
+		// Schedule repeating cleanup job (runs every 24 hours)
+		const filesQueue = createQueue(JOB_QUEUES.FILES);
+		await filesQueue.add(
+			JOB_NAMES.CLEANUP_ORPHANED_FILES,
+			{ retentionHours: 24 },
 			{
-				concurrency: parseInt(process.env.WORKER_CONCURRENCY || "5", 10),
+				repeat: { every: 24 * 60 * 60 * 1000 }, // 24h
+				jobId: "cleanup-orphaned-files-repeat",
 			},
 		);
 
-		workers.push(emailQueueWorker);
-
-		emailQueueWorker.on("completed", (job, result) => {
-			logger.info(`Job ${job.id} (${job.name}) completed`, { result });
-		});
-
-		emailQueueWorker.on("failed", (job, error) => {
-			logger.error(
-				`Job ${job.id} (${job.name}) failed after ${job.attemptsMade} attempts`,
-				{
-					error: error.message,
-					jobName: job.name,
-					attemptsMade: job.attemptsMade,
-				},
-			);
-		});
-
-		logger.info(
-			`Email queue worker started (concurrency: ${emailQueueWorker.opts.concurrency})`,
-		);
-
-		// Ready to process jobs
 		logger.info("Worker service ready");
 	} catch (error) {
 		logger.error("Failed to start worker service", {
@@ -179,12 +103,10 @@ async function shutdown() {
 	logger.info("Shutting down worker service");
 
 	try {
-		// Close all workers
 		for (const worker of workers) {
 			await worker.close();
 		}
 
-		// Disconnect Prisma client
 		await prisma.$disconnect();
 
 		logger.info("All workers closed");
@@ -198,6 +120,11 @@ async function shutdown() {
 	}
 }
 
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+
+startWorker();
+
 // Register shutdown handlers
 process.on("SIGTERM", shutdown);
 process.on("SIGINT", shutdown);

package/templates/base-project/turbo.json

@@ -34,7 +34,17 @@
 				"MAILHOG_UI_PORT",
 				"NEXTAUTH_SECRET",
 				"APP_URL",
-				"WORKER_CONCURRENCY"
+				"WORKER_CONCURRENCY",
+				"STORAGE_PROVIDER",
+				"STORAGE_LOCAL_DIR",
+				"S3_BUCKET",
+				"S3_REGION",
+				"S3_ENDPOINT",
+				"S3_ACCESS_KEY_ID",
+				"S3_SECRET_ACCESS_KEY",
+				"S3_PUBLIC_URL",
+				"UPLOAD_MAX_SIZE",
+				"UPLOAD_ALLOWED_TYPES"
 			]
 		}
 	}

package/templates/jobs/src/definitions.js

@@ -1,9 +1,10 @@
 export const JOB_QUEUES = {
 	EMAIL: "email-queue",
-	NOTIFICATIONS: "notifications-queue",
+	FILES: "files-queue",
 };
 
 export const JOB_NAMES = {
 	SEND_WELCOME_EMAIL: "send-welcome-email",
 	SEND_RESET_PASSWORD_EMAIL: "send-reset-password-email",
+	CLEANUP_ORPHANED_FILES: "cleanup-orphaned-files",
 };

package/templates/jobs/src/index.js

@@ -1,2 +1 @@
 export { JOB_NAMES, JOB_QUEUES } from "./definitions.js";
-export { jobHandlers } from "./handlers.js";

package/templates/jobs/src/handlers.js

@@ -1,20 +0,0 @@
-import { JOB_NAMES } from "./definitions.js";
-
-export async function sendWelcomeEmail(job) {
-	const { email } = job.data;
-	console.log(`Sending welcome email to ${email}`);
-	// Add your email sending logic here
-	return { success: true };
-}
-
-export async function sendResetPasswordEmail(job) {
-	const { email } = job.data;
-	console.log(`Sending reset password email to ${email}`);
-	// Add your email sending logic here
-	return { success: true };
-}
-
-export const jobHandlers = {
-	[JOB_NAMES.SEND_WELCOME_EMAIL]: sendWelcomeEmail,
-	[JOB_NAMES.SEND_RESET_PASSWORD_EMAIL]: sendResetPasswordEmail,
-};