image-skill 0.1.22 → 0.1.23

package/CHANGELOG.md

@@ -4,6 +4,18 @@ This changelog tracks the public `image-skill` CLI package and public skill
 mirror. The npm package metadata remains the authority for tarball integrity and
 provenance; this file is the human- and agent-readable release map.
 
+## 0.1.23 - 2026-06-02
+
+- Fix (guide payments): `create --guide` now distinguishes browserless,
+  agent-payable, and human-handoff payment rails instead of collapsing the
+  payment summary into a single browser-required flag. When the hosted catalog
+  exposes `stripe_x402.exact.usdc` as available and browserless, the guide marks
+  it as the preferred method and puts the x402 quote/buy/status commands before
+  the Stripe Checkout fallback.
+- Fix (quota recovery): when an authenticated agent has no remaining credits,
+  guide mode now points `data.next_command` at the preferred credit quote command
+  instead of the generic `credits methods` inspection command.
+
 ## 0.1.22 - 2026-06-02
 
 - Fix (guide): `create --guide` now reports `cost.estimated_usd_per_image` as

package/bin/image-skill.mjs

@@ -7,7 +7,7 @@ import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import os from "node:os";
 
-const VERSION = "0.1.22";
+const VERSION = "0.1.23";
 const PACKAGE_NAME = "image-skill";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_DOCS_BASE_URL = "https://image-skill.com";
@@ -1171,28 +1171,71 @@ function createGuidePaymentSummary(data) {
   const methods = Array.isArray(data?.methods)
     ? data.methods.filter((method) => method.live_money)
     : [];
+  const availableMethods = methods.filter((method) => method.available);
+  const browserlessMethods = availableMethods.filter(
+    (method) => method.requires_browser === false,
+  );
+  const agentPayableMethods = browserlessMethods.filter((method) =>
+    (method.buyer_modes ?? []).some(
+      (mode) => mode === "agent_only" || mode === "hybrid",
+    ),
+  );
+  const humanHandoffMethods = availableMethods.filter(
+    (method) =>
+      method.requires_browser === true ||
+      (method.buyer_modes ?? []).some((mode) => mode === "human_only"),
+  );
+  const preferredMethod =
+    agentPayableMethods[0] ?? browserlessMethods[0] ?? availableMethods[0];
   return {
     checked: data !== null && typeof data === "object",
-    live_money_methods: methods
-      .filter((method) => method.available)
-      .map((method) => method.method_id),
-    requires_browser: methods.some((method) => method.requires_browser),
+    live_money_methods: availableMethods.map((method) => method.method_id),
+    requires_browser:
+      availableMethods.length > 0 &&
+      availableMethods.every((method) => method.requires_browser === true),
+    browserless_methods: browserlessMethods.map((method) => method.method_id),
+    agent_payable_methods: agentPayableMethods.map(
+      (method) => method.method_id,
+    ),
+    human_handoff_methods: humanHandoffMethods.map(
+      (method) => method.method_id,
+    ),
+    preferred_method: preferredMethod?.method_id ?? null,
     buyer_modes: [
       ...new Set(methods.flatMap((method) => method.buyer_modes ?? [])),
     ],
-    suggested_commands: [
-      "image-skill credits methods --json",
-      "image-skill credits packs list --json",
-      methods[0]?.recovery?.quote_command ??
-        "image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json",
-      methods[0]?.recovery?.purchase_command ??
-        "image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json",
-      methods[0]?.recovery?.status_command ??
-        "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
-    ],
+    suggested_commands: createGuidePaymentCommands(
+      preferredMethod,
+      availableMethods.filter((method) => method !== preferredMethod),
+    ),
   };
 }
 
+function createGuidePaymentCommands(preferredMethod, fallbackMethods) {
+  const commands = [
+    "image-skill credits methods --json",
+    "image-skill credits packs list --json",
+    preferredMethod?.recovery?.quote_command ??
+      "image-skill credits quote --pack starter-500 --payment-method stripe_x402.exact.usdc --idempotency-key KEY --json",
+    preferredMethod?.recovery?.purchase_command ??
+      "image-skill credits buy --provider stripe_x402 --quote-id QUOTE_ID --idempotency-key KEY --json",
+    preferredMethod?.recovery?.status_command ??
+      "image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json",
+  ];
+  for (const method of fallbackMethods) {
+    for (const command of [
+      method.recovery?.quote_command,
+      method.recovery?.purchase_command,
+      method.recovery?.status_command,
+    ]) {
+      if (typeof command === "string" && !commands.includes(command)) {
+        commands.push(command);
+      }
+    }
+  }
+  return commands;
+}
+
 function createGuideStage(input) {
   if (input.prompt.length === 0) {
     return "prompt_required";
@@ -1329,7 +1372,9 @@ function createGuideNextCommand(stage, input) {
   if (stage === "quota_required") {
     return renderGuidePrefixedCommand(
       input.commandPrefix,
-      stripImageSkillCommandPrefix(input.paymentSummary.suggested_commands[0]),
+      stripImageSkillCommandPrefix(
+        firstPaymentActionCommand(input.paymentSummary.suggested_commands),
+      ),
     );
   }
   return renderCreateCommand({
@@ -1362,6 +1407,16 @@ function renderTokenStdinCommand(command) {
   return `printf '%s\\n' "$IMAGE_SKILL_TOKEN" | ${command} --token-stdin`;
 }
 
+function firstPaymentActionCommand(commands) {
+  return (
+    commands.find((command) => /\bcredits\s+quote\b/.test(command)) ??
+    commands.find((command) => /\bcredits\s+buy\b/.test(command)) ??
+    commands.find((command) => /\bcredits\s+methods\b/.test(command)) ??
+    commands[0] ??
+    "image-skill credits methods --json"
+  );
+}
+
 function renderCreateCommand(input) {
   return [
     input.commandPrefix ?? "image-skill",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Zero-setup durable creative-media CLI for agents (image + video + audio + 3D): guide-first creation, model and cost inspection, owned URLs, JSON recovery, payments, reusable assets, and feedback.",
   "type": "module",
   "private": false,