feat: enhance backend conventions for tRPC and Hono with new error handling, pagination, authorization, and logging guidelines. Introduce shared utilities for error management, ownership assertions, and visibility conditions. Update routers to utilize new pagination schema and improve error responses. Add comprehensive documentation in AGENTS.md for better developer onboarding.

AGENTS.md

@@ -145,7 +145,45 @@ bun run build            # Build all packages
 
 ---
 
-## 10. Git & Workflow
+## 10. Backend Conventions (tRPC / Hono)
+
+### Error Handling
+- **Always use English** error messages in tRPC routers.
+- Use helper functions from `packages/api/src/lib/errors.ts`:
+  ```ts
+  import { throwNotFound, throwForbidden, throwBadRequest } from "@labas/api/lib/errors";
+  assertOwnership(row, userId, "Question"); // throws NotFound or Forbidden
+  ```
+- Never throw raw `new Error("...")` in tRPC routers.
+
+### Pagination
+- Use shared schema + helper for all list endpoints:
+  ```ts
+  import { paginationSchema, paginateDefaults } from "@labas/api/lib/pagination";
+  .input(z.object({ search: z.string().optional(), ...paginationSchema?.shape }).optional())
+  const { limit, offset } = paginateDefaults(input);
+  ```
+- Return shape: `{ items: rows, total }` (or domain-specific name like `{ questions: rows, total }` for legacy compatibility).
+
+### Authorization (Ownership)
+- Use `assertOwnership(row, userId, resourceName)` from `packages/api/src/lib/ownership.ts`.
+- Prefer explicit ownership query + assert over embedding `creatorUserId` in `.where()` for mutations that need a clear 404 vs 403.
+
+### Visibility (Public/Private)
+- Use `buildVisibilityCondition(table, userId)` from `packages/api/src/lib/visibility.ts` for list queries.
+- Default behavior: guests see only public; authenticated users see public + their own private.
+
+### Logging
+- Winston logger is available in tRPC context via `ctx.logger`.
+- Use `logger.info()`, `logger.error()`, etc. for business events and errors.
+- Hono HTTP request logging is handled automatically by `hono/logger` in `apps/server/src/index.ts`.
+
+### Router Structure
+- Shared helpers live in `packages/api/src/lib/`.
+- Routers live in `packages/api/src/routers/`.
+- Register new routers in `packages/api/src/routers/index.ts`.
+
+## 11. Git & Workflow
 
 - Do **NOT** run `git commit`, `git push`, `git rebase`, or force-push unless the user explicitly asks for it.
 - Do **NOT** create `README.md` or documentation files unless explicitly requested.
@@ -154,4 +192,4 @@ bun run build            # Build all packages
 
 ---
 
-_Last updated: 2026-05-01_
+_Last updated: 2026-05-06_

packages/api/src/index.ts

@@ -1,5 +1,5 @@
 import { initTRPC, TRPCError } from "@trpc/server";
-
+import { logger } from "./logger";
 import type { Context } from "./context";
 
 export const t = initTRPC.context<Context>().create();
@@ -23,3 +23,15 @@ export const protectedProcedure = t.procedure.use(({ ctx, next }) => {
     },
   });
 });
+
+// Logging middleware (available to use per-router)
+export const loggedProcedure = t.procedure.use(({ ctx, path, type, next }) => {
+  const start = Date.now();
+  logger.info(`${type.toUpperCase()} ${path}`, { userId: ctx.session?.user.id });
+  return next().finally(() => {
+    logger.info(`${type.toUpperCase()} ${path} completed`, {
+      userId: ctx.session?.user.id,
+      durationMs: Date.now() - start,
+    });
+  });
+});

packages/api/src/lib/errors.ts

@@ -0,0 +1,21 @@
+import { TRPCError } from "@trpc/server";
+
+export function throwUnauthorized(message = "Unauthorized"): never {
+  throw new TRPCError({ code: "UNAUTHORIZED", message });
+}
+
+export function throwForbidden(message = "Forbidden"): never {
+  throw new TRPCError({ code: "FORBIDDEN", message });
+}
+
+export function throwNotFound(resource = "Resource"): never {
+  throw new TRPCError({ code: "NOT_FOUND", message: `${resource} not found` });
+}
+
+export function throwBadRequest(message = "Bad request"): never {
+  throw new TRPCError({ code: "BAD_REQUEST", message });
+}
+
+export function throwInternal(message = "Internal server error"): never {
+  throw new TRPCError({ code: "INTERNAL_SERVER_ERROR", message });
+}

packages/api/src/lib/ownership.ts

@@ -0,0 +1,20 @@
+import { eq } from "drizzle-orm";
+import { throwForbidden, throwNotFound } from "./errors";
+
+interface OwnedRow {
+  creatorUserId: string | null;
+}
+
+export function assertOwnership(row: OwnedRow | null | undefined, userId: string, resource = "Resource"): void {
+  if (!row) throwNotFound(resource);
+  if (row.creatorUserId !== userId) throwForbidden();
+}
+
+export function ownershipFilter<TTable extends Record<string, any>>(
+  table: TTable,
+  userId: string,
+  idColumn: keyof TTable,
+  creatorColumn: keyof TTable,
+) {
+  return eq(table[idColumn as string], userId);
+}

packages/api/src/lib/pagination.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { sql } from "drizzle-orm";
+
+export const paginationSchema = z.object({
+  limit: z.number().min(1).max(50).default(20),
+  offset: z.number().min(0).default(0),
+});
+
+export type PaginationInput = z.infer<typeof paginationSchema>;
+
+export interface PaginatedResult<T> {
+  items: T[];
+  total: number;
+}
+
+export function paginateDefaults(input?: PaginationInput) {
+  return {
+    limit: input?.limit ?? 20,
+    offset: input?.offset ?? 0,
+  };
+}
+
+export function countSql(column: any) {
+  return sql<number>`count(*)::int`;
+}

packages/api/src/lib/visibility.ts

@@ -0,0 +1,16 @@
+import { eq, or, isNull, SQL } from "drizzle-orm";
+
+interface VisibilityTable {
+  isPublic: any;
+  creatorUserId: any;
+}
+
+export function buildVisibilityCondition<T extends VisibilityTable>(
+  table: T,
+  userId?: string,
+): SQL | undefined {
+  if (!userId) {
+    return eq(table.isPublic, true);
+  }
+  return or(eq(table.isPublic, true), eq(table.creatorUserId, userId));
+}

packages/api/src/routers/ai.ts

@@ -5,6 +5,8 @@ import { generationInputSchema } from "@labas/ai/schemas";
 import { cancelGenerationJob, enqueueGeneration } from "../queue";
 import { db } from "@labas/db";
 import { question, generationJob } from "@labas/db";
+import { paginationSchema, paginateDefaults } from "../lib/pagination";
+import { throwNotFound, throwForbidden, throwBadRequest } from "../lib/errors";
 
 export const aiRouter = router({
   generate: protectedProcedure
@@ -42,13 +44,9 @@ export const aiRouter = router({
     .mutation(async ({ ctx, input }) => {
       const result = await cancelGenerationJob(ctx.session.user.id, input.jobId);
       if (!result.ok) {
-        const msg =
-          result.reason === "not_found"
-            ? "Job tidak ditemukan"
-            : result.reason === "forbidden"
-              ? "Tidak diizinkan"
-              : "Job sudah selesai atau tidak bisa dibatalkan";
-        throw new Error(msg);
+        if (result.reason === "not_found") throwNotFound("Job");
+        if (result.reason === "forbidden") throwForbidden();
+        throwBadRequest("Job already finished or cannot be cancelled");
       }
       return { ok: true as const };
     }),
@@ -56,18 +54,18 @@ export const aiRouter = router({
   myJobs: protectedProcedure
     .input(
       z.object({
-        limit: z.number().min(1).max(50).default(20),
-        offset: z.number().min(0).default(0),
+        ...paginationSchema.shape,
       }).optional(),
     )
     .query(async ({ ctx, input }) => {
+      const { limit, offset } = paginateDefaults(input);
       const rows = await db
         .select()
         .from(generationJob)
         .where(eq(generationJob.userId, ctx.session.user.id))
         .orderBy(desc(generationJob.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
       return rows;
     }),
 
@@ -126,20 +124,20 @@ export const aiRouter = router({
         .where(eq(generationJob.id, input.jobId))
         .limit(1);
 
-      if (!job) throw new Error("Job tidak ditemukan");
-      if (job.userId !== ctx.session.user.id) throw new Error("Tidak diizinkan");
+      if (!job) throwNotFound("Job");
+      if (job.userId !== ctx.session.user.id) throwForbidden();
       if (job.status !== "failed" && job.status !== "cancelled") {
-        throw new Error("Hanya job yang gagal atau dibatalkan yang bisa di-retry");
+        throwBadRequest("Only failed or cancelled jobs can be retried");
       }
 
       if (!job.inputJson || typeof job.inputJson !== "object") {
-        throw new Error("Data input job tidak tersedia untuk retry");
+        throwBadRequest("Job input data is not available for retry");
       }
 
       const jobInput = job.inputJson as any;
       // Ensure the parsed input has the apiKeyConfig shape the pipeline expects
       if (!jobInput.apiKeyConfig?.baseUrl || !jobInput.apiKeyConfig?.apiKey || !jobInput.apiKeyConfig?.model) {
-        throw new Error("Konfigurasi API key tidak valid untuk retry");
+        throwBadRequest("Invalid API key configuration for retry");
       }
 
       const newJobId = await enqueueGeneration(ctx.session.user.id, jobInput);

packages/api/src/routers/attempt.ts

@@ -12,6 +12,9 @@ import {
   question,
   examType,
 } from "@labas/db";
+import { paginationSchema, paginateDefaults } from "../lib/pagination";
+import { assertOwnership } from "../lib/ownership";
+import { throwNotFound, throwForbidden, throwBadRequest } from "../lib/errors";
 
 function normalizeAnswer(format: string, userAnswer: string, correctAnswer: string): boolean {
   const ua = userAnswer.trim();
@@ -55,10 +58,7 @@ export const attemptRouter = router({
         .where(eq(testPackage.id, input.packageId))
         .limit(1);
 
-      if (!pkg) throw new Error("Package not found");
-      if (!pkg.isPublic && pkg.creatorUserId !== userId) {
-        throw new Error("Not authorized to access this package");
-      }
+      assertOwnership(pkg, userId, "Package");
 
       const sections = await db
         .select({
@@ -78,7 +78,7 @@ export const attemptRouter = router({
         })
         .returning();
 
-      if (!attempt) throw new Error("Failed to create attempt");
+      if (!attempt) throwBadRequest("Failed to create attempt");
 
       for (const section of sections) {
         await db.insert(sectionResult).values({
@@ -107,7 +107,7 @@ export const attemptRouter = router({
         .limit(1);
 
       if (!attempt) return null;
-      if (attempt.userId !== userId) throw new Error("Not authorized");
+      if (attempt.userId !== userId) throwForbidden();
 
       const dbSections = await db
         .select()
@@ -228,9 +228,9 @@ export const attemptRouter = router({
         .where(eq(testAttempt.id, input.attemptId))
         .limit(1);
 
-      if (!attempt) throw new Error("Attempt not found");
-      if (attempt.userId !== userId) throw new Error("Not authorized");
-      if (attempt.status !== "in_progress") throw new Error("Attempt already finished");
+      if (!attempt) throwNotFound("Attempt");
+      if (attempt.userId !== userId) throwForbidden();
+      if (attempt.status !== "in_progress") throwBadRequest("Attempt already finished");
 
       const [q] = await db
         .select()
@@ -238,7 +238,7 @@ export const attemptRouter = router({
         .where(eq(question.id, input.questionId))
         .limit(1);
 
-      if (!q) throw new Error("Question not found");
+      if (!q) throwNotFound("Question");
 
       const isCorrect = normalizeAnswer(q.format, input.userAnswer, q.correctAnswer);
 
@@ -286,9 +286,9 @@ export const attemptRouter = router({
         .where(eq(testAttempt.id, input.attemptId))
         .limit(1);
 
-      if (!attempt) throw new Error("Attempt not found");
-      if (attempt.userId !== userId) throw new Error("Not authorized");
-      if (attempt.status !== "in_progress") throw new Error("Attempt already finished");
+      if (!attempt) throwNotFound("Attempt");
+      if (attempt.userId !== userId) throwForbidden();
+      if (attempt.status !== "in_progress") throwBadRequest("Attempt already finished");
 
       const dbSections = await db
         .select()
@@ -420,9 +420,9 @@ export const attemptRouter = router({
         .where(eq(testAttempt.id, input.attemptId))
         .limit(1);
 
-      if (!attempt) throw new Error("Attempt not found");
-      if (attempt.userId !== userId) throw new Error("Not authorized");
-      if (attempt.status !== "in_progress") throw new Error("Attempt not in progress");
+      if (!attempt) throwNotFound("Attempt");
+      if (attempt.userId !== userId) throwForbidden();
+      if (attempt.status !== "in_progress") throwBadRequest("Attempt not in progress");
 
       await db
         .update(testAttempt)
@@ -437,13 +437,13 @@ export const attemptRouter = router({
       z
         .object({
           packageId: z.string().uuid().optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema.shape,
         })
         .optional(),
     )
     .query(async ({ ctx, input }) => {
       const userId = ctx.session.user.id;
+      const { limit, offset } = paginateDefaults(input);
       const conditions = [eq(testAttempt.userId, userId)];
 
       if (input?.packageId) {
@@ -472,8 +472,8 @@ export const attemptRouter = router({
         .leftJoin(examType, eq(testPackage.examTypeId, examType.id))
         .where(where)
         .orderBy(desc(testAttempt.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })

packages/api/src/routers/combo.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { eq, and, desc, sql, inArray, or } from "drizzle-orm";
+import { eq, and, desc, sql, inArray } from "drizzle-orm";
 import { router, protectedProcedure, publicProcedure } from "../index";
 import { db } from "@labas/db";
 import {
@@ -13,6 +13,10 @@ import {
   sectionType,
   user,
 } from "@labas/db";
+import { paginationSchema, paginateDefaults } from "../lib/pagination";
+import { assertOwnership } from "../lib/ownership";
+import { buildVisibilityCondition } from "../lib/visibility";
+import { throwBadRequest } from "../lib/errors";
 
 export const comboRouter = router({
   list: publicProcedure
@@ -21,19 +25,20 @@ export const comboRouter = router({
         .object({
           isPublic: z.boolean().optional(),
           search: z.string().optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema.shape,
         })
         .optional(),
     )
     .query(async ({ ctx, input }) => {
       const userId = ctx.session?.user.id;
+      const { limit, offset } = paginateDefaults(input);
       const conditions = [];
 
       if (input?.isPublic !== undefined) {
         conditions.push(eq(comboPackage.isPublic, input.isPublic));
-      } else if (!userId) {
-        conditions.push(eq(comboPackage.isPublic, true));
+      } else {
+        const vis = buildVisibilityCondition(comboPackage, userId);
+        if (vis) conditions.push(vis);
       }
 
       const where = conditions.length > 0 ? and(...conditions) : undefined;
@@ -53,8 +58,8 @@ export const comboRouter = router({
         .leftJoin(user, eq(comboPackage.creatorUserId, user.id))
         .where(where)
         .orderBy(desc(comboPackage.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })
@@ -69,13 +74,13 @@ export const comboRouter = router({
       z
         .object({
           search: z.string().optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema.shape,
         })
         .optional(),
     )
     .query(async ({ ctx, input }) => {
       const userId = ctx.session.user.id;
+      const { limit, offset } = paginateDefaults(input);
       const conditions = [eq(comboPackage.creatorUserId, userId)];
       const where = and(...conditions);
 
@@ -91,8 +96,8 @@ export const comboRouter = router({
         .from(comboPackage)
         .where(where)
         .orderBy(desc(comboPackage.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })
@@ -220,7 +225,7 @@ export const comboRouter = router({
         .returning();
 
       if (!combo) {
-        throw new Error("Failed to create combo package");
+        throwBadRequest("Failed to create combo package");
       }
 
       await db.insert(comboSection).values(
@@ -329,23 +334,33 @@ export const comboRouter = router({
     .mutation(async ({ ctx, input }) => {
       const { id, ...data } = input;
       const [combo] = await db
+        .select()
+        .from(comboPackage)
+        .where(eq(comboPackage.id, id))
+        .limit(1);
+
+      assertOwnership(combo, ctx.session.user.id, "Combo");
+
+      const [updated] = await db
         .update(comboPackage)
         .set(data)
-        .where(
-          and(eq(comboPackage.id, id), eq(comboPackage.creatorUserId, ctx.session.user.id)),
-        )
+        .where(eq(comboPackage.id, id))
         .returning();
-      return combo ?? null;
+      return updated ?? null;
     }),
 
   delete: protectedProcedure
     .input(z.object({ id: z.string().uuid() }))
     .mutation(async ({ ctx, input }) => {
-      await db
-        .delete(comboPackage)
-        .where(
-          and(eq(comboPackage.id, input.id), eq(comboPackage.creatorUserId, ctx.session.user.id)),
-        );
+      const [combo] = await db
+        .select()
+        .from(comboPackage)
+        .where(eq(comboPackage.id, input.id))
+        .limit(1);
+
+      assertOwnership(combo, ctx.session.user.id, "Combo");
+
+      await db.delete(comboPackage).where(eq(comboPackage.id, input.id));
       return { success: true };
     }),
 
@@ -355,25 +370,23 @@ export const comboRouter = router({
       z.object({
         examTypeId: z.string().optional(),
         search: z.string().optional(),
-        limit: z.number().min(1).max(50).default(20),
-        offset: z.number().min(0).default(0),
+        ...paginationSchema.shape,
       }).optional(),
     )
     .query(async ({ ctx, input }) => {
       const userId = ctx.session.user.id;
+      const { limit, offset } = paginateDefaults(input);
 
-      // Get packages the user can access (public or owned)
-      const pkgConditions = [
-        and(
-          eq(testPackage.isPublic, true),
-          eq(testPackage.creatorUserId, userId),
-        ),
-      ];
+      const pkgConditions = [];
+      const vis = buildVisibilityCondition(testPackage, userId);
+      if (vis) pkgConditions.push(vis);
 
       if (input?.examTypeId) {
         pkgConditions.push(eq(testPackage.examTypeId, input.examTypeId));
       }
 
+      const pkgWhere = pkgConditions.length > 0 ? and(...pkgConditions) : undefined;
+
       const packages = await db
         .select({
           id: testPackage.id,
@@ -385,14 +398,9 @@ export const comboRouter = router({
         })
         .from(testPackage)
         .leftJoin(examType, eq(testPackage.examTypeId, examType.id))
-        .where(
-          or(
-            eq(testPackage.isPublic, true),
-            eq(testPackage.creatorUserId, userId),
-          ),
-        )
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .where(pkgWhere)
+        .limit(limit)
+        .offset(offset);
 
       const packageIds = packages.map((p) => p.id);
 

packages/api/src/routers/package.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { eq, and, or, desc, sql, inArray } from "drizzle-orm";
+import { eq, and, desc, sql, inArray } from "drizzle-orm";
 import { router, protectedProcedure, publicProcedure } from "../index";
 import { db } from "@labas/db";
 import {
@@ -11,6 +11,10 @@ import {
   sectionType,
   user,
 } from "@labas/db";
+import { paginationSchema, paginateDefaults } from "../lib/pagination";
+import { assertOwnership } from "../lib/ownership";
+import { buildVisibilityCondition } from "../lib/visibility";
+import { throwNotFound, throwBadRequest } from "../lib/errors";
 
 export const packageRouter = router({
   list: publicProcedure
@@ -20,27 +24,22 @@ export const packageRouter = router({
           examTypeId: z.string().optional(),
           isPublic: z.boolean().optional(),
           search: z.string().optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema.shape,
         })
         .optional(),
     )
     .query(async ({ ctx, input }) => {
       const userId = ctx.session?.user.id;
+      const { limit, offset } = paginateDefaults(input);
       const conditions = [];
 
       if (input?.examTypeId) conditions.push(eq(testPackage.examTypeId, input.examTypeId));
 
       if (input?.isPublic !== undefined) {
         conditions.push(eq(testPackage.isPublic, input.isPublic));
-      } else if (!userId) {
-        // Guests: only public packages
-        conditions.push(eq(testPackage.isPublic, true));
       } else {
-        // Logged-in users: public packages + their own private packages
-        conditions.push(
-          or(eq(testPackage.isPublic, true), eq(testPackage.creatorUserId, userId)),
-        );
+        const vis = buildVisibilityCondition(testPackage, userId);
+        if (vis) conditions.push(vis);
       }
 
       const where = conditions.length > 0 ? and(...conditions) : undefined;
@@ -68,8 +67,8 @@ export const packageRouter = router({
         .leftJoin(examType, eq(testPackage.examTypeId, examType.id))
         .where(where)
         .orderBy(desc(testPackage.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })
@@ -86,13 +85,13 @@ export const packageRouter = router({
         .object({
           search: z.string().optional(),
           examTypeId: z.string().optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema.shape,
         })
         .optional(),
     )
     .query(async ({ ctx, input }) => {
       const userId = ctx.session.user.id;
+      const { limit, offset } = paginateDefaults(input);
       const conditions = [eq(testPackage.creatorUserId, userId)];
 
       if (input?.search) {
@@ -127,8 +126,8 @@ export const packageRouter = router({
         .leftJoin(examType, eq(testPackage.examTypeId, examType.id))
         .where(where)
         .orderBy(desc(testPackage.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })
@@ -268,23 +267,33 @@ export const packageRouter = router({
     .mutation(async ({ ctx, input }) => {
       const { id, ...data } = input;
       const [pkg] = await db
+        .select()
+        .from(testPackage)
+        .where(eq(testPackage.id, id))
+        .limit(1);
+
+      assertOwnership(pkg, ctx.session.user.id, "Package");
+
+      const [updated] = await db
         .update(testPackage)
         .set(data)
-        .where(
-          and(eq(testPackage.id, id), eq(testPackage.creatorUserId, ctx.session.user.id)),
-        )
+        .where(eq(testPackage.id, id))
         .returning();
-      return pkg ?? null;
+      return updated ?? null;
     }),
 
   delete: protectedProcedure
     .input(z.object({ id: z.string().uuid() }))
     .mutation(async ({ ctx, input }) => {
-      await db
-        .delete(testPackage)
-        .where(
-          and(eq(testPackage.id, input.id), eq(testPackage.creatorUserId, ctx.session.user.id)),
-        );
+      const [pkg] = await db
+        .select()
+        .from(testPackage)
+        .where(eq(testPackage.id, input.id))
+        .limit(1);
+
+      assertOwnership(pkg, ctx.session.user.id, "Package");
+
+      await db.delete(testPackage).where(eq(testPackage.id, input.id));
       return { success: true };
     }),
 
@@ -304,14 +313,12 @@ export const packageRouter = router({
 
       // Verify ownership
       const [pkg] = await db
-        .select({ creatorUserId: testPackage.creatorUserId })
+        .select()
         .from(testPackage)
         .where(eq(testPackage.id, packageId))
         .limit(1);
 
-      if (!pkg || pkg.creatorUserId !== ctx.session.user.id) {
-        throw new Error("Package not found or not authorized");
-      }
+      assertOwnership(pkg, ctx.session.user.id, "Package");
 
       const [section] = await db
         .insert(packageSection)
@@ -341,17 +348,15 @@ export const packageRouter = router({
         .where(eq(packageSection.id, input.sectionId))
         .limit(1);
 
-      if (!section) throw new Error("Section not found");
+      if (!section) throwNotFound("Section");
 
       const [pkg] = await db
-        .select({ creatorUserId: testPackage.creatorUserId })
+        .select()
         .from(testPackage)
         .where(eq(testPackage.id, section.packageId))
         .limit(1);
 
-      if (!pkg || pkg.creatorUserId !== ctx.session.user.id) {
-        throw new Error("Not authorized");
-      }
+      assertOwnership(pkg, ctx.session.user.id, "Package");
 
       // Count questions in this section
       const [countResult] = await db
@@ -390,17 +395,15 @@ export const packageRouter = router({
         .where(eq(packageSection.id, input.sectionId))
         .limit(1);
 
-      if (!section) throw new Error("Section not found");
+      if (!section) throwNotFound("Section");
 
       const [pkg] = await db
-        .select({ creatorUserId: testPackage.creatorUserId })
+        .select()
         .from(testPackage)
         .where(eq(testPackage.id, section.packageId))
         .limit(1);
 
-      if (!pkg || pkg.creatorUserId !== ctx.session.user.id) {
-        throw new Error("Not authorized");
-      }
+      assertOwnership(pkg, ctx.session.user.id, "Package");
 
       const [sq] = await db
         .insert(sectionQuestion)
@@ -432,7 +435,7 @@ export const packageRouter = router({
         .where(eq(sectionQuestion.id, input.sectionQuestionId))
         .limit(1);
 
-      if (!sq) throw new Error("Section question not found");
+      if (!sq) throwNotFound("Section question");
 
       const [section] = await db
         .select({ packageId: packageSection.packageId })
@@ -440,17 +443,15 @@ export const packageRouter = router({
         .where(eq(packageSection.id, sq.sectionId))
         .limit(1);
 
-      if (!section) throw new Error("Section not found");
+      if (!section) throwNotFound("Section");
 
       const [pkg] = await db
-        .select({ creatorUserId: testPackage.creatorUserId })
+        .select()
         .from(testPackage)
         .where(eq(testPackage.id, section.packageId))
         .limit(1);
 
-      if (!pkg || pkg.creatorUserId !== ctx.session.user.id) {
-        throw new Error("Not authorized");
-      }
+      assertOwnership(pkg, ctx.session.user.id, "Package");
 
       await db
         .delete(sectionQuestion)

packages/api/src/routers/profile.ts

@@ -3,6 +3,7 @@ import { eq, and, desc, sql } from "drizzle-orm";
 import { router, protectedProcedure, publicProcedure } from "../index";
 import { db } from "@labas/db";
 import { testPackage, question, examType, user } from "@labas/db";
+import { throwBadRequest } from "../lib/errors";
 
 export const profileRouter = router({
   getById: publicProcedure
@@ -102,7 +103,7 @@ export const profileRouter = router({
           image: user.image,
         });
 
-      if (!updated) throw new Error("Failed to update profile");
+      if (!updated) throwBadRequest("Failed to update profile");
       return updated;
     }),
 });

packages/api/src/routers/question.ts

@@ -3,6 +3,48 @@ import { eq, and, desc, sql, like, or } from "drizzle-orm";
 import { router, protectedProcedure, publicProcedure } from "../index";
 import { db } from "@labas/db";
 import { question, examType, sectionType, user } from "@labas/db";
+import { paginationSchema, paginateDefaults } from "../lib/pagination";
+import { buildVisibilityCondition } from "../lib/visibility";
+import { assertOwnership } from "../lib/ownership";
+import { throwNotFound } from "../lib/errors";
+
+const questionListSelect = {
+  id: question.id,
+  examTypeId: question.examTypeId,
+  sectionTypeId: question.sectionTypeId,
+  format: question.format,
+  passageText: question.passageText,
+  questionText: question.questionText,
+  options: question.options,
+  correctAnswer: question.correctAnswer,
+  explanation: question.explanation,
+  difficulty: question.difficulty,
+  skillTags: question.skillTags,
+  source: question.source,
+  aiModel: question.aiModel,
+  creatorUserId: question.creatorUserId,
+  isPublic: question.isPublic,
+  usageCount: question.usageCount,
+  avgRating: question.avgRating,
+  createdAt: question.createdAt,
+  updatedAt: question.updatedAt,
+  creatorName: user.name,
+  examTypeName: examType.name,
+  sectionTypeName: sectionType.name,
+};
+
+const questionDetailSelect = {
+  ...questionListSelect,
+};
+
+function buildSearchCondition(term: string) {
+  const pattern = `%${term}%`;
+  return or(
+    like(question.passageText, pattern),
+    like(question.questionText, pattern),
+    like(question.explanation, pattern),
+  );
+}
 
 export const questionRouter = router({
   list: publicProcedure
@@ -17,8 +59,7 @@ export const questionRouter = router({
           creatorUserId: z.string().optional(),
           search: z.string().optional(),
           skillTags: z.array(z.string()).optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema?.shape,
         })
         .optional(),
     )
@@ -31,77 +72,40 @@ export const questionRouter = router({
       if (input?.format) conditions.push(eq(question.format, input.format));
       if (input?.difficulty) conditions.push(eq(question.difficulty, input.difficulty));
       if (input?.skillTags?.length) {
-        conditions.push(
-          sql`${question.skillTags} && ${input.skillTags}`,
-        );
+        conditions.push(sql`${question.skillTags} && ${input.skillTags}`);
       }
 
       if (input?.creatorUserId) {
         conditions.push(eq(question.creatorUserId, input.creatorUserId));
       } else if (input?.isPublic !== undefined) {
         conditions.push(eq(question.isPublic, input.isPublic));
-      } else if (userId) {
-        // Default for authenticated users: show public questions + their own private questions
-        conditions.push(
-          or(eq(question.isPublic, true), eq(question.creatorUserId, userId)),
-        );
       } else {
-        // Default for guests: only public questions
-        conditions.push(eq(question.isPublic, true));
+        const vis = buildVisibilityCondition(question, userId);
+        if (vis) conditions.push(vis);
       }
 
       if (input?.search) {
-        const term = `%${input.search}%`;
-        const searchCond = or(
-          like(question.passageText, term),
-          like(question.questionText, term),
-          like(question.explanation, term),
-        );
+        const searchCond = buildSearchCondition(input.search);
         if (searchCond) conditions.push(searchCond);
       }
 
       const where = conditions.length > 0 ? and(...conditions) : undefined;
+      const { limit, offset } = paginateDefaults(input);
 
       const rows = await db
-        .select({
-          id: question.id,
-          examTypeId: question.examTypeId,
-          sectionTypeId: question.sectionTypeId,
-          format: question.format,
-          passageText: question.passageText,
-          questionText: question.questionText,
-          options: question.options,
-          correctAnswer: question.correctAnswer,
-          explanation: question.explanation,
-          difficulty: question.difficulty,
-          skillTags: question.skillTags,
-          source: question.source,
-          aiModel: question.aiModel,
-          creatorUserId: question.creatorUserId,
-          isPublic: question.isPublic,
-          usageCount: question.usageCount,
-          avgRating: question.avgRating,
-          createdAt: question.createdAt,
-          updatedAt: question.updatedAt,
-          creatorName: user.name,
-          examTypeName: examType.name,
-          sectionTypeName: sectionType.name,
-        })
+        .select(questionListSelect)
         .from(question)
         .leftJoin(user, eq(question.creatorUserId, user.id))
         .leftJoin(examType, eq(question.examTypeId, examType.id))
         .leftJoin(sectionType, eq(question.sectionTypeId, sectionType.id))
         .where(where)
         .orderBy(desc(question.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })
         .from(question)
-        .leftJoin(user, eq(question.creatorUserId, user.id))
-        .leftJoin(examType, eq(question.examTypeId, examType.id))
-        .leftJoin(sectionType, eq(question.sectionTypeId, sectionType.id))
         .where(where);
 
       return { questions: rows, total: Number(countResult?.count ?? 0) };
@@ -112,8 +116,7 @@ export const questionRouter = router({
       z
         .object({
           search: z.string().optional(),
-          limit: z.number().min(1).max(50).default(20),
-          offset: z.number().min(0).default(0),
+          ...paginationSchema?.shape,
         })
         .optional(),
     )
@@ -122,15 +125,12 @@ export const questionRouter = router({
       const conditions = [eq(question.creatorUserId, userId)];
 
       if (input?.search) {
-        const term = `%${input.search}%`;
-        const searchCond = or(
-          like(question.passageText, term),
-          like(question.questionText, term),
-        );
+        const searchCond = buildSearchCondition(input.search);
         if (searchCond) conditions.push(searchCond);
       }
 
       const where = and(...conditions);
+      const { limit, offset } = paginateDefaults(input);
 
       const rows = await db
         .select({
@@ -159,8 +159,8 @@ export const questionRouter = router({
         .leftJoin(sectionType, eq(question.sectionTypeId, sectionType.id))
         .where(where)
         .orderBy(desc(question.createdAt))
-        .limit(input?.limit ?? 20)
-        .offset(input?.offset ?? 0);
+        .limit(limit)
+        .offset(offset);
 
       const [countResult] = await db
         .select({ count: sql<number>`count(*)` })
@@ -175,30 +175,7 @@ export const questionRouter = router({
     .query(async ({ ctx, input }) => {
       const userId = ctx.session?.user.id;
       const [row] = await db
-        .select({
-          id: question.id,
-          examTypeId: question.examTypeId,
-          sectionTypeId: question.sectionTypeId,
-          format: question.format,
-          passageText: question.passageText,
-          questionText: question.questionText,
-          options: question.options,
-          correctAnswer: question.correctAnswer,
-          explanation: question.explanation,
-          difficulty: question.difficulty,
-          skillTags: question.skillTags,
-          source: question.source,
-          aiModel: question.aiModel,
-          creatorUserId: question.creatorUserId,
-          isPublic: question.isPublic,
-          usageCount: question.usageCount,
-          avgRating: question.avgRating,
-          createdAt: question.createdAt,
-          updatedAt: question.updatedAt,
-          creatorName: user.name,
-          examTypeName: examType.name,
-          sectionTypeName: sectionType.name,
-        })
+        .select(questionDetailSelect)
         .from(question)
         .leftJoin(user, eq(question.creatorUserId, user.id))
         .leftJoin(examType, eq(question.examTypeId, examType.id))
@@ -271,12 +248,15 @@ export const questionRouter = router({
     .input(z.object({ id: z.string().uuid() }))
     .mutation(async ({ ctx, input }) => {
       const [existing] = await db
-        .select({ isPublic: question.isPublic })
+        .select({ id: question.id, isPublic: question.isPublic, creatorUserId: question.creatorUserId })
         .from(question)
-        .where(and(eq(question.id, input.id), eq(question.creatorUserId, ctx.session.user.id)))
+        .where(eq(question.id, input.id))
         .limit(1);
 
-      if (!existing) throw new Error("Question not found or not authorized");
+      if (!existing) {
+        throwNotFound("Question");
+      }
+      assertOwnership(existing, ctx.session.user.id, "Question");
 
       const [row] = await db
         .update(question)
@@ -289,9 +269,15 @@ export const questionRouter = router({
   delete: protectedProcedure
     .input(z.object({ id: z.string().uuid() }))
     .mutation(async ({ ctx, input }) => {
-      await db
-        .delete(question)
-        .where(and(eq(question.id, input.id), eq(question.creatorUserId, ctx.session.user.id)));
+      const [existing] = await db
+        .select({ id: question.id, creatorUserId: question.creatorUserId })
+        .from(question)
+        .where(eq(question.id, input.id))
+        .limit(1);
+
+      assertOwnership(existing, ctx.session.user.id, "Question");
+
+      await db.delete(question).where(eq(question.id, input.id));
       return { success: true };
     }),
 });