@jackwener/opencli 1.7.12 → 1.7.13

package/clis/tiktok/explore.js

@@ -1,36 +1,144 @@
-import { cli } from '@jackwener/opencli/registry';
-cli({
+// Browse TikTok "For You" / explore feed via page-context API.
+//
+// Replaces legacy DOM-link scraping (`querySelectorAll('a[href*="/video/"]')`).
+// We borrow the live page session: read `__UNIVERSAL_DATA_FOR_REHYDRATION__` for
+// the warm `webapp.recommend-feed` snapshot, then extend with `/api/recommend/item_list/`
+// when a larger `--limit` is requested. Stays inside the browser, so the session
+// cookies + msToken go along automatically.
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+import {
+    BROWSER_HELPERS,
+    MAX_PAGES,
+    SERVER_PAGE_MAX,
+    TIKTOK_AID,
+    requireLimit,
+    throwTikTokPageContextError,
+    VIDEO_ITEM_NORMALIZER,
+} from './utils.js';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 120;
+
+function buildExploreScript(limit) {
+    return `
+(async () => {
+  const limit = ${Number(limit)};
+  const maxPages = ${MAX_PAGES};
+  const SERVER_PAGE_MAX = ${SERVER_PAGE_MAX};
+  // limit was validated upfront (requireLimit). pageSize is the per-request
+  // cap TikTok accepts; we still loop until \`dedup.size < limit\` is satisfied.
+  const pageSize = limit < SERVER_PAGE_MAX ? limit : SERVER_PAGE_MAX;
+  const aid = ${JSON.stringify(TIKTOK_AID)};
+
+  ${BROWSER_HELPERS}
+  ${VIDEO_ITEM_NORMALIZER}
+
+  function collectFromState(root) {
+    if (!root) return [];
+    const out = [];
+    walkObjects(root, (node) => {
+      if (Array.isArray(node)) return false;
+      if (Array.isArray(node.itemList)) {
+        for (const item of node.itemList) out.push(item);
+      }
+      if (Array.isArray(node.items)) {
+        for (const item of node.items) out.push(item);
+      }
+      return false;
+    });
+    return out;
+  }
+
+  const dedup = new Map();
+  const universal = findUniversalData();
+  for (const item of collectFromState(universal)) {
+    const row = normalizeVideoItem(item, dedup.size + 1);
+    if (row && !dedup.has(row.id)) dedup.set(row.id, row);
+  }
+
+  const msToken = getCookie('msToken');
+  let apiFailure = null;
+  if (dedup.size < limit) {
+    let cursor = 0;
+    for (let page = 0; page < maxPages && dedup.size < limit; page += 1) {
+      const params = new URLSearchParams({
+        aid,
+        count: String(pageSize),
+        from_page: 'fyp',
+        cursor: String(cursor),
+      });
+      if (msToken) params.set('msToken', msToken);
+      try {
+        const data = await fetchJson('/api/recommend/item_list/?' + params.toString());
+        assertTikTokApiSuccess(data, 'recommend');
+        const items = Array.isArray(data.itemList) ? data.itemList : [];
+        for (const item of items) {
+          const row = normalizeVideoItem(item, dedup.size + 1);
+          if (row && !dedup.has(row.id)) dedup.set(row.id, row);
+        }
+        if (data.hasMore !== true && items.length === 0) break;
+        cursor = asNumber(data.cursor) ?? cursor + items.length;
+      } catch (error) {
+        apiFailure = error instanceof Error ? error.message : String(error);
+        break;
+      }
+    }
+  }
+
+  const rows = Array.from(dedup.values())
+    .slice(0, limit)
+    .map((row, index) => ({ ...row, index: index + 1 }));
+
+  if (rows.length === 0) {
+    const suffix = apiFailure ? ' (recommend API failed: ' + apiFailure + ')' : '';
+    throw new Error('No videos found on /explore' + suffix);
+  }
+  return rows;
+})()
+`;
+}
+
+async function listExploreVideos(page, args) {
+    const limit = requireLimit(args.limit, { fallback: DEFAULT_LIMIT, max: MAX_LIMIT });
+    await page.goto('https://www.tiktok.com/explore', { waitUntil: 'load', settleMs: 5000 });
+    let rows;
+    try {
+        rows = await page.evaluate(buildExploreScript(limit));
+    } catch (error) {
+        throwTikTokPageContextError(error, {
+            authMessage: 'TikTok requires browser access to load the explore feed',
+            emptyPattern: /No videos found/,
+            emptyTarget: 'tiktok explore',
+            failureMessage: 'Failed to load TikTok explore feed',
+        });
+    }
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new EmptyResultError('tiktok explore', 'TikTok returned an empty recommend feed');
+    }
+    return rows;
+}
+
+export const exploreCommand = cli({
     site: 'tiktok',
     name: 'explore',
     access: 'read',
-    description: 'Get trending TikTok videos from explore page',
+    description: 'Get trending TikTok videos from the recommend feed via page-context APIs',
     domain: 'www.tiktok.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
     args: [
-        { name: 'limit', type: 'int', default: 20, help: 'Number of videos' },
-    ],
-    columns: ['rank', 'author', 'views', 'url'],
-    pipeline: [
-        { navigate: { url: 'https://www.tiktok.com/explore', settleMs: 5000 } },
-        { evaluate: `(() => {
-  const limit = \${{ args.limit }};
-  const links = Array.from(document.querySelectorAll('a[href*="/video/"]'));
-  const seen = new Set();
-  const results = [];
-  for (const a of links) {
-    const href = a.href;
-    if (seen.has(href)) continue;
-    seen.add(href);
-    const match = href.match(/@([^/]+)\\/video\\/(\\d+)/);
-    results.push({
-      rank: results.length + 1,
-      author: match ? match[1] : '',
-      views: a.textContent.trim() || '-',
-      url: href,
-    });
-    if (results.length >= limit) break;
-  }
-  return results;
-})()
-` },
+        { name: 'limit', type: 'int', default: DEFAULT_LIMIT, help: `Number of videos to return (max ${MAX_LIMIT})` },
     ],
+    columns: ['index', 'id', 'author', 'url', 'cover', 'title', 'desc', 'plays', 'likes', 'comments', 'shares', 'createTime'],
+    func: listExploreVideos,
 });
+
+export const __test__ = {
+    buildExploreScript,
+    DEFAULT_LIMIT,
+    MAX_LIMIT,
+};

package/clis/tiktok/follow.js

@@ -1,40 +1,122 @@
-import { cli } from '@jackwener/opencli/registry';
-cli({
+// Follow a TikTok user via in-page button click + state verification.
+//
+// Replaces the legacy pipeline-based adapter that returned silent failure
+// rows like `{ status: 'Follow button not found', username }`. Route 1
+// here is conservative: keep the live UI button as the trigger (TikTok's
+// `/api/commit/follow/user/` requires X-Bogus signing — out of scope for
+// this PR), but harden every transition with typed errors:
+//
+//   ArgumentError         — empty or malformed username
+//   AuthRequiredError     — not logged in (no sessionid + no viewer secUid)
+//   CommandExecutionError — button missing / state verification fails /
+//                           rate limit detected (retryable=true since
+//                           TikTok dedupes follow on retry)
+//
+// `result` row enum: `followed` / `already-following` / `already-friends`
+// (mutual). Failures throw — never returned as a success row.
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    BROWSER_HELPERS,
+    BUTTON_WALKER_HELPERS,
+    RETRYABLE_HINTS,
+    TIKTOK_HOST,
+    normalizeUsername,
+    throwButtonWalkerError,
+} from './utils.js';
+
+function buildFollowScript(username) {
+    return `
+(async () => {
+  const username = ${JSON.stringify(username)};
+
+  ${BROWSER_HELPERS}
+  ${BUTTON_WALKER_HELPERS}
+
+  ensureLoggedInOrThrow();
+  ensureNoRateLimitOrThrow();
+
+  const FOLLOW_LABELS = ['Follow', '关注', 'フォロー'];
+  const FOLLOWING_LABELS = ['Following', '已关注', 'フォロー中'];
+  const FRIENDS_LABELS = ['Friends', '互关', 'フレンド'];
+  const ALREADY_LABELS = FOLLOWING_LABELS.concat(FRIENDS_LABELS);
+
+  // Idempotent fast path: already in target state.
+  if (buttonExists(FRIENDS_LABELS)) {
+    return [{ username, url: ${JSON.stringify(TIKTOK_HOST)} + '/@' + encodeURIComponent(username), result: 'already-friends' }];
+  }
+  if (buttonExists(FOLLOWING_LABELS)) {
+    return [{ username, url: ${JSON.stringify(TIKTOK_HOST)} + '/@' + encodeURIComponent(username), result: 'already-following' }];
+  }
+
+  const followBtn = findButtonByText(FOLLOW_LABELS);
+  if (!followBtn) {
+    throw new Error('BUTTON_NOT_FOUND: Follow button not on profile page (logged out, private account, or selectors changed)');
+  }
+
+  const target = followBtn.closest('button') || followBtn.closest('[role="button"]') || followBtn;
+  target.click();
+
+  // State verification: button text should flip to Following / 已关注 etc.
+  const flipped = await waitFor(() => buttonExists(ALREADY_LABELS), { timeoutMs: 5000 });
+  if (!flipped) {
+    ensureNoRateLimitOrThrow();
+    throw new Error('STATE_VERIFY_FAIL: follow button did not flip to Following within 5s; relation may not have been recorded');
+  }
+
+  // Re-check rate limit AFTER click — TikTok sometimes flashes captcha
+  // mid-flight even when the button text appears to flip.
+  ensureNoRateLimitOrThrow();
+
+  return [{
+    username,
+    url: ${JSON.stringify(TIKTOK_HOST)} + '/@' + encodeURIComponent(username),
+    result: 'followed',
+  }];
+})()
+`;
+}
+
+async function followUser(page, args) {
+    const username = normalizeUsername(args.username);
+    const throwFailure = (error) => throwButtonWalkerError(error, {
+        authMessage: 'TikTok requires login to follow users',
+        failureMessage: `Failed to follow @${username}`,
+        retryableHint: RETRYABLE_HINTS.relationFailure,
+    });
+    let rows;
+    try {
+        await page.goto(`${TIKTOK_HOST}/@${encodeURIComponent(username)}`, {
+            waitUntil: 'load',
+            settleMs: 5000,
+        });
+        rows = await page.evaluate(buildFollowScript(username));
+    } catch (error) {
+        throwFailure(error);
+    }
+    if (!Array.isArray(rows) || rows.length === 0) {
+        // Defensive: build script always returns a row on success path.
+        // If we land here, treat as state-verify failure.
+        throwFailure(new Error(`STATE_VERIFY_FAIL: follow returned no row for @${username}`));
+    }
+    return rows;
+}
+
+export const followCommand = cli({
     site: 'tiktok',
     name: 'follow',
     access: 'write',
-    description: 'Follow a TikTok user',
+    description: 'Follow a TikTok user by username',
     domain: 'www.tiktok.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
     args: [
-        {
-            name: 'username',
-            required: true,
-            positional: true,
-            help: 'TikTok username (without @)',
-        },
-    ],
-    columns: ['status', 'username'],
-    pipeline: [
-        { navigate: { url: 'https://www.tiktok.com/@${{ args.username }}', settleMs: 6000 } },
-        { evaluate: `(async () => {
-  const username = \${{ args.username | json }};
-  const buttons = Array.from(document.querySelectorAll('button, [role="button"]'));
-  const followBtn = buttons.find(function(b) {
-    var text = b.textContent.trim();
-    return text === 'Follow' || text === '关注';
-  });
-  if (!followBtn) {
-    var isFollowing = buttons.some(function(b) {
-      var t = b.textContent.trim();
-      return t === 'Following' || t === '已关注' || t === 'Friends' || t === '互关';
-    });
-    if (isFollowing) return [{ status: 'Already following', username: username }];
-    return [{ status: 'Follow button not found', username: username }];
-  }
-  followBtn.click();
-  await new Promise(r => setTimeout(r, 2000));
-  return [{ status: 'Followed', username: username }];
-})()
-` },
+        { name: 'username', required: true, positional: true, help: 'TikTok username (without @)' },
     ],
+    columns: ['username', 'url', 'result'],
+    func: followUser,
 });
+
+export const __test__ = {
+    buildFollowScript,
+};

package/clis/tiktok/following.js

@@ -1,43 +1,164 @@
-import { cli } from '@jackwener/opencli/registry';
-cli({
-    site: 'tiktok',
-    name: 'following',
-    access: 'read',
-    description: 'List accounts you follow on TikTok',
-    domain: 'www.tiktok.com',
-    args: [
-        { name: 'limit', type: 'int', default: 20, help: 'Number of accounts' },
-    ],
-    columns: ['index', 'username', 'name'],
-    pipeline: [
-        { navigate: { url: 'https://www.tiktok.com/following', settleMs: 5000 } },
-        { evaluate: `(() => {
-  const limit = \${{ args.limit }};
-  const links = Array.from(document.querySelectorAll('a[href*="/@"]'))
-    .filter(function(a) {
-      const text = a.textContent.trim();
-      return text.length > 1 && text.length < 80 &&
-        !text.includes('Profile') && !text.includes('More') && !text.includes('Upload');
+// List the accounts the logged-in user follows via page-context API.
+//
+// Replaces legacy DOM-link scraping which mistakenly hoovered up navigation
+// links and "Profile" / "Upload" labels. We resolve the viewer's `secUid` from
+// the warm `__UNIVERSAL_DATA_FOR_REHYDRATION__` snapshot, then page through
+// `/api/user/list/?scene=21` (TikTok's own following endpoint).
+
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    EmptyResultError,
+} from '@jackwener/opencli/errors';
+import {
+    BROWSER_HELPERS,
+    MAX_PAGES,
+    SERVER_PAGE_MAX,
+    TIKTOK_AID,
+    USER_ITEM_NORMALIZER,
+    requireLimit,
+    throwTikTokPageContextError,
+} from './utils.js';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 200;
+
+function buildFollowingScript(limit) {
+    return `
+(async () => {
+  const limit = ${Number(limit)};
+  const maxPages = ${MAX_PAGES * 2};
+  const SERVER_PAGE_MAX = ${SERVER_PAGE_MAX};
+  const pageSize = limit < SERVER_PAGE_MAX ? limit : SERVER_PAGE_MAX;
+  const aid = ${JSON.stringify(TIKTOK_AID)};
+
+  ${BROWSER_HELPERS}
+  ${USER_ITEM_NORMALIZER}
+
+  function findViewerSecUid(root) {
+    if (!root) return '';
+    let found = '';
+    walkObjects(root, (node) => {
+      if (Array.isArray(node)) return false;
+      const candidate = node?.user;
+      if (candidate && typeof candidate === 'object') {
+        const secUid = String(candidate.secUid || candidate.sec_uid || '').trim();
+        const isMe = Boolean(candidate.isOwner || candidate.is_owner || candidate.isCurrentUser);
+        if (secUid && isMe) {
+          found = secUid;
+          return true;
+        }
+      }
+      const direct = node?.userInfo?.user;
+      if (direct && (direct.isOwner || direct.is_owner)) {
+        const secUid = String(direct.secUid || direct.sec_uid || '').trim();
+        if (secUid) {
+          found = secUid;
+          return true;
+        }
+      }
+      return false;
     });
+    return found;
+  }
+
+  const universal = findUniversalData();
+  let viewerSecUid = findViewerSecUid(universal);
+  const msToken = getCookie('msToken');
 
-  const seen = {};
-  const results = [];
-  for (const a of links) {
-    const match = a.href.match(/@([^/]+)/);
-    const username = match ? match[1] : '';
-    if (!username || seen[username]) continue;
-    seen[username] = true;
-    const raw = a.textContent.trim();
-    const name = raw.replace(username, '').replace('@', '').trim();
-    results.push({
-      index: results.length + 1,
-      username: username,
-      name: name || username,
+  if (!viewerSecUid) {
+    try {
+      const me = await fetchJson('/api/user/info/?aid=' + aid + (msToken ? '&msToken=' + encodeURIComponent(msToken) : ''));
+      viewerSecUid = String(me?.userInfo?.user?.secUid || me?.user?.secUid || me?.userInfo?.secUid || '').trim();
+    } catch {
+      // Fall through to typed AUTH_REQUIRED below.
+    }
+  }
+  if (!viewerSecUid) {
+    throw new Error('AUTH_REQUIRED: cannot resolve viewer secUid (login required)');
+  }
+
+  const dedup = new Map();
+  let apiFailure = null;
+  let cursor = 0;
+  for (let page = 0; page < maxPages && dedup.size < limit; page += 1) {
+    const params = new URLSearchParams({
+      aid,
+      scene: '21',
+      secUid: viewerSecUid,
+      count: String(pageSize),
+      minCursor: String(cursor),
+      maxCursor: '0',
     });
-    if (results.length >= limit) break;
+    if (msToken) params.set('msToken', msToken);
+    try {
+      const data = await fetchJson('/api/user/list/?' + params.toString());
+      assertTikTokApiSuccess(data, 'user-list');
+      const list = Array.isArray(data.userList)
+        ? data.userList
+        : (Array.isArray(data.user_list) ? data.user_list : []);
+      if (list.length === 0) break;
+      for (const entry of list) {
+        const row = normalizeUserRow(entry?.user || entry, dedup.size + 1);
+        if (row && !dedup.has(row.username)) dedup.set(row.username, row);
+      }
+      if (data.hasMore !== true) break;
+      cursor = asNumber(data.minCursor) ?? asNumber(data.cursor) ?? cursor + list.length;
+    } catch (error) {
+      apiFailure = error instanceof Error ? error.message : String(error);
+      break;
+    }
   }
-  return results;
+
+  const rows = Array.from(dedup.values())
+    .slice(0, limit)
+    .map((row, index) => ({ ...row, index: index + 1 }));
+
+  if (rows.length === 0) {
+    const suffix = apiFailure ? ' (user-list API failed: ' + apiFailure + ')' : '';
+    throw new Error('No following entries returned' + suffix);
+  }
+  return rows;
 })()
-` },
+`;
+}
+
+async function listFollowing(page, args) {
+    const limit = requireLimit(args.limit, { fallback: DEFAULT_LIMIT, max: MAX_LIMIT });
+    await page.goto('https://www.tiktok.com/following', { waitUntil: 'load', settleMs: 5000 });
+    let rows;
+    try {
+        rows = await page.evaluate(buildFollowingScript(limit));
+    } catch (error) {
+        throwTikTokPageContextError(error, {
+            authMessage: 'TikTok requires login to read your following list',
+            emptyPattern: /No following entries/,
+            emptyTarget: 'tiktok following',
+            failureMessage: 'Failed to load TikTok following list',
+        });
+    }
+    if (!Array.isArray(rows) || rows.length === 0) {
+        throw new EmptyResultError('tiktok following', 'TikTok returned no following entries');
+    }
+    return rows;
+}
+
+export const followingCommand = cli({
+    site: 'tiktok',
+    name: 'following',
+    access: 'read',
+    description: 'List accounts the logged-in user follows on TikTok via page-context APIs',
+    domain: 'www.tiktok.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: DEFAULT_LIMIT, help: `Number of accounts (max ${MAX_LIMIT})` },
     ],
+    columns: ['index', 'username', 'name', 'secUid', 'verified', 'followers', 'following', 'url'],
+    func: listFollowing,
 });
+
+export const __test__ = {
+    buildFollowingScript,
+    DEFAULT_LIMIT,
+    MAX_LIMIT,
+};