@spectratools/xapi-cli 0.5.0 → 0.6.1

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,24 +63,51 @@ 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 retweet 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 follow interesting_dev --format json
+xapi-cli users unfollow inactive_account --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
 xapi-cli timeline mentions --max-results 50 --format json
 
+# 4b) Timeline polling with --since-id (resume from last-seen post)
+# Store the newest post ID from the previous fetch, then pass it on the next call
+# to retrieve only new posts since that point.
+xapi-cli timeline home --since-id 1900123456789012345 --max-results 50 --format json
+xapi-cli timeline mentions --since-id 1900123456789012345 --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 get 1234567890 --format json
+xapi-cli lists add-member 1234567890 jack --format json
+xapi-cli lists remove-member 1234567890 jack --format json
+xapi-cli lists members 1234567890 --max-results 100 --format json
+xapi-cli lists posts 1234567890 --max-results 25 --format json
+xapi-cli lists delete 1234567890 --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.
+- `timeline home` and `timeline mentions` support `--since-id <post-id>` for incremental polling — only posts newer than the given ID are returned. Store the newest ID from each fetch and pass it on the next call to avoid re-processing.
+- `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. The baseline file is a newline-delimited list of follower IDs, one per line.
+- Baseline files are read-only input and are never mutated by the CLI. Your application is responsible for updating the baseline after processing new followers.
 - `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

@@ -522,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({
@@ -568,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")
@@ -608,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"),
@@ -869,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({
@@ -1376,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({
@@ -1621,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.5.0",
+  "version": "0.6.1",
   "description": "X (Twitter) API CLI for spectra-the-bot",
   "type": "module",
   "license": "MIT",