@duyquangnvx/webnovel-downloader 0.4.1 → 0.5.0

package/dist/index.cjs

@@ -551,7 +551,10 @@ var EventBus = class {
 // src/http/client.ts
 var import_undici = require("undici");
 init_errors();
+init_primitives();
 var DEFAULT_TIMEOUT_MS = 3e4;
+var MAX_REDIRECTS = 5;
+var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
 var UndiciHttpClient = class {
   #logger;
   #dispatcher;
@@ -566,23 +569,28 @@ var UndiciHttpClient = class {
     const half = Math.max(1, Math.floor(timeoutMs / 2));
     let res;
     try {
-      res = await (0, import_undici.request)(url, {
-        method: "GET",
-        dispatcher: this.#dispatcher,
-        ...opts?.headers !== void 0 ? { headers: opts.headers } : {},
-        ...opts?.signal !== void 0 ? { signal: opts.signal } : {},
-        headersTimeout: half,
-        bodyTimeout: half,
-        maxRedirections: 5
-      });
+      let currentUrl = url;
+      for (let hop = 0; ; hop++) {
+        res = await (0, import_undici.request)(currentUrl, {
+          method: "GET",
+          dispatcher: this.#dispatcher,
+          ...opts?.headers !== void 0 ? { headers: opts.headers } : {},
+          ...opts?.signal !== void 0 ? { signal: opts.signal } : {},
+          headersTimeout: half,
+          bodyTimeout: half
+        });
+        const next = hop < MAX_REDIRECTS ? redirectTarget(res.statusCode, res.headers, currentUrl) : void 0;
+        if (next === void 0) break;
+        await res.body.dump();
+        currentUrl = next;
+      }
       const body = await res.body.text();
       const headers = normalizeHeaders(res.headers);
-      const finalUrl = url;
       return {
         status: res.statusCode,
         headers,
         body,
-        url: finalUrl
+        url: currentUrl
       };
     } catch (cause) {
       if (res !== void 0) await res.body.dump().catch(() => {
@@ -603,6 +611,17 @@ var UndiciHttpClient = class {
     if (this.#ownsDispatcher) await this.#dispatcher.close();
   }
 };
+function redirectTarget(status, headers, currentUrl) {
+  if (!REDIRECT_STATUSES.has(status)) return void 0;
+  const raw = headers["location"];
+  const location = Array.isArray(raw) ? raw[0] : raw;
+  if (location === void 0 || location === "") return void 0;
+  try {
+    return unsafeBrandUrl(new URL(location, currentUrl).href);
+  } catch {
+    return void 0;
+  }
+}
 function normalizeHeaders(h) {
   const out = {};
   for (const [k, v] of Object.entries(h)) {
@@ -899,31 +918,6 @@ function clamp(n, lo, hi) {
 // src/http/index.ts
 init_cookie_jar();
 
-// src/http/stack-builder.ts
-var HttpStack = class _HttpStack {
-  #client;
-  constructor(client) {
-    this.#client = client;
-  }
-  static from(leaf) {
-    return new _HttpStack(leaf);
-  }
-  rotateUserAgent(uas, defaultHeaders, cookieJar) {
-    return new _HttpStack(
-      new UserAgentRotatingHttpClient(this.#client, uas, defaultHeaders, cookieJar)
-    );
-  }
-  rateLimit(limiter, onEvent) {
-    return new _HttpStack(new RateLimitedHttpClient(this.#client, limiter, onEvent));
-  }
-  retry(opts, logger, limiter, onEvent) {
-    return new _HttpStack(new RetryingHttpClient(this.#client, opts, logger, limiter, onEvent));
-  }
-  build() {
-    return this.#client;
-  }
-};
-
 // src/http/tiered.ts
 init_cf_challenge();
 var FALLBACK_UA = DEFAULT_UA_POOL[0] ?? "Mozilla/5.0";
@@ -989,7 +983,20 @@ function buildHttpClient(opts = {}) {
     ...opts.dispatcher !== void 0 ? { dispatcher: opts.dispatcher } : {}
   });
   const limiter = opts.rateLimiter ?? new RateLimiter(opts.rateLimit ?? DEFAULT_RATE_LIMIT);
-  const httpBranch = HttpStack.from(leaf).rotateUserAgent(opts.userAgents ?? new UserAgents(), opts.defaultHeaders, cookieJar).rateLimit(limiter, opts.onEvent).retry(normalizeRetry(opts.retry), logger, limiter, opts.onEvent).build();
+  const withUserAgent = new UserAgentRotatingHttpClient(
+    leaf,
+    opts.userAgents ?? new UserAgents(),
+    opts.defaultHeaders,
+    cookieJar
+  );
+  const withRateLimit = new RateLimitedHttpClient(withUserAgent, limiter, opts.onEvent);
+  const httpBranch = new RetryingHttpClient(
+    withRateLimit,
+    normalizeRetry(opts.retry),
+    logger,
+    limiter,
+    opts.onEvent
+  );
   const { mode } = normalizeTransport(opts.transport);
   if (mode === "http-only") {
     return httpBranch;
@@ -1501,8 +1508,78 @@ var Debouncer = class {
   }
 };
 
-// src/core/download-run.ts
-init_primitives();
+// src/core/run-ledger.ts
+var RunLedger = class _RunLedger {
+  #successes = [];
+  #failures = [];
+  #completedSet = /* @__PURE__ */ new Set();
+  #completedList = [];
+  #failedMap = /* @__PURE__ */ new Map();
+  #enqueuedSet = /* @__PURE__ */ new Set();
+  constructor() {
+  }
+  static seed(state, priorChapters) {
+    const ledger = new _RunLedger();
+    ledger.#successes.push(...priorChapters);
+    for (const idx of state?.completed ?? []) ledger.#markCompleted(idx);
+    for (const chapter of priorChapters) ledger.#markCompleted(chapter.index);
+    for (const f of state?.failed ?? []) {
+      if (!ledger.#completedSet.has(f.index)) ledger.#failedMap.set(f.index, f);
+    }
+    return ledger;
+  }
+  #markCompleted(index) {
+    if (this.#completedSet.has(index)) return;
+    this.#completedSet.add(index);
+    this.#completedList.push(index);
+  }
+  /** Check-and-set enqueue dedup: false if the index is completed or already enqueued. */
+  markEnqueued(index) {
+    if (this.#completedSet.has(index) || this.#enqueuedSet.has(index)) return false;
+    this.#enqueuedSet.add(index);
+    return true;
+  }
+  recordSuccess(chapter) {
+    this.#successes.push(chapter);
+    this.#markCompleted(chapter.index);
+    this.#failedMap.delete(chapter.index);
+  }
+  recordFailure(ref, error) {
+    this.#failures.push({ ref, error, attempts: 1 });
+    this.#failedMap.set(ref.index, {
+      index: ref.index,
+      lastError: { code: error.code, message: error.message }
+    });
+  }
+  dropOrphanFailure(index) {
+    this.#failedMap.delete(index);
+  }
+  /** The ONLY projection to the persisted shape; nothing else writes state.completed/failed. */
+  applyTo(state) {
+    return {
+      ...state,
+      completed: [...this.#completedList].sort((a, b) => Number(a) - Number(b)),
+      failed: [...this.#failedMap.values()]
+    };
+  }
+  successes() {
+    return this.#successes;
+  }
+  failures() {
+    return this.#failures;
+  }
+  /** Snapshot — safe to mutate the ledger while iterating the result. */
+  failedRecords() {
+    return [...this.#failedMap.values()];
+  }
+  /** Fetched-chapter count (including prior-run chapters) — drives the progress event. */
+  get completedCount() {
+    return this.#successes.length;
+  }
+  get enqueuedCount() {
+    return this.#enqueuedSet.size;
+  }
+};
 
 // src/pipeline/fetch-toc.ts
 init_errors();
@@ -1574,15 +1651,51 @@ function assembleNovelData(metadata, results) {
 // src/core/download-run.ts
 init_errors();
 
+// src/storage/resume-state.ts
+var import_zod4 = require("zod");
+init_primitives();
+var ResumeFailureRecordSchema = import_zod4.z.object({
+  index: ChapterIndexSchema,
+  lastError: import_zod4.z.object({ code: import_zod4.z.string(), message: import_zod4.z.string() }).readonly()
+}).readonly();
+var ResumeStateSchema = import_zod4.z.object({
+  schemaVersion: import_zod4.z.literal(1),
+  url: UrlSchema,
+  adapterId: AdapterIdSchema,
+  metadata: NovelMetadataSchema.nullable(),
+  toc: import_zod4.z.array(ChapterRefSchema).readonly().nullable(),
+  completed: import_zod4.z.array(ChapterIndexSchema).readonly(),
+  failed: import_zod4.z.array(ResumeFailureRecordSchema).readonly(),
+  startedAt: IsoDateSchema,
+  updatedAt: IsoDateSchema
+}).readonly();
+function nowIso() {
+  return unsafeBrandIsoDate((/* @__PURE__ */ new Date()).toISOString());
+}
+function freshState(url, adapterId) {
+  const now = nowIso();
+  return {
+    schemaVersion: 1,
+    url,
+    adapterId,
+    metadata: null,
+    toc: null,
+    completed: [],
+    failed: [],
+    startedAt: now,
+    updatedAt: now
+  };
+}
+
 // src/storage/resume-token.ts
 var import_node_path3 = require("path");
-var import_zod4 = require("zod");
+var import_zod5 = require("zod");
 init_errors();
 init_primitives();
-var TokenPayloadSchema = import_zod4.z.object({
-  v: import_zod4.z.literal(1),
-  stateFile: import_zod4.z.string().min(1),
-  urlHash: import_zod4.z.string().min(1)
+var TokenPayloadSchema = import_zod5.z.object({
+  v: import_zod5.z.literal(1),
+  stateFile: import_zod5.z.string().min(1),
+  urlHash: import_zod5.z.string().min(1)
 });
 function encodeResumeToken(stateFile, url) {
   const payload = { v: 1, stateFile, urlHash: sha1(url) };
@@ -1621,23 +1734,6 @@ function verifyResumeToken(token, url) {
 // src/core/download-run.ts
 var QUEUE_BACKPRESSURE_RATIO = 4;
 var STATE_PERSIST_DEBOUNCE_MS = 500;
-function freshState(url, adapterId) {
-  const now = nowIso();
-  return {
-    schemaVersion: 1,
-    url,
-    adapterId,
-    metadata: null,
-    toc: null,
-    completed: [],
-    failed: [],
-    startedAt: now,
-    updatedAt: now
-  };
-}
-function nowIso() {
-  return unsafeBrandIsoDate((/* @__PURE__ */ new Date()).toISOString());
-}
 var DownloadRun = class {
   #adapter;
   #validated;
@@ -1649,13 +1745,7 @@ var DownloadRun = class {
   #bus;
   #logger;
   #state = null;
-  #successes = [];
-  #failures = [];
-  #completedSet = /* @__PURE__ */ new Set();
-  #completedList = [];
-  #failedMap = /* @__PURE__ */ new Map();
-  #enqueuedSet = /* @__PURE__ */ new Set();
-  #aborted = false;
+  #ledger = RunLedger.seed(null, []);
   #queue;
   #stateDebouncer;
   constructor(args) {
@@ -1681,9 +1771,8 @@ var DownloadRun = class {
     const resolved = await this.#resolveMetadata();
     if ("error" in resolved) return resolved.error;
     const meta = resolved.meta;
-    const ctxWithMeta = this.#startQueue(meta);
+    const ctxWithMeta = { ...this.#ctx, novelMetadata: meta };
     const onAbort = () => {
-      this.#aborted = true;
       this.#queue.clear();
     };
     this.#signal.addEventListener("abort", onAbort, { once: true });
@@ -1698,40 +1787,23 @@ var DownloadRun = class {
   }
   async #initResume() {
     const resumeCfg = this.#resumeStorage;
-    if (resumeCfg) {
-      try {
-        let state = await resumeCfg.resume.load(resumeCfg.stateFile);
-        if (state) {
-          if (state.url !== this.#validated) {
-            throw new ParseError("Stale resume state: URL mismatch");
-          }
-          if (state.adapterId !== this.#adapter.id) {
-            throw new ParseError("Stale resume state: adapter mismatch");
-          }
-        } else {
-          state = freshState(this.#validated, this.#adapter.id);
-        }
-        this.#state = state;
-      } catch (err) {
-        return { status: "error", error: normalizeToEnvelopeError(err) };
-      }
-    }
-    if (resumeCfg && this.#state) {
-      const prior = await resumeCfg.chapters.loadAll();
-      this.#successes.push(...prior);
-      const merged = new Set(this.#state.completed);
-      for (const c of prior) merged.add(c.index);
-      this.#state = {
-        ...this.#state,
-        completed: [...merged].sort((a, b) => Number(a) - Number(b))
-      };
+    if (!resumeCfg) return null;
+    try {
+      const { state, priorChapters } = await resumeCfg.loadFor(this.#validated, this.#adapter.id);
+      this.#state = state;
+      this.#ledger = RunLedger.seed(state, priorChapters);
+    } catch (err) {
+      return { status: "error", error: normalizeToEnvelopeError(err) };
     }
     return null;
   }
+  #schedulePersist() {
+    if (this.#state) this.#stateDebouncer.schedule();
+  }
   async #persistState() {
     const resumeCfg = this.#resumeStorage;
     if (!resumeCfg || !this.#state) return;
-    const next = { ...this.#state, updatedAt: nowIso() };
+    const next = { ...this.#ledger.applyTo(this.#state), updatedAt: nowIso() };
     this.#state = next;
     await resumeCfg.resume.save(resumeCfg.stateFile, next);
   }
@@ -1752,69 +1824,35 @@ var DownloadRun = class {
       return { error: { status: "error", error: normalizeToEnvelopeError(err) } };
     }
   }
-  #startQueue(meta) {
-    const state = this.#state;
-    const completedSet = this.#completedSet;
-    const completedList = this.#completedList;
-    const failedMap = this.#failedMap;
-    for (const idx of state?.completed ?? []) completedSet.add(idx);
-    completedList.push(...state ? state.completed : []);
-    if (state) {
-      for (const f of state.failed) {
-        if (!completedSet.has(f.index)) failedMap.set(f.index, f);
-      }
-    }
-    return { ...this.#ctx, novelMetadata: meta };
-  }
   async #enqueueRef(ref, ctxWithMeta) {
-    if (this.#aborted || this.#signal.aborted) return;
-    if (this.#completedSet.has(ref.index)) return;
-    if (this.#enqueuedSet.has(ref.index)) return;
-    this.#enqueuedSet.add(ref.index);
+    if (this.#signal.aborted) return;
+    if (!this.#ledger.markEnqueued(ref.index)) return;
     const backpressureLimit = this.#concurrency * QUEUE_BACKPRESSURE_RATIO;
     while (this.#queue.size >= backpressureLimit) {
       await this.#queue.onSizeLessThan(backpressureLimit);
-      if (this.#aborted || this.#signal.aborted) throw new CancelledError({ cause: this.#signal.reason });
+      if (this.#signal.aborted) throw new CancelledError({ cause: this.#signal.reason });
     }
-    if (this.#aborted) throw new CancelledError({ cause: this.#signal.reason });
     void this.#queue.add(() => this.#fetchChapter(ref, ctxWithMeta));
   }
   async #fetchChapter(ref, ctxWithMeta) {
-    if (this.#aborted || this.#signal.aborted) return;
+    if (this.#signal.aborted) return;
     try {
       const chapter = await fetchChapterTask(this.#adapter, ref, ctxWithMeta, this.#bus);
-      if (this.#aborted) return;
+      if (this.#signal.aborted) return;
       if (this.#resumeStorage) await this.#resumeStorage.chapters.save(chapter);
-      this.#successes.push(chapter);
-      this.#completedList.push(ref.index);
-      this.#completedSet.add(ref.index);
-      this.#failedMap.delete(ref.index);
-      if (this.#state) {
-        this.#state = {
-          ...this.#state,
-          completed: [...this.#completedList],
-          failed: [...this.#failedMap.values()]
-        };
-        this.#stateDebouncer.schedule();
-      }
+      this.#ledger.recordSuccess(chapter);
+      this.#schedulePersist();
       this.#bus.emit({ type: "chapter:success", chapter });
       this.#bus.emit({
         type: "progress",
-        completed: this.#successes.length,
-        total: ctxWithMeta.novelMetadata?.totalChapters ?? this.#enqueuedSet.size
+        completed: this.#ledger.completedCount,
+        total: ctxWithMeta.novelMetadata?.totalChapters ?? this.#ledger.enqueuedCount
       });
     } catch (cause) {
       if (cause instanceof CancelledError) return;
       const wrapped = cause instanceof ChapterFetchError ? cause : new ChapterFetchError(ref, { cause });
-      this.#failures.push({ ref, error: wrapped, attempts: 1 });
-      this.#failedMap.set(ref.index, {
-        index: ref.index,
-        lastError: { code: wrapped.code, message: wrapped.message }
-      });
-      if (this.#state) {
-        this.#state = { ...this.#state, failed: [...this.#failedMap.values()] };
-        this.#stateDebouncer.schedule();
-      }
+      this.#ledger.recordFailure(ref, wrapped);
+      this.#schedulePersist();
       this.#bus.emit({ type: "chapter:failed", ref, error: wrapped });
     }
   }
@@ -1866,7 +1904,7 @@ var DownloadRun = class {
     const tocByIndex = new Map(
       (this.#state.toc ?? []).map((r) => [r.index, r])
     );
-    for (const f of this.#state.failed) {
+    for (const f of this.#ledger.failedRecords()) {
       const ref = tocByIndex.get(f.index);
       if (ref) {
         await this.#enqueueRef(ref, ctxWithMeta);
@@ -1874,11 +1912,8 @@ var DownloadRun = class {
         this.#logger.warn(
           `Resume: dropping orphan failed record for index ${String(f.index)} (no matching TOC ref)`
         );
-        this.#failedMap.delete(f.index);
-        if (this.#state) {
-          this.#state = { ...this.#state, failed: [...this.#failedMap.values()] };
-          this.#stateDebouncer.schedule();
-        }
+        this.#ledger.dropOrphanFailure(f.index);
+        this.#schedulePersist();
       }
     }
   }
@@ -1910,19 +1945,20 @@ var DownloadRun = class {
     if (stage2Error) return { status: "error", error: stage2Error };
     let data;
     try {
-      data = assembleNovelData(metadata, this.#successes);
+      data = assembleNovelData(metadata, this.#ledger.successes());
     } catch (err) {
       return {
         status: "error",
         error: normalizeToEnvelopeError(err)
       };
     }
-    if (this.#failures.length > 0) {
+    const failures = this.#ledger.failures();
+    if (failures.length > 0) {
       if (this.#resumeStorage) {
         const token = encodeResumeToken(this.#resumeStorage.stateFile, this.#validated);
-        return { status: "partial", resumable: true, data, failures: this.#failures, resumeToken: token };
+        return { status: "partial", resumable: true, data, failures, resumeToken: token };
       }
-      return { status: "partial", resumable: false, data, failures: this.#failures };
+      return { status: "partial", resumable: false, data, failures };
     }
     return { status: "success", data };
   }
@@ -1937,32 +1973,12 @@ function normalizeChapterRange(range) {
 
 // src/storage/resume-storage.ts
 var import_node_path6 = require("path");
+init_errors();
 
 // src/storage/resume-store.ts
 var import_promises3 = require("fs/promises");
 var import_node_path4 = require("path");
 init_errors();
-
-// src/storage/resume-state.ts
-var import_zod5 = require("zod");
-init_primitives();
-var ResumeFailureRecordSchema = import_zod5.z.object({
-  index: ChapterIndexSchema,
-  lastError: import_zod5.z.object({ code: import_zod5.z.string(), message: import_zod5.z.string() }).readonly()
-}).readonly();
-var ResumeStateSchema = import_zod5.z.object({
-  schemaVersion: import_zod5.z.literal(1),
-  url: UrlSchema,
-  adapterId: AdapterIdSchema,
-  metadata: NovelMetadataSchema.nullable(),
-  toc: import_zod5.z.array(ChapterRefSchema).readonly().nullable(),
-  completed: import_zod5.z.array(ChapterIndexSchema).readonly(),
-  failed: import_zod5.z.array(ResumeFailureRecordSchema).readonly(),
-  startedAt: IsoDateSchema,
-  updatedAt: IsoDateSchema
-}).readonly();
-
-// src/storage/resume-store.ts
 var MemoryResumeStore = class {
   #map = /* @__PURE__ */ new Map();
   async load(path) {
@@ -2105,6 +2121,32 @@ var ResumeStorage = class _ResumeStorage {
       stateFile
     );
   }
+  /**
+   * Loads state for a run against (url, adapterId) and applies the reconcile
+   * invariant: a chapter file on disk proves the fetch completed, so its index
+   * wins over a stale `state.completed` (they diverge when run 1's in-flight
+   * tasks write chapters after abort but before the debounced state save).
+   */
+  async loadFor(url, adapterId) {
+    let state = await this.resume.load(this.stateFile);
+    if (state) {
+      if (state.url !== url) {
+        throw new ParseError("Stale resume state: URL mismatch", { url, path: this.stateFile });
+      }
+      if (state.adapterId !== adapterId) {
+        throw new ParseError("Stale resume state: adapter mismatch", { url, path: this.stateFile });
+      }
+    } else {
+      state = freshState(url, adapterId);
+    }
+    const priorChapters = await this.chapters.loadAll();
+    if (priorChapters.length > 0) {
+      const merged = new Set(state.completed);
+      for (const c of priorChapters) merged.add(c.index);
+      state = { ...state, completed: [...merged].sort((a, b) => Number(a) - Number(b)) };
+    }
+    return { state, priorChapters };
+  }
 };
 function resolveResumeStorage(opt, url, logger) {
   if (opt === void 0) return null;
@@ -2437,7 +2479,6 @@ var BaseAdapter = class {
 
 // src/adapters/truyenfull/index.ts
 init_primitives();
-init_errors();
 
 // src/adapters/truyenfull/parser.ts
 init_primitives();
@@ -2506,6 +2547,20 @@ function parseNovelHeader($, selectors, sourceUrl) {
     ...coverUrl !== void 0 ? { coverUrl } : {}
   };
 }
+function buildNovelMetadata(fields, envelope) {
+  return {
+    title: fields.title,
+    author: fields.author,
+    description: fields.description,
+    genres: fields.genres,
+    sourceUrl: envelope.sourceUrl,
+    sourceSite: envelope.sourceSite,
+    status: envelope.status,
+    fetchedAt: /* @__PURE__ */ new Date(),
+    ...fields.coverUrl !== void 0 ? { coverUrl: fields.coverUrl } : {},
+    ...envelope.totalChapters !== void 0 ? { totalChapters: envelope.totalChapters } : {}
+  };
+}
 
 // src/adapters/shared/content.ts
 init_errors();
@@ -2551,13 +2606,11 @@ function parseNovelPage($, sourceUrl) {
   let status = "unknown";
   if ($(TRUYENFULL_SELECTORS.metadata.statusFull).length > 0) status = "completed";
   else if ($(TRUYENFULL_SELECTORS.metadata.statusOngoing).length > 0) status = "ongoing";
-  return {
-    ...header,
+  return buildNovelMetadata(header, {
     sourceUrl,
     sourceSite: unsafeBrandAdapterId("truyenfull"),
-    status,
-    fetchedAt: /* @__PURE__ */ new Date()
-  };
+    status
+  });
 }
 function parseTocPage($, startIndex, baseUrl) {
   const refs = refsFromAnchors($, { selector: TRUYENFULL_SELECTORS.toc.listItem, startIndex, baseUrl });
@@ -2603,6 +2656,21 @@ function parseChapterPage($, ref) {
   };
 }
 
+// src/adapters/shared/paginate.ts
+init_primitives();
+init_errors();
+async function* paginateToc(opts) {
+  let index = unsafeBrandChapterIndex(0);
+  for (let page = 1; ; page++) {
+    if (opts.ctx.signal.aborted) throw new CancelledError({ cause: opts.ctx.signal.reason });
+    const result = await opts.fetchPage(page, index);
+    if (result === null || result.refs.length === 0) return;
+    for (const ref of result.refs) yield ref;
+    index = unsafeBrandChapterIndex(index + result.refs.length);
+    if (result.isLast) return;
+  }
+}
+
 // src/adapters/truyenfull/index.ts
 var TruyenFullAdapter = class extends BaseAdapter {
   id = unsafeBrandAdapterId("truyenfull");
@@ -2641,22 +2709,20 @@ var TruyenFullAdapter = class extends BaseAdapter {
   }
   async *fetchChapterList(url, ctx) {
     const base = stripTrailingSlash(this.#normalize(url));
-    let page = 1;
-    let index = unsafeBrandChapterIndex(0);
     let knownTotalPages;
-    while (true) {
-      if (ctx.signal.aborted) throw new CancelledError({ cause: ctx.signal.reason });
-      const pageUrl = page === 1 ? unsafeBrandUrl(`${base}/`) : unsafeBrandUrl(`${base}/trang-${page}/`);
-      const $ = await this.loadHtml(pageUrl, ctx);
-      const { refs, isLastPage, totalPages } = parseTocPage($, index, pageUrl);
-      if (page === 1 && totalPages !== void 0) knownTotalPages = totalPages;
-      if (refs.length === 0) return;
-      for (const ref of refs) yield ref;
-      index = unsafeBrandChapterIndex(index + refs.length);
-      if (isLastPage) return;
-      if (knownTotalPages !== void 0 && page >= knownTotalPages) return;
-      page++;
-    }
+    yield* paginateToc({
+      ctx,
+      fetchPage: async (page, startIndex) => {
+        const pageUrl = page === 1 ? unsafeBrandUrl(`${base}/`) : unsafeBrandUrl(`${base}/trang-${page}/`);
+        const $ = await this.loadHtml(pageUrl, ctx);
+        const { refs, isLastPage, totalPages } = parseTocPage($, startIndex, pageUrl);
+        if (page === 1 && totalPages !== void 0) knownTotalPages = totalPages;
+        return {
+          refs,
+          isLast: isLastPage || knownTotalPages !== void 0 && page >= knownTotalPages
+        };
+      }
+    });
   }
   async fetchChapter(ref, ctx) {
     const target = this.#normalize(ref.url);
@@ -2726,15 +2792,12 @@ function parseNovelPage2($, sourceUrl) {
   let status = "unknown";
   if ($(METRUYENCHU_SELECTORS.metadata.statusFull).length > 0) status = "completed";
   else if (METRUYENCHU_SELECTORS.metadata.statusOngoing.some((sel) => $(sel).length > 0)) status = "ongoing";
-  const totalChapters = extractTotalChapters($);
-  return {
-    ...header,
+  return buildNovelMetadata(header, {
     sourceUrl,
     sourceSite: SOURCE_SITE,
     status,
-    fetchedAt: /* @__PURE__ */ new Date(),
-    ...totalChapters !== void 0 ? { totalChapters } : {}
-  };
+    totalChapters: extractTotalChapters($)
+  });
 }
 var TOTAL_CHAPTERS_LABEL_REGEX = /^\s*Số\s*chương\s*:?\s*$/i;
 var TOTAL_CHAPTERS_VALUE_REGEX = /(\d[\d.,]*)/;
@@ -2831,34 +2894,34 @@ var MeTruyenChuComVnAdapter = class extends BaseAdapter {
       );
     }
     const apiOrigin = new URL(url).origin;
-    let index = unsafeBrandChapterIndex(0);
-    const page1Refs = parseTocPage1($, index, url);
-    for (const ref of page1Refs) yield ref;
-    index = unsafeBrandChapterIndex(index + page1Refs.length);
-    for (let page = 2; page <= lastPage; page++) {
-      if (ctx.signal.aborted) throw new CancelledError({ cause: ctx.signal.reason });
-      const apiUrl = unsafeBrandUrl(`${apiOrigin}/get/listchap/${bid}?page=${page}`);
-      const raw = await this.fetchJson(apiUrl, ctx);
-      const parsed = tocJsonEnvelopeSchema.safeParse(raw);
-      if (!parsed.success) {
-        throw new ParseError(`Invalid TOC JSON envelope at ${apiUrl}`, {
-          cause: parsed.error,
-          url: apiUrl
-        });
-      }
-      const fragment = parsed.data.data;
-      if (!fragment) {
-        ctx.logger.warn({ apiUrl, page }, "Empty TOC JSON data; ending walk early");
-        return;
-      }
-      const refs = parseTocJsonPage(fragment, index, url);
-      if (refs.length === 0) {
-        ctx.logger.warn({ apiUrl, page }, "Zero anchors in TOC JSON page; ending walk early");
-        return;
+    yield* paginateToc({
+      ctx,
+      fetchPage: async (page, startIndex) => {
+        if (page === 1) {
+          return { refs: parseTocPage1($, startIndex, url), isLast: lastPage <= 1 };
+        }
+        const apiUrl = unsafeBrandUrl(`${apiOrigin}/get/listchap/${bid}?page=${page}`);
+        const raw = await this.fetchJson(apiUrl, ctx);
+        const parsed = tocJsonEnvelopeSchema.safeParse(raw);
+        if (!parsed.success) {
+          throw new ParseError(`Invalid TOC JSON envelope at ${apiUrl}`, {
+            cause: parsed.error,
+            url: apiUrl
+          });
+        }
+        const fragment = parsed.data.data;
+        if (!fragment) {
+          ctx.logger.warn({ apiUrl, page }, "Empty TOC JSON data; ending walk early");
+          return null;
+        }
+        const refs = parseTocJsonPage(fragment, startIndex, url);
+        if (refs.length === 0) {
+          ctx.logger.warn({ apiUrl, page }, "Zero anchors in TOC JSON page; ending walk early");
+          return null;
+        }
+        return { refs, isLast: page >= lastPage };
       }
-      for (const ref of refs) yield ref;
-      index = unsafeBrandChapterIndex(index + refs.length);
-    }
+    });
   }
   async fetchChapter(ref, ctx) {
     const $ = await this.loadHtml(ref.url, ctx);
@@ -2915,19 +2978,21 @@ function parseNovelPage3($, sourceUrl) {
   const genres = parseGenres(descBlock);
   const statusText = $(WIKICV_SELECTORS.metadata.statusAnchor).first().text().trim();
   const status = /^Hoàn\s*thành/i.test(statusText) ? "completed" : /^Đang\s*ra/i.test(statusText) ? "ongoing" : "unknown";
-  const totalChapters = extractTotalChapters2($);
-  return {
-    sourceUrl,
-    sourceSite: SOURCE_SITE2,
-    title,
-    author,
-    description,
-    genres,
-    status,
-    fetchedAt: /* @__PURE__ */ new Date(),
-    ...coverUrl !== void 0 ? { coverUrl } : {},
-    ...totalChapters !== void 0 ? { totalChapters } : {}
-  };
+  return buildNovelMetadata(
+    {
+      title,
+      author,
+      description,
+      genres,
+      ...coverUrl !== void 0 ? { coverUrl } : {}
+    },
+    {
+      sourceUrl,
+      sourceSite: SOURCE_SITE2,
+      status,
+      totalChapters: extractTotalChapters2($)
+    }
+  );
 }
 var CHUONG_SLUG_REGEX = /\/chuong-(\d+)-/i;
 var CHUONG_TEXT_REGEX = /Chương\s*(\d+)/i;