feat: add cursor-based pagination for following/followers commands
Add pagination support to `bird following` and `bird followers` commands, similar to existing pagination in search/bookmarks/likes. Changes: - Add `cursor` parameter to `getFollowing()` and `getFollowers()` client methods - Return `nextCursor` in `FollowingResult` for pagination continuation - Add `--cursor <cursor>` CLI option for manual pagination - Add `--all` CLI flag to automatically fetch all pages - Add `--max-pages <number>` option to limit pages when using --all - Add input validation for --max-pages (requires --all or --cursor) - Add deduplication using Set to prevent duplicate users - Add 1-second delay between pages to avoid overwhelming the API - Update `-n/--count` description to clarify it's per-page - Add unit tests for cursor parameter and nextCursor response Usage examples: # Fetch first page (default 20 users) bird following # Fetch with specific page size bird following -n 50 # Use cursor for next page bird following --cursor "CURSOR_FROM_PREVIOUS" # Fetch ALL following users automatically (with rate limiting) bird following --all --json # Limit to first 5 pages bird following --all --max-pages 5 # Same options work for followers bird followers --all Note: REST API fallback does not support cursor pagination. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
This commit is contained in:
Micah Alpern
committed by
Peter Steinberger
Peter Steinberger
co-authored by
Claude Opus 4.5
Claude Opus 4.5
parent
ad125348d6
commit
39a477265c
+239
-56
@@ -1,18 +1,41 @@
|
||||
import type { Command } from 'commander';
|
||||
import type { CliContext } from '../cli/shared.js';
|
||||
import { TwitterClient } from '../lib/twitter-client.js';
|
||||
import type { TwitterUser } from '../lib/twitter-client-types.js';
|
||||
|
||||
export function registerUserCommands(program: Command, ctx: CliContext): void {
|
||||
program
|
||||
.command('following')
|
||||
.description('Get users that you (or another user) follow')
|
||||
.option('--user <userId>', 'User ID to get following for (defaults to current user)')
|
||||
.option('-n, --count <number>', 'Number of users to fetch', '20')
|
||||
.option('-n, --count <number>', 'Number of users to fetch per page', '20')
|
||||
.option('--cursor <cursor>', 'Cursor for pagination (from previous response)')
|
||||
.option('--all', 'Fetch all users (paginate automatically)')
|
||||
.option('--max-pages <number>', 'Stop after N pages when using --all')
|
||||
.option('--json', 'Output as JSON')
|
||||
.action(async (cmdOpts: { user?: string; count?: string; json?: boolean }) => {
|
||||
const opts = program.opts();
|
||||
const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
|
||||
const count = Number.parseInt(cmdOpts.count || '20', 10);
|
||||
.action(
|
||||
async (cmdOpts: {
|
||||
user?: string;
|
||||
count?: string;
|
||||
cursor?: string;
|
||||
all?: boolean;
|
||||
maxPages?: string;
|
||||
json?: boolean;
|
||||
}) => {
|
||||
const opts = program.opts();
|
||||
const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
|
||||
const count = Number.parseInt(cmdOpts.count || '20', 10);
|
||||
const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
|
||||
|
||||
const usePagination = cmdOpts.all || cmdOpts.cursor;
|
||||
if (maxPages !== undefined && !usePagination) {
|
||||
console.error(`${ctx.p('err')}--max-pages requires --all or --cursor.`);
|
||||
process.exit(1);
|
||||
}
|
||||
if (maxPages !== undefined && (!Number.isFinite(maxPages) || maxPages <= 0)) {
|
||||
console.error(`${ctx.p('err')}Invalid --max-pages. Expected a positive integer.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
|
||||
|
||||
@@ -37,16 +60,58 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
|
||||
userId = currentUser.user.id;
|
||||
}
|
||||
|
||||
const result = await client.getFollowing(userId, count);
|
||||
if (cmdOpts.all) {
|
||||
// Fetch all pages
|
||||
const allUsers: TwitterUser[] = [];
|
||||
const seen = new Set<string>();
|
||||
let cursor: string | undefined = cmdOpts.cursor;
|
||||
let pageNum = 0;
|
||||
let nextCursor: string | undefined;
|
||||
|
||||
while (true) {
|
||||
pageNum++;
|
||||
if (!cmdOpts.json) {
|
||||
console.error(`${ctx.p('info')}Fetching page ${pageNum}...`);
|
||||
}
|
||||
|
||||
const result = await client.getFollowing(userId, count, cursor);
|
||||
|
||||
if (!result.success || !result.users) {
|
||||
console.error(`${ctx.p('err')}Failed to fetch following: ${result.error}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (result.success && result.users) {
|
||||
if (cmdOpts.json) {
|
||||
console.log(JSON.stringify(result.users, null, 2));
|
||||
} else {
|
||||
if (result.users.length === 0) {
|
||||
console.log('No users found.');
|
||||
} else {
|
||||
for (const user of result.users) {
|
||||
if (!seen.has(user.id)) {
|
||||
seen.add(user.id);
|
||||
allUsers.push(user);
|
||||
}
|
||||
}
|
||||
|
||||
if (!result.nextCursor || result.users.length === 0) {
|
||||
nextCursor = undefined;
|
||||
break;
|
||||
}
|
||||
|
||||
if (maxPages && pageNum >= maxPages) {
|
||||
nextCursor = result.nextCursor;
|
||||
break;
|
||||
}
|
||||
|
||||
cursor = result.nextCursor;
|
||||
|
||||
// Rate limit: wait between pages to avoid overwhelming the API
|
||||
await new Promise((resolve) => setTimeout(resolve, 1000));
|
||||
}
|
||||
|
||||
if (cmdOpts.json) {
|
||||
console.log(JSON.stringify(allUsers, null, 2));
|
||||
} else {
|
||||
console.error(`${ctx.p('info')}Total: ${allUsers.length} users`);
|
||||
if (nextCursor) {
|
||||
console.error(`${ctx.p('info')}Stopped at --max-pages. Use --cursor to continue.`);
|
||||
}
|
||||
for (const user of allUsers) {
|
||||
console.log(`@${user.username} (${user.name})`);
|
||||
if (user.description) {
|
||||
console.log(` ${user.description.slice(0, 100)}${user.description.length > 100 ? '...' : ''}`);
|
||||
@@ -57,57 +122,148 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
|
||||
console.log('──────────────────────────────────────────────────');
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// Single page fetch
|
||||
const result = await client.getFollowing(userId, count, cmdOpts.cursor);
|
||||
|
||||
if (result.success && result.users) {
|
||||
if (cmdOpts.json) {
|
||||
console.log(JSON.stringify({ users: result.users, nextCursor: result.nextCursor }, null, 2));
|
||||
} else {
|
||||
if (result.users.length === 0) {
|
||||
console.log('No users found.');
|
||||
} else {
|
||||
for (const user of result.users) {
|
||||
console.log(`@${user.username} (${user.name})`);
|
||||
if (user.description) {
|
||||
console.log(` ${user.description.slice(0, 100)}${user.description.length > 100 ? '...' : ''}`);
|
||||
}
|
||||
if (user.followersCount !== undefined) {
|
||||
console.log(` ${ctx.p('info')}${user.followersCount.toLocaleString()} followers`);
|
||||
}
|
||||
console.log('──────────────────────────────────────────────────');
|
||||
}
|
||||
if (result.nextCursor) {
|
||||
console.error(`${ctx.p('info')}Next cursor: ${result.nextCursor}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
} else {
|
||||
console.error(`${ctx.p('err')}Failed to fetch following: ${result.error}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
console.error(`${ctx.p('err')}Failed to fetch following: ${result.error}`);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
program
|
||||
.command('followers')
|
||||
.description('Get users that follow you (or another user)')
|
||||
.option('--user <userId>', 'User ID to get followers for (defaults to current user)')
|
||||
.option('-n, --count <number>', 'Number of users to fetch', '20')
|
||||
.option('-n, --count <number>', 'Number of users to fetch per page', '20')
|
||||
.option('--cursor <cursor>', 'Cursor for pagination (from previous response)')
|
||||
.option('--all', 'Fetch all users (paginate automatically)')
|
||||
.option('--max-pages <number>', 'Stop after N pages when using --all')
|
||||
.option('--json', 'Output as JSON')
|
||||
.action(async (cmdOpts: { user?: string; count?: string; json?: boolean }) => {
|
||||
const opts = program.opts();
|
||||
const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
|
||||
const count = Number.parseInt(cmdOpts.count || '20', 10);
|
||||
.action(
|
||||
async (cmdOpts: {
|
||||
user?: string;
|
||||
count?: string;
|
||||
cursor?: string;
|
||||
all?: boolean;
|
||||
maxPages?: string;
|
||||
json?: boolean;
|
||||
}) => {
|
||||
const opts = program.opts();
|
||||
const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
|
||||
const count = Number.parseInt(cmdOpts.count || '20', 10);
|
||||
const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
|
||||
|
||||
const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
|
||||
|
||||
for (const warning of warnings) {
|
||||
console.error(`${ctx.p('warn')}${warning}`);
|
||||
}
|
||||
|
||||
if (!cookies.authToken || !cookies.ct0) {
|
||||
console.error(`${ctx.p('err')}Missing required credentials`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const client = new TwitterClient({ cookies, timeoutMs });
|
||||
|
||||
let userId = cmdOpts.user;
|
||||
if (!userId) {
|
||||
const currentUser = await client.getCurrentUser();
|
||||
if (!currentUser.success || !currentUser.user?.id) {
|
||||
console.error(`${ctx.p('err')}Failed to get current user: ${currentUser.error || 'Unknown error'}`);
|
||||
const usePagination = cmdOpts.all || cmdOpts.cursor;
|
||||
if (maxPages !== undefined && !usePagination) {
|
||||
console.error(`${ctx.p('err')}--max-pages requires --all or --cursor.`);
|
||||
process.exit(1);
|
||||
}
|
||||
if (maxPages !== undefined && (!Number.isFinite(maxPages) || maxPages <= 0)) {
|
||||
console.error(`${ctx.p('err')}Invalid --max-pages. Expected a positive integer.`);
|
||||
process.exit(1);
|
||||
}
|
||||
userId = currentUser.user.id;
|
||||
}
|
||||
|
||||
const result = await client.getFollowers(userId, count);
|
||||
const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
|
||||
|
||||
for (const warning of warnings) {
|
||||
console.error(`${ctx.p('warn')}${warning}`);
|
||||
}
|
||||
|
||||
if (!cookies.authToken || !cookies.ct0) {
|
||||
console.error(`${ctx.p('err')}Missing required credentials`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const client = new TwitterClient({ cookies, timeoutMs });
|
||||
|
||||
let userId = cmdOpts.user;
|
||||
if (!userId) {
|
||||
const currentUser = await client.getCurrentUser();
|
||||
if (!currentUser.success || !currentUser.user?.id) {
|
||||
console.error(`${ctx.p('err')}Failed to get current user: ${currentUser.error || 'Unknown error'}`);
|
||||
process.exit(1);
|
||||
}
|
||||
userId = currentUser.user.id;
|
||||
}
|
||||
|
||||
if (cmdOpts.all) {
|
||||
// Fetch all pages
|
||||
const allUsers: TwitterUser[] = [];
|
||||
const seen = new Set<string>();
|
||||
let cursor: string | undefined = cmdOpts.cursor;
|
||||
let pageNum = 0;
|
||||
let nextCursor: string | undefined;
|
||||
|
||||
while (true) {
|
||||
pageNum++;
|
||||
if (!cmdOpts.json) {
|
||||
console.error(`${ctx.p('info')}Fetching page ${pageNum}...`);
|
||||
}
|
||||
|
||||
const result = await client.getFollowers(userId, count, cursor);
|
||||
|
||||
if (!result.success || !result.users) {
|
||||
console.error(`${ctx.p('err')}Failed to fetch followers: ${result.error}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (result.success && result.users) {
|
||||
if (cmdOpts.json) {
|
||||
console.log(JSON.stringify(result.users, null, 2));
|
||||
} else {
|
||||
if (result.users.length === 0) {
|
||||
console.log('No users found.');
|
||||
} else {
|
||||
for (const user of result.users) {
|
||||
if (!seen.has(user.id)) {
|
||||
seen.add(user.id);
|
||||
allUsers.push(user);
|
||||
}
|
||||
}
|
||||
|
||||
if (!result.nextCursor || result.users.length === 0) {
|
||||
nextCursor = undefined;
|
||||
break;
|
||||
}
|
||||
|
||||
if (maxPages && pageNum >= maxPages) {
|
||||
nextCursor = result.nextCursor;
|
||||
break;
|
||||
}
|
||||
|
||||
cursor = result.nextCursor;
|
||||
|
||||
// Rate limit: wait between pages to avoid overwhelming the API
|
||||
await new Promise((resolve) => setTimeout(resolve, 1000));
|
||||
}
|
||||
|
||||
if (cmdOpts.json) {
|
||||
console.log(JSON.stringify(allUsers, null, 2));
|
||||
} else {
|
||||
console.error(`${ctx.p('info')}Total: ${allUsers.length} users`);
|
||||
if (nextCursor) {
|
||||
console.error(`${ctx.p('info')}Stopped at --max-pages. Use --cursor to continue.`);
|
||||
}
|
||||
for (const user of allUsers) {
|
||||
console.log(`@${user.username} (${user.name})`);
|
||||
if (user.description) {
|
||||
console.log(` ${user.description.slice(0, 100)}${user.description.length > 100 ? '...' : ''}`);
|
||||
@@ -118,12 +274,39 @@ export function registerUserCommands(program: Command, ctx: CliContext): void {
|
||||
console.log('──────────────────────────────────────────────────');
|
||||
}
|
||||
}
|
||||
} else {
|
||||
// Single page fetch
|
||||
const result = await client.getFollowers(userId, count, cmdOpts.cursor);
|
||||
|
||||
if (result.success && result.users) {
|
||||
if (cmdOpts.json) {
|
||||
console.log(JSON.stringify({ users: result.users, nextCursor: result.nextCursor }, null, 2));
|
||||
} else {
|
||||
if (result.users.length === 0) {
|
||||
console.log('No users found.');
|
||||
} else {
|
||||
for (const user of result.users) {
|
||||
console.log(`@${user.username} (${user.name})`);
|
||||
if (user.description) {
|
||||
console.log(` ${user.description.slice(0, 100)}${user.description.length > 100 ? '...' : ''}`);
|
||||
}
|
||||
if (user.followersCount !== undefined) {
|
||||
console.log(` ${ctx.p('info')}${user.followersCount.toLocaleString()} followers`);
|
||||
}
|
||||
console.log('──────────────────────────────────────────────────');
|
||||
}
|
||||
if (result.nextCursor) {
|
||||
console.error(`${ctx.p('info')}Next cursor: ${result.nextCursor}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
} else {
|
||||
console.error(`${ctx.p('err')}Failed to fetch followers: ${result.error}`);
|
||||
process.exit(1);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
console.error(`${ctx.p('err')}Failed to fetch followers: ${result.error}`);
|
||||
process.exit(1);
|
||||
}
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
program
|
||||
.command('likes')
|
||||
|
||||
Reference in New Issue
Block a user