@zenalexa/unicli 0.207.1

package/src/adapters/xiaohongshu/creator-notes.ts

@@ -0,0 +1,161 @@
+/**
+ * Xiaohongshu Creator Note List — per-note metrics from the creator backend.
+ *
+ * Captures the real creator analytics API response so the list
+ * includes stable note ids and detail-page URLs.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+
+const NOTE_ANALYZE_API_PATH =
+  "/api/galaxy/creator/datacenter/note/analyze/list";
+const NOTE_DETAIL_PAGE_URL =
+  "https://creator.xiaohongshu.com/statistics/note-detail";
+
+export interface CreatorNoteRow {
+  id: string;
+  title: string;
+  date: string;
+  views: number;
+  likes: number;
+  collects: number;
+  comments: number;
+  url: string;
+}
+
+interface CreatorAnalyzeApiResponse {
+  error?: string;
+  data?: {
+    note_infos?: Array<{
+      id?: string;
+      title?: string;
+      post_time?: number;
+      read_count?: number;
+      like_count?: number;
+      fav_count?: number;
+      comment_count?: number;
+    }>;
+    total?: number;
+  };
+}
+
+function buildNoteDetailUrl(noteId?: string): string {
+  return noteId
+    ? `${NOTE_DETAIL_PAGE_URL}?noteId=${encodeURIComponent(noteId)}`
+    : "";
+}
+
+function formatPostTime(ts?: number): string {
+  if (!ts) return "";
+  const date = new Date(ts + 8 * 3600_000);
+  const pad = (value: number) => String(value).padStart(2, "0");
+  return `${date.getUTCFullYear()}年${pad(date.getUTCMonth() + 1)}月${pad(date.getUTCDate())}日 ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}`;
+}
+
+function mapAnalyzeItems(
+  items: NonNullable<CreatorAnalyzeApiResponse["data"]>["note_infos"],
+): CreatorNoteRow[] {
+  return (items ?? []).map((item) => ({
+    id: item.id ?? "",
+    title: item.title ?? "",
+    date: formatPostTime(item.post_time),
+    views: item.read_count ?? 0,
+    likes: item.like_count ?? 0,
+    collects: item.fav_count ?? 0,
+    comments: item.comment_count ?? 0,
+    url: buildNoteDetailUrl(item.id),
+  }));
+}
+
+export async function fetchCreatorNotes(
+  page: IPage,
+  limit: number,
+): Promise<CreatorNoteRow[]> {
+  const pageSize = Math.min(Math.max(limit, 10), 20);
+  const maxPages = Math.max(1, Math.ceil(limit / pageSize));
+  const notes: CreatorNoteRow[] = [];
+
+  await page.goto(
+    `https://creator.xiaohongshu.com/statistics/data-analysis?type=0&page_size=${pageSize}&page_num=1`,
+  );
+
+  for (
+    let pageNum = 1;
+    pageNum <= maxPages && notes.length < limit;
+    pageNum++
+  ) {
+    const apiPath = `${NOTE_ANALYZE_API_PATH}?type=0&page_size=${pageSize}&page_num=${pageNum}`;
+    const fetched = (await page.evaluate(`
+      async () => {
+        try {
+          const resp = await fetch(${JSON.stringify(apiPath)}, { credentials: 'include' });
+          if (!resp.ok) return { error: 'HTTP ' + resp.status };
+          return await resp.json();
+        } catch (e) {
+          return { error: e?.message ?? String(e) };
+        }
+      }
+    `)) as CreatorAnalyzeApiResponse | undefined;
+
+    const items = fetched?.data?.note_infos ?? [];
+    if (!items.length) break;
+
+    notes.push(...mapAnalyzeItems(items));
+    if (items.length < pageSize) break;
+  }
+
+  return notes.slice(0, limit);
+}
+
+cli({
+  site: "xiaohongshu",
+  name: "creator-notes",
+  description:
+    "Xiaohongshu creator note list with per-note metrics (title/date/views/likes/collects/comments)",
+  domain: "creator.xiaohongshu.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    {
+      name: "limit",
+      type: "int",
+      default: 20,
+      description: "Number of notes to return",
+    },
+  ],
+  columns: [
+    "rank",
+    "id",
+    "title",
+    "date",
+    "views",
+    "likes",
+    "collects",
+    "comments",
+    "url",
+  ],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const limit = Number(kwargs.limit) || 20;
+    const notes = await fetchCreatorNotes(p, limit);
+
+    if (!Array.isArray(notes) || notes.length === 0) {
+      throw new Error(
+        "No notes found. Are you logged into creator.xiaohongshu.com?",
+      );
+    }
+
+    return notes.slice(0, limit).map((n, i) => ({
+      rank: i + 1,
+      id: n.id,
+      title: n.title,
+      date: n.date,
+      views: n.views,
+      likes: n.likes,
+      collects: n.collects,
+      comments: n.comments,
+      url: n.url,
+    }));
+  },
+});

package/src/adapters/xiaohongshu/creator-profile.ts

@@ -0,0 +1,69 @@
+/**
+ * Xiaohongshu Creator Profile — creator account info and growth status.
+ *
+ * Uses the creator.xiaohongshu.com internal API (cookie auth).
+ * Returns follower/following counts, total likes+collects, and
+ * creator level growth info.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+
+cli({
+  site: "xiaohongshu",
+  name: "creator-profile",
+  description:
+    "Xiaohongshu creator account info (followers/following/likes/level)",
+  domain: "creator.xiaohongshu.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [],
+  columns: ["field", "value"],
+  func: async (page, _kwargs) => {
+    const p = page as IPage;
+    await p.goto("https://creator.xiaohongshu.com/new/home");
+
+    const data = (await p.evaluate(`
+      async () => {
+        try {
+          const resp = await fetch('/api/galaxy/creator/home/personal_info', {
+            credentials: 'include',
+          });
+          if (!resp.ok) return { error: 'HTTP ' + resp.status };
+          return await resp.json();
+        } catch (e) {
+          return { error: e.message };
+        }
+      }
+    `)) as Record<string, unknown>;
+
+    if (data?.error) {
+      throw new Error(
+        `${data.error}. Are you logged into creator.xiaohongshu.com?`,
+      );
+    }
+
+    const d = (data?.data ?? {}) as Record<string, unknown>;
+    if (!d || typeof d !== "object") {
+      throw new Error("Unexpected response structure");
+    }
+
+    const grow = (d.grow_info ?? {}) as Record<string, unknown>;
+
+    return [
+      { field: "Name", value: String(d.name ?? "") },
+      { field: "Followers", value: String(d.fans_count ?? 0) },
+      { field: "Following", value: String(d.follow_count ?? 0) },
+      { field: "Likes & Collects", value: String(d.faved_count ?? 0) },
+      { field: "Creator Level", value: String(grow.level ?? 0) },
+      {
+        field: "Level Progress",
+        value: `${grow.fans_count ?? 0}/${grow.max_fans_count ?? 0} fans`,
+      },
+      {
+        field: "Bio",
+        value: String(d.personal_desc ?? "").replace(/\n/g, " | "),
+      },
+    ];
+  },
+});

package/src/adapters/xiaohongshu/creator-stats.ts

@@ -0,0 +1,116 @@
+/**
+ * Xiaohongshu Creator Analytics — account-level metrics overview.
+ *
+ * Uses the creator.xiaohongshu.com internal API (cookie auth).
+ * Returns 7-day and 30-day aggregate stats: views, likes, collects,
+ * comments, shares, new followers, and daily trend data.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+
+cli({
+  site: "xiaohongshu",
+  name: "creator-stats",
+  description:
+    "Xiaohongshu creator analytics overview (views/likes/collects/comments/shares/followers + daily trend)",
+  domain: "creator.xiaohongshu.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    {
+      name: "period",
+      default: "seven",
+      description: "Stats period: seven or thirty",
+      choices: ["seven", "thirty"],
+    },
+  ],
+  columns: ["metric", "total", "trend"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const period: string = String(kwargs.period || "seven");
+
+    await p.goto("https://creator.xiaohongshu.com/new/home");
+
+    const data = (await p.evaluate(`
+      async () => {
+        try {
+          const resp = await fetch('/api/galaxy/creator/data/note_detail_new', {
+            credentials: 'include',
+          });
+          if (!resp.ok) return { error: 'HTTP ' + resp.status };
+          return await resp.json();
+        } catch (e) {
+          return { error: e.message };
+        }
+      }
+    `)) as Record<string, unknown>;
+
+    if (data?.error) {
+      throw new Error(
+        `${data.error}. Are you logged into creator.xiaohongshu.com?`,
+      );
+    }
+
+    const allData = (data?.data ?? {}) as Record<string, unknown>;
+    if (!allData) {
+      throw new Error("Unexpected response structure");
+    }
+
+    const stats = allData[period] as Record<string, unknown> | undefined;
+    if (!stats) {
+      throw new Error(
+        `No data for period "${period}". Available: ${Object.keys(allData).join(", ")}`,
+      );
+    }
+
+    const formatTrend = (list: unknown): string => {
+      if (!Array.isArray(list) || !list.length) return "-";
+      return list.map((d: Record<string, unknown>) => d.count).join(" -> ");
+    };
+
+    return [
+      {
+        metric: "views",
+        total: stats.view_count ?? 0,
+        trend: formatTrend(stats.view_list),
+      },
+      {
+        metric: "avg_view_time_ms",
+        total: stats.view_time_avg ?? 0,
+        trend: formatTrend(stats.view_time_list),
+      },
+      {
+        metric: "home_views",
+        total: stats.home_view_count ?? 0,
+        trend: formatTrend(stats.home_view_list),
+      },
+      {
+        metric: "likes",
+        total: stats.like_count ?? 0,
+        trend: formatTrend(stats.like_list),
+      },
+      {
+        metric: "collects",
+        total: stats.collect_count ?? 0,
+        trend: formatTrend(stats.collect_list),
+      },
+      {
+        metric: "comments",
+        total: stats.comment_count ?? 0,
+        trend: formatTrend(stats.comment_list),
+      },
+      { metric: "danmaku", total: stats.danmaku_count ?? 0, trend: "-" },
+      {
+        metric: "shares",
+        total: stats.share_count ?? 0,
+        trend: formatTrend(stats.share_list),
+      },
+      {
+        metric: "new_followers",
+        total: stats.rise_fans_count ?? 0,
+        trend: formatTrend(stats.rise_fans_list),
+      },
+    ];
+  },
+});

package/src/adapters/xiaohongshu/download.ts

@@ -0,0 +1,170 @@
+/**
+ * Xiaohongshu download — download images and videos from a note.
+ *
+ * Navigates to the note page, extracts media URLs from DOM and
+ * __INITIAL_STATE__, then downloads them with cookie authentication.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+import { loadCookies, formatCookieHeader } from "../../engine/cookies.js";
+import { parseNoteId, buildNoteUrl } from "./note-helpers.js";
+
+/** Build authenticated headers for Xiaohongshu downloads. */
+function buildCookieHeader(): string {
+  const cookies = loadCookies("xiaohongshu");
+  if (cookies) return formatCookieHeader(cookies);
+  return "";
+}
+
+cli({
+  site: "xiaohongshu",
+  name: "download",
+  description: "Download images and videos from a Xiaohongshu note",
+  domain: "www.xiaohongshu.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    {
+      name: "note-id",
+      positional: true,
+      required: true,
+      description: "Note ID, full URL, or short link",
+    },
+    {
+      name: "output",
+      default: "./xiaohongshu-downloads",
+      description: "Output directory",
+    },
+  ],
+  columns: ["index", "type", "url"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const rawInput = String(kwargs["note-id"]);
+    const noteId = parseNoteId(rawInput);
+
+    await p.goto(buildNoteUrl(rawInput));
+    await p.wait(3);
+
+    const data = (await p.evaluate(`
+      (() => {
+        const result = {
+          noteId: '${noteId}',
+          title: '',
+          author: '',
+          media: []
+        };
+        const seenMedia = new Set();
+        const pushMedia = (type, url) => {
+          if (!url) return;
+          const key = type + ':' + url;
+          if (seenMedia.has(key)) return;
+          seenMedia.add(key);
+          result.media.push({ type, url });
+        };
+
+        // Get title
+        const titleEl = document.querySelector('.title, #detail-title, .note-content .title');
+        result.title = titleEl?.textContent?.trim() || 'untitled';
+
+        // Get author
+        const authorEl = document.querySelector('.username, .author-name, .name');
+        result.author = authorEl?.textContent?.trim() || 'unknown';
+
+        // Get images
+        const imageSelectors = [
+          '.swiper-slide img',
+          '.carousel-image img',
+          '.note-slider img',
+          '.note-image img',
+          '.image-wrapper img',
+          '#noteContainer .media-container img[src*="xhscdn"]',
+          'img[src*="ci.xiaohongshu.com"]'
+        ];
+        const imageUrls = new Set();
+        for (const selector of imageSelectors) {
+          document.querySelectorAll(selector).forEach(img => {
+            let src = img.src || img.getAttribute('data-src') || '';
+            if (src && (src.includes('xhscdn') || src.includes('xiaohongshu'))) {
+              src = src.split('?')[0];
+              imageUrls.add(src);
+            }
+          });
+        }
+
+        // Get video from __INITIAL_STATE__
+        try {
+          const state = window.__INITIAL_STATE__;
+          if (state) {
+            const noteData = state.note?.noteDetailMap || state.note?.note || {};
+            for (const key of Object.keys(noteData)) {
+              const note = noteData[key]?.note || noteData[key];
+              const video = note?.video;
+              if (video) {
+                const vUrl = video.url || video.originVideoKey || video.consumer?.originVideoKey;
+                if (vUrl) {
+                  const fullUrl = vUrl.startsWith('http') ? vUrl : 'https://sns-video-bd.xhscdn.com/' + vUrl;
+                  pushMedia('video', fullUrl);
+                }
+                const streams = video.media?.stream?.h264 || [];
+                for (const stream of streams) {
+                  if (stream.masterUrl) pushMedia('video', stream.masterUrl);
+                }
+              }
+            }
+          }
+        } catch(e) {}
+
+        // Fallback: video from inline scripts
+        if (result.media.filter(m => m.type === 'video').length === 0) {
+          try {
+            const scripts = document.querySelectorAll('script');
+            for (const s of scripts) {
+              const text = s.textContent || '';
+              const videoMatches = text.match(/https?:\\/\\/sns-video[^"'\\s]+\\.mp4[^"'\\s]*/g)
+                || text.match(/https?:\\/\\/[^"'\\s]*xhscdn[^"'\\s]*\\.mp4[^"'\\s]*/g);
+              if (videoMatches) {
+                videoMatches.forEach(url => {
+                  pushMedia('video', url.replace(/\\\\u002F/g, '/'));
+                });
+              }
+            }
+          } catch(e) {}
+        }
+
+        // Fallback: video from DOM
+        if (result.media.filter(m => m.type === 'video').length === 0) {
+          const videoSelectors = ['video source', 'video[src]', '.player video', '.video-player video'];
+          for (const selector of videoSelectors) {
+            document.querySelectorAll(selector).forEach(v => {
+              const src = v.src || v.getAttribute('src') || '';
+              if (src && !src.startsWith('blob:')) {
+                pushMedia('video', src);
+              }
+            });
+          }
+        }
+
+        // Add images to media
+        imageUrls.forEach(url => pushMedia('image', url));
+        return result;
+      })()
+    `)) as {
+      noteId: string;
+      media: Array<{ type: string; url: string }>;
+    } | null;
+
+    if (!data || !data.media || data.media.length === 0) {
+      return [{ index: 0, type: "-", url: "No media found" }];
+    }
+
+    // Cookie header available for authenticated downloads when media pipeline is wired
+    void buildCookieHeader();
+
+    return data.media.map((m: { type: string; url: string }, idx: number) => ({
+      index: idx + 1,
+      type: m.type,
+      url: m.url,
+    }));
+  },
+});

package/src/adapters/xiaohongshu/feed.yaml

@@ -0,0 +1,31 @@
+site: xiaohongshu
+name: feed
+description: "Xiaohongshu home feed (via Pinia Store Action)"
+domain: www.xiaohongshu.com
+strategy: intercept
+browser: true
+
+args:
+  limit:
+    type: int
+    default: 20
+    description: Number of items to return
+
+columns: [title, author, likes, type, url]
+
+pipeline:
+  - navigate: https://www.xiaohongshu.com/explore
+  - tap:
+      store: feed
+      action: fetchFeeds
+      capture: homefeed
+      select: data.items
+      timeout: 8
+  - map:
+      id: ${{ item.id }}
+      title: ${{ item.note_card.display_title }}
+      type: ${{ item.note_card.type }}
+      author: ${{ item.note_card.user.nickname }}
+      likes: ${{ item.note_card.interact_info.liked_count }}
+      url: https://www.xiaohongshu.com/explore/${{ item.id }}
+  - limit: ${{ args.limit | default(20) }}

package/src/adapters/xiaohongshu/note-helpers.ts

@@ -0,0 +1,24 @@
+/** Side-effect-free helpers shared by xiaohongshu note and comments commands. */
+
+/** Extract a bare note ID from a full URL or raw ID string. */
+export function parseNoteId(input: string): string {
+  const trimmed = input.trim();
+  const match = trimmed.match(/\/(?:explore|note|search_result)\/([a-f0-9]+)/);
+  return match ? match[1] : trimmed;
+}
+
+/**
+ * Build the best navigation URL for a note.
+ *
+ * XHS blocks direct `/explore/<id>` access without a valid `xsec_token`.
+ * When the user passes a full URL (from search results), we preserve it
+ * so the browser navigates with the token intact.  For bare IDs we fall
+ * back to the `/explore/<id>` path (works when cookies carry enough context).
+ */
+export function buildNoteUrl(input: string): string {
+  const trimmed = input.trim();
+  if (/^https?:\/\//.test(trimmed)) {
+    return trimmed;
+  }
+  return `https://www.xiaohongshu.com/explore/${trimmed}`;
+}

package/src/adapters/xiaohongshu/note.ts

@@ -0,0 +1,101 @@
+/**
+ * Xiaohongshu note — read full note content from a public note page.
+ *
+ * Extracts title, author, description text, and engagement metrics
+ * (likes, collects, comment count) via DOM extraction.
+ */
+
+import { cli, Strategy } from "../../registry.js";
+import type { IPage } from "../../types.js";
+import { parseNoteId, buildNoteUrl } from "./note-helpers.js";
+
+cli({
+  site: "xiaohongshu",
+  name: "note",
+  description: "Get note content and engagement metrics",
+  domain: "www.xiaohongshu.com",
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    {
+      name: "note-id",
+      required: true,
+      positional: true,
+      description: "Note ID or full URL (preserves xsec_token for access)",
+    },
+  ],
+  columns: ["field", "value"],
+  func: async (page, kwargs) => {
+    const p = page as IPage;
+    const raw = String(kwargs["note-id"]);
+    const isBareNoteId = !/^https?:\/\//.test(raw.trim());
+    const noteId = parseNoteId(raw);
+    const url = buildNoteUrl(raw);
+
+    await p.goto(url);
+    await p.wait(3);
+
+    const data = (await p.evaluate(`
+      (() => {
+        const loginWall = /登录后查看|请登录/.test(document.body.innerText || '')
+        const notFound = /页面不见了|笔记不存在|无法浏览/.test(document.body.innerText || '')
+        const clean = (el) => (el?.textContent || '').replace(/\\s+/g, ' ').trim()
+        const title = clean(document.querySelector('#detail-title, .title'))
+        const desc = clean(document.querySelector('#detail-desc, .desc, .note-text'))
+        const author = clean(document.querySelector('.username, .author-wrapper .name'))
+        const likes = clean(document.querySelector('.like-wrapper .count'))
+        const collects = clean(document.querySelector('.collect-wrapper .count'))
+        const comments = clean(document.querySelector('.chat-wrapper .count'))
+        const tags = []
+        document.querySelectorAll('#detail-desc a.tag, #detail-desc a[href*="search_result"]').forEach(el => {
+          const t = (el.textContent || '').trim()
+          if (t) tags.push(t)
+        })
+        return { loginWall, notFound, title, desc, author, likes, collects, comments, tags }
+      })()
+    `)) as Record<string, unknown>;
+
+    if (!data || typeof data !== "object") {
+      throw new Error("Unexpected evaluate response");
+    }
+
+    if (data.loginWall) {
+      throw new Error("Note content requires login to www.xiaohongshu.com");
+    }
+
+    if (data.notFound) {
+      throw new Error(
+        `Note ${noteId} not found or unavailable — it may have been deleted or restricted`,
+      );
+    }
+
+    const numOrZero = (v: string) => (/^\d+/.test(v) ? v : "0");
+    const emptyShell = !data.title && !data.author;
+    if (emptyShell) {
+      if (isBareNoteId) {
+        throw new Error(
+          "Pass the full search_result URL with xsec_token instead of a bare note ID.",
+        );
+      }
+      throw new Error(
+        "The note page loaded without visible content. Retry with a fresh URL.",
+      );
+    }
+
+    const rows: Array<{ field: string; value: string }> = [
+      { field: "title", value: String(data.title ?? "") },
+      { field: "author", value: String(data.author ?? "") },
+      { field: "content", value: String(data.desc ?? "") },
+      { field: "likes", value: numOrZero(String(data.likes ?? "")) },
+      { field: "collects", value: numOrZero(String(data.collects ?? "")) },
+      { field: "comments", value: numOrZero(String(data.comments ?? "")) },
+    ];
+
+    const tags = data.tags as string[] | undefined;
+    if (tags?.length) {
+      rows.push({ field: "tags", value: tags.join(", ") });
+    }
+
+    return rows;
+  },
+});