@spectratools/xapi-cli 0.2.4 → 0.4.0

package/README.md

@@ -54,10 +54,15 @@ xapi-cli trends location 1 --format json
 xapi-cli posts search "AI agents" --sort relevancy --max-results 20 --format json
 
 # 2) User intelligence pass
+xapi-cli users me --format json
 xapi-cli users get jack --format json
 xapi-cli users posts jack --max-results 20 --format json
 xapi-cli users followers jack --max-results 100 --format json
 
+# 2b) Client-side follower delta (new followers since a known baseline)
+# Baseline file format: one follower ID per line
+xapi-cli users followers jack --new-only --seen-ids-file ./seen-followers.txt --format json
+
 # 3) Moderation helper flow
 xapi-cli posts get 1234567890 --format json
 xapi-cli posts likes 1234567890 --max-results 100 --format json
@@ -75,5 +80,7 @@ xapi-cli dm send 12345 --text "hello from agent" --format json
 ## Notes
 
 - All commands support JSON output with `--format json`.
+- `users followers --new-only` performs **client-side diffing** against `--seen-ids-file`; it does not use an API-native `since_id` filter for follower deltas.
+- Baseline files are read-only input (newline-delimited follower IDs) and are never mutated by the CLI.
 - `X_BEARER_TOKEN` is for read-only app auth.
 - `X_ACCESS_TOKEN` is required for write actions (`posts create`, `posts delete`, `dm send`).

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync, realpathSync } from "fs";
+import { readFileSync as readFileSync2, realpathSync } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { Cli as Cli7 } from "incur";
@@ -186,6 +186,12 @@ function createXApiClient(bearerToken) {
       ...nextToken ? { pagination_token: nextToken } : {}
     });
   }
+  function likePost(userId, tweetId) {
+    return post(`/users/${userId}/likes`, { tweet_id: tweetId });
+  }
+  function retweetPost(userId, tweetId) {
+    return post(`/users/${userId}/retweets`, { tweet_id: tweetId });
+  }
   const USER_FIELDS = "id,name,username,description,public_metrics,created_at";
   function getUserByUsername(username) {
     return get(`/users/by/username/${username}`, {
@@ -211,6 +217,14 @@ function createXApiClient(bearerToken) {
       ...nextToken ? { pagination_token: nextToken } : {}
     });
   }
+  function followUser(sourceUserId, targetUserId) {
+    return post(`/users/${sourceUserId}/following`, {
+      target_user_id: targetUserId
+    });
+  }
+  function unfollowUser(sourceUserId, targetUserId) {
+    return del(`/users/${sourceUserId}/following/${targetUserId}`);
+  }
   function getUserPosts(id, maxResults, nextToken) {
     return get(`/users/${id}/tweets`, {
       max_results: maxResults,
@@ -231,18 +245,20 @@ function createXApiClient(bearerToken) {
       "user.fields": USER_FIELDS
     });
   }
-  function getHomeTimeline(userId, maxResults, nextToken) {
+  function getHomeTimeline(userId, maxResults, nextToken, sinceId) {
     return get(`/users/${userId}/timelines/reverse_chronological`, {
       max_results: maxResults,
       "tweet.fields": POST_FIELDS,
-      ...nextToken ? { pagination_token: nextToken } : {}
+      ...nextToken ? { pagination_token: nextToken } : {},
+      ...sinceId ? { since_id: sinceId } : {}
     });
   }
-  function getMentionsTimeline(userId, maxResults, nextToken) {
+  function getMentionsTimeline(userId, maxResults, nextToken, sinceId) {
     return get(`/users/${userId}/mentions`, {
       max_results: maxResults,
       "tweet.fields": POST_FIELDS,
-      ...nextToken ? { pagination_token: nextToken } : {}
+      ...nextToken ? { pagination_token: nextToken } : {},
+      ...sinceId ? { since_id: sinceId } : {}
     });
   }
   function getList(id) {
@@ -301,10 +317,14 @@ function createXApiClient(bearerToken) {
     deletePost,
     getPostLikes,
     getPostRetweets,
+    likePost,
+    retweetPost,
     getUserByUsername,
     getUserById,
     getUserFollowers,
     getUserFollowing,
+    followUser,
+    unfollowUser,
     getUserPosts,
     getUserMentions,
     searchUsers,
@@ -771,6 +791,54 @@ posts.command("delete", {
     }
   }
 });
+posts.command("like", {
+  description: "Like a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to like")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    liked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Like a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.likePost(me.data.id, c.args.id);
+      return c.ok({ liked: res.data.liked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts like", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("retweet", {
+  description: "Retweet a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to retweet")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    retweeted: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Retweet a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.retweetPost(me.data.id, c.args.id);
+      return c.ok({ retweeted: res.data.retweeted, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts retweet", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
 posts.command("likes", {
   description: "List users who liked a post.",
   args: z4.object({
@@ -1045,6 +1113,7 @@ trends.command("location", {
 });
 
 // src/commands/users.ts
+import { readFileSync } from "fs";
 import { Cli as Cli6, z as z7 } from "incur";
 var users = Cli6.create("users", {
   description: "Look up X users."
@@ -1055,6 +1124,79 @@ async function resolveUser(client, usernameOrId) {
   }
   return client.getUserByUsername(usernameOrId.replace(/^@/, ""));
 }
+function formatUserProfile(user, verbose) {
+  return {
+    id: user.id,
+    name: user.name,
+    username: user.username,
+    description: user.description ? verbose ? user.description : truncateText(user.description) : void 0,
+    followers: user.public_metrics?.followers_count,
+    following: user.public_metrics?.following_count,
+    tweets: user.public_metrics?.tweet_count,
+    joined: user.created_at ? relativeTime(user.created_at) : void 0
+  };
+}
+function readSeenIds(filePath) {
+  const fileContents = readFileSync(filePath, "utf8");
+  return new Set(
+    fileContents.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+  );
+}
+var followersOptionsSchema = z7.object({
+  maxResults: z7.number().default(100).describe("Maximum followers to return"),
+  seenIdsFile: z7.string().optional().describe(
+    "Path to newline-delimited follower IDs used as a baseline for client-side diffing"
+  ),
+  newOnly: z7.boolean().default(false).describe(
+    "Return only followers not found in --seen-ids-file (client-side baseline diff; not API-native since_id)"
+  )
+}).refine((options) => !options.newOnly || Boolean(options.seenIdsFile), {
+  path: ["seenIdsFile"],
+  message: "--seen-ids-file is required when --new-only is set"
+});
+users.command("me", {
+  description: "Get the authenticated user profile and metrics.",
+  options: z7.object({
+    verbose: z7.boolean().optional().describe("Show full bio without truncation")
+  }),
+  env: xApiReadEnv,
+  output: z7.object({
+    id: z7.string(),
+    name: z7.string(),
+    username: z7.string(),
+    description: z7.string().optional(),
+    followers: z7.number().optional(),
+    following: z7.number().optional(),
+    tweets: z7.number().optional(),
+    joined: z7.string().optional()
+  }),
+  examples: [{ description: "Get your authenticated profile", options: {} }],
+  async run(c) {
+    const client = createXApiClient(readAuthToken(c.env));
+    const res = await client.getMe();
+    const user = res.data;
+    return c.ok(
+      formatUserProfile(user, c.options.verbose),
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
+        cta: {
+          description: "Explore your account:",
+          commands: [
+            {
+              command: "users followers",
+              args: { username: user.username },
+              description: "View your followers"
+            },
+            {
+              command: "users posts",
+              args: { username: user.username },
+              description: "View your recent posts"
+            }
+          ]
+        }
+      }
+    );
+  }
+});
 users.command("get", {
   description: "Get a user by username or ID.",
   args: z7.object({
@@ -1083,16 +1225,7 @@ users.command("get", {
     const res = await resolveUser(client, c.args.username);
     const user = res.data;
     return c.ok(
-      {
-        id: user.id,
-        name: user.name,
-        username: user.username,
-        description: user.description ? c.options.verbose ? user.description : truncateText(user.description) : void 0,
-        followers: user.public_metrics?.followers_count,
-        following: user.public_metrics?.following_count,
-        tweets: user.public_metrics?.tweet_count,
-        joined: user.created_at ? relativeTime(user.created_at) : void 0
-      },
+      formatUserProfile(user, c.options.verbose),
       c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           description: "Explore this user:",
@@ -1113,15 +1246,77 @@ users.command("get", {
     );
   }
 });
+users.command("follow", {
+  description: "Follow a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    following: z7.boolean(),
+    pending_follow: z7.boolean().optional()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Follow @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.followUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        following: res.data.following,
+        pending_follow: res.data.pending_follow
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users follow", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("unfollow", {
+  description: "Unfollow a user by username or ID.",
+  args: z7.object({
+    username: z7.string().describe("Username (with or without @) or user ID")
+  }),
+  env: xApiWriteEnv,
+  output: z7.object({
+    id: z7.string(),
+    username: z7.string(),
+    following: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Unfollow @jack" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const targetRes = await resolveUser(client, c.args.username);
+      const target = targetRes.data;
+      const res = await client.unfollowUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        following: res.data.following
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users unfollow", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
 users.command("followers", {
-  description: "List followers of a user.",
+  description: "List followers of a user. Supports optional client-side baseline diffing for new follower detection.",
   args: z7.object({
     username: z7.string().describe("Username or user ID")
   }),
-  options: z7.object({
-    maxResults: z7.number().default(100).describe("Maximum followers to return")
-  }),
-  alias: { maxResults: "n" },
+  options: followersOptionsSchema,
+  alias: { maxResults: "n", seenIdsFile: "s" },
   env: xApiReadEnv,
   output: z7.object({
     users: z7.array(
@@ -1134,7 +1329,14 @@ users.command("followers", {
     ),
     count: z7.number()
   }),
-  examples: [{ args: { username: "jack" }, description: "List followers of jack" }],
+  examples: [
+    { args: { username: "jack" }, description: "List followers of jack" },
+    {
+      args: { username: "jack" },
+      options: { seenIdsFile: "./seen-followers.txt", newOnly: true },
+      description: "Show only followers not in your baseline file (client-side diffing; the X API does not support since_id here)"
+    }
+  ],
   async run(c) {
     const client = createXApiClient(readAuthToken(c.env));
     const userRes = await resolveUser(client, c.args.username);
@@ -1150,7 +1352,15 @@ users.command("followers", {
       c.options.maxResults,
       1e3
     );
-    return c.ok({ users: allUsers, count: allUsers.length });
+    if (!c.options.newOnly) {
+      return c.ok({ users: allUsers, count: allUsers.length });
+    }
+    if (!c.options.seenIdsFile) {
+      throw new Error("--seen-ids-file is required when --new-only is set");
+    }
+    const seenIds = readSeenIds(c.options.seenIdsFile);
+    const newUsers = allUsers.filter((user) => !seenIds.has(user.id));
+    return c.ok({ users: newUsers, count: newUsers.length });
   }
 });
 users.command("following", {
@@ -1336,12 +1546,20 @@ users.command("search", {
 
 // src/cli.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(readFileSync(resolve(__dirname, "../package.json"), "utf8"));
+var pkg = JSON.parse(readFileSync2(resolve(__dirname, "../package.json"), "utf8"));
 var cli = Cli7.create("xapi", {
   version: pkg.version,
   description: "X (Twitter) API CLI for spectra-the-bot."
 });
-var WRITE_OPERATIONS = /* @__PURE__ */ new Set(["posts create", "posts delete", "dm send"]);
+var WRITE_OPERATIONS = /* @__PURE__ */ new Set([
+  "posts create",
+  "posts delete",
+  "posts like",
+  "posts retweet",
+  "users follow",
+  "users unfollow",
+  "dm send"
+]);
 cli.use(async ({ command, error }, next) => {
   try {
     return await next();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectratools/xapi-cli",
-  "version": "0.2.4",
+  "version": "0.4.0",
   "description": "X (Twitter) API CLI for spectra-the-bot",
   "type": "module",
   "license": "MIT",