thecatapi-cli 0.1.1

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "thecatapi-cli",
+  "version": "0.1.1",
+  "description": "CLI for the thecatapi API",
+  "type": "module",
+  "bin": {
+    "thecatapi-cli": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target bun",
+    "dev": "bun run src/index.ts"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "picocolors": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/thecatapi-cli/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: thecatapi-cli
+description: "Manage thecatapi via CLI - images, breeds, favourites, votes, facts. Use when user mentions 'thecatapi' or wants to interact with the thecatapi API."
+category: apis
+---
+
+# thecatapi-cli
+
+## Setup
+
+If `thecatapi-cli` is not found, install and build it:
+```bash
+bun --version || curl -fsSL https://bun.sh/install | bash
+npx api2cli bundle thecatapi
+npx api2cli link thecatapi
+```
+
+`api2cli link` adds `~/.local/bin` to PATH automatically. The CLI is available in the next command.
+
+Always use `--json` flag when calling commands programmatically.
+
+## Authentication
+
+```bash
+thecatapi-cli auth set "your-api-key"
+thecatapi-cli auth test
+```
+
+Get a free API key at https://thecatapi.com/signup
+
+## Resources
+
+### images
+
+| Command | Description |
+|---------|-------------|
+| `thecatapi-cli images search --json` | Search random cat images |
+| `thecatapi-cli images search --limit 5 --has-breeds --size small --json` | Search with filters |
+| `thecatapi-cli images list --json` | List your uploaded images |
+| `thecatapi-cli images get <id> --json` | Get a specific image |
+| `thecatapi-cli images upload <file> --json` | Upload a cat image |
+| `thecatapi-cli images delete <id> --json` | Delete an uploaded image |
+
+### breeds
+
+| Command | Description |
+|---------|-------------|
+| `thecatapi-cli breeds list --json` | List all cat breeds |
+| `thecatapi-cli breeds get <id> --json` | Get breed details (e.g. abys, beng) |
+| `thecatapi-cli breeds search <query> --json` | Search breeds by name |
+| `thecatapi-cli breeds facts <id> --json` | Get facts about a breed |
+
+### favourites
+
+| Command | Description |
+|---------|-------------|
+| `thecatapi-cli favourites list --json` | List your favourited images |
+| `thecatapi-cli favourites get <id> --json` | Get a specific favourite |
+| `thecatapi-cli favourites create --image-id <id> --json` | Add image to favourites |
+| `thecatapi-cli favourites delete <id> --json` | Remove from favourites |
+
+### votes
+
+| Command | Description |
+|---------|-------------|
+| `thecatapi-cli votes list --json` | List your votes |
+| `thecatapi-cli votes get <id> --json` | Get a specific vote |
+| `thecatapi-cli votes create --image-id <id> --value 1 --json` | Vote on an image (1=up, 0=down) |
+| `thecatapi-cli votes delete <id> --json` | Delete a vote |
+
+### facts
+
+| Command | Description |
+|---------|-------------|
+| `thecatapi-cli facts list --json` | Get random cat facts |
+| `thecatapi-cli facts list --limit 10 --json` | Get multiple cat facts |
+
+## Global Flags
+
+All commands support: `--json`, `--format <text|json|csv|yaml>`, `--verbose`, `--no-color`, `--no-header`

package/src/commands/auth.ts

@@ -0,0 +1,53 @@
+import { Command } from "commander";
+import { getToken, setToken, removeToken, hasToken, maskToken } from "../lib/auth.js";
+import { client } from "../lib/client.js";
+import { log } from "../lib/logger.js";
+import { handleError } from "../lib/errors.js";
+
+export const authCommand = new Command("auth").description("Manage API authentication");
+
+authCommand
+  .command("set")
+  .description("Save your API token")
+  .argument("<token>", "Your API token")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli auth set sk-abc123xyz")
+  .action((token: string) => {
+    setToken(token);
+    log.success("Token saved securely");
+  });
+
+authCommand
+  .command("show")
+  .description("Display current token (masked by default)")
+  .option("--raw", "Show the full unmasked token")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli auth show\n  thecatapi-cli auth show --raw")
+  .action((opts: { raw?: boolean }) => {
+    if (!hasToken()) {
+      log.warn("No token configured. Run: thecatapi-cli auth set <token>");
+      return;
+    }
+    const token = getToken();
+    console.log(opts.raw ? token : `Token: ${maskToken(token)}`);
+  });
+
+authCommand
+  .command("remove")
+  .description("Delete the saved token")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli auth remove")
+  .action(() => {
+    removeToken();
+    log.success("Token removed");
+  });
+
+authCommand
+  .command("test")
+  .description("Verify your token works by making a test API call")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli auth test")
+  .action(async () => {
+    try {
+      await client.get("/");
+      log.success("Token is valid");
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/index.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env bun
+import { Command } from "commander";
+import { globalFlags } from "./lib/config.js";
+import { authCommand } from "./commands/auth.js";
+import { imagesResource } from "./resources/images.js";
+import { breedsResource } from "./resources/breeds.js";
+import { favouritesResource } from "./resources/favourites.js";
+import { votesResource } from "./resources/votes.js";
+import { factsResource } from "./resources/facts.js";
+
+const program = new Command();
+
+program
+  .name("thecatapi-cli")
+  .description("CLI for The Cat API — search cat images, browse breeds, vote, and more")
+  .version("0.1.0")
+  .option("--json", "Output as JSON", false)
+  .option("--format <fmt>", "Output format: text, json, csv, yaml", "text")
+  .option("--verbose", "Enable debug logging", false)
+  .option("--no-color", "Disable colored output")
+  .option("--no-header", "Omit table/csv headers (for piping)")
+  .hook("preAction", (_thisCmd, actionCmd) => {
+    const root = actionCmd.optsWithGlobals();
+    globalFlags.json = root.json ?? false;
+    globalFlags.format = root.format ?? "text";
+    globalFlags.verbose = root.verbose ?? false;
+    globalFlags.noColor = root.color === false;
+    globalFlags.noHeader = root.header === false;
+  });
+
+// Built-in commands
+program.addCommand(authCommand);
+
+// Resources
+program.addCommand(imagesResource);
+program.addCommand(breedsResource);
+program.addCommand(favouritesResource);
+program.addCommand(votesResource);
+program.addCommand(factsResource);
+
+program.parse();

package/src/lib/auth.ts

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync } from "fs";
+import { dirname } from "path";
+import { TOKEN_PATH, AUTH_TYPE, AUTH_HEADER, APP_CLI } from "./config.js";
+import { CliError } from "./errors.js";
+
+/** Check if a token is configured */
+export function hasToken(): boolean {
+  return existsSync(TOKEN_PATH);
+}
+
+/** Read the stored token. Throws if not configured. */
+export function getToken(): string {
+  if (!hasToken()) {
+    throw new CliError(2, "No token configured.", `Run: ${APP_CLI} auth set <token>`);
+  }
+  return readFileSync(TOKEN_PATH, "utf-8").trim();
+}
+
+/** Save a token to disk with restricted permissions (chmod 600). */
+export function setToken(token: string): void {
+  mkdirSync(dirname(TOKEN_PATH), { recursive: true });
+  writeFileSync(TOKEN_PATH, token.trim(), { mode: 0o600 });
+  // Ensure permissions even if file existed
+  chmodSync(TOKEN_PATH, 0o600);
+}
+
+/** Delete the stored token. */
+export function removeToken(): void {
+  if (existsSync(TOKEN_PATH)) {
+    unlinkSync(TOKEN_PATH);
+  }
+}
+
+/** Mask a token for display: "sk-abc...wxyz" */
+export function maskToken(token: string): string {
+  if (token.length <= 8) return "****";
+  return `${token.slice(0, 4)}...${token.slice(-4)}`;
+}
+
+/** Build the auth header based on configured auth type. */
+export function buildAuthHeaders(): Record<string, string> {
+  const token = getToken();
+
+  switch (AUTH_TYPE) {
+    case "bearer":
+      return { [AUTH_HEADER]: `Bearer ${token}` };
+    case "api-key":
+      return { [AUTH_HEADER]: token };
+    case "basic":
+      return { Authorization: `Basic ${Buffer.from(token).toString("base64")}` };
+    default:
+      return { [AUTH_HEADER]: token };
+  }
+}

package/src/lib/client.ts

@@ -0,0 +1,107 @@
+import { buildAuthHeaders } from "./auth.js";
+import { BASE_URL } from "./config.js";
+import { CliError } from "./errors.js";
+import { log } from "./logger.js";
+
+const MAX_RETRIES = 3;
+const RETRY_DELAYS = [1000, 2000, 4000];
+const TIMEOUT_MS = 30_000;
+
+/** HTTP methods supported by the client */
+type Method = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+
+/** Options for an API request */
+interface RequestOptions {
+  params?: Record<string, string>;
+  body?: Record<string, unknown>;
+  timeout?: number;
+}
+
+/**
+ * Make an authenticated API request with retry logic.
+ * Retries on 429 (rate limit) and 5xx (server errors).
+ */
+async function request(method: Method, path: string, opts: RequestOptions = {}): Promise<unknown> {
+  let url = `${BASE_URL}${path}`;
+
+  if (opts.params) {
+    const filtered = Object.fromEntries(
+      Object.entries(opts.params).filter(([, v]) => v !== undefined && v !== ""),
+    );
+    if (Object.keys(filtered).length > 0) {
+      url += `?${new URLSearchParams(filtered).toString()}`;
+    }
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...buildAuthHeaders(),
+  };
+
+  const fetchOpts: RequestInit = {
+    method,
+    headers,
+    signal: AbortSignal.timeout(opts.timeout ?? TIMEOUT_MS),
+  };
+
+  if (opts.body && method !== "GET") {
+    fetchOpts.body = JSON.stringify(opts.body);
+  }
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    log.debug(`${method} ${url}${attempt > 0 ? ` (retry ${attempt})` : ""}`);
+
+    const res = await fetch(url, fetchOpts);
+
+    // Retry on rate limit or server error
+    if ((res.status === 429 || res.status >= 500) && attempt < MAX_RETRIES) {
+      const delay = RETRY_DELAYS[attempt] ?? 4000;
+      log.warn(`${res.status} - retrying in ${delay / 1000}s...`);
+      await Bun.sleep(delay);
+      continue;
+    }
+
+    const data = await res.json().catch(() => null);
+
+    if (!res.ok) {
+      const msg =
+        (data as Record<string, unknown>)?.message ??
+        ((data as Record<string, Record<string, unknown>>)?.error?.message as string) ??
+        res.statusText;
+      throw new CliError(res.status, `${res.status}: ${String(msg)}`);
+    }
+
+    return data;
+  }
+
+  throw new CliError(500, "Max retries exceeded");
+}
+
+/** Typed HTTP client with convenience methods */
+export const client = {
+  /** GET request with optional query params */
+  get(path: string, params?: Record<string, string>) {
+    return request("GET", path, { params });
+  },
+
+  /** POST request with JSON body */
+  post(path: string, body?: Record<string, unknown>) {
+    return request("POST", path, { body });
+  },
+
+  /** PATCH request with JSON body */
+  patch(path: string, body?: Record<string, unknown>) {
+    return request("PATCH", path, { body });
+  },
+
+  /** PUT request with JSON body */
+  put(path: string, body?: Record<string, unknown>) {
+    return request("PUT", path, { body });
+  },
+
+  /** DELETE request */
+  delete(path: string) {
+    return request("DELETE", path);
+  },
+};

package/src/lib/config.ts

@@ -0,0 +1,29 @@
+import { homedir } from "os";
+import { join } from "path";
+
+/** Application name (replaced during api2cli create) */
+export const APP_NAME = "thecatapi";
+
+/** CLI binary name (replaced during api2cli create) */
+export const APP_CLI = "thecatapi-cli";
+
+/** API base URL (replaced during api2cli create) */
+export const BASE_URL = "https://api.thecatapi.com/v1";
+
+/** Auth type: bearer | api-key | basic | custom */
+export const AUTH_TYPE = "api-key";
+
+/** Auth header name (e.g. Authorization, X-Api-Key) */
+export const AUTH_HEADER = "x-api-key";
+
+/** Path to the token file for this CLI */
+export const TOKEN_PATH = join(homedir(), ".config", "tokens", `${APP_NAME}-cli.txt`);
+
+/** Global state for output flags (set by root command) */
+export const globalFlags = {
+  json: false,
+  format: "text" as "text" | "json" | "csv" | "yaml",
+  verbose: false,
+  noColor: false,
+  noHeader: false,
+};

package/src/lib/errors.ts

@@ -0,0 +1,101 @@
+import pc from "picocolors";
+
+/** Exit code constants */
+export const EXIT = {
+  SUCCESS: 0,
+  API_ERROR: 1,
+  USAGE_ERROR: 2,
+} as const;
+
+/** Structured error for JSON output */
+interface ErrorEnvelope {
+  ok: false;
+  error: {
+    code: number;
+    message: string;
+    suggestion?: string;
+  };
+}
+
+/** Typed CLI error with code and optional suggestion */
+export class CliError extends Error {
+  constructor(
+    public readonly code: number,
+    message: string,
+    public readonly suggestion?: string,
+  ) {
+    super(message);
+    this.name = "CliError";
+  }
+
+  /** Create a structured JSON error envelope */
+  toJSON(): ErrorEnvelope {
+    return {
+      ok: false,
+      error: {
+        code: this.code,
+        message: this.message,
+        ...(this.suggestion && { suggestion: this.suggestion }),
+      },
+    };
+  }
+}
+
+/** Suggestion map for common HTTP status codes */
+const SUGGESTIONS: Record<number, string> = {
+  401: "Check your token: thecatapi-cli auth test",
+  403: "Insufficient permissions. Check your API token scope.",
+  404: "Resource not found. Verify the ID.",
+  429: "Rate limited. Wait a moment and try again.",
+  500: "Server error. Try again later.",
+};
+
+/** Parse an HTTP status code from an error message like "401: Unauthorized" */
+function parseStatusCode(msg: string): number | null {
+  const match = msg.match(/^(\d{3}):\s/);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * Handle errors consistently. Outputs JSON or human-readable
+ * depending on the --json flag, then exits with proper code.
+ */
+export function handleError(err: unknown, json = false): never {
+  if (err instanceof CliError) {
+    if (json) {
+      console.error(JSON.stringify(err.toJSON(), null, 2));
+    } else {
+      console.error(`${pc.red("Error")} ${err.code}: ${err.message}`);
+      if (err.suggestion) {
+        console.error(`${pc.dim("Suggestion:")} ${err.suggestion}`);
+      }
+    }
+    process.exit(err.code >= 400 ? EXIT.API_ERROR : EXIT.USAGE_ERROR);
+  }
+
+  if (err instanceof Error) {
+    const status = parseStatusCode(err.message);
+    const suggestion = status ? SUGGESTIONS[status] : undefined;
+
+    if (json) {
+      const envelope: ErrorEnvelope = {
+        ok: false,
+        error: {
+          code: status ?? 1,
+          message: err.message,
+          ...(suggestion && { suggestion }),
+        },
+      };
+      console.error(JSON.stringify(envelope, null, 2));
+    } else {
+      console.error(`${pc.red("Error")}: ${err.message}`);
+      if (suggestion) {
+        console.error(`${pc.dim("Suggestion:")} ${suggestion}`);
+      }
+    }
+    process.exit(EXIT.API_ERROR);
+  }
+
+  console.error(`${pc.red("Error")}: Unknown error`);
+  process.exit(EXIT.API_ERROR);
+}

package/src/lib/logger.ts

@@ -0,0 +1,41 @@
+import pc from "picocolors";
+import { globalFlags } from "./config.js";
+
+/**
+ * Logger that respects --json (silent except errors)
+ * and --verbose (enables debug output).
+ */
+export const log = {
+  /** Informational message. Suppressed in --json mode. */
+  info(msg: string): void {
+    if (!globalFlags.json) {
+      console.log(msg);
+    }
+  },
+
+  /** Success message with green checkmark. Suppressed in --json mode. */
+  success(msg: string): void {
+    if (!globalFlags.json) {
+      console.log(`${pc.green("✓")} ${msg}`);
+    }
+  },
+
+  /** Warning message. Suppressed in --json mode. */
+  warn(msg: string): void {
+    if (!globalFlags.json) {
+      console.warn(`${pc.yellow("⚠")} ${msg}`);
+    }
+  },
+
+  /** Error message. Always shown. */
+  error(msg: string): void {
+    console.error(`${pc.red("✗")} ${msg}`);
+  },
+
+  /** Debug message. Only shown with --verbose, suppressed in --json mode. */
+  debug(msg: string): void {
+    if (globalFlags.verbose && !globalFlags.json) {
+      console.log(`${pc.dim("[debug]")} ${msg}`);
+    }
+  },
+};