@vornrun/connector-x 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to `@vornrun/connector-x`.
+
+## 0.1.0
+
+First release.
+
+Trigger a workflow from new mentions of the connected account or from posts
+matching a recent-search query, and let a workflow step create, reply to,
+delete, read and search posts or look up the connected account and a user by
+username.
+
+- **Triggers:** `newMention`, `newSearchResult`.
+- **Actions:** `createPost`, `replyToPost`, `deletePost`, `getMe`, `getPost`,
+  `getUserByUsername`, `searchRecentPosts`.
+- **Signing in:** the four OAuth 1.0a credentials of an X developer app with
+  Read and Write permission, from the app's Keys and tokens tab. Every request
+  is signed in the package with `node:crypto` (HMAC-SHA1, the
+  `Authorization: OAuth …` header); no OAuth dependency. All four fields are
+  stored encrypted, because the SDK refuses a credential field left in the
+  clear.
+
+Every call goes through one small client rather than a declared SDK request,
+because a per-request OAuth 1.0a signature cannot be written as a static
+header template. The client waits out a `429` until `x-rate-limit-reset`
+(capped at 60 seconds, past which the reset instant is reported) and sends
+once more, retries a `500`, `502`, `503` or `504` once after a second, and
+reports a failure as `<status> <title>: <detail> [<problem>]`, appending a
+`403`'s `reason` when present. A `402`, `client-forbidden` or `usage-capped`
+answer says plainly that the plan or credits do not cover the endpoint and is
+never retried.
+
+Both triggers are declarative polls on the SDK's `lastItem` strategy with
+`since_id`; the connected account's id is fetched once per process. Post text
+is counted in code points and refused over 280 characters before sending.
+The README records which reads needed a paid tier and what each call costs.
+
+Ships as a pack with a conformance receipt covering the dedupe replay of both
+triggers and the mock run of every action. No runtime dependencies.

package/README.md

@@ -0,0 +1,189 @@
+# @vornrun/connector-x
+
+Trigger Vorn workflows from new mentions of the connected account or from
+posts matching a search on X (formerly Twitter), and create, reply to, delete,
+read and search posts from a workflow step. Talks to API v2 at
+`https://api.x.com/2`.
+
+## Signing in
+
+Paste the four OAuth 1.0a user-context credentials of an X developer app.
+There is no X CLI to borrow a login from. Create the app in the
+[Developer Console](https://developer.x.com/en/portal/dashboard) under
+Projects & Apps, open the app's **Keys and tokens** tab, and copy the API Key
+and Secret (the consumer key pair) and the Access Token and Secret generated
+for your own account. Each value is shown once at creation; regenerate it from
+the same tab.
+
+Two things about the app's permissions:
+
+- Set **User authentication settings** to **Read and Write** before
+  `createPost`, `replyToPost` or `deletePost` will work. Read alone "cannot
+  post, like, or modify anything".
+- Generate (or regenerate) the access token **after** setting Read and Write.
+  Changing permissions "requires users to re-authorize your app to get new
+  tokens with the updated scope": an access token generated before the change
+  stays read-only, and the API answers `403` to every write.
+
+Every request is signed in the package with `node:crypto`: an
+`Authorization: OAuth …` header carrying `oauth_consumer_key`, `oauth_nonce`,
+`oauth_signature` (HMAC-SHA1, base64), `oauth_signature_method`,
+`oauth_timestamp`, `oauth_token` and `oauth_version`, built as the signing
+guide describes. A `401` means one of the four values or the signature is
+wrong; the error says so and names the Keys and tokens tab.
+
+All four fields are stored encrypted. The consumer key and access token are
+not secrets in X's own terms, but Vorn stores every field that names a
+credential encrypted, and the SDK refuses to leave one in the clear.
+
+## Settings
+
+| Setting | Environment | Required | What it does |
+| --- | --- | --- | --- |
+| API key | `X_API_KEY` | yes | The app's API Key (OAuth 1.0a consumer key) |
+| API key secret | `X_API_SECRET` | yes | The app's API Key Secret; half of the signing key |
+| Access token | `X_ACCESS_TOKEN` | yes | The access token generated for your own account |
+| Access token secret | `X_ACCESS_TOKEN_SECRET` | yes | Shown with the access token; the other half of the signing key |
+| Search query | `X_SEARCH_QUERY` | for `newSearchResult` | A recent-search query, 1 to 512 characters, such as `from:xdevelopers -is:retweet` |
+
+## Access, pricing and tiers
+
+Access to the X API is metered per endpoint, and the connector cannot make a
+call the app's plan or credit balance does not cover. The pages the connector
+was built from describe pay-per-usage pricing: credits bought in the Developer
+Console, deducted per resource read and per write request, deduplicated within
+a UTC day, with a cap of 3 million post reads per billing cycle. Those pages
+no longer name the Free, Basic and Pro tiers; what the older tiers allowed is
+recorded here because the API still refuses in the same shapes:
+
+- The **Free** tier allowed writes (create and delete a post) and
+  `GET /2/users/me`, with a small monthly post budget and very few reads.
+- The **mentions timeline** and **recent search** were the reads that needed
+  **Basic or above**. If your app is on a legacy tier, `newMention`,
+  `newSearchResult` and `searchRecentPosts` are the ones that will refuse.
+- **Quote posts** need an Enterprise plan: the create page says quoting is
+  "not available on self-serve tiers".
+
+What each call costs and how often it may be made, per user, from the
+rate-limit and pricing pages:
+
+| Call | Used by | Rate limit | Billing |
+| --- | --- | --- | --- |
+| `GET /2/users/me` | `getMe`, `newMention` once per process | 75 / 15 min | 1 user read ($0.010) |
+| `GET /2/users/:id/mentions` | `newMention` | 300 / 15 min | per post returned: Owned Read ($0.001) when the account owns the app, $0.005 otherwise |
+| `GET /2/tweets/search/recent` | `newSearchResult`, `searchRecentPosts` | 300 / 15 min | $0.005 per post returned |
+| `GET /2/tweets/:id` | `getPost` | 900 / 15 min | 1 post read plus 1 user read |
+| `GET /2/users/by/username/:username` | `getUserByUsername` | 900 / 15 min | 1 user read |
+| `POST /2/tweets` | `createPost`, `replyToPost` | 100 / 15 min, 10,000 / 24 h app-wide | $0.015 per request |
+| `DELETE /2/tweets/:id` | `deletePost` | 50 / 15 min | $0.010 per request |
+
+When the plan or the balance is what refuses, the connector says so plainly.
+A `402`, a `403` whose problem type is `client-forbidden` ("App not enrolled
+or lacks required access") and a `429` whose type is `usage-capped` ("Usage
+cap exceeded") are thrown as `<status> <title>: <detail> [<problem>]`
+followed by "The app's plan or credits do not cover this endpoint." None of
+the three is retried: a budget does not come back in a second.
+
+## Rate limits
+
+Every answer carries `x-rate-limit-limit`, `x-rate-limit-remaining` and
+`x-rate-limit-reset` (Unix seconds). On a `429` the connector reads
+`x-rate-limit-reset`, waits until that instant and sends once more; a second
+`429` is reported. The wait is capped at 60 seconds: a window that resets
+later than that is reported at once with the reset instant in the message,
+so a fresh 15-minute window cannot hold a workflow step or a poll open. A
+`500`, `502`, `503` or `504` is retried once after one second. Any other
+failure is reported as X describes it: `<status> <title>: <detail>` for a v2
+problem, with the last segment of the problem `type` in brackets, or
+`<status>: <message> (code <n>)` for the legacy `errors` list; a `403` that
+carries a `reason` field has it appended.
+
+## Triggers
+
+Both are declarative polls on the SDK's `lastItem` strategy: X returns the
+feed newest first, and the post id is the only dependable order. Each poll
+sends `since_id` = the newest id already delivered and `max_results` = the
+poll's limit clamped to the endpoint's window (5 to 100 for mentions, 10 to
+100 for search). The connector does not follow `next_token`, so a burst above
+100 new posts between two polls loses the oldest.
+
+Every item has the post id as `externalId`, `@username: ` plus the first 80
+characters of the text as `title`, `created_at` as `updatedAt`,
+`https://x.com/{username}/status/{id}` as `url`, and in `data` the post joined
+with its author: `id`, `text`, `createdAt`, `conversationId`,
+`inReplyToUserId`, `author` (`id`, `username`, `name`) and `url`. When the
+author is missing from `includes` (a partial answer) the username is empty and
+the URL takes the `https://x.com/i/status/{id}` form, which X resolves.
+
+### `newMention` — a post mentions the connected account
+
+`GET /2/users/{id}/mentions` with
+`tweet.fields=created_at,author_id,conversation_id,in_reply_to_user_id`,
+`expansions=author_id` and `user.fields=username,name`. The account id comes
+from `GET /2/users/me`, fetched once per connection and cached for the life of
+the process (the SDK keeps nothing but the cursor between polls, so "once per
+connection" means once per process). Seeds the workflow `X: new mentions`,
+every 5 minutes.
+
+### `newSearchResult` — a post matches a search
+
+`GET /2/tweets/search/recent?query=…&sort_order=recency` with the same
+fields, using the **Search query** setting. Only posts from the last 7 days
+are searchable, and `start_time` is never sent because at most one of it and
+`since_id` may be. Seeds the workflow `X: search results`, every 5 minutes.
+
+## Actions
+
+`createPost` and `replyToPost` count the text in code points and refuse
+anything empty or over 280 characters before sending, with `Post text is N
+characters; the limit is 280 for non-Premium accounts`. The pages read do not
+publish the weighted counting rule, so this is a plain count; a text the API
+weighs longer still answers `403`, reported like any other error.
+
+| Action | Idempotent | What it does |
+| --- | --- | --- |
+| `createPost` | no | `POST /2/tweets` with `text`, optional `inReplyToPostId` (sent as `reply.in_reply_to_tweet_id`) and `quotePostId` (`quote_tweet_id`, Enterprise only). Returns `id`, `url` (`https://x.com/i/status/{id}`), `text`. |
+| `replyToPost` | no | `POST /2/tweets` with `text` and `reply.in_reply_to_tweet_id` = `postId`. Returns `id`, `url`, `text`. |
+| `deletePost` | no | `DELETE /2/tweets/{postId}`; only the connected account's own posts. Returns `deleted`. |
+| `getMe` | yes | `GET /2/users/me?user.fields=id,username,name`. Returns `id`, `username`, `name`, `url`. The live check. |
+| `getPost` | yes | `GET /2/tweets/{postId}` with `created_at,author_id,conversation_id,public_metrics` and the author expansion. Returns `id`, `text`, `createdAt`, `authorId`, `authorUsername`, `conversationId`, `url`, `metrics`, `raw`. |
+| `getUserByUsername` | yes | `GET /2/users/by/username/{username}` (a leading `@` is stripped). Returns `id`, `username`, `name`, `description`, `createdAt`, `followers`, `following`, `posts`, `url`, `raw`. |
+| `searchRecentPosts` | yes | `GET /2/tweets/search/recent` with `query`, `maxResults` (10 to 100, default 10; a smaller value is raised to 10, a larger one refused) and `sinceId`. Returns `posts` (the trigger's `data` shape), `count`, `newestId`, `nextToken`. |
+
+## Checks
+
+```sh
+packages/x/scripts/check.sh        # typecheck, tests, build, conformance receipt
+packages/x/scripts/check-live.sh   # needs the four X_* credentials; exits 0 with a note without them
+```
+
+Tests make no network calls: the client takes an injected `fetch`, clock and
+sleep. The signer is pinned to the signing guide's worked example with
+stand-in credentials of the same shape. The live check calls the idempotent
+actions on their samples (`getMe`, `getPost` on id `20`,
+`getUserByUsername` on `x`, `searchRecentPosts` on
+`from:xdevelopers -is:retweet`); those are billed reads and need credits on
+the app. Nothing is created or deleted.
+
+## Built from
+
+- [X API introduction](https://docs.x.com/x-api/introduction)
+- [About the X API](https://docs.x.com/x-api/getting-started/about-x-api)
+  and [pricing](https://docs.x.com/x-api/getting-started/pricing)
+- [Authentication overview](https://docs.x.com/resources/fundamentals/authentication),
+  [API key and secret](https://docs.x.com/resources/fundamentals/authentication/oauth-1-0a/api-key-and-secret)
+  and [developer apps](https://docs.x.com/resources/fundamentals/developer-apps)
+- OAuth 1.0a: [creating a signature](https://docs.x.com/resources/fundamentals/authentication/oauth-1-0a/creating-a-signature),
+  [authorizing a request](https://docs.x.com/resources/fundamentals/authentication/oauth-1-0a/authorizing-a-request)
+  and [percent encoding](https://docs.x.com/resources/fundamentals/authentication/oauth-1-0a/percent-encoding-parameters)
+- [Fields](https://docs.x.com/x-api/fundamentals/fields)
+- Posts: [create](https://docs.x.com/x-api/posts/creation-of-a-post),
+  [delete](https://docs.x.com/x-api/posts/post-delete-by-post-id),
+  [lookup by id](https://docs.x.com/x-api/posts/post-lookup-by-post-id),
+  [mentions timeline](https://docs.x.com/x-api/posts/user-mention-timeline-by-user-id)
+  and [recent search](https://docs.x.com/x-api/posts/recent-search)
+- Users: [me](https://docs.x.com/x-api/users/user-lookup-me)
+  and [by username](https://docs.x.com/x-api/users/user-lookup-by-username)
+- [Rate limits overview](https://docs.x.com/resources/fundamentals/rate-limits)
+  and [v2 rate limits](https://docs.x.com/x-api/fundamentals/rate-limits)
+- [Response codes and errors](https://docs.x.com/x-api/fundamentals/response-codes-and-errors)

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import * as _vornrun_connector_sdk from '@vornrun/connector-sdk';
+
+declare const connector: _vornrun_connector_sdk.Connector;
+
+export { connector, connector as default };

package/dist/index.js

@@ -0,0 +1,755 @@
+#!/usr/bin/env node
+
+// src/connector.ts
+import {
+  defineConnector
+} from "@vornrun/connector-sdk";
+
+// src/oauth.ts
+import { createHmac, randomBytes } from "crypto";
+function percentEncode(value) {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+}
+function oauthParams(credentials, nonce, timestamp) {
+  return {
+    oauth_consumer_key: credentials.consumerKey,
+    oauth_nonce: nonce,
+    oauth_signature_method: "HMAC-SHA1",
+    oauth_timestamp: String(timestamp),
+    oauth_token: credentials.token,
+    oauth_version: "1.0"
+  };
+}
+function makeNonce(random = randomBytes) {
+  return random(32).toString("base64").replace(/\W/g, "");
+}
+function byteOrder(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+function parameterString(params) {
+  return params.map(([key, value]) => [percentEncode(key), percentEncode(value)]).sort(([a], [b]) => byteOrder(a, b)).map(([key, value]) => `${key}=${value}`).join("&");
+}
+function signatureBaseString(method, url, params) {
+  const baseUrl = `${url.origin}${url.pathname}`;
+  return `${method.toUpperCase()}&${percentEncode(baseUrl)}&${percentEncode(parameterString(params))}`;
+}
+function sign(credentials, input) {
+  const url = new URL(input.url);
+  const nonce = input.nonce ?? makeNonce();
+  const timestamp = input.timestamp ?? Math.floor(Date.now() / 1e3);
+  const oauth = oauthParams(credentials, nonce, timestamp);
+  const params = [
+    ...Array.from(url.searchParams.entries()),
+    ...Object.entries(input.bodyParams ?? {}),
+    ...Object.entries(oauth)
+  ];
+  const baseString = signatureBaseString(input.method, url, params);
+  const signingKey = `${percentEncode(credentials.consumerSecret)}&${percentEncode(credentials.tokenSecret)}`;
+  const signature = createHmac("sha1", signingKey).update(baseString).digest("base64");
+  const header = "OAuth " + Object.entries({ ...oauth, oauth_signature: signature }).sort(([a], [b]) => byteOrder(a, b)).map(([key, value]) => `${percentEncode(key)}="${percentEncode(value)}"`).join(", ");
+  return { header, baseString, signature };
+}
+
+// src/client.ts
+var API_ROOT = "https://api.x.com/2";
+var MAX_RATE_LIMIT_WAIT_MS = 6e4;
+var SERVER_ERROR_RETRY_MS = 1e3;
+var RETRYABLE_SERVER_STATUSES = /* @__PURE__ */ new Set([500, 502, 503, 504]);
+var MAX_ERROR_BODY = 300;
+var ACCESS_PROBLEMS = /* @__PURE__ */ new Set(["client-forbidden", "usage-capped"]);
+var XApiError = class extends Error {
+  status;
+  title;
+  detail;
+  /** The last path segment of the problem `type`, such as `client-forbidden`. */
+  problem;
+  reason;
+  constructor(status, message, body = {}) {
+    super(message);
+    this.name = "XApiError";
+    this.status = status;
+    this.title = body.title;
+    this.detail = body.detail;
+    this.problem = problemName(body.type);
+    this.reason = body.reason;
+  }
+  /** Whether the plan or the credit balance, not a window, is what refused the call. */
+  get accessDenied() {
+    return this.status === 402 || this.problem !== void 0 && ACCESS_PROBLEMS.has(this.problem);
+  }
+};
+function problemName(type) {
+  if (!type || type === "about:blank") return void 0;
+  const segment = type.split("/").filter(Boolean).pop();
+  return segment || void 0;
+}
+async function readBody(response) {
+  const text2 = await response.text().catch(() => "");
+  try {
+    const parsed = JSON.parse(text2);
+    if (typeof parsed === "object" && parsed !== null) return { parsed, text: text2 };
+  } catch {
+  }
+  return { parsed: {}, text: text2 };
+}
+function describeFailure(status, parsed, text2) {
+  const legacy = parsed.errors?.find((entry) => typeof entry?.message === "string");
+  let message;
+  if (parsed.title || parsed.detail) {
+    message = `${status} ${parsed.title ?? "Error"}${parsed.detail ? `: ${parsed.detail}` : ""}`;
+  } else if (legacy) {
+    message = `${status}: ${legacy.message}${legacy.code !== void 0 ? ` (code ${legacy.code})` : ""}`;
+  } else {
+    const quoted = text2.length > MAX_ERROR_BODY ? `${text2.slice(0, MAX_ERROR_BODY)}\u2026` : text2;
+    message = `X API ${status}${quoted ? `: ${quoted}` : ""}`;
+  }
+  const problem = problemName(parsed.type);
+  if (problem) message += ` [${problem}]`;
+  if (status === 403 && parsed.reason) message += ` reason: ${parsed.reason}`;
+  if (status === 401) {
+    message += ". The four credentials or the signature are wrong: check the Keys and tokens tab of the app and regenerate the access token after setting Read and Write.";
+  }
+  if (status === 402 || problem && ACCESS_PROBLEMS.has(problem)) {
+    message += ". The app's plan or credits do not cover this endpoint.";
+  }
+  return new XApiError(status, message, parsed);
+}
+var wait = (ms) => new Promise((resolve) => {
+  setTimeout(resolve, ms);
+});
+function compact(params) {
+  const out = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== "") out.push([key, String(value)]);
+  }
+  return out;
+}
+var POST_FIELDS = {
+  "tweet.fields": "created_at,author_id,conversation_id,in_reply_to_user_id",
+  expansions: "author_id",
+  "user.fields": "username,name"
+};
+var USER_FIELDS = "id,username,name";
+function createXClient(options) {
+  const sleep = options.sleep ?? wait;
+  const now = options.now ?? Date.now;
+  let fetchImpl = options.fetch;
+  async function call(path, callOptions = {}) {
+    const method = callOptions.method ?? "GET";
+    const url = new URL(`${API_ROOT}${path}`);
+    for (const [key, value] of compact(callOptions.query ?? {})) url.searchParams.set(key, value);
+    const hasBody = callOptions.body !== void 0;
+    for (let attempt = 0; ; attempt++) {
+      const { header } = sign(options.credentials, {
+        method,
+        url: url.toString(),
+        timestamp: Math.floor(now() / 1e3)
+      });
+      const response = await fetchImpl(url.toString(), {
+        method,
+        headers: { Authorization: header, ...hasBody && { "Content-Type": "application/json" } },
+        ...hasBody && { body: JSON.stringify(callOptions.body) }
+      });
+      if (response.ok) {
+        const text3 = await response.text();
+        return text3 === "" ? {} : JSON.parse(text3);
+      }
+      const { parsed, text: text2 } = await readBody(response);
+      const failure = describeFailure(response.status, parsed, text2);
+      if (attempt === 0 && response.status === 429 && !failure.accessDenied) {
+        const resetAt = Number(response.headers.get("x-rate-limit-reset")) * 1e3;
+        const pending = Number.isFinite(resetAt) && resetAt > 0 ? resetAt - now() : SERVER_ERROR_RETRY_MS;
+        if (pending > MAX_RATE_LIMIT_WAIT_MS) {
+          throw new XApiError(
+            429,
+            `${failure.message}. The rate limit resets at ${new Date(resetAt).toISOString()}.`,
+            parsed
+          );
+        }
+        await sleep(Math.max(0, pending));
+        continue;
+      }
+      if (attempt === 0 && RETRYABLE_SERVER_STATUSES.has(response.status)) {
+        await sleep(SERVER_ERROR_RETRY_MS);
+        continue;
+      }
+      throw failure;
+    }
+  }
+  let me;
+  return {
+    call,
+    /** The host hands a fresh resilient fetch to every call; a memoised client takes the latest. */
+    setFetch(next) {
+      fetchImpl = next;
+    },
+    getMe: () => call("/users/me", { query: { "user.fields": USER_FIELDS } }),
+    // Fetched once per process: the SDK keeps no store beyond the cursor, so a memo is the nearest thing to per connection.
+    myId() {
+      me ??= this.getMe().then((envelope) => envelope.data ?? {}).catch((error) => {
+        me = void 0;
+        throw error;
+      });
+      return me;
+    },
+    getPost: (id, query = POST_FIELDS) => call(`/tweets/${encodeURIComponent(id)}`, { query }),
+    getUserByUsername: (username, query) => call(`/users/by/username/${encodeURIComponent(username)}`, { query }),
+    mentions: (userId, query) => call(`/users/${encodeURIComponent(userId)}/mentions`, { query: { ...POST_FIELDS, ...query } }),
+    searchRecent: (query) => call("/tweets/search/recent", { query: { ...POST_FIELDS, sort_order: "recency", ...query } }),
+    createPost: (body) => call("/tweets", { method: "POST", body }),
+    deletePost: (id) => call(`/tweets/${encodeURIComponent(id)}`, { method: "DELETE" })
+  };
+}
+
+// src/items.ts
+var TITLE_LIMIT = 80;
+function postUrl(id, username) {
+  return username ? `https://x.com/${username}/status/${id}` : `https://x.com/i/status/${id}`;
+}
+function joinAuthor(post, users) {
+  const id = post.id ?? "";
+  const author = users?.find((user) => user.id !== void 0 && user.id === post.author_id);
+  const username = author?.username ?? "";
+  return {
+    id,
+    text: post.text ?? "",
+    createdAt: post.created_at ?? "",
+    conversationId: post.conversation_id ?? "",
+    inReplyToUserId: post.in_reply_to_user_id ?? null,
+    author: { id: post.author_id ?? "", username, name: author?.name ?? "" },
+    url: postUrl(id, username)
+  };
+}
+function postToItem(record) {
+  const firstLine = record.text.replace(/\s+/g, " ").trim();
+  const excerpt = Array.from(firstLine).slice(0, TITLE_LIMIT).join("");
+  return {
+    externalId: record.id,
+    title: `@${record.author.username}: ${excerpt}`,
+    ...record.createdAt && { updatedAt: record.createdAt },
+    url: record.url,
+    data: record
+  };
+}
+var SAMPLE_ITEM = {
+  externalId: "1346889436626259968",
+  title: "@xdevelopers: Hello world!",
+  updatedAt: "2024-01-15T12:00:00.000Z",
+  url: "https://x.com/xdevelopers/status/1346889436626259968",
+  data: {
+    id: "1346889436626259968",
+    text: "Hello world!",
+    createdAt: "2024-01-15T12:00:00.000Z",
+    conversationId: "1346889436626259968",
+    inReplyToUserId: null,
+    author: { id: "2244994945", username: "xdevelopers", name: "X Developers" },
+    url: "https://x.com/xdevelopers/status/1346889436626259968"
+  }
+};
+
+// package.json
+var package_default = {
+  name: "@vornrun/connector-x",
+  version: "0.1.0",
+  description: "Trigger workflows from new mentions or posts matching a search on X, and create, reply to, delete, read and search posts from a step.",
+  type: "module",
+  license: "MIT",
+  author: "Javier Canizalez <javier-canizalez@outlook.com>",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/vorn-run/connectors.git",
+    directory: "packages/x"
+  },
+  keywords: [
+    "vorn",
+    "connector",
+    "x",
+    "twitter",
+    "mcp"
+  ],
+  bin: {
+    "vorn-connector-x": "dist/index.js"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc --noEmit",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@vornrun/connector-sdk": "^0.7.0-beta.14"
+  },
+  devDependencies: {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    tsup: "^8.5.1",
+    typescript: "^6.0.3",
+    vitest: "^4.1.10"
+  },
+  vorn: {
+    category: "Social",
+    keywords: [
+      "x",
+      "twitter",
+      "posts",
+      "tweets",
+      "mentions",
+      "social"
+    ],
+    auth: "Paste the four OAuth 1.0a credentials of an X developer app with Read and Write permission; there is no X CLI to borrow a login from.",
+    packs: true
+  }
+};
+
+// src/connector.ts
+var MAX_POST_LENGTH = 280;
+var MENTIONS_MIN_RESULTS = 5;
+var SEARCH_MIN_RESULTS = 10;
+var MAX_RESULTS = 100;
+var DEFAULT_SEARCH_RESULTS = 10;
+var MAX_QUERY_LENGTH = 512;
+var USERNAME = /^[A-Za-z0-9_]{1,15}$/;
+var CONSOLE_URL = "https://developer.x.com/en/portal/dashboard";
+var ACCESS_NOTE = "Metered per request and per post read; see the README for the price and the rate limit of each call.";
+function text(value) {
+  const trimmed = String(value ?? "").trim();
+  return trimmed || void 0;
+}
+function required(config, key, env) {
+  const value = text(config[key]);
+  if (value === void 0) throw new Error(`${env} is required`);
+  return value;
+}
+function postText(value) {
+  const body = String(value ?? "");
+  const length = Array.from(body).length;
+  if (body.trim() === "") throw new Error("Post text is required");
+  if (length > MAX_POST_LENGTH) {
+    throw new Error(`Post text is ${length} characters; the limit is ${MAX_POST_LENGTH} for non-Premium accounts`);
+  }
+  return body;
+}
+function pageSize(value, floor, fallback) {
+  const raw = text(value);
+  if (raw === void 0) return fallback;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed)) throw new Error(`maxResults must be a whole number between ${floor} and ${MAX_RESULTS}`);
+  if (parsed > MAX_RESULTS) throw new Error(`maxResults must be at most ${MAX_RESULTS}`);
+  return Math.max(floor, parsed);
+}
+function searchQuery(value) {
+  const query = text(value);
+  if (query === void 0) throw new Error("query is required");
+  if (query.length > MAX_QUERY_LENGTH) {
+    throw new Error(`query is ${query.length} characters; recent search accepts at most ${MAX_QUERY_LENGTH}`);
+  }
+  return query;
+}
+function handle(value) {
+  const username = text(value)?.replace(/^@/, "");
+  if (username === void 0 || !USERNAME.test(username)) {
+    throw new Error("username must be 1 to 15 letters, digits or underscores, without the @");
+  }
+  return username;
+}
+function postId(value, key) {
+  const id = text(value);
+  if (id === void 0) throw new Error(`${key} is required`);
+  return id;
+}
+function postsOf(envelope) {
+  const posts = Array.isArray(envelope.data) ? envelope.data : [];
+  return posts.map((post) => joinAuthor(post, envelope.includes?.users));
+}
+function createdOutput(envelope) {
+  const id = envelope.data?.id ?? "";
+  return { id, url: id ? postUrl(id) : "", text: envelope.data?.text ?? "" };
+}
+function createXConnector(options = {}) {
+  const clock = options.now ?? Date.now;
+  const clients = /* @__PURE__ */ new Map();
+  function client(context) {
+    const credentials = {
+      consumerKey: required(context.config, "apiKey", "X_API_KEY"),
+      consumerSecret: required(context.config, "apiSecret", "X_API_SECRET"),
+      token: required(context.config, "accessToken", "X_ACCESS_TOKEN"),
+      tokenSecret: required(context.config, "accessTokenSecret", "X_ACCESS_TOKEN_SECRET")
+    };
+    const key = Object.values(credentials).join("\n");
+    const cached = clients.get(key);
+    if (cached) {
+      cached.setFetch(context.fetch);
+      return cached;
+    }
+    const created = createXClient({
+      credentials,
+      fetch: context.fetch,
+      now: clock,
+      ...options.sleep && { sleep: options.sleep }
+    });
+    clients.set(key, created);
+    return created;
+  }
+  function pageQuery(context, floor) {
+    return {
+      since_id: context.lastItemId,
+      max_results: Math.min(MAX_RESULTS, Math.max(floor, context.limit ?? MAX_RESULTS))
+    };
+  }
+  async function fetchMentions(context) {
+    const api = client(context);
+    const me = await api.myId();
+    if (!me.id) throw new Error("GET /2/users/me returned no id for the connected account");
+    const page = await api.mentions(me.id, pageQuery(context, MENTIONS_MIN_RESULTS));
+    return postsOf(page).map(postToItem);
+  }
+  async function fetchSearch(context) {
+    const query = searchQuery(context.config.query);
+    const page = await client(context).searchRecent({ query, ...pageQuery(context, SEARCH_MIN_RESULTS) });
+    return postsOf(page).map(postToItem);
+  }
+  return defineConnector({
+    id: "x",
+    name: "X",
+    version: options.version ?? package_default.version,
+    description: "Trigger workflows from new mentions or posts matching a search on X, and create, reply to, delete, read and search posts from a step.",
+    icon: {
+      viewBox: "0 0 24 24",
+      paths: [
+        "M0 1.2H7.6L24 22.8H16.6Z M4.3 3.4H6.6L19.7 20.6H17.4Z M18.9 1.2H22.7L14.72 10.57L12.93 8.22Z M10.77 15.21L8.97 12.87L0.5 22.8H4.3Z"
+      ]
+    },
+    auth: { rung: "key", keys: ["apiKey", "apiSecret", "accessToken", "accessTokenSecret"] },
+    config: [
+      {
+        key: "apiKey",
+        label: "API key",
+        env: "X_API_KEY",
+        required: true,
+        secret: true,
+        description: "The app's API Key (OAuth 1.0a consumer key).",
+        builderHint: `${CONSOLE_URL}: Projects & Apps, the app, Keys and tokens. Shown once at creation; regenerate from the same tab.`
+      },
+      {
+        key: "apiSecret",
+        label: "API key secret",
+        env: "X_API_SECRET",
+        required: true,
+        secret: true,
+        description: "The app's API Key Secret (consumer secret).",
+        builderHint: "Same tab as the API key; half of the HMAC-SHA1 signing key."
+      },
+      {
+        key: "accessToken",
+        label: "Access token",
+        env: "X_ACCESS_TOKEN",
+        required: true,
+        secret: true,
+        description: "The Access Token generated for your own account under Keys and tokens.",
+        builderHint: "Set the app permission to Read and Write before generating it: a token made earlier stays read-only."
+      },
+      {
+        key: "accessTokenSecret",
+        label: "Access token secret",
+        env: "X_ACCESS_TOKEN_SECRET",
+        required: true,
+        secret: true,
+        description: "The Access Token Secret shown with the access token.",
+        builderHint: "Regenerated together with the access token; the other half of the signing key."
+      },
+      {
+        key: "query",
+        label: "Search query",
+        env: "X_SEARCH_QUERY",
+        description: 'Recent-search query the "new search result" trigger polls, such as `from:xdevelopers -is:retweet`.',
+        builderHint: "Only needed by newSearchResult; 1 to 512 characters of recent-search syntax, last 7 days only."
+      }
+    ],
+    triggers: [
+      {
+        type: "newMention",
+        label: "New mention",
+        description: `A post mentions the connected account. Polls the mentions timeline with since_id; a burst above ${MAX_RESULTS} mentions between polls loses the oldest. Access: 300 requests per 15 minutes per user, billed per post read (an Owned Read when the account owns the app). ${ACCESS_NOTE}`,
+        dedupe: "lastItem",
+        fetch: fetchMentions,
+        sample: [SAMPLE_ITEM],
+        defaultWorkflow: { name: "X: new mentions", defaultCronFromMinutes: 5 }
+      },
+      {
+        type: "newSearchResult",
+        label: "New search result",
+        description: `A post from the last 7 days matches the search query with since_id; a burst above ${MAX_RESULTS} matches between polls loses the oldest. Access: 300 requests per 15 minutes per user, billed per post returned; recent search is the read that used to need a paid tier. ${ACCESS_NOTE}`,
+        dedupe: "lastItem",
+        fetch: fetchSearch,
+        sample: [SAMPLE_ITEM],
+        defaultWorkflow: { name: "X: search results", defaultCronFromMinutes: 5 }
+      }
+    ],
+    actions: [
+      {
+        type: "createPost",
+        label: "Create post",
+        description: `Publish a post of up to ${MAX_POST_LENGTH} characters, optionally as a reply or a quote. Needs Read and Write permission.`,
+        idempotent: false,
+        inputs: [
+          {
+            key: "text",
+            label: "Text",
+            required: true,
+            description: `The post, up to ${MAX_POST_LENGTH} characters for non-Premium accounts.`,
+            builderHint: "Counted in code points before sending; the API may still weigh a text longer and answer 403."
+          },
+          {
+            key: "inReplyToPostId",
+            label: "In reply to post id",
+            description: "Id of the post to reply to, sent as reply.in_reply_to_tweet_id."
+          },
+          {
+            key: "quotePostId",
+            label: "Quote post id",
+            description: "Id of the post to quote, sent as quote_tweet_id; the docs say quoting needs an Enterprise plan."
+          }
+        ],
+        outputs: [
+          { key: "id", type: "string", description: "The new post id" },
+          { key: "url", type: "string", description: "https://x.com/i/status/{id}" },
+          { key: "text", type: "string", description: "The text as X stored it" }
+        ],
+        async run(args, context) {
+          const body = { text: postText(args.text) };
+          const replyTo = text(args.inReplyToPostId);
+          const quote = text(args.quotePostId);
+          if (replyTo) body.reply = { in_reply_to_tweet_id: replyTo };
+          if (quote) body.quote_tweet_id = quote;
+          return createdOutput(await client(context).createPost(body));
+        }
+      },
+      {
+        type: "replyToPost",
+        label: "Reply to post",
+        description: `Reply to a post with up to ${MAX_POST_LENGTH} characters. Needs Read and Write permission.`,
+        idempotent: false,
+        inputs: [
+          { key: "postId", label: "Post id", required: true, description: "The post being replied to." },
+          {
+            key: "text",
+            label: "Text",
+            required: true,
+            description: `The reply, up to ${MAX_POST_LENGTH} characters for non-Premium accounts.`
+          }
+        ],
+        outputs: [
+          { key: "id", type: "string", description: "The new post id" },
+          { key: "url", type: "string", description: "https://x.com/i/status/{id}" },
+          { key: "text", type: "string", description: "The text as X stored it" }
+        ],
+        async run(args, context) {
+          const body = { text: postText(args.text), reply: { in_reply_to_tweet_id: postId(args.postId, "postId") } };
+          return createdOutput(await client(context).createPost(body));
+        }
+      },
+      {
+        type: "deletePost",
+        label: "Delete post",
+        description: "Delete one of the connected account's own posts. Needs Read and Write permission.",
+        idempotent: false,
+        inputs: [{ key: "postId", label: "Post id", required: true, description: "The post to delete." }],
+        outputs: [{ key: "deleted", type: "boolean", description: "Whether X reports the post deleted" }],
+        async run(args, context) {
+          const answer = await client(context).deletePost(postId(args.postId, "postId"));
+          return { deleted: answer.data?.deleted === true };
+        }
+      },
+      {
+        type: "getMe",
+        label: "Get me",
+        description: `The connected account. Access: 75 requests per 15 minutes per user, one user read. ${ACCESS_NOTE}`,
+        idempotent: true,
+        inputs: [],
+        outputs: [
+          { key: "id", type: "string", description: "The account id" },
+          { key: "username", type: "string", description: "The handle without @" },
+          { key: "name", type: "string", description: "The display name" },
+          { key: "url", type: "string", description: "https://x.com/{username}" }
+        ],
+        sample: {},
+        async run(_args, context) {
+          const user = (await client(context).getMe()).data ?? {};
+          const username = user.username ?? "";
+          return { id: user.id ?? "", username, name: user.name ?? "", url: username ? `https://x.com/${username}` : "" };
+        }
+      },
+      {
+        type: "getPost",
+        label: "Get post",
+        description: `A post by id with its author and public metrics. Access: 900 requests per 15 minutes per user, one post read plus one user read. ${ACCESS_NOTE}`,
+        idempotent: true,
+        inputs: [{ key: "postId", label: "Post id", required: true, description: "The post to read." }],
+        outputs: [
+          { key: "id", type: "string", description: "The post id" },
+          { key: "text", type: "string", description: "The post text" },
+          { key: "createdAt", type: "string", description: "ISO 8601 creation instant" },
+          { key: "authorId", type: "string", description: "The author id" },
+          { key: "authorUsername", type: "string", description: "The author handle, when included" },
+          { key: "conversationId", type: "string", description: "The conversation (thread root) id" },
+          { key: "url", type: "string", description: "The post page" },
+          { key: "metrics", description: "public_metrics as JSON: like, reply, repost, quote, bookmark and impression counts" },
+          { key: "raw", description: "The full answer as JSON" }
+        ],
+        sample: { postId: "20" },
+        async run(args, context) {
+          const answer = await client(context).getPost(postId(args.postId, "postId"), {
+            "tweet.fields": "created_at,author_id,conversation_id,public_metrics",
+            expansions: "author_id",
+            "user.fields": "username,name"
+          });
+          const post = answer.data ?? {};
+          const record = joinAuthor(post, answer.includes?.users);
+          return {
+            id: record.id,
+            text: record.text,
+            createdAt: record.createdAt,
+            authorId: record.author.id,
+            authorUsername: record.author.username,
+            conversationId: record.conversationId,
+            url: record.url,
+            metrics: post.public_metrics ?? {},
+            raw: answer
+          };
+        }
+      },
+      {
+        type: "getUserByUsername",
+        label: "Get user by username",
+        description: `A user by handle. Access: 900 requests per 15 minutes per user, one user read. ${ACCESS_NOTE}`,
+        idempotent: true,
+        inputs: [
+          {
+            key: "username",
+            label: "Username",
+            required: true,
+            description: "The handle without @ (1 to 15 letters, digits or underscores); a leading @ is stripped."
+          }
+        ],
+        outputs: [
+          { key: "id", type: "string", description: "The user id" },
+          { key: "username", type: "string", description: "The handle" },
+          { key: "name", type: "string", description: "The display name" },
+          { key: "description", type: "string", description: "The profile bio" },
+          { key: "createdAt", type: "string", description: "ISO 8601 account creation instant" },
+          { key: "followers", type: "number", description: "public_metrics.followers_count" },
+          { key: "following", type: "number", description: "public_metrics.following_count" },
+          { key: "posts", type: "number", description: "public_metrics.tweet_count" },
+          { key: "url", type: "string", description: "https://x.com/{username}" },
+          { key: "raw", description: "The full answer as JSON" }
+        ],
+        sample: { username: "x" },
+        async run(args, context) {
+          const answer = await client(context).getUserByUsername(handle(args.username), {
+            "user.fields": `${USER_FIELDS},description,public_metrics,created_at`
+          });
+          const user = answer.data ?? {};
+          const metrics = user.public_metrics ?? {};
+          const username = user.username ?? "";
+          return {
+            id: user.id ?? "",
+            username,
+            name: user.name ?? "",
+            description: user.description ?? "",
+            createdAt: user.created_at ?? "",
+            followers: metrics.followers_count ?? 0,
+            following: metrics.following_count ?? 0,
+            posts: metrics.tweet_count ?? 0,
+            url: username ? `https://x.com/${username}` : "",
+            raw: answer
+          };
+        }
+      },
+      {
+        type: "searchRecentPosts",
+        label: "Search recent posts",
+        description: `Posts from the last 7 days matching a query, newest first. Access: 300 requests per 15 minutes per user, billed per post returned; this is the read that used to need a paid tier. ${ACCESS_NOTE}`,
+        idempotent: true,
+        inputs: [
+          {
+            key: "query",
+            label: "Query",
+            required: true,
+            description: `Recent-search query, 1 to ${MAX_QUERY_LENGTH} characters, such as from:xdevelopers -is:retweet.`
+          },
+          {
+            key: "maxResults",
+            label: "Max results",
+            type: "number",
+            description: `${SEARCH_MIN_RESULTS} to ${MAX_RESULTS}, default ${DEFAULT_SEARCH_RESULTS}; a smaller value is raised to ${SEARCH_MIN_RESULTS}.`
+          },
+          { key: "sinceId", label: "Since id", description: "Only posts with an id greater than this one." }
+        ],
+        outputs: [
+          { key: "posts", description: "JSON array of posts: id, text, createdAt, conversationId, inReplyToUserId, author, url" },
+          { key: "count", type: "number", description: "meta.result_count" },
+          { key: "newestId", type: "string", description: "meta.newest_id" },
+          { key: "nextToken", type: "string", description: "meta.next_token, for the page after this one" }
+        ],
+        sample: { query: "from:xdevelopers -is:retweet", maxResults: "10" },
+        async run(args, context) {
+          const answer = await client(context).searchRecent({
+            query: searchQuery(args.query),
+            max_results: pageSize(args.maxResults, SEARCH_MIN_RESULTS, DEFAULT_SEARCH_RESULTS),
+            since_id: text(args.sinceId)
+          });
+          return {
+            posts: postsOf(answer),
+            count: answer.meta?.result_count ?? 0,
+            newestId: answer.meta?.newest_id ?? "",
+            nextToken: answer.meta?.next_token ?? ""
+          };
+        }
+      }
+    ]
+  });
+}
+var connector = createXConnector();
+
+// src/entry.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { serveConnector } from "@vornrun/connector-sdk";
+function isEntryPoint(moduleUrl, argv = process.argv) {
+  const invoked = argv[1];
+  if (invoked === void 0) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(invoked);
+  } catch {
+    return false;
+  }
+}
+async function serveIfEntryPoint(moduleUrl, serve = serveConnector) {
+  if (!isEntryPoint(moduleUrl)) return false;
+  await serve(connector);
+  return true;
+}
+
+// src/index.ts
+var index_default = connector;
+await serveIfEntryPoint(import.meta.url);
+export {
+  connector,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@vornrun/connector-x",
+  "version": "0.1.0",
+  "description": "Trigger workflows from new mentions or posts matching a search on X, and create, reply to, delete, read and search posts from a step.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Javier Canizalez <javier-canizalez@outlook.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vorn-run/connectors.git",
+    "directory": "packages/x"
+  },
+  "keywords": [
+    "vorn",
+    "connector",
+    "x",
+    "twitter",
+    "mcp"
+  ],
+  "bin": {
+    "vorn-connector-x": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@vornrun/connector-sdk": "^0.7.0-beta.14"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "vorn": {
+    "category": "Social",
+    "keywords": [
+      "x",
+      "twitter",
+      "posts",
+      "tweets",
+      "mentions",
+      "social"
+    ],
+    "auth": "Paste the four OAuth 1.0a credentials of an X developer app with Read and Write permission; there is no X CLI to borrow a login from.",
+    "packs": true
+  }
+}