apitweet-cli 0.1.1

package/src/config.js

@@ -0,0 +1,301 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { CONFIG_FILE_NAME, DEFAULT_BASE_URL, DEFAULT_CONFIG } from "./constants.js";
+import { exitWithError, findOption, hasFlag, maskSecret, printJson, sanitizeForOutput } from "./utils.js";
+
+export function configFilePath(configDir) {
+  return path.join(configDir, CONFIG_FILE_NAME);
+}
+
+export async function loadConfig(configDir) {
+  try {
+    const contents = await fs.readFile(configFilePath(configDir), "utf8");
+    const parsed = JSON.parse(contents);
+    return {
+      ...structuredClone(DEFAULT_CONFIG),
+      ...parsed,
+      apps: parsed.apps || {},
+      profiles: parsed.profiles || {},
+    };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return structuredClone(DEFAULT_CONFIG);
+    }
+    exitWithError("Failed to load config.", error.message);
+  }
+}
+
+export async function saveConfig(configDir, config) {
+  await fs.mkdir(configDir, { recursive: true });
+  await fs.writeFile(configFilePath(configDir), `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+export function printConfigSummary(configDir, config) {
+  const display = {
+    configDir,
+    currentApp: config.currentApp || null,
+    currentProfile: config.currentProfile || null,
+    apps: Object.fromEntries(
+      Object.entries(config.apps).map(([name, app]) => [
+        name,
+        {
+          baseUrl: app.baseUrl,
+          apiKey: maskSecret(app.apiKey),
+        },
+      ]),
+    ),
+    profiles: Object.fromEntries(
+      Object.entries(config.profiles).map(([name, profile]) => [
+        name,
+        {
+          cookie: profile.cookie ? maskSecret(profile.cookie) : "",
+          authToken: profile.authToken ? maskSecret(profile.authToken) : "",
+          ct0: profile.ct0 ? maskSecret(profile.ct0) : "",
+        },
+      ]),
+    ),
+  };
+
+  printJson(display);
+}
+
+export function resolveAppState(state, config) {
+  const configuredApp = state.appName
+    ? config.apps[state.appName]
+    : config.currentApp
+      ? config.apps[config.currentApp]
+      : null;
+
+  if (state.appName && !configuredApp) {
+    exitWithError(`Unknown app profile: ${state.appName}`);
+  }
+
+  return {
+    appName: state.appName || config.currentApp || "",
+    apiKey: state.apiKey || process.env.APITWEET_KEY || configuredApp?.apiKey || "",
+    baseUrl: (
+      state.baseUrl ||
+      process.env.APITWEET_BASE_URL ||
+      configuredApp?.baseUrl ||
+      DEFAULT_BASE_URL
+    ).replace(/\/+$/, ""),
+  };
+}
+
+export function resolveProfile(config, preferredName) {
+  const profileName = preferredName || config.currentProfile || "";
+  if (!profileName) {
+    return { profileName: "", profile: null };
+  }
+
+  const profile = config.profiles[profileName];
+  if (!profile) {
+    exitWithError(`Unknown profile: ${profileName}`);
+  }
+
+  return { profileName, profile };
+}
+
+export function profileCredential(profile) {
+  if (!profile) {
+    return "";
+  }
+  if (profile.cookie) {
+    return profile.cookie;
+  }
+  if (profile.authToken && profile.ct0) {
+    return `ct0=${profile.ct0}; auth_token=${profile.authToken}`;
+  }
+  if (profile.authToken) {
+    return profile.authToken;
+  }
+  return "";
+}
+
+export function resolveCookieArg(args, state, config, required = true) {
+  const explicitCookie = findOption(args, "--cookie");
+  if (explicitCookie) {
+    return explicitCookie;
+  }
+
+  const explicitProfile = findOption(args, "--profile") || state.profileName;
+  const { profile } = resolveProfile(config, explicitProfile);
+  const savedValue = profileCredential(profile);
+  if (savedValue) {
+    return savedValue;
+  }
+
+  if (required && !state.dryRun) {
+    exitWithError("Missing cookie/auth token.", "Pass --cookie or configure a saved profile.");
+  }
+  return "";
+}
+
+export async function handleConfigCommand(state, config, args) {
+  const action = args[1] || "show";
+  if (action === "show") {
+    printConfigSummary(state.configDir, config);
+    return;
+  }
+
+  if (action === "path") {
+    console.log(configFilePath(state.configDir));
+    return;
+  }
+
+  exitWithError("Unknown config command.", "Use: config show | config path");
+}
+
+export async function handleAuthAppsCommand(state, config, args) {
+  const action = args[2];
+
+  if (action === "add") {
+    const name = findOption(args, "--name");
+    const apiKey = findOption(args, "--api-key");
+    if (!name || !apiKey) {
+      exitWithError("Usage: apitweet auth apps add --name <name> --api-key <key> [--base-url <url>]");
+    }
+
+    const baseUrl = (findOption(args, "--base-url") || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    config.apps[name] = { apiKey, baseUrl };
+    if (!config.currentApp || hasFlag(args, "--use")) {
+      config.currentApp = name;
+    }
+    await saveConfig(state.configDir, config);
+
+    printJson({
+      saved: name,
+      currentApp: config.currentApp,
+      app: {
+        baseUrl,
+        apiKey: maskSecret(apiKey),
+      },
+    });
+    return;
+  }
+
+  if (action === "list") {
+    printJson({
+      currentApp: config.currentApp || null,
+      apps: Object.entries(config.apps).map(([name, app]) => ({
+        name,
+        isCurrent: name === config.currentApp,
+        baseUrl: app.baseUrl,
+        apiKey: maskSecret(app.apiKey),
+      })),
+    });
+    return;
+  }
+
+  if (action === "use") {
+    const name = args[3];
+    if (!name) {
+      exitWithError("Usage: apitweet auth apps use <name>");
+    }
+    if (!config.apps[name]) {
+      exitWithError(`Unknown app profile: ${name}`);
+    }
+    config.currentApp = name;
+    await saveConfig(state.configDir, config);
+    printJson({ currentApp: name });
+    return;
+  }
+
+  if (action === "remove") {
+    const name = args[3];
+    if (!name) {
+      exitWithError("Usage: apitweet auth apps remove <name>");
+    }
+    if (!config.apps[name]) {
+      exitWithError(`Unknown app profile: ${name}`);
+    }
+    delete config.apps[name];
+    if (config.currentApp === name) {
+      config.currentApp = "";
+    }
+    await saveConfig(state.configDir, config);
+    printJson({ removed: name, currentApp: config.currentApp || null });
+    return;
+  }
+
+  exitWithError("Unknown auth apps command.", "Use: add | list | use | remove");
+}
+
+export async function handleAuthProfilesCommand(state, config, args) {
+  const action = args[2];
+
+  if (action === "add") {
+    const name = findOption(args, "--name");
+    const cookie = findOption(args, "--cookie");
+    const authToken = findOption(args, "--auth-token");
+    const ct0 = findOption(args, "--ct0");
+    if (!name || (!cookie && !authToken)) {
+      exitWithError("Usage: apitweet auth profiles add --name <name> [--cookie <value> | --auth-token <value>] [--ct0 <value>]");
+    }
+
+    config.profiles[name] = {
+      ...(cookie ? { cookie } : {}),
+      ...(authToken ? { authToken } : {}),
+      ...(ct0 ? { ct0 } : {}),
+    };
+    if (!config.currentProfile || hasFlag(args, "--use")) {
+      config.currentProfile = name;
+    }
+    await saveConfig(state.configDir, config);
+
+    printJson({
+      saved: name,
+      currentProfile: config.currentProfile,
+      profile: sanitizeForOutput(config.profiles[name]),
+    });
+    return;
+  }
+
+  if (action === "list") {
+    printJson({
+      currentProfile: config.currentProfile || null,
+      profiles: Object.entries(config.profiles).map(([name, profile]) => ({
+        name,
+        isCurrent: name === config.currentProfile,
+        hasCookie: Boolean(profile.cookie),
+        hasAuthToken: Boolean(profile.authToken),
+        hasCt0: Boolean(profile.ct0),
+      })),
+    });
+    return;
+  }
+
+  if (action === "use") {
+    const name = args[3];
+    if (!name) {
+      exitWithError("Usage: apitweet auth profiles use <name>");
+    }
+    if (!config.profiles[name]) {
+      exitWithError(`Unknown profile: ${name}`);
+    }
+    config.currentProfile = name;
+    await saveConfig(state.configDir, config);
+    printJson({ currentProfile: name });
+    return;
+  }
+
+  if (action === "remove") {
+    const name = args[3];
+    if (!name) {
+      exitWithError("Usage: apitweet auth profiles remove <name>");
+    }
+    if (!config.profiles[name]) {
+      exitWithError(`Unknown profile: ${name}`);
+    }
+    delete config.profiles[name];
+    if (config.currentProfile === name) {
+      config.currentProfile = "";
+    }
+    await saveConfig(state.configDir, config);
+    printJson({ removed: name, currentProfile: config.currentProfile || null });
+    return;
+  }
+
+  exitWithError("Unknown auth profiles command.", "Use: add | list | use | remove");
+}

package/src/constants.js

@@ -0,0 +1,34 @@
+import os from "node:os";
+import path from "node:path";
+
+export const DEFAULT_BASE_URL = "https://apitweet.com";
+export const API_PATH_PREFIX = "/api";
+export const CONFIG_FILE_NAME = "config.json";
+export const DEFAULT_CONFIG_DIR =
+  process.env.APITWEET_CONFIG_DIR ||
+  path.join(os.homedir(), ".apitweet");
+export const DEFAULT_CONFIG = {
+  version: 1,
+  currentApp: "",
+  currentProfile: "",
+  apps: {},
+  profiles: {},
+};
+
+export const LEADING_GLOBAL_OPTIONS = {
+  "-X": { takesValue: true, key: "method" },
+  "--method": { takesValue: true, key: "method" },
+  "-d": { takesValue: true, key: "data" },
+  "--data": { takesValue: true, key: "data" },
+  "-H": { takesValue: true, key: "header" },
+  "--header": { takesValue: true, key: "header" },
+  "--app": { takesValue: true, key: "appName" },
+  "--profile": { takesValue: true, key: "profileName" },
+  "--api-key": { takesValue: true, key: "apiKey" },
+  "--base-url": { takesValue: true, key: "baseUrl" },
+  "--config-dir": { takesValue: true, key: "configDir" },
+  "--dry-run": { takesValue: false, key: "dryRun" },
+  "--raw": { takesValue: false, key: "raw" },
+  "-h": { takesValue: false, key: "help" },
+  "--help": { takesValue: false, key: "help" },
+};

package/src/help.js

@@ -0,0 +1,86 @@
+export function printHelp() {
+  console.log(`apitweet - command-line client for Twitter/X apitweet APIs
+
+Usage:
+  apitweet [global options] <path>                                         # Raw API request
+
+  # Twitter/X User and Search
+  apitweet [global options] users <username...>                            # Multi-user lookup
+  apitweet [global options] about <screen_name>                            # User profile details
+  apitweet [global options] search tweets <term...> [--count <n>]          # Search Twitter/X tweets
+  apitweet [global options] search users <keyword> [--count <n>]           # Search Twitter/X users
+  apitweet [global options] followers <screen_name> [--count <n>]           # List user followers
+  apitweet [global options] following <screen_name> [--count <n>]           # List users followed
+
+  # Twitter/X Lists
+  apitweet [global options] list search --query <text> [--count <n>]       # Search for lists
+  apitweet [global options] list create --name <n> --desc <t> [--private]  # Create a new list
+  apitweet [global options] list members <list_id> [--count <n>]           # List members in a list
+  apitweet [global options] list subscribers <list_id> [--count <n>]       # List list subscribers
+
+  # Twitter/X Articles and DMs
+  apitweet [global options] article markdown <tweet_id>                    # Fetch article as Markdown
+  apitweet [global options] article lookup <tweet_id...>                   # Batch article details
+  apitweet [global options] article publish-md <file.md> --title <title>   # Publish Markdown as an X article
+  apitweet [global options] dm history <username> [--max-id <id>]          # Fetch DM history
+  apitweet [global options] dm send <username> --text <content>            # Send a Direct Message
+
+  # Twitter/X Profile and Timeline
+  apitweet [global options] profile update [--name <n>] [--desc <t>] ...   # Update your profile info
+  apitweet [global options] timeline user <screen_name> [--cursor <c>]     # Fetch user timeline page
+
+  # Twitter/X Global Trending
+  apitweet [global options] trending tweets --country <country>            # Fetch global trending tweets
+
+  # Twitter/X Tweets
+  apitweet [global options] tweet create --text <c> [--media-url <u>]      # Create a new tweet
+  apitweet [global options] tweet quote --text <c> --quote-url <u>         # Quote a tweet
+  apitweet [global options] tweet lookup <tweet_id...> [--summary]         # Batch tweet lookup
+  apitweet [global options] tweet replies <tweet_id> [--count <n>]         # Fetch tweet replies
+  apitweet [global options] tweet like <tweet_id>                          # Like a tweet
+  apitweet [global options] tweet bookmark <tweet_id>                      # Bookmark a tweet
+  apitweet [global options] tweet retweet <tweet_id>                       # Retweet a tweet
+
+  # Twitter/X Actions
+  apitweet [global options] user follow <username>                         # Follow a user
+  apitweet [global options] user unfollow <username>                       # Unfollow a user
+
+  # Config and Auth
+  apitweet [global options] auth apps add --name <n> --api-key <k>         # Add an app config
+  apitweet [global options] auth profiles add --name <n> [--cookie <v>]    # Add an auth profile
+  apitweet [global options] auth cookie --auth-token <t> [--save-as <p>]   # Create profile from token
+  apitweet [global options] config show                                    # Show current config
+
+Examples:
+  apitweet --app prod users elonmusk sama
+  apitweet --profile founder tweet create --text "hello world" --media-url "https://example.com/image.jpg"
+  apitweet --app prod --profile founder article publish-md ./article.md --title "Launch Notes" --cover-image "https://example.com/cover.jpg"
+  apitweet --profile founder tweet like 1900000000000000000
+  apitweet --app prod trending tweets --country "United States" --topic "Sports" --content "NFL" --count 50
+  apitweet --app prod -X POST -d '["1900000000000000000"]' /api/twitter/tweets/lookup # Twitter/X tweet lookup
+  apitweet auth apps add --name prod --api-key "twitterx_..."
+  apitweet auth profiles add --name founder --cookie "ct0=...; auth_token=..."
+  apitweet auth cookie --auth-token "<auth_token>" --save-as founder
+  apitweet config show
+
+Global options:
+  -X, --method <METHOD>       HTTP method for generic path requests, default GET
+  -d, --data <JSON>           JSON body for generic path requests
+  -H, --header <K:V>          Extra header for generic path requests, can be repeated
+  --app <NAME>                Use a saved app config
+  --profile <NAME>            Use a saved profile config
+  --api-key <KEY>             Override API key for this request
+  --base-url <URL>            Override base URL for this request
+  --config-dir <DIR>          Override config directory, default ~/.apitweet
+  --dry-run                   Print the request payload without sending it
+  --raw                       Print response body without pretty JSON formatting
+  -h, --help                  Show help
+
+Notes:
+  Global options should be placed before the command.
+  Saved apps store API keys and base URLs.
+  Saved profiles store cookies or auth_token values for write actions.
+  Get API keys from https://apitweet.io/dashboard.
+  Copy the API key from the dashboard and save it with auth apps add.
+`);
+}

package/src/index.js

@@ -0,0 +1,15 @@
+import { loadConfig } from "./config.js";
+import { printHelp } from "./help.js";
+import { parseGlobalArgs } from "./parser.js";
+import { runCommand } from "./commands.js";
+
+export async function main(argv = process.argv.slice(2)) {
+  const state = parseGlobalArgs(argv);
+  if (state.help || state.commandArgs.length === 0) {
+    printHelp();
+    return;
+  }
+
+  const config = await loadConfig(state.configDir);
+  await runCommand(state, config);
+}

package/src/parser.js

@@ -0,0 +1,55 @@
+import { DEFAULT_CONFIG_DIR, LEADING_GLOBAL_OPTIONS } from "./constants.js";
+import { parseHeader, parseJson, exitWithError } from "./utils.js";
+
+export function parseGlobalArgs(argv) {
+  const state = {
+    method: "GET",
+    data: undefined,
+    headers: {},
+    appName: "",
+    profileName: "",
+    apiKey: "",
+    baseUrl: "",
+    configDir: DEFAULT_CONFIG_DIR,
+    dryRun: false,
+    raw: false,
+    help: false,
+    commandArgs: [],
+  };
+
+  let index = 0;
+  while (index < argv.length) {
+    const current = argv[index];
+    const descriptor = LEADING_GLOBAL_OPTIONS[current];
+    if (!descriptor) {
+      break;
+    }
+
+    if (descriptor.takesValue) {
+      const value = argv[index + 1];
+      if (!value) {
+        exitWithError(`Missing value for ${current}.`);
+      }
+
+      if (descriptor.key === "method") {
+        state.method = value.toUpperCase();
+      } else if (descriptor.key === "data") {
+        state.data = parseJson(current, value);
+      } else if (descriptor.key === "header") {
+        const [name, headerValue] = parseHeader(value);
+        state.headers[name] = headerValue;
+      } else {
+        state[descriptor.key] = value;
+      }
+
+      index += 2;
+      continue;
+    }
+
+    state[descriptor.key] = true;
+    index += 1;
+  }
+
+  state.commandArgs = argv.slice(index);
+  return state;
+}

package/src/request.js

@@ -0,0 +1,95 @@
+import { resolveAppState } from "./config.js";
+import { apiPath, exitWithError, printJson, sanitizeForOutput } from "./utils.js";
+
+export async function performRequest(state, config, request) {
+  const appState = resolveAppState(state, config);
+  if (!appState.apiKey && !state.dryRun) {
+    const guidance = [
+      "Use --api-key, set APITWEET_KEY, or configure an app with auth apps add.",
+      "Get an API key here: https://apitweet.io/dashboard",
+      'Example: apitweet auth apps add --name prod --api-key "twitterx_..."',
+    ].join("\n");
+    exitWithError("Missing API key.", guidance);
+  }
+
+  const target = apiPath(request.path);
+  const url = /^https?:\/\//i.test(target) ? target : `${appState.baseUrl}${target}`;
+  const headers = {
+    Accept: "application/json",
+    ...state.headers,
+    ...request.headers,
+  };
+
+  if (appState.apiKey) {
+    headers.Authorization = `Bearer ${appState.apiKey}`;
+  }
+
+  let body;
+  if (request.body !== undefined) {
+    headers["Content-Type"] = headers["Content-Type"] || "application/json";
+    body = headers["Content-Type"].includes("application/json")
+      ? JSON.stringify(request.body)
+      : String(request.body);
+  }
+
+  if (state.dryRun) {
+    const preview = sanitizeForOutput({
+      method: request.method,
+      url,
+      headers,
+      ...(body
+        ? {
+            body: headers["Content-Type"]?.includes("application/json") ? JSON.parse(body) : body,
+          }
+        : {}),
+    });
+    printJson(preview);
+    return { dryRun: true, data: preview };
+  }
+
+  const response = await fetch(url, {
+    method: request.method,
+    headers,
+    body,
+  });
+
+  const text = await response.text();
+  const contentType = response.headers.get("content-type") || "";
+  const isJson = contentType.includes("application/json");
+  let data = text;
+
+  if (isJson && text) {
+    try {
+      data = JSON.parse(text);
+    } catch (error) {
+      exitWithError("Failed to parse JSON response.", error.message);
+    }
+  }
+
+  if (!response.ok) {
+    if (isJson) {
+      console.error(JSON.stringify(data, null, 2));
+    } else {
+      console.error(text);
+    }
+    process.exit(response.status || 1);
+  }
+
+  if (!request.silent) {
+    if (state.raw || !isJson) {
+      process.stdout.write(text);
+      if (!text.endsWith("\n")) {
+        process.stdout.write("\n");
+      }
+    } else {
+      printJson(data);
+    }
+  }
+
+  return {
+    response,
+    text,
+    isJson,
+    data,
+  };
+}