fxtwitter 2.0.0 → 2.1.0

package/README.md

@@ -13,6 +13,27 @@ Typed wrapper for the [FxTwitter](https://github.com/FxEmbed/FxEmbed) API.
 npm install fxtwitter
 ```
 
+## CLI
+
+```sh
+npx fxtwitter status 20
+npx fxtwitter status "https://x.com/jack/status/20" --pretty
+npx fxtwitter profile @jack --api v1
+npx fxtwitter search "from:jack puppies" | jq '.results'
+```
+
+The CLI uses API v2 by default. Use `--api v1` with `status` or `profile`. Search is available in v2. Profile handles can include a leading `@`.
+
+Successful commands write compact JSON to stdout. Use `--pretty` to indent it. Errors go to stderr and exit with a nonzero status.
+
+| Option | Description |
+| ------ | ----------- |
+| `--base-url <url>` | Override the API base URL |
+| `--timeout <ms>` | Set the request timeout |
+| `--retry <count>` | Set the retry count (use `0` to disable retries) |
+| `--retry-delay <ms>` | Set the delay between retries |
+| `-h, --help` | Show commands and options. Use `fxtwitter status --help` for help with a specific command |
+
 ## Usage
 
 ```ts

package/dist/LICENSE-citty

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Pooya Parsa <pooya@pi0.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/THIRD-PARTY-LICENSES-citty.md

@@ -0,0 +1,33 @@
+# Licenses of Bundled Dependencies
+
+The published artifact additionally contains code with the following licenses:
+MIT
+
+# Bundled Dependencies
+
+## scule
+
+License: MIT
+Repository: https://github.com/unjs/scule
+
+> MIT License
+> 
+> Copyright (c) Pooya Parsa <pooya@pi0.io>
+> 
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+> 
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/dist/cli.mjs

@@ -0,0 +1,880 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { defu } from "defu";
+import { FetchError, createFetch } from "ofetch";
+import { hasWindow, nodeVersion, runtime } from "std-env";
+//#region node_modules/citty/dist/_chunks/libs/scule.mjs
+const NUMBER_CHAR_RE = /\d/;
+const STR_SPLITTERS = [
+	"-",
+	"_",
+	"/",
+	"."
+];
+function isUppercase(char = "") {
+	if (NUMBER_CHAR_RE.test(char)) return;
+	return char !== char.toLowerCase();
+}
+function splitByCase(str, separators) {
+	const splitters = separators ?? STR_SPLITTERS;
+	const parts = [];
+	if (!str || typeof str !== "string") return parts;
+	let buff = "";
+	let previousUpper;
+	let previousSplitter;
+	for (const char of str) {
+		const isSplitter = splitters.includes(char);
+		if (isSplitter === true) {
+			parts.push(buff);
+			buff = "";
+			previousUpper = void 0;
+			continue;
+		}
+		const isUpper = isUppercase(char);
+		if (previousSplitter === false) {
+			if (previousUpper === false && isUpper === true) {
+				parts.push(buff);
+				buff = char;
+				previousUpper = isUpper;
+				continue;
+			}
+			if (previousUpper === true && isUpper === false && buff.length > 1) {
+				const lastChar = buff.at(-1);
+				parts.push(buff.slice(0, Math.max(0, buff.length - 1)));
+				buff = lastChar + char;
+				previousUpper = isUpper;
+				continue;
+			}
+		}
+		buff += char;
+		previousUpper = isUpper;
+		previousSplitter = isSplitter;
+	}
+	parts.push(buff);
+	return parts;
+}
+function upperFirst(str) {
+	return str ? str[0].toUpperCase() + str.slice(1) : "";
+}
+function lowerFirst(str) {
+	return str ? str[0].toLowerCase() + str.slice(1) : "";
+}
+function pascalCase(str, opts) {
+	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => upperFirst(opts?.normalize ? p.toLowerCase() : p)).join("") : "";
+}
+function camelCase(str, opts) {
+	return lowerFirst(pascalCase(str || "", opts));
+}
+function kebabCase(str, joiner) {
+	return str ? (Array.isArray(str) ? str : splitByCase(str)).map((p) => p.toLowerCase()).join(joiner ?? "-") : "";
+}
+function snakeCase(str) {
+	return kebabCase(str || "", "_");
+}
+//#endregion
+//#region node_modules/citty/dist/index.mjs
+function toArray(val) {
+	if (Array.isArray(val)) return val;
+	return val === void 0 ? [] : [val];
+}
+function formatLineColumns(lines, linePrefix = "") {
+	const maxLength = [];
+	for (const line of lines) for (const [i, element] of line.entries()) maxLength[i] = Math.max(maxLength[i] || 0, element.length);
+	return lines.map((l) => l.map((c, i) => linePrefix + c[i === 0 ? "padStart" : "padEnd"](maxLength[i])).join("  ")).join("\n");
+}
+function resolveValue(input) {
+	return typeof input === "function" ? input() : input;
+}
+var CLIError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "CLIError";
+		this.code = code;
+	}
+};
+function parseRawArgs(args = [], opts = {}) {
+	const booleans = new Set(opts.boolean || []);
+	const strings = new Set(opts.string || []);
+	const aliasMap = opts.alias || {};
+	const defaults = opts.default || {};
+	const aliasToMain = /* @__PURE__ */ new Map();
+	const mainToAliases = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(aliasMap)) {
+		const targets = value;
+		for (const target of targets) {
+			aliasToMain.set(key, target);
+			if (!mainToAliases.has(target)) mainToAliases.set(target, []);
+			mainToAliases.get(target).push(key);
+			aliasToMain.set(target, key);
+			if (!mainToAliases.has(key)) mainToAliases.set(key, []);
+			mainToAliases.get(key).push(target);
+		}
+	}
+	const options = {};
+	function getType(name) {
+		if (booleans.has(name)) return "boolean";
+		const aliases = mainToAliases.get(name) || [];
+		for (const alias of aliases) if (booleans.has(alias)) return "boolean";
+		return "string";
+	}
+	function isStringType(name) {
+		if (strings.has(name)) return true;
+		const aliases = mainToAliases.get(name) || [];
+		for (const alias of aliases) if (strings.has(alias)) return true;
+		return false;
+	}
+	const allOptions = /* @__PURE__ */ new Set([
+		...booleans,
+		...strings,
+		...Object.keys(aliasMap),
+		...Object.values(aliasMap).flat(),
+		...Object.keys(defaults)
+	]);
+	for (const name of allOptions) if (!options[name]) options[name] = {
+		type: getType(name),
+		default: defaults[name]
+	};
+	for (const [alias, main] of aliasToMain.entries()) if (alias.length === 1 && options[main] && !options[main].short) options[main].short = alias;
+	const processedArgs = [];
+	const negatedFlags = {};
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--") {
+			processedArgs.push(...args.slice(i));
+			break;
+		}
+		if (arg.startsWith("--no-")) {
+			const flagName = arg.slice(5);
+			negatedFlags[flagName] = true;
+			continue;
+		}
+		processedArgs.push(arg);
+	}
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: processedArgs,
+			options: Object.keys(options).length > 0 ? options : void 0,
+			allowPositionals: true,
+			strict: false
+		});
+	} catch {
+		parsed = {
+			values: {},
+			positionals: processedArgs
+		};
+	}
+	const out = { _: [] };
+	out._ = parsed.positionals;
+	for (const [key, value] of Object.entries(parsed.values)) {
+		let coerced = value;
+		if (getType(key) === "boolean" && typeof value === "string") coerced = value !== "false";
+		else if (isStringType(key) && typeof value === "boolean") coerced = "";
+		out[key] = coerced;
+	}
+	for (const [name] of Object.entries(negatedFlags)) {
+		out[name] = false;
+		const mainName = aliasToMain.get(name);
+		if (mainName) out[mainName] = false;
+		const aliases = mainToAliases.get(name);
+		if (aliases) for (const alias of aliases) out[alias] = false;
+	}
+	for (const [alias, main] of aliasToMain.entries()) {
+		if (out[alias] !== void 0 && out[main] === void 0) out[main] = out[alias];
+		if (out[main] !== void 0 && out[alias] === void 0) out[alias] = out[main];
+		if (out[alias] !== out[main] && defaults[main] === out[main]) out[main] = out[alias];
+	}
+	return out;
+}
+const noColor = /* @__PURE__ */ (() => {
+	const env = globalThis.process?.env ?? {};
+	return env.NO_COLOR === "1" || env.TERM === "dumb" || env.TEST || env.CI;
+})();
+const _c = (c, r = 39) => (t) => noColor ? t : `\u001B[${c}m${t}\u001B[${r}m`;
+const bold = /* @__PURE__ */ _c(1, 22);
+const cyan = /* @__PURE__ */ _c(36);
+const gray = /* @__PURE__ */ _c(90);
+const underline = /* @__PURE__ */ _c(4, 24);
+function parseArgs$1(rawArgs, argsDef) {
+	const parseOptions = {
+		boolean: [],
+		string: [],
+		alias: {},
+		default: {}
+	};
+	const args = resolveArgs(argsDef);
+	for (const arg of args) {
+		if (arg.type === "positional") continue;
+		if (arg.type === "string" || arg.type === "enum") parseOptions.string.push(arg.name);
+		else if (arg.type === "boolean") parseOptions.boolean.push(arg.name);
+		if (arg.default !== void 0) parseOptions.default[arg.name] = arg.default;
+		if (arg.alias) parseOptions.alias[arg.name] = arg.alias;
+		const camelName = camelCase(arg.name);
+		const kebabName = kebabCase(arg.name);
+		if (camelName !== arg.name || kebabName !== arg.name) {
+			const existingAliases = toArray(parseOptions.alias[arg.name] || []);
+			if (camelName !== arg.name && !existingAliases.includes(camelName)) existingAliases.push(camelName);
+			if (kebabName !== arg.name && !existingAliases.includes(kebabName)) existingAliases.push(kebabName);
+			if (existingAliases.length > 0) parseOptions.alias[arg.name] = existingAliases;
+		}
+	}
+	const parsed = parseRawArgs(rawArgs, parseOptions);
+	const [ ...positionalArguments] = parsed._;
+	const parsedArgsProxy = new Proxy(parsed, { get(target, prop) {
+		return target[prop] ?? target[camelCase(prop)] ?? target[kebabCase(prop)];
+	} });
+	for (const [, arg] of args.entries()) if (arg.type === "positional") {
+		const nextPositionalArgument = positionalArguments.shift();
+		if (nextPositionalArgument !== void 0) parsedArgsProxy[arg.name] = nextPositionalArgument;
+		else if (arg.default === void 0 && arg.required !== false) throw new CLIError(`Missing required positional argument: ${arg.name.toUpperCase()}`, "EARG");
+		else parsedArgsProxy[arg.name] = arg.default;
+	} else if (arg.type === "enum") {
+		const argument = parsedArgsProxy[arg.name];
+		const options = arg.options || [];
+		if (argument !== void 0 && options.length > 0 && !options.includes(argument)) throw new CLIError(`Invalid value for argument: ${cyan(`--${arg.name}`)} (${cyan(argument)}). Expected one of: ${options.map((o) => cyan(o)).join(", ")}.`, "EARG");
+	} else if (arg.required && parsedArgsProxy[arg.name] === void 0) throw new CLIError(`Missing required argument: --${arg.name}`, "EARG");
+	return parsedArgsProxy;
+}
+function resolveArgs(argsDef) {
+	const args = [];
+	for (const [name, argDef] of Object.entries(argsDef || {})) args.push({
+		...argDef,
+		name,
+		alias: toArray(argDef.alias)
+	});
+	return args;
+}
+const negativePrefixRe = /^no[-A-Z]/;
+async function renderUsage(cmd, parent) {
+	const cmdMeta = await resolveValue(cmd.meta || {});
+	const cmdArgs = resolveArgs(await resolveValue(cmd.args || {}));
+	const parentMeta = await resolveValue(parent?.meta || {});
+	const commandName = `${parentMeta.name ? `${parentMeta.name} ` : ""}` + (cmdMeta.name || process.argv[1]);
+	const argLines = [];
+	const posLines = [];
+	const commandsLines = [];
+	const usageLine = [];
+	for (const arg of cmdArgs) if (arg.type === "positional") {
+		const name = arg.name.toUpperCase();
+		const isRequired = arg.required !== false && arg.default === void 0;
+		posLines.push([cyan(name + renderValueHint(arg)), renderDescription(arg, isRequired)]);
+		usageLine.push(isRequired ? `<${name}>` : `[${name}]`);
+	} else {
+		const isRequired = arg.required === true && arg.default === void 0;
+		const argStr = [...(arg.alias || []).map((a) => `-${a}`), `--${arg.name}`].join(", ") + renderValueHint(arg);
+		argLines.push([cyan(argStr), renderDescription(arg, isRequired)]);
+		/**
+		* print negative boolean arg variant usage when
+		* - enabled by default or has `negativeDescription`
+		* - not prefixed with `no-` or `no[A-Z]`
+		*/
+		if (arg.type === "boolean" && (arg.default === true || arg.negativeDescription) && !negativePrefixRe.test(arg.name)) {
+			const negativeArgStr = [...(arg.alias || []).map((a) => `--no-${a}`), `--no-${arg.name}`].join(", ");
+			argLines.push([cyan(negativeArgStr), [arg.negativeDescription, isRequired ? gray("(Required)") : ""].filter(Boolean).join(" ")]);
+		}
+		if (isRequired) usageLine.push(`--${arg.name}` + renderValueHint(arg));
+	}
+	if (cmd.subCommands) {
+		const commandNames = [];
+		const subCommands = await resolveValue(cmd.subCommands);
+		for (const [name, sub] of Object.entries(subCommands)) {
+			const meta = await resolveValue((await resolveValue(sub))?.meta);
+			if (meta?.hidden) continue;
+			const aliases = toArray(meta?.alias);
+			const label = [name, ...aliases].join(", ");
+			commandsLines.push([cyan(label), meta?.description || ""]);
+			commandNames.push(name, ...aliases);
+		}
+		usageLine.push(commandNames.join("|"));
+	}
+	const usageLines = [];
+	const version = cmdMeta.version || parentMeta.version;
+	usageLines.push(gray(`${cmdMeta.description} (${commandName + (version ? ` v${version}` : "")})`), "");
+	const hasOptions = argLines.length > 0 || posLines.length > 0;
+	usageLines.push(`${underline(bold("USAGE"))} ${cyan(`${commandName}${hasOptions ? " [OPTIONS]" : ""} ${usageLine.join(" ")}`)}`, "");
+	if (posLines.length > 0) {
+		usageLines.push(underline(bold("ARGUMENTS")), "");
+		usageLines.push(formatLineColumns(posLines, "  "));
+		usageLines.push("");
+	}
+	if (argLines.length > 0) {
+		usageLines.push(underline(bold("OPTIONS")), "");
+		usageLines.push(formatLineColumns(argLines, "  "));
+		usageLines.push("");
+	}
+	if (commandsLines.length > 0) {
+		usageLines.push(underline(bold("COMMANDS")), "");
+		usageLines.push(formatLineColumns(commandsLines, "  "));
+		usageLines.push("", `Use ${cyan(`${commandName} <command> --help`)} for more information about a command.`);
+	}
+	return usageLines.filter((l) => typeof l === "string").join("\n");
+}
+function renderValueHint(arg) {
+	const valueHint = arg.valueHint ? `=<${arg.valueHint}>` : "";
+	const fallbackValueHint = valueHint || `=<${snakeCase(arg.name)}>`;
+	if (!arg.type || arg.type === "positional" || arg.type === "boolean") return valueHint;
+	if (arg.type === "enum" && arg.options?.length) return `=<${arg.options.join("|")}>`;
+	return fallbackValueHint;
+}
+function renderDescription(arg, required) {
+	const requiredHint = required ? gray("(Required)") : "";
+	const defaultHint = arg.default === void 0 ? "" : gray(`(Default: ${arg.default})`);
+	return [
+		arg.description,
+		requiredHint,
+		defaultHint
+	].filter(Boolean).join(" ");
+}
+//#endregion
+//#region src/deprecation.ts
+const emitted = /* @__PURE__ */ new Set();
+/**
+* Emits a deprecation warning once per process, the way Node's own deprecated
+* APIs (and libraries such as discord.js) do — so `--no-deprecation` and
+* `--throw-deprecation` apply, and repeated construction doesn't spam the
+* console. Falls back to `console.warn` in runtimes without
+* `process.emitWarning`.
+*/
+function emitDeprecationWarning(code, message) {
+	if (emitted.has(code)) return;
+	emitted.add(code);
+	const proc = globalThis.process;
+	if (typeof proc?.emitWarning === "function") {
+		proc.emitWarning(message, {
+			type: "DeprecationWarning",
+			code
+		});
+		return;
+	}
+	console.warn(`DeprecationWarning [${code}]: ${message}`);
+}
+//#endregion
+//#region src/errors.ts
+/** Thrown for any non-2xx response, network failure, timeout, or unparsable body. */
+var FxTwitterError = class extends Error {
+	status;
+	code;
+	body;
+	constructor(message, options = {}) {
+		super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "FxTwitterError";
+		this.status = options.status;
+		this.code = options.code;
+		this.body = options.body;
+	}
+};
+//#endregion
+//#region src/user-agent.ts
+/** Reads a version off a runtime global without assuming it exists. */
+function globalVersion(name, path) {
+	let value = globalThis[name];
+	for (const key of path) {
+		if (typeof value !== "object" || value === null) return null;
+		value = value[key];
+	}
+	return typeof value === "string" ? value : null;
+}
+function product(name, version) {
+	return version ? `${name}/${version}` : name;
+}
+/**
+* A `User-Agent` describing the runtime the request is made from, such as
+* `Node.js/22.16.0`, `Bun/1.3.0` or `Cloudflare-Workers`.
+*
+* The API requires callers to identify themselves and answers `401` otherwise.
+* Runtimes that fill the header in do so very tersely — Node sends just `node`
+* — so this states the runtime and version instead. It deliberately says
+* nothing about this package.
+*
+* Returns `null` in browsers, where `User-Agent` is a forbidden header: the
+* request carries the browser's own regardless, and setting it only logs a
+* warning.
+*/
+function environmentUserAgent() {
+	if (hasWindow) return null;
+	switch (runtime) {
+		case "node": return product("Node.js", nodeVersion);
+		case "bun": return product("Bun", globalVersion("Bun", ["version"]));
+		case "deno": return product("Deno", globalVersion("Deno", ["version", "deno"]));
+		case "workerd": return "Cloudflare-Workers";
+		case "edge-light": return "Vercel-Edge";
+		case "fastly": return "Fastly-Compute";
+		case "netlify": return "Netlify-Edge";
+		default: return runtime || null;
+	}
+}
+/** Header lookup that ignores case, as HTTP header names are case-insensitive. */
+function hasHeader(headers, name) {
+	if (!headers) return false;
+	const wanted = name.toLowerCase();
+	return Object.keys(headers).some((key) => key.toLowerCase() === wanted);
+}
+//#endregion
+//#region src/http.ts
+const DEFAULT_BASE_URL = "https://api.fxtwitter.com";
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Wraps ofetch with the conventions shared by the clients: `null` for 204
+* responses, and `FxTwitterError` for everything that fails.
+*/
+var HttpClient = class {
+	request;
+	constructor(options = {}) {
+		const headers = { ...options.headers };
+		if (!hasHeader(headers, "User-Agent")) {
+			const userAgent = environmentUserAgent();
+			if (userAgent) headers["User-Agent"] = userAgent;
+		}
+		const globalOptions = { defaults: defu({
+			baseURL: options.baseUrl,
+			headers,
+			timeout: options.timeout,
+			retry: options.retry,
+			retryDelay: options.retryDelay
+		}, { baseURL: DEFAULT_BASE_URL }) };
+		if (options.fetch) globalOptions.fetch = options.fetch;
+		this.request = createFetch(globalOptions);
+	}
+	/** Runs a GET request and returns the parsed JSON body, or `null` on a 204. */
+	async get(options) {
+		let response;
+		try {
+			response = await this.request.raw(options.path, {
+				query: options.query,
+				signal: options.signal
+			});
+		} catch (cause) {
+			throw toFxTwitterError(cause);
+		}
+		if (response.status === 204) return null;
+		const body = response._data;
+		if (!isRecord(body)) throw new FxTwitterError(nonJsonMessage(body, response.status), {
+			status: response.status,
+			body
+		});
+		return body;
+	}
+};
+function nonJsonMessage(body, status) {
+	return `Expected a JSON response but got ${typeof body === "string" ? body.trimStart().startsWith("<") ? "an HTML document" : "a plain text body" : `a ${typeof body} body`} (HTTP ${status}). The endpoint may not exist, or the request was redirected.`;
+}
+/** ofetch wraps aborts in a FetchError, so the original name lives on `cause`. */
+function isAbort(error) {
+	const names = /* @__PURE__ */ new Set(["AbortError", "TimeoutError"]);
+	if (names.has(error.name)) return true;
+	const cause = error.cause;
+	return isRecord(cause) && typeof cause.name === "string" ? names.has(cause.name) : false;
+}
+function toFxTwitterError(cause) {
+	if (cause instanceof FxTwitterError) return cause;
+	if (!(cause instanceof Error)) return new FxTwitterError("Network request failed", { cause });
+	if (isAbort(cause)) return new FxTwitterError("Request aborted or timed out", { cause });
+	if (!(cause instanceof FetchError)) return new FxTwitterError(cause.message, { cause });
+	const status = cause.status ?? cause.response?.status;
+	const data = cause.data;
+	if (isRecord(data)) return new FxTwitterError(typeof data.message === "string" ? data.message : typeof data.error === "string" ? data.error : `Request failed with HTTP ${status ?? "error"}`, {
+		status,
+		code: typeof data.code === "number" ? data.code : void 0,
+		body: data,
+		cause
+	});
+	if (data !== void 0 && status !== void 0) return new FxTwitterError(nonJsonMessage(data, status), {
+		status,
+		body: data,
+		cause
+	});
+	return new FxTwitterError(cause.message, {
+		status,
+		body: data,
+		cause
+	});
+}
+//#endregion
+//#region src/v1.ts
+/**
+* The API resolves a status from the first 2-20 digit run in the path segment,
+* and answers anything else with its embed HTML at HTTP 200 rather than JSON.
+*/
+const STATUS_ID_PATTERN = /^\d{2,20}$/;
+/**
+* Handles are matched as `\w{1,15}` upstream; anything else is redirected to
+* the project's GitHub page instead of returning JSON.
+*/
+const HANDLE_PATTERN = /^\w{1,15}$/;
+const DEPRECATION_MESSAGE = "FxTwitterV1 targets the legacy FxTwitter v1 API, which is kept only for backwards compatibility and does not receive new features. Use FxTwitterV2 (import from \"fxtwitter/v2\") instead.";
+/**
+* Client for the legacy FxTwitter v1 API.
+*
+* @deprecated Use {@link import("./v2").FxTwitterV2} instead. v1 is kept only
+* for backwards compatibility and does not receive new features.
+*/
+var FxTwitterV1 = class {
+	http;
+	constructor(options = {}) {
+		if (!options.silenceDeprecationWarning) emitDeprecationWarning("FXTWITTER_V1_DEPRECATED", DEPRECATION_MESSAGE);
+		this.http = new HttpClient(options);
+	}
+	/**
+	* Fetches a single status by its snowflake ID.
+	*
+	* `GET /status/:id`, `GET /status/:id/:language`,
+	* `GET /:handle/status/:id`, `GET /:handle/status/:id/:language`
+	*/
+	async getStatus(id, options = {}) {
+		if (!STATUS_ID_PATTERN.test(id)) throw new FxTwitterError(`Invalid status ID ${JSON.stringify(id)}: expected 2-20 digits`);
+		if (options.screenName !== void 0 && options.screenName.trim() === "") throw new FxTwitterError("screenName must not be empty");
+		const segments = [
+			options.screenName,
+			"status",
+			id,
+			options.translateTo
+		].filter((segment) => segment !== void 0);
+		return requireBody(await this.http.get({
+			path: `/${segments.map(encodeURIComponent).join("/")}`,
+			signal: options.signal
+		}));
+	}
+	/** Fetches a user profile by handle (`GET /:handle`). */
+	async getUser(screenName, options = {}) {
+		assertHandle(screenName);
+		return requireBody(await this.http.get({
+			path: `/${encodeURIComponent(screenName)}`,
+			signal: options.signal
+		}));
+	}
+};
+function assertHandle(handle) {
+	if (!HANDLE_PATTERN.test(handle)) throw new FxTwitterError(`Invalid handle ${JSON.stringify(handle)}: expected 1-15 letters, digits or underscores, without a leading @`);
+}
+/** v1 never answers 204, so an empty body here means something went wrong. */
+function requireBody(body) {
+	if (body === null) throw new FxTwitterError("The API returned an empty response");
+	return body;
+}
+//#endregion
+//#region src/v2.ts
+/**
+* Recovers the body of a 404 that carries a well-formed, empty result page,
+* which is how the list endpoints report "no results or timeline unavailable".
+*/
+function emptyPage(error) {
+	if (!(error instanceof FxTwitterError) || error.status !== 404) return null;
+	const body = error.body;
+	if (typeof body !== "object" || body === null) return null;
+	const results = body.results;
+	return Array.isArray(results) ? body : null;
+}
+/** Client for the FxTwitter/FxEmbed v2 API (https://docs.fxembed.com/api/twitter/). */
+var FxTwitterV2 = class {
+	http;
+	constructor(options = {}) {
+		this.http = new HttpClient(options);
+	}
+	/** Only `/2/profile/{handle}/statuses` can answer 204, so everything else demands a body. */
+	async get(path, query, signal) {
+		const body = await this.http.get({
+			path,
+			query,
+			signal
+		});
+		if (body === null) throw new FxTwitterError("The API returned an empty response");
+		return body;
+	}
+	/**
+	* Same as {@link get}, for the endpoints that report "no results" as a 404
+	* carrying an otherwise normal body. An empty page is a result, not an
+	* error, so it is returned rather than thrown.
+	*
+	* The API uses that same 404 for an unknown handle, which it does not
+	* distinguish from an empty timeline.
+	*/
+	async getPage(path, query, signal) {
+		try {
+			return await this.get(path, query, signal);
+		} catch (error) {
+			const page = emptyPage(error);
+			if (page) return page;
+			throw error;
+		}
+	}
+	/** `GET /2/status/{id}` — a single post by snowflake ID. */
+	getStatus(id, options = {}) {
+		return this.get(`/2/status/${encodeURIComponent(id)}`, {
+			about_account: options.aboutAccount ? "1" : void 0,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/status/{id}/reposts` — users who reposted a post. */
+	getStatusReposts(id, options = {}) {
+		return this.getPage(`/2/status/${encodeURIComponent(id)}/reposts`, {
+			count: options.count,
+			cursor: options.cursor
+		}, options.signal);
+	}
+	/** `GET /2/status/{id}/quotes` — posts quoting a post. */
+	getStatusQuotes(id, options = {}) {
+		return this.getPage(`/2/status/${encodeURIComponent(id)}/quotes`, {
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/thread/{id}` — a post with its unrolled thread. */
+	getThread(id, options = {}) {
+		return this.get(`/2/thread/${encodeURIComponent(id)}`, {
+			about_account: options.aboutAccount ? "1" : void 0,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/conversation/{id}` — a post, its thread, and ranked replies. */
+	getConversation(id, options = {}) {
+		return this.get(`/2/conversation/${encodeURIComponent(id)}`, {
+			ranking_mode: options.rankingMode,
+			cursor: options.cursor,
+			about_account: options.aboutAccount ? "1" : void 0,
+			lang: options.lang
+		}, options.signal);
+	}
+	/**
+	* `GET /2/profile/{handle}` — a user's profile. `handle` is a username
+	* without `@`, or `byUserId(id)` for a numeric user ID.
+	*/
+	getProfile(handle, options = {}) {
+		return this.get(`/2/profile/${encodeURIComponent(handle)}`, { about_account: options.aboutAccount ? "1" : void 0 }, options.signal);
+	}
+	/**
+	* `GET /2/profile/{handle}/statuses` — a user's posts. Resolves to `null`
+	* when `since` is set (without `cursor`) and nothing is newer than it.
+	*/
+	async getProfileStatuses(handle, options = {}) {
+		try {
+			return await this.http.get({
+				path: `/2/profile/${encodeURIComponent(handle)}/statuses`,
+				query: {
+					count: options.count,
+					cursor: options.cursor,
+					since: options.since,
+					with_replies: options.withReplies ? "1" : void 0,
+					groupthreads: options.groupThreads ? "1" : void 0,
+					lang: options.lang
+				},
+				signal: options.signal
+			});
+		} catch (error) {
+			const page = emptyPage(error);
+			if (page) return page;
+			throw error;
+		}
+	}
+	/** `GET /2/profile/{handle}/articles` — a user's long-form articles. */
+	getProfileArticles(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/articles`, {
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/profile/{handle}/about` — account metadata (based-in country, name changes). */
+	getProfileAbout(handle, options = {}) {
+		return this.get(`/2/profile/${encodeURIComponent(handle)}/about`, void 0, options.signal);
+	}
+	/** `GET /2/profile/{handle}/media` — a user's posts that contain media. */
+	getProfileMedia(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/media`, {
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/profile/{handle}/followers` — a user's followers. */
+	getProfileFollowers(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/followers`, {
+			count: options.count,
+			cursor: options.cursor
+		}, options.signal);
+	}
+	/** `GET /2/profile/{handle}/following` — accounts a user follows. */
+	getProfileFollowing(handle, options = {}) {
+		return this.getPage(`/2/profile/${encodeURIComponent(handle)}/following`, {
+			count: options.count,
+			cursor: options.cursor
+		}, options.signal);
+	}
+	/** `GET /2/search` — search posts. */
+	search(query, options = {}) {
+		return this.getPage("/2/search", {
+			q: query,
+			feed: options.feed,
+			count: options.count,
+			cursor: options.cursor,
+			lang: options.lang
+		}, options.signal);
+	}
+	/** `GET /2/typeahead` — search-box autocomplete suggestions. */
+	typeahead(query, options = {}) {
+		return this.get("/2/typeahead", {
+			q: query,
+			result_type: options.resultType?.join(","),
+			src: options.src
+		}, options.signal);
+	}
+	/** `GET /2/trends` — trending topics. */
+	trends(options = {}) {
+		return this.get("/2/trends", {
+			type: "trending",
+			count: options.count
+		}, options.signal);
+	}
+};
+//#endregion
+//#region src/cli.ts
+const flags = {
+	api: {
+		type: "enum",
+		options: ["v1", "v2"],
+		default: "v2",
+		description: "API version"
+	},
+	"base-url": {
+		type: "string",
+		valueHint: "url",
+		description: "Override the API base URL"
+	},
+	timeout: {
+		type: "string",
+		valueHint: "ms",
+		description: "Request timeout"
+	},
+	retry: {
+		type: "string",
+		valueHint: "count",
+		description: "Retry count (use 0 to disable retries)"
+	},
+	"retry-delay": {
+		type: "string",
+		valueHint: "ms",
+		description: "Delay between retries"
+	},
+	pretty: {
+		type: "boolean",
+		description: "Indent JSON output"
+	},
+	help: {
+		type: "boolean",
+		alias: "h",
+		description: "Show help"
+	}
+};
+const STATUS_ID = /^\d{2,20}$/;
+const STATUS_HOSTS = /* @__PURE__ */ new Set(["x.com", "twitter.com"]);
+const parseStatusId = (input) => {
+	if (STATUS_ID.test(input)) return input;
+	const url = URL.canParse(input) ? new URL(input) : null;
+	if (url && (url.protocol === "https:" || url.protocol === "http:")) {
+		const host = url.hostname.replace(/^(www|mobile)\./, "");
+		const id = /^\/(?:\w{1,15}|i\/web)\/status\/(\d{2,20})\/?$/.exec(url.pathname)?.[1];
+		if (STATUS_HOSTS.has(host) && id !== void 0) return id;
+	}
+	throw new Error("Expected a status ID (2–20 digits) or an X/Twitter status URL");
+};
+const parseBaseUrl = (input) => {
+	if (input === void 0) return void 0;
+	const url = URL.canParse(input) ? new URL(input) : null;
+	if (!url || url.protocol !== "https:" && url.protocol !== "http:") throw new Error("--base-url must be an absolute HTTP or HTTPS URL");
+	return input;
+};
+const parseNonNegativeInteger = (flag, value, max = Number.MAX_SAFE_INTEGER) => {
+	if (value === void 0) return void 0;
+	const number = Number(value);
+	if (!/^\d+$/.test(value) || !Number.isSafeInteger(number)) throw new Error(`--${flag} must be a non-negative integer`);
+	if (number > max) throw new Error(`--${flag} must be at most ${max}`);
+	return number;
+};
+const MAX_TIMER_DELAY = 2147483647;
+const commands = {
+	status: {
+		argument: "id-or-url",
+		description: "Fetch a post by ID or X/Twitter status URL",
+		run: (input, version, options) => {
+			const id = parseStatusId(input);
+			return (version === "v1" ? new FxTwitterV1(options) : new FxTwitterV2(options)).getStatus(id);
+		}
+	},
+	profile: {
+		argument: "screen-name",
+		description: "Fetch a profile by screen name",
+		run: (input, version, options) => {
+			const handle = input.replace(/^@/, "");
+			if (!handle) throw new Error("Expected a profile screen name");
+			if (version === "v1") return new FxTwitterV1(options).getUser(handle);
+			return new FxTwitterV2(options).getProfile(handle);
+		}
+	},
+	search: {
+		argument: "query",
+		description: "Search posts (v2 only)",
+		run: (input, version, options) => {
+			if (version === "v1") throw new Error("search requires API v2");
+			return new FxTwitterV2(options).search(input);
+		}
+	}
+};
+const cliMeta = {
+	name: "fxtwitter",
+	description: "Query the FxTwitter API"
+};
+const printUsage = async (...params) => {
+	console.log((await renderUsage(...params)).replace(/(--[\w-]+)=</g, "$1 <"));
+};
+const main = async (rawArgs) => {
+	const args = parseArgs$1(rawArgs, flags);
+	for (const key of Object.keys(args)) {
+		const flag = key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+		if (key !== "_" && key !== "h" && !Object.hasOwn(flags, flag)) throw new Error(`Unknown option ${JSON.stringify(key)}`);
+	}
+	const [name, input] = args._;
+	if (name === void 0 && (args.help || rawArgs.length === 0)) {
+		const subCommands = Object.fromEntries(Object.entries(commands).map(([name, { description }]) => [name, { meta: { description } }]));
+		await printUsage({
+			meta: cliMeta,
+			args: flags,
+			subCommands
+		});
+		return;
+	}
+	if (name === void 0 || !Object.hasOwn(commands, name)) throw new Error(name === void 0 ? "Expected a command. Run fxtwitter --help for usage." : `Unknown command ${JSON.stringify(name)}. Run fxtwitter --help for usage.`);
+	const command = commands[name];
+	if (args.help) {
+		await printUsage({
+			meta: {
+				name,
+				description: command.description
+			},
+			args: {
+				...flags,
+				[command.argument]: { type: "positional" }
+			}
+		}, { meta: cliMeta });
+		return;
+	}
+	if (args._.length !== 2 || !input.trim()) throw new Error(`${name} requires exactly one non-empty argument`);
+	const options = {
+		baseUrl: parseBaseUrl(args["base-url"]),
+		timeout: parseNonNegativeInteger("timeout", args.timeout, MAX_TIMER_DELAY),
+		retry: parseNonNegativeInteger("retry", args.retry),
+		retryDelay: parseNonNegativeInteger("retry-delay", args["retry-delay"], MAX_TIMER_DELAY)
+	};
+	const response = await command.run(input, args.api, options);
+	console.log(JSON.stringify(response, null, args.pretty ? 2 : void 0));
+};
+try {
+	await main(process.argv.slice(2));
+} catch (error) {
+	console.error(`fxtwitter: ${error instanceof Error ? error.message : error}`);
+	process.exitCode = 1;
+}
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fxtwitter",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Typed wrapper for the FxTwitter API.",
   "keywords": [
     "x",
@@ -20,6 +20,9 @@
   "license": "MIT",
   "author": "otoneko.",
   "type": "module",
+  "bin": {
+    "fxtwitter": "./dist/cli.mjs"
+  },
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -80,6 +83,7 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.20.1",
     "@vitest/coverage-v8": "^4.1.10",
+    "citty": "^0.2.2",
     "eslint": "^10.8.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.8.0",