agentspend 0.2.0 → 0.2.1

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentspend
-description: Find the right APIs for any task and pay for them, without authentication.
+description: Use this skill when you need to: search the web, generate images or pictures, create videos, scrape or read a webpage, take a screenshot of a website, get stock prices or financial data, look up business info, find news articles, translate text, parse PDFs, do OCR on images, convert files, get weather data, or access any external API that requires payment. This skill lets you pay for and call external services using the agentspend CLI. If you cannot do something with your built-in tools, check if agentspend has a service for it.
 ---
 
 # When To Use This Skill
@@ -9,6 +9,17 @@ Use this skill whenever the user asks to:
 - call an endpoint
 - fetch/search information outside local context
 - pay for x402 services
+- generate an image, video, voice, transcription, or music with an external API
+- scrape/extract data from a URL
+- find an API for a task ("is there an API for X?")
+
+If the task needs an external paid API, start with `agentspend search`.
+
+## Playbook (Default Workflow)
+
+1. `npx agentspend search "<task>"`
+2. Confirm cost and constraints with the user (`--max-cost`, budget, allowlist)
+3. `npx agentspend pay <endpoint> --method ... --header ... --body ... --max-cost ...`
 
 ## Setup
 
@@ -58,10 +69,19 @@ npx agentspend check <url>
 
 Discover an endpoint's price without paying.
 
+Important:
+- `check` must use the same request shape you plan to `pay` with.
+- Always pass `--method` for non-GET endpoints.
+- If the endpoint needs headers/body, include the same `--header` and `--body` on `check`.
+- If request shape is wrong, endpoint may return `404`/`400` instead of `402`, and no price can be extracted.
+
 **Example:**
 
 ```bash
-npx agentspend check <url>
+npx agentspend check <url> \
+  --method POST \
+  --header "content-type:application/json" \
+  --body '{"key":"value"}'
 ```
 
 **Returns:**

package/dist/commands/check.js

@@ -1,9 +1,9 @@
 import { ApiError } from "../lib/api.js";
-import { requireApiKey } from "../lib/credentials.js";
+import { resolveApiKeyWithAutoClaim } from "../lib/auth-flow.js";
 import { formatUsd, usd6ToUsd } from "../lib/output.js";
 import { normalizeMethod, parseBody, parseHeaders } from "../lib/request-options.js";
 export async function runCheck(apiClient, url, options) {
-    const apiKey = await requireApiKey();
+    const apiKey = await resolveApiKeyWithAutoClaim(apiClient);
     try {
         const response = await apiClient.check(apiKey, {
             url,

package/dist/commands/configure.js

@@ -1,29 +1,6 @@
-import bcrypt from "bcryptjs";
-import crypto from "node:crypto";
 import { ApiError } from "../lib/api.js";
-import { clearPendingConfigureToken, readCredentials, readPendingConfigureToken, saveCredentials, savePendingConfigureToken, } from "../lib/credentials.js";
-const POLL_INTERVAL_MS = 2_000;
-const CONFIGURE_TIMEOUT_MS = 10 * 60 * 1000;
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function generateApiKey() {
-    return `sk_agent_${crypto.randomBytes(32).toString("hex")}`;
-}
-function isExpiredStatus(status) {
-    return status.claim_status === "expired";
-}
-async function getStatusOrNull(apiClient, token) {
-    try {
-        return await apiClient.configureStatus(token);
-    }
-    catch (error) {
-        if (error instanceof ApiError && (error.status === 401 || error.status === 404 || error.status === 410)) {
-            return null;
-        }
-        throw error;
-    }
-}
+import { clearPendingConfigureToken, readCredentials, savePendingConfigureToken, } from "../lib/credentials.js";
+import { claimConfigureToken, getPendingConfigureStatus } from "../lib/auth-flow.js";
 async function tryAuthenticatedConfigure(apiClient, apiKey) {
     try {
         return await apiClient.configure(undefined, apiKey);
@@ -35,13 +12,6 @@ async function tryAuthenticatedConfigure(apiClient, apiKey) {
         throw error;
     }
 }
-async function claimAndSaveCredentials(apiClient, token) {
-    const apiKey = generateApiKey();
-    const apiKeyHash = await bcrypt.hash(apiKey, 12);
-    await apiClient.claimConfigure(token, apiKeyHash);
-    await saveCredentials(apiKey);
-    await clearPendingConfigureToken();
-}
 export async function runConfigure(apiClient) {
     const credentials = await readCredentials();
     if (credentials) {
@@ -51,49 +21,24 @@ export async function runConfigure(apiClient) {
             return;
         }
     }
-    let token = await readPendingConfigureToken();
-    let status = null;
-    if (token) {
-        status = await getStatusOrNull(apiClient, token);
-        if (!status || isExpiredStatus(status)) {
-            token = null;
-            status = null;
-            await clearPendingConfigureToken();
-        }
-    }
-    if (!token) {
-        const created = await apiClient.configure();
-        token = created.token;
-        await savePendingConfigureToken(token);
-        status = created;
-    }
-    if (!status) {
-        throw new Error("Unable to initialize configure session. Run agentspend configure again.");
-    }
-    console.log(`Open this URL to configure settings:\n${status.configure_url}\n`);
-    console.log("Waiting for card setup and API key claim...");
-    const started = Date.now();
-    while (Date.now() - started < CONFIGURE_TIMEOUT_MS) {
-        if (status.claim_status === "ready_to_claim") {
-            await claimAndSaveCredentials(apiClient, token);
-            console.log("Ready! Your agent can now spend.");
+    const pending = await getPendingConfigureStatus(apiClient);
+    if (pending) {
+        if (pending.status.claim_status === "awaiting_card") {
+            console.log(`Open this URL to configure settings:\n${pending.status.configure_url}`);
             return;
         }
-        if (status.claim_status === "expired") {
-            await clearPendingConfigureToken();
-            throw new Error("Configure session expired. Run agentspend configure again.");
-        }
-        if (status.claim_status === "claimed") {
-            await clearPendingConfigureToken();
-            throw new Error("Configure session already claimed. Run agentspend configure again.");
-        }
-        await sleep(POLL_INTERVAL_MS);
-        const polled = await getStatusOrNull(apiClient, token);
-        if (!polled) {
-            await clearPendingConfigureToken();
-            throw new Error("Configure session expired. Run agentspend configure again.");
+        if (pending.status.claim_status === "ready_to_claim") {
+            const apiKey = await claimConfigureToken(apiClient, pending.token);
+            const claimedResponse = await tryAuthenticatedConfigure(apiClient, apiKey);
+            if (claimedResponse) {
+                console.log(`Open this URL to configure settings:\n${claimedResponse.configure_url}`);
+                return;
+            }
+            throw new Error("API key was claimed, but configure session could not be created. Run agentspend configure again.");
         }
-        status = polled;
+        await clearPendingConfigureToken();
     }
-    throw new Error("Configure timed out. Run agentspend configure again.");
+    const created = await apiClient.configure();
+    await savePendingConfigureToken(created.token);
+    console.log(`Open this URL to configure settings:\n${created.configure_url}`);
 }

package/dist/commands/pay.js

@@ -1,5 +1,5 @@
 import { ApiError } from "../lib/api.js";
-import { requireApiKey } from "../lib/credentials.js";
+import { resolveApiKeyWithAutoClaim } from "../lib/auth-flow.js";
 import { formatJson, formatUsd, formatUsdEstimate, usd6ToUsd } from "../lib/output.js";
 import { normalizeMethod, parseBody, parseHeaders } from "../lib/request-options.js";
 function isRecord(value) {
@@ -54,7 +54,7 @@ function parsePayErrorBody(body) {
     return parsed;
 }
 export async function runPay(apiClient, url, options) {
-    const apiKey = await requireApiKey();
+    const apiKey = await resolveApiKeyWithAutoClaim(apiClient);
     const method = normalizeMethod(options.method);
     try {
         const response = await apiClient.pay(apiKey, {

package/dist/commands/search.js

@@ -1,6 +1,6 @@
-import { requireApiKey } from "../lib/credentials.js";
+import { resolveApiKeyWithAutoClaim } from "../lib/auth-flow.js";
 export async function runSearch(apiClient, query) {
-    const apiKey = await requireApiKey();
+    const apiKey = await resolveApiKeyWithAutoClaim(apiClient);
     const response = await apiClient.search(apiKey, query);
     if (response.services.length === 0) {
         console.log(`No services matched "${response.query}".`);

package/dist/commands/status.js

@@ -1,7 +1,7 @@
-import { requireApiKey } from "../lib/credentials.js";
+import { resolveApiKeyWithAutoClaim } from "../lib/auth-flow.js";
 import { printStatus } from "../lib/output.js";
 export async function runStatus(apiClient) {
-    const apiKey = await requireApiKey();
+    const apiKey = await resolveApiKeyWithAutoClaim(apiClient);
     const status = await apiClient.status(apiKey);
     printStatus(status);
 }

package/dist/lib/auth-flow.js

@@ -0,0 +1,56 @@
+import bcrypt from "bcryptjs";
+import crypto from "node:crypto";
+import { ApiError } from "./api.js";
+import { clearPendingConfigureToken, readCredentials, readPendingConfigureToken, saveCredentials, } from "./credentials.js";
+function generateApiKey() {
+    return `sk_agent_${crypto.randomBytes(32).toString("hex")}`;
+}
+async function getConfigureStatusOrNull(apiClient, token) {
+    try {
+        return await apiClient.configureStatus(token);
+    }
+    catch (error) {
+        if (error instanceof ApiError && (error.status === 401 || error.status === 404 || error.status === 410)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function claimConfigureToken(apiClient, token) {
+    const apiKey = generateApiKey();
+    const apiKeyHash = await bcrypt.hash(apiKey, 12);
+    await apiClient.claimConfigure(token, apiKeyHash);
+    await saveCredentials(apiKey);
+    await clearPendingConfigureToken();
+    return apiKey;
+}
+export async function getPendingConfigureStatus(apiClient) {
+    const token = await readPendingConfigureToken();
+    if (!token) {
+        return null;
+    }
+    const status = await getConfigureStatusOrNull(apiClient, token);
+    if (!status || status.claim_status === "expired") {
+        await clearPendingConfigureToken();
+        return null;
+    }
+    return { token, status };
+}
+export async function resolveApiKeyWithAutoClaim(apiClient) {
+    const credentials = await readCredentials();
+    if (credentials) {
+        return credentials.api_key;
+    }
+    const pending = await getPendingConfigureStatus(apiClient);
+    if (!pending) {
+        throw new Error("No API key found. Run `agentspend configure` first.");
+    }
+    if (pending.status.claim_status === "ready_to_claim") {
+        return claimConfigureToken(apiClient, pending.token);
+    }
+    if (pending.status.claim_status === "awaiting_card") {
+        throw new Error(`Card setup required. Open this URL:\n${pending.status.configure_url}`);
+    }
+    await clearPendingConfigureToken();
+    throw new Error("Configure session already claimed. Run `agentspend configure` again.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentspend",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "AgentSpend CLI for managed x402 spending",
   "files": ["dist", "SKILL.md"],
   "type": "module",