@todoforai/image-api 2.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @todoforai/image-api
+
+Generate and edit images through the TODOforAI backend (gpt-image).
+
+## Install
+
+```bash
+npm install -g @todoforai/image-api
+```
+
+## Usage
+
+```bash
+image-api generate "An orange rocket on a white background" -o rocket.png
+image-api edit "Change only the background to black" --image rocket.png -o edited.png
+```
+
+Authenticate with `todoforai login`, `TODOFORAI_API_KEY`, or `--api-key`.

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@todoforai/image-api",
+  "version": "2.1.0",
+  "description": "AI image generation and editing through TODOforAI (gpt-image)",
+  "type": "module",
+  "bin": {
+    "image-api": "src/index.ts"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,139 @@
+/**
+ * Backend API client — calls TODOFORAI's codex/imagegen endpoint.
+ *
+ * Mount routing: a bridge-injected `dst_` device-session token is only accepted
+ * on the `/dst/v1` mount; long-lived API keys go through `/api/v1`.
+ *
+ * Auth precedence (matches todoforai-subagent):
+ *   1. --api-key flag
+ *   2. TODOFORAI_API_TOKEN env (bridge-injected short-lived token)
+ *   3. stored creds for explicit --api-url
+ *   4. TODOFORAI_API_KEY env
+ *   5. stored creds at platform config dir
+ *      (`~/.config/todoforai/credentials.json` on Linux,
+ *       legacy `~/.todoforai/credentials.json` for back-compat).
+ */
+
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// Mirrors @shared/fbe CodexImageGen{Input,Output,Content}; kept inline so this
+// CLI stays a zero-dep package (like todoforai-subagent).
+export type CodexImageGenContent =
+  | { type: "input_text"; text: string }
+  | { type: "input_image"; imageUrl: string };
+
+export type CodexImageSize =
+  | "1024x1024"
+  | "1536x1024"
+  | "1024x1536"
+  | "2048x2048"
+  | "4096x4096";
+
+export interface CodexImageGenInput {
+  content: CodexImageGenContent[];
+  model?: string;
+  size: CodexImageSize;
+  quality?: "low" | "medium" | "high";
+  background?: "auto" | "transparent" | "opaque";
+  outputFormat?: "png" | "webp" | "jpeg";
+  instructions?: string;
+}
+
+export interface CodexImageGenOutput {
+  image: string;
+  format: string;
+  cost?: number;
+  elapsed?: number;
+  revisedPrompt?: string;
+}
+
+const DEFAULT_API_URL = "https://api.todofor.ai";
+
+// Credentials path matches todoforai-c-core / bridge (XDG on Linux,
+// Library/Application Support on macOS, %APPDATA% on Windows).
+function credentialsPaths(): string[] {
+  const sys = process.platform;
+  if (sys === "win32") {
+    // Match todoforai-c-core: %HOME%\AppData\Roaming (not %APPDATA%).
+    return [join(homedir(), "AppData", "Roaming", "todoforai", "credentials.json")];
+  }
+  if (sys === "darwin") {
+    return [join(homedir(), "Library", "Application Support", "todoforai", "credentials.json")];
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return [join(xdg, "todoforai", "credentials.json")];
+}
+
+export interface ApiOptions {
+  apiUrl?: string;
+  apiKey?: string;
+}
+
+function getEnv(name: string): string {
+  return process.env[`TODOFORAI_${name}`] || process.env[`TODO4AI_${name}`] || "";
+}
+
+function normalizeApiUrl(url: string): string {
+  if (url.startsWith("localhost")) return `http://${url}`;
+  if (!url.startsWith("http://") && !url.startsWith("https://")) return `https://${url}`;
+  return url.replace(/\/+$/, "");
+}
+
+function readStoredApiKey(apiUrl: string): string {
+  for (const p of credentialsPaths()) {
+    try {
+      const creds = JSON.parse(readFileSync(p, "utf8")) as Record<string, string>;
+      if (creds[apiUrl]) return creds[apiUrl];
+    } catch {}
+  }
+  return "";
+}
+
+function resolveAuth(opts: ApiOptions): { apiUrl: string; apiKey: string } {
+  const explicitUrl = opts.apiUrl || getEnv("API_URL");
+  const apiUrl = normalizeApiUrl(explicitUrl || DEFAULT_API_URL);
+  // Bridge-injected short-lived token (TODOFORAI_API_TOKEN) wins over
+  // long-lived API keys / stored creds, but loses to an explicit --api-key.
+  const apiKey =
+    opts.apiKey ||
+    getEnv("API_TOKEN") ||
+    (opts.apiUrl ? readStoredApiKey(apiUrl) : "") ||
+    getEnv("API_KEY") ||
+    process.env.API_KEY ||
+    readStoredApiKey(apiUrl);
+  if (!apiKey) {
+    console.error(
+      "Error: no API key. Set TODOFORAI_API_KEY, pass --api-key, or run `todoforai login` first."
+    );
+    process.exit(2);
+  }
+  return { apiUrl, apiKey };
+}
+
+export async function imageGen(
+  input: CodexImageGenInput,
+  opts: ApiOptions = {}
+): Promise<CodexImageGenOutput> {
+  const { apiUrl, apiKey } = resolveAuth(opts);
+  // `dst_` device-session tokens are only valid on the /dst/v1 mount; long-lived
+  // API keys go through /api/v1.
+  const mount = apiKey.startsWith("dst_") ? "dst" : "api";
+  const res = await fetch(`${apiUrl}/${mount}/v1/codex/imagegen`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": apiKey },
+    body: JSON.stringify(input),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    let msg = text.slice(0, 500);
+    try {
+      const j = JSON.parse(text);
+      msg = j?.error?.message || j?.message || msg;
+    } catch { /* keep raw */ }
+    console.error(`HTTP ${res.status}: ${msg}`);
+    process.exit(1);
+  }
+  return (await res.json()) as CodexImageGenOutput;
+}

package/src/commands/edit.ts

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { runImageGen, imageToDataUrl, ContentItem } from "../imagegen";
+
+export const editCommand = new Command("edit")
+  .description(
+    "Edit one or more images via TODOFORAI's image generation endpoint.\n\n" +
+      "Pass --image multiple times to provide reference / edit-target images.\n" +
+      "Tip: state invariants in the prompt (e.g. 'change only X; keep Y unchanged')."
+  )
+  .argument("<prompt>", "Edit instruction")
+  .requiredOption(
+    "-i, --image <path>",
+    "Input image; repeat for multiple images",
+    (v: string, prev: string[] = []) => [...prev, v],
+    [],
+  )
+  .option("-o, --output <file>", "Output PNG file", "edited.png")
+  .option("--model <model>", "Model (default: gpt-image-2)")
+  .option("--size <size>", "1024x1024 | 1536x1024 | 1024x1536 | 2048x2048 | 4096x4096", "1024x1024")
+  .option("--quality <quality>", "low | medium | high")
+  .option("--background <bg>", "auto | transparent | opaque")
+  .option("--output_format <fmt>", "png | webp | jpeg", "png")
+  .option("--instructions <text>", "System instructions")
+  .option("--api-url <url>", "TODOFORAI API URL")
+  .option("--api-key <key>", "TODOFORAI API key")
+  .action(async (prompt: string, opts) => {
+    const imagePaths: string[] = opts.image ?? [];
+    if (imagePaths.length === 0) {
+      console.error("Error: at least one --image is required.");
+      process.exit(1);
+    }
+    const content: ContentItem[] = [{ type: "input_text", text: prompt }];
+    for (const p of imagePaths) {
+      content.push({ type: "input_image", imageUrl: await imageToDataUrl(p) });
+    }
+    await runImageGen(content, opts);
+  });

package/src/commands/generate.ts

@@ -0,0 +1,21 @@
+import { Command } from "commander";
+import { runImageGen } from "../imagegen";
+
+export const generateCommand = new Command("generate")
+  .description(
+    "Generate an image via TODOFORAI's image generation endpoint.\n\n" +
+      "Auth: TODOFORAI_API_TOKEN (bridge-injected) or TODOFORAI_API_KEY env (or --api-key)."
+  )
+  .argument("<prompt>", "Image prompt")
+  .option("-o, --output <file>", "Output PNG file", "out.png")
+  .option("--model <model>", "Model (default: gpt-image-2)")
+  .option("--size <size>", "1024x1024 | 1536x1024 | 1024x1536 | 2048x2048 | 4096x4096", "1024x1024")
+  .option("--quality <quality>", "low | medium | high")
+  .option("--background <bg>", "auto | transparent | opaque")
+  .option("--output_format <fmt>", "png | webp | jpeg", "png")
+  .option("--instructions <text>", "System instructions")
+  .option("--api-url <url>", "TODOFORAI API URL (default: $TODOFORAI_API_URL or https://api.todofor.ai)")
+  .option("--api-key <key>", "TODOFORAI API key (default: $TODOFORAI_API_TOKEN or $TODOFORAI_API_KEY)")
+  .action(async (prompt: string, opts) => {
+    await runImageGen([{ type: "input_text", text: prompt }], opts);
+  });

package/src/imagegen.ts

@@ -0,0 +1,50 @@
+import { writeFile, readFile } from "fs/promises";
+import { extname } from "path";
+import { imageGen, ApiOptions, CodexImageGenContent, CodexImageGenInput, CodexImageSize } from "./api";
+
+const MIME_BY_EXT: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+};
+
+export async function imageToDataUrl(path: string): Promise<string> {
+  const buf = await readFile(path);
+  const mime = MIME_BY_EXT[extname(path).toLowerCase()] ?? "image/png";
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
+export type ContentItem = CodexImageGenContent;
+
+export interface ImageGenOptions extends ApiOptions {
+  model?: string;
+  size?: CodexImageSize;
+  quality?: "low" | "medium" | "high";
+  background?: "auto" | "transparent" | "opaque";
+  output_format?: "png" | "webp" | "jpeg";
+  instructions?: string;
+  output: string;
+}
+
+export async function runImageGen(content: ContentItem[], opts: ImageGenOptions): Promise<void> {
+  const input: CodexImageGenInput = {
+    content,
+    size: opts.size ?? "1024x1024",
+    ...(opts.model && { model: opts.model }),
+    ...(opts.quality && { quality: opts.quality }),
+    ...(opts.background && { background: opts.background }),
+    ...(opts.output_format && { outputFormat: opts.output_format }),
+    ...(opts.instructions && { instructions: opts.instructions }),
+  };
+
+  const result = await imageGen(input, { apiUrl: opts.apiUrl, apiKey: opts.apiKey });
+
+  const buf = Buffer.from(result.image, "base64");
+  await writeFile(opts.output, buf);
+  console.error(`Saved ${opts.output} (${buf.length} bytes)`);
+
+  if (result.revisedPrompt) console.error(`Revised prompt: ${result.revisedPrompt}`);
+  if (result.cost !== undefined) console.error(`Cost: $${result.cost.toFixed(3)}`);
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+import { program } from "commander";
+import { generateCommand } from "./commands/generate";
+import { editCommand } from "./commands/edit";
+
+program
+  .name("image-api")
+  .description(
+    "Image generation & editing CLI via TODOFORAI backend (gpt-image).\n\n" +
+      "Auth: TODOFORAI_API_TOKEN (bridge-injected) or TODOFORAI_API_KEY env (or --api-key).\n" +
+      "Run `todoforai login` to store credentials."
+  )
+  .version("2.1.0");
+
+program.addCommand(generateCommand);
+program.addCommand(editCommand);
+
+program.parse();