@itsmrtr/bunkoshelf 1.14.1 → 1.16.0

package/dist/src/lib/db/appSettings.ts

@@ -0,0 +1,25 @@
+import { queryOne, execute } from "./query";
+import type { ParentalControlMode } from "@/lib/parentalControl";
+
+export interface AppSettings {
+  parentalControlEnabled: boolean;
+  parentalControlMode: ParentalControlMode;
+}
+
+export async function getAppSettings(): Promise<AppSettings> {
+  const row = await queryOne<{ parental_control_enabled: boolean; parental_control_mode: ParentalControlMode }>(
+    "SELECT parental_control_enabled, parental_control_mode FROM app_settings WHERE id = 'global' LIMIT 1"
+  );
+
+  return {
+    parentalControlEnabled: row?.parental_control_enabled ?? false,
+    parentalControlMode: row?.parental_control_mode ?? "flexible",
+  };
+}
+
+export async function updateParentalControlEnabled(enabled: boolean, mode: ParentalControlMode): Promise<void> {
+  await execute(
+    "UPDATE app_settings SET parental_control_enabled = $1, parental_control_mode = $2, updated_at = NOW() WHERE id = 'global'",
+    [enabled, mode]
+  );
+}

package/dist/src/lib/db/books/library.ts

@@ -2,6 +2,8 @@ import { createId } from "@paralleldrive/cuid2";
 import { buildNaturalSortKey } from "@/lib/naturalSort";
 import type { EpubMetadata } from "@/lib/books/types";
 import { execute, query, queryOne } from "../query";
+import { getCurrentContentVisibilityPolicy } from "@/lib/parentalControlServer";
+import { canViewAgeRating } from "@/lib/parentalControl";
 
 export type BookLibrarySection = "books" | "other";
 
@@ -41,6 +43,13 @@ export interface BookSearchEntry {
   librarySection: BookLibrarySection;
   writer: string;
   subjects: string;
+  ageRating: string | null;
+}
+
+export interface BookSubjectFilter {
+  subject: string;
+  name: string;
+  type: "genre" | "tag";
 }
 
 interface BookRow {
@@ -170,6 +179,11 @@ async function hydrateMetadata(volume: BookVolume): Promise<BookVolume> {
   return volume;
 }
 
+async function filterVisibleBooks(books: BookVolume[]): Promise<BookVolume[]> {
+  const policy = await getCurrentContentVisibilityPolicy();
+  return books.filter((book) => canViewAgeRating(book.metadata.ageRating, "book", policy));
+}
+
 export async function upsertBook(input: {
   seriesTitle: string;
   seriesPath: string;
@@ -240,27 +254,35 @@ export async function upsertBook(input: {
   ]);
   await execute(`DELETE FROM book_series
     WHERE id <> $1 AND NOT EXISTS (SELECT 1 FROM book_volumes WHERE book_volumes.series_id = book_series.id)`, [series.id]);
-  const result = await findBookVolumeBySlug(input.volumeSlug);
+  const result = await findBookVolumeBySlugRaw(input.volumeSlug);
   if (!result) throw new Error("Failed to read indexed book");
   return result;
 }
 
 export async function findBookVolumeBySlug(slug: string): Promise<BookVolume | null> {
+  const volume = await findBookVolumeBySlugRaw(slug);
+  return (await filterVisibleBooks(volume ? [volume] : []))[0] ?? null;
+}
+
+async function findBookVolumeBySlugRaw(slug: string): Promise<BookVolume | null> {
   const row = await queryOne<BookRow>(`${BOOK_SELECT} WHERE bv.slug = $1 LIMIT 1`, [slug]);
   return row ? hydrateMetadata(mapBook(row)) : null;
 }
 
 export async function findBookFileBySlug(slug: string): Promise<{ filename: string; fullPath: string } | null> {
-  const row = await queryOne<{ filename: string; full_path: string }>(
-    "SELECT filename, full_path FROM book_volumes WHERE slug = $1 LIMIT 1",
+  const row = await queryOne<{ filename: string; full_path: string; age_rating: string | null }>(
+    "SELECT bv.filename, bv.full_path, bm.age_rating FROM book_volumes bv INNER JOIN book_metadata bm ON bm.volume_id = bv.id WHERE bv.slug = $1 LIMIT 1",
     [slug],
   );
-  return row ? { filename: row.filename, fullPath: row.full_path } : null;
+  const policy = await getCurrentContentVisibilityPolicy();
+  return row && canViewAgeRating(row.age_rating, "book", policy) ? { filename: row.filename, fullPath: row.full_path } : null;
 }
 
 export async function listBookVolumes(options?: {
   seriesSlug?: string;
   authorNames?: string[];
+  genreNames?: string[];
+  tagNames?: string[];
   limit?: number;
   librarySection?: BookLibrarySection;
 }): Promise<BookVolume[]> {
@@ -303,16 +325,189 @@ export async function listBookVolumes(options?: {
     `);
   }
 
+  if (options?.genreNames && options.genreNames.length > 0) {
+    for (const genreName of options.genreNames) {
+      params.push(genreName);
+      const genreParam = params.length;
+      conditions.push(`
+        EXISTS (
+          SELECT 1
+          FROM book_subjects bsub
+          INNER JOIN book_metadata subject_metadata ON subject_metadata.id = bsub.metadata_id
+          WHERE subject_metadata.volume_id = bv.id
+            AND LOWER(BTRIM(bsub.name)) = LOWER(BTRIM($${genreParam}))
+            AND EXISTS (
+              SELECT 1
+              FROM genres g
+              INNER JOIN volume_to_genres vtg ON vtg.genre_id = g.id
+              WHERE LOWER(BTRIM(g.name)) = LOWER(BTRIM(bsub.name))
+            )
+        )
+      `);
+    }
+  }
+
+  if (options?.tagNames && options.tagNames.length > 0) {
+    for (const tagName of options.tagNames) {
+      params.push(tagName);
+      const tagParam = params.length;
+      conditions.push(`
+        EXISTS (
+          SELECT 1
+          FROM book_subjects bsub
+          INNER JOIN book_metadata subject_metadata ON subject_metadata.id = bsub.metadata_id
+          WHERE subject_metadata.volume_id = bv.id
+            AND LOWER(BTRIM(bsub.name)) = LOWER(BTRIM($${tagParam}))
+            AND NOT EXISTS (
+              SELECT 1
+              FROM genres g
+              INNER JOIN volume_to_genres vtg ON vtg.genre_id = g.id
+              WHERE LOWER(BTRIM(g.name)) = LOWER(BTRIM(bsub.name))
+            )
+        )
+      `);
+    }
+  }
+
   const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
   const limit = options?.limit ?? 100;
   params.push(limit);
   const rows = await query<BookRow>(`${BOOK_SELECT}${where} ORDER BY bs.sort_title, bv.number NULLS LAST, bv.sort_title LIMIT $${params.length}`, params);
-  return Promise.all(rows.map((row) => hydrateMetadata(mapBook(row))));
+  return filterVisibleBooks(await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row)))));
+}
+
+export async function listBookLibraryFilters(): Promise<{
+  authors: Array<{ id: string; name: string }>;
+  genres: Array<{ id: string; name: string }>;
+  tags: Array<{ id: string; name: string }>;
+}> {
+  const [authors, genres, tags] = await Promise.all([
+    query<{ id: string; name: string }>(`
+      SELECT DISTINCT author.name AS id, author.name
+      FROM book_volumes bv
+      INNER JOIN book_series bs ON bs.id = bv.series_id
+      INNER JOIN book_metadata bm ON bm.volume_id = bv.id
+      CROSS JOIN LATERAL (
+        SELECT BTRIM(bp.name) AS name
+        FROM book_people bp
+        WHERE bp.metadata_id = bm.id
+          AND bp.kind = 'creator'
+          AND (bp.role IS NULL OR LOWER(bp.role) = 'aut')
+          AND BTRIM(bp.name) <> ''
+
+        UNION ALL
+
+        SELECT '__unknown__'
+        WHERE NOT EXISTS (
+          SELECT 1
+          FROM book_people bp
+          WHERE bp.metadata_id = bm.id
+            AND bp.kind = 'creator'
+            AND (bp.role IS NULL OR LOWER(bp.role) = 'aut')
+            AND BTRIM(bp.name) <> ''
+        )
+      ) AS author
+      WHERE bs.library_section = 'books'
+      ORDER BY name ASC
+    `),
+    query<{ id: string; name: string }>(`
+      SELECT DISTINCT g.id, g.name
+      FROM genres g
+      INNER JOIN volume_to_genres vtg ON vtg.genre_id = g.id
+      WHERE EXISTS (
+        SELECT 1
+        FROM book_subjects bsub
+        INNER JOIN book_metadata bm ON bm.id = bsub.metadata_id
+        INNER JOIN book_volumes bv ON bv.id = bm.volume_id
+        INNER JOIN book_series bs ON bs.id = bv.series_id
+        WHERE bs.library_section = 'books'
+          AND LOWER(BTRIM(bsub.name)) = LOWER(BTRIM(g.name))
+      )
+      ORDER BY g.name ASC
+    `),
+    query<{ id: string; name: string }>(`
+      WITH active_genres AS (
+        SELECT DISTINCT LOWER(BTRIM(g.name)) AS normalized_name
+        FROM genres g
+        INNER JOIN volume_to_genres vtg ON vtg.genre_id = g.id
+      ),
+      active_tags AS (
+        SELECT DISTINCT ON (LOWER(BTRIM(t.name)))
+          LOWER(BTRIM(t.name)) AS normalized_name,
+          t.id,
+          t.name
+        FROM tags t
+        INNER JOIN volume_to_tags vtt ON vtt.tag_id = t.id
+        ORDER BY LOWER(BTRIM(t.name)), t.name
+      ),
+      book_subjects_without_genres AS (
+        SELECT DISTINCT ON (LOWER(BTRIM(bsub.name)))
+          LOWER(BTRIM(bsub.name)) AS normalized_name,
+          BTRIM(bsub.name) AS name
+        FROM book_subjects bsub
+        INNER JOIN book_metadata bm ON bm.id = bsub.metadata_id
+        INNER JOIN book_volumes bv ON bv.id = bm.volume_id
+        INNER JOIN book_series bs ON bs.id = bv.series_id
+        WHERE bs.library_section = 'books'
+          AND BTRIM(bsub.name) <> ''
+          AND NOT EXISTS (
+            SELECT 1
+            FROM active_genres ag
+            WHERE ag.normalized_name = LOWER(BTRIM(bsub.name))
+          )
+        ORDER BY LOWER(BTRIM(bsub.name)), BTRIM(bsub.name)
+      )
+      SELECT COALESCE(at.id, bswg.normalized_name) AS id, COALESCE(at.name, bswg.name) AS name
+      FROM book_subjects_without_genres bswg
+      LEFT JOIN active_tags at ON at.normalized_name = bswg.normalized_name
+      ORDER BY name ASC
+    `),
+  ]);
+
+  return { authors, genres, tags };
+}
+
+export async function classifyBookSubjects(subjectNames: string[]): Promise<BookSubjectFilter[]> {
+  const subjects = subjectNames.map((subject) => subject.trim()).filter(Boolean);
+  if (!subjects.length) return [];
+
+  return query<BookSubjectFilter>(`
+    WITH requested_subjects AS (
+      SELECT DISTINCT BTRIM(subject.name) AS subject
+      FROM unnest($1::text[]) AS subject(name)
+      WHERE BTRIM(subject.name) <> ''
+    ),
+    active_genres AS (
+      SELECT DISTINCT ON (LOWER(BTRIM(g.name)))
+        LOWER(BTRIM(g.name)) AS normalized_name,
+        g.name
+      FROM genres g
+      INNER JOIN volume_to_genres vtg ON vtg.genre_id = g.id
+      ORDER BY LOWER(BTRIM(g.name)), g.name
+    ),
+    active_tags AS (
+      SELECT DISTINCT ON (LOWER(BTRIM(t.name)))
+        LOWER(BTRIM(t.name)) AS normalized_name,
+        t.name
+      FROM tags t
+      INNER JOIN volume_to_tags vtt ON vtt.tag_id = t.id
+      ORDER BY LOWER(BTRIM(t.name)), t.name
+    )
+    SELECT
+      requested_subjects.subject,
+      COALESCE(active_genres.name, active_tags.name, requested_subjects.subject) AS name,
+      CASE WHEN active_genres.name IS NOT NULL THEN 'genre' ELSE 'tag' END AS type
+    FROM requested_subjects
+    LEFT JOIN active_genres
+      ON active_genres.normalized_name = LOWER(requested_subjects.subject)
+    LEFT JOIN active_tags
+      ON active_tags.normalized_name = LOWER(requested_subjects.subject)
+  `, [subjects]);
 }
 
 export async function listRecentlyAddedBooks(limit = 8, librarySection: BookLibrarySection = "books"): Promise<BookVolume[]> {
   const rows = await query<BookRow>(`${BOOK_SELECT} WHERE bs.library_section = $1 ORDER BY bv.created_at DESC LIMIT $2`, [librarySection, limit]);
-  return Promise.all(rows.map((row) => hydrateMetadata(mapBook(row))));
+  return filterVisibleBooks(await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row)))));
 }
 
 export async function listFavoriteBookSeries(userId: string, options: { page: number; pageSize: number }) {
@@ -353,7 +548,7 @@ export async function listFavoriteBookVolumes(userId: string, options: { page: n
     WHERE ub.user_id = $1 AND ub.is_favorite = TRUE AND bs.library_section = 'books'
     ORDER BY bs.sort_title, bv.number NULLS LAST, bv.sort_title
     LIMIT $2 OFFSET $3`, [userId, options.pageSize, offset]);
-  const items = await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row))));
+  const items = await filterVisibleBooks(await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row)))));
 
   return { items, total, totalPages: Math.max(1, Math.ceil(total / options.pageSize)) };
 }
@@ -364,11 +559,12 @@ export async function listBooksInProgress(userId: string, limit = 12, librarySec
     INNER JOIN user_to_books ub ON ub.volume_id = bv.id
     WHERE ub.user_id = $1 AND ub.cfi IS NOT NULL AND ub.is_read = FALSE AND bs.library_section = $2
     ORDER BY ub.last_read_at DESC NULLS LAST LIMIT $3`, [userId, librarySection, limit]);
-  const books = await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row))));
-  return books.map((book, index) => ({
+  const books = await filterVisibleBooks(await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row)))));
+  const progressById = new Map(rows.map((row) => [row.volume_id, row]));
+  return books.map((book) => ({
     ...book,
-    progression: Number(rows[index].progression ?? 0),
-    lastReadAt: rows[index].last_read_at,
+    progression: Number(progressById.get(book.id)?.progression ?? 0),
+    lastReadAt: progressById.get(book.id)?.last_read_at ?? null,
   }));
 }
 
@@ -410,7 +606,7 @@ export async function listRecentlyReadBooks(userId: string, limit = 12): Promise
     INNER JOIN user_to_books ub ON ub.volume_id = bv.id
     WHERE ub.user_id = $1 AND ub.is_read = TRUE AND ub.last_read_at IS NOT NULL AND bs.library_section = 'books'
     ORDER BY ub.last_read_at DESC LIMIT $2`, [userId, limit]);
-  return Promise.all(rows.map((row) => hydrateMetadata(mapBook(row))));
+  return filterVisibleBooks(await Promise.all(rows.map((row) => hydrateMetadata(mapBook(row)))));
 }
 
 export async function listBookSeries(): Promise<Array<BookSeries & { volumeCount: number }>> {
@@ -424,8 +620,8 @@ export async function listBookSeries(): Promise<Array<BookSeries & { volumeCount
 }
 
 export async function listBookSearchEntries(): Promise<BookSearchEntry[]> {
-  return query<BookSearchEntry>(`
-    SELECT bv.id, bv.slug, bm.title,
+  const entries = await query<BookSearchEntry>(`
+    SELECT bv.id, bv.slug, bm.title, bm.age_rating AS "ageRating",
       bs.id AS "seriesId", bs.slug AS "seriesSlug", bs.title AS "seriesTitle",
       bs.is_oneshot AS "seriesIsOneshot", bs.library_section AS "librarySection",
       COALESCE(
@@ -445,9 +641,11 @@ export async function listBookSearchEntries(): Promise<BookSearchEntry[]> {
     INNER JOIN book_metadata bm ON bm.volume_id = bv.id
     LEFT JOIN book_people bp ON bp.metadata_id = bm.id
     LEFT JOIN book_subjects bsub ON bsub.metadata_id = bm.id
-    GROUP BY bv.id, bv.slug, bv.number, bv.sort_title, bm.title, bs.id, bs.slug, bs.title, bs.is_oneshot, bs.library_section, bs.sort_title
+    GROUP BY bv.id, bv.slug, bv.number, bv.sort_title, bm.title, bm.age_rating, bs.id, bs.slug, bs.title, bs.is_oneshot, bs.library_section, bs.sort_title
     ORDER BY bs.sort_title, bv.number NULLS LAST, bv.sort_title
   `);
+  const policy = await getCurrentContentVisibilityPolicy();
+  return entries.filter((entry) => canViewAgeRating(entry.ageRating, "book", policy));
 }
 
 export async function findBookSeriesBySlug(slug: string): Promise<BookSeries | null> {

package/dist/src/lib/db/clubs.ts

@@ -1,5 +1,7 @@
 import { createId } from "@paralleldrive/cuid2";
 import { createHmac, timingSafeEqual } from "node:crypto";
+import { getBookCoverUrl } from "@/lib/books/cover";
+import { getMangaCoverUrl } from "@/lib/mangaCover";
 import { execute, query, queryOne } from "./query";
 
 export type ClubMemberStatus = "PENDING" | "APPROVED" | "REJECTED" | "REVOKED";
@@ -14,6 +16,14 @@ export interface ReadingClub {
   ownerId: string;
   status: "ACTIVE" | "ARCHIVED";
   createdAt: Date;
+  participantCount: number;
+  membershipStatus: ClubMemberStatus | null;
+  workTitle: string | null;
+  workCover: string | null;
+  workSourceType: ClubSourceType | null;
+  workSection: string | null;
+  workIsOneshot: boolean;
+  workVotes: number | null;
 }
 
 export interface ClubMember {
@@ -34,11 +44,55 @@ export interface ClubCycle {
   selectedType: ClubSourceType | null;
   selectedId: string | null;
   workTitle: string | null;
+  workCover: string | null;
   startedAt: Date | null;
 }
 
+export interface ClubCandidate {
+  id: string;
+  source_type: ClubSourceType;
+  source_id: string;
+  title: string | null;
+  section: string | null;
+  is_oneshot: boolean;
+  votes: string;
+  cover: string | null;
+}
+
+function getWorkCover(row: Record<string, unknown>): string | null {
+  if (row.source_type === "LIBRARY_SERIES" && typeof row.library_cover_slug === "string") {
+    return getMangaCoverUrl({
+      slug: row.library_cover_slug,
+      coverImage: row.library_cover_image as string | null,
+      updatedAt: row.library_cover_updated_at as Date | string | null,
+    });
+  }
+
+  if (row.source_type === "BOOK_SERIES" && typeof row.book_cover_slug === "string") {
+    return getBookCoverUrl(row.book_cover_slug, row.book_cover_path as string | null);
+  }
+
+  return null;
+}
+
 function mapClub(row: Record<string, unknown>): ReadingClub {
-  return { id: row.id as string, slug: row.slug as string, name: row.name as string, description: row.description as string | null, ownerId: row.owner_id as string, status: row.status as ReadingClub["status"], createdAt: row.created_at as Date };
+  return {
+    id: row.id as string,
+    slug: row.slug as string,
+    name: row.name as string,
+    description: row.description as string | null,
+    ownerId: row.owner_id as string,
+    status: row.status as ReadingClub["status"],
+    createdAt: row.created_at as Date,
+    participantCount: Number(row.participant_count ?? 0),
+    membershipStatus: (row.membership_status as ClubMemberStatus | null) ?? null,
+    workTitle: (row.work_title as string | null) ?? null,
+    workCover: getWorkCover(row),
+    workSourceType: (row.source_type as ClubSourceType | null) ?? null,
+    workSection: (row.work_section as string | null) ?? null,
+    workIsOneshot: row.work_is_oneshot === true,
+    workVotes: row.work_votes === null || row.work_votes === undefined ? null : Number(row.work_votes),
+  };
 }
 
 export async function findClubBySlug(slug: string): Promise<ReadingClub | null> {
@@ -46,12 +100,69 @@ export async function findClubBySlug(slug: string): Promise<ReadingClub | null>
   return row ? mapClub(row) : null;
 }
 
-export async function listClubsForUser(userId: string): Promise<ReadingClub[]> {
+export async function listClubsForUser(userId: string, options?: { includePublic?: boolean }): Promise<ReadingClub[]> {
   const rows = await query<Record<string, unknown>>(`
-    SELECT DISTINCT c.* FROM reading_clubs c
-    LEFT JOIN reading_club_members m ON m.club_id = c.id
-    WHERE c.owner_id = $1 OR (m.user_id = $1 AND m.status = 'APPROVED')
-    ORDER BY c.status, c.created_at DESC`, [userId]);
+    SELECT c.*, members.participant_count, viewer.status AS membership_status, COALESCE(library_series.title, book_series.title) AS work_title,
+      selected.source_type,
+      COALESCE(library_series.library_section, book_series.library_section) AS work_section,
+      COALESCE(library_series.is_oneshot, book_series.is_oneshot, FALSE) AS work_is_oneshot,
+      selected.votes AS work_votes,
+      library_cover.slug AS library_cover_slug, library_cover.cover_image AS library_cover_image, library_cover.updated_at AS library_cover_updated_at,
+      book_cover.slug AS book_cover_slug, book_cover.cover_path AS book_cover_path
+    FROM reading_clubs c
+    LEFT JOIN LATERAL (
+      SELECT COUNT(*)::text AS participant_count
+      FROM reading_club_members member_count
+      WHERE member_count.club_id = c.id AND member_count.status = 'APPROVED'
+    ) members ON TRUE
+    LEFT JOIN LATERAL (
+      SELECT membership.status
+      FROM reading_club_members membership
+      WHERE membership.club_id = c.id AND membership.user_id = $1
+    ) viewer ON TRUE
+    LEFT JOIN LATERAL (
+      SELECT source_type, source_id, votes
+      FROM (
+        SELECT cycle.selected_type AS source_type, cycle.selected_id AS source_id, 0 AS priority, NULL::int AS votes
+        FROM reading_club_cycles cycle
+        WHERE cycle.club_id = c.id AND cycle.status = 'READING'
+
+        UNION ALL
+
+        SELECT candidate.source_type, candidate.source_id, 1 AS priority, COUNT(vote.id)::int AS votes
+        FROM reading_club_cycles cycle
+        INNER JOIN reading_club_candidates candidate ON candidate.cycle_id = cycle.id
+        LEFT JOIN reading_club_votes vote ON vote.candidate_id = candidate.id
+        WHERE cycle.club_id = c.id AND cycle.status = 'VOTING'
+        GROUP BY candidate.id
+      ) work
+      WHERE source_id IS NOT NULL
+      ORDER BY priority, votes DESC, source_id
+      LIMIT 1
+    ) selected ON TRUE
+    LEFT JOIN library_series ON selected.source_type = 'LIBRARY_SERIES' AND library_series.id = selected.source_id
+    LEFT JOIN book_series ON selected.source_type = 'BOOK_SERIES' AND book_series.id = selected.source_id
+    LEFT JOIN LATERAL (
+      SELECT volume.slug, volume.cover_image, volume.updated_at
+      FROM library_volumes volume
+      WHERE selected.source_type = 'LIBRARY_SERIES' AND volume.series_id = selected.source_id
+      ORDER BY volume.created_at
+      LIMIT 1
+    ) library_cover ON TRUE
+    LEFT JOIN LATERAL (
+      SELECT volume.slug, metadata.cover_path
+      FROM book_volumes volume
+      INNER JOIN book_metadata metadata ON metadata.volume_id = volume.id
+      WHERE selected.source_type = 'BOOK_SERIES' AND volume.series_id = selected.source_id
+      ORDER BY volume.number NULLS FIRST, volume.title
+      LIMIT 1
+    ) book_cover ON TRUE
+    WHERE ($2::boolean AND c.status = 'ACTIVE') OR c.owner_id = $1 OR EXISTS (
+      SELECT 1
+      FROM reading_club_members membership
+      WHERE membership.club_id = c.id AND membership.user_id = $1 AND membership.status = 'APPROVED'
+    )
+    ORDER BY c.status, c.created_at DESC`, [userId, options?.includePublic ?? false]);
   return rows.map(mapClub);
 }
 
@@ -119,7 +230,17 @@ export async function createCycleRecord(clubId: string, title: string, voteClose
 }
 
 function mapCycle(row: Record<string, unknown>): ClubCycle {
-  return { id: row.id as string, title: row.title as string, status: row.status as ClubCycleStatus, voteClosesAt: row.vote_closes_at as Date | null, selectedType: row.selected_type as ClubSourceType | null, selectedId: row.selected_id as string | null, workTitle: row.work_title as string | null, startedAt: row.started_at as Date | null };
+  return {
+    id: row.id as string,
+    title: row.title as string,
+    status: row.status as ClubCycleStatus,
+    voteClosesAt: row.vote_closes_at as Date | null,
+    selectedType: row.selected_type as ClubSourceType | null,
+    selectedId: row.selected_id as string | null,
+    workTitle: (row.work_title as string | null) ?? null,
+    workCover: getWorkCover(row),
+    startedAt: row.started_at as Date | null,
+  };
 }
 
 export async function addCandidateRecord(cycleId: string, sourceType: ClubSourceType, sourceId: string): Promise<void> {
@@ -166,9 +287,27 @@ export async function getClubDashboard(club: ReadingClub, userId: string) {
     query<Record<string, unknown>>(`SELECT m.id,m.user_id,u.username,u.name,u.role,m.status
       FROM reading_club_members m INNER JOIN users u ON u.id=m.user_id WHERE m.club_id=$1 AND m.status <> 'REVOKED' ORDER BY m.status, COALESCE(u.name,u.username)`, [club.id]),
     query<Record<string, unknown>>(`SELECT c.id,c.title,c.status,c.vote_closes_at,c.selected_type,c.selected_id,c.started_at,
-      COALESCE(ls.title,bs.title) AS work_title FROM reading_club_cycles c
+      COALESCE(ls.title,bs.title) AS work_title,
+      library_cover.slug AS library_cover_slug, library_cover.cover_image AS library_cover_image, library_cover.updated_at AS library_cover_updated_at,
+      book_cover.slug AS book_cover_slug, book_cover.cover_path AS book_cover_path
+      FROM reading_club_cycles c
       LEFT JOIN library_series ls ON c.selected_type='LIBRARY_SERIES' AND ls.id=c.selected_id
       LEFT JOIN book_series bs ON c.selected_type='BOOK_SERIES' AND bs.id=c.selected_id
+      LEFT JOIN LATERAL (
+        SELECT volume.slug, volume.cover_image, volume.updated_at
+        FROM library_volumes volume
+        WHERE c.selected_type='LIBRARY_SERIES' AND volume.series_id=c.selected_id
+        ORDER BY volume.created_at
+        LIMIT 1
+      ) library_cover ON TRUE
+      LEFT JOIN LATERAL (
+        SELECT volume.slug, metadata.cover_path
+        FROM book_volumes volume
+        INNER JOIN book_metadata metadata ON metadata.volume_id=volume.id
+        WHERE c.selected_type='BOOK_SERIES' AND volume.series_id=c.selected_id
+        ORDER BY volume.number NULLS FIRST, volume.title
+        LIMIT 1
+      ) book_cover ON TRUE
       WHERE c.club_id=$1 ORDER BY c.created_at DESC`, [club.id]),
     query<{ id: string; type: string; created_at: Date; username: string; name: string | null; label: string | null }>(`
       SELECT a.id,a.type,a.created_at,u.username,u.name,ms.label FROM reading_club_activities a
@@ -209,13 +348,47 @@ export async function listClubWorks() {
   return [...library.map((work) => ({ ...work, type: "LIBRARY_SERIES" as const })), ...books.map((work) => ({ ...work, type: "BOOK_SERIES" as const }))];
 }
 
-export async function listCycleCandidates(cycleId: string) {
-  return query<{ id: string; source_type: ClubSourceType; source_id: string; title: string | null; section: string | null; is_oneshot: boolean; votes: string }>(`
-    SELECT ca.id,ca.source_type,ca.source_id,COALESCE(ls.title,bs.title) AS title,COALESCE(ls.library_section,bs.library_section) AS section,COALESCE(ls.is_oneshot,bs.is_oneshot,FALSE) AS is_oneshot,COUNT(v.id)::text AS votes
+export async function listCycleCandidates(cycleId: string): Promise<ClubCandidate[]> {
+  const rows = await query<Record<string, unknown>>(`
+    SELECT ca.id,ca.source_type,ca.source_id,COALESCE(ls.title,bs.title) AS title,COALESCE(ls.library_section,bs.library_section) AS section,COALESCE(ls.is_oneshot,bs.is_oneshot,FALSE) AS is_oneshot,
+      vote_count.votes,
+      library_cover.slug AS library_cover_slug, library_cover.cover_image AS library_cover_image, library_cover.updated_at AS library_cover_updated_at,
+      book_cover.slug AS book_cover_slug, book_cover.cover_path AS book_cover_path
     FROM reading_club_candidates ca LEFT JOIN library_series ls ON ca.source_type='LIBRARY_SERIES' AND ls.id=ca.source_id
     LEFT JOIN book_series bs ON ca.source_type='BOOK_SERIES' AND bs.id=ca.source_id
-    LEFT JOIN reading_club_votes v ON v.candidate_id=ca.id WHERE ca.cycle_id=$1
-    GROUP BY ca.id,ls.title,bs.title,ls.library_section,bs.library_section,ls.is_oneshot,bs.is_oneshot ORDER BY title`, [cycleId]);
+    LEFT JOIN LATERAL (
+      SELECT COUNT(*)::text AS votes
+      FROM reading_club_votes vote
+      WHERE vote.candidate_id=ca.id
+    ) vote_count ON TRUE
+    LEFT JOIN LATERAL (
+      SELECT volume.slug, volume.cover_image, volume.updated_at
+      FROM library_volumes volume
+      WHERE ca.source_type='LIBRARY_SERIES' AND volume.series_id=ca.source_id
+      ORDER BY volume.created_at
+      LIMIT 1
+    ) library_cover ON TRUE
+    LEFT JOIN LATERAL (
+      SELECT volume.slug, metadata.cover_path
+      FROM book_volumes volume
+      INNER JOIN book_metadata metadata ON metadata.volume_id=volume.id
+      WHERE ca.source_type='BOOK_SERIES' AND volume.series_id=ca.source_id
+      ORDER BY volume.number NULLS FIRST, volume.title
+      LIMIT 1
+    ) book_cover ON TRUE
+    WHERE ca.cycle_id=$1
+    ORDER BY title`, [cycleId]);
+
+  return rows.map((row) => ({
+    id: row.id as string,
+    source_type: row.source_type as ClubSourceType,
+    source_id: row.source_id as string,
+    title: row.title as string | null,
+    section: row.section as string | null,
+    is_oneshot: row.is_oneshot === true,
+    votes: row.votes as string,
+    cover: getWorkCover(row),
+  }));
 }
 
 export async function listCycleMilestones(cycleId: string) {