feat: add --json-full flag to include raw API response in _raw field

Add a new --json-full flag to tweet-fetching commands that outputs JSON
with an additional _raw field containing the full GraphQL response.

This provides power users access to additional data not exposed in the
curated TweetData interface (media, entities, hashtags, cards, etc.)
while maintaining backward compatibility with --json.

Supported commands:
- read, replies, thread (TweetDetail API)
- search, mentions (SearchTimeline API)
- bookmarks (Bookmarks API)
- likes (Likes API)

Not supported: following, followers (uses mixed GraphQL/REST fallback
with different response structures)

Implementation:
- Add _raw?: GraphqlTweetResult optional field to TweetData type
- Add includeRaw option to mapTweetResult() and parseTweetsFromInstructions()
- Add TweetFetchOptions, SearchFetchOptions, TimelineFetchOptions interfaces
- Update client methods to accept options parameter
- Add --json-full flag to CLI commands
- Update help text to document the new flag
- Add comprehensive test coverage (16 tests)

Co-authored-by: Christian Catalan <[email protected]>

src/lib/twitter-client-utils.ts

@@ -163,7 +163,19 @@ export function unwrapTweetResult(result: GraphqlTweetResult | undefined): Graph
   return result;
 }
 
-export function mapTweetResult(result: GraphqlTweetResult | undefined, quoteDepth: number): TweetData | undefined {
+export interface MapTweetResultOptions {
+  quoteDepth: number;
+  includeRaw?: boolean;
+}
+
+export function mapTweetResult(
+  result: GraphqlTweetResult | undefined,
+  quoteDepthOrOptions: number | MapTweetResultOptions,
+): TweetData | undefined {
+  const options: MapTweetResultOptions =
+    typeof quoteDepthOrOptions === 'number' ? { quoteDepth: quoteDepthOrOptions } : quoteDepthOrOptions;
+  const { quoteDepth, includeRaw = false } = options;
+
   const userResult = result?.core?.user_results?.result;
   const userLegacy = userResult?.legacy;
   const userCore = userResult?.core;
@@ -183,11 +195,11 @@ export function mapTweetResult(result: GraphqlTweetResult | undefined, quoteDept
   if (quoteDepth > 0) {
     const quotedResult = unwrapTweetResult(result.quoted_status_result?.result);
     if (quotedResult) {
-      quotedTweet = mapTweetResult(quotedResult, quoteDepth - 1);
+      quotedTweet = mapTweetResult(quotedResult, { quoteDepth: quoteDepth - 1, includeRaw });
     }
   }
 
-  return {
+  const tweetData: TweetData = {
     id: result.rest_id,
     text,
     createdAt: result.legacy?.created_at,
@@ -203,6 +215,12 @@ export function mapTweetResult(result: GraphqlTweetResult | undefined, quoteDept
     authorId: userId,
     quotedTweet,
   };
+
+  if (includeRaw) {
+    tweetData._raw = result;
+  }
+
+  return tweetData;
 }
 
 export function findTweetInInstructions(
@@ -294,6 +312,11 @@ export function collectTweetResultsFromEntry(entry: {
   return results;
 }
 
+export interface ParseTweetsOptions {
+  quoteDepth: number;
+  includeRaw?: boolean;
+}
+
 export function parseTweetsFromInstructions(
   instructions:
     | Array<{
@@ -336,8 +359,12 @@ export function parseTweetsFromInstructions(
         }>;
       }>
     | undefined,
-  quoteDepth: number,
+  quoteDepthOrOptions: number | ParseTweetsOptions,
 ): TweetData[] {
+  const options: ParseTweetsOptions =
+    typeof quoteDepthOrOptions === 'number' ? { quoteDepth: quoteDepthOrOptions } : quoteDepthOrOptions;
+  const { quoteDepth, includeRaw = false } = options;
+
   const tweets: TweetData[] = [];
   const seen = new Set<string>();
 
@@ -345,7 +372,7 @@ export function parseTweetsFromInstructions(
     for (const entry of instruction.entries ?? []) {
       const results = collectTweetResultsFromEntry(entry);
       for (const result of results) {
-        const mapped = mapTweetResult(result, quoteDepth);
+        const mapped = mapTweetResult(result, { quoteDepth, includeRaw });
         if (!mapped || seen.has(mapped.id)) {
           continue;
         }