@spectratools/xapi-cli 0.4.0 → 0.6.0

package/README.md

@@ -27,8 +27,8 @@ xapi-cli mcp add
 # Read-only endpoints (search, profiles, trends, list reads)
 export X_BEARER_TOKEN=your_app_bearer_token
 
-# Write endpoints (create/delete post, send DM)
-# OAuth 2.0 user context token with the required write scopes
+# Write endpoints (post interactions, list mutations, user moderation, and send DM)
+# OAuth 2.0 user context token with required write scopes
 export X_ACCESS_TOKEN=your_oauth2_user_access_token
 ```
 
@@ -38,10 +38,10 @@ Auth behavior:
 
 ## Command Group Intent Summary
 
-- `posts` — Read/search/create/delete posts and inspect social engagement
-- `users` — Profile lookup, social graph traversal, and user timelines
+- `posts` — Read/search/create/delete posts, plus like/unlike, retweet, and bookmark workflows
+- `users` — Profile lookup, social graph traversal, timelines, and follow/block/mute moderation actions
 - `timeline` — Home timeline and mention stream monitoring
-- `lists` — List discovery, member inspection, and list feed reads
+- `lists` — List lookup, creation/deletion, member management, and list feed reads
 - `trends` — Trend place discovery and per-location trend fetch
 - `dm` — Conversation listing and outbound direct messages
 
@@ -63,10 +63,18 @@ xapi-cli users followers jack --max-results 100 --format json
 # 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
+# 3) Engagement + moderation helper flow
 xapi-cli posts get 1234567890 --format json
+xapi-cli posts like 1234567890 --format json
+xapi-cli posts unlike 1234567890 --format json
+xapi-cli posts bookmark 1234567890 --format json
+xapi-cli posts unbookmark 1234567890 --format json
 xapi-cli posts likes 1234567890 --max-results 100 --format json
 xapi-cli posts retweets 1234567890 --max-results 100 --format json
+xapi-cli users block spammer123 --format json
+xapi-cli users unblock spammer123 --format json
+xapi-cli users mute noisyaccount --format json
+xapi-cli users unmute noisyaccount --format json
 
 # 4) Timeline monitor
 xapi-cli timeline home --max-results 50 --format json
@@ -75,6 +83,11 @@ xapi-cli timeline mentions --max-results 50 --format json
 # 5) DM assistant loop
 xapi-cli dm conversations --max-results 20 --format json
 xapi-cli dm send 12345 --text "hello from agent" --format json
+
+# 6) List curation loop
+xapi-cli lists create --name "Core devs" --description "Builders only" --private --format json
+xapi-cli lists add-member 1234567890 jack --format json
+xapi-cli lists members 1234567890 --max-results 100 --format json
 ```
 
 ## Notes
@@ -83,4 +96,4 @@ xapi-cli dm send 12345 --text "hello from agent" --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`).
+- `X_ACCESS_TOKEN` is required for write actions (`posts create|delete|like|unlike|bookmark|unbookmark|retweet`, `users follow|unfollow|block|unblock|mute|unmute`, `lists create|delete|add-member|remove-member`, `dm send`).

package/dist/cli.js

@@ -189,6 +189,15 @@ function createXApiClient(bearerToken) {
   function likePost(userId, tweetId) {
     return post(`/users/${userId}/likes`, { tweet_id: tweetId });
   }
+  function unlikePost(userId, tweetId) {
+    return del(`/users/${userId}/likes/${tweetId}`);
+  }
+  function bookmarkPost(userId, tweetId) {
+    return post(`/users/${userId}/bookmarks`, { tweet_id: tweetId });
+  }
+  function unbookmarkPost(userId, tweetId) {
+    return del(`/users/${userId}/bookmarks/${tweetId}`);
+  }
   function retweetPost(userId, tweetId) {
     return post(`/users/${userId}/retweets`, { tweet_id: tweetId });
   }
@@ -225,6 +234,22 @@ function createXApiClient(bearerToken) {
   function unfollowUser(sourceUserId, targetUserId) {
     return del(`/users/${sourceUserId}/following/${targetUserId}`);
   }
+  function blockUser(sourceUserId, targetUserId) {
+    return post(`/users/${sourceUserId}/blocking`, {
+      target_user_id: targetUserId
+    });
+  }
+  function unblockUser(sourceUserId, targetUserId) {
+    return del(`/users/${sourceUserId}/blocking/${targetUserId}`);
+  }
+  function muteUser(sourceUserId, targetUserId) {
+    return post(`/users/${sourceUserId}/muting`, {
+      target_user_id: targetUserId
+    });
+  }
+  function unmuteUser(sourceUserId, targetUserId) {
+    return del(`/users/${sourceUserId}/muting/${targetUserId}`);
+  }
   function getUserPosts(id, maxResults, nextToken) {
     return get(`/users/${id}/tweets`, {
       max_results: maxResults,
@@ -280,6 +305,24 @@ function createXApiClient(bearerToken) {
       ...nextToken ? { pagination_token: nextToken } : {}
     });
   }
+  function createList(name, description, isPrivate) {
+    return post("/lists", {
+      name,
+      ...description ? { description } : {},
+      ...isPrivate !== void 0 ? { private: isPrivate } : {}
+    });
+  }
+  function deleteList(id) {
+    return del(`/lists/${id}`);
+  }
+  function addListMember(id, userId) {
+    return post(`/lists/${id}/members`, {
+      user_id: userId
+    });
+  }
+  function removeListMember(id, userId) {
+    return del(`/lists/${id}/members/${userId}`);
+  }
   function getTrendingPlaces() {
     return getV1_1(
       "/trends/available.json"
@@ -318,6 +361,9 @@ function createXApiClient(bearerToken) {
     getPostLikes,
     getPostRetweets,
     likePost,
+    unlikePost,
+    bookmarkPost,
+    unbookmarkPost,
     retweetPost,
     getUserByUsername,
     getUserById,
@@ -325,6 +371,10 @@ function createXApiClient(bearerToken) {
     getUserFollowing,
     followUser,
     unfollowUser,
+    blockUser,
+    unblockUser,
+    muteUser,
+    unmuteUser,
     getUserPosts,
     getUserMentions,
     searchUsers,
@@ -333,6 +383,10 @@ function createXApiClient(bearerToken) {
     getList,
     getListMembers,
     getListPosts,
+    createList,
+    deleteList,
+    addListMember,
+    removeListMember,
     getTrendingPlaces,
     getTrendsByLocation,
     getDmConversations,
@@ -468,10 +522,28 @@ import { Cli as Cli2, z as z3 } from "incur";
 var lists = Cli2.create("lists", {
   description: "Manage and browse X lists."
 });
+var listIdSchema = z3.string().min(1).describe("List ID");
+var memberSchema = z3.string().trim().min(1).describe("Member to target (username with or without @, or user ID)");
+var createListOptionsSchema = z3.object({
+  name: z3.string().trim().min(1).max(25).describe("List name (1-25 characters)"),
+  description: z3.string().trim().min(1).max(100).optional().describe("Optional list description (1-100 characters)"),
+  private: z3.boolean().default(false).describe("Create as a private list")
+});
+async function resolveMemberTarget(client, usernameOrId) {
+  const normalized = usernameOrId.replace(/^@/, "");
+  if (/^\d+$/.test(normalized)) {
+    return { id: normalized };
+  }
+  const user = await client.getUserByUsername(normalized);
+  return {
+    id: user.data.id,
+    username: user.data.username
+  };
+}
 lists.command("get", {
   description: "Get a list by ID.",
   args: z3.object({
-    id: z3.string().describe("List ID")
+    id: listIdSchema
   }),
   env: xApiReadEnv,
   output: z3.object({
@@ -514,10 +586,180 @@ lists.command("get", {
     );
   }
 });
+lists.command("create", {
+  description: "Create a new list.",
+  options: createListOptionsSchema,
+  env: xApiWriteEnv,
+  output: z3.object({
+    id: z3.string(),
+    name: z3.string()
+  }),
+  examples: [
+    {
+      options: { name: "Core devs", description: "Builders only", private: true },
+      description: "Create a private list"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.createList(c.options.name, c.options.description, c.options.private);
+      return c.ok(
+        res.data,
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "Next steps:",
+            commands: [
+              {
+                command: "lists get",
+                args: { id: res.data.id },
+                description: "View the list details"
+              },
+              {
+                command: "lists add-member",
+                args: { id: res.data.id, member: "username-or-id" },
+                description: "Add members to the new list"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("lists create", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("delete", {
+  description: "Delete a list by ID.",
+  args: z3.object({
+    id: listIdSchema.describe("List ID to delete")
+  }),
+  env: xApiWriteEnv,
+  output: z3.object({
+    deleted: z3.boolean(),
+    id: z3.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Delete a list" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const res = await client.deleteList(c.args.id);
+      return c.ok({ deleted: res.data.deleted, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("lists delete", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("add-member", {
+  description: "Add a member to an X list.",
+  args: z3.object({
+    id: listIdSchema,
+    member: memberSchema
+  }),
+  env: xApiWriteEnv,
+  output: z3.object({
+    id: z3.string(),
+    member_id: z3.string(),
+    member_username: z3.string().optional(),
+    is_member: z3.boolean()
+  }),
+  examples: [
+    {
+      args: { id: "1234567890", member: "jack" },
+      description: "Add @jack to a list"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const member = await resolveMemberTarget(client, c.args.member);
+      const res = await client.addListMember(c.args.id, member.id);
+      return c.ok(
+        {
+          id: c.args.id,
+          member_id: member.id,
+          member_username: member.username,
+          is_member: res.data.is_member
+        },
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "Verify list membership:",
+            commands: [
+              {
+                command: "lists members",
+                args: { id: c.args.id },
+                description: "View current list members"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("lists add-member", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+lists.command("remove-member", {
+  description: "Remove a member from an X list.",
+  args: z3.object({
+    id: listIdSchema,
+    member: memberSchema
+  }),
+  env: xApiWriteEnv,
+  output: z3.object({
+    id: z3.string(),
+    member_id: z3.string(),
+    member_username: z3.string().optional(),
+    is_member: z3.boolean()
+  }),
+  examples: [
+    {
+      args: { id: "1234567890", member: "jack" },
+      description: "Remove @jack from a list"
+    }
+  ],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const member = await resolveMemberTarget(client, c.args.member);
+      const res = await client.removeListMember(c.args.id, member.id);
+      return c.ok(
+        {
+          id: c.args.id,
+          member_id: member.id,
+          member_username: member.username,
+          is_member: res.data.is_member
+        },
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "Next steps:",
+            commands: [
+              {
+                command: "lists members",
+                args: { id: c.args.id },
+                description: "Confirm updated membership"
+              }
+            ]
+          }
+        }
+      );
+    } catch (error) {
+      const authError = toWriteAuthError("lists remove-member", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
 lists.command("members", {
   description: "List members of an X list.",
   args: z3.object({
-    id: z3.string().describe("List ID")
+    id: listIdSchema
   }),
   options: z3.object({
     maxResults: z3.number().default(100).describe("Maximum members to return")
@@ -554,7 +796,7 @@ lists.command("members", {
 lists.command("posts", {
   description: "Get posts from an X list.",
   args: z3.object({
-    id: z3.string().describe("List ID")
+    id: listIdSchema
   }),
   options: z3.object({
     maxResults: z3.number().default(25).describe("Maximum posts to return"),
@@ -815,6 +1057,78 @@ posts.command("like", {
     }
   }
 });
+posts.command("unlike", {
+  description: "Unlike a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to unlike")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    liked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Unlike a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.unlikePost(me.data.id, c.args.id);
+      return c.ok({ liked: res.data.liked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts unlike", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("bookmark", {
+  description: "Bookmark a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to bookmark")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    bookmarked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Bookmark a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.bookmarkPost(me.data.id, c.args.id);
+      return c.ok({ bookmarked: res.data.bookmarked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts bookmark", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+posts.command("unbookmark", {
+  description: "Remove bookmark from a post by ID.",
+  args: z4.object({
+    id: z4.string().describe("Post ID to unbookmark")
+  }),
+  env: xApiWriteEnv,
+  output: z4.object({
+    bookmarked: z4.boolean(),
+    id: z4.string()
+  }),
+  examples: [{ args: { id: "1234567890" }, description: "Remove a bookmark from a post" }],
+  async run(c) {
+    try {
+      const client = createXApiClient(writeAuthToken(c.env));
+      const me = await client.getMe();
+      const res = await client.unbookmarkPost(me.data.id, c.args.id);
+      return c.ok({ bookmarked: res.data.bookmarked, id: c.args.id });
+    } catch (error) {
+      const authError = toWriteAuthError("posts unbookmark", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
 posts.command("retweet", {
   description: "Retweet a post by ID.",
   args: z4.object({
@@ -935,6 +1249,7 @@ timeline.command("home", {
   description: "View your home timeline.",
   options: z5.object({
     maxResults: z5.number().default(25).describe("Maximum posts to return (5\u2013100)"),
+    sinceId: z5.string().optional().describe("Only return posts newer than this post ID"),
     verbose: z5.boolean().optional().describe("Show full text without truncation")
   }),
   alias: { maxResults: "n" },
@@ -954,14 +1269,18 @@ timeline.command("home", {
   }),
   examples: [
     { description: "View your home timeline" },
-    { options: { maxResults: 50 }, description: "View 50 posts" }
+    { options: { maxResults: 50 }, description: "View 50 posts" },
+    {
+      options: { sinceId: "1900123456789012345" },
+      description: "Resume from last-seen post ID"
+    }
   ],
   async run(c) {
     const client = createXApiClient(readAuthToken(c.env));
     const meRes = await client.getMe();
     const userId = meRes.data.id;
     const allPosts = await collectPaged(
-      (limit, cursor) => client.getHomeTimeline(userId, limit, cursor),
+      (limit, cursor) => client.getHomeTimeline(userId, limit, cursor, c.options.sinceId),
       (post) => ({
         id: post.id,
         text: c.options.verbose ? post.text : truncateText(post.text),
@@ -994,6 +1313,7 @@ timeline.command("mentions", {
   description: "View your recent mentions.",
   options: z5.object({
     maxResults: z5.number().default(25).describe("Maximum mentions to return"),
+    sinceId: z5.string().optional().describe("Only return mentions newer than this post ID"),
     verbose: z5.boolean().optional().describe("Show full text without truncation")
   }),
   alias: { maxResults: "n" },
@@ -1009,13 +1329,19 @@ timeline.command("mentions", {
     ),
     count: z5.number()
   }),
-  examples: [{ description: "View your recent mentions" }],
+  examples: [
+    { description: "View your recent mentions" },
+    {
+      options: { sinceId: "1900123456789012345" },
+      description: "Resume mentions from last-seen post ID"
+    }
+  ],
   async run(c) {
     const client = createXApiClient(readAuthToken(c.env));
     const meRes = await client.getMe();
     const userId = meRes.data.id;
     const allPosts = await collectPaged(
-      (limit, cursor) => client.getMentionsTimeline(userId, limit, cursor),
+      (limit, cursor) => client.getMentionsTimeline(userId, limit, cursor, c.options.sinceId),
       (post) => ({
         id: post.id,
         text: c.options.verbose ? post.text : truncateText(post.text),
@@ -1310,6 +1636,130 @@ users.command("unfollow", {
     }
   }
 });
+users.command("block", {
+  description: "Block 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(),
+    blocking: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Block @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.blockUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        blocking: res.data.blocking
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users block", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("unblock", {
+  description: "Unblock 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(),
+    blocking: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Unblock @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.unblockUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        blocking: res.data.blocking
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users unblock", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("mute", {
+  description: "Mute 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(),
+    muting: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Mute @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.muteUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        muting: res.data.muting
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users mute", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
+users.command("unmute", {
+  description: "Unmute 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(),
+    muting: z7.boolean()
+  }),
+  examples: [{ args: { username: "jack" }, description: "Unmute @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.unmuteUser(me.data.id, target.id);
+      return c.ok({
+        id: target.id,
+        username: target.username,
+        muting: res.data.muting
+      });
+    } catch (error) {
+      const authError = toWriteAuthError("users unmute", error);
+      if (authError) return c.error(authError);
+      throw error;
+    }
+  }
+});
 users.command("followers", {
   description: "List followers of a user. Supports optional client-side baseline diffing for new follower detection.",
   args: z7.object({
@@ -1555,9 +2005,20 @@ var WRITE_OPERATIONS = /* @__PURE__ */ new Set([
   "posts create",
   "posts delete",
   "posts like",
+  "posts unlike",
+  "posts bookmark",
+  "posts unbookmark",
   "posts retweet",
   "users follow",
   "users unfollow",
+  "users block",
+  "users unblock",
+  "users mute",
+  "users unmute",
+  "lists create",
+  "lists delete",
+  "lists add-member",
+  "lists remove-member",
   "dm send"
 ]);
 cli.use(async ({ command, error }, next) => {

package/package.json

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