@granitebps/twitter-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026 granitebps
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# Twitter/X MCP
+
+Twitter/X MCP lets an MCP client read public X posts, replies, and profiles, or search X. It uses Rettiwt by default, so you do not need an X developer plan. You can switch to the official X API if you have access.
+
+## Requirements
+
+- Node.js 22.21.0 or newer within the Node 22 release line. The current Rettiwt release does not support Node 23 or later.
+- A `RETTIWT_API_KEY`. Official X API credentials work when you select API mode.
+
+## Quick start
+
+Once the package is published, your MCP client can run it without a clone:
+
+```bash
+npx -y @granitebps/twitter-mcp
+```
+
+The server selects Rettiwt when you omit `TWITTER_MODE`. Pass `RETTIWT_API_KEY` in the client configuration.
+
+The server uses stdio. Keep stdout reserved for MCP traffic.
+
+## Run from a cloned repository
+
+To develop the server or use a clone directly:
+
+```bash
+git clone https://github.com/granitebps/twitter-mcp.git
+cd twitter-mcp
+npm ci
+npm run build
+```
+
+Point your MCP client at the compiled entry point:
+
+```text
+node /absolute/path/to/twitter-mcp/dist/cli.js
+```
+
+Run `npm run build` after each source change. Do not use `src` or `npm run dev` as the client's stdio command. Build logs on stdout can corrupt MCP messages.
+
+## Client configuration
+
+Each example starts with the npm package, followed by the local equivalent. Replace `/absolute/path/to/twitter-mcp` with your clone's path and `your_key_here` with your Rettiwt key. Do not commit a configuration file that contains the key.
+
+### Claude
+
+Add the npm package to Claude Code:
+
+```bash
+claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp
+```
+
+For a local build:
+
+```bash
+claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js
+```
+
+Claude Code uses local scope by default. Add `--scope user` before `twitter` to make the server available across projects.
+
+Claude Desktop reads the same server from `claude_desktop_config.json`. Restart the app after editing the file.
+
+```json
+{
+  "mcpServers": {
+    "twitter": {
+      "command": "npx",
+      "args": ["-y", "@granitebps/twitter-mcp"],
+      "env": {
+        "RETTIWT_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+For a local build, replace `command` and `args` with:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
+}
+```
+
+### Codex
+
+Add the npm package to `~/.codex/config.toml`, or to `.codex/config.toml` in a trusted project:
+
+```toml
+[mcp_servers.twitter]
+command = "npx"
+args = ["-y", "@granitebps/twitter-mcp"]
+
+[mcp_servers.twitter.env]
+RETTIWT_API_KEY = "your_key_here"
+```
+
+For a local build:
+
+```toml
+[mcp_servers.twitter]
+command = "node"
+args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]
+
+[mcp_servers.twitter.env]
+RETTIWT_API_KEY = "your_key_here"
+```
+
+Restart Codex after editing the file. The CLI, IDE extension, and desktop app share this configuration on the same computer.
+
+### OpenCode
+
+Add the npm package to `opencode.json` or `opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "twitter": {
+      "type": "local",
+      "command": ["npx", "-y", "@granitebps/twitter-mcp"],
+      "enabled": true,
+      "environment": {
+        "RETTIWT_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+For a local build, replace the `command` array with:
+
+```json
+{
+  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]
+}
+```
+
+### Cursor
+
+Add the npm package to `.cursor/mcp.json` in a project, or to `~/.cursor/mcp.json` for global use:
+
+```json
+{
+  "mcpServers": {
+    "twitter": {
+      "command": "npx",
+      "args": ["-y", "@granitebps/twitter-mcp"],
+      "env": {
+        "RETTIWT_API_KEY": "your_key_here"
+      }
+    }
+  }
+}
+```
+
+For a local build, replace `command` and `args` with:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
+}
+```
+
+## Providers
+
+| Mode         | Selection                          | Credentials                                | Notes                                                                                               |
+| ------------ | ---------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Rettiwt      | Default, or `TWITTER_MODE=rettiwt` | `RETTIWT_API_KEY`                          | Free of X API charges. Uses unofficial internal endpoints and may break or put the account at risk. |
+| Official API | `TWITTER_MODE=api`                 | Bearer token or complete OAuth credentials | Uses the supported X API. X controls access tiers and pricing.                                      |
+
+### Rettiwt setup
+
+Rettiwt requires authenticated user mode in this server. Guest mode is not supported.
+
+1. Generate an API key using the [Rettiwt authentication instructions](https://github.com/Rishikant181/Rettiwt-API#authentication).
+2. Store it as `RETTIWT_API_KEY` in the MCP client's environment.
+3. Start the server without `TWITTER_MODE`, or set `TWITTER_MODE=rettiwt` explicitly.
+
+A Rettiwt key contains X session cookies and has the same access as the account. Treat it like a password. Do not commit it, paste it into an issue, log it, or pass it as a command-line argument. Use a key only for an account you own or have permission to access.
+
+Rettiwt is unofficial. X's [automation rules](https://help.x.com/en/rules-and-policies/x-automation) prohibit non-API website automation and warn that violations may lead to account suspension. Read the [X Rules](https://help.x.com/en/rules-and-policies/x-rules) before using this mode. You accept the compliance and account risk.
+
+### Official X API setup
+
+Use a bearer token:
+
+```env
+TWITTER_MODE=api
+TWITTER_BEARER_TOKEN=your_bearer_token
+```
+
+Or provide the complete OAuth set:
+
+```env
+TWITTER_MODE=api
+TWITTER_API_KEY=your_api_key
+TWITTER_API_SECRET=your_api_secret
+TWITTER_ACCESS_TOKEN=your_access_token
+TWITTER_ACCESS_SECRET=your_access_secret
+```
+
+Create credentials in the [X Developer Portal](https://developer.x.com/en/portal/dashboard). X controls API access and pricing, so check the current terms before choosing this mode.
+
+## Configuration
+
+| Variable                     | Required        | Meaning                                                     |
+| ---------------------------- | --------------- | ----------------------------------------------------------- |
+| `TWITTER_MODE`               | No              | `rettiwt` by default, or `api`. Other values fail startup.  |
+| `RETTIWT_API_KEY`            | Rettiwt mode    | Authenticated Rettiwt session key.                          |
+| `TWITTER_BEARER_TOKEN`       | API mode option | Official API bearer token.                                  |
+| `TWITTER_API_KEY`            | OAuth option    | OAuth application key.                                      |
+| `TWITTER_API_SECRET`         | OAuth option    | OAuth application secret.                                   |
+| `TWITTER_ACCESS_TOKEN`       | OAuth option    | OAuth access token.                                         |
+| `TWITTER_ACCESS_SECRET`      | OAuth option    | OAuth access secret.                                        |
+| `TWITTER_REQUEST_TIMEOUT_MS` | No              | Request deadline from 1,000 to 120,000 ms. Default: 30,000. |
+
+The server rejects an incomplete OAuth configuration at startup. It reads credentials from the process environment and never returns them through `get_server_info`.
+
+## Tools
+
+| Tool                | Input                              | Result                                                                               |
+| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------ |
+| `get_tweet`         | `tweet_id`                         | One post. Accepts a numeric ID or an `x.com` or `twitter.com` status URL.            |
+| `get_tweet_replies` | `tweet_id`, optional `max_results` | Replies and available page metadata.                                                 |
+| `get_user_profile`  | `username`                         | One public profile. A leading `@` is accepted.                                       |
+| `search_tweets`     | `query`, optional `max_results`    | Matching posts and available page metadata. Search operators depend on the provider. |
+| `get_server_info`   | None                               | Version, active provider, tools, limits, and capabilities.                           |
+
+`max_results` defaults to 10 and accepts 1 through 100. Successful calls return structured MCP content plus JSON text for older clients. Collection tools return the items as JSON text and put cursors and warnings in structured content.
+
+## Errors
+
+Tool failures use stable codes:
+
+- `INVALID_INPUT`
+- `AUTH_REQUIRED`
+- `AUTH_FAILED`
+- `NOT_FOUND`
+- `RATE_LIMITED`
+- `UPSTREAM_UNAVAILABLE`
+- `TIMEOUT`
+- `UNSUPPORTED_OPERATION`
+- `INTERNAL_ERROR`
+
+Errors name the provider and tell the client whether a retry may work. They do not include credentials or raw upstream response bodies.
+
+## Architecture
+
+```text
+stdio CLI
+  -> validated environment configuration
+  -> MCP server and tool handlers
+  -> TwitterProvider contract
+       -> Rettiwt adapter
+       -> official X API adapter
+```
+
+The domain schemas do not depend on either provider. Each provider adapter maps upstream data, enforces limits and deadlines, and translates errors. Importing `src/index.ts` does not start the server.
+
+## Development
+
+```bash
+npm ci
+npm run check
+```
+
+`npm run check` checks formatting, lint, types, coverage, the production build, npm package contents, and a clean tarball installation. The default test suite uses fakes and does not need X credentials.
+
+Useful focused commands:
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run build
+npm run check:package
+npm run check:install
+npx @modelcontextprotocol/inspector node dist/cli.js
+```
+
+### Live Rettiwt smoke test
+
+The live smoke test starts the compiled stdio server and calls `get_tweet`, `get_tweet_replies`, `get_user_profile`, and `search_tweets`. It derives the username and search query from the selected post.
+
+```bash
+RETTIWT_API_KEY=your_key_here \
+TWITTER_LIVE_TWEET_ID=1234567890123456789 \
+npm run test:live
+```
+
+Choose a public post whose author profile is still available. If either variable is missing, the command stops before starting the live server or making a network request. It does not run as part of `npm run check` or normal CI.
+
+## Release verification
+
+The automated suite covers configuration, provider adapters, MCP calls, the compiled stdio entry point, and installation from an npm tarball. The live Rettiwt smoke test is optional and does not run in normal CI. Version 1.0.0 was prepared without live upstream verification.
+
+Maintainers can follow the [release guide](https://github.com/granitebps/twitter-mcp/blob/main/RELEASE.md) for the manual npm, MCP Registry, and GitHub release process. Live tests must read credentials from repository secrets and must not run for untrusted pull requests.
+
+## Troubleshooting
+
+### Missing Rettiwt key
+
+If startup reports `RETTIWT_API_KEY is required in rettiwt mode`, set the key in the MCP client configuration. Desktop clients do not automatically inherit a shell's `.env` file.
+
+### Invalid Rettiwt authentication
+
+If you see `Invalid authentication data` or `AUTH_FAILED`, generate a new Rettiwt key and check that the X session still works. Never post the failing key in an issue.
+
+### Rate limit
+
+For `RATE_LIMITED`, wait before retrying and reduce the request rate. Check `retryAfterSeconds` when the provider supplies it.
+
+### Official API 401 or 403
+
+Confirm the credential set, app permissions, endpoint access, and current X API plan.
+
+### Node engine warning
+
+Run Node.js 22.21.0 or a newer Node 22 release. Do not use Node 23 or later with the current Rettiwt dependency.
+
+## License
+
+[ISC](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { config as loadDotenv } from "dotenv";
+import { loadConfig } from "./config/env.js";
+import { redactSecrets } from "./errors/twitter-error.js";
+import { createProvider } from "./providers/factory.js";
+import { createTwitterServer } from "./server/create-server.js";
+function packageVersion() {
+    const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof manifest.version !== "string")
+        throw new Error("Package version is missing");
+    return manifest.version;
+}
+function reportFatal(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`twitter-mcp: ${redactSecrets(message)}`);
+}
+async function main() {
+    loadDotenv({ quiet: true });
+    const runtimeConfig = loadConfig(process.env);
+    const provider = await createProvider(runtimeConfig);
+    const version = packageVersion();
+    const handle = serveStdio(() => createTwitterServer({ config: runtimeConfig, provider, version }), { onerror: reportFatal });
+    const close = () => {
+        void handle.close().catch(reportFatal);
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+}
+void main().catch((error) => {
+    reportFatal(error);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhE,SAAS,cAAc;IACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CACzC,CAAC;IAC3B,IAAI,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IACxF,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,CAAC,KAAK,CAAC,gBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5B,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,UAAU,CACvB,GAAG,EAAE,CAAC,mBAAmB,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EACvE,EAAE,OAAO,EAAE,WAAW,EAAE,CACzB,CAAC;IAEF,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AACjC,CAAC;AAED,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACnC,WAAW,CAAC,KAAK,CAAC,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/config/env.d.ts

@@ -0,0 +1,22 @@
+export interface RettiwtConfig {
+    mode: "rettiwt";
+    apiKey: string;
+    requestTimeoutMs: number;
+}
+export type ApiCredentials = {
+    type: "bearer";
+    token: string;
+} | {
+    type: "oauth";
+    appKey: string;
+    appSecret: string;
+    accessToken: string;
+    accessSecret: string;
+};
+export interface ApiConfig {
+    mode: "api";
+    credentials: ApiCredentials;
+    requestTimeoutMs: number;
+}
+export type RuntimeConfig = RettiwtConfig | ApiConfig;
+export declare function loadConfig(env: NodeJS.ProcessEnv): RuntimeConfig;

package/dist/config/env.js

@@ -0,0 +1,44 @@
+function readNonEmpty(env, name) {
+    const value = env[name]?.trim();
+    return value ? value : undefined;
+}
+function readTimeout(env) {
+    const raw = readNonEmpty(env, "TWITTER_REQUEST_TIMEOUT_MS");
+    if (!raw)
+        return 30_000;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1_000 || value > 120_000) {
+        throw new Error("TWITTER_REQUEST_TIMEOUT_MS must be an integer from 1000 to 120000");
+    }
+    return value;
+}
+export function loadConfig(env) {
+    const rawMode = readNonEmpty(env, "TWITTER_MODE")?.toLowerCase() ?? "rettiwt";
+    if (rawMode !== "rettiwt" && rawMode !== "api") {
+        throw new Error('TWITTER_MODE must be either "rettiwt" or "api"');
+    }
+    const requestTimeoutMs = readTimeout(env);
+    if (rawMode === "rettiwt") {
+        const apiKey = readNonEmpty(env, "RETTIWT_API_KEY");
+        if (!apiKey)
+            throw new Error("RETTIWT_API_KEY is required in rettiwt mode");
+        return { mode: "rettiwt", apiKey, requestTimeoutMs };
+    }
+    const bearer = readNonEmpty(env, "TWITTER_BEARER_TOKEN");
+    if (bearer) {
+        return { mode: "api", credentials: { type: "bearer", token: bearer }, requestTimeoutMs };
+    }
+    const appKey = readNonEmpty(env, "TWITTER_API_KEY");
+    const appSecret = readNonEmpty(env, "TWITTER_API_SECRET");
+    const accessToken = readNonEmpty(env, "TWITTER_ACCESS_TOKEN");
+    const accessSecret = readNonEmpty(env, "TWITTER_ACCESS_SECRET");
+    if (!appKey || !appSecret || !accessToken || !accessSecret) {
+        throw new Error("API mode requires TWITTER_BEARER_TOKEN or a complete OAuth credential set");
+    }
+    return {
+        mode: "api",
+        credentials: { type: "oauth", appKey, appSecret, accessToken, accessSecret },
+        requestTimeoutMs,
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAwBA,SAAS,YAAY,CAAC,GAAsB,EAAE,IAAY;IACxD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC;IAChC,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACnC,CAAC;AAED,SAAS,WAAW,CAAC,GAAsB;IACzC,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,4BAA4B,CAAC,CAAC;IAC5D,IAAI,CAAC,GAAG;QAAE,OAAO,MAAM,CAAC;IAExB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,KAAK,IAAI,KAAK,GAAG,OAAO,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAsB;IAC/C,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,WAAW,EAAE,IAAI,SAAS,CAAC;IAC9E,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAC5E,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACvD,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IACzD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,gBAAgB,EAAE,CAAC;IAC3F,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC;IAC9D,MAAM,YAAY,GAAG,YAAY,CAAC,GAAG,EAAE,uBAAuB,CAAC,CAAC;IAChE,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,IAAI,CAAC,WAAW,IAAI,CAAC,YAAY,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;IAC/F,CAAC;IAED,OAAO;QACL,IAAI,EAAE,KAAK;QACX,WAAW,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE;QAC5E,gBAAgB;KACjB,CAAC;AACJ,CAAC"}

package/dist/domain/requests.d.ts

@@ -0,0 +1,36 @@
+export interface GetTweetRequest {
+    tweetId: string;
+}
+export interface GetRepliesRequest {
+    tweetId: string;
+    maxResults: number;
+}
+export interface GetProfileRequest {
+    username: string;
+}
+export interface SearchTweetsRequest {
+    query: string;
+    maxResults: number;
+}
+export interface RequestContext {
+    signal: AbortSignal;
+    deadline: number;
+}
+export interface ProviderCapabilities {
+    provider: "rettiwt" | "api";
+    authenticated: boolean;
+    operations: {
+        getTweet: boolean;
+        getTweetReplies: boolean;
+        getUserProfile: boolean;
+        searchTweets: boolean;
+    };
+    pagination: {
+        replies: boolean;
+        search: boolean;
+    };
+    limits: {
+        replies: number;
+        search: number;
+    };
+}

package/dist/domain/requests.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=requests.js.map

package/dist/domain/requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.js","sourceRoot":"","sources":["../../src/domain/requests.ts"],"names":[],"mappings":""}

package/dist/domain/schemas.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+export declare const TweetMetricsSchema: z.ZodObject<{
+    likes: z.ZodNumber;
+    retweets: z.ZodNumber;
+    replies: z.ZodNumber;
+    quotes: z.ZodNumber;
+    bookmarks: z.ZodNumber;
+    views: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const TweetAuthorSchema: z.ZodObject<{
+    name: z.ZodString;
+    username: z.ZodString;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    blue_verified: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const TweetSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    created_at: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        name: z.ZodString;
+        username: z.ZodString;
+        verified: z.ZodOptional<z.ZodBoolean>;
+        blue_verified: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    metrics: z.ZodObject<{
+        likes: z.ZodNumber;
+        retweets: z.ZodNumber;
+        replies: z.ZodNumber;
+        quotes: z.ZodNumber;
+        bookmarks: z.ZodNumber;
+        views: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const ProfileMetricsSchema: z.ZodObject<{
+    followers_count: z.ZodNumber;
+    following_count: z.ZodNumber;
+    tweet_count: z.ZodNumber;
+    listed_count: z.ZodNumber;
+    likes_count: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const UserProfileSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    username: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    created_at: z.ZodOptional<z.ZodString>;
+    verified: z.ZodBoolean;
+    blue_verified: z.ZodOptional<z.ZodBoolean>;
+    profile_image_url: z.ZodOptional<z.ZodString>;
+    location: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    metrics: z.ZodObject<{
+        followers_count: z.ZodNumber;
+        following_count: z.ZodNumber;
+        tweet_count: z.ZodNumber;
+        listed_count: z.ZodNumber;
+        likes_count: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const ProviderWarningSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const TweetPageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        created_at: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            name: z.ZodString;
+            username: z.ZodString;
+            verified: z.ZodOptional<z.ZodBoolean>;
+            blue_verified: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+        metrics: z.ZodObject<{
+            likes: z.ZodNumber;
+            retweets: z.ZodNumber;
+            replies: z.ZodNumber;
+            quotes: z.ZodNumber;
+            bookmarks: z.ZodNumber;
+            views: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+    partial: z.ZodOptional<z.ZodBoolean>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Tweet = z.infer<typeof TweetSchema>;
+export type UserProfile = z.infer<typeof UserProfileSchema>;
+export type ProviderWarning = z.infer<typeof ProviderWarningSchema>;
+export type TweetPage = z.infer<typeof TweetPageSchema>;

package/dist/domain/schemas.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export const TweetMetricsSchema = z.object({
+    likes: z.number().int().nonnegative(),
+    retweets: z.number().int().nonnegative(),
+    replies: z.number().int().nonnegative(),
+    quotes: z.number().int().nonnegative(),
+    bookmarks: z.number().int().nonnegative(),
+    views: z.number().int().nonnegative().optional(),
+});
+export const TweetAuthorSchema = z.object({
+    name: z.string(),
+    username: z.string(),
+    verified: z.boolean().optional(),
+    blue_verified: z.boolean().optional(),
+});
+export const TweetSchema = z.object({
+    id: z.string(),
+    text: z.string(),
+    created_at: z.string().optional(),
+    author: TweetAuthorSchema.nullable().optional(),
+    metrics: TweetMetricsSchema,
+});
+export const ProfileMetricsSchema = z.object({
+    followers_count: z.number().int().nonnegative(),
+    following_count: z.number().int().nonnegative(),
+    tweet_count: z.number().int().nonnegative(),
+    listed_count: z.number().int().nonnegative(),
+    likes_count: z.number().int().nonnegative().optional(),
+});
+export const UserProfileSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    username: z.string(),
+    description: z.string().optional(),
+    created_at: z.string().optional(),
+    verified: z.boolean(),
+    blue_verified: z.boolean().optional(),
+    profile_image_url: z.string().optional(),
+    location: z.string().optional(),
+    url: z.string().optional(),
+    metrics: ProfileMetricsSchema,
+});
+export const ProviderWarningSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
+export const TweetPageSchema = z.object({
+    items: z.array(TweetSchema),
+    nextCursor: z.string().optional(),
+    partial: z.boolean().optional(),
+    warnings: z.array(ProviderWarningSchema).optional(),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/domain/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/domain/schemas.ts"],"names":[],"mappings":"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"}

package/dist/errors/twitter-error.d.ts

@@ -0,0 +1,20 @@
+export type TwitterErrorCode = "INVALID_INPUT" | "AUTH_REQUIRED" | "AUTH_FAILED" | "NOT_FOUND" | "RATE_LIMITED" | "UPSTREAM_UNAVAILABLE" | "TIMEOUT" | "UNSUPPORTED_OPERATION" | "INTERNAL_ERROR";
+export type ProviderName = "rettiwt" | "api";
+export interface TwitterErrorOptions {
+    code: TwitterErrorCode;
+    safeMessage: string;
+    provider: ProviderName;
+    retryable: boolean;
+    retryAfterSeconds?: number;
+    cause?: unknown;
+}
+export declare class TwitterError extends Error {
+    readonly code: TwitterErrorCode;
+    readonly safeMessage: string;
+    readonly provider: ProviderName;
+    readonly retryable: boolean;
+    readonly retryAfterSeconds: number | undefined;
+    constructor(options: TwitterErrorOptions);
+}
+export declare function redactSecrets(value: string): string;
+export declare function toTwitterError(error: unknown, provider: ProviderName): TwitterError;