npm package: @rosid/threads-api
Description: Standalone Threads API library for fetching user data and threads
Latest version: 1.1.0

# Threads API

A standalone library for fetching data from Threads (threads.net).

## Installation

```bash
npm install @rosid/threads-api
```

or

```bash
bun add @rosid/threads-api
```

## Usage

```typescript
import { extractTokens, getUserId, fetchThreadsData, searchPosts } from '@rosid/threads-api';

// Extract LSD token
const { lsd } = await extractTokens('zuck');

// Get user ID (cached)
const userId = await getUserId('zuck');

// Fetch threads from a user's profile
const threads = await fetchThreadsData('zuck');

// Search for posts (with LSD token to avoid rate limits)
const { lsd } = await extractTokens('zuck');
const results = await searchPosts('threads', { lsd });
```

## API

### `extractTokens(user: string)`

Extract LSD token from a Threads profile page.

**Returns:** `Promise<{ lsd: string }>`

```typescript
const { lsd } = await extractTokens('zuck');
// { lsd: "token_value_here" }
```

---

### `getUserId(user: string)`

Get user ID from a Threads profile. Results are cached for 1 hour.

**Returns:** `Promise<string>`

```typescript
const userId = await getUserId('zuck');
// "1234567890"
```

---

### `fetchThreadsData(user: string)`

Fetch thread items from a user's profile page.

**Returns:** `Promise<ThreadItem[]>`

**ThreadItem Structure:**
```typescript
interface ThreadItem {
  post: {
    user?: {
      username: string;
      profile_pic_url: string;
    };
    taken_at: number;           // Unix timestamp
    code: string;               // Post code/ID
    caption?: {
      text: string;             // Post text content
    };
    text_post_app_info?: {
      share_info?: {
        quoted_post?: any;      // Quoted post data
        reposted_post?: any;    // Reposted post data
      };
      reply_to_author?: any;   // Reply information
    };
    image_versions2?: any;      // Image media data
    carousel_media?: any;       // Carousel/multiple images
    video_versions?: any;       // Video media data
  };
}
```

**Example:**
```typescript
const threads = await fetchThreadsData('zuck');
// [
//   {
//     post: {
//       user: {
//         username: "zuck",
//         profile_pic_url: "https://..."
//       },
//       taken_at: 1699123456,
//       code: "C1234567890",
//       caption: {
//         text: "Post content here..."
//       },
//       image_versions2: { ... },
//       // ... other media fields
//     }
//   },
//   // ... more threads
// ]
```

---

### `searchPosts(query: string, options?: SearchOptions)`

Search for posts on Threads by keyword.

**Parameters:**
- `query: string` - Search query/keyword
- `options?: SearchOptions` - Optional search parameters
  - `serp_type?: string` - Search result type (e.g., "default")
  - `filter?: 'recent' | 'profiles'` - Filter results by type
  - `lsd?: string` - LSD token (recommended to avoid rate limits)

**Returns:** `Promise<ThreadItem[]>` (same structure as `fetchThreadsData`)

**Examples:**
```typescript
// Basic search
const results = await searchPosts('threads');

// Search with serp_type
const results = await searchPosts('threads', { serp_type: 'default' });

// Search with filter
const recentResults = await searchPosts('threads', { filter: 'recent' });
const profileResults = await searchPosts('threads', { filter: 'profiles' });

// Search with both parameters
const results = await searchPosts('threads', { 
  serp_type: 'default', 
  filter: 'recent' 
});

// Search with LSD token (recommended to avoid rate limits)
const { lsd } = await extractTokens('zuck');
const results = await searchPosts('threads', { lsd });

// Search with all parameters including LSD token
const results = await searchPosts('threads', { 
  serp_type: 'default', 
  filter: 'recent',
  lsd 
});
```

## License

MIT