agentmall 0.1.1 → 0.1.4

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+// src/cli/index.ts
+import { spawn } from "child_process";
+
 // src/constants.ts
 var BASE_URL = "https://api.agentmall.sh";
 var SERVICE_FEE_CENTS = 150;
@@ -80,6 +83,10 @@ var AgentMall = class {
     this.refunds = new AgentMallRefunds(this);
   }
   /** @internal */
+  hasApiSecret() {
+    return Boolean(this.apiSecret);
+  }
+  /** @internal */
   async request(method, path, options) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (options?.params) {
@@ -159,8 +166,19 @@ var AgentMallPurchases = class {
       }
     });
   }
-  /** Get a single purchase by ID. Requires apiSecret. */
-  async get(id) {
+  /** Get a single purchase by ID using either operator auth or a buyer token. */
+  async get(id, options) {
+    if (options?.buyerToken) {
+      return this.client.request("POST", "/api/purchases/status", {
+        body: {
+          id,
+          buyer_token: options.buyerToken
+        }
+      });
+    }
+    if (!this.client.hasApiSecret()) {
+      throw new Error("buyerToken or apiSecret is required for this endpoint");
+    }
     return this.client.request("GET", "/api/purchases", {
       auth: true,
       params: { id }
@@ -208,6 +226,33 @@ var AgentMallRefunds = class {
       params: { id }
     });
   }
+  /** Get refund status for a purchase using either operator auth or a buyer token. */
+  async getByPurchase(purchaseId, options) {
+    if (options?.buyerToken) {
+      return this.client.request("POST", "/api/refunds/status", {
+        body: {
+          purchase_id: purchaseId,
+          buyer_token: options.buyerToken
+        }
+      });
+    }
+    if (!this.client.hasApiSecret()) {
+      throw new Error("buyerToken or apiSecret is required for this endpoint");
+    }
+    const result = await this.client.request(
+      "GET",
+      "/api/refunds",
+      {
+        auth: true,
+        params: { purchase_id: purchaseId }
+      }
+    );
+    const refund2 = result.refunds[0];
+    if (!refund2) {
+      throw new AgentMallError(404, { error: "Not found" });
+    }
+    return refund2;
+  }
   /** List refunds. Requires apiSecret. */
   async list(filters) {
     const result = await this.client.request(
@@ -219,31 +264,24 @@ var AgentMallRefunds = class {
   }
 };
 
-// src/purchase.ts
-async function purchase(config) {
-  const { account, baseUrl, ...body } = config;
-  let mppxClient;
-  try {
-    mppxClient = await import("mppx/client");
-  } catch {
-    throw new Error("mppx is required for purchases. Install it: npm install mppx");
-  }
-  const Mppx = mppxClient.Mppx;
-  const tempo = mppxClient.tempo;
-  if (!Mppx || !tempo) {
-    throw new Error("mppx is required for purchases. Install it: npm install mppx");
-  }
-  const mppx = Mppx.create({
-    methods: [tempo({ account })]
-  });
-  const client = new AgentMall({
-    baseUrl: baseUrl ?? BASE_URL,
-    fetch: mppx.fetch.bind(mppx)
-  });
-  return client.purchases.create(body);
-}
-
 // src/cli/display.ts
+var FAILURE_MESSAGES = {
+  budget_exceeded: "Actual total exceeded your maximum budget.",
+  out_of_stock: "Item is out of stock.",
+  product_not_found: "Product is no longer available.",
+  product_unavailable: "Product cannot be purchased right now.",
+  variant_required: "A required size, color, or variant must be selected.",
+  variant_unavailable: "Selected variant is unavailable.",
+  quantity_unavailable: "Requested quantity is unavailable.",
+  quantity_limit: "Retailer quantity limit exceeded.",
+  invalid_url: "Product URL is invalid.",
+  invalid_address: "Shipping address could not be validated.",
+  shipping_unavailable: "Item cannot be shipped to this address.",
+  retailer_unavailable: "Retailer is temporarily unavailable.",
+  unsupported_retailer: "Retailer is not supported.",
+  validation_failed: "Order request failed validation.",
+  cancelled: "Order was cancelled."
+};
 function formatCents(cents) {
   return `$${(cents / 100).toFixed(2)}`;
 }
@@ -268,7 +306,7 @@ function displayProduct(product) {
   }
   console.log();
   console.log(
-    `  Suggested budget: \x1B[1m${formatCents(product.suggestedMaxBudget)}\x1B[0m (includes 15% buffer for tax & shipping)`
+    `  Suggested budget: \x1B[1m${formatCents(product.suggestedMaxBudget)}\x1B[0m (includes 15% buffer for tax and an $8 minimum shipping buffer)`
   );
   console.log(
     `  Service fee: ${formatCents(SERVICE_FEE_CENTS)}`
@@ -314,6 +352,9 @@ function displayOrderResult(order) {
   }
   console.log(`  ID: \x1B[1m${order.id}\x1B[0m`);
   console.log(`  Status: ${order.status}`);
+  if (order.buyerToken) {
+    console.log("  Saved local access token for status and refund checks.");
+  }
   console.log();
   console.log(
     order.status === "failed" ? "  Check status for failure details and refund progress:" : "  Check status in 5-10 minutes:"
@@ -321,26 +362,43 @@ function displayOrderResult(order) {
   console.log(`  npx agentmall status ${order.id}`);
   console.log();
 }
-function displayStatus(purchase2) {
+function displayStatus(purchase) {
   console.log();
-  console.log(`  \x1B[1mOrder ${purchase2.id}\x1B[0m`);
-  console.log(`  Status: ${purchase2.status}`);
-  if (purchase2.items?.length) {
-    for (const item of purchase2.items) {
+  console.log(`  \x1B[1mOrder ${purchase.id}\x1B[0m`);
+  console.log(`  Status: ${purchase.status}`);
+  if (purchase.items?.length) {
+    for (const item of purchase.items) {
       const price = item.price ? ` \u2014 ${formatCents(item.price)}` : "";
       console.log(`  ${item.quantity}x ${item.title ?? item.productRef}${price}`);
     }
   }
-  if (purchase2.finalTotal) {
-    console.log(`  Final total: ${formatCents(purchase2.finalTotal)}`);
+  if (purchase.finalTotal) {
+    console.log(`  Final total: ${formatCents(purchase.finalTotal)}`);
   }
-  if (purchase2.failureReason) {
-    console.log(`  \x1B[31mFailure: ${purchase2.failureReason}\x1B[0m`);
+  if (purchase.failureReason) {
+    console.log(
+      `  \x1B[31mFailure: ${FAILURE_MESSAGES[purchase.failureReason] ?? purchase.failureReason}\x1B[0m`
+    );
   }
-  if (purchase2.deliveryMethod) {
-    console.log(`  Shipping: ${purchase2.deliveryMethod}`);
+  if (purchase.deliveryMethod) {
+    console.log(`  Shipping: ${purchase.deliveryMethod}`);
+  }
+  console.log(`  Created: ${new Date(purchase.createdAt).toLocaleString()}`);
+  console.log();
+}
+function displayRefund(refund2) {
+  console.log();
+  console.log(`  \x1B[1mRefund ${refund2.id}\x1B[0m`);
+  console.log(`  Status: ${refund2.status}`);
+  console.log(`  Amount: ${formatCents(refund2.amountCents)}`);
+  console.log(`  Reason: ${refund2.reason}`);
+  if (refund2.txHash) {
+    console.log(`  TX: ${refund2.txHash}`);
+  }
+  console.log(`  Created: ${new Date(refund2.createdAt).toLocaleString()}`);
+  if (refund2.processedAt) {
+    console.log(`  Processed: ${new Date(refund2.processedAt).toLocaleString()}`);
   }
-  console.log(`  Created: ${new Date(purchase2.createdAt).toLocaleString()}`);
   console.log();
 }
 
@@ -416,34 +474,181 @@ async function promptAddress() {
 async function promptConfirm(message) {
   return confirm({ message });
 }
-async function promptBudget(suggested) {
+function formatCents2(cents) {
+  return `$${(cents / 100).toFixed(2)}`;
+}
+function parseBudgetInput(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^\d+\.\d{1,2}$/.test(trimmed)) {
+    return Math.round(Number(trimmed) * 100);
+  }
+  if (/^\d+$/.test(trimmed)) {
+    return parseInt(trimmed, 10);
+  }
+  return null;
+}
+async function promptBudget(suggested, minimumCents) {
   const value = await input({
-    message: `Max budget in cents (suggested: ${suggested})`,
+    message: `Max budget in cents (e.g. ${suggested} = ${formatCents2(suggested)})`,
     default: String(suggested),
     validate: (v) => {
-      const n = parseInt(v, 10);
-      if (isNaN(n) || n <= 0) return "Must be a positive integer";
+      const n = parseBudgetInput(v);
+      if (n === null || n <= 0) {
+        return "Enter cents like 1540 or dollars like 15.40";
+      }
+      if (n < minimumCents) {
+        return `Max budget must be at least the current product price ${formatCents2(minimumCents)}`;
+      }
       return true;
     }
   });
-  return parseInt(value, 10);
+  const parsed = parseBudgetInput(value);
+  if (parsed === null) {
+    throw new Error("Invalid budget input");
+  }
+  return parsed;
+}
+
+// src/cli/tokenStore.ts
+import { chmod, mkdir, readFile, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var STORE_PATH = join(homedir(), ".agentmall", "tokens.json");
+function emptyStore() {
+  return {
+    version: 1,
+    purchases: {}
+  };
+}
+async function readStore() {
+  try {
+    const raw = await readFile(STORE_PATH, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      version: 1,
+      purchases: parsed.purchases ?? {}
+    };
+  } catch {
+    return emptyStore();
+  }
+}
+async function writeStore(store) {
+  await mkdir(dirname(STORE_PATH), { recursive: true });
+  await writeFile(STORE_PATH, JSON.stringify(store, null, 2), "utf8");
+  try {
+    await chmod(STORE_PATH, 384);
+  } catch {
+  }
+}
+async function saveBuyerToken(purchaseId, buyerToken) {
+  const store = await readStore();
+  store.purchases[purchaseId] = {
+    buyerToken,
+    savedAt: Date.now()
+  };
+  await writeStore(store);
+}
+async function getBuyerToken(purchaseId) {
+  const store = await readStore();
+  return store.purchases[purchaseId]?.buyerToken ?? null;
 }
 
 // src/cli/index.ts
 var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-async function resolveAccount() {
+async function runCommandCapture(command2, args2) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command2, args2, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: process.platform === "win32"
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", reject);
+    child.on(
+      "exit",
+      (code) => resolve({
+        code: code ?? 1,
+        stdout,
+        stderr
+      })
+    );
+  });
+}
+async function runInteractiveCommand(command2, args2) {
+  return await new Promise((resolve, reject) => {
+    const child = spawn(command2, args2, {
+      stdio: "inherit",
+      shell: process.platform === "win32"
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => resolve(code ?? 1));
+  });
+}
+async function readTempoWhoami() {
   try {
-    const { resolveAccount: resolve } = await import("mppx/cli");
-    return await resolve();
+    const result = await runCommandCapture("tempo", ["wallet", "-j", "whoami"]);
+    if (result.code !== 0) return null;
+    return JSON.parse(result.stdout);
   } catch {
-    const key = process.env.MPPX_PRIVATE_KEY;
-    if (!key) {
-      console.error("\x1B[31mNo wallet found.\x1B[0m");
-      console.error("Set MPPX_PRIVATE_KEY or run: npx mppx account create");
-      process.exit(1);
-    }
-    const { privateKeyToAccount } = await import("viem/accounts");
-    return privateKeyToAccount(key);
+    return null;
+  }
+}
+async function ensureTempoInstalled() {
+  try {
+    const result = await runCommandCapture("tempo", ["--version"]);
+    if (result.code === 0) return;
+  } catch {
+  }
+  console.error("\x1B[31mTempo CLI is required for purchases.\x1B[0m");
+  console.error("");
+  console.error("Install it first:");
+  console.error("  curl -fsSL https://tempo.xyz/install | bash");
+  process.exit(1);
+}
+async function ensureTempoReady() {
+  await ensureTempoInstalled();
+  const whoami = await readTempoWhoami();
+  if (whoami?.ready) return whoami;
+  console.log("  Tempo wallet login required...");
+  const loginCode = await runInteractiveCommand("tempo", ["wallet", "login"]);
+  if (loginCode !== 0) {
+    throw new Error("Tempo wallet login failed");
+  }
+  const afterLogin = await readTempoWhoami();
+  if (afterLogin?.ready) return afterLogin;
+  throw new Error("Tempo wallet is not ready after login");
+}
+function formatUsdAmount(cents) {
+  return (cents / 100).toFixed(2);
+}
+async function createPurchaseWithTempo(body) {
+  const totalChargeCents = body.max_budget + SERVICE_FEE_CENTS;
+  const result = await runCommandCapture("tempo", [
+    "request",
+    "-s",
+    "--max-spend",
+    formatUsdAmount(totalChargeCents),
+    "-X",
+    "POST",
+    "--json",
+    JSON.stringify(body),
+    `${BASE_URL}/api/purchases`
+  ]);
+  if (result.code !== 0) {
+    const message = result.stderr.trim() || result.stdout.trim() || "Tempo request failed";
+    throw new Error(message);
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch {
+    throw new Error(`Unexpected response from Tempo request: ${result.stdout.trim() || "(empty)"}`);
   }
 }
 async function buy(urlArg) {
@@ -451,15 +656,14 @@ async function buy(urlArg) {
     console.log();
     console.log("  \x1B[1magentmall\x1B[0m \u2014 Buy anything with a URL");
     console.log();
-    const account = await resolveAccount();
     const url = urlArg ?? await promptProductUrl();
     const client = new AgentMall();
-    console.log("  Fetching product info...");
+    console.log("  Looking up product...");
     const product = await client.products.lookup(url);
     displayProduct(product);
     const variantSelections = product.variants?.length ? await promptVariants(product.variants) : void 0;
     const address = await promptAddress();
-    const maxBudget = await promptBudget(product.suggestedMaxBudget);
+    const maxBudget = await promptBudget(product.suggestedMaxBudget, product.price);
     const { input: input2 } = await import("@inquirer/prompts");
     const buyerEmail = await input2({
       message: "Email for order updates",
@@ -483,11 +687,16 @@ async function buy(urlArg) {
       console.log("  Cancelled.");
       return;
     }
+    const wallet = await ensureTempoReady();
+    if (wallet.wallet) {
+      const balance = wallet.balance?.available ? `, balance ${wallet.balance.available} ${wallet.balance?.symbol ?? "USDC"}` : "";
+      console.log(`  Paying with Tempo wallet ${wallet.wallet}${balance}`);
+    }
     console.log("  Placing order...");
-    const order = await purchase({
-      ...body,
-      account
-    });
+    const order = await createPurchaseWithTempo(body);
+    if (order.buyerToken) {
+      await saveBuyerToken(order.id, order.buyerToken);
+    }
     displayOrderResult(order);
   } catch (error) {
     console.log();
@@ -516,14 +725,48 @@ async function buy(urlArg) {
 }
 async function status(purchaseId) {
   const apiSecret = process.env.AGENTMALL_API_SECRET;
-  if (!apiSecret) {
-    console.error("\x1B[31mAGENTMALL_API_SECRET is required.\x1B[0m");
-    process.exit(1);
-  }
-  const client = new AgentMall({ apiSecret });
-  const result = await client.purchases.get(purchaseId);
+  const buyerToken = apiSecret ? null : await getBuyerToken(purchaseId);
+  const client = apiSecret ? new AgentMall({ apiSecret }) : new AgentMall();
+  if (!apiSecret && !buyerToken) {
+    throw new Error("No saved buyer token found for this order on this machine.");
+  }
+  const result = await client.purchases.get(
+    purchaseId,
+    buyerToken ? { buyerToken } : void 0
+  );
   displayStatus(result);
 }
+async function refund(purchaseId) {
+  const apiSecret = process.env.AGENTMALL_API_SECRET;
+  const buyerToken = apiSecret ? null : await getBuyerToken(purchaseId);
+  const client = apiSecret ? new AgentMall({ apiSecret }) : new AgentMall();
+  if (!apiSecret && !buyerToken) {
+    throw new Error("No saved buyer token found for this order on this machine.");
+  }
+  const result = await client.refunds.getByPurchase(
+    purchaseId,
+    buyerToken ? { buyerToken } : void 0
+  );
+  displayRefund(result);
+}
+async function onboard() {
+  console.log();
+  console.log("  \x1B[1magentmall onboarding\x1B[0m");
+  console.log();
+  const wallet = await ensureTempoReady();
+  console.log();
+  if (wallet.wallet) {
+    console.log(`  Wallet ready: ${wallet.wallet}`);
+  }
+  if (wallet.balance?.available) {
+    console.log(`  Available balance: ${wallet.balance.available} ${wallet.balance?.symbol ?? "USDC"}`);
+  }
+  console.log("  Next steps:");
+  console.log("  1. Run \x1B[1mtempo wallet whoami\x1B[0m to review your wallet");
+  console.log("  2. Add funds to your Tempo wallet if needed");
+  console.log("  3. Retry your purchase with \x1B[1mnpx agentmall buy <url>\x1B[0m");
+  console.log();
+}
 
 // src/cli.ts
 var args = process.argv.slice(2);
@@ -541,6 +784,17 @@ async function main() {
         }
         await status(args[1]);
         break;
+      case "refund":
+        if (!args[1]) {
+          console.error("Usage: agentmall refund <purchase_id>");
+          process.exit(1);
+        }
+        await refund(args[1]);
+        break;
+      case "onboard":
+      case "setup":
+        await onboard();
+        break;
       case "help":
       case "--help":
       case "-h":
@@ -566,14 +820,12 @@ function printHelp() {
   \x1B[1magentmall\x1B[0m \u2014 Buy anything with a URL
 
   Usage:
+    agentmall onboard            Log in to Tempo and show wallet funding steps
     agentmall [url]              Buy a product (interactive)
     agentmall buy <url>          Buy a product
-    agentmall status <id>        Check order status
+    agentmall status <id>        Check order status using the saved buyer token
+    agentmall refund <id>        Check refund status using the saved buyer token
     agentmall help               Show this help
-
-  Environment:
-    MPPX_PRIVATE_KEY             Wallet private key for payments
-    AGENTMALL_API_SECRET         Operator secret for read endpoints
 `);
 }
 main();

package/dist/index.cjs

@@ -123,6 +123,10 @@ var AgentMall = class {
     this.refunds = new AgentMallRefunds(this);
   }
   /** @internal */
+  hasApiSecret() {
+    return Boolean(this.apiSecret);
+  }
+  /** @internal */
   async request(method, path, options) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (options?.params) {
@@ -202,8 +206,19 @@ var AgentMallPurchases = class {
       }
     });
   }
-  /** Get a single purchase by ID. Requires apiSecret. */
-  async get(id) {
+  /** Get a single purchase by ID using either operator auth or a buyer token. */
+  async get(id, options) {
+    if (options?.buyerToken) {
+      return this.client.request("POST", "/api/purchases/status", {
+        body: {
+          id,
+          buyer_token: options.buyerToken
+        }
+      });
+    }
+    if (!this.client.hasApiSecret()) {
+      throw new Error("buyerToken or apiSecret is required for this endpoint");
+    }
     return this.client.request("GET", "/api/purchases", {
       auth: true,
       params: { id }
@@ -251,6 +266,33 @@ var AgentMallRefunds = class {
       params: { id }
     });
   }
+  /** Get refund status for a purchase using either operator auth or a buyer token. */
+  async getByPurchase(purchaseId, options) {
+    if (options?.buyerToken) {
+      return this.client.request("POST", "/api/refunds/status", {
+        body: {
+          purchase_id: purchaseId,
+          buyer_token: options.buyerToken
+        }
+      });
+    }
+    if (!this.client.hasApiSecret()) {
+      throw new Error("buyerToken or apiSecret is required for this endpoint");
+    }
+    const result = await this.client.request(
+      "GET",
+      "/api/refunds",
+      {
+        auth: true,
+        params: { purchase_id: purchaseId }
+      }
+    );
+    const refund = result.refunds[0];
+    if (!refund) {
+      throw new AgentMallError(404, { error: "Not found" });
+    }
+    return refund;
+  }
   /** List refunds. Requires apiSecret. */
   async list(filters) {
     const result = await this.client.request(

package/dist/index.d.cts

@@ -1,11 +1,17 @@
 type AgentMallConfig = {
     /** API base URL. Defaults to https://api.agentmall.sh */
     baseUrl?: string;
-    /** Operator API secret for read endpoints (Bearer auth). */
+    /** Operator API secret for admin read endpoints (Bearer auth). */
     apiSecret?: string;
     /** Custom fetch implementation (e.g. mppx-wrapped fetch for automatic 402 handling). */
     fetch?: typeof globalThis.fetch;
 };
+type WalletAccount = {
+    address: string;
+    signMessage(args: {
+        message: string;
+    }): Promise<string>;
+};
 type ProductVariant = {
     label?: string;
     value: string;
@@ -25,7 +31,7 @@ type ProductLookup = {
     availability: string;
     imageUrl?: string;
     retailer: string;
-    /** Suggested max_budget in cents (list price + 15% buffer). */
+    /** Suggested max_budget in cents (list price + a buffer, with a minimum $8 buffer). */
     suggestedMaxBudget: number;
     variants?: ProductVariant[];
     /** True if served from cache. Price may not reflect current listing. */
@@ -64,7 +70,14 @@ type CreatePurchaseResponse = {
     id: string;
     status: PurchaseLifecycleStatus;
     deduplicated?: boolean;
+    buyerToken?: string;
+};
+type PurchaseStatusChallenge = {
+    challenge: string;
+    message: string;
+    expiresAt: number;
 };
+type RefundStatusChallenge = PurchaseStatusChallenge;
 type PurchaseItem = {
     productRef: string;
     quantity: number;
@@ -138,6 +151,8 @@ declare class AgentMall {
     refunds: AgentMallRefunds;
     constructor(config?: AgentMallConfig);
     /** @internal */
+    hasApiSecret(): boolean;
+    /** @internal */
     request<T>(method: string, path: string, options?: {
         body?: unknown;
         auth?: boolean;
@@ -159,8 +174,10 @@ declare class AgentMallPurchases {
      * Use mppx-wrapped fetch to handle payment automatically, or catch PaymentRequiredError.
      */
     create(body: CreatePurchaseRequest): Promise<CreatePurchaseResponse>;
-    /** Get a single purchase by ID. Requires apiSecret. */
-    get(id: string): Promise<Purchase>;
+    /** Get a single purchase by ID using either operator auth or a buyer token. */
+    get(id: string, options?: {
+        buyerToken?: string;
+    }): Promise<Purchase>;
     /** List purchases. Requires apiSecret. */
     list(filters?: PurchaseFilters): Promise<Purchase[]>;
 }
@@ -177,6 +194,10 @@ declare class AgentMallRefunds {
     constructor(client: AgentMall);
     /** Get a single refund by public ID. Requires apiSecret. */
     get(id: string): Promise<Refund>;
+    /** Get refund status for a purchase using either operator auth or a buyer token. */
+    getByPurchase(purchaseId: string, options?: {
+        buyerToken?: string;
+    }): Promise<Refund>;
     /** List refunds. Requires apiSecret. */
     list(filters?: RefundFilters): Promise<Refund[]>;
 }
@@ -230,4 +251,4 @@ declare const BASE_URL = "https://api.agentmall.sh";
 declare const SERVICE_FEE_CENTS = 150;
 declare const SUPPORTED_RETAILERS: readonly ["amazon.com", "walmart.com", "target.com", "bestbuy.com", "homedepot.com", "ebay.com", "lowes.com", "wayfair.com", "acehardware.com", "1800flowers.com", "pokemoncenter.com"];
 
-export { AgentMall, type AgentMallConfig, AgentMallError, BASE_URL, ConflictError, type CreatePurchaseRequest, type CreatePurchaseResponse, type DeliveryAddress, type Payment, type PaymentFilters, PaymentRequiredError, type ProductLookup, type ProductVariant, type Purchase, type PurchaseFilters, type PurchaseItem, type PurchaseItemInput, type PurchaseLifecycleStatus, RateLimitError, type Refund, type RefundFilters, SERVICE_FEE_CENTS, SUPPORTED_RETAILERS, ValidationError, type VariantSelection, purchase };
+export { AgentMall, type AgentMallConfig, AgentMallError, BASE_URL, ConflictError, type CreatePurchaseRequest, type CreatePurchaseResponse, type DeliveryAddress, type Payment, type PaymentFilters, PaymentRequiredError, type ProductLookup, type ProductVariant, type Purchase, type PurchaseFilters, type PurchaseItem, type PurchaseItemInput, type PurchaseLifecycleStatus, type PurchaseStatusChallenge, RateLimitError, type Refund, type RefundFilters, type RefundStatusChallenge, SERVICE_FEE_CENTS, SUPPORTED_RETAILERS, ValidationError, type VariantSelection, type WalletAccount, purchase };

package/dist/index.d.ts

@@ -1,11 +1,17 @@
 type AgentMallConfig = {
     /** API base URL. Defaults to https://api.agentmall.sh */
     baseUrl?: string;
-    /** Operator API secret for read endpoints (Bearer auth). */
+    /** Operator API secret for admin read endpoints (Bearer auth). */
     apiSecret?: string;
     /** Custom fetch implementation (e.g. mppx-wrapped fetch for automatic 402 handling). */
     fetch?: typeof globalThis.fetch;
 };
+type WalletAccount = {
+    address: string;
+    signMessage(args: {
+        message: string;
+    }): Promise<string>;
+};
 type ProductVariant = {
     label?: string;
     value: string;
@@ -25,7 +31,7 @@ type ProductLookup = {
     availability: string;
     imageUrl?: string;
     retailer: string;
-    /** Suggested max_budget in cents (list price + 15% buffer). */
+    /** Suggested max_budget in cents (list price + a buffer, with a minimum $8 buffer). */
     suggestedMaxBudget: number;
     variants?: ProductVariant[];
     /** True if served from cache. Price may not reflect current listing. */
@@ -64,7 +70,14 @@ type CreatePurchaseResponse = {
     id: string;
     status: PurchaseLifecycleStatus;
     deduplicated?: boolean;
+    buyerToken?: string;
+};
+type PurchaseStatusChallenge = {
+    challenge: string;
+    message: string;
+    expiresAt: number;
 };
+type RefundStatusChallenge = PurchaseStatusChallenge;
 type PurchaseItem = {
     productRef: string;
     quantity: number;
@@ -138,6 +151,8 @@ declare class AgentMall {
     refunds: AgentMallRefunds;
     constructor(config?: AgentMallConfig);
     /** @internal */
+    hasApiSecret(): boolean;
+    /** @internal */
     request<T>(method: string, path: string, options?: {
         body?: unknown;
         auth?: boolean;
@@ -159,8 +174,10 @@ declare class AgentMallPurchases {
      * Use mppx-wrapped fetch to handle payment automatically, or catch PaymentRequiredError.
      */
     create(body: CreatePurchaseRequest): Promise<CreatePurchaseResponse>;
-    /** Get a single purchase by ID. Requires apiSecret. */
-    get(id: string): Promise<Purchase>;
+    /** Get a single purchase by ID using either operator auth or a buyer token. */
+    get(id: string, options?: {
+        buyerToken?: string;
+    }): Promise<Purchase>;
     /** List purchases. Requires apiSecret. */
     list(filters?: PurchaseFilters): Promise<Purchase[]>;
 }
@@ -177,6 +194,10 @@ declare class AgentMallRefunds {
     constructor(client: AgentMall);
     /** Get a single refund by public ID. Requires apiSecret. */
     get(id: string): Promise<Refund>;
+    /** Get refund status for a purchase using either operator auth or a buyer token. */
+    getByPurchase(purchaseId: string, options?: {
+        buyerToken?: string;
+    }): Promise<Refund>;
     /** List refunds. Requires apiSecret. */
     list(filters?: RefundFilters): Promise<Refund[]>;
 }
@@ -230,4 +251,4 @@ declare const BASE_URL = "https://api.agentmall.sh";
 declare const SERVICE_FEE_CENTS = 150;
 declare const SUPPORTED_RETAILERS: readonly ["amazon.com", "walmart.com", "target.com", "bestbuy.com", "homedepot.com", "ebay.com", "lowes.com", "wayfair.com", "acehardware.com", "1800flowers.com", "pokemoncenter.com"];
 
-export { AgentMall, type AgentMallConfig, AgentMallError, BASE_URL, ConflictError, type CreatePurchaseRequest, type CreatePurchaseResponse, type DeliveryAddress, type Payment, type PaymentFilters, PaymentRequiredError, type ProductLookup, type ProductVariant, type Purchase, type PurchaseFilters, type PurchaseItem, type PurchaseItemInput, type PurchaseLifecycleStatus, RateLimitError, type Refund, type RefundFilters, SERVICE_FEE_CENTS, SUPPORTED_RETAILERS, ValidationError, type VariantSelection, purchase };
+export { AgentMall, type AgentMallConfig, AgentMallError, BASE_URL, ConflictError, type CreatePurchaseRequest, type CreatePurchaseResponse, type DeliveryAddress, type Payment, type PaymentFilters, PaymentRequiredError, type ProductLookup, type ProductVariant, type Purchase, type PurchaseFilters, type PurchaseItem, type PurchaseItemInput, type PurchaseLifecycleStatus, type PurchaseStatusChallenge, RateLimitError, type Refund, type RefundFilters, type RefundStatusChallenge, SERVICE_FEE_CENTS, SUPPORTED_RETAILERS, ValidationError, type VariantSelection, type WalletAccount, purchase };

package/dist/index.js

@@ -78,6 +78,10 @@ var AgentMall = class {
     this.refunds = new AgentMallRefunds(this);
   }
   /** @internal */
+  hasApiSecret() {
+    return Boolean(this.apiSecret);
+  }
+  /** @internal */
   async request(method, path, options) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (options?.params) {
@@ -157,8 +161,19 @@ var AgentMallPurchases = class {
       }
     });
   }
-  /** Get a single purchase by ID. Requires apiSecret. */
-  async get(id) {
+  /** Get a single purchase by ID using either operator auth or a buyer token. */
+  async get(id, options) {
+    if (options?.buyerToken) {
+      return this.client.request("POST", "/api/purchases/status", {
+        body: {
+          id,
+          buyer_token: options.buyerToken
+        }
+      });
+    }
+    if (!this.client.hasApiSecret()) {
+      throw new Error("buyerToken or apiSecret is required for this endpoint");
+    }
     return this.client.request("GET", "/api/purchases", {
       auth: true,
       params: { id }
@@ -206,6 +221,33 @@ var AgentMallRefunds = class {
       params: { id }
     });
   }
+  /** Get refund status for a purchase using either operator auth or a buyer token. */
+  async getByPurchase(purchaseId, options) {
+    if (options?.buyerToken) {
+      return this.client.request("POST", "/api/refunds/status", {
+        body: {
+          purchase_id: purchaseId,
+          buyer_token: options.buyerToken
+        }
+      });
+    }
+    if (!this.client.hasApiSecret()) {
+      throw new Error("buyerToken or apiSecret is required for this endpoint");
+    }
+    const result = await this.client.request(
+      "GET",
+      "/api/refunds",
+      {
+        auth: true,
+        params: { purchase_id: purchaseId }
+      }
+    );
+    const refund = result.refunds[0];
+    if (!refund) {
+      throw new AgentMallError(404, { error: "Not found" });
+    }
+    return refund;
+  }
   /** List refunds. Requires apiSecret. */
   async list(filters) {
     const result = await this.client.request(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentmall",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "SDK and CLI for the AgentMall API — let AI agents buy physical products from US retailers",
   "type": "module",
   "main": "./dist/index.js",