Add pages to series and adds schemas for zod 4

package.json

@@ -22,6 +22,12 @@
         "types": "./dist/zod-schemas.d.ts",
         "default": "./dist/zod-schemas.js"
       }
+    },
+    "./zod-schemas/v4": {
+      "import": {
+        "types": "./dist/zod-schemas-v4.d.ts",
+        "default": "./dist/zod-schemas-v4.js"
+      }
     }
   },
   "files": [
@@ -64,10 +70,10 @@
     "vite-plugin-dts": "^4.5.4",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "zod": "^3.23.8"
+    "zod": "^3.25.0"
   },
   "peerDependencies": {
-    "zod": "^3.0.0 || ^4.0.0"
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
     "zod": {

src/page-loaders.ts

@@ -156,8 +156,14 @@ export const loadChaptersIndexPage = async ({
 export interface SeriesPage extends CheerioAPI {
   kind: "SeriesPage";
 }
-export const loadSeriesPage = async (seriesId: ArchiveId) => {
+export const loadSeriesPage = async ({
+  seriesId,
+  page,
+}: {
+  seriesId: ArchiveId;
+  page?: number;
+}) => {
   return await fetchPage<SeriesPage>({
-    url: getSeriesUrl({ seriesId }),
+    url: getSeriesUrl({ seriesId, page }),
   });
 };

src/series/index.ts

@@ -15,17 +15,20 @@ import {
 
 import type { Series } from "types/entities";
 import { loadSeriesPage } from "src/page-loaders";
+import { getPagesCount } from "src/tags/search-getters";
 
 export const getSeries = async ({
   seriesId,
+  page,
 }: {
   seriesId: string | number;
+  page?: number;
 }): Promise<Series> => {
   if (!isValidArchiveId(seriesId)) {
     throw new InvalidIDError(seriesId, "series");
   }
 
-  const seriesPage = await loadSeriesPage(seriesId);
+  const seriesPage = await loadSeriesPage({ seriesId, page });
 
   const seriesWorks = getSeriesWorks(seriesPage);
 
@@ -41,6 +44,10 @@ export const getSeries = async ({
     bookmarks: getSeriesBookmarkCount(seriesPage),
     complete: getSeriesCompletionStatus(seriesPage),
     workCount: getSeriesWorkCount(seriesPage),
+    pages: {
+      total: seriesWorks.length > 0 ? Math.max(1, getPagesCount(seriesPage)) : 0,
+      current: page ?? 1,
+    },
     works: seriesWorks,
   };
 };

src/tags/search-getters.ts

@@ -1,4 +1,4 @@
-import { TagSearchPage, UserWorksPage } from "src/page-loaders";
+import { SeriesPage, TagSearchPage, UserWorksPage } from "src/page-loaders";
 import { TagSearchResultSummary } from "types/entities";
 
 const parseIntOrThrow = (text: string) => {
@@ -17,7 +17,7 @@ export const getTotalResults = (page: TagSearchPage) => {
   return totalResultsMatch ? parseIntOrThrow(totalResultsMatch[1]) : 0;
 };
 
-export const getPagesCount = (page: TagSearchPage | UserWorksPage) => {
+export const getPagesCount = (page: TagSearchPage | UserWorksPage | SeriesPage) => {
   const lastPageMatch = page(".pagination.actions li:not(.next, .previous)")
     .last()
     .text();

src/urls.ts

@@ -72,12 +72,22 @@ export const getWorkIndexUrl = ({ workId }: { workId: string | number }) => {
   return new URL(`works/${workId}/navigate`, getArchiveBaseUrl()).href;
 };
 
-export const getSeriesUrl = ({ seriesId }: { seriesId: string | number }) => {
+export const getSeriesUrl = ({
+  seriesId,
+  page,
+}: {
+  seriesId: string | number;
+  page?: number;
+}) => {
   if (!isValidArchiveId(seriesId)) {
     throw new InvalidIDError(seriesId, "series");
   }
 
-  return new URL(`series/${seriesId}`, getArchiveBaseUrl()).href;
+  const url = new URL(`series/${seriesId}`, getArchiveBaseUrl());
+  if (page !== undefined) {
+    url.searchParams.set("page", String(page));
+  }
+  return url.href;
 };
 
 export const getAsShortUrl = ({ url }: { url: string | URL }) => {

tests/mocks/handlers/series/index.ts

@@ -1,19 +1,11 @@
 import fs from "fs";
-import path from "path";
 import { http, HttpHandler, HttpResponse } from "msw";
-import { getArchiveDataDir, safeFilenamify } from "../../scripts/utils.mjs";
+import { getFilePathFromUrl } from "../../scripts/utils.mjs";
 
 export default http.all(
   "https://archiveofourown.org/series/:series_id",
-  ({ params }) => {
-    const html = fs.readFileSync(
-      path.resolve(
-        getArchiveDataDir(),
-        "series",
-        safeFilenamify(params.series_id as string),
-        "index.html"
-      )
-    );
+  ({ request }) => {
+    const html = fs.readFileSync(getFilePathFromUrl(request.url));
 
     return new HttpResponse(html, {
       headers: { "Content-Type": "text/html" },

tests/mocks/scripts/utils.mts

@@ -279,6 +279,12 @@ export function getUrlFromPath(
 
   const segments = urlPath.split(path.sep).filter(Boolean);
 
+  if (segments[0] === "series" && /^\d+\.html$/.test(filename)) {
+    const url = new URL(`/${segments.join("/")}`, getArchiveUrl(archive));
+    url.searchParams.set("page", String(parseInt(filename, 10)));
+    return url.href;
+  }
+
   if (
     segments[0] === "users" &&
     segments[segments.length - 2] === "works" &&
@@ -334,6 +340,15 @@ export function getFilePathFromUrl(url: string | URL) {
   const lastSegment = segments[segments.length - 1];
   const hasExtension = lastSegment?.includes(".");
 
+  if (segments[0] === "series" && parsedUrl.searchParams.has("page")) {
+    const pageFileName = getPageFileName(parsedUrl.searchParams);
+    return path.join(
+      getArchiveDataDir(archive),
+      ...segments.map((segment) => safeFilenamify(decodeURIComponent(segment))),
+      pageFileName === "01.html" ? "index.html" : pageFileName,
+    );
+  }
+
   if (segments[0] === "tags" && lastSegment === "search") {
     return path.join(
       getArchiveDataDir(archive),

tests/series.test.ts

@@ -430,3 +430,39 @@ describe("Series/title", () => {
     expect(series.name).toBe("*Insert Fandom* but Social Media (one-shots)");
   });
 });
+
+describe("Series/pagination", () => {
+  it("should fetch the first page with no page parameter", async () => {
+    const series = await getSeries({ seriesId: 60910 });
+
+    expect(series.name).toBe("Fandom Stats");
+    expect(series.pages).toEqual({ total: 7, current: 1 });
+    expect(series.works.map((work) => work.id)).toEqual([
+      16890957, 1026780, 1026854, 16876149, 16891416,
+      16926933, 16932096, 16933218, 17009412, 17009619,
+      17009676, 17011452, 17011545, 17011641, 17011701,
+      17011803, 17012055, 17012217, 1608254, 1704926,
+    ]);
+  });
+
+  it("should fetch the requested page", async () => {
+    const series = await getSeries({ seriesId: 60910, page: 2 });
+
+    expect(series.name).toBe("Fandom Stats");
+    expect(series.pages).toEqual({ total: 7, current: 2 });
+    expect(series.works.map((work) => work.id)).toEqual([
+      1706072, 1708259, 2076084, 16844275, 16861600,
+      16890750, 16890834, 16910946, 16913802, 16913982,
+      16925628, 17014116, 17013705, 17009067, 17009250,
+      17012409, 17012583, 16965927, 17002176, 16933407,
+    ]);
+  });
+
+  it("should return one page for a series without pagination", async () => {
+    const series = await getSeries({ seriesId: 2270465 });
+
+    expect(series.pages).toEqual({ total: 1, current: 1 });
+    expect(series.works).toHaveLength(6);
+  });
+
+});

tests/urls.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest";
 import {
   getAuthorFromUrl,
   getSearchUrlFromTagFilters,
+  getSeriesUrl,
   getTagUrl,
   getTagWorksFeedUrl,
   getUserDetailsFromUrl,
@@ -540,3 +541,18 @@ describe("getUserDetailsFromUrl", () => {
     );
   });
 });
+
+
+describe("getSeriesUrl", () => {
+  it("should preserve the URL without a page", () => {
+    expect(getSeriesUrl({ seriesId: 2270465 })).toBe(
+      "https://archiveofourown.org/series/2270465",
+    );
+  });
+
+  it("should add an optional page", () => {
+    expect(getSeriesUrl({ seriesId: "2270465", page: 2 })).toBe(
+      "https://archiveofourown.org/series/2270465?page=2",
+    );
+  });
+});

tsdown.config.ts

@@ -8,10 +8,11 @@ export default defineConfig([
       index: resolve(import.meta.dirname, "src/index.ts"),
       urls: resolve(import.meta.dirname, "src/urls.ts"),
       "zod-schemas": resolve(import.meta.dirname, "types/zod/generated/schemas.ts"),
+      "zod-schemas-v4": resolve(import.meta.dirname, "types/zod/generated/schemas-v4.ts"),
     },
     dts: true,
     clean: true,
     unbundle: true,
-    external: ["zod"],
+    external: [/^zod(\/.*)?$/],
   },
 ]);

types/entities.ts

@@ -149,6 +149,10 @@ export interface Series {
   bookmarks: number;
   complete: boolean;
   workCount: number;
+  pages: {
+    total: number;
+    current: number;
+  };
   works: WorkBlurbSummary[];
 }
 

types/zod/fix-schemas.mjs

@@ -1,21 +1,18 @@
 /**
- * Post-processes schemas generated by ts-to-zod to fix enum handling: ts-to-zod
- * generates z.enum(EnumName) but Zod v3 requires z.nativeEnum(EnumName) for
- * TypeScript enums.
+ * ts-to-zod generates Zod 4 code, but we still support Zod 3 consumers.
+ * This post-processing is needed to produce both entry points: the Zod 4
+ * file explicitly imports zod/v4, while the existing Zod 3 file uses
+ * z.nativeEnum() for TypeScript enums. Both come from the same generator run.
  */
 import { readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 
 const ENUM_PATTERN = /z\.enum\(([A-Z][a-zA-Z0-9]*)\)/g;
 
 const schemasPath = resolve(import.meta.dirname, "generated/schemas.ts");
+const v4SchemasPath = resolve(import.meta.dirname, "generated/schemas-v4.ts");
 const content = readFileSync(schemasPath, "utf-8");
-const fixedContent = content.replace(ENUM_PATTERN, "z.nativeEnum($1)");
+writeFileSync(v4SchemasPath, content.replace('from "zod"', 'from "zod/v4"'));
+writeFileSync(schemasPath, content.replace(ENUM_PATTERN, "z.nativeEnum($1)"));
 
-const matches = content.match(ENUM_PATTERN);
-if (matches) {
-  console.log(`✔ Fixed ${matches.length} enum schemas to use z.nativeEnum()`);
-}
-
-writeFileSync(schemasPath, fixedContent);
-console.log("✔ Generated types/zod/schemas.ts");
+console.log("✔ Generated Zod 3 and Zod 4 schemas");