@spectratools/xapi-cli 0.2.1 → 0.2.3

package/dist/cli.js

@@ -1,10 +1,115 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { realpathSync } from "fs";
+import { readFileSync, realpathSync } from "fs";
+import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { Cli as Cli7 } from "incur";
 
+// src/auth.ts
+import { HttpError } from "@spectratools/cli-shared";
+import { z } from "incur";
+var bearerTokenSchema = z.string().describe("X app-only bearer token (read-only endpoints)");
+var accessTokenSchema = z.string().describe("X OAuth 2.0 user access token (required for write endpoints)");
+var xApiReadEnv = z.object({
+  X_BEARER_TOKEN: bearerTokenSchema.optional(),
+  X_ACCESS_TOKEN: accessTokenSchema.optional()
+}).refine((env) => Boolean(env.X_ACCESS_TOKEN || env.X_BEARER_TOKEN), {
+  message: "Set X_ACCESS_TOKEN or X_BEARER_TOKEN to authenticate X API requests."
+});
+var xApiWriteEnv = z.object({
+  X_ACCESS_TOKEN: accessTokenSchema,
+  X_BEARER_TOKEN: bearerTokenSchema.optional()
+});
+function readAuthToken(env) {
+  if (env.X_ACCESS_TOKEN) {
+    return env.X_ACCESS_TOKEN;
+  }
+  return env.X_BEARER_TOKEN;
+}
+function writeAuthToken(env) {
+  return env.X_ACCESS_TOKEN;
+}
+function parseXApiErrorDetail(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed !== "object" || parsed === null) {
+      return void 0;
+    }
+    const candidate = parsed;
+    if (typeof candidate.detail === "string" && candidate.detail.trim()) return candidate.detail;
+    if (typeof candidate.title === "string" && candidate.title.trim()) return candidate.title;
+    const firstError = candidate.errors?.[0];
+    if (typeof firstError?.message === "string" && firstError.message.trim())
+      return firstError.message;
+    if (typeof firstError?.detail === "string" && firstError.detail.trim())
+      return firstError.detail;
+  } catch {
+  }
+  return void 0;
+}
+function readEndpointNeedsUserToken(detail) {
+  if (!detail) return false;
+  const normalized = detail.toLowerCase();
+  return normalized.includes("application-only is forbidden") || normalized.includes("oauth 2.0 application-only") || normalized.includes("app-only") || normalized.includes("user context");
+}
+function toReadAuthError(operation, error) {
+  if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
+    const detail = parseXApiErrorDetail(error.body);
+    const requiresUserToken = readEndpointNeedsUserToken(detail);
+    return {
+      code: "INSUFFICIENT_READ_AUTH",
+      message: [
+        "Insufficient auth for read endpoint:",
+        `- operation: ${operation}`,
+        `- status: ${error.status} ${error.statusText}`,
+        requiresUserToken ? "- required auth: X_ACCESS_TOKEN (OAuth 2.0 user token required for this endpoint)" : "- required auth: X_ACCESS_TOKEN or X_BEARER_TOKEN (with required read scopes)",
+        ...detail ? [`- x_api_detail: ${detail}`] : []
+      ].join("\n")
+    };
+  }
+  return void 0;
+}
+function toWriteAuthError(operation, error) {
+  if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
+    const detail = parseXApiErrorDetail(error.body);
+    return {
+      code: "INSUFFICIENT_WRITE_AUTH",
+      message: [
+        "Insufficient auth for write endpoint:",
+        `- operation: ${operation}`,
+        `- status: ${error.status} ${error.statusText}`,
+        "- required auth: X_ACCESS_TOKEN (OAuth 2.0 user token with write scopes)",
+        "- note: app-only X_BEARER_TOKEN cannot perform write actions",
+        ...detail ? [`- x_api_detail: ${detail}`] : []
+      ].join("\n")
+    };
+  }
+  return void 0;
+}
+function toXApiHttpError(operation, error) {
+  if (!(error instanceof HttpError)) {
+    return void 0;
+  }
+  const detail = parseXApiErrorDetail(error.body);
+  return {
+    code: "X_API_REQUEST_FAILED",
+    message: [
+      "X API request failed:",
+      `- operation: ${operation}`,
+      `- status: ${error.status} ${error.statusText}`,
+      ...detail ? [`- x_api_detail: ${detail}`] : []
+    ].join("\n")
+  };
+}
+function toXApiCommandError(operation, error, authScope = "read") {
+  const authError = authScope === "write" ? toWriteAuthError(operation, error) : toReadAuthError(operation, error);
+  if (authError) {
+    return authError;
+  }
+  return toXApiHttpError(operation, error);
+}
+
 // src/commands/dm.ts
 import { Cli, z as z2 } from "incur";
 
@@ -231,66 +336,6 @@ function truncateText(text, max = 100) {
   return `${text.slice(0, max - 3)}...`;
 }
 
-// src/auth.ts
-import { HttpError } from "@spectratools/cli-shared";
-import { z } from "incur";
-var bearerTokenSchema = z.string().describe("X app-only bearer token (read-only endpoints)");
-var accessTokenSchema = z.string().describe("X OAuth 2.0 user access token (required for write endpoints)");
-var xApiReadEnv = z.object({
-  X_BEARER_TOKEN: bearerTokenSchema.optional(),
-  X_ACCESS_TOKEN: accessTokenSchema.optional()
-}).refine((env) => Boolean(env.X_ACCESS_TOKEN || env.X_BEARER_TOKEN), {
-  message: "Set X_ACCESS_TOKEN or X_BEARER_TOKEN to authenticate X API requests."
-});
-var xApiWriteEnv = z.object({
-  X_ACCESS_TOKEN: accessTokenSchema,
-  X_BEARER_TOKEN: bearerTokenSchema.optional()
-});
-function readAuthToken(env) {
-  if (env.X_ACCESS_TOKEN) {
-    return env.X_ACCESS_TOKEN;
-  }
-  return env.X_BEARER_TOKEN;
-}
-function writeAuthToken(env) {
-  return env.X_ACCESS_TOKEN;
-}
-function parseXApiErrorDetail(body) {
-  try {
-    const parsed = JSON.parse(body);
-    if (typeof parsed !== "object" || parsed === null) {
-      return void 0;
-    }
-    const candidate = parsed;
-    if (typeof candidate.detail === "string" && candidate.detail.trim()) return candidate.detail;
-    if (typeof candidate.title === "string" && candidate.title.trim()) return candidate.title;
-    const firstError = candidate.errors?.[0];
-    if (typeof firstError?.message === "string" && firstError.message.trim())
-      return firstError.message;
-    if (typeof firstError?.detail === "string" && firstError.detail.trim())
-      return firstError.detail;
-  } catch {
-  }
-  return void 0;
-}
-function toWriteAuthError(operation, error) {
-  if (error instanceof HttpError && (error.status === 401 || error.status === 403)) {
-    const detail = parseXApiErrorDetail(error.body);
-    return {
-      code: "INSUFFICIENT_WRITE_AUTH",
-      message: [
-        "Insufficient auth for write endpoint:",
-        `- operation: ${operation}`,
-        `- status: ${error.status} ${error.statusText}`,
-        "- required auth: X_ACCESS_TOKEN (OAuth 2.0 user token with write scopes)",
-        "- note: app-only X_BEARER_TOKEN cannot perform write actions",
-        ...detail ? [`- x_api_detail: ${detail}`] : []
-      ].join("\n")
-    };
-  }
-  return void 0;
-}
-
 // src/collect-paged.ts
 import { paginateCursor } from "@spectratools/cli-shared";
 async function collectPaged(fetchFn, mapFn, maxResults, pageSize = 100) {
@@ -349,7 +394,7 @@ dm.command("conversations", {
     const firstParticipant = allConvos[0]?.participant_ids[0];
     return c.ok(
       { conversations: allConvos, count: allConvos.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: firstParticipant ? {
           description: "Next steps:",
           commands: [
@@ -429,12 +474,20 @@ lists.command("get", {
         owner_id: list.owner_id,
         member_count: list.member_count
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           description: "Explore this list:",
           commands: [
-            { command: "lists members", args: { id: c.args.id }, description: "See list members" },
-            { command: "lists posts", args: { id: c.args.id }, description: "See list posts" }
+            {
+              command: "lists members",
+              args: { id: c.args.id },
+              description: "See list members"
+            },
+            {
+              command: "lists posts",
+              args: { id: c.args.id },
+              description: "See list posts"
+            }
           ]
         }
       }
@@ -518,7 +571,7 @@ lists.command("posts", {
     const firstId = allPosts[0]?.id;
     return c.ok(
       { posts: allPosts, count: allPosts.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: firstId ? {
           description: "Next steps:",
           commands: [
@@ -573,7 +626,7 @@ posts.command("get", {
         retweets: post.public_metrics?.retweet_count,
         replies: post.public_metrics?.reply_count
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           description: "Explore this post:",
           commands: [
@@ -599,7 +652,7 @@ posts.command("search", {
     query: z4.string().describe("Search query")
   }),
   options: z4.object({
-    maxResults: z4.number().default(10).describe("Maximum results to return (10\u2013100)"),
+    maxResults: z4.number().int().min(10).max(100).default(10).describe("Maximum results to return (10\u2013100)"),
     sort: z4.enum(["recency", "relevancy"]).default("recency").describe("Sort order"),
     verbose: z4.boolean().optional().describe("Show full text without truncation")
   }),
@@ -638,7 +691,7 @@ posts.command("search", {
     const firstId = items[0]?.id;
     return c.ok(
       { posts: items, count: items.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: firstId ? {
           description: "Next steps:",
           commands: [
@@ -673,18 +726,21 @@ posts.command("create", {
     try {
       const client = createXApiClient(writeAuthToken(c.env));
       const res = await client.createPost(c.options.text, c.options.replyTo, c.options.quote);
-      return c.ok(res.data, {
-        cta: {
-          description: "View your post:",
-          commands: [
-            {
-              command: "posts get",
-              args: { id: res.data.id },
-              description: "See the created post"
-            }
-          ]
+      return c.ok(
+        res.data,
+        c.format === "json" || c.format === "jsonl" ? void 0 : {
+          cta: {
+            description: "View your post:",
+            commands: [
+              {
+                command: "posts get",
+                args: { id: res.data.id },
+                description: "See the created post"
+              }
+            ]
+          }
         }
-      });
+      );
     } catch (error) {
       const authError = toWriteAuthError("posts create", error);
       if (authError) return c.error(authError);
@@ -751,7 +807,7 @@ posts.command("likes", {
     );
     return c.ok(
       { users: allUsers, count: allUsers.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           description: "Next steps:",
           commands: allUsers.slice(0, 1).map((u) => ({
@@ -851,7 +907,7 @@ timeline.command("home", {
     const firstId = allPosts[0]?.id;
     return c.ok(
       { posts: allPosts, count: allPosts.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: firstId ? {
           description: "Next steps:",
           commands: [
@@ -930,7 +986,7 @@ trends.command("places", {
     const first = places[0];
     return c.ok(
       { places, count: places.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: first ? {
           description: "Next steps:",
           commands: [
@@ -972,7 +1028,7 @@ trends.command("location", {
     const firstTrend = trendItems[0];
     return c.ok(
       { trends: trendItems, count: trendItems.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: firstTrend ? {
           description: "Next steps:",
           commands: [
@@ -1037,7 +1093,7 @@ users.command("get", {
         tweets: user.public_metrics?.tweet_count,
         joined: user.created_at ? relativeTime(user.created_at) : void 0
       },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: {
           description: "Explore this user:",
           commands: [
@@ -1179,7 +1235,7 @@ users.command("posts", {
     const firstId = allPosts[0]?.id;
     return c.ok(
       { posts: allPosts, count: allPosts.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: firstId ? {
           description: "Next steps:",
           commands: [
@@ -1262,7 +1318,7 @@ users.command("search", {
     const first = items[0];
     return c.ok(
       { users: items, count: items.length },
-      {
+      c.format === "json" || c.format === "jsonl" ? void 0 : {
         cta: first ? {
           description: "Next steps:",
           commands: [
@@ -1279,9 +1335,25 @@ users.command("search", {
 });
 
 // src/cli.ts
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync(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"]);
+cli.use(async ({ command, error }, next) => {
+  try {
+    return await next();
+  } catch (cause) {
+    const authScope = WRITE_OPERATIONS.has(command) ? "write" : "read";
+    const mapped = toXApiCommandError(command, cause, authScope);
+    if (mapped) {
+      return error(mapped);
+    }
+    throw cause;
+  }
+});
 cli.command(posts);
 cli.command(users);
 cli.command(timeline);

package/package.json

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