@jackwener/opencli 1.7.21 → 1.8.0

package/clis/chatgpt/utils.js

@@ -74,7 +74,6 @@ function buildComposerLocatorScript() {
       };
 
       findComposer.toString = () => 'findComposer';
-      return { findComposer, markerAttr };
     `;
 }
 
@@ -103,6 +102,50 @@ export function requirePositiveInt(value, flagLabel, hint) {
     return value;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// page.evaluate envelope helpers.
+//
+// The browser bridge wraps every `page.evaluate(...)` return value in a
+// `{ session, data }` envelope. Adapters that read `.length` or
+// `Array.isArray(payload)` directly on the envelope silently see "no data" —
+// this matches the failure mode fixed for xiaohongshu/rednote (#1561) and
+// weibo (#1568).
+//
+// `unwrapEvaluateResult` is a defensive ternary: it unwraps when the payload
+// looks like an envelope, otherwise passes the value through unchanged so
+// older bridge versions and primitive return values still work.
+// ─────────────────────────────────────────────────────────────────────────────
+export function unwrapEvaluateResult(payload) {
+    if (payload && !Array.isArray(payload) && typeof payload === 'object' && 'session' in payload && 'data' in payload) {
+        return payload.data;
+    }
+    return payload;
+}
+
+export function requireArrayEvaluateResult(payload, label) {
+    if (!Array.isArray(payload)) {
+        if (payload && typeof payload === 'object' && 'error' in payload) {
+            throw new CommandExecutionError(`${label}: ${String(payload.error)}`);
+        }
+        throw new CommandExecutionError(`${label} returned malformed extraction payload`);
+    }
+    return payload;
+}
+
+export function requireObjectEvaluateResult(payload, label) {
+    if (!payload || Array.isArray(payload) || typeof payload !== 'object') {
+        throw new CommandExecutionError(`${label} returned malformed extraction payload`);
+    }
+    return payload;
+}
+
+export function requireBooleanEvaluateResult(payload, label) {
+    if (typeof payload !== 'boolean') {
+        throw new CommandExecutionError(`${label} returned malformed extraction payload`);
+    }
+    return payload;
+}
+
 export function parseChatGPTConversationId(value) {
     const raw = String(value ?? '').trim();
     const match = raw.match(/(?:^|\/c\/)([A-Za-z0-9_-]{8,})(?:[/?#]|$)/);
@@ -115,7 +158,7 @@ export function parseChatGPTConversationId(value) {
 }
 
 export async function currentChatGPTUrl(page) {
-    const url = await page.evaluate('window.location.href').catch(() => '');
+    const url = unwrapEvaluateResult(await page.evaluate('window.location.href').catch(() => ''));
     return typeof url === 'string' ? url : '';
 }
 
@@ -161,7 +204,7 @@ export async function startNewChat(page) {
 }
 
 export async function getPageState(page) {
-    return await page.evaluate(`(() => {
+    return requireObjectEvaluateResult(unwrapEvaluateResult(await page.evaluate(`(() => {
         const isVisible = (el) => {
             if (!(el instanceof HTMLElement)) return false;
             const style = window.getComputedStyle(el);
@@ -187,7 +230,7 @@ export async function getPageState(page) {
             isLoggedIn: hasComposer || !!userMenu || !hasLoginGate,
             hasLoginGate,
         };
-    })()`);
+    })()`)), 'chatgpt page state');
 }
 
 export async function ensureChatGPTLogin(page, message = 'ChatGPT requires a logged-in browser session.') {
@@ -258,7 +301,7 @@ export async function sendChatGPTMessage(page, text) {
     // findComposer() retries inside a single CDP call, so no fixed sleep is
     // needed before reading the composer.
 
-    const typeResult = await page.evaluate(`
+    const typeResult = requireBooleanEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
         (() => {
             ${buildComposerLocatorScript()}
             const composer = findComposer();
@@ -276,8 +319,8 @@ export async function sendChatGPTMessage(page, text) {
             composer.dispatchEvent(new Event('change', { bubbles: true }));
             return true;
         })()
-    `);
-    
+    `)), 'chatgpt composer readiness');
+
     if (!typeResult) return false;
     
     // Use page.type() which is Playwright's native method
@@ -304,7 +347,7 @@ export async function sendChatGPTMessage(page, text) {
     let sent = null;
     for (let attempt = 0; attempt < 20; attempt += 1) {
         await page.wait(0.5);
-        sent = await page.evaluate(`
+        sent = requireObjectEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
             (() => {
                 const isUsable = (button) => button
                     && !button.disabled
@@ -318,7 +361,7 @@ export async function sendChatGPTMessage(page, text) {
                     : btns.find(b => labels.includes(b.getAttribute('aria-label') || '') && isUsable(b));
                 return { sendBtnFound: !!sendBtn };
             })()
-        `);
+        `)), 'chatgpt send button readiness');
         if (sent?.sendBtnFound) break;
     }
 
@@ -339,7 +382,7 @@ export async function sendChatGPTMessage(page, text) {
 }
 
 export async function getVisibleMessages(page) {
-    const result = await page.evaluate(`(() => {
+    const result = requireArrayEvaluateResult(unwrapEvaluateResult(await page.evaluate(`(() => {
         const isVisible = (el) => {
             if (!(el instanceof HTMLElement)) return false;
             const style = window.getComputedStyle(el);
@@ -385,8 +428,7 @@ export async function getVisibleMessages(page) {
             rows.push({ role, text, html });
         }
         return rows;
-    })()`);
-    if (!Array.isArray(result)) return [];
+    })()`)), 'chatgpt visible messages');
     return result.map((item, index) => ({
         Index: index + 1,
         Role: item?.role === 'Assistant' ? 'Assistant' : 'User',
@@ -448,7 +490,7 @@ export async function getConversationList(page) {
     // so the previous standalone 2 s settle is redundant.
     await ensureOnChatGPT(page);
 
-    const openSidebar = await page.evaluate(`(() => {
+    const openSidebar = requireBooleanEvaluateResult(unwrapEvaluateResult(await page.evaluate(`(() => {
         const button = Array.from(document.querySelectorAll('button'))
             .find((node) => /open sidebar/i.test(node.getAttribute('aria-label') || ''));
         if (button instanceof HTMLElement) {
@@ -456,7 +498,7 @@ export async function getConversationList(page) {
             return true;
         }
         return false;
-    })()`);
+    })()`)), 'chatgpt sidebar open state');
     if (openSidebar) {
         try {
             await page.wait({ selector: CONVERSATION_LINK_SELECTOR, timeout: 3 });
@@ -480,7 +522,7 @@ export async function getConversationList(page) {
 }
 
 async function extractConversationLinks(page) {
-    const items = await page.evaluate(`(() => {
+    const items = requireArrayEvaluateResult(unwrapEvaluateResult(await page.evaluate(`(() => {
         const isVisible = (el) => {
             if (!(el instanceof HTMLElement)) return false;
             const style = window.getComputedStyle(el);
@@ -505,15 +547,13 @@ async function extractConversationLinks(page) {
             });
         }
         return rows;
-    })()`);
-    return Array.isArray(items)
-        ? items.map((item, index) => ({
+    })()`)), 'chatgpt conversation link extraction');
+    return items.map((item, index) => ({
             Index: index + 1,
             Id: String(item?.Id || ''),
             Title: String(item?.Title || '(untitled)').trim() || '(untitled)',
             Url: String(item?.Url || ''),
-        })).filter((item) => item.Id)
-        : [];
+        })).filter((item) => item.Id);
 }
 
 function imageMimeFromPath(filePath) {
@@ -556,7 +596,7 @@ async function waitForChatGPTUploadPreview(page, fileNames) {
     const namesJson = JSON.stringify(fileNames);
     for (let attempt = 0; attempt < 10; attempt += 1) {
         await page.wait(1);
-        const ready = await page.evaluate(`
+        const ready = requireBooleanEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
             (() => {
                 const names = ${namesJson};
                 const text = document.body ? (document.body.innerText || '') : '';
@@ -572,7 +612,7 @@ async function waitForChatGPTUploadPreview(page, fileNames) {
                 const previewNodes = scope.querySelectorAll('img[src], canvas, video, [style*="background-image"], [data-testid*="attachment"], [data-testid*="upload"], [class*="attachment"], [class*="upload"]');
                 return previewNodes.length >= names.length;
             })()
-        `);
+        `)), 'chatgpt upload preview detection');
         if (ready) return true;
     }
     return false;
@@ -606,7 +646,7 @@ export async function uploadChatGPTImages(page, imagePaths) {
             mime: imageMimeFromPath(absPath),
             base64: fs.default.readFileSync(absPath).toString('base64'),
         }));
-        const fallbackResult = await page.evaluate(`
+        const fallbackResult = requireObjectEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
             (() => {
                 const files = ${JSON.stringify(files)};
                 const input = document.querySelector('input[type="file"]');
@@ -642,7 +682,7 @@ export async function uploadChatGPTImages(page, imagePaths) {
                 }
                 return { ok: true };
             })()
-        `);
+        `)), 'chatgpt image upload fallback');
         if (fallbackResult && !fallbackResult.ok) return fallbackResult;
     }
 
@@ -656,21 +696,21 @@ export async function uploadChatGPTImages(page, imagePaths) {
  * Check if ChatGPT is still generating a response.
  */
 export async function isGenerating(page) {
-    return await page.evaluate(`
+    return requireBooleanEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
         (() => {
             return Array.from(document.querySelectorAll('button')).some(b => {
                 const label = b.getAttribute('aria-label') || '';
                 return label === 'Stop generating' || label.includes('Thinking');
             });
         })()
-    `);
+    `)), 'chatgpt generation state');
 }
 
 /**
  * Get visible image URLs from the ChatGPT page (excluding profile/avatar images).
  */
 export async function getChatGPTVisibleImageUrls(page) {
-    return await page.evaluate(`
+    return requireArrayEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
         (() => {
             const isVisible = (el) => {
                 if (!(el instanceof HTMLElement)) return false;
@@ -680,32 +720,78 @@ export async function getChatGPTVisibleImageUrls(page) {
                 return rect.width > 32 && rect.height > 32;
             };
 
+            const urls = [];
+            const seen = new Set();
+            const normalizeUrl = (value) => {
+                const raw = String(value || '').trim();
+                if (!raw || raw === 'none') return '';
+                if (/^(?:https?:|blob:|data:)/i.test(raw)) return raw;
+                try {
+                    return new URL(raw, window.location.href).href;
+                } catch {
+                    return raw;
+                }
+            };
+            const addUrl = (value) => {
+                const src = normalizeUrl(value);
+                if (!src || seen.has(src)) return;
+                seen.add(src);
+                urls.push(src);
+            };
+            const isDecorative = (el, src = '') => {
+                const alt = (el.getAttribute('alt') || '').toLowerCase();
+                const cls = String(el.className || '').toLowerCase();
+                const testId = (el.getAttribute('data-testid') || '').toLowerCase();
+                const label = (el.getAttribute('aria-label') || '').toLowerCase();
+                const text = [alt, cls, testId, label, src.toLowerCase()].join(' ');
+                return /avatar|profile|logo|icon/.test(text);
+            };
+
             const imgs = Array.from(document.querySelectorAll('img')).filter(img =>
                 img instanceof HTMLImageElement && isVisible(img)
             );
 
-            const urls = [];
-            const seen = new Set();
-
             for (const img of imgs) {
                 const src = img.currentSrc || img.src || '';
-                const alt = (img.getAttribute('alt') || '').toLowerCase();
-                const cls = (img.className || '').toLowerCase();
                 const width = img.naturalWidth || img.width || 0;
                 const height = img.naturalHeight || img.height || 0;
 
                 if (!src) continue;
-                if (alt.includes('avatar') || alt.includes('profile') || alt.includes('logo') || alt.includes('icon')) continue;
-                if (cls.includes('avatar') || cls.includes('profile') || cls.includes('icon')) continue;
+                if (isDecorative(img, src)) continue;
                 if (width < 128 && height < 128) continue;
-                if (seen.has(src)) continue;
+                addUrl(src);
+            }
 
-                seen.add(src);
-                urls.push(src);
+            // ChatGPT occasionally renders generated images as CSS background
+            // thumbnails instead of plain <img> nodes. Treat visible, large
+            // background images as generated-image candidates too.
+            for (const el of Array.from(document.querySelectorAll('[style*="background-image"], [style*="background"]'))) {
+                if (!(el instanceof HTMLElement) || !isVisible(el) || isDecorative(el)) continue;
+                const rect = el.getBoundingClientRect();
+                if (rect.width < 128 && rect.height < 128) continue;
+                const backgroundImage = window.getComputedStyle(el).backgroundImage || '';
+                for (const match of backgroundImage.matchAll(/url\\((['"]?)(.*?)\\1\\)/g)) {
+                    const src = match[2];
+                    if (!src || isDecorative(el, src)) continue;
+                    addUrl(src);
+                }
+            }
+
+            // Some image experiences render to a canvas. Returning the data URL
+            // lets the downstream asset exporter save it without needing a DOM
+            // selector to rediscover the canvas.
+            for (const canvas of Array.from(document.querySelectorAll('canvas'))) {
+                if (!(canvas instanceof HTMLCanvasElement) || !isVisible(canvas) || isDecorative(canvas)) continue;
+                const width = canvas.width || canvas.getBoundingClientRect().width || 0;
+                const height = canvas.height || canvas.getBoundingClientRect().height || 0;
+                if (width < 128 && height < 128) continue;
+                try {
+                    addUrl(canvas.toDataURL('image/png'));
+                } catch { }
             }
             return urls;
         })()
-    `);
+    `)), 'chatgpt visible image url extraction');
 }
 
 /**
@@ -723,7 +809,7 @@ export async function waitForChatGPTImages(page, beforeUrls, timeoutSeconds, con
 
         let currentUrl = '';
         if (convUrl && convUrl.includes('/c/')) {
-            currentUrl = await page.evaluate('window.location.href').catch(() => '');
+            currentUrl = unwrapEvaluateResult(await page.evaluate('window.location.href').catch(() => ''));
             if (currentUrl && !isSameChatGPTConversation(currentUrl, convUrl)) {
                 await page.goto(convUrl);
                 await page.wait(3);
@@ -766,6 +852,7 @@ export const __test__ = {
     SEND_BUTTON_FALLBACK_SELECTORS,
     SEND_BUTTON_LABELS,
     CLOSE_SIDEBAR_LABELS,
+    buildComposerLocatorScript,
     isSameChatGPTConversation,
     parseChatGPTConversationId,
     imageMimeFromPath,
@@ -776,7 +863,7 @@ export const __test__ = {
  */
 export async function getChatGPTImageAssets(page, urls) {
     const urlsJson = JSON.stringify(urls);
-    return await page.evaluate(`
+    return requireArrayEvaluateResult(unwrapEvaluateResult(await page.evaluate(`
         (async (targetUrls) => {
             const blobToDataUrl = (blob) => new Promise((resolve, reject) => {
                 const reader = new FileReader();
@@ -809,6 +896,26 @@ export async function getChatGPTImageAssets(page, urls) {
                 if (img) {
                     width = img.naturalWidth || img.width || 0;
                     height = img.naturalHeight || img.height || 0;
+                } else {
+                    const backgroundEl = Array.from(document.querySelectorAll('[style*="background-image"], [style*="background"]')).find(el => {
+                        if (!(el instanceof HTMLElement)) return false;
+                        const backgroundImage = window.getComputedStyle(el).backgroundImage || '';
+                        return Array.from(backgroundImage.matchAll(/url\\((['"]?)(.*?)\\1\\)/g)).some(match => {
+                            const raw = String(match[2] || '').trim();
+                            if (!raw) return false;
+                            if (raw === targetUrl) return true;
+                            try {
+                                return new URL(raw, window.location.href).href === targetUrl;
+                            } catch {
+                                return false;
+                            }
+                        });
+                    });
+                    if (backgroundEl) {
+                        const rect = backgroundEl.getBoundingClientRect();
+                        width = Math.round(rect.width || 0);
+                        height = Math.round(rect.height || 0);
+                    }
                 }
 
                 try {
@@ -850,5 +957,5 @@ export async function getChatGPTImageAssets(page, urls) {
 
             return results;
         })(${urlsJson})
-    `, urls);
+    `)), 'chatgpt image asset export');
 }

package/clis/chatgpt/utils.test.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { JSDOM } from 'jsdom';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { __test__, prepareChatGPTImagePaths, sendChatGPTMessage, uploadChatGPTImages, waitForChatGPTImages } from './utils.js';
+import { __test__, getChatGPTImageAssets, getChatGPTVisibleImageUrls, prepareChatGPTImagePaths, sendChatGPTMessage, uploadChatGPTImages, waitForChatGPTImages } from './utils.js';
 
 const tempDirs = [];
 
@@ -88,6 +89,25 @@ describe('chatgpt conversation id parsing', () => {
 });
 
 describe('chatgpt send selectors', () => {
+    it('inlines the composer locator without returning before caller code runs', () => {
+        const dom = new JSDOM('<!doctype html><div id="prompt-textarea" contenteditable="true"></div>', {
+            url: 'https://chatgpt.com/',
+            runScripts: 'outside-only',
+        });
+        const composer = dom.window.document.querySelector('#prompt-textarea');
+        composer.getBoundingClientRect = () => ({ width: 320, height: 48 });
+
+        const result = dom.window.eval(`
+            (() => {
+                ${__test__.buildComposerLocatorScript()}
+                const composer = findComposer();
+                return !!composer && composer.getAttribute(markerAttr) === '1';
+            })()
+        `);
+
+        expect(result).toBe(true);
+    });
+
     it('keeps locale-independent send-button selector before aria-label fallbacks', async () => {
         const page = {
             wait: vi.fn().mockResolvedValue(undefined),
@@ -143,6 +163,73 @@ describe('chatgpt send selectors', () => {
     });
 });
 
+describe('chatgpt generated image detection', () => {
+    function createDomPage(html, setup = () => {}) {
+        const dom = new JSDOM(html, {
+            url: 'https://chatgpt.com/c/demo',
+            runScripts: 'outside-only',
+        });
+        setup(dom.window);
+        return {
+            evaluate: vi.fn((script) => Promise.resolve(dom.window.eval(String(script)))),
+        };
+    }
+
+    it('detects visible CSS background images when ChatGPT does not render a plain img', async () => {
+        const page = createDomPage(`
+            <!doctype html>
+            <main>
+              <div class="avatar" style="background-image: url('https://chatgpt.com/avatar.png')"></div>
+              <button data-testid="generated-image" style="background-image: url('/backend-api/generated/foo.webp')"></button>
+            </main>
+        `, (window) => {
+            for (const el of window.document.querySelectorAll('div, button')) {
+                el.getBoundingClientRect = () => ({ width: 512, height: 512 });
+            }
+        });
+
+        await expect(getChatGPTVisibleImageUrls(page)).resolves.toEqual([
+            'https://chatgpt.com/backend-api/generated/foo.webp',
+        ]);
+    });
+
+    it('detects visible generated canvases as data URLs', async () => {
+        const page = createDomPage('<!doctype html><canvas width="512" height="512"></canvas>', (window) => {
+            const canvas = window.document.querySelector('canvas');
+            canvas.getBoundingClientRect = () => ({ width: 512, height: 512 });
+            canvas.toDataURL = () => 'data:image/png;base64,ZmFrZQ==';
+        });
+
+        await expect(getChatGPTVisibleImageUrls(page)).resolves.toEqual([
+            'data:image/png;base64,ZmFrZQ==',
+        ]);
+    });
+
+    it('exports assets for generated CSS background images', async () => {
+        const imageUrl = 'https://chatgpt.com/backend-api/generated/foo.webp';
+        const page = createDomPage(`
+            <!doctype html>
+            <button style="background-image: url('/backend-api/generated/foo.webp')"></button>
+        `, (window) => {
+            const button = window.document.querySelector('button');
+            button.getBoundingClientRect = () => ({ width: 512, height: 512 });
+            window.fetch = vi.fn().mockResolvedValue({
+                ok: true,
+                blob: async () => new window.Blob(['fake-image'], { type: 'image/webp' }),
+            });
+        });
+
+        await expect(getChatGPTImageAssets(page, [imageUrl])).resolves.toEqual([
+            expect.objectContaining({
+                url: imageUrl,
+                mimeType: 'image/webp',
+                width: 512,
+                height: 512,
+            }),
+        ]);
+    });
+});
+
 describe('chatgpt image upload helper', () => {
     it('validates local images without a browser page', async () => {
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-chatgpt-'));
@@ -218,7 +305,10 @@ describe('chatgpt image upload helper', () => {
             setFileInput: vi.fn().mockRejectedValue(new Error('No element found')),
             wait: vi.fn().mockResolvedValue(undefined),
             evaluate: vi.fn((script) => {
-                return Promise.resolve({ ok: true });
+                if (String(script).includes('new DataTransfer()')) {
+                    return Promise.resolve({ ok: true });
+                }
+                return Promise.resolve(true);
             }),
         };
 

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

@@ -1,4 +1,11 @@
-import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { unwrapEvaluateResult } from './evaluate-result.js';
+
+function isAuthLikeError(code, message) {
+    const text = String(message ?? '');
+    return code === 401 || code === 403 || /login|cookie|auth|captcha|verify|forbidden|permission|登录|登陆|权限|验证|验证码/i.test(text);
+}
+
 /**
  * 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.
@@ -6,36 +13,53 @@ import { CommandExecutionError } from '@jackwener/opencli/errors';
 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)}),` : ''}
-      });
-      const text = await res.text();
-      if (!text) return null;
-      return JSON.parse(text);
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), ${Number(options.timeoutMs ?? 30000)});
+      try {
+        const res = await fetch(${JSON.stringify(url)}, {
+          method: ${JSON.stringify(method)},
+          credentials: 'include',
+          signal: controller.signal,
+          headers: {
+            'Content-Type': 'application/json',
+            ...${JSON.stringify(options.headers ?? {})}
+          },
+          ${options.body ? `body: JSON.stringify(${JSON.stringify(options.body)}),` : ''}
+        });
+        const text = await res.text();
+        try {
+          return JSON.parse(text);
+        } catch (error) {
+          return { status_code: res.ok ? -2 : res.status, status_msg: \`JSON parse failed: \${text.slice(0, 500) || String(error && error.message || error)}\` };
+        }
+      } catch (error) {
+        return { status_code: -1, status_msg: String(error && error.message || error) };
+      } finally {
+        clearTimeout(timer);
+      }
     })()
   `;
     let result;
     try {
-        result = await page.evaluate(js);
+        result = unwrapEvaluateResult(await page.evaluate(js));
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new CommandExecutionError(`Douyin API request failed: ${message}`);
+        throw new CommandExecutionError(`Douyin API request failed (${method} ${url}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (result == null) {
+        throw new CommandExecutionError(`Empty response from Douyin API (${method} ${url})`);
     }
-    if (result === null || result === undefined) {
-        throw new CommandExecutionError('Empty response from Douyin API');
+    if (Array.isArray(result) || typeof result !== 'object') {
+        throw new CommandExecutionError(`Malformed response from Douyin API (${method} ${url})`);
     }
     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}`);
+            const msg = result.status_msg ?? result.message ?? 'unknown error';
+            if (isAuthLikeError(code, msg)) {
+                throw new AuthRequiredError('creator.douyin.com', `Douyin API auth/permission error ${code} at ${method} ${url}: ${msg}`);
+            }
+            throw new CommandExecutionError(`Douyin API error ${code} at ${method} ${url}: ${msg}`);
         }
     }
     return result;

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

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { browserFetch } from './browser-fetch.js';
 function makePage(result) {
     return {
@@ -18,10 +19,20 @@ describe('browserFetch', () => {
         const result = await browserFetch(page, 'GET', 'https://creator.douyin.com/api/test');
         expect(result).toEqual({ status_code: 0, data: { ak: 'KEY' } });
     });
+    it('unwraps Browser Bridge {session,data} envelopes', async () => {
+        const page = makePage({ session: 'site:douyin:test', data: { status_code: 0, data: { ok: true } } });
+        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test'))
+            .resolves.toEqual({ status_code: 0, data: { ok: true } });
+    });
     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('maps auth-like API errors to AuthRequiredError', async () => {
+        const page = makePage({ status_code: 401, status_msg: 'login required' });
+        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test'))
+            .rejects.toBeInstanceOf(AuthRequiredError);
+    });
     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');
@@ -35,9 +46,19 @@ describe('browserFetch', () => {
         const page = makePage(undefined);
         await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test')).rejects.toThrow('Empty response from Douyin API');
     });
+    it('throws typed on malformed primitive response body', async () => {
+        const page = makePage('not-json-object');
+        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test'))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+    it('throws typed when browser fetch returns a non-JSON body', async () => {
+        const page = makePage({ status_code: -2, status_msg: 'JSON parse failed: <html>not-json</html>' });
+        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test'))
+            .rejects.toThrow('Douyin API error -2');
+    });
     it('wraps browser-side fetch or JSON parse failures', async () => {
         const page = makePage(null);
         page.evaluate.mockRejectedValueOnce(new SyntaxError('Unexpected token < in JSON'));
-        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test')).rejects.toThrow('Douyin API request failed: Unexpected token < in JSON');
+        await expect(browserFetch(page, 'GET', 'https://creator.douyin.com/api/test')).rejects.toThrow('Douyin API request failed (GET https://creator.douyin.com/api/test): Unexpected token < in JSON');
     });
 });

package/clis/douyin/_shared/evaluate-result.js

@@ -0,0 +1,16 @@
+import { CommandExecutionError } from '@jackwener/opencli/errors';
+
+export function unwrapEvaluateResult(payload) {
+  if (payload && !Array.isArray(payload) && typeof payload === 'object' && 'session' in payload && 'data' in payload) {
+    return payload.data;
+  }
+  return payload;
+}
+
+export function requireObjectEvaluateResult(payload, context) {
+  const result = unwrapEvaluateResult(payload);
+  if (!result || Array.isArray(result) || typeof result !== 'object') {
+    throw new CommandExecutionError(`${context}: malformed evaluate payload`);
+  }
+  return result;
+}