image-skill 0.1.1 → 0.1.2

package/README.md

@@ -17,6 +17,7 @@ Install the executable CLI from npm:
 npm install -g image-skill
 image-skill doctor --json
 image-skill signup --agent --human-email human@example.com --agent-name creative-agent --runtime openclaw --save --json
+image-skill credits methods --json
 image-skill credits packs list --json
 image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key first-topup-001 --json
 image-skill credits buy --provider stripe --quote-id quote_... --idempotency-key first-buy-001 --json

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.1";
+const VERSION = "0.1.2";
 const DEFAULT_API_BASE_URL = "https://api.image-skill.com";
 const DEFAULT_CONFIG_PATH = join(
   process.env.XDG_CONFIG_HOME ?? join(os.homedir(), ".config"),
@@ -41,6 +41,7 @@ async function main(rawArgv) {
         "auth logout",
         "whoami",
         "usage quota",
+        "credits methods",
         "credits packs list",
         "credits quote",
         "credits buy",
@@ -335,6 +336,32 @@ async function quota(argv) {
 
 async function credits(argv) {
   const [subcommand, ...rest] = argv;
+  if (subcommand === "methods") {
+    const args = parseArgs(rest);
+    const unknownFlags = [...args.flags.keys()].filter(
+      (flag) => !["json", "api-base-url"].includes(flag),
+    );
+    if (!flagBool(args, "json")) {
+      return invalid(
+        "image-skill credits methods",
+        "credits methods requires --json",
+      );
+    }
+    if (args.positionals.length > 0 || unknownFlags.length > 0) {
+      return invalid(
+        "image-skill credits methods",
+        unknownFlags.length > 0
+          ? `unsupported flags for credits methods: ${unknownFlags.map((flag) => `--${flag}`).join(", ")}`
+          : "credits methods does not accept positional arguments",
+      );
+    }
+    return apiRequest({
+      command: "image-skill credits methods",
+      method: "GET",
+      apiBaseUrl: apiBase(args),
+      path: "/v1/payment-methods",
+    });
+  }
   if (subcommand === "packs") {
     const [packsSubcommand, ...packsRest] = rest;
     if (packsSubcommand !== "list") {
@@ -483,7 +510,7 @@ async function credits(argv) {
   }
   return invalid(
     "image-skill credits",
-    "credits requires packs, quote, buy, status, or fake-purchase",
+    "credits requires methods, packs, quote, buy, status, or fake-purchase",
   );
 }
 

package/cli.md

@@ -109,6 +109,58 @@ curl -sS https://api.image-skill.com/v1/quota \
   -H "authorization: Bearer $IMAGE_SKILL_TOKEN"
 ```
 
+### `image-skill credits methods`
+
+Machine-readable payment rail discovery. Use this before quoting or buying so
+agents can tell which rails are available, whether live money can move, whether
+browser/human action is required, and which command to try next.
+
+```bash
+image-skill credits methods --json
+```
+
+Minimum success data shape:
+
+```json
+{
+  "contract_version": "image-skill.payment-methods.v1",
+  "credit_unit_cents": 1,
+  "currency": "USD",
+  "quote_endpoint": "/v1/credit-quotes",
+  "packs_endpoint": "/v1/credit-packs",
+  "status_endpoint": "/v1/credit-purchases/status",
+  "methods": [
+    {
+      "method_id": "fake",
+      "available": true,
+      "live_money": false,
+      "buyer_modes": ["agent_only", "hybrid", "human_only"],
+      "requires_browser": false,
+      "purchase_endpoint": "/v1/credit-purchases"
+    },
+    {
+      "method_id": "stripe_checkout",
+      "available": true,
+      "live_money": true,
+      "buyer_modes": ["hybrid", "human_only"],
+      "requires_browser": true,
+      "default_pack_id": "starter-500",
+      "purchase_endpoint": "/v1/credit-purchases/stripe-checkout-sessions"
+    }
+  ]
+}
+```
+
+`available` is environment-dependent. `available:false` means the rail is known
+but not currently usable in the queried environment; read `unavailable_reason`
+and `recovery`.
+
+Hosted API equivalent:
+
+```bash
+curl -sS https://api.image-skill.com/v1/payment-methods
+```
+
 ### `image-skill credits packs list`
 
 Lists the recommended Image Skill credit packs for Stripe Checkout. Packs are
@@ -819,7 +871,7 @@ example, `BUDGET_REQUIRES_CONFIRMATION` returns
 `credits status`, `credits fake-purchase`, `create`, `activity list`,
 `activity show`, and `feedback create` accept `--token-stdin` for stdin-based
 secret handoff.
-`credits packs list` does not require auth.
+`credits methods` and `credits packs list` do not require auth.
 
 Feedback should avoid raw prompts, provider keys, generated image bytes, source
 image bytes, and private user data.

package/llms.txt

@@ -49,11 +49,12 @@ First-run flow:
 4. image-skill whoami --json
 5. image-skill usage quota --json
 5-credit-note. One Image Skill credit is $0.01. Credit quotes grant prepaid value units; create/edit operations debit model-priced credits reported as cost.credit_pricing. Starter preview currently gives bounded free-preview credits plus a two-job daily cap.
-5a. image-skill credits packs list --json to inspect recommended live-money packs.
-5b. image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json for the default Stripe Checkout top-up path. Use --credits CREDITS instead of --pack only when the required exact budget is already known.
-5c. image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json when the agent has a stripe_checkout quote and needs a Stripe-hosted checkout_url. Credits are granted only after verified Stripe webhook fulfillment succeeds.
-5d. image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy or checkout completion to read durable payment state, receipt, credit_event, limits, and retry guidance without inferring from quota text.
-5e. image-skill credits quote --credits 10 --json and image-skill credits fake-purchase --quote-id QUOTE_ID --idempotency-key KEY --json only for fake/test credit-ledger proof. This moves no live money, accepts no payment credential, and returns live_money:false.
+5a. image-skill credits methods --json to inspect payment rails, availability, buyer modes, browser requirements, and recovery commands before quoting or buying.
+5b. image-skill credits packs list --json to inspect recommended live-money packs.
+5c. image-skill credits quote --pack starter-500 --payment-method stripe_checkout --idempotency-key KEY --json for the default Stripe Checkout top-up path. Use --credits CREDITS instead of --pack only when the required exact budget is already known.
+5d. image-skill credits buy --provider stripe --quote-id QUOTE_ID --idempotency-key KEY --json when the agent has a stripe_checkout quote and needs a Stripe-hosted checkout_url. Credits are granted only after verified Stripe webhook fulfillment succeeds.
+5e. image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy or checkout completion to read durable payment state, receipt, credit_event, limits, and retry guidance without inferring from quota text.
+5f. image-skill credits quote --credits 10 --json and image-skill credits fake-purchase --quote-id QUOTE_ID --idempotency-key KEY --json only for fake/test credit-ledger proof. This moves no live money, accepts no payment credential, and returns live_money:false.
 6. image-skill create --dry-run --prompt PROMPT --json for zero-cost planning.
 7. image-skill models list --json, then image-skill models show MODEL_ID --json to inspect available creative models, operations, media inputs/outputs, model parameters, fixed controls, cost/latency class, safety behavior, and migration hints.
 8. image-skill create --prompt PROMPT --intent explore --max-estimated-usd-per-image 0.05 --json for the first bounded free-preview operation when quota allows.
@@ -70,6 +71,7 @@ Core commands:
 - image-skill whoami --json
 - image-skill usage quota --json
 - image-skill quota --json (compatibility alias)
+- image-skill credits methods --json
 - image-skill credits packs list --json
 - image-skill credits quote --pack PACK_ID --payment-method fake|stripe_checkout --idempotency-key KEY --json
 - image-skill credits quote --credits CREDITS --payment-method fake|stripe_checkout --idempotency-key KEY --json
@@ -99,6 +101,7 @@ Hosted API endpoints:
 - POST https://api.image-skill.com/v1/agent-signups creates or rotates a restricted unclaimed agent token. The response returns the token once as data.token. Store it in the agent runtime secret store; never put it in prompts, logs, issue text, or feedback.
 - GET https://api.image-skill.com/v1/whoami returns durable hosted identity for Authorization: Bearer TOKEN.
 - GET https://api.image-skill.com/v1/quota returns durable hosted quota for Authorization: Bearer TOKEN.
+- GET https://api.image-skill.com/v1/payment-methods returns the no-auth payment rail catalog. It tells agents which rails are available, whether live money can move, buyer modes (agent_only, hybrid, human_only), browser requirements, limits, endpoint paths, and recovery commands.
 - GET https://api.image-skill.com/v1/credit-packs returns the public pack catalog. Recommended live-money packs include starter-500, builder-2000, and studio-5000. Packs are the default Stripe Checkout UX; exact quotes remain supported for agents that already know the required credit budget.
 - POST https://api.image-skill.com/v1/credit-quotes returns a fake/test or stripe_checkout credit quote for Authorization: Bearer TOKEN. Request JSON: either credits or pack_id, optional payment_method, idempotency_key. Response includes quote_id, credits, price_amount_cents, currency, accepted_payment_method, pack_id, pack, and live_money. One credit equals $0.01, so price_amount_cents equals credits. This does not grant credits.
 - POST https://api.image-skill.com/v1/credit-purchases/stripe-checkout-sessions creates a Stripe Checkout Session for a stripe_checkout quote. Request JSON: quote_id, idempotency_key. Response includes state: action_required, payment_attempt_id, checkout_session_id, checkout_url, accepted_payment_method: stripe_checkout, and next.human_action: open_checkout_url. This does not grant credits; verified Stripe webhook fulfillment grants paid credits exactly once.
@@ -178,7 +181,7 @@ Unclaimed agents may not:
 - send card data, wallet secrets, provider receipts, Stripe secrets, MPP tokens, SPTs, or any payment credential to Image Skill; Stripe payment details must be entered only on Stripe-hosted checkout pages
 
 Credits:
-One Image Skill credit is $0.01. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --json for exact bounded custom top-ups when the required budget is already known. The default payment_method is fake. Use image-skill credits buy --provider stripe --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_url and does not grant credits. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Use image-skill credits fake-purchase --json only to exercise the quote, receipt, credit-ledger, and activity-audit contract before live settlement rails are enabled. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Credits buy and fake-purchase require explicit --idempotency-key. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
+One Image Skill credit is $0.01. Use image-skill credits methods --json to inspect payment rail availability and whether a browser/human action is required. Use image-skill credits packs list --json to inspect recommended Stripe Checkout packs. Use image-skill credits quote --pack PACK_ID --payment-method stripe_checkout --json for the default live-money top-up path. Use image-skill credits quote --credits CREDITS --json for exact bounded custom top-ups when the required budget is already known. The default payment_method is fake. Use image-skill credits buy --provider stripe --json to create a hosted Stripe Checkout Session for a stripe_checkout quote; this returns checkout_url and does not grant credits. Use image-skill credits status --payment-attempt-id PAYMENT_ATTEMPT_ID --json after buy and after checkout completion to read state, receipt, credit_event, limits, and retry guidance. Use image-skill credits fake-purchase --json only to exercise the quote, receipt, credit-ledger, and activity-audit contract before live settlement rails are enabled. Create/edit debit model-priced credits after provider success; inspect models show and operation cost.credit_pricing for credits_required and pricing_confidence. Credits buy and fake-purchase require explicit --idempotency-key. Never send payment credentials to Image Skill; Stripe collects payment details on Stripe-hosted pages. Public request fields are credits, pack_id, payment_method, quote_id, status reference IDs, and idempotency_key.
 
 Telemetry:
 - command or endpoint name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-skill",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Thin hosted CLI for Image Skill, a creative runtime for agents.",
   "type": "module",
   "private": false,

package/skill.md

@@ -81,6 +81,7 @@ path to meaningful usage.
 Credit quote and buy flow:
 
 ```bash
+image-skill credits methods --json
 image-skill credits packs list --json
 image-skill credits quote \
   --pack starter-500 \
@@ -102,7 +103,10 @@ image-skill credits fake-purchase \
 This is the agent-facing precursor to future MPP, Stripe, wallet, or
 delegated-card adapters. Packs are the default Stripe Checkout UX; exact
 `--credits` quotes remain available when an agent already knows the required
-budget. `credits buy --provider stripe` returns a
+budget. `credits methods --json` tells agents which rails are currently
+available, which buyer modes they support, and whether browser/human action is
+required before an agent tries to quote or buy. `credits buy --provider stripe`
+returns a
 Stripe-hosted `checkout_url` for a `stripe_checkout` quote and does not grant
 credits until verified webhook fulfillment succeeds. `credits fake-purchase`
 returns `live_money:false`, moves no live money, accepts no payment credential,
@@ -293,6 +297,8 @@ closed if durable hosted feedback storage is unavailable.
 
 - Check `usage quota --json` before costly workflows. `quota --json` remains a
   compatibility alias.
+- Use `credits methods --json` to inspect payment rail availability, buyer
+  modes, limits, and recovery commands before quoting or buying.
 - Use `credits packs list --json` to inspect recommended live-money packs.
 - Use `credits quote --pack PACK_ID --payment-method stripe_checkout --json`
   for the default Stripe Checkout path.