x-relay-mcp 1.1.0 → 1.3.0

package/.claude/skills/x-relay/SKILL.md

@@ -100,7 +100,40 @@ xrelay sync bookmarks|posts|all [--handle <you>] [--repair] [--max N]
 ```
 - Pulls ONLY tweets newer than the last sync (snowflake-id watermark + newest-first early-break) — never a
   full refetch. `--repair` refetches everything and patches records; `--max N` caps a run (good for a first
-  sync). `posts` needs your `--handle` once (it's remembered). Returns `{ source, added, total, watermark }`.
+  sync). `posts` auto-detects your handle from the session (override/remember with `--handle`). Returns
+  `{ source, added, total, watermark }`.
+
+### More endpoints
+
+```
+xrelay list <list-id> [--limit N]           # tweets from a Twitter List (curated sources)
+xrelay user-media <handle> [--limit N]      # a user's images/videos only (visual evidence)
+xrelay followers <handle> [--limit N]       # a user's followers   (network mapping)
+xrelay following <handle> [--limit N]       # who a user follows
+xrelay retweeters <id|url> [--limit N]      # who retweeted a tweet (amplification graph)
+xrelay likers <id|url> [--limit N]          # who liked a tweet      (engagement graph)
+xrelay quoters <id|url> [--limit N]         # tweets quoting a tweet (reactions; recency-windowed)
+xrelay trends [--woeid N] [--limit N]       # what's hot now (woeid 1 = worldwide, default)
+xrelay article <id|url>                     # a long-form X Article → Markdown
+xrelay media <id|url> [--out <dir>]         # a tweet's image/video URLs; --out downloads the files
+xrelay community <community-id> [--limit N] # a community's tweet feed (topical, moderated sub-network)
+xrelay community-info <community-id>        # community metadata: name, members, rules, topic, creator
+```
+
+- **`retweeters`/`followers`/`following`** return `{ users:[<profile>...], nextCursor }` — the
+  amplification/audience graph. Use them to answer "who is paying attention to / amplifying X".
+- **`likers`** also returns `{ users }`, but X made likes private in 2024, so it's usually **empty** for
+  tweets you don't own (only the like *count* is public — read that from the tweet's `metrics.likes`).
+- **`quoters`** is search-based (`quoted_tweet_id:`), so it's recency-windowed, not the full historical set.
+- **`trends`** is a cheap zoomed-out entry point before drilling into `search`.
+- **`article`** returns `{ id, title, markdown, url }` — the full long-form read for a finalist.
+- **`media`** returns `{ tweetId, media:[{type,url,...}], files? }`; `--out <dir>` saves the actual
+  image/video files (for OCR / transcription / multimodal analysis).
+- **`community`** returns the community's feed as a normal `{ tweets[], nextCursor }` — a focused,
+  on-topic corpus that's often higher-signal than open search for a niche. **`community-info`** returns
+  `{ name, description, memberCount, moderatorCount, rules[], topic, tags[], creator, url }`. Get the
+  `community-id` from a community URL (`x.com/i/communities/<id>`). Note: X exposes no stable endpoint for
+  a full member roster or within-community search, so those aren't provided — use the feed + `search`.
 
 ---
 
@@ -128,3 +161,28 @@ npm i -g x-relay-mcp
 ```
 Cookies are read automatically from your logged-in browser (macOS Keychain). The first run may show a one-time
 Keychain "Always Allow" prompt. Assumes a residential IP (run locally); datacenter IPs are blocked by X.
+
+### Account pool + proxy (optional — for heavy/sustained use)
+
+X rate-limits per account and blocks datacenter IPs. For deep sweeps, give the tool **several sessions, each
+behind its own residential proxy**; it transparently fails over to the next session when one hits a rate-limit
+(429) or its cookies expire — so a long research run survives a single account getting throttled. All optional;
+the default single-browser-session path needs none of this.
+
+```
+# Several accounts, each pinned to its own proxy (JSON array — the robust form):
+export XRELAY_ACCOUNTS='[
+  {"cookies":"auth_token=..; ct0=..","proxy":"http://user:pass@host1:port","label":"main"},
+  {"cookies":"auth_token=..; ct0=..","proxy":"socks5://user:pass@host2:port"}
+]'
+
+# Or a simpler newline list of cookie strings, with proxies round-robined onto them:
+export XRELAY_ACCOUNTS=$'auth_token=..; ct0=..\nauth_token=..; ct0=..'
+export XRELAY_PROXIES='http://host1:port, http://host2:port'
+
+# Single browser session, just routed through one proxy:
+export XRELAY_PROXY='http://user:pass@host:port'
+```
+
+Rotation triggers on `RATE_LIMITED` / `AUTH_FAILED` only; other errors fail fast. Pair an equal number of
+accounts and proxies for a clean 1:1 mapping. http(s) and socks proxies are both supported.

package/dist/{cli-DO7p1WNQ.d.ts → cli-DDbxyp9v.d.ts}

@@ -84,6 +84,55 @@ type ThreadResult = {
     nextCursor?: string;
 };
 type SearchProduct$1 = 'Top' | 'Latest' | 'Media' | 'People';
+/** A paginated set of users (followers / following / retweeters / likers). */
+type UserPage = {
+    users: UserProfile[];
+    nextCursor?: string;
+};
+/** A trending topic. */
+type Trend = {
+    name: string;
+    rank?: number;
+    /** Volume blurb as X reports it, e.g. "42.1K posts". */
+    volume?: string;
+    url?: string;
+};
+/** A downloadable media asset attached to a tweet. */
+type MediaItem = {
+    type: MediaKind;
+    url: string;
+    thumbnail?: string;
+    width?: number;
+    height?: number;
+    durationMs?: number;
+    bitrate?: number;
+};
+/** A long-form X Article rendered to Markdown. */
+type Article = {
+    id: string;
+    title: string;
+    markdown: string;
+    url: string;
+    author?: Author;
+};
+/** An X Community's metadata (the `community-info` command). */
+type Community = {
+    id: string;
+    name: string;
+    description?: string;
+    memberCount?: number;
+    moderatorCount?: number;
+    /** ISO timestamp (X reports created_at as epoch ms). */
+    createdAt?: string;
+    /** The viewer's role in the community (Member / Moderator / Admin / NonMember). */
+    role?: string;
+    joinPolicy?: string;
+    topic?: string;
+    rules?: string[];
+    tags?: string[];
+    creator?: Author;
+    url: string;
+};
 
 /** The two load-bearing cookies, plus any others the jar carries. */
 type Cookies = {
@@ -150,6 +199,30 @@ declare const OPS: {
         readonly queryId: "7UuJsFvnWuZo0HmxrzU42Q";
         readonly operationName: "ListLatestTweetsTimeline";
     };
+    readonly Retweeters: {
+        readonly queryId: "TZsWuSj7vGmncVnq7KWDUQ";
+        readonly operationName: "Retweeters";
+    };
+    readonly Favoriters: {
+        readonly queryId: "LLkw5EcVutJL6y-2gkz22A";
+        readonly operationName: "Favoriters";
+    };
+    readonly GenericTimelineById: {
+        readonly queryId: "_dGVIf1cY6xFanFNPsAzPQ";
+        readonly operationName: "GenericTimelineById";
+    };
+    readonly TweetResultByRestId: {
+        readonly queryId: "Xl5pC_lBk_gcO2ItU39DQw";
+        readonly operationName: "TweetResultByRestId";
+    };
+    readonly CommunityByRestId: {
+        readonly queryId: "vLS7mhOqMLtGZdXqFP1DEg";
+        readonly operationName: "CommunityByRestId";
+    };
+    readonly CommunityTweetsTimeline: {
+        readonly queryId: "pXYASW5kVylF3YMrGJovLg";
+        readonly operationName: "CommunityTweetsTimeline";
+    };
 };
 type OpName = keyof typeof OPS;
 type Vars = Record<string, unknown>;
@@ -204,8 +277,23 @@ interface Engine {
     search(query: string, opts?: SearchOpts): Promise<SearchResult>;
     user(handle: string): Promise<UserProfile | null>;
     userTweets(handle: string, opts?: UserTweetsOpts): Promise<TweetPage>;
+    userMedia(handle: string, opts?: PageOpts): Promise<TweetPage>;
     bookmarks(opts?: PageOpts): Promise<TweetPage>;
     thread(id: string): Promise<ThreadResult>;
+    list(listId: string, opts?: PageOpts): Promise<TweetPage>;
+    followers(handle: string, opts?: PageOpts): Promise<UserPage>;
+    following(handle: string, opts?: PageOpts): Promise<UserPage>;
+    retweeters(tweetId: string, opts?: PageOpts): Promise<UserPage>;
+    likers(tweetId: string, opts?: PageOpts): Promise<UserPage>;
+    quoters(tweetId: string, opts?: SearchOpts): Promise<SearchResult>;
+    trends(opts?: {
+        woeid?: number;
+        limit?: number;
+    }): Promise<Trend[]>;
+    article(tweetId: string): Promise<Article | null>;
+    media(tweetId: string): Promise<MediaItem[]>;
+    community(communityId: string, opts?: PageOpts): Promise<TweetPage>;
+    communityInfo(communityId: string): Promise<Community | null>;
     /** The authenticated user's own @handle (from the session), or null. Memoized. */
     me(): Promise<string | null>;
 }
@@ -217,6 +305,8 @@ interface EngineDeps {
     sleep?: (ms: number) => Promise<void>;
     /** Injectable transport (tests). Defaults to a real client over the X API. */
     client?: EngineClient;
+    /** Injectable transport lanes (tests) — drives account-pool rotation. Overrides `client`. */
+    clients?: EngineClient[];
     /** Injectable transaction provider (tests). Defaults to the xctid generator. */
     transaction?: TransactionProvider;
 }
@@ -233,4 +323,4 @@ declare function parseArgs(argv: string[]): ParsedArgs;
 declare function dispatch(parsed: ParsedArgs, engine: Engine): Promise<Envelope<unknown>>;
 declare function run(argv: string[], engine?: Engine): Promise<number>;
 
-export { type Author as A, type Cookies as C, type Err as E, type MediaKind as M, type Ok as O, type PageOpts as P, type SearchProduct as S, type Tweet as T, type UserProfile as U, type Engine as a, type Envelope as b, type TweetPage as c, type SearchResult as d, type ThreadResult as e, type EngineDeps as f, EngineError as g, type Metrics as h, type SearchOpts as i, type SearchProduct$1 as j, type UserTweetsOpts as k, createEngine as l, dispatch as m, parseCookies as n, type ParsedArgs as o, parseArgs as p, run as r };
+export { type Article as A, type Cookies as C, type Err as E, type MediaItem as M, type Ok as O, type PageOpts as P, type SearchResult as S, type Tweet as T, type UserPage as U, type Engine as a, type Envelope as b, type TweetPage as c, type SearchProduct as d, type ThreadResult as e, type Trend as f, type UserProfile as g, type Author as h, type Community as i, type EngineDeps as j, EngineError as k, type MediaKind as l, type Metrics as m, type SearchOpts as n, type SearchProduct$1 as o, type UserTweetsOpts as p, createEngine as q, dispatch as r, parseArgs as s, parseCookies as t, run as u, type ParsedArgs as v };

package/dist/cli.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export { o as ParsedArgs, m as dispatch, p as parseArgs, r as run } from './cli-DO7p1WNQ.js';
+export { v as ParsedArgs, r as dispatch, s as parseArgs, u as run } from './cli-DDbxyp9v.js';