@jackwener/opencli 1.7.12 → 1.7.13

package/clis/tiktok/comment.js

@@ -1,58 +1,145 @@
-import { cli } from '@jackwener/opencli/registry';
-cli({
-    site: 'tiktok',
-    name: 'comment',
-    access: 'write',
-    description: 'Comment on a TikTok video',
-    domain: 'www.tiktok.com',
-    args: [
-        { name: 'url', required: true, positional: true, help: 'TikTok video URL' },
-        { name: 'text', required: true, positional: true, help: 'Comment text' },
-    ],
-    columns: ['status', 'url', 'text'],
-    pipeline: [
-        { navigate: { url: '${{ args.url }}', settleMs: 6000 } },
-        { evaluate: `(async () => {
-  const url = \${{ args.url | json }};
-  const commentText = \${{ args.text | json }};
-  const wait = (ms) => new Promise(r => setTimeout(r, ms));
-
-  // Click comment icon to expand comment section
+// Post a comment on a TikTok video via in-page button click + state
+// verification.
+//
+// Replaces the legacy pipeline-based adapter that returned a silent
+// failure row `{ status: posted ? 'Commented' : 'Comment may have failed' }`.
+// Route 1 keeps the live UI button + contenteditable input as the
+// trigger (TikTok's `/api/comment/publish/` write endpoint requires
+// X-Bogus signing — out of scope), and every transition raises a typed
+// error:
+//
+//   ArgumentError         — empty / overlong text, malformed video URL
+//   AuthRequiredError     — not logged in
+//   CommandExecutionError — comment input / post button missing /
+//                           state verification fails / rate limit
+//                           detected (retryable=false: TikTok may have
+//                           accepted the comment server-side even when
+//                           our state-verify timed out)
+//
+// `result` row enum: `posted`. There is no idempotent fast path: TikTok
+// allows multiple identical comments, so we cannot safely "detect"
+// already-posted by scanning the existing list. Failures throw — never
+// returned as a success row.
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    BROWSER_HELPERS,
+    BUTTON_WALKER_HELPERS,
+    RETRYABLE_HINTS,
+    parseTikTokVideoUrl,
+    requireCommentText,
+    throwButtonWalkerError,
+} from './utils.js';
+
+function buildCommentScript(commentText) {
+    return `
+(async () => {
+  const commentText = ${JSON.stringify(commentText)};
+
+  ${BROWSER_HELPERS}
+  ${BUTTON_WALKER_HELPERS}
+
+  ensureLoggedInOrThrow();
+  ensureNoRateLimitOrThrow();
+
+  // Expand the comment panel if it is collapsed (vertical feed pages).
   const commentIcon = document.querySelector('[data-e2e="comment-icon"]');
   if (commentIcon) {
     const cBtn = commentIcon.closest('button') || commentIcon.closest('[role="button"]') || commentIcon;
     cBtn.click();
-    await wait(3000);
+    await waitFor(() => Boolean(
+      document.querySelector('[data-e2e="comment-input"] [contenteditable="true"]')
+    ), { timeoutMs: 4000 });
   }
 
-  // Count existing comments for verification
   const beforeCount = document.querySelectorAll('[data-e2e="comment-level-1"]').length;
 
-  // Find comment input
-  const input = document.querySelector('[data-e2e="comment-input"] [contenteditable="true"]') ||
-                document.querySelector('[contenteditable="true"]');
-  if (!input) throw new Error('Comment input not found - make sure you are logged in');
+  const input = document.querySelector('[data-e2e="comment-input"] [contenteditable="true"]')
+    || document.querySelector('[contenteditable="true"]');
+  if (!input) {
+    throw new Error('BUTTON_NOT_FOUND: comment input not found (page not rendered, comments disabled, or selectors changed)');
+  }
 
   input.focus();
+  // execCommand is deprecated but still the only reliable way to inject
+  // text into TikTok's contenteditable so its React tree picks up the
+  // value; replicating with InputEvent fires but TikTok ignores it.
   document.execCommand('insertText', false, commentText);
-  await wait(1000);
-
-  // Click post button
-  const btns = Array.from(document.querySelectorAll('[data-e2e="comment-post"], button'));
-  const postBtn = btns.find(function(b) {
-    var t = b.textContent.trim();
-    return t === 'Post' || t === '发布' || t === '发送';
-  });
-  if (!postBtn) throw new Error('Post button not found');
+
+  // Wait for the post button to become enabled — TikTok disables it
+  // until non-empty text is detected by their input handler.
+  const postReady = await waitFor(() => {
+    const candidate = findButtonByText(['Post', '发布', '发送']);
+    if (!candidate) return false;
+    const ariaDisabled = candidate.getAttribute && candidate.getAttribute('aria-disabled');
+    return !candidate.disabled && ariaDisabled !== 'true';
+  }, { timeoutMs: 4000 });
+  if (!postReady) {
+    ensureNoRateLimitOrThrow();
+    throw new Error('BUTTON_NOT_FOUND: Post button never became enabled (text not registered or selectors changed)');
+  }
+
+  const postBtn = findButtonByText(['Post', '发布', '发送']);
   postBtn.click();
-  await wait(3000);
 
-  // Verify comment was posted by checking if comment count increased
-  const afterCount = document.querySelectorAll('[data-e2e="comment-level-1"]').length;
-  const posted = afterCount > beforeCount;
+  // State verification: a new comment-level-1 element should appear.
+  const flipped = await waitFor(
+    () => document.querySelectorAll('[data-e2e="comment-level-1"]').length > beforeCount,
+    { timeoutMs: 8000 },
+  );
+  if (!flipped) {
+    ensureNoRateLimitOrThrow();
+    throw new Error('STATE_VERIFY_FAIL: comment count did not increase within 8s; comment may or may not have been recorded server-side');
+  }
+
+  ensureNoRateLimitOrThrow();
 
-  return [{ status: posted ? 'Commented' : 'Comment may have failed', url: url, text: commentText }];
+  return [{
+    url: location.href,
+    text: commentText,
+    result: 'posted',
+  }];
 })()
-` },
+`;
+}
+
+async function postComment(page, args) {
+    const { url } = parseTikTokVideoUrl(args.url);
+    const text = requireCommentText(args.text);
+    const throwFailure = (error) => throwButtonWalkerError(error, {
+        authMessage: 'TikTok requires login to post comments',
+        failureMessage: `Failed to post comment on ${url}`,
+        retryableHint: RETRYABLE_HINTS.commentFailure,
+    });
+    let rows;
+    try {
+        await page.goto(url, { waitUntil: 'load', settleMs: 6000 });
+        rows = await page.evaluate(buildCommentScript(text));
+    } catch (error) {
+        throwFailure(error);
+    }
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throwFailure(new Error(`STATE_VERIFY_FAIL: comment returned no row for ${url}`));
+    }
+    return rows;
+}
+
+export const commentCommand = cli({
+    site: 'tiktok',
+    name: 'comment',
+    access: 'write',
+    description: 'Post a comment on a TikTok video',
+    domain: 'www.tiktok.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'url', required: true, positional: true, help: 'TikTok video URL (https://www.tiktok.com/@user/video/<id>)' },
+        { name: 'text', required: true, positional: true, help: 'Comment text (≤150 chars)' },
     ],
+    columns: ['url', 'text', 'result'],
+    func: postComment,
 });
+
+export const __test__ = {
+    buildCommentScript,
+};

package/clis/tiktok/creator-videos.js

@@ -0,0 +1,270 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    ArgumentError,
+    AuthRequiredError,
+    CommandExecutionError,
+    EmptyResultError,
+    getErrorMessage,
+} from '@jackwener/opencli/errors';
+
+const STUDIO_CONTENT_URL = 'https://www.tiktok.com/tiktokstudio/content';
+const ITEM_LIST_API_PATH = '/tiktok/creator/manage/item_list/v1/';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 250;
+const SERVER_PAGE_MAX = 50;
+
+function requirePositiveInt(value, label, defaultValue, maxValue) {
+    const raw = value ?? defaultValue;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new ArgumentError(`${label} must be a positive integer`, `Example: opencli tiktok creator-videos --${label} ${defaultValue}`);
+    }
+    if (parsed > maxValue) {
+        throw new ArgumentError(`${label} must be <= ${maxValue}`, `Example: opencli tiktok creator-videos --${label} ${maxValue}`);
+    }
+    return parsed;
+}
+
+function requireCursor(value) {
+    const raw = value ?? '0';
+    const text = String(raw).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new ArgumentError('cursor must be a non-negative integer string', 'Example: opencli tiktok creator-videos --cursor 0');
+    }
+    const cursor = Number(text);
+    if (!Number.isSafeInteger(cursor)) {
+        throw new ArgumentError('cursor must be a safe integer', 'Example: opencli tiktok creator-videos --cursor 0');
+    }
+    return cursor;
+}
+
+function buildItemListRequest(cursor, size) {
+    return {
+        cursor,
+        size,
+        query: {
+            conditions: [],
+            sort_orders: [{ field_name: 'create_time', order: 2 }],
+        },
+    };
+}
+
+function buildFetchItemListScript(body) {
+    const request = {
+        url: `${ITEM_LIST_API_PATH}?aid=1988`,
+        body,
+    };
+    return `
+(async () => {
+  const request = ${JSON.stringify(request)};
+  try {
+    const res = await fetch(request.url, {
+      method: 'POST',
+      credentials: 'include',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(request.body),
+    });
+    const text = await res.text();
+    let data = null;
+    if (text.trim()) {
+      try {
+        data = JSON.parse(text);
+      } catch (error) {
+        return {
+          ok: false,
+          status: res.status,
+          statusText: res.statusText,
+          parseError: error instanceof Error ? error.message : String(error),
+          text: text.slice(0, 500),
+        };
+      }
+    }
+    return {
+      ok: res.ok,
+      status: res.status,
+      statusText: res.statusText,
+      data,
+      text: text.slice(0, 500),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      status: 0,
+      statusText: '',
+      networkError: error instanceof Error ? error.message : String(error),
+    };
+  }
+})()
+`;
+}
+
+function looksAuthFailure(message) {
+    return /\b(auth|login|log in|permission|unauthori[sz]ed|forbidden)\b/i.test(message);
+}
+
+function unwrapPayload(data) {
+    if (!data || typeof data !== 'object') {
+        throw new CommandExecutionError('TikTok Studio item_list returned an empty response');
+    }
+    return data.data && typeof data.data === 'object' ? data.data : data;
+}
+
+function assertApiSuccess(data) {
+    const statusCode = data.status_code ?? data.statusCode;
+    const statusMsg = String(data.status_msg ?? data.statusMsg ?? '').trim();
+    if (statusCode !== undefined && Number(statusCode) !== 0) {
+        if (looksAuthFailure(statusMsg)) {
+            throw new AuthRequiredError('www.tiktok.com', `TikTok Studio item_list requires login: ${statusMsg || statusCode}`);
+        }
+        throw new CommandExecutionError(`TikTok Studio item_list failed: ${statusMsg || statusCode}`);
+    }
+    if (statusMsg && !/^(success|ok)$/i.test(statusMsg)) {
+        if (looksAuthFailure(statusMsg)) {
+            throw new AuthRequiredError('www.tiktok.com', `TikTok Studio item_list requires login: ${statusMsg}`);
+        }
+        throw new CommandExecutionError(`TikTok Studio item_list failed: ${statusMsg}`);
+    }
+}
+
+function normalizeNumber(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : 0;
+}
+
+function formatDate(value) {
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds <= 0) return '';
+    return new Date(seconds * 1000).toLocaleString('zh-CN', {
+        timeZone: 'Asia/Shanghai',
+        hour12: false,
+    });
+}
+
+function extractUsername(item) {
+    const direct = item.author?.unique_id ?? item.author?.uniqueId ?? item.author_unique_id ?? item.authorUniqueId ?? item.user_name ?? item.username;
+    if (direct) return String(direct);
+
+    const blobs = [
+        ...(Array.isArray(item.play_addr) ? item.play_addr : []),
+        ...(item.download_info && Array.isArray(item.download_info.download_urls) ? item.download_info.download_urls : []),
+    ];
+    for (const raw of blobs) {
+        try {
+            const match = String(raw).match(/[?&]user_text=([^&]+)/);
+            if (match) return decodeURIComponent(match[1]);
+        } catch {
+            // Keep scanning other candidate URLs.
+        }
+    }
+    return '';
+}
+
+function normalizeRow(item) {
+    if (!item || typeof item !== 'object') return null;
+    const videoId = String(item.item_id ?? item.id ?? '').trim();
+    if (!videoId) return null;
+    const username = extractUsername(item);
+    const url = username
+        ? `https://www.tiktok.com/@${encodeURIComponent(username)}/video/${encodeURIComponent(videoId)}`
+        : '';
+    return {
+        video_id: videoId,
+        title: String(item.desc ?? item.title ?? '').replace(/\s+/g, ' ').trim(),
+        date: formatDate(item.post_time ?? item.create_time ?? item.schedule_time),
+        views: normalizeNumber(item.play_count),
+        likes: normalizeNumber(item.like_count),
+        comments: normalizeNumber(item.comment_count),
+        saves: normalizeNumber(item.favorite_count),
+        shares: normalizeNumber(item.share_count),
+        url,
+    };
+}
+
+async function fetchCreatorVideosPage(page, cursor, size) {
+    const result = await page.evaluate(buildFetchItemListScript(buildItemListRequest(cursor, size))).catch((error) => {
+        throw new CommandExecutionError(`Failed to fetch TikTok Studio item_list: ${getErrorMessage(error)}`);
+    });
+    if (!result || typeof result !== 'object') {
+        throw new CommandExecutionError('TikTok Studio item_list returned an unreadable response');
+    }
+    if (result.networkError) {
+        throw new CommandExecutionError(`TikTok Studio item_list network failure: ${result.networkError}`);
+    }
+    if (result.status === 401 || result.status === 403) {
+        throw new AuthRequiredError('www.tiktok.com', `TikTok Studio item_list requires login (HTTP ${result.status})`);
+    }
+    if (!result.ok) {
+        const detail = result.parseError
+            ? `invalid JSON (${result.parseError})`
+            : `HTTP ${result.status || 0}${result.statusText ? ` ${result.statusText}` : ''}`;
+        throw new CommandExecutionError(`TikTok Studio item_list failed: ${detail}`, result.text ? `Response preview: ${result.text}` : undefined);
+    }
+    const payload = unwrapPayload(result.data);
+    assertApiSuccess(payload);
+    return payload;
+}
+
+async function listCreatorVideos(page, args) {
+    const limit = requirePositiveInt(args.limit, 'limit', DEFAULT_LIMIT, MAX_LIMIT);
+    let nextCursor = requireCursor(args.cursor);
+    const rows = [];
+    let skippedMissingId = 0;
+    const pageSize = limit > SERVER_PAGE_MAX ? SERVER_PAGE_MAX : limit;
+    const maxPages = Math.ceil(limit / pageSize);
+
+    await page.goto(STUDIO_CONTENT_URL, { waitUntil: 'load', settleMs: 6000 });
+
+    for (let pageIndex = 0; pageIndex < maxPages && rows.length < limit; pageIndex += 1) {
+        const data = await fetchCreatorVideosPage(page, nextCursor, pageSize);
+        const items = Array.isArray(data.item_list) ? data.item_list : [];
+        for (const item of items) {
+            const row = normalizeRow(item);
+            if (!row) {
+                skippedMissingId += 1;
+                continue;
+            }
+            rows.push(row);
+            if (rows.length >= limit) break;
+        }
+        if (!data.has_more || items.length === 0) break;
+        nextCursor = requireCursor(data.cursor);
+        await page.wait(250);
+    }
+
+    if (rows.length === 0 && skippedMissingId > 0) {
+        throw new CommandExecutionError('TikTok Studio item_list returned videos without stable video_id');
+    }
+    if (rows.length === 0) {
+        throw new EmptyResultError('tiktok creator-videos', 'No creator videos were returned. Confirm the current Chrome profile is logged in to TikTok Studio and has published content.');
+    }
+    return rows.slice(0, limit);
+}
+
+export const creatorVideosCommand = cli({
+    site: 'tiktok',
+    name: 'creator-videos',
+    access: 'read',
+    description: 'TikTok Studio creator content list (views/likes/comments/saves/shares)',
+    domain: 'www.tiktok.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    navigateBefore: STUDIO_CONTENT_URL,
+    args: [
+        { name: 'limit', type: 'int', default: DEFAULT_LIMIT, help: `Number of creator videos to return (max ${MAX_LIMIT})` },
+        { name: 'cursor', type: 'string', default: '0', help: 'Non-negative TikTok Studio pagination cursor' },
+    ],
+    columns: ['video_id', 'title', 'date', 'views', 'likes', 'comments', 'saves', 'shares', 'url'],
+    func: listCreatorVideos,
+});
+
+export const __test__ = {
+    buildFetchItemListScript,
+    buildItemListRequest,
+    extractUsername,
+    normalizeRow,
+    requireCursor,
+    requirePositiveInt,
+};

package/clis/tiktok/creator-videos.test.js

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from 'vitest';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { creatorVideosCommand, __test__ } from './creator-videos.js';
+
+function makePage(evaluateResults = []) {
+    const evaluate = vi.fn();
+    for (const result of evaluateResults) {
+        evaluate.mockResolvedValueOnce(result);
+    }
+    evaluate.mockResolvedValue({ ok: true, data: { item_list: [], has_more: false } });
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate,
+    };
+}
+
+const apiItem = {
+    item_id: '7350000000000000000',
+    desc: 'hello\nworld',
+    create_time: 1710000000,
+    play_count: '123',
+    like_count: '12',
+    comment_count: '3',
+    favorite_count: '4',
+    share_count: '5',
+    author: { uniqueId: 'creator' },
+};
+
+describe('tiktok/creator-videos', () => {
+    it('registers a read-only browser command with stable video_id column', () => {
+        expect(creatorVideosCommand.access).toBe('read');
+        expect(creatorVideosCommand.browser).toBe(true);
+        expect(creatorVideosCommand.columns).toEqual([
+            'video_id',
+            'title',
+            'date',
+            'views',
+            'likes',
+            'comments',
+            'saves',
+            'shares',
+            'url',
+        ]);
+    });
+
+    it('validates args before navigating', async () => {
+        const page = makePage();
+
+        await expect(creatorVideosCommand.func(page, { limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(creatorVideosCommand.func(page, { limit: 251 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(creatorVideosCommand.func(page, { cursor: 'abc' })).rejects.toBeInstanceOf(ArgumentError);
+
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('maps TikTok Studio API rows and keeps video_id even when URL can be built', async () => {
+        const page = makePage([
+            { ok: true, data: { status_code: 0, status_msg: 'success', item_list: [apiItem], has_more: false } },
+        ]);
+
+        const rows = await creatorVideosCommand.func(page, { limit: 1 });
+
+        expect(page.goto).toHaveBeenCalledWith('https://www.tiktok.com/tiktokstudio/content', { waitUntil: 'load', settleMs: 6000 });
+        expect(rows).toEqual([{
+            video_id: '7350000000000000000',
+            title: 'hello world',
+            date: expect.any(String),
+            views: 123,
+            likes: 12,
+            comments: 3,
+            saves: 4,
+            shares: 5,
+            url: 'https://www.tiktok.com/@creator/video/7350000000000000000',
+        }]);
+    });
+
+    it('uses explicit cursor validation for follow-up pages instead of fallback-to-zero', async () => {
+        const page = makePage([
+            { ok: true, data: { item_list: [apiItem], has_more: true, cursor: 'bad-cursor' } },
+        ]);
+
+        await expect(creatorVideosCommand.func(page, { limit: 51 })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('maps auth, API, empty, and missing-id states to typed errors', async () => {
+        await expect(creatorVideosCommand.func(makePage([
+            { ok: false, status: 403, statusText: 'Forbidden' },
+        ]), { limit: 1 })).rejects.toBeInstanceOf(AuthRequiredError);
+
+        await expect(creatorVideosCommand.func(makePage([
+            { ok: true, data: { status_code: 1001, status_msg: 'creator permission denied' } },
+        ]), { limit: 1 })).rejects.toBeInstanceOf(AuthRequiredError);
+
+        await expect(creatorVideosCommand.func(makePage([
+            { ok: true, data: { status_code: 500, status_msg: 'internal error' } },
+        ]), { limit: 1 })).rejects.toBeInstanceOf(CommandExecutionError);
+
+        await expect(creatorVideosCommand.func(makePage([
+            { ok: true, data: { item_list: [], has_more: false } },
+        ]), { limit: 1 })).rejects.toBeInstanceOf(EmptyResultError);
+
+        await expect(creatorVideosCommand.func(makePage([
+            { ok: true, data: { item_list: [{ desc: 'missing id' }], has_more: false } },
+        ]), { limit: 1 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('extracts username from TikTok media URLs when author fields are absent', () => {
+        expect(__test__.extractUsername({
+            play_addr: ['https://example.invalid/video?user_text=test_user&x=1'],
+        })).toBe('test_user');
+    });
+});