@jackwener/opencli 0.9.5 → 0.9.8

package/src/clis/xiaohongshu/creator-note-detail.ts

@@ -0,0 +1,95 @@
+/**
+ * Xiaohongshu Creator Note Detail — per-note analytics breakdown.
+ *
+ * Uses the creator.xiaohongshu.com internal API (cookie auth).
+ * Returns total reads, engagement, likes, collects, comments, shares
+ * for a specific note, split by channel (organic vs promoted vs video).
+ *
+ * Requires: logged into creator.xiaohongshu.com in Chrome.
+ */
+
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'creator-note-detail',
+  description: '小红书单篇笔记详细数据 (阅读/互动/点赞/收藏/评论/分享，区分自然流量/推广/视频)',
+  domain: 'creator.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: 'note_id', type: 'string', required: true, help: 'Note ID (from note URL or creator-notes command)' },
+  ],
+  columns: ['channel', 'reads', 'engagement', 'likes', 'collects', 'comments', 'shares'],
+  func: async (page, kwargs) => {
+    const noteId: string = kwargs.note_id;
+    const encodedNoteId = encodeURIComponent(noteId);
+
+    // Navigate for cookie context
+    await page.goto('https://creator.xiaohongshu.com/new/home');
+    await page.wait(2);
+
+    const data = await page.evaluate(`
+      async () => {
+        try {
+          const resp = await fetch(
+            '/api/galaxy/creator/data/note_detail?note_id=${encodedNoteId}',
+            { credentials: 'include' }
+          );
+          if (!resp.ok) return { error: 'HTTP ' + resp.status };
+          return await resp.json();
+        } catch (e) {
+          return { error: e.message };
+        }
+      }
+    `);
+
+    if (data?.error) {
+      throw new Error(data.error + '. Check note_id and login status.');
+    }
+    if (!data?.data) {
+      throw new Error('Unexpected response structure');
+    }
+
+    const d = data.data;
+
+    return [
+      {
+        channel: 'Total',
+        reads: d.total_read ?? 0,
+        engagement: d.total_engage ?? 0,
+        likes: d.total_like ?? 0,
+        collects: d.total_fav ?? 0,
+        comments: d.total_cmt ?? 0,
+        shares: d.total_share ?? 0,
+      },
+      {
+        channel: 'Organic',
+        reads: d.normal_read ?? 0,
+        engagement: d.normal_engage ?? 0,
+        likes: d.normal_like ?? 0,
+        collects: d.normal_fav ?? 0,
+        comments: d.normal_cmt ?? 0,
+        shares: d.normal_share ?? 0,
+      },
+      {
+        channel: 'Promoted',
+        reads: d.total_promo_read ?? 0,
+        engagement: 0,
+        likes: 0,
+        collects: 0,
+        comments: 0,
+        shares: 0,
+      },
+      {
+        channel: 'Video',
+        reads: d.video_read ?? 0,
+        engagement: d.video_engage ?? 0,
+        likes: d.video_like ?? 0,
+        collects: d.video_fav ?? 0,
+        comments: d.video_cmt ?? 0,
+        shares: d.video_share ?? 0,
+      },
+    ];
+  },
+});

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

@@ -0,0 +1,116 @@
+/**
+ * Xiaohongshu Creator Note List — per-note metrics from the creator backend.
+ *
+ * Navigates to the note manager page and extracts per-note data from
+ * the rendered DOM. This approach bypasses the v2 API signature requirement.
+ *
+ * Returns: note title, publish date, views, likes, collects, comments.
+ *
+ * Requires: logged into creator.xiaohongshu.com in Chrome.
+ */
+
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'creator-notes',
+  description: '小红书创作者笔记列表 + 每篇数据 (标题/日期/观看/点赞/收藏/评论)',
+  domain: 'creator.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    { name: 'limit', type: 'int', default: 20, help: 'Number of notes to return' },
+  ],
+  columns: ['rank', 'id', 'title', 'date', 'views', 'likes', 'collects', 'comments', 'url'],
+  func: async (page, kwargs) => {
+    const limit = kwargs.limit || 20;
+
+    // Navigate to note manager
+    await page.goto('https://creator.xiaohongshu.com/new/note-manager');
+    await page.wait(4);
+
+    // Scroll to load more notes if needed
+    await page.autoScroll({ times: Math.ceil(limit / 10), delayMs: 1500 });
+
+    // Extract note data from rendered DOM
+    const notes = await page.evaluate(`
+      (() => {
+        const results = [];
+        // Note cards in the manager page contain title, date, and metric numbers
+        // Each note card has a consistent structure with the title, date line,
+        // and a row of 4 numbers (views, likes, collects, comments)
+        const cards = document.querySelectorAll('[class*="note-item"], [class*="noteItem"], [class*="card"]');
+
+        if (cards.length === 0) {
+          // Fallback: parse from any container with note-like content
+          const allText = document.body.innerText;
+          const notePattern = /(.+?)\\s+发布于\\s+(\\d{4}年\\d{2}月\\d{2}日\\s+\\d{2}:\\d{2})\\s*(\\d+)\\s*(\\d+)\\s*(\\d+)\\s*(\\d+)/g;
+          let match;
+          while ((match = notePattern.exec(allText)) !== null) {
+            results.push({
+              title: match[1].trim(),
+              date: match[2],
+              views: parseInt(match[3]) || 0,
+              likes: parseInt(match[4]) || 0,
+              collects: parseInt(match[5]) || 0,
+              comments: parseInt(match[6]) || 0,
+            });
+          }
+          return results;
+        }
+
+        cards.forEach(card => {
+          const text = card.innerText || '';
+          const linkEl = card.querySelector('a[href*="/publish/"], a[href*="/note/"], a[href*="/explore/"]');
+          const href = linkEl?.getAttribute('href') || '';
+          const idMatch = href.match(/\/(?:publish|explore|note)\/([a-zA-Z0-9]+)/);
+          // Try to extract structured data
+          const lines = text.split('\\n').map(l => l.trim()).filter(Boolean);
+          if (lines.length < 2) return;
+
+          const title = lines[0];
+          const dateLine = lines.find(l => l.includes('发布于'));
+          const dateMatch = dateLine?.match(/发布于\\s+(\\d{4}年\\d{2}月\\d{2}日\\s+\\d{2}:\\d{2})/);
+
+          // Remove the publish timestamp before collecting note metrics.
+          // Otherwise year/month/day/hour digits are picked up as views/likes/etc.
+          const metricText = dateLine ? text.replace(dateLine, ' ') : text;
+          const nums = metricText.match(/(?:^|\\s)(\\d+)(?:\\s|$)/g)?.map(n => parseInt(n.trim())) || [];
+
+          if (title && !title.includes('全部笔记')) {
+            results.push({
+              id: idMatch ? idMatch[1] : '',
+              title: title.replace(/\\s+/g, ' ').substring(0, 80),
+              date: dateMatch ? dateMatch[1] : '',
+              views: nums[0] || 0,
+              likes: nums[1] || 0,
+              collects: nums[2] || 0,
+              comments: nums[3] || 0,
+              url: href ? new URL(href, window.location.origin).toString() : '',
+            });
+          }
+        });
+
+        return results;
+      })()
+    `);
+
+    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: any, i: number) => ({
+        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/clis/xiaohongshu/creator-profile.ts

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ *
+ * Requires: logged into creator.xiaohongshu.com in Chrome.
+ */
+
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'creator-profile',
+  description: '小红书创作者账号信息 (粉丝/关注/获赞/成长等级)',
+  domain: 'creator.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [],
+  columns: ['field', 'value'],
+  func: async (page, _kwargs) => {
+    await page.goto('https://creator.xiaohongshu.com/new/home');
+    await page.wait(3);
+
+    const data = await page.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 };
+        }
+      }
+    `);
+
+    if (data?.error) {
+      throw new Error(data.error + '. Are you logged into creator.xiaohongshu.com?');
+    }
+    if (!data?.data) {
+      throw new Error('Unexpected response structure');
+    }
+
+    const d = data.data;
+    const grow = d.grow_info || {};
+
+    return [
+      { field: 'Name', value: d.name ?? '' },
+      { field: 'Followers', value: d.fans_count ?? 0 },
+      { field: 'Following', value: d.follow_count ?? 0 },
+      { field: 'Likes & Collects', value: d.faved_count ?? 0 },
+      { field: 'Creator Level', value: grow.level ?? 0 },
+      { field: 'Level Progress', value: `${grow.fans_count ?? 0}/${grow.max_fans_count ?? 0} fans` },
+      { field: 'Bio', value: (d.personal_desc ?? '').replace(/\\n/g, ' | ') },
+    ];
+  },
+});

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

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ *
+ * Requires: logged into creator.xiaohongshu.com in Chrome.
+ */
+
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'creator-stats',
+  description: '小红书创作者数据总览 (观看/点赞/收藏/评论/分享/涨粉，含每日趋势)',
+  domain: 'creator.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  browser: true,
+  args: [
+    {
+      name: 'period',
+      type: 'string',
+      default: 'seven',
+      help: 'Stats period: seven or thirty',
+      choices: ['seven', 'thirty'],
+    },
+  ],
+  columns: ['metric', 'total', 'trend'],
+  func: async (page, kwargs) => {
+    const period: string = kwargs.period || 'seven';
+
+    // Navigate to creator center for cookie context
+    await page.goto('https://creator.xiaohongshu.com/new/home');
+    await page.wait(3);
+
+    const data = await page.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 };
+        }
+      }
+    `);
+
+    if (data?.error) {
+      throw new Error(data.error + '. Are you logged into creator.xiaohongshu.com?');
+    }
+    if (!data?.data) {
+      throw new Error('Unexpected response structure');
+    }
+
+    const stats = data.data[period];
+    if (!stats) {
+      throw new Error(`No data for period "${period}". Available: ${Object.keys(data.data).join(', ')}`);
+    }
+
+    // Format daily trend as sparkline-like summary
+    const formatTrend = (list: any[]): string => {
+      if (!list || !list.length) return '-';
+      return list.map((d: any) => 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/clis/xiaohongshu/download.ts

@@ -0,0 +1,173 @@
+/**
+ * Xiaohongshu download — download images and videos from a note.
+ *
+ * Usage:
+ *   opencli xiaohongshu download --note-id abc123 --output ./xhs
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { cli, Strategy } from '../../registry.js';
+import {
+  httpDownload,
+  sanitizeFilename,
+  detectContentType,
+} from '../../download/index.js';
+import { DownloadProgressTracker, formatBytes } from '../../download/progress.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'download',
+  description: '下载小红书笔记中的图片和视频',
+  domain: 'www.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'note_id', required: true, help: 'Note ID (from URL)' },
+    { name: 'output', default: './xiaohongshu-downloads', help: 'Output directory' },
+  ],
+  columns: ['index', 'type', 'status', 'size'],
+  func: async (page, kwargs) => {
+    const noteId = kwargs.note_id;
+    const output = kwargs.output;
+
+    // Navigate to note page
+    await page.goto(`https://www.xiaohongshu.com/explore/${noteId}`);
+    await page.wait(3);
+
+    // Extract note info and media URLs
+    const data = await page.evaluate(`
+      (() => {
+        const result = {
+          noteId: '${noteId}',
+          title: '',
+          author: '',
+          media: []
+        };
+
+        // 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 - try multiple selectors
+        const imageSelectors = [
+          '.swiper-slide img',
+          '.carousel-image img',
+          '.note-slider img',
+          '.note-image img',
+          '.image-wrapper img',
+          '#noteContainer 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'))) {
+              // Convert to high quality URL (remove resize parameters)
+              src = src.split('?')[0];
+              // Try to get original size
+              src = src.replace(/\\/imageView\\d+\\/\\d+\\/w\\/\\d+/, '');
+              imageUrls.add(src);
+            }
+          });
+        }
+
+        // Get video if exists
+        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) {
+              result.media.push({
+                type: 'video',
+                url: src
+              });
+            }
+          });
+        }
+
+        // Add images to media
+        imageUrls.forEach(url => {
+          result.media.push({
+            type: 'image',
+            url: url
+          });
+        });
+
+        return result;
+      })()
+    `);
+
+    if (!data || !data.media || data.media.length === 0) {
+      return [{ index: 0, type: '-', status: 'failed', size: 'No media found' }];
+    }
+
+    // Extract cookies for authenticated downloads
+    const cookies = await page.evaluate(`(() => document.cookie)()`);
+
+    // Create output directory
+    const outputDir = path.join(output, noteId);
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    // Download all media files
+    const tracker = new DownloadProgressTracker(data.media.length, true);
+    const results: any[] = [];
+
+    for (let i = 0; i < data.media.length; i++) {
+      const media = data.media[i];
+      const ext = media.type === 'video' ? 'mp4' : 'jpg';
+      const filename = `${noteId}_${i + 1}.${ext}`;
+      const destPath = path.join(outputDir, filename);
+
+      const progressBar = tracker.onFileStart(filename, i);
+
+      try {
+        const result = await httpDownload(media.url, destPath, {
+          cookies: typeof cookies === 'string' ? cookies : '',
+          timeout: 60000,
+          onProgress: (received, total) => {
+            if (progressBar) progressBar.update(received, total);
+          },
+        });
+
+        if (progressBar) {
+          progressBar.complete(result.success, result.success ? formatBytes(result.size) : undefined);
+        }
+
+        tracker.onFileComplete(result.success);
+
+        results.push({
+          index: i + 1,
+          type: media.type,
+          status: result.success ? 'success' : 'failed',
+          size: result.success ? formatBytes(result.size) : (result.error || 'unknown error'),
+        });
+      } catch (err: any) {
+        if (progressBar) progressBar.fail(err.message);
+        tracker.onFileComplete(false);
+
+        results.push({
+          index: i + 1,
+          type: media.type,
+          status: 'failed',
+          size: err.message,
+        });
+      }
+    }
+
+    tracker.finish();
+
+    return results;
+  },
+});

package/src/clis/xiaohongshu/search.ts

@@ -43,7 +43,7 @@ cli({
           const linkEl = el.querySelector('a[href*="/explore/"], a[href*="/search_result/"], a[href*="/note/"]');
 
           const href = linkEl?.getAttribute('href') || '';
-          const noteId = href.match(/\\/(?:explore|note)\\/([a-f0-9]+)/)?.[1] || '';
+          const noteId = href.match(/\\/(?:explore|note)\\/([a-zA-Z0-9]+)/)?.[1] || '';
 
           results.push({
             title: (titleEl?.textContent || '').trim(),

package/src/clis/xiaohongshu/user-helpers.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildXhsNoteUrl,
+  extractXhsUserNotes,
+  flattenXhsNoteGroups,
+  normalizeXhsUserId,
+} from './user-helpers.js';
+
+describe('normalizeXhsUserId', () => {
+  it('extracts the profile id from a full Xiaohongshu URL', () => {
+    expect(
+      normalizeXhsUserId(
+        'https://www.xiaohongshu.com/user/profile/615529370000000002026001?xsec_source=pc_search'
+      )
+    ).toBe('615529370000000002026001');
+  });
+
+  it('keeps a bare profile id unchanged', () => {
+    expect(normalizeXhsUserId('615529370000000002026001')).toBe('615529370000000002026001');
+  });
+});
+
+describe('flattenXhsNoteGroups', () => {
+  it('flattens grouped note arrays and ignores empty groups', () => {
+    expect(flattenXhsNoteGroups([[{ id: 'a' }], [], null, [{ id: 'b' }]])).toEqual([
+      { id: 'a' },
+      { id: 'b' },
+    ]);
+  });
+});
+
+describe('buildXhsNoteUrl', () => {
+  it('includes xsec token when available', () => {
+    expect(buildXhsNoteUrl('user123', 'note456', 'token789')).toBe(
+      'https://www.xiaohongshu.com/user/profile/user123/note456?xsec_token=token789&xsec_source=pc_user'
+    );
+  });
+});
+
+describe('extractXhsUserNotes', () => {
+  it('normalizes grouped note cards into CLI rows', () => {
+    const rows = extractXhsUserNotes(
+      {
+        noteGroups: [
+          [
+            {
+              id: 'note-1',
+              xsecToken: 'abc',
+              noteCard: {
+                noteId: 'note-1',
+                displayTitle: 'First note',
+                type: 'video',
+                interactInfo: { likedCount: '4.6万' },
+                user: { userId: 'user-1' },
+              },
+            },
+            {
+              noteCard: {
+                note_id: 'note-2',
+                display_title: 'Second note',
+                type: 'normal',
+                interact_info: { liked_count: 42 },
+              },
+            },
+          ],
+          [],
+        ],
+      },
+      'fallback-user'
+    );
+
+    expect(rows).toEqual([
+      {
+        id: 'note-1',
+        title: 'First note',
+        type: 'video',
+        likes: '4.6万',
+        url: 'https://www.xiaohongshu.com/user/profile/user-1/note-1?xsec_token=abc&xsec_source=pc_user',
+      },
+      {
+        id: 'note-2',
+        title: 'Second note',
+        type: 'normal',
+        likes: '42',
+        url: 'https://www.xiaohongshu.com/user/profile/fallback-user/note-2',
+      },
+    ]);
+  });
+
+  it('deduplicates repeated notes by note id', () => {
+    const rows = extractXhsUserNotes(
+      {
+        noteGroups: [
+          [
+            { noteCard: { noteId: 'dup-1', displayTitle: 'keep me' } },
+            { noteCard: { noteId: 'dup-1', displayTitle: 'drop me' } },
+          ],
+        ],
+      },
+      'fallback-user'
+    );
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe('keep me');
+  });
+});