feat: add pagination control to home timeline methods

[the-vampiire]

Summary

Adds cursor and maxPages options to getHomeTimeline() and getHomeLatestTimeline(), with nextCursor in the response.

New options in HomeTimelineFetchOptions:

• cursor?: string - Resume pagination from a saved position
• maxPages?: number - Limit number of pages fetched (returns nextCursor if more available)

Return value:

• nextCursor now included in SearchResult when more pages are available

Use Cases

• Resumable pagination: Save cursor, continue later from same position
• Rate-limited fetching: Fetch one page at a time with delays between calls
• Consistent API: Aligns with other paginated methods like getRepliesPaged

Example

// Fetch one page, get cursor for next
const page1 = await client.getHomeTimeline(20, { maxPages: 1 });
console.log(page1.tweets);  // First 20 tweets
console.log(page1.nextCursor);  // "abc123..."

// Later, resume from cursor
const page2 = await client.getHomeTimeline(20, { 
  cursor: page1.nextCursor,
  maxPages: 1 
});

Design Decision

This implementation uses an inline pagination loop rather than the existing paginateCursor() utility. The reasons:

1. Different semantics: Home timeline uses count-based fetching ("fetch N tweets total") while paginateCursor() is designed for simpler "fetch all matching items" scenarios
2. Consistency with similar methods: Follows the same pattern as getUserTweetsPaged(), getBookmarksPaged(), and getLikesPaged() which all use inline loops
3. Query ID refresh logic: Home timeline includes fetchWithRefresh() wrapper for handling 404s with query ID mismatches, which paginateCursor() doesn't support

Changes

• src/lib/twitter-client-home.ts: Add cursor/maxPages/nextCursor support
• tests/twitter-client.home-timeline.test.ts: Add 4 new pagination tests

Testing

All existing tests pass, plus 4 new tests covering:

• maxPages option respected
• cursor option for resuming
• nextCursor undefined when no more pages
• Works with getHomeLatestTimeline too

---

🤖 Generated with Claude Code