@zenalexa/unicli 0.219.0 → 0.220.0

package/src/adapters/zhihu/collection.ts

@@ -0,0 +1,239 @@
+/**
+ * @owner   src/adapters/zhihu/collection.ts
+ * @does    Register agent-facing Zhihu collection item reader.
+ * @needs   Logged-in Zhihu browser session, collection item API, bounded pagination.
+ * @feeds   surface coverage ledger, Zhihu collection content workflows, answer/article/pin rows.
+ * @breaks  Zhihu collection API shape drift or weak content mapping can hide saved items.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+
+interface ZhihuCollectionItem {
+  content?: {
+    type?: unknown;
+    id?: unknown;
+    url?: unknown;
+    content?: unknown;
+    question?: { id?: unknown; title?: unknown };
+    title?: unknown;
+    author?: { name?: unknown };
+    voteup_count?: unknown;
+    reaction_count?: unknown;
+  };
+}
+
+interface ZhihuPage {
+  data?: ZhihuCollectionItem[];
+  paging?: {
+    totals?: unknown;
+    is_end?: unknown;
+    next?: unknown;
+  };
+  __httpError?: unknown;
+}
+
+function stringField(value: unknown): string {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function numberField(value: unknown): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : 0;
+}
+
+export function stripZhihuHtml(value: unknown): string {
+  return stringField(value)
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"')
+    .trim();
+}
+
+export function requireZhihuCollectionId(value: unknown): string {
+  const id = String(value ?? "").trim();
+  if (!/^\d+$/.test(id))
+    throw new Error("Zhihu collection ID must be numeric.");
+  return id;
+}
+
+export function requireZhihuPositiveInt(value: unknown, label: string): number {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new Error(`zhihu collection ${label} must be a positive integer.`);
+  }
+  return n;
+}
+
+export function requireZhihuNonNegativeInt(
+  value: unknown,
+  label: string,
+): number {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new Error(
+      `zhihu collection ${label} must be a non-negative integer.`,
+    );
+  }
+  return n;
+}
+
+export function zhihuCollectionItemKey(item: ZhihuCollectionItem): string {
+  const content = item.content ?? {};
+  return `${stringField(content.type) || "unknown"}:${stringField(
+    content.id || content.url || JSON.stringify(content).slice(0, 80),
+  )}`;
+}
+
+export function mapZhihuCollectionItem(
+  item: ZhihuCollectionItem,
+  rank: number,
+): Record<string, unknown> {
+  const content = item.content ?? {};
+  const type = stringField(content.type) || "unknown";
+  let title = "";
+  let excerpt = "";
+  let url = "";
+  let author = "";
+  let votes = 0;
+  if (type === "answer") {
+    const question = content.question ?? {};
+    title = stringField(question.title);
+    excerpt = stripZhihuHtml(content.content).slice(0, 150);
+    url =
+      stringField(content.url) ||
+      `https://www.zhihu.com/question/${stringField(question.id)}/answer/${stringField(content.id)}`;
+    author = stringField(content.author?.name) || "匿名用户";
+    votes = numberField(content.voteup_count);
+  } else if (type === "article") {
+    title = stringField(content.title);
+    excerpt = stripZhihuHtml(content.content).slice(0, 150);
+    url =
+      stringField(content.url) ||
+      `https://zhuanlan.zhihu.com/p/${stringField(content.id)}`;
+    author = stringField(content.author?.name) || "匿名用户";
+    votes = numberField(content.voteup_count);
+  } else if (type === "pin") {
+    title = "想法";
+    const blocks = Array.isArray(content.content) ? content.content : [];
+    excerpt = stripZhihuHtml(
+      blocks
+        .map((block) =>
+          typeof block === "object" && block !== null && "content" in block
+            ? stringField((block as { content?: unknown }).content)
+            : "",
+        )
+        .join(" "),
+    ).slice(0, 150);
+    url =
+      stringField(content.url) ||
+      `https://www.zhihu.com/pin/${stringField(content.id)}`;
+    author = stringField(content.author?.name) || "匿名用户";
+    votes = numberField(content.reaction_count);
+  }
+  return {
+    rank,
+    type,
+    title: title.slice(0, 100),
+    author,
+    votes,
+    excerpt,
+    url,
+  };
+}
+
+function nextOffsetFromPaging(page: ZhihuPage, fallback: number): number {
+  const next = stringField(page.paging?.next);
+  if (next) {
+    try {
+      const url = new URL(next);
+      const parsed = Number(url.searchParams.get("offset"));
+      if (Number.isInteger(parsed) && parsed > fallback) return parsed;
+    } catch {
+      return fallback;
+    }
+  }
+  return fallback;
+}
+
+cli({
+  site: "zhihu",
+  name: "collection",
+  description: "List items in a Zhihu collection",
+  domain: "www.zhihu.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    {
+      name: "id",
+      type: "str",
+      required: true,
+      positional: true,
+      description: "Collection ID",
+    },
+    { name: "offset", type: "int", default: 0, description: "Starting offset" },
+    { name: "limit", type: "int", default: 20, description: "Number of items" },
+  ],
+  columns: ["rank", "type", "title", "author", "votes", "excerpt", "url"],
+  func: async (page, kwargs) => {
+    const browserPage = page as {
+      goto: (url: string) => Promise<unknown>;
+      evaluate: (script: string) => Promise<ZhihuPage>;
+    };
+    const id = requireZhihuCollectionId(kwargs.id);
+    const offset = requireZhihuNonNegativeInt(kwargs.offset ?? 0, "offset");
+    const requestedLimit = requireZhihuPositiveInt(kwargs.limit ?? 20, "limit");
+    const pageLimit = Math.min(requestedLimit, 20);
+    await browserPage.goto("https://www.zhihu.com");
+    const collected: ZhihuCollectionItem[] = [];
+    const seen = new Set<string>();
+    let nextOffset = offset;
+    const maxPages = Math.ceil(requestedLimit / pageLimit) + 2;
+    for (
+      let pageIndex = 0;
+      pageIndex < maxPages && collected.length < requestedLimit;
+      pageIndex += 1
+    ) {
+      const fetchLimit = Math.min(pageLimit, requestedLimit - collected.length);
+      const url = `https://www.zhihu.com/api/v4/collections/${id}/items?offset=${nextOffset}&limit=${fetchLimit}`;
+      const data = await browserPage.evaluate(`(async () => {
+        const response = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
+        if (!response.ok) return { __httpError: response.status };
+        return await response.json();
+      })()`);
+      if (!data || data.__httpError) {
+        throw new Error(
+          `Zhihu collection request failed${data?.__httpError ? ` (HTTP ${String(data.__httpError)})` : ""}.`,
+        );
+      }
+      const items = Array.isArray(data.data) ? data.data : [];
+      for (const item of items) {
+        const key = zhihuCollectionItemKey(item);
+        if (!seen.has(key)) {
+          seen.add(key);
+          collected.push(item);
+        }
+        if (collected.length >= requestedLimit) break;
+      }
+      if (
+        items.length === 0 ||
+        data.paging?.is_end ||
+        collected.length >= requestedLimit
+      )
+        break;
+      const parsedNextOffset = nextOffsetFromPaging(data, nextOffset);
+      nextOffset =
+        parsedNextOffset > nextOffset
+          ? parsedNextOffset
+          : nextOffset + items.length;
+    }
+    if (collected.length === 0) {
+      throw new Error(`No items found for Zhihu collection ${id}.`);
+    }
+    return collected
+      .slice(0, requestedLimit)
+      .map((item, index) => mapZhihuCollectionItem(item, offset + index + 1));
+  },
+});

package/src/adapters/zlibrary/web.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it, vi } from "vitest";
+import { resolveCommand } from "../../registry.js";
+import {
+  buildZlibrarySearchUrl,
+  mapZlibrarySearchRows,
+  normalizeZlibraryBookUrl,
+  requireZlibraryLimit,
+} from "./web.js";
+
+function pageMock(evaluateResults: unknown[]) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn(async () => evaluateResults.shift()),
+  };
+}
+
+describe("zlibrary agent-facing commands", () => {
+  it("validates URLs, queries, limits, and maps rows", () => {
+    expect(buildZlibrarySearchUrl(" test book ")).toBe(
+      "https://z-library.im/s/test%20book",
+    );
+    expect(() => buildZlibrarySearchUrl(" ")).toThrow(
+      "Z-Library search query cannot be empty.",
+    );
+    expect(normalizeZlibraryBookUrl("https://z-library.im/book/demo")).toBe(
+      "https://z-library.im/book/demo",
+    );
+    expect(() =>
+      normalizeZlibraryBookUrl("https://example.com/book/demo"),
+    ).toThrow("Unsupported Z-Library URL host");
+    expect(requireZlibraryLimit("25")).toBe(25);
+    expect(() => requireZlibraryLimit(26)).toThrow(
+      "Z-Library search limit must be <= 25.",
+    );
+    expect(
+      mapZlibrarySearchRows([
+        {
+          rank: 1,
+          title: " Book ",
+          author: " Author ",
+          url: " https://z-library.im/book/demo ",
+        },
+      ]),
+    ).toEqual([
+      {
+        rank: 1,
+        title: "Book",
+        author: "Author",
+        url: "https://z-library.im/book/demo",
+      },
+    ]);
+  });
+
+  it("searches Z-Library results", async () => {
+    const command = resolveCommand("zlibrary", "search")?.command;
+    const page = pageMock([
+      [
+        {
+          rank: 1,
+          title: "Book",
+          author: "Author",
+          url: "https://z-library.im/book/demo",
+        },
+      ],
+    ]);
+    await expect(
+      command!.func!(page, { query: "book", limit: 10 }),
+    ).resolves.toEqual([
+      {
+        rank: 1,
+        title: "Book",
+        author: "Author",
+        url: "https://z-library.im/book/demo",
+      },
+    ]);
+    expect(page.goto).toHaveBeenCalledWith("https://z-library.im/s/book", {
+      waitUntil: "load",
+      settleMs: 3000,
+    });
+    expect(page.wait).toHaveBeenCalledWith(5);
+  });
+
+  it("extracts Z-Library book info and formats", async () => {
+    const command = resolveCommand("zlibrary", "info")?.command;
+    const page = pageMock([
+      "Demo Book",
+      undefined,
+      { pdf: "https://z-library.im/dl/pdf", epub: "" },
+    ]);
+    await expect(
+      command!.func!(page, { url: "https://z-library.im/book/demo" }),
+    ).resolves.toEqual([
+      {
+        title: "Demo Book",
+        pdf: "https://z-library.im/dl/pdf",
+        epub: "",
+        url: "https://z-library.im/book/demo",
+      },
+    ]);
+    expect(page.wait).toHaveBeenCalledWith(5);
+    expect(page.wait).toHaveBeenCalledWith(3);
+  });
+});

package/src/adapters/zlibrary/web.ts

@@ -0,0 +1,192 @@
+/**
+ * @owner   src/adapters/zlibrary/web.ts
+ * @does    Register agent-facing Z-Library search and info commands implemented with site-specific safety checks.
+ * @needs   Logged-in z-library.im browser session and Z-Library search/book page DOM.
+ * @feeds   surface coverage ledger, book search rows, and book detail/download-format discovery.
+ * @breaks  Z-Library host changes, login redirects, or z-bookcard shadow DOM drift can hide results.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+import { str } from "../_shared/browser-tools.js";
+
+const ZLIBRARY_DOMAIN = "z-library.im";
+const ZLIBRARY_ORIGIN = `https://${ZLIBRARY_DOMAIN}`;
+const ALLOWED_HOSTS = new Set([ZLIBRARY_DOMAIN, `www.${ZLIBRARY_DOMAIN}`]);
+
+interface ZlibraryFormatLinks {
+  pdf?: unknown;
+  epub?: unknown;
+}
+
+interface ZlibrarySearchRow {
+  rank?: unknown;
+  title?: unknown;
+  author?: unknown;
+  url?: unknown;
+}
+
+export function normalizeZlibraryBookUrl(value: unknown): string {
+  const raw = str(value).trim();
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(
+      `Z-Library book URL must be a valid http(s) URL under ${ZLIBRARY_DOMAIN}.`,
+    );
+  }
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    !ALLOWED_HOSTS.has(url.hostname)
+  ) {
+    throw new Error(
+      `Unsupported Z-Library URL host: ${url.hostname}. Expected ${ZLIBRARY_DOMAIN}.`,
+    );
+  }
+  return url.toString();
+}
+
+export function buildZlibrarySearchUrl(value: unknown): string {
+  const query = str(value).trim();
+  if (!query) throw new Error("Z-Library search query cannot be empty.");
+  return `${ZLIBRARY_ORIGIN}/s/${encodeURIComponent(query)}`;
+}
+
+export function requireZlibraryLimit(value: unknown, fallback = 10): number {
+  const raw = value ?? fallback;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error("Z-Library search limit must be a positive integer.");
+  }
+  if (limit > 25) throw new Error("Z-Library search limit must be <= 25.");
+  return limit;
+}
+
+export function mapZlibrarySearchRows(
+  rows: ZlibrarySearchRow[],
+): Record<string, unknown>[] {
+  return rows
+    .map((row, index) => ({
+      rank: Number(row.rank) || index + 1,
+      title: str(row.title).trim(),
+      author: str(row.author).trim(),
+      url: str(row.url).trim(),
+    }))
+    .filter((row) => row.title && row.url);
+}
+
+async function extractBookTitle(page: IPage): Promise<string> {
+  const title = await page.evaluate(`(() => {
+    const card = document.querySelector('z-bookcard');
+    if (card?.shadowRoot) {
+      const el = card.shadowRoot.querySelector('[class*="title"], h1, a');
+      if (el) return el.textContent.trim().split('\\n')[0].trim();
+    }
+    return document.title.replace(/\\s*[-|].*$/, '').trim();
+  })()`);
+  return str(title).trim();
+}
+
+async function extractFormats(
+  page: IPage,
+): Promise<{ pdf: string; epub: string }> {
+  await page.evaluate(`(() => {
+    const button = document.querySelector('button[aria-label*="more" i], [class*="dots" i], [class*="more" i]');
+    if (button instanceof HTMLElement) button.click();
+  })()`);
+  await page.wait(3);
+  const formats = await page.evaluate(`(() => {
+    const result = { pdf: '', epub: '' };
+    document.querySelectorAll('a[href]').forEach((anchor) => {
+      const href = anchor.href || '';
+      const text = (anchor.textContent || '').toUpperCase();
+      if (href.includes('/dl/') && text.includes('PDF')) result.pdf = href;
+      if (href.includes('/dl/') && text.includes('EPUB')) result.epub = href;
+    });
+    return result;
+  })()`);
+  const row =
+    typeof formats === "object" && formats !== null
+      ? (formats as ZlibraryFormatLinks)
+      : {};
+  return { pdf: str(row.pdf), epub: str(row.epub) };
+}
+
+async function extractSearchResults(
+  page: IPage,
+  limit: number,
+): Promise<Record<string, unknown>[]> {
+  const result = await page.evaluate(`(() => {
+    return Array.from(document.querySelectorAll('z-bookcard'))
+      .slice(0, ${JSON.stringify(limit)})
+      .map((card, index) => {
+        const text = (card.textContent || '').trim();
+        const lines = text.split('\\n').map((line) => line.trim()).filter(Boolean);
+        const title = lines[0] || '';
+        const author = lines[1] || '';
+        let url = '';
+        if (card.shadowRoot) {
+          const link = card.shadowRoot.querySelector('a');
+          if (link) url = link.href || '';
+        }
+        return { rank: index + 1, title, author, url };
+      });
+  })()`);
+  return mapZlibrarySearchRows(
+    Array.isArray(result) ? (result as ZlibrarySearchRow[]) : [],
+  );
+}
+
+cli({
+  site: "zlibrary",
+  name: "search",
+  description: "Search Z-Library for books by title, author, ISBN, or keyword",
+  domain: ZLIBRARY_DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: "query", type: "str", required: true, positional: true },
+    { name: "limit", type: "int", default: 10 },
+  ],
+  columns: ["rank", "title", "author", "url"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const limit = requireZlibraryLimit(kwargs.limit);
+    await p.goto(buildZlibrarySearchUrl(kwargs.query), {
+      waitUntil: "load",
+      settleMs: 3000,
+    });
+    await p.wait(5);
+    const rows = await extractSearchResults(p, limit);
+    if (!rows.length)
+      throw new Error("No Z-Library books found for the query.");
+    return rows;
+  },
+});
+
+cli({
+  site: "zlibrary",
+  name: "info",
+  description:
+    "Get book details and available download formats from a Z-Library book page",
+  domain: ZLIBRARY_DOMAIN,
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [{ name: "url", type: "str", required: true, positional: true }],
+  columns: ["title", "pdf", "epub", "url"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const url = normalizeZlibraryBookUrl(kwargs.url);
+    await p.goto(url, { waitUntil: "load", settleMs: 3000 });
+    await p.wait(5);
+    const title = await extractBookTitle(p);
+    const formats = await extractFormats(p);
+    if (!title || (!formats.pdf && !formats.epub)) {
+      throw new Error(
+        "Could not extract Z-Library title and download formats.",
+      );
+    }
+    return [{ title, pdf: formats.pdf, epub: formats.epub, url }];
+  },
+});