@jackwener/opencli 1.7.22 → 1.8.0

package/clis/weibo/user-posts.js

@@ -0,0 +1,234 @@
+/**
+ * Weibo user-posts — list posts from a user within an optional date range.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { unwrapEvaluateResult } from './utils.js';
+
+const MAX_LIMIT = 100;
+const DEFAULT_LIMIT = 20;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+function readRequiredId(raw) {
+    const value = String(raw ?? '').trim();
+    if (!value) {
+        throw new ArgumentError('weibo user-posts id cannot be empty');
+    }
+    return value;
+}
+
+function readLimit(raw) {
+    const value = raw === undefined || raw === null || raw === '' ? DEFAULT_LIMIT : Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > MAX_LIMIT) {
+        throw new ArgumentError(`weibo user-posts limit must be an integer between 1 and ${MAX_LIMIT}`);
+    }
+    return value;
+}
+
+function readDate(raw, name) {
+    if (raw === undefined || raw === null || raw === '') return null;
+    const value = String(raw).trim();
+    if (!DATE_RE.test(value)) {
+        throw new ArgumentError(`weibo user-posts ${name} must use YYYY-MM-DD`);
+    }
+    const date = new Date(`${value}T00:00:00+08:00`);
+    if (!Number.isFinite(date.getTime()) || value !== formatShanghaiDate(date)) {
+        throw new ArgumentError(`weibo user-posts ${name} must be a valid calendar date`);
+    }
+    return value;
+}
+
+function formatShanghaiDate(date) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: 'Asia/Shanghai',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(date);
+    const get = (type) => parts.find((part) => part.type === type)?.value;
+    return `${get('year')}-${get('month')}-${get('day')}`;
+}
+
+function dateToTimestamp(date) {
+    return Math.floor(new Date(`${date}T00:00:00+08:00`).getTime() / 1000);
+}
+
+function validateRange(start, end) {
+    if (start && end && dateToTimestamp(start) > dateToTimestamp(end)) {
+        throw new ArgumentError('weibo user-posts start must be <= end');
+    }
+}
+
+function mapError(error) {
+    const message = String(error ?? '').trim();
+    if (!message) {
+        throw new CommandExecutionError('weibo user-posts failed without an error message');
+    }
+    if (/login|cookie|登录|auth|forbidden|permission|权限|unauthorized/i.test(message)) {
+        throw new AuthRequiredError('weibo.com', message);
+    }
+    throw new CommandExecutionError(message);
+}
+
+export const testInternals = {
+    readRequiredId,
+    readLimit,
+    readDate,
+    dateToTimestamp,
+};
+
+cli({
+    site: 'weibo',
+    name: 'user-posts',
+    access: 'read',
+    description: 'List Weibo posts from a user, optionally filtered by date range',
+    domain: 'weibo.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'id', positional: true, required: true, help: 'User ID (numeric uid) or screen name' },
+        { name: 'start', help: 'Start date in Asia/Shanghai (YYYY-MM-DD)' },
+        { name: 'end', help: 'End date in Asia/Shanghai (YYYY-MM-DD)' },
+        { name: 'limit', type: 'int', default: DEFAULT_LIMIT, help: `Number of posts (1-${MAX_LIMIT})` },
+        { name: 'include-retweets', type: 'boolean', default: false, help: 'Include retweets' },
+    ],
+    columns: ['rank', 'id', 'mblogid', 'author', 'uid', 'text', 'time', 'reposts', 'comments', 'likes', 'pic_count', 'url'],
+    func: async (page, kwargs) => {
+        const id = readRequiredId(kwargs.id);
+        const limit = readLimit(kwargs.limit);
+        const start = readDate(kwargs.start, 'start');
+        const end = readDate(kwargs.end, 'end');
+        validateRange(start, end);
+        const includeRetweets = Boolean(kwargs['include-retweets']);
+        const starttime = start ? dateToTimestamp(start) : null;
+        const endtime = end ? dateToTimestamp(end) + 24 * 60 * 60 - 1 : null;
+
+        await page.goto('https://weibo.com');
+        await page.wait(2);
+
+        const evaluateResult = await page.evaluate(`
+      (async () => {
+        const rawId = ${JSON.stringify(id)};
+        const limit = ${limit};
+        const includeRetweets = ${includeRetweets};
+        const starttime = ${starttime === null ? 'null' : starttime};
+        const endtime = ${endtime === null ? 'null' : endtime};
+        const strip = (html) => (html || '')
+          .replace(/<[^>]+>/g, '')
+          .replace(/&nbsp;/g, ' ')
+          .replace(/&lt;/g, '<')
+          .replace(/&gt;/g, '>')
+          .replace(/&amp;/g, '&')
+          .replace(/\\s+/g, ' ')
+          .trim();
+
+        async function readJson(url) {
+          const resp = await fetch(url, { credentials: 'include' });
+          if (resp.status === 401 || resp.status === 403) {
+            return { error: 'login required: HTTP ' + resp.status };
+          }
+          if (!resp.ok) {
+            return { error: 'HTTP ' + resp.status };
+          }
+          try {
+            return await resp.json();
+          } catch {
+            return { error: 'Malformed JSON response' };
+          }
+        }
+
+        let uid = rawId;
+        if (!/^\\d+$/.test(rawId)) {
+          const profile = await readJson('/ajax/profile/info?screen_name=' + encodeURIComponent(rawId));
+          if (profile.error) return profile;
+          if (!profile.ok || !profile.data?.user?.id) return [rawId, [], true, false];
+          uid = String(profile.data.user.id);
+        }
+
+        const rows = [];
+        let sawList = false;
+        let sawPostCandidates = false;
+        for (let page = 1; page <= 20 && rows.length < limit; page++) {
+          const qs = new URLSearchParams();
+          qs.set('uid', uid);
+          qs.set('page', String(page));
+          qs.set('hasori', '1');
+          qs.set('hasret', includeRetweets ? '1' : '0');
+          if (starttime !== null) qs.set('starttime', String(starttime));
+          if (endtime !== null) qs.set('endtime', String(endtime));
+
+          const data = await readJson('/ajax/statuses/searchProfile?' + qs.toString());
+          if (data.error) return data;
+          if (data.ok === false) {
+            return { error: 'Weibo user posts API error: ' + (data.msg || data.message || 'request failed') };
+          }
+          const list = data.data?.list;
+          if (!Array.isArray(list)) {
+            return { error: 'Weibo user posts response did not include data.list' };
+          }
+          sawList = true;
+          if (list.length > 0) sawPostCandidates = true;
+          if (list.length === 0) break;
+
+          for (const post of list) {
+            if (rows.length >= limit) break;
+            const postId = post.idstr || (post.id === undefined || post.id === null ? '' : String(post.id));
+            const mblogid = post.mblogid || '';
+            const user = post.user || {};
+            const text = post.text_raw || strip(post.text || '');
+            if (!postId || !mblogid || !text) continue;
+            rows.push({
+              id: postId,
+              mblogid,
+              author: user.screen_name || '',
+              uid: user.id === undefined || user.id === null ? uid : String(user.id),
+              text,
+              time: post.created_at || '',
+              reposts: post.reposts_count ?? 0,
+              comments: post.comments_count ?? 0,
+              likes: post.attitudes_count ?? 0,
+              pic_count: post.pic_num ?? Object.keys(post.pic_infos || {}).length,
+              url: 'https://weibo.com/' + (user.id || uid) + '/' + mblogid,
+            });
+          }
+
+          if (list.length < 10) break;
+        }
+
+        return [uid, rows, sawList, sawPostCandidates];
+      })()
+    `);
+
+        const payload = unwrapEvaluateResult(evaluateResult);
+        if (payload && !Array.isArray(payload) && typeof payload === 'object' && 'error' in payload) {
+            mapError(payload.error);
+        }
+        if (!Array.isArray(payload) || payload.length !== 4 || !Array.isArray(payload[1])) {
+            throw new CommandExecutionError('weibo user-posts returned malformed extraction payload');
+        }
+        const [resolvedUid, rows, sawList, sawPostCandidates] = payload;
+        if (!sawList && rows.length === 0) {
+            throw new CommandExecutionError('weibo user-posts did not observe a valid posts list');
+        }
+        if (sawPostCandidates && rows.length === 0) {
+            throw new CommandExecutionError('weibo user-posts found post candidates but could not extract valid rows');
+        }
+        if (rows.length === 0) {
+            throw new EmptyResultError('weibo user-posts', 'No Weibo posts found for this user/date range');
+        }
+
+        return rows.slice(0, limit).map((row, index) => ({
+            rank: index + 1,
+            id: String(row.id),
+            mblogid: row.mblogid || '',
+            author: row.author || '',
+            uid: String(row.uid || resolvedUid || ''),
+            text: row.text || '',
+            time: row.time || '',
+            reposts: row.reposts ?? 0,
+            comments: row.comments ?? 0,
+            likes: row.likes ?? 0,
+            pic_count: row.pic_count ?? 0,
+            url: row.url || '',
+        }));
+    },
+});

package/clis/weibo/user-posts.test.js

@@ -0,0 +1,92 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './user-posts.js';
+import { testInternals } from './user-posts.js';
+
+function envelope(data) {
+    return { session: 'site:weibo:test', data };
+}
+
+function makePage(payload) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(payload),
+    };
+}
+
+describe('weibo user-posts', () => {
+    const command = getRegistry().get('weibo/user-posts');
+
+    it('validates id, limit, dates, and date ranges before navigation', async () => {
+        await expect(command.func(makePage({ rows: [] }), { id: '', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(makePage({ rows: [] }), { id: '123', limit: 0 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(makePage({ rows: [] }), { id: '123', start: '2025-02-30', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(makePage({ rows: [] }), { id: '123', start: '2025-06-02', end: '2025-06-01', limit: 10 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('converts Asia/Shanghai date boundaries to unix seconds', () => {
+        expect(testInternals.dateToTimestamp('2025-06-01')).toBe(1748707200);
+        expect(testInternals.dateToTimestamp('2025-01-01')).toBe(1735660800);
+    });
+
+    it('unwraps browser bridge envelopes and returns stable listing rows', async () => {
+        const page = makePage(envelope(['1670458304', [{
+                id: '5012345678901234',
+                mblogid: 'QD5uq0ydj',
+                author: 'Alice',
+                uid: '1670458304',
+                text: 'hello',
+                time: 'Sun Jun 01 10:00:00 +0800 2025',
+                reposts: 1,
+                comments: 2,
+                likes: 3,
+                pic_count: 4,
+                url: 'https://weibo.com/1670458304/QD5uq0ydj',
+            }], true, true]));
+
+        await expect(command.func(page, {
+            id: '1670458304',
+            start: '2025-06-01',
+            end: '2025-06-02',
+            limit: 20,
+        })).resolves.toEqual([{
+            rank: 1,
+            id: '5012345678901234',
+            mblogid: 'QD5uq0ydj',
+            author: 'Alice',
+            uid: '1670458304',
+            text: 'hello',
+            time: 'Sun Jun 01 10:00:00 +0800 2025',
+            reposts: 1,
+            comments: 2,
+            likes: 3,
+            pic_count: 4,
+            url: 'https://weibo.com/1670458304/QD5uq0ydj',
+        }]);
+    });
+
+    it('maps auth-like evaluate errors to AuthRequiredError', async () => {
+        await expect(command.func(makePage({ error: 'login required: HTTP 403' }), { id: '123', limit: 10 }))
+            .rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('maps malformed payload and parser drift to CommandExecutionError', async () => {
+        await expect(command.func(makePage({ rows: [] }), { id: '123', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ error: 'Weibo user posts response did not include data.list' }), { id: '123', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage(['123', [], true, true]), { id: '123', limit: 10 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps true empty lists to EmptyResultError', async () => {
+        await expect(command.func(makePage(['123', [], true, false]), { id: '123', limit: 10 }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+    });
+});

package/clis/weread/search-regression.test.js

@@ -1,5 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import './search.js';
 describe('weread/search regression', () => {
     beforeEach(() => {
@@ -146,7 +147,7 @@ describe('weread/search regression', () => {
             },
         ]);
     });
-    it('falls back to empty urls when the search html request fails', async () => {
+    it('surfaces search html request failures instead of emitting empty urls', async () => {
         const command = getRegistry().get('weread/search');
         expect(command?.func).toBeTypeOf('function');
         const fetchMock = vi.fn()
@@ -166,16 +167,22 @@ describe('weread/search regression', () => {
         })
             .mockRejectedValueOnce(new Error('network timeout'));
         vi.stubGlobal('fetch', fetchMock);
-        const result = await command.func({ query: 'deep work', limit: 5 });
-        expect(result).toEqual([
-            {
-                rank: 1,
-                title: 'Deep Work',
-                author: 'Cal Newport',
-                bookId: 'abc123',
-                url: '',
-            },
-        ]);
+        await expect(command.func({ query: 'deep work', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+    it('throws EmptyResultError when the public search API returns no books', async () => {
+        const command = getRegistry().get('weread/search');
+        expect(command?.func).toBeTypeOf('function');
+        const fetchMock = vi.fn()
+            .mockResolvedValueOnce({
+            ok: true,
+            json: () => Promise.resolve({ books: [] }),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            text: () => Promise.resolve('<html></html>'),
+        });
+        vi.stubGlobal('fetch', fetchMock);
+        await expect(command.func({ query: 'definitely-missing-book', limit: 5 })).rejects.toBeInstanceOf(EmptyResultError);
     });
     it('binds reader urls with title and author instead of title alone', async () => {
         const command = getRegistry().get('weread/search');

package/clis/weread/search.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { fetchWebApi, WEREAD_UA, WEREAD_WEB_ORIGIN } from './utils.js';
 function decodeHtmlText(value) {
     return value
@@ -84,18 +85,19 @@ function resolveSearchResultUrl(params) {
 async function loadSearchHtmlEntries(query) {
     const url = new URL('/web/search/books', WEREAD_WEB_ORIGIN);
     url.searchParams.set('keyword', query);
-    let html = '';
+    let resp;
     try {
-        const resp = await fetch(url.toString(), {
+        resp = await fetch(url.toString(), {
             headers: { 'User-Agent': WEREAD_UA },
         });
-        if (!resp.ok)
-            return [];
-        html = await resp.text();
     }
-    catch {
-        return [];
+    catch (error) {
+        throw new CommandExecutionError(`Failed to fetch WeRead search page: ${error instanceof Error ? error.message : String(error)}`);
     }
+    if (!resp.ok) {
+        throw new CommandExecutionError(`WeRead search page request failed: HTTP ${resp.status}`);
+    }
+    const html = await resp.text();
     const items = Array.from(html.matchAll(/<li[^>]*class="wr_bookList_item"[^>]*>([\s\S]*?)<\/li>/g));
     return items.map((match) => {
         const chunk = match[1];
@@ -131,6 +133,12 @@ cli({
             loadSearchHtmlEntries(String(args.query ?? '')),
         ]);
         const books = data?.books ?? [];
+        if (!Array.isArray(books)) {
+            throw new CommandExecutionError('WeRead search API returned an unreadable books payload');
+        }
+        if (books.length === 0) {
+            throw new EmptyResultError('weread search', `No books were returned for query ${args.query}.`);
+        }
         const { exactQueues, titleOnlyQueues } = buildSearchUrlQueues(htmlEntries);
         const apiIdentityCounts = countSearchIdentities(books.map((item) => ({
             title: item.bookInfo?.title ?? '',

package/clis/weread-official/book.js

@@ -0,0 +1,135 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    callGateway,
+    emptyResult,
+    formatDate,
+    formatDuration,
+    formatRating,
+    makeDeepLink,
+    requireBookId,
+    truncate,
+} from './utils.js';
+
+/**
+ * 3-in-1 book lookup: `/book/info` always runs; `/book/chapterinfo` and
+ * `/book/getprogress` are opt-out via `--no-chapters` / `--no-progress`
+ * so users can shave 1-2 gateway calls when only a single section is needed.
+ *
+ * Output is a flat row list with a `section` column so table/json/yaml
+ * consumers can filter without ad-hoc joins:
+ *   - section=info       — single row, basic metadata
+ *   - section=chapter    — one row per chapter (level/title/wordCount)
+ *   - section=progress   — single row, progress % + cumulative read time
+ */
+cli({
+    site: 'weread-official',
+    name: 'book',
+    access: 'read',
+    description: 'Show WeRead book metadata, chapters, and reading progress',
+    domain: 'weread.qq.com',
+    strategy: Strategy.PUBLIC,
+    browser: false,
+    args: [
+        { name: 'bookId', positional: true, required: true, help: 'WeRead bookId (from `weread-official search`)' },
+        { name: 'no-chapters', type: 'boolean', default: false, help: 'Skip /book/chapterinfo call' },
+        { name: 'no-progress', type: 'boolean', default: false, help: 'Skip /book/getprogress call' },
+    ],
+    columns: ['section', 'idx', 'key', 'value', 'link'],
+    func: async (args) => {
+        const bookId = requireBookId(args.bookId);
+
+        const tasks = [callGateway('/book/info', { bookId })];
+        const want = {
+            chapters: !args['no-chapters'],
+            progress: !args['no-progress'],
+        };
+        if (want.chapters) tasks.push(callGateway('/book/chapterinfo', { bookId }));
+        if (want.progress) tasks.push(callGateway('/book/getprogress', { bookId }));
+
+        const results = await Promise.all(tasks);
+        let cursor = 0;
+        const info = results[cursor++];
+        const chapters = want.chapters ? results[cursor++] : null;
+        const progress = want.progress ? results[cursor++] : null;
+
+        const rows = [];
+
+        // ── info section ────────────────────────────────────────────────────
+        const infoPairs = [
+            ['bookId', String(info?.bookId ?? bookId)],
+            ['title', String(info?.title ?? '')],
+            ['author', String(info?.author ?? '')],
+            ['translator', String(info?.translator ?? '')],
+            ['category', String(info?.category ?? '')],
+            ['publisher', String(info?.publisher ?? '')],
+            ['publishTime', String(info?.publishTime ?? '')],
+            ['isbn', String(info?.isbn ?? '')],
+            ['wordCount', String(info?.wordCount ?? '')],
+            ['rating', formatRating(info?.newRating)],
+            ['ratingCount', String(info?.newRatingCount ?? '')],
+            ['intro', truncate(info?.intro, 400)],
+            ['cover', String(info?.cover ?? '')],
+        ];
+        for (let i = 0; i < infoPairs.length; i += 1) {
+            const [key, value] = infoPairs[i];
+            rows.push({ section: 'info', idx: i + 1, key, value, link: '' });
+        }
+        rows.push({
+            section: 'info',
+            idx: infoPairs.length + 1,
+            key: 'link',
+            value: '',
+            link: makeDeepLink({ bookId }),
+        });
+
+        // ── chapters section ────────────────────────────────────────────────
+        if (chapters) {
+            const list = Array.isArray(chapters?.chapters) ? chapters.chapters : [];
+            list.forEach((ch, i) => {
+                const chapterUid = String(ch?.chapterUid ?? '').trim();
+                const level = Number(ch?.level ?? 1);
+                const indent = '  '.repeat(Math.max(0, level - 1));
+                const title = `${indent}${String(ch?.title ?? '')}`;
+                const wordCount = Number(ch?.wordCount ?? 0);
+                const paid = Number(ch?.paid ?? 0) === 1;
+                const price = Number(ch?.price ?? 0);
+                const meta = [`${wordCount}字`];
+                if (price > 0) meta.push(paid ? '已购买' : `${price}元`);
+                rows.push({
+                    section: 'chapter',
+                    idx: Number(ch?.chapterIdx ?? i + 1),
+                    key: chapterUid,
+                    value: `${title}  (${meta.join(' · ')})`,
+                    link: chapterUid ? makeDeepLink({ bookId, chapterUid }) : '',
+                });
+            });
+        }
+
+        // ── progress section ────────────────────────────────────────────────
+        if (progress) {
+            const p = progress?.book ?? {};
+            const pct = Number(p?.progress ?? 0);
+            const updateTime = formatDate(p?.updateTime);
+            const finishTime = pct === 100 ? formatDate(p?.finishTime) : '';
+            const cumulative = formatDuration(p?.recordReadingTime);
+            const isStart = Number(p?.isStartReading ?? 0) === 1;
+            const progressPairs = [
+                ['progress', `${pct}%`],
+                ['cumulative', cumulative],
+                ['lastReadAt', updateTime],
+                ['finishedAt', finishTime],
+                ['isStartReading', isStart ? 'true' : 'false'],
+                ['currentChapterUid', String(p?.chapterUid ?? '')],
+            ];
+            for (let i = 0; i < progressPairs.length; i += 1) {
+                const [key, value] = progressPairs[i];
+                rows.push({ section: 'progress', idx: i + 1, key, value, link: '' });
+            }
+        }
+
+        if (rows.length === 0) {
+            emptyResult('book', `No data returned for bookId=${bookId}`);
+        }
+        return rows;
+    },
+});