@flatkey-ai/cli 0.1.25 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flatkey-ai/cli",
-  "version": "0.1.25",
+  "version": "0.2.1",
   "description": "Flatkey media generation CLI for image, video, audio, credits, status, and models.",
   "type": "module",
   "bin": {

package/src/api.js

@@ -29,12 +29,16 @@ export async function uploadTempMediaImage(options) {
 export function planImageRequest(options) {
   const model = options.model ?? "nano-banana-pro-preview";
   if (model.startsWith("gpt")) {
+    const responseFormat = options.response_format ?? options.responseFormat ?? "url";
+    const tempUrl = options.temp_url ?? options.tempUrl;
     return planJsonPost(options, "/v1/images/generations", cleanObject({
       model,
       prompt: options.prompt,
       size: options.size,
       n: parseOptionalInteger(options.n),
       quality: options.quality,
+      response_format: responseFormat,
+      temp_url: tempUrl ?? true,
     }));
   }
 
@@ -47,6 +51,7 @@ export function planImageRequest(options) {
     },
     body: {
       contents: [{ parts: [{ text: options.prompt }] }],
+      temp_url: true,
     },
   });
 }
@@ -88,6 +93,7 @@ export function planVideoRequest(options) {
     resolution,
     quality: resolution,
     fps: parseOptionalInteger(options.fps),
+    temp_url: true,
     images: !isSeedanceModel(model) && imageUrls.length > 0 ? imageUrls : undefined,
   });
   const seedanceContent = buildSeedanceContent(options);
@@ -232,7 +238,7 @@ function planRequest(options, path, init = {}) {
 
 async function requestJsonFromPlan(options, plan) {
   const fetchImpl = options.fetch ?? fetch;
-  const response = await fetchImpl(plan.url, {
+  const request = {
     method: plan.method,
     headers: plan.headers,
     body: plan.body === undefined
@@ -240,8 +246,12 @@ async function requestJsonFromPlan(options, plan) {
       : isFormData(plan.body)
         ? plan.body
         : JSON.stringify(plan.body),
-  });
+  };
+  logRequest(options, plan.url, request);
+  const response = await fetchImpl(plan.url, request);
+  logResponse(options, response);
   const body = await readJson(response);
+  logResponseBody(options, body);
   if (!response.ok || body?.success === false) {
     throw new FlatkeyError(extractErrorMessage(body, response.status), {
       status: response.status,
@@ -256,13 +266,17 @@ function isFormData(value) {
 
 async function requestBinaryArtifactFromPlan(options, plan) {
   const fetchImpl = options.fetch ?? fetch;
-  const response = await fetchImpl(plan.url, {
+  const request = {
     method: plan.method,
     headers: plan.headers,
     body: plan.body === undefined ? undefined : JSON.stringify(plan.body),
-  });
+  };
+  logRequest(options, plan.url, request);
+  const response = await fetchImpl(plan.url, request);
+  logResponse(options, response);
   if (!response.ok) {
     const body = await readJson(response);
+    logResponseBody(options, body);
     throw new FlatkeyError(extractErrorMessage(body, response.status), {
       status: response.status,
     });
@@ -272,6 +286,43 @@ async function requestBinaryArtifactFromPlan(options, plan) {
   };
 }
 
+function logRequest(options, url, request) {
+  if (!options?.verbose) return;
+  const safeHeaders = redactHeaders(request.headers);
+  const safeBody = request.body === undefined
+    ? undefined
+    : isFormData(request.body)
+      ? "<form-data>"
+      : request.body;
+  options.verboseLog?.(`-> ${request.method} ${url}`);
+  options.verboseLog?.(`headers: ${JSON.stringify(safeHeaders)}`);
+  if (safeBody !== undefined) {
+    options.verboseLog?.(`body: ${safeBody}`);
+  }
+}
+
+function logResponse(options, response) {
+  if (!options?.verbose) return;
+  options.verboseLog?.(`<- ${response.status} ${response.statusText || ""}`.trim());
+}
+
+function logResponseBody(options, body) {
+  if (!options?.verbose) return;
+  options.verboseLog?.(`response: ${truncateLogValue(JSON.stringify(body))}`);
+}
+
+function redactHeaders(headers) {
+  return Object.fromEntries(Object.entries(headers ?? {}).map(([key, value]) => [
+    key,
+    key.toLowerCase() === "authorization" ? "Bearer <redacted>" : `${value}`,
+  ]));
+}
+
+function truncateLogValue(value) {
+  if (value === undefined) return "";
+  return value.length > 1200 ? `${value.slice(0, 1200)}…` : value;
+}
+
 async function requestJson(options, path, init = {}) {
   return requestJsonFromPlan(options, planRequest(options, path, {
     method: init.method ?? "GET",

package/src/artifacts.js

@@ -47,7 +47,7 @@ function expandHomePath(path) {
 }
 
 async function persistItem({ kind, item, outDir, output, index, fetchImpl }) {
-  const dataUrl = getString(item, ["url", "video_url", "data_url", "dataUrl"]);
+  const dataUrl = getString(item, ["url", "video_url", "data_url", "dataUrl", "temp_url"]);
   if (dataUrl?.startsWith("data:")) {
     const parsed = parseDataUrl(dataUrl);
     const path = artifactPath({ kind, outDir, output, index, extension: parsed.extension });
@@ -94,6 +94,8 @@ function extractItems(response) {
   if (Array.isArray(response?.candidates)) {
     return response.candidates.flatMap((candidate) => candidate.content?.parts ?? []);
   }
+  if (typeof response?.temp_url === "string") return [{ url: response.temp_url }];
+  if (typeof response?.metadata?.temp_url === "string") return [{ url: response.metadata.temp_url }];
   if (typeof response?.metadata?.url === "string") return [{ url: response.metadata.url }];
   if (typeof response?.url === "string") return [response];
   if (typeof response?.video_url?.url === "string") return [{ url: response.video_url.url }];

package/src/cli.js

@@ -15,7 +15,7 @@ const COMMANDS = new Set([
 ]);
 
 const GROUP_ACTIONS = new Set(["audio", "auth", "image", "text", "video"]);
-const GLOBAL_OPTIONS = new Set(["api_key", "base_url", "console_url", "dry_run", "help", "json", "output", "out"]);
+const GLOBAL_OPTIONS = new Set(["api_key", "base_url", "console_url", "dry_run", "help", "json", "output", "out", "verbose"]);
 const REPEATABLE_OPTIONS = new Set(["image", "image_url", "video_url"]);
 const COMMAND_OPTIONS = {
   "audio generate": new Set(["model", "prompt", "similarity_boost", "stability", "style", "voice_id"]),
@@ -146,26 +146,30 @@ function validateCommandOptions(command) {
   return command;
 }
 
-export async function main(argv) {
+export async function main(argv, deps = {}) {
+  const stdout = deps.stdout ?? process.stdout;
+  const stderr = deps.stderr ?? process.stderr;
   const command = parseArgv(argv);
   if (command.options.help) {
-    const result = await runCommand(command);
-    process.stdout.write(`${formatHuman(result)}\n`);
+    const result = await runCommand(command, { ...deps, stdout, stderr });
+    stdout.write(`${formatHuman(result)}\n`);
     return;
   }
   if (command.group === "onboard") {
     const { writeConfig } = await import("./config.js");
-    const configPath = await writeConfig({ apiKey: command.options.api_key });
-    process.stdout.write(`Saved Flatkey config: ${configPath}\n`);
+    const configPath = await writeConfig({ apiKey: command.options.api_key, configDir: deps.configDir });
+    stdout.write(`Saved Flatkey config: ${configPath}\n`);
+    await maybeWriteUpdateNotice(command, { ...deps, stderr });
     return;
   }
 
-  const result = await runCommand(command);
+  const result = await runCommand(command, { ...deps, stdout, stderr });
   if (result !== undefined) {
-    process.stdout.write(
+    stdout.write(
       command.options.json ? `${JSON.stringify(result)}\n` : `${formatHuman(result)}\n`,
     );
   }
+  await maybeWriteUpdateNotice(command, { ...deps, stderr });
 }
 
 export async function runCommand(command, deps = {}) {
@@ -187,7 +191,7 @@ export async function runCommand(command, deps = {}) {
   }
 
   if (command.group === "models") {
-    return handleModels(command, deps);
+    return handleModels(command, { ...deps, stdout, stderr });
   }
 
   if (command.group === "login") {
@@ -206,12 +210,12 @@ export async function runCommand(command, deps = {}) {
   }
 
   if (command.group === "credits" || command.group === "status") {
-    return handleUtility(command, deps);
+    return handleUtility(command, { ...deps, stdout, stderr });
   }
 
   if (["image", "video", "audio", "text"].includes(command.group)) {
     if (command.group === "audio" && command.action === "voices") {
-      return handleVoices(command, deps);
+      return handleVoices(command, { ...deps, stdout, stderr });
     }
     const validAction = command.group === "audio"
       ? ["generate", "sfx", "music"].includes(command.action)
@@ -222,7 +226,7 @@ export async function runCommand(command, deps = {}) {
       throw new Error(`Unknown action for ${command.group}: ${command.action}`);
     }
     if (command.group === "image" && command.action === "upload") {
-      return handleImageUpload(command, deps);
+      return handleImageUpload(command, { ...deps, stdout, stderr });
     }
     return handleGenerate(command, { ...deps, stdout, stderr });
   }
@@ -236,12 +240,17 @@ async function handleLogin(command, deps) {
   const deviceId = await ensureDeviceId({ configDir: deps.configDir });
   const version = await readPackageVersion();
   const consoleOrigin = firstNonEmpty(command.options.console_url, DEFAULT_CONSOLE_URL);
-  const authorization = await createDeviceAuthorization({
+  const requestOptions = {
     consoleUrl: consoleOrigin,
+    fetch: deps.fetch,
+    verbose: command.options.verbose,
+    verboseLog: verboseLogger(deps.stderr, command.options.verbose),
+  };
+  const authorization = await createDeviceAuthorization({
     deviceId,
     clientName: "flatkey-cli",
     clientVersion: version,
-    fetch: deps.fetch,
+    ...requestOptions,
   });
   const data = authorization?.data ?? authorization;
   if (!data?.device_code || !data?.verification_uri_complete) {
@@ -261,9 +270,8 @@ async function handleLogin(command, deps) {
   while (Date.now() < deadline) {
     await delay(nextLoginPollDelay(startedAt, initialIntervalMs), deps);
     const poll = await pollDeviceAuthorization({
-      consoleUrl: consoleOrigin,
       deviceCode: data.device_code,
-      fetch: deps.fetch,
+      ...requestOptions,
     });
     const pollData = poll?.data ?? poll;
     if (pollData?.status === "approved") {
@@ -432,6 +440,8 @@ async function handleImageUpload(command, deps) {
     filename: basename(file),
     contentType: imageContentTypeFromPath(file),
     fetch: deps.fetch,
+    verbose: command.options.verbose,
+    verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   });
   const data = response?.data ?? response;
   const signedUrl = extractUploadedImageUrl(response);
@@ -494,6 +504,7 @@ async function handleGenerate(command, deps) {
     tempMediaBaseUrl: tempMediaBaseUrl ?? DEFAULT_CONSOLE_URL,
     env: deps.env ?? process.env,
     fetch: deps.fetch,
+    verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   };
   if (command.group === "video" && !command.options.dry_run) {
     await uploadVideoLocalImages(options, { uploadTempMediaImage });
@@ -581,6 +592,8 @@ async function uploadLocalImage(file, options, deps) {
     filename: basename(file),
     contentType: imageContentTypeFromPath(file),
     fetch: options.fetch,
+    verbose: options.verbose,
+    verboseLog: options.verboseLog,
   });
   const url = extractUploadedImageUrl(response);
   if (!url) throw new Error(`Image upload failed: missing signed_url for ${file}`);
@@ -632,10 +645,12 @@ async function waitForVideoResult(response, options) {
 function hasArtifact(response) {
   return Boolean(
     response?.metadata?.url
+      || response?.metadata?.temp_url
       || response?.url
+      || response?.temp_url
       || response?.video_url?.url
-      || response?.data?.some?.((item) => item?.url || item?.b64_json || item?.base64 || item?.data)
-      || response?.artifacts?.some?.((item) => item?.url || item?.path)
+      || response?.data?.some?.((item) => item?.url || item?.temp_url || item?.b64_json || item?.base64 || item?.data)
+      || response?.artifacts?.some?.((item) => item?.url || item?.temp_url || item?.path)
       || response?.content?.some?.((item) => item?.url || item?.video_url?.url || item?.data_url || item?.b64_json || item?.base64 || item?.data),
   );
 }
@@ -696,6 +711,8 @@ async function handleVoices(command, deps) {
     apiKey,
     baseUrl: routerOrigin,
     fetch: deps.fetch,
+    verbose: command.options.verbose,
+    verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   });
 }
 
@@ -755,6 +772,8 @@ async function handleUtility(command, deps) {
     apiKey,
     baseUrl: consoleOrigin,
     fetch: deps.fetch,
+    verbose: command.options.verbose,
+    verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   };
   if (command.group === "credits") return getCredits(options);
 
@@ -841,10 +860,21 @@ async function handleModels(command, deps) {
     apiKey,
     baseUrl: consoleOrigin,
     fetch: deps.fetch,
+    verbose: command.options.verbose,
+    verboseLog: verboseLogger(deps.stderr, command.options.verbose),
   });
   return { models: normalizeModels(response, command.options.type) };
 }
 
+function verboseLogger(stream, enabled) {
+  if (!enabled) return () => {};
+  return (line) => {
+    if (typeof line === "string") {
+      stream?.write?.(`${line}\n`);
+    }
+  };
+}
+
 function formatHuman(result) {
   if (typeof result === "string") return result;
   if (!result || typeof result !== "object") return String(result);
@@ -1001,3 +1031,52 @@ async function readPackageVersion() {
   const packageUrl = new URL("../package.json", import.meta.url);
   return JSON.parse(await readFile(packageUrl, "utf8")).version;
 }
+
+async function maybeWriteUpdateNotice(command, deps = {}) {
+  if (command.options.json || command.options.help || command.group === "help" || command.group === "version") {
+    return;
+  }
+  try {
+    const current = await readPackageVersion();
+    const latest = await fetchLatestPackageVersion(deps);
+    if (!latest || compareVersions(latest, current) <= 0) return;
+    deps.stderr?.write?.([
+      `\nFlatkey CLI update available: ${current} -> ${latest}`,
+      "Upgrade: npm install -g @flatkey-ai/cli",
+      "",
+    ].join("\n"));
+  } catch {
+    // Update checks must never break normal CLI commands.
+  }
+}
+
+async function fetchLatestPackageVersion(deps = {}) {
+  const fetchImpl = deps.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") return undefined;
+  const response = await fetchImpl("https://registry.npmjs.org/@flatkey-ai%2fcli/latest", {
+    signal: typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function"
+      ? AbortSignal.timeout(750)
+      : undefined,
+  });
+  if (!response?.ok) return undefined;
+  const body = await response.json();
+  return typeof body?.version === "string" ? body.version : undefined;
+}
+
+function compareVersions(left, right) {
+  const leftParts = parseVersionParts(left);
+  const rightParts = parseVersionParts(right);
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+
+function parseVersionParts(version) {
+  return String(version)
+    .split("-", 1)[0]
+    .split(".")
+    .map((part) => Number.parseInt(part, 10))
+    .map((part) => Number.isFinite(part) ? part : 0);
+}

package/src/help.js

@@ -67,6 +67,7 @@ Commands:
 Global options:
   --json                         Print machine-readable JSON
   --output, -o <file>             Write generated output to a local file
+  --verbose                      Print request/response logs to stderr
   --base-url <url>               Override Flatkey router URL
 
 Environment: