v3: added site-wide categories, added admin category management, various visual fixes

api/routes/categories.ts

@@ -0,0 +1,117 @@
+import { Router } from "@oak/oak";
+
+import {
+  APIErrorCode,
+  APIException,
+  type APIResponse,
+  type Category,
+  type Dump,
+  isCreateCategoryRequest,
+  isUpdateCategoryRequest,
+  type PaginatedData,
+} from "../model/interfaces.ts";
+
+import { authMiddleware, requirePermission } from "../middleware/auth.ts";
+import { parseOptionalAuth } from "../lib/auth.ts";
+import { parsePagination } from "../lib/pagination.ts";
+import {
+  createCategory,
+  deleteCategory,
+  getCategoryBySlug,
+  listCategories,
+  listDumpsByCategory,
+  updateCategory,
+} from "../services/category-service.ts";
+
+const router = new Router({ prefix: "/api/categories" });
+
+router.get("/", (ctx) => {
+  const responseBody: APIResponse<Category[]> = {
+    success: true,
+    data: listCategories(),
+  };
+  ctx.response.body = responseBody;
+});
+
+router.get("/:slug", (ctx) => {
+  const category = getCategoryBySlug(ctx.params.slug);
+  const responseBody: APIResponse<Category> = {
+    success: true,
+    data: category,
+  };
+  ctx.response.body = responseBody;
+});
+
+router.get("/:slug/dumps", async (ctx) => {
+  const requestingUserId = await parseOptionalAuth(ctx) ?? undefined;
+  const { page, limit } = parsePagination(ctx.request.url.searchParams);
+  const { items, total } = listDumpsByCategory(
+    ctx.params.slug,
+    page,
+    limit,
+    requestingUserId,
+  );
+  const responseBody: APIResponse<PaginatedData<Dump>> = {
+    success: true,
+    data: { items, total, hasMore: page * limit < total },
+  };
+  ctx.response.body = responseBody;
+});
+
+router.post(
+  "/",
+  authMiddleware,
+  requirePermission("category:manage"),
+  async (ctx) => {
+    const body = await ctx.request.body.json();
+    if (!isCreateCategoryRequest(body)) {
+      throw new APIException(
+        APIErrorCode.VALIDATION_ERROR,
+        400,
+        "Invalid category data",
+      );
+    }
+    const category = createCategory(body);
+    const responseBody: APIResponse<Category> = {
+      success: true,
+      data: category,
+    };
+    ctx.response.status = 201;
+    ctx.response.body = responseBody;
+  },
+);
+
+router.put(
+  "/:id",
+  authMiddleware,
+  requirePermission("category:manage"),
+  async (ctx) => {
+    const body = await ctx.request.body.json();
+    if (!isUpdateCategoryRequest(body)) {
+      throw new APIException(
+        APIErrorCode.VALIDATION_ERROR,
+        400,
+        "Invalid category data",
+      );
+    }
+    const category = updateCategory(ctx.params.id, body);
+    const responseBody: APIResponse<Category> = {
+      success: true,
+      data: category,
+    };
+    ctx.response.body = responseBody;
+  },
+);
+
+router.delete(
+  "/:id",
+  authMiddleware,
+  requirePermission("category:manage"),
+  (ctx) => {
+    deleteCategory(ctx.params.id);
+    const responseBody: APIResponse<null> = { success: true, data: null };
+    ctx.response.body = responseBody;
+  },
+);
+
+export default router;

api/routes/dumps.ts

@@ -33,6 +33,19 @@ import { getRelatedDumps } from "../services/backlink-service.ts";
 
 const router = new Router({ prefix: "/api/dumps" });
 
+// Categories arrive on the multipart create path as a JSON-encoded string field.
+function parseCategoryIds(value: FormDataEntryValue | null): string[] {
+  if (typeof value !== "string" || !value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed)
+      ? parsed.filter((v): v is string => typeof v === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
 router.post(
   "/",
   authMiddleware,
@@ -63,6 +76,7 @@ router.post(
         userId,
         isPrivate,
         typeof title === "string" && title ? title : undefined,
+        parseCategoryIds(formData.get("categoryIds")),
       );
     } else {
       const body = await ctx.request.body.json();
@@ -156,6 +170,9 @@ router.put("/:dumpId/file", authMiddleware, async (ctx) => {
     file,
     typeof comment === "string" && comment ? comment : undefined,
     typeof title === "string" && title ? title : undefined,
+    formData.has("categoryIds")
+      ? parseCategoryIds(formData.get("categoryIds"))
+      : undefined,
   );
   const responseBody: APIResponse<Dump> = { success: true, data: updatedDump };
   ctx.response.body = responseBody;

api/routes/follows.ts

@@ -16,6 +16,20 @@ import {
   unfollowPlaylist,
   unfollowUser,
 } from "../services/follow-service.ts";
+import { getCategoryIdBySlug } from "../services/category-service.ts";
+
+// Resolves the optional ?category=<slug> filter. Returns the matching category
+// id, or "missing" when a slug was given but matches nothing (so the feed comes
+// back empty rather than unfiltered), or undefined when no filter was requested.
+function resolveCategoryFilter(
+  params: URLSearchParams,
+): string | "missing" | undefined {
+  const slug = params.get("category");
+  if (!slug) return undefined;
+  return getCategoryIdBySlug(slug) ?? "missing";
+}
+
+const EMPTY_FEED: { items: Dump[]; total: number } = { items: [], total: 0 };
 
 const router = new Router({ prefix: "/api/follows" });
 
@@ -31,11 +45,10 @@ router.get("/status", authMiddleware, (ctx) => {
 // GET /api/follows/feed/users?page=&limit=
 router.get("/feed/users", authMiddleware, (ctx) => {
   const { page, limit } = parsePagination(ctx.request.url.searchParams);
-  const { items, total } = getFollowedUsersDumpFeed(
-    ctx.state.user.userId,
-    page,
-    limit,
-  );
+  const categoryId = resolveCategoryFilter(ctx.request.url.searchParams);
+  const { items, total } = categoryId === "missing"
+    ? EMPTY_FEED
+    : getFollowedUsersDumpFeed(ctx.state.user.userId, page, limit, categoryId);
   const data: PaginatedData<Dump> = {
     items,
     total,
@@ -48,11 +61,15 @@ router.get("/feed/users", authMiddleware, (ctx) => {
 // GET /api/follows/feed/playlists?page=&limit=
 router.get("/feed/playlists", authMiddleware, (ctx) => {
   const { page, limit } = parsePagination(ctx.request.url.searchParams);
-  const { items, total } = getFollowedPlaylistsDumpFeed(
-    ctx.state.user.userId,
-    page,
-    limit,
-  );
+  const categoryId = resolveCategoryFilter(ctx.request.url.searchParams);
+  const { items, total } = categoryId === "missing"
+    ? EMPTY_FEED
+    : getFollowedPlaylistsDumpFeed(
+      ctx.state.user.userId,
+      page,
+      limit,
+      categoryId,
+    );
   const data: PaginatedData<Dump> = {
     items,
     total,