@side-quest/x-api 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nathan Vale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,382 @@
+# bun-typescript-starter
+
+Modern TypeScript starter template with enterprise-grade tooling.
+
+## Features
+
+- **Bun** - Fast all-in-one JavaScript runtime and toolkit
+- **TypeScript 5.9+** - Strict mode, ESM only
+- **Biome** - Lightning-fast linting and formatting (replaces ESLint + Prettier)
+- **Vitest** - Fast unit testing with native Bun support
+- **Changesets** - Automated versioning and changelog generation
+- **GitHub Actions** - Comprehensive CI/CD with OIDC npm publishing
+- **Conventional Commits** - Enforced via commitlint + Husky
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) installed (`curl -fsSL https://bun.sh/install | bash`)
+- [GitHub CLI](https://cli.github.com) installed and authenticated (`gh auth login`)
+- [npm account](https://www.npmjs.com) with a granular access token (see [NPM Token Setup](#npm-token-setup))
+
+### Option A: GitHub CLI (Recommended)
+
+Create a new repo from this template and set it up in one command:
+
+```bash
+# Create repo from template
+gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
+
+# Run setup (interactive)
+cd my-lib
+bun run setup
+```
+
+### Option B: CLI Mode (Non-Interactive)
+
+For automated/scripted setups, pass all arguments via CLI flags:
+
+```bash
+# Create repo from template
+gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
+cd my-lib
+
+# Run setup with all arguments (no prompts)
+bun run setup -- \
+  --name "@myusername/my-lib" \
+  --description "My awesome library" \
+  --author "Your Name" \
+  --yes
+```
+
+### Option C: degit
+
+```bash
+npx degit nathanvale/bun-typescript-starter my-lib
+cd my-lib
+bun run setup
+```
+
+## Setup Script
+
+The setup script configures your project and optionally creates the GitHub repository with all settings pre-configured.
+
+### Interactive Mode
+
+```bash
+bun run setup
+```
+
+Prompts for:
+- Package name (e.g., `@myusername/my-lib` or `my-lib`)
+- Repository name
+- GitHub username/org
+- Project description
+- Author name
+
+### CLI Mode
+
+```bash
+bun run setup -- [options]
+```
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--name` | `-n` | Package name (e.g., `@myusername/my-lib`) |
+| `--repo` | `-r` | Repository name (defaults to package name) |
+| `--user` | `-u` | GitHub username/org (auto-detected from `gh`) |
+| `--description` | `-d` | Project description |
+| `--author` | `-a` | Author name |
+| `--yes` | `-y` | Skip confirmation prompts (auto-yes) |
+| `--no-github` | | Skip GitHub repo creation/configuration |
+| `--help` | `-h` | Show help |
+
+### What Setup Does
+
+1. **Configures files** - Replaces placeholders in `package.json` and `.changeset/config.json`
+2. **Installs dependencies** - Runs `bun install`
+3. **Creates initial commit** - Commits all configured files
+4. **Creates GitHub repo** (if it doesn't exist) - Uses `gh repo create`
+5. **Configures GitHub settings**:
+   - Enables workflow permissions for PR creation
+   - Sets squash-only merging
+   - Enables auto-delete branches
+   - Enables auto-merge
+   - Configures branch protection rules
+
+## Complete Setup Guide
+
+This guide walks through the full process of creating a new package and publishing it to npm.
+
+### Step 1: Create Repository
+
+```bash
+# Create and clone from template
+gh repo create myusername/my-lib --template nathanvale/bun-typescript-starter --public --clone
+cd my-lib
+```
+
+### Step 2: Run Setup
+
+```bash
+# Interactive mode
+bun run setup
+
+# Or non-interactive mode
+bun run setup -- \
+  --name "@myusername/my-lib" \
+  --description "My awesome library" \
+  --author "Your Name" \
+  --yes
+```
+
+### Step 3: Configure NPM Token
+
+Before publishing, you need to add your npm token to GitHub secrets.
+
+#### Create npm Granular Access Token
+
+1. Go to [npmjs.com](https://www.npmjs.com) → Access Tokens → Generate New Token → **Granular Access Token**
+
+2. Configure the token:
+   - **Token name:** `github-actions-publish` (or any name)
+   - **Expiration:** 90 days (maximum for granular tokens)
+   - **Packages and scopes:** Select "All packages" for new packages, or specific packages for existing ones
+   - **Permissions:** Read and write
+   - **IMPORTANT:** Check **"Bypass two-factor authentication for automation"**
+
+   > Without "Bypass 2FA", CI/CD publishing will fail with "Access token expired or revoked"
+
+3. Copy the token (starts with `npm_`)
+
+#### Add Token to GitHub Secrets
+
+```bash
+# If you have NPM_TOKEN in your environment
+echo "$NPM_TOKEN" | gh secret set NPM_TOKEN --repo myusername/my-lib
+
+# Or set it interactively
+gh secret set NPM_TOKEN --repo myusername/my-lib
+# Paste your token when prompted
+```
+
+### Step 4: Create Initial Release
+
+Create a changeset describing your initial release:
+
+```bash
+# Create a feature branch
+git checkout -b feat/initial-release
+
+# Create changeset file
+mkdir -p .changeset
+cat > .changeset/initial-release.md << 'EOF'
+---
+"@myusername/my-lib": minor
+---
+
+Initial release
+EOF
+
+# Commit and push
+git add .changeset/initial-release.md
+git commit -m "chore: add changeset for initial release"
+git push -u origin feat/initial-release
+
+# Create PR
+gh pr create --title "chore: add changeset for initial release" --body "Initial release"
+```
+
+### Step 5: Merge and Publish
+
+1. **Wait for CI checks** to pass on your PR
+2. **Merge the PR** - This triggers the changesets workflow
+3. **A "Version Packages" PR** will be automatically created
+4. **Merge the Version PR** - This triggers the publish workflow
+5. **Package is published to npm!**
+
+```bash
+# Check your package
+npm view @myusername/my-lib
+```
+
+### Step 6: Configure OIDC Trusted Publishing (Optional)
+
+After the first publish, you can enable token-free publishing via OIDC:
+
+1. Go to [npmjs.com](https://www.npmjs.com) → Your Package → Settings → Publishing Access
+2. Click "Add Trusted Publisher"
+3. Configure:
+   - **Owner:** Your GitHub username/org
+   - **Repository:** Your repo name
+   - **Workflow file:** `publish.yml`
+4. Save changes
+5. Optionally remove the `NPM_TOKEN` secret from GitHub
+
+Now future releases will publish automatically without any tokens!
+
+## NPM Token Setup
+
+### Why Granular Tokens?
+
+As of December 2024, npm has revoked all classic tokens. You must use **granular access tokens** for CI/CD publishing.
+
+### Token Requirements
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| Type | Granular Access Token | Classic tokens no longer work |
+| Packages | All packages (for new) or specific | Allows publishing |
+| Permissions | Read and write | Required to publish |
+| **Bypass 2FA** | **Checked** | **Required for CI/CD** |
+
+### Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Access token expired or revoked" | Token doesn't have "Bypass 2FA" | Create new token with 2FA bypass |
+| "E404 Not Found" | Token doesn't have publish permissions | Check token has read/write access |
+| "E403 Forbidden" | Package scope mismatch | Ensure token covers your package scope |
+
+## What's Included
+
+### CI/CD Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `pr-quality.yml` | PR | Lint, Typecheck, Test with coverage |
+| `publish.yml` | Push to main | Auto-publish via Changesets |
+| `commitlint.yml` | PR | Enforce conventional commits |
+| `pr-title.yml` | PR | Validate PR title format |
+| `security.yml` | Push/Schedule | CodeQL + Trivy scanning |
+| `dependency-review.yml` | PR | Supply chain security |
+| `dependabot-auto-merge.yml` | Dependabot PR | Auto-merge patch updates |
+
+### Scripts
+
+```bash
+# Development
+bun dev              # Watch mode
+bun run build        # Build for production
+bun run clean        # Remove dist/
+
+# Quality
+bun run check        # Biome lint + format (write)
+bun run lint         # Lint only
+bun run format       # Format only
+bun run typecheck    # TypeScript type check
+bun run validate     # Full quality check (lint + types + build + test)
+
+# Testing
+bun test             # Run tests
+bun test --watch     # Watch mode
+bun run coverage     # With coverage report
+
+# Publishing
+bun run version:gen  # Create changeset interactively
+bun run release      # Publish to npm (CI handles this)
+```
+
+## Project Structure
+
+```
+├── .github/
+│   ├── workflows/        # CI/CD workflows
+│   ├── actions/          # Reusable composite actions
+│   └── scripts/          # CI helper scripts
+├── .husky/               # Git hooks
+├── .changeset/           # Changeset config
+├── src/
+│   └── index.ts          # Main entry point
+├── tests/
+│   └── index.test.ts     # Example test
+├── biome.json            # Biome config
+├── tsconfig.json         # TypeScript config
+├── bunup.config.ts       # Build config
+└── package.json
+```
+
+## Configuration
+
+### Biome
+
+Configured in `biome.json`:
+- Tab indentation
+- 80 character line width
+- Single quotes
+- Organize imports on save
+
+### TypeScript
+
+- Strict mode enabled
+- ESM output
+- Source maps and declarations
+
+### Changesets
+
+- GitHub changelog format
+- Public npm access
+- Provenance enabled
+
+## Branch Protection
+
+The setup script automatically configures branch protection for `main`:
+
+- Require pull request before merging
+- Require status checks to pass ("All checks passed")
+- Require linear history
+- No force pushes
+- No deletions
+
+If you need to manually configure it:
+
+1. Go to Settings → Branches → Add rule
+2. Branch name pattern: `main`
+3. Enable the settings above
+
+## Troubleshooting
+
+### Setup script hangs
+
+If running in a non-TTY environment (like some CI systems), use CLI flags:
+
+```bash
+bun run setup -- --name "my-lib" --description "desc" --author "name" --yes
+```
+
+### CI can't create PRs
+
+The setup script enables this automatically. If you need to do it manually:
+
+```bash
+gh api repos/OWNER/REPO/actions/permissions/workflow \
+  --method PUT \
+  -f default_workflow_permissions=write \
+  -F can_approve_pull_request_reviews=true
+```
+
+### Version PR checks don't run
+
+Bot-created PRs don't trigger workflows. Push an empty commit:
+
+```bash
+git fetch origin
+git checkout changeset-release/main
+git commit --allow-empty -m "chore: trigger CI"
+git push
+```
+
+### npm publish fails with 404
+
+1. Ensure your npm token has "Bypass 2FA" checked
+2. Ensure token has "Read and write" permissions
+3. Ensure token covers "All packages" (for new packages)
+
+## License
+
+MIT
+
+---
+
+Built with [bun-typescript-starter](https://github.com/nathanvale/bun-typescript-starter)

package/dist/mcp/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env bun
+// @bun
+import {
+  createCorrelationId,
+  createXApiClient,
+  formatReplies,
+  formatSearch,
+  formatThread,
+  formatTimeline,
+  formatTweet,
+  formatUser,
+  initLogger,
+  logger
+} from "../shared/chunk-219wrwgz.js";
+
+// mcp/index.ts
+import { startServer, tool, z } from "@side-quest/core/mcp";
+import {
+  createLoggerAdapter,
+  setMcpLogger,
+  wrapToolHandler
+} from "@side-quest/core/mcp-response";
+await initLogger();
+var logAdapter = createLoggerAdapter(logger);
+setMcpLogger(logAdapter);
+var bearerToken = process.env.X_BEARER_TOKEN;
+if (!bearerToken) {
+  console.error("X_BEARER_TOKEN environment variable is required");
+  process.exit(1);
+}
+var client = createXApiClient({ bearerToken });
+var responseFormatSchema = z.enum(["markdown", "json"]).optional().default("json").describe("Output format: 'markdown' or 'json' (default)");
+var readOnlyAnnotations = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var handlerOpts = (toolName) => ({
+  toolName,
+  logger: logAdapter,
+  createCid: createCorrelationId
+});
+tool("x_get_tweet", {
+  description: "Get a single tweet by ID with author info and engagement metrics",
+  inputSchema: {
+    tweet_id: z.string().describe("The tweet/post ID"),
+    response_format: responseFormatSchema
+  },
+  annotations: readOnlyAnnotations
+}, wrapToolHandler(async (args, format) => {
+  const result = await client.getTweet(args.tweet_id);
+  return formatTweet(result, format);
+}, handlerOpts("x_get_tweet")));
+tool("x_get_thread", {
+  description: "Get a full conversation thread starting from a tweet ID. Uses search API (7-day window). Returns tweets in chronological reading order.",
+  inputSchema: {
+    tweet_id: z.string().describe("The root tweet/post ID"),
+    max_results: z.number().int().min(1).max(200).optional().default(50).describe("Maximum conversation tweets to fetch (default 50, max 200)"),
+    response_format: responseFormatSchema
+  },
+  annotations: readOnlyAnnotations
+}, wrapToolHandler(async (args, format) => {
+  const result = await client.getThread(args.tweet_id, args.max_results ?? 50);
+  return formatThread(result, format);
+}, handlerOpts("x_get_thread")));
+tool("x_get_timeline", {
+  description: "Get a user's recent tweets by username",
+  inputSchema: {
+    username: z.string().describe("Twitter username (without @ prefix)"),
+    max_results: z.number().int().min(1).max(100).optional().default(10).describe("Number of tweets to fetch (default 10, max 100)"),
+    response_format: responseFormatSchema
+  },
+  annotations: readOnlyAnnotations
+}, wrapToolHandler(async (args, format) => {
+  const result = await client.getTimeline(args.username, args.max_results ?? 10);
+  return formatTimeline(result, format);
+}, handlerOpts("x_get_timeline")));
+tool("x_search", {
+  description: "Search recent tweets (7-day window). Uses Twitter search API \u2014 may require elevated API tier.",
+  inputSchema: {
+    query: z.string().describe("Search query (supports Twitter search operators)"),
+    max_results: z.number().int().min(10).max(100).optional().default(10).describe("Number of results to return (default 10, max 100)"),
+    response_format: responseFormatSchema
+  },
+  annotations: readOnlyAnnotations
+}, wrapToolHandler(async (args, format) => {
+  const result = await client.searchRecent(args.query, args.max_results ?? 10);
+  return formatSearch(result, format);
+}, handlerOpts("x_get_search")));
+tool("x_get_user", {
+  description: "Get a Twitter/X user profile by username \u2014 bio, follower counts, tweet count",
+  inputSchema: {
+    username: z.string().describe("Twitter username (without @ prefix)"),
+    response_format: responseFormatSchema
+  },
+  annotations: readOnlyAnnotations
+}, wrapToolHandler(async (args, format) => {
+  const result = await client.getUser(args.username);
+  return formatUser(result, format);
+}, handlerOpts("x_get_user")));
+tool("x_get_replies", {
+  description: "Get direct replies to a tweet. Uses search API (7-day window) \u2014 may require elevated API tier.",
+  inputSchema: {
+    tweet_id: z.string().describe("The tweet/post ID to get replies for"),
+    max_results: z.number().int().min(10).max(100).optional().default(20).describe("Maximum replies to fetch (default 20, max 100)"),
+    response_format: responseFormatSchema
+  },
+  annotations: readOnlyAnnotations
+}, wrapToolHandler(async (args, format) => {
+  const result = await client.getReplies(args.tweet_id, args.max_results ?? 20);
+  return formatReplies(result, format);
+}, handlerOpts("x_get_replies")));
+startServer("x-api", {
+  version: "1.0.0",
+  fileLogging: {
+    enabled: true,
+    subsystems: ["mcp"],
+    level: "info"
+  }
+});

package/dist/shared/chunk-219wrwgz.js

@@ -0,0 +1,357 @@
+// @bun
+// src/includes.ts
+function buildMaps(includes) {
+  const userMap = new Map(includes?.users?.map((u) => [u.id, u]));
+  const tweetMap = new Map(includes?.tweets?.map((t) => [t.id, t]));
+  return { userMap, tweetMap };
+}
+function enrichTweet(tweet, userMap, tweetMap) {
+  return {
+    ...tweet,
+    author: tweet.author_id ? userMap.get(tweet.author_id) : undefined,
+    referenced_tweet_data: tweet.referenced_tweets?.[0] ? tweetMap.get(tweet.referenced_tweets[0].id) : undefined
+  };
+}
+function mergeSingleTweet(response) {
+  const { userMap, tweetMap } = buildMaps(response.includes);
+  return enrichTweet(response.data, userMap, tweetMap);
+}
+function mergeTweetList(response) {
+  if (!response.data)
+    return [];
+  const { userMap, tweetMap } = buildMaps(response.includes);
+  return response.data.map((tweet) => enrichTweet(tweet, userMap, tweetMap));
+}
+
+// src/logger.ts
+import { createPluginLogger } from "@side-quest/core/logging";
+var { initLogger, getSubsystemLogger, createCorrelationId } = createPluginLogger({
+  name: "x-api",
+  subsystems: ["mcp"]
+});
+var logger = getSubsystemLogger("mcp");
+
+// src/thread.ts
+var SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+var MAX_THREAD_TWEETS = 200;
+async function buildThread(request, tweetId, maxResults, fields) {
+  const cap = Math.min(maxResults, MAX_THREAD_TWEETS);
+  const rootParams = new URLSearchParams({
+    "tweet.fields": fields.tweetFields,
+    expansions: fields.expansions,
+    "user.fields": fields.userFields
+  });
+  const rootResponse = await request(`/tweets/${tweetId}`, rootParams);
+  const rootTweet = mergeSingleTweet(rootResponse);
+  const conversationId = rootResponse.data.conversation_id ?? rootResponse.data.id;
+  let ageWarning;
+  if (rootResponse.data.created_at) {
+    const tweetAge = Date.now() - new Date(rootResponse.data.created_at).getTime();
+    if (tweetAge > SEVEN_DAYS_MS) {
+      ageWarning = "Warning: Tweet is older than 7 days. Search API only returns recent replies.";
+    }
+  }
+  const allTweets = [rootTweet];
+  const seenIds = new Set([tweetId]);
+  let nextToken;
+  let fetched = 0;
+  while (fetched < cap) {
+    const pageSize = Math.min(100, cap - fetched);
+    const params = new URLSearchParams({
+      query: `conversation_id:${conversationId}`,
+      max_results: String(Math.max(pageSize, 10)),
+      "tweet.fields": fields.tweetFields,
+      expansions: fields.expansions,
+      "user.fields": fields.userFields
+    });
+    if (nextToken)
+      params.set("next_token", nextToken);
+    const page = await request("/tweets/search/recent", params);
+    if (page.data) {
+      const enriched = mergeTweetList(page);
+      for (const tweet of enriched) {
+        if (!seenIds.has(tweet.id)) {
+          seenIds.add(tweet.id);
+          allTweets.push(tweet);
+          fetched++;
+        }
+      }
+    }
+    nextToken = page.meta?.next_token;
+    if (!nextToken || !page.data?.length)
+      break;
+  }
+  allTweets.sort((a, b) => {
+    if (!a.created_at || !b.created_at)
+      return 0;
+    return new Date(a.created_at).getTime() - new Date(b.created_at).getTime();
+  });
+  return { tweets: allTweets, ageWarning };
+}
+
+// src/client.ts
+import { TimeoutError, withTimeout } from "@side-quest/core/concurrency";
+import { getErrorCategory } from "@side-quest/core/instrumentation";
+import { createCorrelationId as createCorrelationId2 } from "@side-quest/core/logging";
+import { retry } from "@side-quest/core/utils";
+var BASE_URL = "https://api.twitter.com/2";
+var TWEET_FIELDS = "author_id,conversation_id,created_at,in_reply_to_user_id,public_metrics,referenced_tweets";
+var TWEET_EXPANSIONS = "author_id,referenced_tweets.id";
+var USER_FIELDS = "created_at,description,profile_image_url,public_metrics,verified";
+
+class TwitterApiError extends Error {
+  status;
+  category;
+  constructor(message, status, category) {
+    super(message);
+    this.status = status;
+    this.category = category;
+    this.name = "TwitterApiError";
+  }
+}
+function parseTwitterError(status, body) {
+  let detail;
+  try {
+    const parsed = JSON.parse(body);
+    detail = parsed?.detail ?? parsed?.errors?.[0]?.message ?? body;
+  } catch {
+    detail = body;
+  }
+  if (status === 429)
+    return new TwitterApiError(`Rate limited: ${detail}`, status, "transient");
+  if (status === 401)
+    return new TwitterApiError(`Auth failed: ${detail}`, status, "configuration");
+  if (status === 403)
+    return new TwitterApiError(`Forbidden: ${detail} (check API tier)`, status, "configuration");
+  if (status === 404)
+    return new TwitterApiError(`Not found: ${detail}`, status, "permanent");
+  if (status >= 500)
+    return new TwitterApiError(`Server error ${status}: ${detail}`, status, "transient");
+  return new TwitterApiError(`API error ${status}: ${detail}`, status, "permanent");
+}
+function createXApiClient(config) {
+  const { bearerToken, fetchFn = fetch, timeoutMs = 1e4 } = config;
+  async function request(endpoint, params) {
+    const cid = createCorrelationId2();
+    const url = params ? `${BASE_URL}${endpoint}?${params}` : `${BASE_URL}${endpoint}`;
+    logger.info`x-api:request:start cid=${cid} endpoint=${endpoint}`;
+    const result = await retry(async () => {
+      const response = await withTimeout(fetchFn(url, {
+        headers: { Authorization: `Bearer ${bearerToken}` }
+      }), timeoutMs, `Twitter API timeout: ${endpoint}`);
+      const remaining = response.headers.get("x-rate-limit-remaining");
+      const reset = response.headers.get("x-rate-limit-reset");
+      if (remaining && Number(remaining) < 3) {
+        logger.warn`x-api:rateLimit:low cid=${cid} remaining=${remaining} resetAt=${reset}`;
+      }
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw parseTwitterError(response.status, errorBody);
+      }
+      return response.json();
+    }, {
+      maxAttempts: 3,
+      initialDelay: 1000,
+      shouldRetry: (error) => {
+        if (error instanceof TimeoutError)
+          return true;
+        if (error instanceof TwitterApiError)
+          return error.category === "transient";
+        return getErrorCategory(error) === "transient";
+      }
+    });
+    logger.info`x-api:request:complete cid=${cid} endpoint=${endpoint}`;
+    return result;
+  }
+  function defaultTweetParams() {
+    return new URLSearchParams({
+      "tweet.fields": TWEET_FIELDS,
+      expansions: TWEET_EXPANSIONS,
+      "user.fields": USER_FIELDS
+    });
+  }
+  function defaultUserParams() {
+    return new URLSearchParams({
+      "user.fields": USER_FIELDS
+    });
+  }
+  return {
+    async getTweet(id) {
+      const response = await request(`/tweets/${id}`, defaultTweetParams());
+      return mergeSingleTweet(response);
+    },
+    async getThread(tweetId, maxResults) {
+      return buildThread(request, tweetId, maxResults, {
+        tweetFields: TWEET_FIELDS,
+        expansions: TWEET_EXPANSIONS,
+        userFields: USER_FIELDS
+      });
+    },
+    async getTimeline(username, maxResults) {
+      const userResponse = await request(`/users/by/username/${username}`, defaultUserParams());
+      const params = defaultTweetParams();
+      params.set("max_results", String(Math.min(maxResults, 100)));
+      const timeline = await request(`/users/${userResponse.data.id}/tweets`, params);
+      return {
+        user: userResponse.data,
+        tweets: mergeTweetList(timeline)
+      };
+    },
+    async searchRecent(query, maxResults) {
+      const params = defaultTweetParams();
+      params.set("query", query);
+      params.set("max_results", String(Math.min(maxResults, 100)));
+      const response = await request("/tweets/search/recent", params);
+      return {
+        query,
+        tweets: mergeTweetList(response),
+        resultCount: response.meta?.result_count ?? 0
+      };
+    },
+    async getUser(username) {
+      const response = await request(`/users/by/username/${username}`, defaultUserParams());
+      return response.data;
+    },
+    async getReplies(tweetId, maxResults) {
+      const original = await request(`/tweets/${tweetId}`, defaultTweetParams());
+      const enrichedOriginal = mergeSingleTweet(original);
+      const conversationId = original.data.conversation_id ?? original.data.id;
+      const params = defaultTweetParams();
+      params.set("query", `conversation_id:${conversationId} in_reply_to_tweet_id:${tweetId}`);
+      params.set("max_results", String(Math.min(maxResults, 100)));
+      const response = await request("/tweets/search/recent", params);
+      return {
+        originalTweet: enrichedOriginal,
+        replies: mergeTweetList(response),
+        resultCount: response.meta?.result_count ?? 0
+      };
+    }
+  };
+}
+
+// src/formatters.ts
+import { ResponseFormat } from "@side-quest/core/mcp-response";
+function formatTweetMarkdown(tweet) {
+  const lines = [];
+  const author = tweet.author;
+  if (author) {
+    lines.push(`**@${author.username}** (${author.name})`);
+  }
+  lines.push(tweet.text);
+  if (tweet.created_at) {
+    lines.push(`*${new Date(tweet.created_at).toLocaleString()}*`);
+  }
+  const m = tweet.public_metrics;
+  if (m) {
+    const parts = [];
+    if (m.like_count > 0)
+      parts.push(`${m.like_count} likes`);
+    if (m.retweet_count > 0)
+      parts.push(`${m.retweet_count} retweets`);
+    if (m.reply_count > 0)
+      parts.push(`${m.reply_count} replies`);
+    if (m.quote_count > 0)
+      parts.push(`${m.quote_count} quotes`);
+    if (parts.length > 0)
+      lines.push(parts.join(" | "));
+  }
+  return lines.join(`
+`);
+}
+function formatTweet(tweet, format) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify(tweet, null, 2);
+  }
+  return formatTweetMarkdown(tweet);
+}
+function formatThread(result, format) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  if (result.ageWarning) {
+    lines.push(`> ${result.ageWarning}`);
+    lines.push("");
+  }
+  lines.push(`**Thread** (${result.tweets.length} tweets)`);
+  lines.push("---");
+  for (const tweet of result.tweets) {
+    lines.push(formatTweetMarkdown(tweet));
+    lines.push("---");
+  }
+  return lines.join(`
+`);
+}
+function formatTimeline(result, format) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  const u = result.user;
+  lines.push(`**@${u.username}** (${u.name})`);
+  if (u.description)
+    lines.push(u.description);
+  if (u.public_metrics) {
+    lines.push(`${u.public_metrics.followers_count} followers | ${u.public_metrics.following_count} following | ${u.public_metrics.tweet_count} tweets`);
+  }
+  lines.push("");
+  lines.push(`**Recent tweets** (${result.tweets.length})`);
+  lines.push("---");
+  for (const tweet of result.tweets) {
+    lines.push(formatTweetMarkdown(tweet));
+    lines.push("---");
+  }
+  return lines.join(`
+`);
+}
+function formatSearch(result, format) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  lines.push(`**Search:** "${result.query}" (${result.resultCount} results)`);
+  lines.push("---");
+  for (const tweet of result.tweets) {
+    lines.push(formatTweetMarkdown(tweet));
+    lines.push("---");
+  }
+  return lines.join(`
+`);
+}
+function formatUser(user, format) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify(user, null, 2);
+  }
+  const lines = [];
+  lines.push(`**@${user.username}** (${user.name})`);
+  if (user.description)
+    lines.push(user.description);
+  if (user.created_at) {
+    lines.push(`Joined: ${new Date(user.created_at).toLocaleDateString()}`);
+  }
+  if (user.public_metrics) {
+    const m = user.public_metrics;
+    lines.push(`${m.followers_count} followers | ${m.following_count} following | ${m.tweet_count} tweets`);
+  }
+  return lines.join(`
+`);
+}
+function formatReplies(result, format) {
+  if (format === ResponseFormat.JSON) {
+    return JSON.stringify(result, null, 2);
+  }
+  const lines = [];
+  lines.push("**Original tweet:**");
+  lines.push(formatTweetMarkdown(result.originalTweet));
+  lines.push("");
+  lines.push(`**Replies** (${result.resultCount})`);
+  lines.push("---");
+  for (const reply of result.replies) {
+    lines.push(formatTweetMarkdown(reply));
+    lines.push("---");
+  }
+  return lines.join(`
+`);
+}
+
+export { mergeSingleTweet, mergeTweetList, initLogger, createCorrelationId, logger, buildThread, TwitterApiError, createXApiClient, formatTweet, formatThread, formatTimeline, formatSearch, formatUser, formatReplies };

package/dist/src/index.d.ts

@@ -0,0 +1,151 @@
+/**
+* Twitter/X API v2 types.
+*
+* Covers tweet, user, and includes structures returned by the v2 endpoints.
+* Only models the fields we actually request via tweet.fields / user.fields.
+*/
+interface Tweet {
+	id: string;
+	text: string;
+	author_id?: string;
+	conversation_id?: string;
+	created_at?: string;
+	in_reply_to_user_id?: string;
+	referenced_tweets?: ReferencedTweet[];
+	public_metrics?: TweetPublicMetrics;
+}
+interface ReferencedTweet {
+	type: "retweeted" | "quoted" | "replied_to";
+	id: string;
+}
+interface TweetPublicMetrics {
+	retweet_count: number;
+	reply_count: number;
+	like_count: number;
+	quote_count: number;
+	bookmark_count?: number;
+	impression_count?: number;
+}
+interface User {
+	id: string;
+	name: string;
+	username: string;
+	description?: string;
+	created_at?: string;
+	profile_image_url?: string;
+	verified?: boolean;
+	public_metrics?: UserPublicMetrics;
+}
+interface UserPublicMetrics {
+	followers_count: number;
+	following_count: number;
+	tweet_count: number;
+	listed_count: number;
+}
+interface TwitterIncludes {
+	users?: User[];
+	tweets?: Tweet[];
+}
+interface TwitterV2Response<T> {
+	data: T;
+	includes?: TwitterIncludes;
+}
+interface TwitterV2ListResponse<T> {
+	data?: T[];
+	includes?: TwitterIncludes;
+	meta?: TwitterMeta;
+}
+interface TwitterMeta {
+	result_count: number;
+	newest_id?: string;
+	oldest_id?: string;
+	next_token?: string;
+}
+interface EnrichedTweet extends Tweet {
+	author?: User;
+	referenced_tweet_data?: Tweet;
+}
+interface ThreadResult {
+	tweets: EnrichedTweet[];
+	ageWarning?: string;
+}
+interface TimelineResult {
+	user: User;
+	tweets: EnrichedTweet[];
+}
+interface SearchResult {
+	query: string;
+	tweets: EnrichedTweet[];
+	resultCount: number;
+}
+interface RepliesResult {
+	originalTweet: EnrichedTweet;
+	replies: EnrichedTweet[];
+	resultCount: number;
+}
+declare class TwitterApiError extends Error {
+	readonly status: number;
+	readonly category: "transient" | "permanent" | "configuration";
+	constructor(message: string, status: number, category: "transient" | "permanent" | "configuration");
+}
+interface XApiClientConfig {
+	bearerToken: string;
+	/** Injectable fetch for testing — no global mock needed */
+	fetchFn?: typeof fetch;
+	/** Request timeout in ms (default: 10_000) */
+	timeoutMs?: number;
+}
+/** Create a Twitter/X API v2 client with retry, timeout, and rate limit awareness. */
+declare function createXApiClient(config: XApiClientConfig): {
+	/** Fetch a single tweet by ID with author and metrics. */
+	getTweet(id: string): Promise<EnrichedTweet>;
+	/** Reconstruct a conversation thread with pagination. */
+	getThread(tweetId: string, maxResults: number): Promise<ThreadResult>;
+	/** Fetch a user's recent tweets. */
+	getTimeline(username: string, maxResults: number): Promise<TimelineResult>;
+	/** Search recent tweets (7-day window). */
+	searchRecent(query: string, maxResults: number): Promise<SearchResult>;
+	/** Fetch a user profile by username. */
+	getUser(username: string): Promise<User>;
+	/** Fetch direct replies to a tweet. */
+	getReplies(tweetId: string, maxResults: number): Promise<RepliesResult>;
+};
+type XApiClient = ReturnType<typeof createXApiClient>;
+import { ResponseFormat } from "@side-quest/core/mcp-response";
+/** Format a single enriched tweet result. */
+declare function formatTweet(tweet: EnrichedTweet, format: ResponseFormat): string;
+/** Format a thread result. */
+declare function formatThread(result: ThreadResult, format: ResponseFormat): string;
+/** Format a timeline result. */
+declare function formatTimeline(result: TimelineResult, format: ResponseFormat): string;
+/** Format a search result. */
+declare function formatSearch(result: SearchResult, format: ResponseFormat): string;
+/** Format a user profile. */
+declare function formatUser(user: User, format: ResponseFormat): string;
+/** Format a replies result. */
+declare function formatReplies(result: RepliesResult, format: ResponseFormat): string;
+/**
+* Merge includes into a single tweet response.
+*/
+declare function mergeSingleTweet(response: TwitterV2Response<Tweet>): EnrichedTweet;
+/**
+* Merge includes into a list of tweets.
+*/
+declare function mergeTweetList(response: TwitterV2ListResponse<Tweet>): EnrichedTweet[];
+/** Generic request function matching the client's internal shape. */
+type RequestFn = <T>(endpoint: string, params?: URLSearchParams) => Promise<T>;
+interface ThreadFieldParams {
+	tweetFields: string;
+	expansions: string;
+	userFields: string;
+}
+/**
+* Build a conversation thread from a root tweet ID.
+*
+* 1. Fetches the root tweet to get conversation_id
+* 2. Warns if tweet is older than 7 days (search won't find old replies)
+* 3. Paginates through search results for the conversation
+* 4. Sorts chronologically for reading order
+*/
+declare function buildThread(request: RequestFn, tweetId: string, maxResults: number, fields: ThreadFieldParams): Promise<ThreadResult>;
+export { mergeTweetList, mergeSingleTweet, formatUser, formatTweet, formatTimeline, formatThread, formatSearch, formatReplies, createXApiClient, buildThread, XApiClientConfig, XApiClient, UserPublicMetrics, User, TwitterV2Response, TwitterV2ListResponse, TwitterMeta, TwitterIncludes, TwitterApiError, TweetPublicMetrics, Tweet, TimelineResult, ThreadResult, ThreadFieldParams, SearchResult, RequestFn, RepliesResult, ReferencedTweet, EnrichedTweet };

package/dist/src/index.js

@@ -0,0 +1,27 @@
+// @bun
+import {
+  TwitterApiError,
+  buildThread,
+  createXApiClient,
+  formatReplies,
+  formatSearch,
+  formatThread,
+  formatTimeline,
+  formatTweet,
+  formatUser,
+  mergeSingleTweet,
+  mergeTweetList
+} from "../shared/chunk-219wrwgz.js";
+export {
+  mergeTweetList,
+  mergeSingleTweet,
+  formatUser,
+  formatTweet,
+  formatTimeline,
+  formatThread,
+  formatSearch,
+  formatReplies,
+  createXApiClient,
+  buildThread,
+  TwitterApiError
+};

package/package.json

@@ -0,0 +1,119 @@
+{
+	"name": "@side-quest/x-api",
+	"version": "0.0.0",
+	"description": "Read-only Twitter/X API v2 — tweets, threads, timelines, user profiles",
+	"author": {
+		"name": "Nathan Vale",
+		"url": "https://github.com/nathanvale"
+	},
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/src/index.js",
+	"types": "./dist/src/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/src/index.d.ts",
+			"import": "./dist/src/index.js"
+		},
+		"./mcp": {
+			"types": "./dist/mcp/index.d.ts",
+			"import": "./dist/mcp/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"bin": {
+		"x-api-mcp": "./dist/mcp/index.js"
+	},
+	"files": [
+		"dist/**",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nathanvale/side-quest-x-api.git"
+	},
+	"bugs": {
+		"url": "https://github.com/nathanvale/side-quest-x-api/issues"
+	},
+	"homepage": "https://github.com/nathanvale/side-quest-x-api#readme",
+	"keywords": [
+		"twitter",
+		"x",
+		"api",
+		"mcp",
+		"tweets",
+		"read-only",
+		"typescript",
+		"bun"
+	],
+	"engines": {
+		"node": ">=22.20"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"sideEffects": false,
+	"scripts": {
+		"build": "bunx bunup",
+		"check": "biome check --write .",
+		"check:publint": "publint",
+		"check:types": "attw --pack",
+		"clean": "rimraf dist 2>/dev/null || true",
+		"coverage": "bun test --coverage",
+		"dev": "bun --watch src/index.ts",
+		"format": "biome format --write .",
+		"format:check": "biome format .",
+		"hygiene": "bun run check:publint && bun run check:types",
+		"lint": "biome lint .",
+		"lint:fix": "biome lint --write .",
+		"lint:scripts": "shellcheck .github/scripts/*.sh",
+		"lint:workflows": "actionlint -color -verbose",
+		"pack:dry": "mkdir -p .pack && bun pm pack --destination .pack --ignore-scripts && ls -lah .pack && tar -tf .pack/*.tgz | sort | sed 's/^/ - /'",
+		"pre:enter:beta": "changeset pre enter beta",
+		"pre:enter:next": "changeset pre enter next",
+		"pre:enter:rc": "changeset pre enter rc",
+		"pre:exit": "changeset pre exit",
+		"prepare": "husky",
+		"publish:pre": "changeset publish --provenance",
+		"quality-check:ci": "biome check . && bun run typecheck",
+		"release": "changeset publish --provenance",
+		"release:snapshot:canary": "changeset version --snapshot canary && changeset publish --tag canary",
+		"security:audit": "npm audit",
+		"test": "bun test --recursive",
+		"test:ci": "TF_BUILD=true bun test --recursive",
+		"test:coverage": "bun test --coverage",
+		"test:watch": "bun test --watch",
+		"typecheck": "tsc -p tsconfig.eslint.json --noEmit",
+		"validate": "bun run lint && bun run typecheck && bun run build && TF_BUILD=true bun run test",
+		"version:gen": "bun run scripts/version-gen.ts",
+		"version:pre": "changeset version",
+		"watch:types": "tsc -p tsconfig.eslint.json --noEmit --watch"
+	},
+	"dependencies": {
+		"@side-quest/core": "^0.1.1"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.2",
+		"@biomejs/biome": "^2.3.7",
+		"@changesets/changelog-github": "^0.5.1",
+		"@changesets/cli": "^2.29.7",
+		"@commitlint/cli": "^20.1.0",
+		"@commitlint/config-conventional": "^20.0.0",
+		"@types/node": "^24.8.1",
+		"bun-types": "^1.3.3",
+		"bunup": "^0.16.10",
+		"husky": "^9.1.7",
+		"lint-staged": "^15.2.10",
+		"publint": "^0.3.15",
+		"rimraf": "^6.0.1",
+		"typescript": "^5.9.3"
+	},
+	"lint-staged": {
+		"*.{ts,tsx,js,jsx,mts,cts,json}": [
+			"biome check --write"
+		]
+	}
+}