feat: support ranked tweet search

tests/commands.search.test.ts

@@ -82,8 +82,8 @@ describe('search command', () => {
     const searchSpy = vi.spyOn(TwitterClient.prototype, 'search').mockResolvedValue({ success: true, tweets: [] });
 
     try {
-      await program.parseAsync(['node', 'bird', 'search', 'cats', '--all', '--json']);
-      expect(getAllSpy).toHaveBeenCalledWith('cats', expect.objectContaining({ includeRaw: false }));
+      await program.parseAsync(['node', 'bird', 'search', 'cats', '--all', '--json', '--product', 'Top']);
+      expect(getAllSpy).toHaveBeenCalledWith('cats', expect.objectContaining({ includeRaw: false, product: 'Top' }));
       expect(searchSpy).not.toHaveBeenCalled();
       expect(mockContext.printTweetsResult).toHaveBeenCalledWith(expect.objectContaining({ tweets: [] }), {
         json: true,
@@ -96,6 +96,30 @@ describe('search command', () => {
     }
   });
 
+  it('passes --product to non-paged search', async () => {
+    registerSearchCommands(program, mockContext as CliContext);
+    const searchSpy = vi.spyOn(TwitterClient.prototype, 'search').mockResolvedValue({ success: true, tweets: [] });
+
+    try {
+      await program.parseAsync(['node', 'bird', 'search', 'cats', '--product', 'Top']);
+      expect(searchSpy).toHaveBeenCalledWith('cats', 10, {
+        includeRaw: false,
+        product: 'Top',
+      });
+    } finally {
+      searchSpy.mockRestore();
+    }
+  });
+
+  it('rejects unsupported search products', async () => {
+    program.exitOverride();
+    registerSearchCommands(program, mockContext as CliContext);
+
+    await expect(program.parseAsync(['node', 'bird', 'search', 'cats', '--product', 'Media'])).rejects.toMatchObject({
+      code: 'commander.invalidArgument',
+    });
+  });
+
   it('uses cursor pagination when --cursor is set', async () => {
     registerSearchCommands(program, mockContext as CliContext);
     const getAllSpy = vi

tests/library-exports.test.ts

@@ -1,8 +1,15 @@
 import { describe, expect, it } from 'vitest';
-import { TwitterClient } from '../src/index.js';
+import { type SearchFetchOptions, type SearchProduct, TwitterClient } from '../src/index.js';
 
 describe('library exports', () => {
   it('exposes primary library surface', () => {
     expect(typeof TwitterClient).toBe('function');
   });
+
+  it('exposes search product types', () => {
+    const product: SearchProduct = 'Top';
+    const options: SearchFetchOptions = { product };
+
+    expect(options.product).toBe('Top');
+  });
 });

tests/twitter-client.search-bookmarks.test.ts

@@ -83,8 +83,12 @@ describe('TwitterClient search', () => {
     expect(body.queryId).toBeDefined();
     const urlVars = new URL(url as string).searchParams.get('variables');
     expect(urlVars).toBeTruthy();
-    const parsed = JSON.parse(urlVars as string) as { rawQuery?: string };
+    const parsed = JSON.parse(urlVars as string) as {
+      rawQuery?: string;
+      product?: string;
+    };
     expect(parsed.rawQuery).toBe('needle');
+    expect(parsed.product).toBe('Latest');
   });
 
   it('refreshes query IDs when all search endpoints 404', async () => {
@@ -186,7 +190,7 @@ describe('TwitterClient search', () => {
       });
 
     const client = new TwitterClient({ relayBaseUrl: testRelayBaseUrl });
-    const result = await client.search('needle', 3);
+    const result = await client.search('needle', 3, { product: 'Top' });
 
     expect(result.success).toBe(true);
     expect(result.tweets?.map((tweet) => tweet.id)).toEqual(['1', '2', '3']);
@@ -194,13 +198,15 @@ describe('TwitterClient search', () => {
 
     const firstVars = JSON.parse(
       new URL(mockFetch.mock.calls[0][0] as string).searchParams.get('variables') as string,
-    ) as { cursor?: string };
+    ) as { cursor?: string; product?: string };
     const secondVars = JSON.parse(
       new URL(mockFetch.mock.calls[1][0] as string).searchParams.get('variables') as string,
-    ) as { cursor?: string };
+    ) as { cursor?: string; product?: string };
 
     expect(firstVars.cursor).toBeUndefined();
     expect(secondVars.cursor).toBe('cursor-1');
+    expect(firstVars.product).toBe('Top');
+    expect(secondVars.product).toBe('Top');
   });
 
   it('stops paginating when the cursor repeats', async () => {