@jackwener/opencli 1.3.3 → 1.4.1

package/dist/clis/cursor/composer.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { SelectorError } from '../../errors.js';
 export const composerCommand = cli({
     site: 'cursor',
     name: 'composer',
@@ -26,7 +27,7 @@ export const composerCommand = cli({
         return true;
       })(${JSON.stringify(textToInsert)})`);
         if (!typed) {
-            throw new Error('Could not find Cursor Composer input element after pressing Cmd+I.');
+            throw new SelectorError('Cursor Composer input element', 'Could not find Cursor Composer input element after pressing Cmd+I.');
         }
         await page.wait(0.5);
         await page.pressKey('Enter');

package/dist/clis/cursor/dump.js

@@ -1,25 +1,2 @@
-import { cli, Strategy } from '../../registry.js';
-import * as fs from 'fs';
-export const dumpCommand = cli({
-    site: 'cursor',
-    name: 'dump',
-    description: 'Dump the DOM and Accessibility tree of Cursor for reverse-engineering',
-    domain: 'localhost',
-    strategy: Strategy.UI,
-    browser: true,
-    columns: ['action', 'files'],
-    func: async (page) => {
-        // Extract full HTML
-        const dom = await page.evaluate('document.body.innerHTML');
-        fs.writeFileSync('/tmp/cursor-dom.html', dom);
-        // Get accessibility snapshot
-        const snap = await page.snapshot({ interactive: false });
-        fs.writeFileSync('/tmp/cursor-snapshot.json', JSON.stringify(snap, null, 2));
-        return [
-            {
-                action: 'Dom extraction finished',
-                files: '/tmp/cursor-dom.html, /tmp/cursor-snapshot.json',
-            },
-        ];
-    },
-});
+import { makeDumpCommand } from '../_shared/desktop-commands.js';
+export const dumpCommand = makeDumpCommand('cursor');

package/dist/clis/cursor/new.js

@@ -1,18 +1,2 @@
-import { cli, Strategy } from '../../registry.js';
-export const newCommand = cli({
-    site: 'cursor',
-    name: 'new',
-    description: 'Start a new Cursor chat or Composer session',
-    domain: 'localhost',
-    strategy: Strategy.UI,
-    browser: true,
-    args: [],
-    columns: ['Status'],
-    func: async (page) => {
-        // Use keyboard shortcut — most robust approach, avoids brittle DOM selectors
-        const isMac = process.platform === 'darwin';
-        await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
-        await page.wait(1);
-        return [{ Status: 'Success' }];
-    },
-});
+import { makeNewCommand } from '../_shared/desktop-commands.js';
+export const newCommand = makeNewCommand('cursor', 'Cursor chat or Composer');

package/dist/clis/cursor/read.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { EmptyResultError } from '../../errors.js';
 export const readCommand = cli({
     site: 'cursor',
     name: 'read',
@@ -36,7 +37,7 @@ export const readCommand = cli({
       })()
     `);
         if (!history || history.length === 0) {
-            throw new Error('No conversation history found in Cursor.');
+            throw new EmptyResultError('cursor read', 'No conversation history found in Cursor.');
         }
         return history;
     },

package/dist/clis/cursor/screenshot.js

@@ -1,31 +1,2 @@
-import * as fs from 'node:fs';
-import { cli, Strategy } from '../../registry.js';
-function makeScreenshotCommand(site) {
-    return cli({
-        site,
-        name: 'screenshot',
-        description: `Capture a snapshot of the current ${site} window (DOM + Accessibility tree)`,
-        domain: 'localhost',
-        strategy: Strategy.UI,
-        browser: true,
-        args: [
-            { name: 'output', required: false, help: `Output file path (default: /tmp/${site}-snapshot.txt)` },
-        ],
-        columns: ['Status', 'File'],
-        func: async (page, kwargs) => {
-            const outputPath = kwargs.output || `/tmp/${site}-snapshot.txt`;
-            // Get both the accessibility snapshot and the raw DOM HTML
-            const snap = await page.snapshot({ compact: true });
-            const html = await page.evaluate('document.documentElement.outerHTML');
-            const htmlPath = outputPath.replace(/\.\w+$/, '') + '-dom.html';
-            const snapPath = outputPath.replace(/\.\w+$/, '') + '-a11y.txt';
-            fs.writeFileSync(htmlPath, html);
-            fs.writeFileSync(snapPath, typeof snap === 'string' ? snap : JSON.stringify(snap, null, 2));
-            return [
-                { Status: 'Success', File: htmlPath },
-                { Status: 'Success', File: snapPath },
-            ];
-        },
-    });
-}
+import { makeScreenshotCommand } from '../_shared/desktop-commands.js';
 export const screenshotCursor = makeScreenshotCommand('cursor');

package/dist/clis/cursor/send.js

@@ -1,4 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
+import { SelectorError } from '../../errors.js';
 export const sendCommand = cli({
     site: 'cursor',
     name: 'send',
@@ -23,7 +24,7 @@ export const sendCommand = cli({
         return true;
       })(${JSON.stringify(textToInsert)})`);
         if (!injected) {
-            throw new Error('Could not find Cursor Composer input element.');
+            throw new SelectorError('Cursor Composer input element');
         }
         // Submit the command. In Cursor, Enter usually submits the chat.
         await page.wait(0.5);

package/dist/clis/cursor/status.js

@@ -1,21 +1,2 @@
-import { cli, Strategy } from '../../registry.js';
-export const statusCommand = cli({
-    site: 'cursor',
-    name: 'status',
-    description: 'Check active CDP connection to Cursor AI Editor',
-    domain: 'localhost',
-    strategy: Strategy.UI, // Interactive UI manipulation
-    browser: true,
-    columns: ['Status', 'Url', 'Title'],
-    func: async (page) => {
-        const url = await page.evaluate('window.location.href');
-        const title = await page.evaluate('document.title');
-        return [
-            {
-                Status: 'Connected',
-                Url: url,
-                Title: title,
-            },
-        ];
-    },
-});
+import { makeStatusCommand } from '../_shared/desktop-commands.js';
+export const statusCommand = makeStatusCommand('cursor', 'Cursor AI Editor');

package/dist/clis/dictionary/examples.yaml

@@ -0,0 +1,25 @@
+site: dictionary
+name: examples
+description: Read real-world example sentences utilizing the word
+domain: api.dictionaryapi.dev
+strategy: public
+browser: false
+
+args:
+  word:
+    type: string
+    required: true
+    positional: true
+    description: Word to get example sentences for
+
+pipeline:
+  - fetch:
+      url: "https://api.dictionaryapi.dev/api/v2/entries/en/${{ args.word | urlencode }}"
+
+  - map:
+      word: "${{ item.word }}"
+      example: "${{ (() => { if (item.meanings) { for (const m of item.meanings) { if (m.definitions) { for (const d of m.definitions) { if (d.example) return d.example; } } } } return 'No example found in API.'; })() }}"
+
+  - limit: 1
+
+columns: [word, example]

package/dist/clis/dictionary/search.yaml

@@ -0,0 +1,27 @@
+site: dictionary
+name: search
+description: Search the Free Dictionary API for definitions, parts of speech, and pronunciations.
+domain: api.dictionaryapi.dev
+strategy: public
+browser: false
+
+args:
+  word:
+    type: string
+    required: true
+    positional: true
+    description: Word to define (e.g., serendipity)
+
+pipeline:
+  - fetch:
+      url: "https://api.dictionaryapi.dev/api/v2/entries/en/${{ args.word | urlencode }}"
+
+  - map:
+      word: "${{ item.word }}"
+      phonetic: "${{ (() => { if (item.phonetic) return item.phonetic; if (item.phonetics) { for (const p of item.phonetics) { if (p.text) return p.text; } } return ''; })() }}"
+      type: "${{ (() => { if (item.meanings && item.meanings[0] && item.meanings[0].partOfSpeech) return item.meanings[0].partOfSpeech; return 'N/A'; })() }}"
+      definition: "${{ (() => { if (item.meanings && item.meanings[0] && item.meanings[0].definitions && item.meanings[0].definitions[0] && item.meanings[0].definitions[0].definition) return item.meanings[0].definitions[0].definition; return 'No definition found in API.'; })() }}"
+
+  - limit: 1
+
+columns: [word, phonetic, type, definition]

package/dist/clis/dictionary/synonyms.yaml

@@ -0,0 +1,25 @@
+site: dictionary
+name: synonyms
+description: Find synonyms for a specific word
+domain: api.dictionaryapi.dev
+strategy: public
+browser: false
+
+args:
+  word:
+    type: string
+    required: true
+    positional: true
+    description: Word to find synonyms for (e.g., serendipity)
+
+pipeline:
+  - fetch:
+      url: "https://api.dictionaryapi.dev/api/v2/entries/en/${{ args.word | urlencode }}"
+
+  - map:
+      word: "${{ item.word }}"
+      synonyms: "${{ (() => { const s = new Set(); if (item.meanings) { for (const m of item.meanings) { if (m.synonyms) { for (const syn of m.synonyms) s.add(syn); } if (m.definitions) { for (const d of m.definitions) { if (d.synonyms) { for (const syn of d.synonyms) s.add(syn); } } } } } const arr = Array.from(s); return arr.length > 0 ? arr.slice(0, 5).join(', ') : 'No synonyms found in API.'; })() }}"
+
+  - limit: 1
+
+columns: [word, synonyms]

package/dist/clis/douban/book-hot.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { loadDoubanBookHot } from './shared.js';
+import { loadDoubanBookHot } from './utils.js';
 cli({
     site: 'douban',
     name: 'book-hot',

package/dist/clis/douban/movie-hot.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { loadDoubanMovieHot } from './shared.js';
+import { loadDoubanMovieHot } from './utils.js';
 cli({
     site: 'douban',
     name: 'movie-hot',

package/dist/clis/douban/search.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { searchDouban } from './shared.js';
+import { searchDouban } from './utils.js';
 cli({
     site: 'douban',
     name: 'search',

package/dist/clis/douban/utils.d.ts

@@ -1,7 +1,10 @@
 /**
- * Douban movie adapter utilities.
+ * Douban adapter utilities.
  */
 import type { IPage } from '../../types.js';
+export declare function loadDoubanBookHot(page: IPage, limit: number): Promise<any[]>;
+export declare function loadDoubanMovieHot(page: IPage, limit: number): Promise<any[]>;
+export declare function searchDouban(page: IPage, type: string, keyword: string, limit: number): Promise<any[]>;
 /**
  * Get current user's Douban ID from movie.douban.com/mine page
  */

package/dist/clis/douban/utils.js

@@ -1,6 +1,161 @@
 /**
- * Douban movie adapter utilities.
+ * Douban adapter utilities.
  */
+import { CliError } from '../../errors.js';
+function clampLimit(limit) {
+    return Math.max(1, Math.min(limit || 20, 50));
+}
+async function ensureDoubanReady(page) {
+    const state = await page.evaluate(`
+    (() => {
+      const title = (document.title || '').trim();
+      const href = (location.href || '').trim();
+      const blocked = href.includes('sec.douban.com') || /登录跳转/.test(title) || /异常请求/.test(document.body?.innerText || '');
+      return { blocked, title, href };
+    })()
+  `);
+    if (state?.blocked) {
+        throw new CliError('AUTH_REQUIRED', 'Douban requires a logged-in browser session before these commands can load data.', 'Please sign in to douban.com in the browser that opencli reuses, then rerun the command.');
+    }
+}
+export async function loadDoubanBookHot(page, limit) {
+    const safeLimit = clampLimit(limit);
+    await page.goto('https://book.douban.com/chart');
+    await page.wait(4);
+    await ensureDoubanReady(page);
+    const data = await page.evaluate(`
+    (() => {
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const books = [];
+      for (const el of Array.from(document.querySelectorAll('.media.clearfix'))) {
+        try {
+          const titleEl = el.querySelector('h2 a[href*="/subject/"]');
+          const title = normalize(titleEl?.textContent);
+          let url = titleEl?.getAttribute('href') || '';
+          if (!title || !url) continue;
+          if (!url.startsWith('http')) url = 'https://book.douban.com' + url;
+
+          const info = normalize(el.querySelector('.subject-abstract, .pl, .pub')?.textContent);
+          const infoParts = info.split('/').map((part) => part.trim()).filter(Boolean);
+          const ratingText = normalize(el.querySelector('.subject-rating .font-small, .rating_nums, .rating')?.textContent);
+          const quote = Array.from(el.querySelectorAll('.subject-tags .tag'))
+            .map((node) => normalize(node.textContent))
+            .filter(Boolean)
+            .join(' / ');
+
+          books.push({
+            rank: parseInt(normalize(el.querySelector('.green-num-box')?.textContent), 10) || books.length + 1,
+            title,
+            rating: parseFloat(ratingText) || 0,
+            quote,
+            author: infoParts[0] || '',
+            publisher: infoParts.find((part) => /出版社|出版公司|Press/i.test(part)) || infoParts[2] || '',
+            year: infoParts.find((part) => /\\d{4}(?:-\\d{1,2})?/.test(part))?.match(/\\d{4}/)?.[0] || '',
+            price: infoParts.find((part) => /元|USD|\\$|￥/.test(part)) || '',
+            url,
+            cover: el.querySelector('img')?.getAttribute('src') || '',
+          });
+        } catch {}
+      }
+      return books.slice(0, ${safeLimit});
+    })()
+  `);
+    return Array.isArray(data) ? data : [];
+}
+export async function loadDoubanMovieHot(page, limit) {
+    const safeLimit = clampLimit(limit);
+    await page.goto('https://movie.douban.com/chart');
+    await page.wait(4);
+    await ensureDoubanReady(page);
+    const data = await page.evaluate(`
+    (() => {
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const results = [];
+      for (const el of Array.from(document.querySelectorAll('.item'))) {
+        const titleEl = el.querySelector('.pl2 a');
+        const title = normalize(titleEl?.textContent);
+        let url = titleEl?.getAttribute('href') || '';
+        if (!title || !url) continue;
+        if (!url.startsWith('http')) url = 'https://movie.douban.com' + url;
+
+        const info = normalize(el.querySelector('.pl2 p')?.textContent);
+        const infoParts = info.split('/').map((part) => part.trim()).filter(Boolean);
+        const releaseIndex = (() => {
+          for (let i = infoParts.length - 1; i >= 0; i -= 1) {
+            if (/\\d{4}-\\d{2}-\\d{2}|\\d{4}\\/\\d{2}\\/\\d{2}/.test(infoParts[i])) return i;
+          }
+          return -1;
+        })();
+        const directorPart = releaseIndex >= 1 ? infoParts[releaseIndex - 1] : '';
+        const regionPart = releaseIndex >= 2 ? infoParts[releaseIndex - 2] : '';
+        const yearMatch = info.match(/\\b(19|20)\\d{2}\\b/);
+        results.push({
+          rank: results.length + 1,
+          title,
+          rating: parseFloat(normalize(el.querySelector('.rating_nums')?.textContent)) || 0,
+          quote: normalize(el.querySelector('.inq')?.textContent),
+          director: directorPart.replace(/^导演:\\s*/, ''),
+          year: yearMatch?.[0] || '',
+          region: regionPart,
+          url,
+          cover: el.querySelector('img')?.getAttribute('src') || '',
+        });
+        if (results.length >= ${safeLimit}) break;
+      }
+      return results;
+    })()
+  `);
+    return Array.isArray(data) ? data : [];
+}
+export async function searchDouban(page, type, keyword, limit) {
+    const safeLimit = clampLimit(limit);
+    await page.goto(`https://search.douban.com/${encodeURIComponent(type)}/subject_search?search_text=${encodeURIComponent(keyword)}`);
+    await page.wait(2);
+    await ensureDoubanReady(page);
+    const data = await page.evaluate(`
+    (async () => {
+      const type = ${JSON.stringify(type)};
+      const normalize = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const seen = new Set();
+      const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+      for (let i = 0; i < 20; i += 1) {
+        if (document.querySelector('.item-root .title-text, .item-root .title a')) break;
+        await sleep(300);
+      }
+
+      const items = Array.from(document.querySelectorAll('.item-root'));
+
+      const results = [];
+      for (const el of items) {
+        const titleEl = el.querySelector('.title-text, .title a, a[title]');
+        const title = normalize(titleEl?.textContent) || normalize(titleEl?.getAttribute('title'));
+        let url = titleEl?.getAttribute('href') || '';
+        if (!title || !url) continue;
+        if (!url.startsWith('http')) url = 'https://search.douban.com' + url;
+        if (!url.includes('/subject/') || seen.has(url)) continue;
+        seen.add(url);
+        const ratingText = normalize(el.querySelector('.rating_nums')?.textContent);
+        const abstract = normalize(
+          el.querySelector('.meta.abstract, .meta, .abstract, p')?.textContent,
+        );
+        results.push({
+          rank: results.length + 1,
+          id: url.match(/subject\\/(\\d+)/)?.[1] || '',
+          type,
+          title,
+          rating: ratingText.includes('.') ? parseFloat(ratingText) : 0,
+          abstract: abstract.slice(0, 100) + (abstract.length > 100 ? '...' : ''),
+          url,
+          cover: el.querySelector('img')?.getAttribute('src') || '',
+        });
+        if (results.length >= ${safeLimit}) break;
+      }
+      return results;
+    })()
+  `);
+    return Array.isArray(data) ? data : [];
+}
 /**
  * Get current user's Douban ID from movie.douban.com/mine page
  */

package/dist/clis/doubao/ask.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { DOUBAO_DOMAIN, getDoubaoTranscriptLines, getDoubaoVisibleTurns, sendDoubaoMessage, waitForDoubaoResponse } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoTranscriptLines, getDoubaoVisibleTurns, sendDoubaoMessage, waitForDoubaoResponse } from './utils.js';
 export const askCommand = cli({
     site: 'doubao',
     name: 'ask',

package/dist/clis/doubao/new.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { DOUBAO_DOMAIN, startNewDoubaoChat } from './common.js';
+import { DOUBAO_DOMAIN, startNewDoubaoChat } from './utils.js';
 export const newCommand = cli({
     site: 'doubao',
     name: 'new',

package/dist/clis/doubao/read.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { DOUBAO_DOMAIN, getDoubaoVisibleTurns } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoVisibleTurns } from './utils.js';
 export const readCommand = cli({
     site: 'doubao',
     name: 'read',

package/dist/clis/doubao/send.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { DOUBAO_DOMAIN, sendDoubaoMessage } from './common.js';
+import { DOUBAO_DOMAIN, sendDoubaoMessage } from './utils.js';
 export const sendCommand = cli({
     site: 'doubao',
     name: 'send',

package/dist/clis/doubao/status.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { DOUBAO_DOMAIN, getDoubaoPageState } from './common.js';
+import { DOUBAO_DOMAIN, getDoubaoPageState } from './utils.js';
 export const statusCommand = cli({
     site: 'doubao',
     name: 'status',

package/dist/clis/doubao-app/ask.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { SEL, injectTextScript, clickSendScript, pollResponseScript } from './common.js';
+import { SEL, injectTextScript, clickSendScript, pollResponseScript } from './utils.js';
 export const askCommand = cli({
     site: 'doubao-app',
     name: 'ask',

package/dist/clis/doubao-app/new.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { clickNewChatScript } from './common.js';
+import { clickNewChatScript } from './utils.js';
 export const newCommand = cli({
     site: 'doubao-app',
     name: 'new',

package/dist/clis/doubao-app/read.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { readMessagesScript } from './common.js';
+import { readMessagesScript } from './utils.js';
 export const readCommand = cli({
     site: 'doubao-app',
     name: 'read',

package/dist/clis/doubao-app/send.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '../../registry.js';
-import { injectTextScript, clickSendScript } from './common.js';
+import { injectTextScript, clickSendScript } from './utils.js';
 export const sendCommand = cli({
     site: 'doubao-app',
     name: 'send',

package/dist/clis/douyin/_shared/browser-fetch.d.ts

@@ -0,0 +1,10 @@
+import type { IPage } from '../../../types.js';
+export interface FetchOptions {
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * Execute a fetch() call inside the Chrome browser context via page.evaluate.
+ * This ensures a_bogus signing and cookies are handled automatically by the browser.
+ */
+export declare function browserFetch(page: IPage, method: 'GET' | 'POST', url: string, options?: FetchOptions): Promise<unknown>;

package/dist/clis/douyin/_shared/browser-fetch.js

@@ -0,0 +1,30 @@
+import { CommandExecutionError } from '../../../errors.js';
+/**
+ * Execute a fetch() call inside the Chrome browser context via page.evaluate.
+ * This ensures a_bogus signing and cookies are handled automatically by the browser.
+ */
+export async function browserFetch(page, method, url, options = {}) {
+    const js = `
+    (async () => {
+      const res = await fetch(${JSON.stringify(url)}, {
+        method: ${JSON.stringify(method)},
+        credentials: 'include',
+        headers: {
+          'Content-Type': 'application/json',
+          ...${JSON.stringify(options.headers ?? {})}
+        },
+        ${options.body ? `body: JSON.stringify(${JSON.stringify(options.body)}),` : ''}
+      });
+      return res.json();
+    })()
+  `;
+    const result = await page.evaluate(js);
+    if (result && typeof result === 'object' && 'status_code' in result) {
+        const code = result.status_code;
+        if (code !== 0) {
+            const msg = result.status_msg ?? 'unknown error';
+            throw new CommandExecutionError(`Douyin API error ${code}: ${msg}`);
+        }
+    }
+    return result;
+}

package/dist/clis/douyin/_shared/browser-fetch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clis/douyin/_shared/browser-fetch.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from 'vitest';
+import { browserFetch } from './browser-fetch.js';
+function makePage(result) {
+    return {
+        goto: vi.fn(), evaluate: vi.fn().mockResolvedValue(result),
+        getCookies: vi.fn(), snapshot: vi.fn(), click: vi.fn(),
+        typeText: vi.fn(), pressKey: vi.fn(), scrollTo: vi.fn(),
+        getFormState: vi.fn(), wait: vi.fn(), tabs: vi.fn(),
+        closeTab: vi.fn(), newTab: vi.fn(), selectTab: vi.fn(),
+        networkRequests: vi.fn(), consoleMessages: vi.fn(),
+        scroll: vi.fn(), autoScroll: vi.fn(),
+        installInterceptor: vi.fn(), getInterceptedRequests: vi.fn(),
+        screenshot: vi.fn(),
+    };
+}
+describe('browserFetch', () => {
+    it('returns parsed JSON on success', async () => {
+        const page = makePage({ status_code: 0, data: { ak: 'KEY' } });
+        const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
+        expect(result).toEqual({ status_code: 0, data: { ak: 'KEY' } });
+    });
+    it('throws when status_code is non-zero', async () => {
+        const page = makePage({ status_code: 8, message: 'fail' });
+        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test')).rejects.toThrow('Douyin API error 8');
+    });
+    it('returns result even when no status_code field', async () => {
+        const page = makePage({ some_field: 'value' });
+        const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
+        expect(result).toEqual({ some_field: 'value' });
+    });
+});

package/dist/clis/douyin/_shared/creation-id.d.ts

@@ -0,0 +1 @@
+export declare function generateCreationId(): string;

package/dist/clis/douyin/_shared/creation-id.js

@@ -0,0 +1,5 @@
+const CHARS = 'abcdefghijklmnopqrstuvwxyz0123456789';
+export function generateCreationId() {
+    const random = Array.from({ length: 4 }, () => CHARS[Math.floor(Math.random() * CHARS.length)]).join('');
+    return 'pin' + random + Date.now();
+}

package/dist/clis/douyin/_shared/creation-id.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clis/douyin/_shared/creation-id.test.js

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { generateCreationId } from './creation-id.js';
+describe('generateCreationId', () => {
+    it('starts with "pin"', () => {
+        expect(generateCreationId()).toMatch(/^pin/);
+    });
+    it('has 4 random lowercase-alphanumeric chars after "pin"', () => {
+        expect(generateCreationId()).toMatch(/^pin[a-z0-9]{4}/);
+    });
+    it('ends with a numeric timestamp (ms)', () => {
+        const before = Date.now();
+        const id = generateCreationId();
+        const after = Date.now();
+        const ts = parseInt(id.replace(/^pin[a-z0-9]{4}/, ''), 10);
+        expect(ts).toBeGreaterThanOrEqual(before);
+        expect(ts).toBeLessThanOrEqual(after);
+    });
+    it('generates unique IDs', () => {
+        const ids = new Set(Array.from({ length: 100 }, generateCreationId));
+        expect(ids.size).toBe(100);
+    });
+});

package/dist/clis/douyin/_shared/imagex-upload.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ImageX cover image uploader.
+ *
+ * Uploads a JPEG/PNG image to ByteDance ImageX via a pre-signed PUT URL
+ * obtained from the Douyin "apply cover upload" API.
+ */
+export interface ImageXUploadInfo {
+    /** Pre-signed PUT target URL (provided by the apply cover upload API) */
+    upload_url: string;
+    /** Image URI to use in create_v2 (returned from the apply step) */
+    store_uri: string;
+}
+/**
+ * Upload a cover image to ByteDance ImageX via a pre-signed PUT URL.
+ *
+ * @param imagePath - Local file path to the image (JPEG/PNG/etc.)
+ * @param uploadInfo - Upload URL and store_uri from the apply cover upload API
+ * @returns The store_uri (= image_uri for use in create_v2)
+ */
+export declare function imagexUpload(imagePath: string, uploadInfo: ImageXUploadInfo): Promise<string>;