thecatapi-cli 0.1.1

package/src/lib/output.ts

@@ -0,0 +1,169 @@
+import pc from "picocolors";
+import { globalFlags } from "./config.js";
+
+interface JsonEnvelope {
+  ok: true;
+  data: unknown;
+  meta?: { total?: number; page?: number };
+}
+
+export function output(
+  data: unknown,
+  opts: { json?: boolean; format?: string; fields?: string[]; noHeader?: boolean } = {},
+): void {
+  const isJson = opts.json ?? globalFlags.json;
+  const format = isJson ? "json" : (opts.format ?? globalFlags.format);
+
+  switch (format) {
+    case "json":
+      printJson(data);
+      break;
+    case "csv":
+      printCsv(data, opts.fields, opts.noHeader ?? globalFlags.noHeader);
+      break;
+    case "yaml":
+      printYaml(data, 0);
+      break;
+    default:
+      printText(data, opts.fields, opts.noHeader ?? globalFlags.noHeader);
+  }
+}
+
+function printJson(data: unknown): void {
+  const envelope: JsonEnvelope = { ok: true, data };
+  if (Array.isArray(data)) {
+    envelope.meta = { total: data.length };
+  }
+  console.log(JSON.stringify(envelope, null, 2));
+}
+
+function printText(data: unknown, fields?: string[], noHeader?: boolean): void {
+  if (Array.isArray(data)) {
+    if (data.length === 0) {
+      console.log(pc.dim("(no results)"));
+      return;
+    }
+    printTable(data as Record<string, unknown>[], fields, noHeader);
+    console.log(pc.dim(`\n${data.length} result${data.length === 1 ? "" : "s"}`));
+  } else if (typeof data === "object" && data !== null) {
+    printKeyValue(data as Record<string, unknown>);
+  } else {
+    console.log(String(data));
+  }
+}
+
+function printKeyValue(obj: Record<string, unknown>): void {
+  const maxKey = Math.max(...Object.keys(obj).map((k) => k.length));
+  for (const [k, v] of Object.entries(obj)) {
+    const label = pc.bold(k.padEnd(maxKey));
+    const val = formatValue(v);
+    console.log(`  ${label}  ${val}`);
+  }
+}
+
+function formatValue(v: unknown): string {
+  if (v === null || v === undefined) return pc.dim("-");
+  if (typeof v === "boolean") return v ? pc.green("true") : pc.red("false");
+  if (typeof v === "number") return pc.cyan(String(v));
+  if (typeof v === "object") return pc.dim(JSON.stringify(v));
+  const s = String(v);
+  if (/^\d{4}-\d{2}-\d{2}/.test(s)) return pc.dim(s);
+  if (/^https?:\/\//.test(s)) return pc.underline(pc.cyan(s));
+  return s;
+}
+
+function formatCell(v: unknown): string {
+  if (v === null || v === undefined) return pc.dim("-");
+  if (typeof v === "boolean") return v ? pc.green("yes") : pc.red("no");
+  if (typeof v === "number") return pc.cyan(String(v));
+  if (typeof v === "object") return pc.dim(JSON.stringify(v));
+  const s = String(v);
+  if (/^\d{4}-\d{2}-\d{2}T/.test(s)) {
+    return pc.dim(s.replace("T", " ").replace(/\.\d+Z$/, "Z"));
+  }
+  return s;
+}
+
+function printTable(
+  rows: Record<string, unknown>[],
+  fields?: string[],
+  noHeader?: boolean,
+): void {
+  const cols = fields ?? Object.keys(rows[0] ?? {});
+  const widths = cols.map((col) => {
+    const values = rows.map((r) => stripAnsi(formatCell(r[col])).length);
+    return Math.min(Math.max(col.length, ...values), 40);
+  });
+
+  if (!noHeader) {
+    const header = cols.map((c, i) => pc.bold(pc.white(c.padEnd(widths[i] ?? 10)))).join("  ");
+    console.log(header);
+    console.log(pc.dim(widths.map((w) => "\u2500".repeat(w)).join("  ")));
+  }
+
+  for (const row of rows) {
+    const line = cols.map((c, i) => {
+      const formatted = formatCell(row[c]);
+      const raw = stripAnsi(formatted);
+      const w = widths[i] ?? 10;
+      if (raw.length > w) {
+        return formatted.slice(0, formatted.length - (raw.length - w) - 1) + pc.dim("\u2026");
+      }
+      const padding = w - raw.length;
+      return formatted + " ".repeat(padding > 0 ? padding : 0);
+    });
+    console.log(line.join("  "));
+  }
+}
+
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function printCsv(data: unknown, fields?: string[], noHeader?: boolean): void {
+  if (!Array.isArray(data)) {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  if (data.length === 0) return;
+
+  const cols = fields ?? Object.keys((data[0] as Record<string, unknown>) ?? {});
+
+  if (!noHeader) {
+    console.log(cols.join(","));
+  }
+
+  for (const row of data as Record<string, unknown>[]) {
+    console.log(cols.map((c) => csvEscape(String(row[c] ?? ""))).join(","));
+  }
+}
+
+function csvEscape(val: string): string {
+  if (val.includes(",") || val.includes('"') || val.includes("\n")) {
+    return `"${val.replace(/"/g, '""')}"`;
+  }
+  return val;
+}
+
+function printYaml(data: unknown, indent: number): void {
+  const pad = "  ".repeat(indent);
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      if (typeof item === "object" && item !== null) {
+        console.log(`${pad}-`);
+        printYaml(item, indent + 1);
+      } else {
+        console.log(`${pad}- ${String(item)}`);
+      }
+    }
+  } else if (typeof data === "object" && data !== null) {
+    for (const [k, v] of Object.entries(data)) {
+      if (typeof v === "object" && v !== null) {
+        console.log(`${pad}${k}:`);
+        printYaml(v, indent + 1);
+      } else {
+        console.log(`${pad}${k}: ${String(v)}`);
+      }
+    }
+  }
+}

package/src/resources/breeds.ts

@@ -0,0 +1,103 @@
+import { Command } from "commander";
+import { client } from "../lib/client.js";
+import { output } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+
+interface ActionOpts {
+  json?: boolean;
+  format?: string;
+  fields?: string;
+  limit?: string;
+  page?: string;
+  order?: string;
+  attachImage?: boolean;
+}
+
+export const breedsResource = new Command("breeds")
+  .description("Browse and search cat breeds");
+
+// ── LIST ───────────────────────────────────────────
+breedsResource
+  .command("list")
+  .description("List all cat breeds")
+  .option("--limit <n>", "Results per page")
+  .option("--page <n>", "Page number")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExamples:\n  thecatapi-cli breeds list\n  thecatapi-cli breeds list --limit 5 --json")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const params: Record<string, string> = {};
+      if (opts.limit) params.limit = opts.limit;
+      if (opts.page) params.page = opts.page;
+      const data = await client.get("/breeds", params);
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── GET ────────────────────────────────────────────
+breedsResource
+  .command("get")
+  .description("Get a specific breed by ID")
+  .argument("<id>", "Breed ID (e.g. abys, beng)")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli breeds get abys")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      const data = await client.get(`/breeds/${id}`);
+      output(data, { json: opts.json, format: opts.format });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── SEARCH ─────────────────────────────────────────
+breedsResource
+  .command("search")
+  .description("Search breeds by name")
+  .argument("<query>", "Search term")
+  .option("--attach-image", "Include reference image in results")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli breeds search bengal")
+  .action(async (query: string, opts: ActionOpts) => {
+    try {
+      const params: Record<string, string> = { q: query };
+      if (opts.attachImage) params.attach_image = "1";
+      const data = await client.get("/breeds/search", params);
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── FACTS ──────────────────────────────────────────
+breedsResource
+  .command("facts")
+  .description("Get facts about a specific breed")
+  .argument("<id>", "Breed ID")
+  .option("--limit <n>", "Number of facts")
+  .option("--page <n>", "Page number")
+  .option("--order <order>", "Order: ASC, DESC, RAND")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli breeds facts abys")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      const params: Record<string, string> = {};
+      if (opts.limit) params.limit = opts.limit;
+      if (opts.page) params.page = opts.page;
+      if (opts.order) params.order = opts.order;
+      const data = await client.get(`/breeds/${id}/facts`, params);
+      output(data, { json: opts.json, format: opts.format });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });

package/src/resources/example.ts

@@ -0,0 +1,125 @@
+/**
+ * Example resource file.
+ * Copy this and adapt for each API resource.
+ * Pattern: one file per resource (drafts.ts, links.ts, accounts.ts, etc.)
+ */
+import { Command } from "commander";
+import { client } from "../lib/client.js";
+import { output } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+
+interface ActionOpts {
+  json?: boolean;
+  format?: string;
+  fields?: string;
+  limit?: string;
+  page?: string;
+  sort?: string;
+  filter?: string;
+  name?: string;
+  description?: string;
+}
+
+export const exampleResource = new Command("examples")
+  .description("Manage examples (replace with your resource)");
+
+// ── LIST ──────────────────────────────────────────────
+exampleResource
+  .command("list")
+  .description("List all examples")
+  .option("--limit <n>", "Max results to return", "20")
+  .option("--page <n>", "Page number", "1")
+  .option("--sort <field>", "Sort by field (e.g. created_at:desc)")
+  .option("--filter <expr>", "Filter expression (e.g. status=active)")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExamples:\n  thecatapi-cli examples list\n  thecatapi-cli examples list --limit 5 --json")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const data = await client.get("/examples", {
+        limit: opts.limit ?? "20",
+        page: opts.page ?? "1",
+        ...(opts.sort && { sort: opts.sort }),
+        ...(opts.filter && { filter: opts.filter }),
+      });
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── GET ───────────────────────────────────────────────
+exampleResource
+  .command("get")
+  .description("Get a specific example by ID")
+  .argument("<id>", "Example ID")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli examples get abc123")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      const data = await client.get(`/examples/${id}`);
+      output(data, { json: opts.json, format: opts.format });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── CREATE ────────────────────────────────────────────
+exampleResource
+  .command("create")
+  .description("Create a new example")
+  .requiredOption("--name <name>", "Name for the example")
+  .option("--description <desc>", "Optional description")
+  .option("--json", "Output as JSON")
+  .addHelpText("after", '\nExample:\n  thecatapi-cli examples create --name "My Example"')
+  .action(async (opts: ActionOpts) => {
+    try {
+      const data = await client.post("/examples", {
+        name: opts.name,
+        ...(opts.description && { description: opts.description }),
+      });
+      output(data, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── UPDATE ────────────────────────────────────────────
+exampleResource
+  .command("update")
+  .description("Update an existing example")
+  .argument("<id>", "Example ID")
+  .option("--name <name>", "New name")
+  .option("--description <desc>", "New description")
+  .option("--json", "Output as JSON")
+  .addHelpText("after", '\nExample:\n  thecatapi-cli examples update abc123 --name "Updated"')
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      const body: Record<string, unknown> = {};
+      if (opts.name) body.name = opts.name;
+      if (opts.description) body.description = opts.description;
+      const data = await client.patch(`/examples/${id}`, body);
+      output(data, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── DELETE ────────────────────────────────────────────
+exampleResource
+  .command("delete")
+  .description("Delete an example")
+  .argument("<id>", "Example ID")
+  .option("--json", "Output as JSON")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli examples delete abc123")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      await client.delete(`/examples/${id}`);
+      output({ deleted: true, id }, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });

package/src/resources/facts.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { client } from "../lib/client.js";
+import { output } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+
+interface ActionOpts {
+  json?: boolean;
+  format?: string;
+  fields?: string;
+  limit?: string;
+}
+
+export const factsResource = new Command("facts")
+  .description("Get random cat facts");
+
+// ── LIST ───────────────────────────────────────────
+factsResource
+  .command("list")
+  .description("Get random cat facts")
+  .option("--limit <n>", "Number of facts to return", "5")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExamples:\n  thecatapi-cli facts list\n  thecatapi-cli facts list --limit 10 --json")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const data = await client.get("/facts", {
+        limit: opts.limit ?? "5",
+      });
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });

package/src/resources/favourites.ts

@@ -0,0 +1,83 @@
+import { Command } from "commander";
+import { client } from "../lib/client.js";
+import { output } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+
+interface ActionOpts {
+  json?: boolean;
+  format?: string;
+  fields?: string;
+  imageId?: string;
+  subId?: string;
+}
+
+export const favouritesResource = new Command("favourites")
+  .description("Manage your favourite cat images");
+
+// ── LIST ───────────────────────────────────────────
+favouritesResource
+  .command("list")
+  .description("List your favourited images")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli favourites list")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const data = await client.get("/favourites");
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── GET ────────────────────────────────────────────
+favouritesResource
+  .command("get")
+  .description("Get a specific favourite")
+  .argument("<id>", "Favourite ID")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      const data = await client.get(`/favourites/${id}`);
+      output(data, { json: opts.json, format: opts.format });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── CREATE ─────────────────────────────────────────
+favouritesResource
+  .command("create")
+  .description("Add an image to your favourites")
+  .requiredOption("--image-id <id>", "Image ID to favourite")
+  .option("--sub-id <id>", "User segment identifier")
+  .option("--json", "Output as JSON")
+  .addHelpText("after", "\nExample:\n  thecatapi-cli favourites create --image-id abc123")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const body: Record<string, unknown> = { image_id: opts.imageId };
+      if (opts.subId) body.sub_id = opts.subId;
+      const data = await client.post("/favourites", body);
+      output(data, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── DELETE ─────────────────────────────────────────
+favouritesResource
+  .command("delete")
+  .description("Remove an image from your favourites")
+  .argument("<id>", "Favourite ID")
+  .option("--json", "Output as JSON")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      await client.delete(`/favourites/${id}`);
+      output({ deleted: true, id }, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });

package/src/resources/images.ts

@@ -0,0 +1,153 @@
+import { Command } from "commander";
+import { client } from "../lib/client.js";
+import { output } from "../lib/output.js";
+import { handleError } from "../lib/errors.js";
+import { buildAuthHeaders } from "../lib/auth.js";
+import { BASE_URL } from "../lib/config.js";
+import { CliError } from "../lib/errors.js";
+
+interface ActionOpts {
+  json?: boolean;
+  format?: string;
+  fields?: string;
+  limit?: string;
+  page?: string;
+  size?: string;
+  mimeTypes?: string;
+  hasBreeds?: boolean;
+  order?: string;
+  subId?: string;
+  breedIds?: string;
+}
+
+export const imagesResource = new Command("images")
+  .description("Search, list, upload, and manage cat images");
+
+// ── SEARCH ─────────────────────────────────────────
+imagesResource
+  .command("search")
+  .description("Search for random or filtered cat images")
+  .option("--limit <n>", "Results per page (max 25)", "10")
+  .option("--page <n>", "Page number", "0")
+  .option("--size <size>", "Image size: thumb, small, med, full")
+  .option("--mime-types <types>", "Filter by mime type: jpg, png, gif")
+  .option("--has-breeds", "Only images with breed data")
+  .option("--order <order>", "Order: RANDOM, ASC, DESC", "RANDOM")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .addHelpText("after", "\nExamples:\n  thecatapi-cli images search\n  thecatapi-cli images search --limit 5 --has-breeds --json")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const params: Record<string, string> = {
+        limit: opts.limit ?? "10",
+        page: opts.page ?? "0",
+        order: opts.order ?? "RANDOM",
+      };
+      if (opts.size) params.size = opts.size;
+      if (opts.mimeTypes) params.mime_types = opts.mimeTypes;
+      if (opts.hasBreeds) params.has_breeds = "1";
+      const data = await client.get("/images/search", params);
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── LIST (user's uploaded images) ──────────────────
+imagesResource
+  .command("list")
+  .description("List your uploaded images")
+  .option("--limit <n>", "Results per page (1-10)", "10")
+  .option("--page <n>", "Page number", "0")
+  .option("--order <order>", "Order: ASC, DESC", "DESC")
+  .option("--fields <cols>", "Comma-separated columns to display")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .action(async (opts: ActionOpts) => {
+    try {
+      const data = await client.get("/images", {
+        limit: opts.limit ?? "10",
+        page: opts.page ?? "0",
+        order: opts.order ?? "DESC",
+      });
+      const fields = opts.fields?.split(",");
+      output(data, { json: opts.json, format: opts.format, fields });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── GET ────────────────────────────────────────────
+imagesResource
+  .command("get")
+  .description("Get a specific image by ID")
+  .argument("<id>", "Image ID")
+  .option("--json", "Output as JSON")
+  .option("--format <fmt>", "Output format: text, json, csv, yaml")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      const data = await client.get(`/images/${id}`);
+      output(data, { json: opts.json, format: opts.format });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── UPLOAD ─────────────────────────────────────────
+imagesResource
+  .command("upload")
+  .description("Upload a cat image")
+  .argument("<file>", "Path to image file")
+  .option("--sub-id <id>", "User segment identifier")
+  .option("--breed-ids <ids>", "Comma-separated breed IDs")
+  .option("--json", "Output as JSON")
+  .action(async (file: string, opts: ActionOpts) => {
+    try {
+      const fs = await import("fs");
+      const path = await import("path");
+      const resolved = path.resolve(file);
+      if (!fs.existsSync(resolved)) {
+        throw new CliError(2, `File not found: ${resolved}`);
+      }
+      const fileData = fs.readFileSync(resolved);
+      const fileName = path.basename(resolved);
+
+      const formData = new FormData();
+      formData.append("file", new Blob([fileData]), fileName);
+      if (opts.subId) formData.append("sub_id", opts.subId);
+      if (opts.breedIds) formData.append("breed_ids", opts.breedIds);
+
+      const headers = buildAuthHeaders();
+      const res = await fetch(`${BASE_URL}/images/upload`, {
+        method: "POST",
+        headers: { ...headers, Accept: "application/json" },
+        body: formData,
+      });
+
+      const data = await res.json().catch(() => null);
+      if (!res.ok) {
+        const msg = (data as Record<string, unknown>)?.message ?? res.statusText;
+        throw new CliError(res.status, `${res.status}: ${String(msg)}`);
+      }
+      output(data, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });
+
+// ── DELETE ─────────────────────────────────────────
+imagesResource
+  .command("delete")
+  .description("Delete an uploaded image")
+  .argument("<id>", "Image ID")
+  .option("--json", "Output as JSON")
+  .action(async (id: string, opts: ActionOpts) => {
+    try {
+      await client.delete(`/images/${id}`);
+      output({ deleted: true, id }, { json: opts.json });
+    } catch (err) {
+      handleError(err, opts.json);
+    }
+  });