@jackwener/opencli 1.5.5 → 1.5.7

package/src/clis/weread/shelf.ts

@@ -1,10 +1,13 @@
 import { cli, Strategy } from '../../registry.js';
 import { CliError } from '../../errors.js';
+import { log } from '../../logger.js';
 import type { IPage } from '../../types.js';
-import { fetchPrivateApi } from './utils.js';
-
-const WEREAD_DOMAIN = 'weread.qq.com';
-const WEREAD_SHELF_URL = `https://${WEREAD_DOMAIN}/web/shelf`;
+import {
+  buildWebShelfEntries,
+  fetchPrivateApi,
+  loadWebShelfSnapshot,
+  type WebShelfSnapshot,
+} from './utils.js';
 
 interface ShelfRow {
   title: string;
@@ -13,24 +16,6 @@ interface ShelfRow {
   bookId: string;
 }
 
-interface WebShelfRawBook {
-  bookId?: string;
-  title?: string;
-  author?: string;
-}
-
-interface WebShelfIndexEntry {
-  bookId?: string;
-  idx?: number;
-  role?: string;
-}
-
-interface WebShelfSnapshot {
-  cacheFound: boolean;
-  rawBooks: WebShelfRawBook[];
-  shelfIndexes: WebShelfIndexEntry[];
-}
-
 function normalizeShelfLimit(limit: number): number {
   if (!Number.isFinite(limit)) return 0;
   return Math.max(0, Math.trunc(limit));
@@ -50,110 +35,17 @@ function normalizePrivateApiRows(data: any, limit: number): ShelfRow[] {
 function normalizeWebShelfRows(snapshot: WebShelfSnapshot, limit: number): ShelfRow[] {
   if (limit <= 0) return [];
 
-  const bookById = new Map<string, WebShelfRawBook>();
-  for (const book of snapshot.rawBooks) {
-    const bookId = String(book?.bookId || '').trim();
-    if (!bookId) continue;
-    bookById.set(bookId, book);
-  }
-
-  const orderedBookIds = snapshot.shelfIndexes
-    .filter((entry) => String(entry?.role || 'book') === 'book')
-    .sort((left, right) => Number(left?.idx ?? Number.MAX_SAFE_INTEGER) - Number(right?.idx ?? Number.MAX_SAFE_INTEGER))
-    .map((entry) => String(entry?.bookId || '').trim())
-    .filter(Boolean);
-
-  const fallbackOrder = snapshot.rawBooks
-    .map((book) => String(book?.bookId || '').trim())
-    .filter(Boolean);
-
-  const orderedUniqueBookIds = Array.from(new Set([
-    ...orderedBookIds,
-    ...fallbackOrder,
-  ]));
-
-  return orderedUniqueBookIds
-    .map((bookId) => {
-      const book = bookById.get(bookId);
-      if (!book) return null;
-      return {
-        title: String(book.title || '').trim(),
-        author: String(book.author || '').trim(),
+  return buildWebShelfEntries(snapshot)
+    .map((entry) => ({
+        title: entry.title,
+        author: entry.author,
         progress: '-',
-        bookId,
-      } satisfies ShelfRow;
-    })
-    .filter((item): item is ShelfRow => Boolean(item && (item.title || item.bookId)))
+        bookId: entry.bookId,
+      } satisfies ShelfRow))
+    .filter((item): item is ShelfRow => Boolean(item.title || item.bookId))
     .slice(0, limit);
 }
 
-/**
- * Read the structured shelf cache from the web shelf page.
- * The page hydrates localStorage with raw book data plus shelf ordering.
- */
-async function loadWebShelfSnapshot(page: IPage): Promise<WebShelfSnapshot> {
-  await page.goto(WEREAD_SHELF_URL);
-
-  const cookies = await page.getCookies({ domain: WEREAD_DOMAIN });
-  const currentVid = String(cookies.find((cookie) => cookie.name === 'wr_vid')?.value || '').trim();
-
-  if (!currentVid) {
-    return { cacheFound: false, rawBooks: [], shelfIndexes: [] };
-  }
-
-  const rawBooksKey = `shelf:rawBooks:${currentVid}`;
-  const shelfIndexesKey = `shelf:shelfIndexes:${currentVid}`;
-
-  const result = await page.evaluate(`
-    (() => new Promise((resolve) => {
-      const deadline = Date.now() + 5000;
-      const rawBooksKey = ${JSON.stringify(rawBooksKey)};
-      const shelfIndexesKey = ${JSON.stringify(shelfIndexesKey)};
-
-      const readJson = (raw) => {
-        if (typeof raw !== 'string') return null;
-        try {
-          return JSON.parse(raw);
-        } catch {
-          return null;
-        }
-      };
-
-      const poll = () => {
-        const rawBooksRaw = localStorage.getItem(rawBooksKey);
-        const shelfIndexesRaw = localStorage.getItem(shelfIndexesKey);
-        const rawBooks = readJson(rawBooksRaw);
-        const shelfIndexes = readJson(shelfIndexesRaw);
-        const cacheFound = Array.isArray(rawBooks);
-
-        if (cacheFound || Date.now() >= deadline) {
-          resolve({
-            cacheFound,
-            rawBooks: Array.isArray(rawBooks) ? rawBooks : [],
-            shelfIndexes: Array.isArray(shelfIndexes) ? shelfIndexes : [],
-          });
-          return;
-        }
-
-        setTimeout(poll, 100);
-      };
-
-      poll();
-    }))
-  `);
-
-  if (!result || typeof result !== 'object') {
-    return { cacheFound: false, rawBooks: [], shelfIndexes: [] };
-  }
-
-  const snapshot = result as Partial<WebShelfSnapshot>;
-  return {
-    cacheFound: snapshot.cacheFound === true,
-    rawBooks: Array.isArray(snapshot.rawBooks) ? snapshot.rawBooks : [],
-    shelfIndexes: Array.isArray(snapshot.shelfIndexes) ? snapshot.shelfIndexes : [],
-  };
-}
-
 cli({
   site: 'weread',
   name: 'shelf',
@@ -180,6 +72,12 @@ cli({
       if (!snapshot.cacheFound) {
         throw error;
       }
+
+      // Make the fallback explicit so users do not mistake cached shelf data
+      // for a valid private API session.
+      log.warn(
+        'WeRead private API auth expired; showing cached shelf data from localStorage. Results may be stale, and detail commands may still require re-login.',
+      );
       return normalizeWebShelfRows(snapshot, limit);
     }
   },

package/src/clis/weread/utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { formatDate, fetchWebApi } from './utils.js';
+import { buildWebShelfEntries, formatDate, fetchWebApi } from './utils.js';
 
 describe('formatDate', () => {
   it('formats a typical Unix timestamp in UTC+8', () => {
@@ -71,3 +71,83 @@ describe('fetchWebApi', () => {
     await expect(fetchWebApi('/search/global')).rejects.toThrow('Invalid JSON');
   });
 });
+
+describe('buildWebShelfEntries', () => {
+  it('keeps mixed shelf item reader urls aligned when shelf indexes include non-book roles', () => {
+    const result = buildWebShelfEntries(
+      {
+        cacheFound: true,
+        rawBooks: [
+          { bookId: 'MP_WXS_1', title: '公众号文章一', author: '作者甲' },
+          { bookId: 'BOOK_2', title: '普通书二', author: '作者乙' },
+          { bookId: 'MP_WXS_3', title: '公众号文章三', author: '作者丙' },
+        ],
+        shelfIndexes: [
+          { bookId: 'MP_WXS_1', idx: 0, role: 'mp' },
+          { bookId: 'BOOK_2', idx: 1, role: 'book' },
+          { bookId: 'MP_WXS_3', idx: 2, role: 'mp' },
+        ],
+      },
+      [
+        'https://weread.qq.com/web/reader/mp1',
+        'https://weread.qq.com/web/reader/book2',
+        'https://weread.qq.com/web/reader/mp3',
+      ],
+    );
+
+    expect(result).toEqual([
+      {
+        bookId: 'MP_WXS_1',
+        title: '公众号文章一',
+        author: '作者甲',
+        readerUrl: 'https://weread.qq.com/web/reader/mp1',
+      },
+      {
+        bookId: 'BOOK_2',
+        title: '普通书二',
+        author: '作者乙',
+        readerUrl: 'https://weread.qq.com/web/reader/book2',
+      },
+      {
+        bookId: 'MP_WXS_3',
+        title: '公众号文章三',
+        author: '作者丙',
+        readerUrl: 'https://weread.qq.com/web/reader/mp3',
+      },
+    ]);
+  });
+
+  it('falls back to raw cache order when shelf indexes are incomplete', () => {
+    const result = buildWebShelfEntries(
+      {
+        cacheFound: true,
+        rawBooks: [
+          { bookId: 'BOOK_1', title: '第一本', author: '作者甲' },
+          { bookId: 'BOOK_2', title: '第二本', author: '作者乙' },
+        ],
+        shelfIndexes: [
+          { bookId: 'BOOK_2', idx: 0, role: 'book' },
+        ],
+      },
+      [
+        'https://weread.qq.com/web/reader/book1',
+        'https://weread.qq.com/web/reader/book2',
+      ],
+    );
+
+    expect(result).toEqual([
+      {
+        bookId: 'BOOK_1',
+        title: '第一本',
+        author: '作者甲',
+        readerUrl: 'https://weread.qq.com/web/reader/book1',
+      },
+      {
+        bookId: 'BOOK_2',
+        title: '第二本',
+        author: '作者乙',
+        readerUrl: 'https://weread.qq.com/web/reader/book2',
+      },
+    ]);
+  });
+});

package/src/clis/weread/utils.ts

@@ -9,11 +9,49 @@
 import { CliError } from '../../errors.js';
 import type { BrowserCookie, IPage } from '../../types.js';
 
-const WEB_API = 'https://weread.qq.com/web';
-const API = 'https://i.weread.qq.com';
-const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+export const WEREAD_DOMAIN = 'weread.qq.com';
+export const WEREAD_WEB_ORIGIN = `https://${WEREAD_DOMAIN}`;
+export const WEREAD_SHELF_URL = `${WEREAD_WEB_ORIGIN}/web/shelf`;
+const WEB_API = `${WEREAD_WEB_ORIGIN}/web`;
+const API = `https://i.${WEREAD_DOMAIN}`;
+export const WEREAD_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
 const WEREAD_AUTH_ERRCODES = new Set([-2010, -2012]);
 
+export interface WebShelfRawBook {
+  bookId?: string;
+  title?: string;
+  author?: string;
+}
+
+export interface WebShelfIndexEntry {
+  bookId?: string;
+  idx?: number;
+  role?: string;
+}
+
+export interface WebShelfSnapshot {
+  cacheFound: boolean;
+  rawBooks: WebShelfRawBook[];
+  shelfIndexes: WebShelfIndexEntry[];
+}
+
+export interface WebShelfEntry {
+  bookId: string;
+  title: string;
+  author: string;
+  readerUrl: string;
+}
+
+export interface WebShelfReaderResolution {
+  snapshot: WebShelfSnapshot;
+  readerUrl: string | null;
+}
+
+interface WebShelfStorageKeys {
+  rawBooksKey: string;
+  shelfIndexesKey: string;
+}
+
 function buildCookieHeader(cookies: BrowserCookie[]): string {
   return cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join('; ');
 }
@@ -22,6 +60,88 @@ function isAuthErrorResponse(resp: Response, data: any): boolean {
   return resp.status === 401 || WEREAD_AUTH_ERRCODES.has(Number(data?.errcode));
 }
 
+function getCurrentVid(cookies: BrowserCookie[]): string {
+  return String(cookies.find((cookie) => cookie.name === 'wr_vid')?.value || '').trim();
+}
+
+function getWebShelfStorageKeys(currentVid: string): WebShelfStorageKeys {
+  return {
+    rawBooksKey: `shelf:rawBooks:${currentVid}`,
+    shelfIndexesKey: `shelf:shelfIndexes:${currentVid}`,
+  };
+}
+
+function normalizeWebShelfSnapshot(value: Partial<WebShelfSnapshot> | null | undefined): WebShelfSnapshot {
+  return {
+    cacheFound: value?.cacheFound === true,
+    rawBooks: Array.isArray(value?.rawBooks) ? value.rawBooks : [],
+    shelfIndexes: Array.isArray(value?.shelfIndexes) ? value.shelfIndexes : [],
+  };
+}
+
+function buildShelfSnapshotPollScript(storageKeys: WebShelfStorageKeys, requireTrustedIndexes: boolean): string {
+  return `
+    (() => new Promise((resolve) => {
+      const deadline = Date.now() + 5000;
+      const rawBooksKey = ${JSON.stringify(storageKeys.rawBooksKey)};
+      const shelfIndexesKey = ${JSON.stringify(storageKeys.shelfIndexesKey)};
+      const requireTrustedIndexes = ${JSON.stringify(requireTrustedIndexes)};
+
+      const readJson = (raw) => {
+        if (typeof raw !== 'string') return null;
+        try {
+          return JSON.parse(raw);
+        } catch {
+          return null;
+        }
+      };
+
+      const collectBookIds = (items) => Array.isArray(items)
+        ? Array.from(new Set(items.map((item) => String(item?.bookId || '').trim()).filter(Boolean)))
+        : [];
+
+      // Mirror of getTrustedIndexedBookIds in Node.js — keep in sync
+      const hasTrustedIndexes = (rawBooks, shelfIndexes) => {
+        const rawBookIds = collectBookIds(rawBooks);
+        if (rawBookIds.length === 0) return false;
+
+        const rawBookIdSet = new Set(rawBookIds);
+        const projectedIndexedBookIds = Array.isArray(shelfIndexes)
+          ? Array.from(new Set(
+              shelfIndexes
+                .filter((entry) => Number.isFinite(entry?.idx))
+                .sort((left, right) => Number(left?.idx ?? Number.MAX_SAFE_INTEGER) - Number(right?.idx ?? Number.MAX_SAFE_INTEGER))
+                .map((entry) => String(entry?.bookId || '').trim())
+                .filter((bookId) => rawBookIdSet.has(bookId)),
+            ))
+          : [];
+
+        return projectedIndexedBookIds.length === rawBookIds.length;
+      };
+
+      const poll = () => {
+        const rawBooks = readJson(localStorage.getItem(rawBooksKey));
+        const shelfIndexes = readJson(localStorage.getItem(shelfIndexesKey));
+        const cacheFound = Array.isArray(rawBooks);
+        const ready = cacheFound && (!requireTrustedIndexes || hasTrustedIndexes(rawBooks, shelfIndexes));
+
+        if (ready || Date.now() >= deadline) {
+          resolve({
+            cacheFound,
+            rawBooks: Array.isArray(rawBooks) ? rawBooks : [],
+            shelfIndexes: Array.isArray(shelfIndexes) ? shelfIndexes : [],
+          });
+          return;
+        }
+
+        setTimeout(poll, 100);
+      };
+
+      poll();
+    }))
+  `;
+}
+
 /**
  * Fetch a public WeRead web endpoint (Node.js direct fetch).
  * Used by search and ranking commands (browser: false).
@@ -32,7 +152,7 @@ export async function fetchWebApi(path: string, params?: Record<string, string>)
     for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
   }
   const resp = await fetch(url.toString(), {
-    headers: { 'User-Agent': UA },
+    headers: { 'User-Agent': WEREAD_UA },
   });
   if (!resp.ok) {
     throw new CliError('FETCH_ERROR', `HTTP ${resp.status} for ${path}`, 'WeRead API may be temporarily unavailable');
@@ -47,6 +167,10 @@ export async function fetchWebApi(path: string, params?: Record<string, string>)
 /**
  * Fetch a private WeRead API endpoint with cookies extracted from the browser.
  * The HTTP request itself runs in Node.js to avoid page-context CORS failures.
+ *
+ * Cookies are collected from both the API subdomain (i.weread.qq.com) and the
+ * main domain (weread.qq.com). WeRead may set auth cookies as host-only on
+ * weread.qq.com, which won't match i.weread.qq.com in a URL-based lookup.
  */
 export async function fetchPrivateApi(page: IPage, path: string, params?: Record<string, string>): Promise<any> {
   const url = new URL(`${API}${path}`);
@@ -55,14 +179,21 @@ export async function fetchPrivateApi(page: IPage, path: string, params?: Record
   }
   const urlStr = url.toString();
 
-  const cookies = await page.getCookies({ url: urlStr });
-  const cookieHeader = buildCookieHeader(cookies);
+  // Merge cookies from both domains; API-domain cookies take precedence on name collision
+  const [apiCookies, domainCookies] = await Promise.all([
+    page.getCookies({ url: urlStr }),
+    page.getCookies({ domain: WEREAD_DOMAIN }),
+  ]);
+  const merged = new Map<string, BrowserCookie>();
+  for (const c of domainCookies) merged.set(c.name, c);
+  for (const c of apiCookies) merged.set(c.name, c);
+  const cookieHeader = buildCookieHeader(Array.from(merged.values()));
 
   let resp: Response;
   try {
     resp = await fetch(urlStr, {
       headers: {
-        'User-Agent': UA,
+        'User-Agent': WEREAD_UA,
         'Origin': 'https://weread.qq.com',
         'Referer': 'https://weread.qq.com/',
         ...(cookieHeader ? { 'Cookie': cookieHeader } : {}),
@@ -95,6 +226,161 @@ export async function fetchPrivateApi(page: IPage, path: string, params?: Record
   return data;
 }
 
+function getUniqueRawBookIds(snapshot: WebShelfSnapshot): string[] {
+  return Array.from(new Set(
+    snapshot.rawBooks
+      .map((book) => String(book?.bookId || '').trim())
+      .filter(Boolean),
+  ));
+}
+
+/** Mirror of hasTrustedIndexes in buildShelfSnapshotPollScript — keep in sync */
+function getTrustedIndexedBookIds(snapshot: WebShelfSnapshot): string[] {
+  const rawBookIds = getUniqueRawBookIds(snapshot);
+  if (rawBookIds.length === 0) return [];
+
+  const rawBookIdSet = new Set(rawBookIds);
+  const projectedIndexedBookIds = Array.from(new Set(
+    snapshot.shelfIndexes
+      .filter((entry) => Number.isFinite(entry?.idx))
+      .sort((left, right) => Number(left?.idx ?? Number.MAX_SAFE_INTEGER) - Number(right?.idx ?? Number.MAX_SAFE_INTEGER))
+      .map((entry) => String(entry?.bookId || '').trim())
+      .filter((bookId) => rawBookIdSet.has(bookId)),
+  ));
+
+  return projectedIndexedBookIds.length === rawBookIds.length ? projectedIndexedBookIds : [];
+}
+
+/**
+ * Build stable shelf records from the web cache plus optional rendered reader URLs.
+ * We only trust shelfIndexes when it fully covers the same bookId set as rawBooks;
+ * otherwise we keep rawBooks order to avoid partial hydration reordering entries.
+ */
+export function buildWebShelfEntries(snapshot: WebShelfSnapshot, readerUrls: string[] = []): WebShelfEntry[] {
+  const rawBookIds = getUniqueRawBookIds(snapshot);
+  const trustedIndexedBookIds = getTrustedIndexedBookIds(snapshot);
+  const orderedBookIds = trustedIndexedBookIds.length > 0 ? trustedIndexedBookIds : rawBookIds;
+
+  const rawBookById = new Map<string, WebShelfRawBook>();
+  for (const book of snapshot.rawBooks) {
+    const bookId = String(book?.bookId || '').trim();
+    if (!bookId || rawBookById.has(bookId)) continue;
+    rawBookById.set(bookId, book);
+  }
+
+  return orderedBookIds.map((bookId, index) => {
+    const book = rawBookById.get(bookId);
+    return {
+      bookId,
+      title: String(book?.title || '').trim(),
+      author: String(book?.author || '').trim(),
+      readerUrl: String(readerUrls[index] || '').trim(),
+    };
+  });
+}
+
+/**
+ * Internal: load shelf snapshot and return the currentVid alongside it,
+ * so callers like resolveShelfReaderUrl can reuse it without a second getCookies.
+ */
+async function loadWebShelfSnapshotWithVid(page: IPage): Promise<{ snapshot: WebShelfSnapshot; currentVid: string }> {
+  await page.goto(WEREAD_SHELF_URL);
+
+  const cookies = await page.getCookies({ domain: WEREAD_DOMAIN });
+  const currentVid = getCurrentVid(cookies);
+
+  if (!currentVid) {
+    return { snapshot: { cacheFound: false, rawBooks: [], shelfIndexes: [] }, currentVid: '' };
+  }
+
+  const result = await page.evaluate(
+    buildShelfSnapshotPollScript(getWebShelfStorageKeys(currentVid), false),
+  );
+  return {
+    snapshot: normalizeWebShelfSnapshot(result as Partial<WebShelfSnapshot> | null | undefined),
+    currentVid,
+  };
+}
+
+/**
+ * Read the structured shelf cache from the WeRead shelf page.
+ * The page hydrates localStorage asynchronously, so we poll briefly before
+ * giving up and treating the cache as unavailable for the current session.
+ */
+export async function loadWebShelfSnapshot(page: IPage): Promise<WebShelfSnapshot> {
+  const { snapshot } = await loadWebShelfSnapshotWithVid(page);
+  return snapshot;
+}
+
+/**
+ * `book` needs a trustworthy `bookId -> readerUrl` mapping, which may lag behind
+ * the first rawBooks cache hydration. Keep the fast shelf fallback path separate
+ * and only wait here, with a bounded poll, when resolving reader URLs.
+ */
+async function waitForTrustedWebShelfSnapshot(page: IPage, snapshot: WebShelfSnapshot, currentVid: string): Promise<WebShelfSnapshot> {
+  // Cache not available; nothing to wait for
+  if (!snapshot.cacheFound) return snapshot;
+  // Indexes already fully cover rawBooks; no need to re-poll
+  if (getTrustedIndexedBookIds(snapshot).length > 0) return snapshot;
+
+  if (!currentVid) return snapshot;
+
+  const result = await page.evaluate(
+    buildShelfSnapshotPollScript(getWebShelfStorageKeys(currentVid), true),
+  );
+  return normalizeWebShelfSnapshot(result as Partial<WebShelfSnapshot> | null | undefined);
+}
+
+/**
+ * Resolve a shelf bookId to the current web reader URL by pairing structured
+ * shelf cache order with the visible shelf links rendered on the page.
+ */
+export async function resolveShelfReaderUrl(page: IPage, bookId: string): Promise<string | null> {
+  const resolution = await resolveShelfReader(page, bookId);
+  return resolution.readerUrl;
+}
+
+/**
+ * Resolve the current reader URL for a shelf entry and return the parsed shelf
+ * snapshot used during resolution, so callers can reuse cached title/author
+ * metadata without loading the shelf page twice.
+ */
+export async function resolveShelfReader(page: IPage, bookId: string): Promise<WebShelfReaderResolution> {
+  const { snapshot: initialSnapshot, currentVid } = await loadWebShelfSnapshotWithVid(page);
+  const snapshot = await waitForTrustedWebShelfSnapshot(page, initialSnapshot, currentVid);
+  if (!snapshot.cacheFound) {
+    return { snapshot, readerUrl: null };
+  }
+  const rawBookIds = getUniqueRawBookIds(snapshot);
+  const trustedIndexedBookIds = getTrustedIndexedBookIds(snapshot);
+  const canUseRawOrderFallback = trustedIndexedBookIds.length === 0
+    && rawBookIds.length > 0
+    && snapshot.shelfIndexes.length === 0;
+  if (trustedIndexedBookIds.length === 0 && !canUseRawOrderFallback) {
+    return { snapshot, readerUrl: null };
+  }
+
+  const readerUrls = await page.evaluate(`
+    (() => Array.from(document.querySelectorAll('a.shelfBook[href]'))
+      .map((anchor) => {
+        const href = anchor.getAttribute('href') || '';
+        return href ? new URL(href, location.origin).toString() : '';
+      })
+      .filter(Boolean))
+  `) as string[];
+  const expectedEntryCount = trustedIndexedBookIds.length > 0 ? trustedIndexedBookIds.length : rawBookIds.length;
+  if (readerUrls.length !== expectedEntryCount) {
+    return { snapshot, readerUrl: null };
+  }
+  const entries = buildWebShelfEntries(snapshot, readerUrls);
+
+  const entry = entries.find((candidate) => candidate.bookId === bookId);
+  return {
+    snapshot,
+    readerUrl: entry?.readerUrl || null,
+  };
+}
+
 /** Format a Unix timestamp (seconds) to YYYY-MM-DD in UTC+8. Returns '-' for invalid input. */
 export function formatDate(ts: number | undefined | null): string {
   if (!Number.isFinite(ts) || (ts as number) <= 0) return '-';