@jackwener/opencli 1.7.22 → 1.8.0

package/clis/barchart/greeks.js

@@ -4,6 +4,47 @@
  * Auth: CSRF token from <meta name="csrf-token"> + session cookies.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+
+const DEFAULT_LIMIT = 10;
+const MIN_LIMIT = 1;
+const MAX_LIMIT = 100;
+
+function normalizeSymbol(value) {
+    const symbol = String(value ?? '').trim().toUpperCase();
+    if (!symbol) throw new ArgumentError('symbol is required');
+    return symbol;
+}
+
+function normalizeExpiration(value) {
+    const expiration = String(value ?? '').trim();
+    if (!expiration) return '';
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(expiration)) {
+        throw new ArgumentError('--expiration must use YYYY-MM-DD format');
+    }
+    const parsed = new Date(`${expiration}T00:00:00Z`);
+    if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== expiration) {
+        throw new ArgumentError('--expiration must be a valid calendar date');
+    }
+    return expiration;
+}
+
+function parseLimit(value) {
+    if (value === undefined || value === null || value === '') return DEFAULT_LIMIT;
+    const limit = Number(value);
+    if (!Number.isInteger(limit) || limit < MIN_LIMIT || limit > MAX_LIMIT) {
+        throw new ArgumentError(`--limit must be an integer between ${MIN_LIMIT} and ${MAX_LIMIT}`);
+    }
+    return limit;
+}
+
+function unwrapBrowserResult(value) {
+    if (value && typeof value === 'object' && 'session' in value && 'data' in value) {
+        return value.data;
+    }
+    return value;
+}
+
 cli({
     site: 'barchart',
     name: 'greeks',
@@ -14,19 +55,19 @@ cli({
     args: [
         { name: 'symbol', required: true, positional: true, help: 'Stock ticker (e.g. AAPL)' },
         { name: 'expiration', type: 'str', help: 'Expiration date (YYYY-MM-DD). Defaults to the nearest available expiration.' },
-        { name: 'limit', type: 'int', default: 10, help: 'Number of near-the-money strikes per type' },
+        { name: 'limit', type: 'int', default: DEFAULT_LIMIT, help: 'Number of near-the-money strikes per type (1-100)' },
     ],
     columns: [
         'type', 'strike', 'last', 'iv', 'delta', 'gamma', 'theta', 'vega', 'rho',
         'volume', 'openInterest', 'expiration',
     ],
     func: async (page, kwargs) => {
-        const symbol = kwargs.symbol.toUpperCase().trim();
-        const expiration = kwargs.expiration ?? '';
-        const limit = kwargs.limit ?? 10;
+        const symbol = normalizeSymbol(kwargs.symbol);
+        const expiration = normalizeExpiration(kwargs.expiration);
+        const limit = parseLimit(kwargs.limit);
         await page.goto(`https://www.barchart.com/stocks/quotes/${encodeURIComponent(symbol)}/options`);
         await page.wait(4);
-        const data = await page.evaluate(`
+        const data = unwrapBrowserResult(await page.evaluate(`
       (async () => {
         const sym = ${JSON.stringify(symbol)};
         const expDate = ${JSON.stringify(expiration)};
@@ -45,39 +86,53 @@ cli({
             + '&fields=' + fields + '&raw=1';
           if (expDate) url += '&expirationDate=' + encodeURIComponent(expDate);
           const resp = await fetch(url, { credentials: 'include', headers });
-          if (resp.ok) {
-            const d = await resp.json();
-            let items = d?.data || [];
+          if (!resp.ok) {
+            return { ok: false, reason: 'http', status: resp.status, statusText: resp.statusText || '' };
+          }
+
+          const d = await resp.json();
+          const allItems = d?.data;
+          if (!Array.isArray(allItems)) {
+            return { ok: false, reason: 'malformed' };
+          }
+          let items = allItems;
 
-            if (!expDate) {
-              const expirations = items
-                .map(i => (i.raw || i).expirationDate || null)
-                .filter(Boolean)
-                .sort((a, b) => {
-                  const aTime = Date.parse(a);
-                  const bTime = Date.parse(b);
-                  if (Number.isNaN(aTime) && Number.isNaN(bTime)) return 0;
-                  if (Number.isNaN(aTime)) return 1;
-                  if (Number.isNaN(bTime)) return -1;
-                  return aTime - bTime;
-                });
-              const nearestExpiration = expirations[0];
-              if (nearestExpiration) {
-                items = items.filter(i => ((i.raw || i).expirationDate || null) === nearestExpiration);
-              }
+          if (!expDate) {
+            const expirations = items
+              .map(i => (i.raw || i).expirationDate || null)
+              .filter(Boolean)
+              .sort((a, b) => {
+                const aTime = Date.parse(a);
+                const bTime = Date.parse(b);
+                if (Number.isNaN(aTime) && Number.isNaN(bTime)) return 0;
+                if (Number.isNaN(aTime)) return 1;
+                if (Number.isNaN(bTime)) return -1;
+                return aTime - bTime;
+              });
+            const nearestExpiration = expirations[0];
+            if (nearestExpiration) {
+              items = items.filter(i => ((i.raw || i).expirationDate || null) === nearestExpiration);
             }
+          }
+
+          // Separate calls and puts, sort by distance from current price.
+          const calls = items
+            .filter(i => ((i.raw || i).optionType || '').toLowerCase() === 'call')
+            .sort((a, b) => Math.abs((a.raw || a).percentFromLast || 999) - Math.abs((b.raw || b).percentFromLast || 999))
+            .slice(0, limit);
+          const puts = items
+            .filter(i => ((i.raw || i).optionType || '').toLowerCase() === 'put')
+            .sort((a, b) => Math.abs((a.raw || a).percentFromLast || 999) - Math.abs((b.raw || b).percentFromLast || 999))
+            .slice(0, limit);
+          const selected = [...calls, ...puts];
 
-            // Separate calls and puts, sort by distance from current price
-            const calls = items
-              .filter(i => ((i.raw || i).optionType || '').toLowerCase() === 'call')
-              .sort((a, b) => Math.abs((a.raw || a).percentFromLast || 999) - Math.abs((b.raw || b).percentFromLast || 999))
-              .slice(0, limit);
-            const puts = items
-              .filter(i => ((i.raw || i).optionType || '').toLowerCase() === 'put')
-              .sort((a, b) => Math.abs((a.raw || a).percentFromLast || 999) - Math.abs((b.raw || b).percentFromLast || 999))
-              .slice(0, limit);
+          if (items.length > 0 && selected.length === 0) {
+            return { ok: false, reason: 'malformed', message: 'options rows did not include call or put identities' };
+          }
 
-            return [...calls, ...puts].map(i => {
+          return {
+            ok: true,
+            rows: selected.map(i => {
               const r = i.raw || i;
               return {
                 type: r.optionType,
@@ -93,28 +148,61 @@ cli({
                 openInterest: r.openInterest,
                 expiration: r.expirationDate,
               };
-            });
-          }
-        } catch(e) {}
-
-        return [];
+            })
+          };
+        } catch(e) {
+          return { ok: false, reason: 'exception', message: e?.message || String(e) };
+        }
       })()
-    `);
-        if (!data || !Array.isArray(data))
-            return [];
-        return data.map(r => ({
-            type: r.type || '',
-            strike: r.strike,
-            last: r.last != null ? Number(Number(r.last).toFixed(2)) : null,
-            iv: r.iv != null ? Number(Number(r.iv).toFixed(2)) + '%' : null,
-            delta: r.delta != null ? Number(Number(r.delta).toFixed(4)) : null,
-            gamma: r.gamma != null ? Number(Number(r.gamma).toFixed(4)) : null,
-            theta: r.theta != null ? Number(Number(r.theta).toFixed(4)) : null,
-            vega: r.vega != null ? Number(Number(r.vega).toFixed(4)) : null,
-            rho: r.rho != null ? Number(Number(r.rho).toFixed(4)) : null,
-            volume: r.volume,
-            openInterest: r.openInterest,
-            expiration: r.expiration ?? null,
-        }));
+    `));
+        if (!data || data.ok !== true) {
+            if (data?.reason === 'http') {
+                throw new CommandExecutionError(`Barchart greeks request failed: HTTP ${data.status}${data.statusText ? ` ${data.statusText}` : ''}`);
+            }
+            if (data?.reason === 'malformed') {
+                throw new CommandExecutionError(`Barchart greeks returned an unreadable options payload${data.message ? `: ${data.message}` : ''}`);
+            }
+            if (data?.reason === 'exception') {
+                throw new CommandExecutionError(`Barchart greeks request failed: ${data.message || 'unknown error'}`);
+            }
+            throw new CommandExecutionError(`Failed to fetch Barchart greeks for ${symbol}`);
+        }
+        if (!Array.isArray(data.rows)) {
+            throw new CommandExecutionError('Barchart greeks returned an unreadable options payload');
+        }
+        if (data.rows.length === 0) {
+            throw new EmptyResultError('barchart greeks', `No option greeks were returned for ${symbol}. Confirm the symbol, expiration, and Barchart login state.`);
+        }
+        return data.rows.map(r => {
+            if (!r || typeof r !== 'object' || Array.isArray(r)) {
+                throw new CommandExecutionError('Barchart greeks returned a malformed option row');
+            }
+            const type = String(r.type || '').trim();
+            const expirationValue = String(r.expiration || '').trim();
+            if (!/^(call|put)$/i.test(type) || r.strike === undefined || r.strike === null || r.strike === '' || !expirationValue) {
+                throw new CommandExecutionError('Barchart greeks returned a malformed option row identity');
+            }
+            return {
+                type,
+                strike: r.strike,
+                last: r.last != null ? Number(Number(r.last).toFixed(2)) : null,
+                iv: r.iv != null ? Number(Number(r.iv).toFixed(2)) + '%' : null,
+                delta: r.delta != null ? Number(Number(r.delta).toFixed(4)) : null,
+                gamma: r.gamma != null ? Number(Number(r.gamma).toFixed(4)) : null,
+                theta: r.theta != null ? Number(Number(r.theta).toFixed(4)) : null,
+                vega: r.vega != null ? Number(Number(r.vega).toFixed(4)) : null,
+                rho: r.rho != null ? Number(Number(r.rho).toFixed(4)) : null,
+                volume: r.volume,
+                openInterest: r.openInterest,
+                expiration: expirationValue,
+            };
+        });
     },
 });
+
+export const __test__ = {
+    normalizeSymbol,
+    normalizeExpiration,
+    parseLimit,
+    unwrapBrowserResult,
+};

package/clis/barchart/greeks.test.js

@@ -0,0 +1,138 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './greeks.js';
+
+const { normalizeExpiration, normalizeSymbol, parseLimit, unwrapBrowserResult } = await import('./greeks.js').then((m) => m.__test__);
+
+function makePage(evaluateResult) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    };
+}
+
+describe('barchart greeks command', () => {
+    const command = getRegistry().get('barchart/greeks');
+
+    it('registers with the expected shape', () => {
+        expect(command).toBeDefined();
+        expect(command.access).toBe('read');
+        expect(command.browser).toBe(true);
+        expect(command.columns).toEqual([
+            'type', 'strike', 'last', 'iv', 'delta', 'gamma', 'theta', 'vega', 'rho',
+            'volume', 'openInterest', 'expiration',
+        ]);
+    });
+
+    it('maps returned option rows without changing the declared output shape', async () => {
+        const page = makePage({
+            session: 'site:barchart',
+            data: {
+            ok: true,
+            rows: [
+                {
+                    type: 'Call',
+                    strike: 190,
+                    last: 3.456,
+                    iv: 21.234,
+                    delta: 0.56789,
+                    gamma: 0.01234,
+                    theta: -0.12345,
+                    vega: 0.23456,
+                    rho: 0.03456,
+                    volume: 123,
+                    openInterest: 456,
+                    expiration: '2026-06-19',
+                },
+            ],
+            },
+        });
+
+        const rows = await command.func(page, { symbol: 'aapl', limit: 1 });
+
+        expect(page.goto).toHaveBeenCalledWith('https://www.barchart.com/stocks/quotes/AAPL/options');
+        expect(page.wait).toHaveBeenCalledWith(4);
+        expect(rows).toEqual([
+            {
+                type: 'Call',
+                strike: 190,
+                last: 3.46,
+                iv: '21.23%',
+                delta: 0.5679,
+                gamma: 0.0123,
+                theta: -0.1235,
+                vega: 0.2346,
+                rho: 0.0346,
+                volume: 123,
+                openInterest: 456,
+                expiration: '2026-06-19',
+            },
+        ]);
+    });
+
+    it('validates args before browser navigation and unwraps bridge envelopes', async () => {
+        expect(normalizeSymbol(' aapl ')).toBe('AAPL');
+        expect(normalizeExpiration('2026-06-19')).toBe('2026-06-19');
+        expect(parseLimit(undefined)).toBe(10);
+        expect(parseLimit(100)).toBe(100);
+        expect(unwrapBrowserResult({ session: 'site:barchart', data: { ok: true } })).toEqual({ ok: true });
+
+        await expect(command.func(makePage({ ok: true, rows: [] }), { symbol: '', limit: 1 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(makePage({ ok: true, rows: [] }), { symbol: 'AAPL', expiration: '2026-02-30', limit: 1 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+        await expect(command.func(makePage({ ok: true, rows: [] }), { symbol: 'AAPL', limit: 101 }))
+            .rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('embeds expiration and limit in the browser-side request script', async () => {
+        const page = makePage({
+            ok: true,
+            rows: [{
+                type: 'Put',
+                strike: 185,
+                last: null,
+                iv: null,
+                delta: null,
+                gamma: null,
+                theta: null,
+                vega: null,
+                rho: null,
+                volume: 0,
+                openInterest: 0,
+                expiration: '2026-07-17',
+            }],
+        });
+
+        await command.func(page, { symbol: 'MSFT', expiration: '2026-07-17', limit: 7 });
+        const script = page.evaluate.mock.calls[0][0];
+
+        expect(script).toContain('const expDate = "2026-07-17"');
+        expect(script).toContain('const limit = 7');
+        expect(script).toContain("url += '&expirationDate=' + encodeURIComponent(expDate)");
+    });
+
+    it('throws CommandExecutionError for HTTP, malformed, exception, and missing payload states', async () => {
+        await expect(command.func(makePage({ ok: false, reason: 'http', status: 403, statusText: 'Forbidden' }), { symbol: 'AAPL' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ ok: false, reason: 'malformed' }), { symbol: 'AAPL' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ ok: false, reason: 'exception', message: 'network down' }), { symbol: 'AAPL' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ ok: false, reason: 'malformed', message: 'options rows did not include call or put identities' }), { symbol: 'AAPL' }))
+            .rejects.toThrow('call or put identities');
+        await expect(command.func(makePage(null), { symbol: 'AAPL' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ ok: true, rows: 'bad' }), { symbol: 'AAPL' }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ ok: true, rows: [{ type: 'Call', strike: null, expiration: '' }] }), { symbol: 'AAPL' }))
+            .rejects.toThrow('malformed option row identity');
+    });
+
+    it('throws EmptyResultError when Barchart returns no greeks rows', async () => {
+        await expect(command.func(makePage({ ok: true, rows: [] }), { symbol: 'AAPL' }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+    });
+});

package/clis/bilibili/summary.js

@@ -0,0 +1,167 @@
+/**
+ * Bilibili summary — fetches the official AI-generated video summary (the "AI总结"
+ * shown on the video page) via /x/web-interface/view/conclusion/get.
+ */
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { apiGet, resolveBvid } from './utils.js';
+
+const BILIBILI_HOST_RE = /(^|\.)bilibili\.com$/i;
+const B23_HOST_RE = /(^|\.)b23\.tv$/i;
+const BVID_RE = /^BV[A-Za-z0-9]+$/;
+
+function formatTime(seconds) {
+    const s = Math.max(0, Math.floor(Number(seconds) || 0));
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const sec = s % 60;
+    const pad = (n) => String(n).padStart(2, '0');
+    return h > 0 ? `${h}:${pad(m)}:${pad(sec)}` : `${pad(m)}:${pad(sec)}`;
+}
+
+async function readBvid(raw) {
+    const input = String(raw ?? '').trim();
+    if (!input) {
+        throw new ArgumentError('bilibili summary bvid cannot be empty', 'Pass a BV ID, Bilibili video URL, or b23.tv short link.');
+    }
+    if (BVID_RE.test(input)) {
+        return input;
+    }
+    let parsed = null;
+    try {
+        parsed = new URL(input);
+    } catch {
+        // Bare b23.tv short codes are accepted by the shared resolver.
+    }
+    if (parsed) {
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            throw new ArgumentError('Bilibili summary URL must use http or https');
+        }
+        if (BILIBILI_HOST_RE.test(parsed.hostname)) {
+            const match = parsed.pathname.match(/\/(?:video|bangumi\/play)\/(BV[A-Za-z0-9]+)/i);
+            if (!match) {
+                throw new ArgumentError('Bilibili summary URL must contain a BV video id');
+            }
+            return match[1];
+        }
+        if (!B23_HOST_RE.test(parsed.hostname)) {
+            throw new ArgumentError('Bilibili summary URL must be a bilibili.com or b23.tv URL');
+        }
+    }
+    try {
+        return await resolveBvid(input);
+    } catch (error) {
+        throw new ArgumentError(`Cannot resolve Bilibili BV ID from input: ${input}`, error instanceof Error ? error.message : String(error));
+    }
+}
+
+function requireOkPayload(payload, label) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new CommandExecutionError(`Bilibili ${label} API returned a malformed payload`);
+    }
+    if (payload.code !== 0) {
+        const message = payload.message ?? 'unknown error';
+        if (payload.code === -101 || payload.code === -403 || /登录|权限|forbidden|permission|login/i.test(String(message))) {
+            throw new AuthRequiredError('bilibili.com', `Bilibili ${label} API requires login or permission: ${message} (${payload.code})`);
+        }
+        throw new CommandExecutionError(`Bilibili ${label} API failed: ${message} (${payload.code})`);
+    }
+    return payload.data;
+}
+
+function readModelResult(data, bvid) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new CommandExecutionError('Bilibili conclusion API returned malformed data');
+    }
+    if (data.code !== 0) {
+        throw new EmptyResultError('bilibili summary', `Bilibili has not generated an AI summary for ${bvid}.`);
+    }
+    let modelResult = data.model_result;
+    if (typeof modelResult === 'string') {
+        try {
+            modelResult = JSON.parse(modelResult);
+        } catch {
+            throw new CommandExecutionError('Bilibili conclusion API returned malformed model_result JSON');
+        }
+    }
+    if (!modelResult || typeof modelResult !== 'object' || Array.isArray(modelResult)) {
+        throw new CommandExecutionError('Bilibili conclusion API returned malformed model_result');
+    }
+    const summary = String(modelResult.summary ?? '').trim();
+    if (!summary) {
+        throw new EmptyResultError('bilibili summary', `Bilibili has not generated an AI summary for ${bvid}.`);
+    }
+    const outline = modelResult.outline ?? [];
+    if (!Array.isArray(outline)) {
+        throw new CommandExecutionError('Bilibili conclusion API returned malformed outline');
+    }
+    return { summary, outline };
+}
+
+function rowsFromModel(model) {
+    const rows = [{ time: '', content: model.summary }];
+    for (const section of model.outline) {
+        if (!section || typeof section !== 'object' || Array.isArray(section)) {
+            throw new CommandExecutionError('Bilibili conclusion API returned malformed outline section');
+        }
+        const sectionTitle = String(section.title ?? '').trim();
+        const sectionTime = formatTime(section.timestamp);
+        if (sectionTitle) {
+            rows.push({ time: sectionTime, content: `# ${sectionTitle}` });
+        }
+        const points = section.part_outline ?? [];
+        if (!Array.isArray(points)) {
+            throw new CommandExecutionError('Bilibili conclusion API returned malformed part outline');
+        }
+        for (const point of points) {
+            if (!point || typeof point !== 'object' || Array.isArray(point)) {
+                throw new CommandExecutionError('Bilibili conclusion API returned malformed outline point');
+            }
+            const content = String(point.content ?? '').trim();
+            if (content) {
+                rows.push({ time: formatTime(point.timestamp), content });
+            }
+        }
+    }
+    return rows;
+}
+
+var command = cli({
+    site: 'bilibili',
+    name: 'summary',
+    access: 'read',
+    description: '获取 B站视频的官方 AI 总结（视频页「AI总结」同款，含分段大纲与时间戳）',
+    domain: 'www.bilibili.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'bvid', required: true, positional: true, help: 'Video BV ID / URL / b23.tv short link' },
+    ],
+    columns: ['time', 'content'],
+    func: async (page, kwargs) => {
+        if (!page) {
+            throw new CommandExecutionError('Browser session required for bilibili summary');
+        }
+        const bvid = await readBvid(kwargs.bvid);
+        const view = await apiGet(page, '/x/web-interface/view', { params: { bvid } });
+        const viewData = requireOkPayload(view, 'view');
+        const cid = viewData?.cid;
+        const upMid = viewData?.owner?.mid;
+        if (!cid || !upMid) {
+            throw new CommandExecutionError(`Bilibili view API did not return cid/up_mid for ${bvid}`);
+        }
+        const conclusion = await apiGet(page, '/x/web-interface/view/conclusion/get', {
+            params: { bvid, cid, up_mid: upMid },
+            signed: true,
+        });
+        const conclusionData = requireOkPayload(conclusion, 'conclusion');
+        return rowsFromModel(readModelResult(conclusionData, bvid));
+    },
+});
+
+export const __test__ = {
+    command,
+    formatTime,
+    readBvid,
+    readModelResult,
+    rowsFromModel,
+};