@jackwener/opencli 1.7.22 → 1.8.1

package/clis/twitter/download.test.js

@@ -0,0 +1,457 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const { mockDownloadMedia, mockFormatCookieHeader } = vi.hoisted(() => ({
+    mockDownloadMedia: vi.fn(),
+    mockFormatCookieHeader: vi.fn(() => 'ct0=token'),
+}));
+vi.mock('@jackwener/opencli/download/media-download', () => ({
+    downloadMedia: mockDownloadMedia,
+}));
+vi.mock('@jackwener/opencli/download', () => ({
+    formatCookieHeader: mockFormatCookieHeader,
+}));
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { __test__ } from './download.js';
+
+const {
+    buildUserMediaUrl,
+    buildUserByScreenNameUrl,
+    parseUserMedia,
+    classifyMediaUrl,
+    requireLimit,
+    nextUserMediaFetchCount,
+} = __test__;
+
+function createPageMock(evaluateResults = []) {
+    const evaluate = vi.fn();
+    for (const result of evaluateResults) evaluate.mockResolvedValueOnce(result);
+    evaluate.mockResolvedValue(undefined);
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue(undefined),
+        evaluate,
+        getCookies: vi.fn().mockResolvedValue([{ name: 'ct0', value: 'token', domain: '.x.com' }]),
+    };
+}
+
+function userLookupPayload(userId = '42') {
+    return {
+        ok: true,
+        payload: {
+            data: {
+                user: {
+                    result: { rest_id: userId },
+                },
+            },
+        },
+    };
+}
+
+function userMediaPayload(entries) {
+    return {
+        ok: true,
+        payload: {
+            data: {
+                user: {
+                    result: {
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [{ entries }],
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+
+function tweetEntry(id, url = `https://pbs.twimg.com/media/${id}.jpg`) {
+    return {
+        content: {
+            itemContent: {
+                tweet_results: {
+                    result: {
+                        rest_id: id,
+                        legacy: {
+                            extended_entities: {
+                                media: [{ type: 'photo', media_url_https: url }],
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+
+describe('twitter download helpers', () => {
+    beforeEach(() => {
+        mockDownloadMedia.mockReset();
+        mockDownloadMedia.mockResolvedValue([{ index: 1, type: 'image', status: 'success', size: '1 KB' }]);
+        mockFormatCookieHeader.mockClear();
+    });
+
+    it('registers the canonical download columns', () => {
+        const cmd = getRegistry().get('twitter/download');
+        expect(cmd?.columns).toEqual(['index', 'tweet_id', 'url', 'type', 'status', 'size']);
+    });
+
+    it('makes username positional and tweet-url a flag', () => {
+        const cmd = getRegistry().get('twitter/download');
+        const usernameArg = cmd?.args?.find((a) => a.name === 'username');
+        const tweetUrlArg = cmd?.args?.find((a) => a.name === 'tweet-url');
+        expect(usernameArg?.positional).toBe(true);
+        expect(tweetUrlArg?.positional).not.toBe(true);
+    });
+
+    it('builds a UserMedia URL with userId, count and cursor', () => {
+        const url = buildUserMediaUrl(
+            { queryId: 'QID', features: { fa: true }, fieldToggles: { fb: true } },
+            '42',
+            50,
+            'cursor-xyz',
+        );
+        expect(url.startsWith('/i/api/graphql/QID/UserMedia?')).toBe(true);
+        const vars = JSON.parse(decodeURIComponent(url.match(/variables=([^&]+)/)[1]));
+        expect(vars.userId).toBe('42');
+        expect(vars.count).toBe(50);
+        expect(vars.cursor).toBe('cursor-xyz');
+        expect(vars.includePromotedContent).toBe(false);
+    });
+
+    it('omits cursor variable when not paging', () => {
+        const url = buildUserMediaUrl({ queryId: 'QID', features: {}, fieldToggles: {} }, '42', 10, null);
+        const vars = JSON.parse(decodeURIComponent(url.match(/variables=([^&]+)/)[1]));
+        expect(vars.cursor).toBeUndefined();
+    });
+
+    it('builds a UserByScreenName URL with the screen_name variable', () => {
+        const url = buildUserByScreenNameUrl(
+            { queryId: 'UBSN', features: {}, fieldToggles: {} },
+            'jack',
+        );
+        expect(url.startsWith('/i/api/graphql/UBSN/UserByScreenName?')).toBe(true);
+        expect(decodeURIComponent(url)).toContain('"screen_name":"jack"');
+    });
+
+    it('classifies twimg video URLs as video and pbs URLs as image', () => {
+        expect(classifyMediaUrl('https://video.twimg.com/amplify_video/123/vid/avc1/720x1280/abc.mp4?tag=27')).toBe('video');
+        expect(classifyMediaUrl('https://pbs.twimg.com/media/AbCdEf.jpg')).toBe('image');
+        expect(classifyMediaUrl('https://example.com/clip.m3u8')).toBe('video');
+        expect(classifyMediaUrl(null)).toBe('unknown');
+    });
+
+    it('strictly validates profile download limit', () => {
+        expect(requireLimit(undefined)).toBe(10);
+        expect(requireLimit(1)).toBe(1);
+        for (const value of [0, -1, 1.5, 'abc', 1001]) {
+            expect(() => requireLimit(value)).toThrow(ArgumentError);
+        }
+    });
+
+    it('calculates profile media page sizes without silently clamping user input', () => {
+        expect(nextUserMediaFetchCount(1, 0)).toBe(11);
+        expect(nextUserMediaFetchCount(1000, 0)).toBe(100);
+        expect(nextUserMediaFetchCount(1000, 950)).toBe(60);
+        expect(nextUserMediaFetchCount(10, 10)).toBe(0);
+    });
+
+    it('extracts media urls and the bottom cursor from a UserMedia payload', () => {
+        const payload = {
+            data: {
+                user: {
+                    result: {
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [
+                                    {
+                                        entries: [
+                                            {
+                                                content: {
+                                                    itemContent: {
+                                                        tweet_results: {
+                                                            result: {
+                                                                rest_id: 'tweet-1',
+                                                                legacy: {
+                                                                    extended_entities: {
+                                                                        media: [
+                                                                            { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/IMG1.jpg' },
+                                                                            { type: 'video', video_info: { variants: [{ content_type: 'video/mp4', url: 'https://video.twimg.com/v/1.mp4' }] } },
+                                                                        ],
+                                                                    },
+                                                                },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                            {
+                                                content: {
+                                                    entryType: 'TimelineTimelineCursor',
+                                                    cursorType: 'Bottom',
+                                                    value: 'next-cursor-abc',
+                                                },
+                                            },
+                                        ],
+                                    },
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const seen = new Set();
+        const { items, nextCursor } = parseUserMedia(payload, seen);
+        expect(nextCursor).toBe('next-cursor-abc');
+        expect(items).toHaveLength(2);
+        expect(items[0]).toMatchObject({ tweet_id: 'tweet-1', url: 'https://pbs.twimg.com/media/IMG1.jpg', type: 'image' });
+        expect(items[1]).toMatchObject({ tweet_id: 'tweet-1', url: 'https://video.twimg.com/v/1.mp4', type: 'video' });
+        expect(seen.has('tweet-1')).toBe(true);
+    });
+
+    it('skips already-seen tweets across pages', () => {
+        const tweetEntry = (id) => ({
+            content: {
+                itemContent: {
+                    tweet_results: {
+                        result: {
+                            rest_id: id,
+                            legacy: {
+                                extended_entities: {
+                                    media: [{ type: 'photo', media_url_https: `https://pbs.twimg.com/media/${id}.jpg` }],
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        });
+        const payload = {
+            data: {
+                user: {
+                    result: {
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [{ entries: [tweetEntry('A'), tweetEntry('A'), tweetEntry('B')] }],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const seen = new Set();
+        const { items } = parseUserMedia(payload, seen);
+        expect(items.map((item) => item.tweet_id)).toEqual(['A', 'B']);
+    });
+
+    it('treats TweetWithVisibilityResults wrappers as tweets', () => {
+        const payload = {
+            data: {
+                user: {
+                    result: {
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [
+                                    {
+                                        entries: [
+                                            {
+                                                content: {
+                                                    itemContent: {
+                                                        tweet_results: {
+                                                            result: {
+                                                                __typename: 'TweetWithVisibilityResults',
+                                                                tweet: {
+                                                                    rest_id: 'wrapped-1',
+                                                                    legacy: {
+                                                                        extended_entities: {
+                                                                            media: [{ type: 'photo', media_url_https: 'https://pbs.twimg.com/media/W.jpg' }],
+                                                                        },
+                                                                    },
+                                                                },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        ],
+                                    },
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const { items } = parseUserMedia(payload, new Set());
+        expect(items).toHaveLength(1);
+        expect(items[0].tweet_id).toBe('wrapped-1');
+    });
+
+    it('fails typed when UserMedia payload has no timeline instructions', () => {
+        expect(() => parseUserMedia({ data: { user: { result: {} } } }, new Set()))
+            .toThrow(CommandExecutionError);
+    });
+
+    it('rejects missing, mixed, invalid username and invalid limit before navigation', async () => {
+        const cmd = getRegistry().get('twitter/download');
+        for (const args of [
+            {},
+            { username: 'jack', 'tweet-url': 'https://x.com/jack/status/123' },
+            { username: 'bad/name' },
+            { username: 'jack', limit: 0 },
+        ]) {
+            const page = createPageMock();
+            await expect(cmd.func(page, args)).rejects.toBeInstanceOf(ArgumentError);
+            expect(page.goto).not.toHaveBeenCalled();
+        }
+    });
+
+    it('downloads profile media through UserByScreenName and UserMedia GraphQL payloads', async () => {
+        const cmd = getRegistry().get('twitter/download');
+        mockDownloadMedia.mockResolvedValueOnce([
+            { index: 1, type: 'image', status: 'success', size: '1 KB' },
+            { index: 2, type: 'image', status: 'success', size: '2 KB' },
+        ]);
+        const page = createPageMock([
+            { queryId: 'UM', features: { a: true }, fieldToggles: {} },
+            { queryId: 'UB', features: {}, fieldToggles: {} },
+            userLookupPayload('42'),
+            userMediaPayload([
+                tweetEntry('A'),
+                {
+                    content: {
+                        entryType: 'TimelineTimelineCursor',
+                        cursorType: 'Bottom',
+                        value: 'cursor-1',
+                    },
+                },
+            ]),
+            userMediaPayload([tweetEntry('B')]),
+        ]);
+        const rows = await cmd.func(page, { username: '@jack', limit: 2, output: './out' });
+        expect(page.goto).toHaveBeenCalledWith('https://x.com/jack');
+        expect(page.evaluate).toHaveBeenCalledTimes(5);
+        expect(mockDownloadMedia).toHaveBeenCalledWith([
+            { tweet_id: 'A', url: 'https://pbs.twimg.com/media/A.jpg', type: 'image' },
+            { tweet_id: 'B', url: 'https://pbs.twimg.com/media/B.jpg', type: 'image' },
+        ], expect.objectContaining({
+            output: './out',
+            subdir: 'jack',
+            filenamePrefix: 'jack',
+            cookies: 'ct0=token',
+        }));
+        expect(rows).toEqual([
+            {
+                index: 1,
+                tweet_id: 'A',
+                url: 'https://pbs.twimg.com/media/A.jpg',
+                type: 'image',
+                status: 'success',
+                size: '1 KB',
+            },
+            {
+                index: 2,
+                tweet_id: 'B',
+                url: 'https://pbs.twimg.com/media/B.jpg',
+                type: 'image',
+                status: 'success',
+                size: '2 KB',
+            },
+        ]);
+    });
+
+    it('maps missing ct0 and GraphQL auth failures to AuthRequiredError', async () => {
+        const cmd = getRegistry().get('twitter/download');
+        const noCt0Page = createPageMock();
+        noCt0Page.getCookies.mockResolvedValueOnce([]);
+        await expect(cmd.func(noCt0Page, { username: 'jack', limit: 1 }))
+            .rejects.toBeInstanceOf(AuthRequiredError);
+
+        const authPage = createPageMock([
+            { queryId: 'UM', features: {}, fieldToggles: {} },
+            { queryId: 'UB', features: {}, fieldToggles: {} },
+            { ok: false, status: 401 },
+        ]);
+        await expect(cmd.func(authPage, { username: 'jack', limit: 1 }))
+            .rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('fails typed for malformed UserMedia and fetch failures instead of partial success', async () => {
+        const cmd = getRegistry().get('twitter/download');
+        const malformedPage = createPageMock([
+            { queryId: 'UM', features: {}, fieldToggles: {} },
+            { queryId: 'UB', features: {}, fieldToggles: {} },
+            userLookupPayload('42'),
+            { ok: true, payload: { data: { user: { result: {} } } } },
+        ]);
+        await expect(cmd.func(malformedPage, { username: 'jack', limit: 1 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+
+        const partialPage = createPageMock([
+            { queryId: 'UM', features: {}, fieldToggles: {} },
+            { queryId: 'UB', features: {}, fieldToggles: {} },
+            userLookupPayload('42'),
+            userMediaPayload([
+                tweetEntry('A'),
+                {
+                    content: {
+                        entryType: 'TimelineTimelineCursor',
+                        cursorType: 'Bottom',
+                        value: 'cursor-1',
+                    },
+                },
+            ]),
+            { ok: false, status: 500 },
+        ]);
+        await expect(cmd.func(partialPage, { username: 'jack', limit: 2 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        expect(mockDownloadMedia).not.toHaveBeenCalled();
+
+        const repeatedCursorPage = createPageMock([
+            { queryId: 'UM', features: {}, fieldToggles: {} },
+            { queryId: 'UB', features: {}, fieldToggles: {} },
+            userLookupPayload('42'),
+            userMediaPayload([
+                tweetEntry('A'),
+                {
+                    content: {
+                        entryType: 'TimelineTimelineCursor',
+                        cursorType: 'Bottom',
+                        value: 'cursor-1',
+                    },
+                },
+            ]),
+            userMediaPayload([
+                tweetEntry('B'),
+                {
+                    content: {
+                        entryType: 'TimelineTimelineCursor',
+                        cursorType: 'Bottom',
+                        value: 'cursor-1',
+                    },
+                },
+            ]),
+        ]);
+        await expect(cmd.func(repeatedCursorPage, { username: 'jack', limit: 3 }))
+            .rejects.toThrowError(/same cursor twice/);
+        expect(mockDownloadMedia).not.toHaveBeenCalled();
+    });
+
+    it('uses typed empty result for profile or tweet media absence', async () => {
+        const cmd = getRegistry().get('twitter/download');
+        const profilePage = createPageMock([
+            { queryId: 'UM', features: {}, fieldToggles: {} },
+            { queryId: 'UB', features: {}, fieldToggles: {} },
+            userLookupPayload('42'),
+            userMediaPayload([]),
+        ]);
+        await expect(cmd.func(profilePage, { username: 'jack', limit: 1 }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+
+        const tweetPage = createPageMock([[]]);
+        await expect(cmd.func(tweetPage, { 'tweet-url': 'https://x.com/jack/status/123' }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+    });
+});

package/clis/twitter/followers.js

@@ -1,4 +1,4 @@
-import { ArgumentError, AuthRequiredError, selectorError, EmptyResultError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError, selectorError, EmptyResultError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { normalizeTwitterScreenName, unwrapBrowserResult } from './shared.js';
 
@@ -161,7 +161,11 @@ cli({
         const seen = new Set();
         let sameCount = 0;
         while (allFollowers.length < limit && sameCount < 3) {
-            const followers = await extractFollowersFromDOM(page);
+            const rawFollowers = await extractFollowersFromDOM(page);
+            if (!Array.isArray(rawFollowers)) {
+                throw new CommandExecutionError('Twitter followers extraction returned malformed rows');
+            }
+            const followers = rawFollowers;
             const newFollowers = followers.filter(f => !seen.has(f.screen_name));
             for (const f of newFollowers) {
                 seen.add(f.screen_name);

package/clis/twitter/followers.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
-import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { __test__ } from './followers.js';
 
 describe('twitter followers command', () => {
@@ -41,4 +41,22 @@ describe('twitter followers command', () => {
         expect(page.goto).toHaveBeenCalledWith('https://x.com/home');
         expect(page.goto).not.toHaveBeenCalledWith('https://x.com/home/followers');
     });
+
+    it('typed-fails instead of throwing "filter is not a function" when extractFollowersFromDOM returns a non-array', async () => {
+        const command = getRegistry().get('twitter/followers');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            wait: vi.fn().mockResolvedValue(undefined),
+            autoScroll: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn(async (script) => {
+                const text = String(script);
+                if (text.includes('AppTabBar_Profile_Link')) return '/viewer';
+                if (text.includes('/followers') && text.includes('click')) return true;
+                if (text.includes('UserCell')) return undefined;
+                return undefined;
+            }),
+        };
+
+        await expect(command.func(page, { user: 'someone', limit: 5 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
 });

package/clis/twitter/following.js

@@ -1,10 +1,10 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
-import { normalizeTwitterScreenName, resolveTwitterQueryId, sanitizeQueryId, unwrapBrowserResult } from './shared.js';
+import { looksLikePrivateTwitterTimeline, normalizeTwitterScreenName, resolveTwitterQueryId, sanitizeQueryId, unwrapBrowserResult } from './shared.js';
 import { TWITTER_BEARER_TOKEN } from './utils.js';
 
-const FOLLOWING_QUERY_ID = 'zx6e-TLzRkeDO_a7p4b3JQ';  // Following fallback
-const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
+const FOLLOWING_QUERY_ID = 'F42cDX8PDFxkbjjq6JrM2w';
+const USER_BY_SCREEN_NAME_QUERY_ID = 'IGgvgiOx4QZndDHuD3x9TQ';
 const MAX_PAGINATION_PAGES = 100;
 
 const FEATURES = {
@@ -90,9 +90,13 @@ function extractUser(result) {
         return null;
     const core = result.core || {};
     const legacy = result.legacy || {};
+    const screenName = core.screen_name || legacy.screen_name || '';
+    if (!screenName) {
+        throw new CommandExecutionError('Malformed Twitter following user: missing screen_name');
+    }
     return {
-        screen_name: core.screen_name || legacy.screen_name || 'unknown',
-        name: core.name || legacy.name || 'unknown',
+        screen_name: screenName,
+        name: core.name || legacy.name || '',
         bio: legacy.description || result.profile_bio?.description || '',
         followers: legacy.followers_count || legacy.normal_followers_count || 0,
     };
@@ -221,6 +225,7 @@ cli({
         const allUsers = [];
         const seen = new Set();
         let cursor = null;
+        let lastRawResponse = null;
 
         // Runaway guard only; --limit and cursor exhaustion control normal pagination.
         for (let i = 0; i < MAX_PAGINATION_PAGES && allUsers.length < limit; i++) {
@@ -235,6 +240,7 @@ cli({
                     throw new AuthRequiredError('x.com', `Twitter following request failed (HTTP ${data.error})`);
                 throw new CommandExecutionError(`HTTP ${data.error}: Failed to fetch following list. queryId may have expired.`);
             }
+            lastRawResponse = data;
             const { users, nextCursor } = parseFollowing(data);
             for (const u of users) {
                 if (!seen.has(u.screen_name)) {
@@ -248,6 +254,9 @@ cli({
         }
 
         if (allUsers.length === 0) {
+            if (looksLikePrivateTwitterTimeline(lastRawResponse)) {
+                throw new EmptyResultError('twitter following', `No following data returned for @${targetUser} (the target account may have set their following list to private)`);
+            }
             throw new EmptyResultError('twitter following', `No following accounts found for @${targetUser}`);
         }
 

package/clis/twitter/following.test.js

@@ -53,6 +53,27 @@ describe('twitter following helpers', () => {
         expect(user?.screen_name).toBe('bob');
     });
 
+    it('typed-fails when upstream omits screen_name identity', () => {
+        expect(() => __test__.extractUser({
+            __typename: 'User',
+            legacy: { description: 'no names', followers_count: 7 },
+        })).toThrow(CommandExecutionError);
+    });
+
+    it('surfaces empty name display when upstream omits only name', () => {
+        const user = __test__.extractUser({
+            __typename: 'User',
+            core: { screen_name: 'alice' },
+            legacy: { description: 'no display name', followers_count: 7 },
+        });
+        expect(user).toMatchObject({
+            screen_name: 'alice',
+            name: '',
+            bio: 'no display name',
+            followers: 7,
+        });
+    });
+
     it('parses following timeline with users and cursor', () => {
         const payload = {
             data: {
@@ -327,4 +348,12 @@ describe('twitter following command', () => {
 
         await expect(command.func(page, { user: 'elonmusk', limit: 10 })).rejects.toBeInstanceOf(EmptyResultError);
     });
+
+    it('surfaces the private-following privacy hint when result.timeline is empty', async () => {
+        const command = getRegistry().get('twitter/following');
+        const page = createFollowingPage([{ data: { user: { result: { __typename: 'User', timeline: {} } } } }]);
+
+        await expect(command.func(page, { user: 'simonw', limit: 10 }))
+            .rejects.toMatchObject({ hint: expect.stringContaining('following list to private') });
+    });
 });

package/clis/twitter/likes.js

@@ -1,9 +1,9 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
-import { normalizeTwitterScreenName, resolveTwitterQueryId, sanitizeQueryId, extractMedia, unwrapBrowserResult } from './shared.js';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { looksLikePrivateTwitterTimeline, normalizeTwitterScreenName, resolveTwitterQueryId, sanitizeQueryId, extractMedia, unwrapBrowserResult } from './shared.js';
 import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
-const LIKES_QUERY_ID = 'RozQdCp4CilQzrcuU0NY5w';
-const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
+const LIKES_QUERY_ID = 'CDWHmpZeSdIJ3HGeRbNm0w';
+const USER_BY_SCREEN_NAME_QUERY_ID = 'IGgvgiOx4QZndDHuD3x9TQ';
 const MAX_PAGINATION_PAGES = 100;
 const FEATURES = {
     rweb_video_screen_enabled: false,
@@ -202,6 +202,7 @@ cli({
         const allTweets = [];
         const seen = new Set();
         let cursor = null;
+        let lastRawResponse = null;
         // Runaway guard only; --limit and cursor exhaustion control normal pagination.
         for (let i = 0; i < MAX_PAGINATION_PAGES && allTweets.length < limit; i++) {
             const fetchCount = Math.min(100, limit - allTweets.length + 10);
@@ -215,12 +216,19 @@ cli({
                     throw new CommandExecutionError(`HTTP ${data.error}: Failed to fetch likes. queryId may have expired.`);
                 break;
             }
+            lastRawResponse = data;
             const { tweets, nextCursor } = parseLikes(data, seen);
             allTweets.push(...tweets);
             if (!nextCursor || nextCursor === cursor)
                 break;
             cursor = nextCursor;
         }
+        if (allTweets.length === 0) {
+            if (looksLikePrivateTwitterTimeline(lastRawResponse)) {
+                throw new EmptyResultError('twitter likes', `No likes returned for @${username} (Likes are private by default on X; only the account owner can view their own likes)`);
+            }
+            throw new EmptyResultError('twitter likes', `No likes found for @${username}`);
+        }
         const trimmed = allTweets.slice(0, limit);
         return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     },