agentmall 0.0.1 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,233 @@
+type AgentMallConfig = {
+    /** API base URL. Defaults to https://api.agentmall.sh */
+    baseUrl?: string;
+    /** Operator API secret for read endpoints (Bearer auth). */
+    apiSecret?: string;
+    /** Custom fetch implementation (e.g. mppx-wrapped fetch for automatic 402 handling). */
+    fetch?: typeof globalThis.fetch;
+};
+type ProductVariant = {
+    label?: string;
+    value: string;
+    /** Price in dollars. */
+    price: number;
+    url?: string;
+};
+type ProductLookup = {
+    title: string;
+    /** Current/sale price in cents. */
+    price: number;
+    /** Original list price in cents (before discount). */
+    listPrice?: number;
+    /** Discount percentage (e.g. 13 for -13% off). */
+    discountPercent?: number;
+    currency: string;
+    availability: string;
+    imageUrl?: string;
+    retailer: string;
+    /** Suggested max_budget in cents (list price + 15% buffer). */
+    suggestedMaxBudget: number;
+    variants?: ProductVariant[];
+    /** True if served from cache. Price may not reflect current listing. */
+    cached?: boolean;
+};
+type VariantSelection = {
+    label: string;
+    value: string;
+};
+type PurchaseItemInput = {
+    product_url: string;
+    quantity?: number;
+    variant?: VariantSelection[];
+};
+type DeliveryAddress = {
+    first_name: string;
+    last_name: string;
+    address_line1: string;
+    address_line2?: string;
+    city: string;
+    state?: string;
+    postal_code: string;
+    phone_number: string;
+    country: string;
+};
+type CreatePurchaseRequest = {
+    items: PurchaseItemInput[];
+    delivery_address: DeliveryAddress;
+    max_budget: number;
+    buyer_email: string;
+    idempotency_key?: string;
+    metadata?: unknown;
+};
+type PurchaseLifecycleStatus = "payment_received" | "submitted" | "pending" | "completed" | "failed";
+type CreatePurchaseResponse = {
+    id: string;
+    status: PurchaseLifecycleStatus;
+    deduplicated?: boolean;
+};
+type PurchaseItem = {
+    productRef: string;
+    quantity: number;
+    title?: string;
+    price?: number;
+    variant?: VariantSelection[];
+};
+type Purchase = {
+    id: string;
+    status: PurchaseLifecycleStatus;
+    items: PurchaseItem[];
+    deliveryMethod?: string;
+    maxBudget: number;
+    finalTotal?: number;
+    merchantReferences?: string[];
+    failureReason?: string;
+    paymentMethod?: string;
+    metadata?: unknown;
+    createdAt: number;
+    updatedAt: number;
+};
+type PurchaseFilters = {
+    status?: string;
+    lifecycle_status?: PurchaseLifecycleStatus;
+};
+type Payment = {
+    id: string;
+    purchaseId?: string;
+    idempotencyKey?: string;
+    amountCents: number;
+    currency: string;
+    network: string;
+    chainId?: string;
+    status: string;
+    paymentMethod: string;
+    paymentRef?: string;
+    payerAddress?: string;
+    receiptMethod?: string;
+    receiptStatus?: string;
+    receiptTimestamp?: string;
+    createdAt: number;
+    updatedAt: number;
+};
+type PaymentFilters = {
+    purchase_id?: string;
+    status?: string;
+};
+type Refund = {
+    id: string;
+    purchaseId: string;
+    payerAddress: string;
+    amountCents: number;
+    reason: string;
+    status: string;
+    txHash?: string;
+    createdAt: number;
+    processedAt?: number;
+};
+type RefundFilters = {
+    purchase_id?: string;
+    status?: string;
+};
+
+declare class AgentMall {
+    private baseUrl;
+    private apiSecret?;
+    private _fetch;
+    products: AgentMallProducts;
+    purchases: AgentMallPurchases;
+    payments: AgentMallPayments;
+    refunds: AgentMallRefunds;
+    constructor(config?: AgentMallConfig);
+    /** @internal */
+    request<T>(method: string, path: string, options?: {
+        body?: unknown;
+        auth?: boolean;
+        params?: Record<string, string | undefined>;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+declare class AgentMallProducts {
+    private client;
+    constructor(client: AgentMall);
+    /** Look up product info by URL. Returns price, availability, variants, and suggested max_budget. */
+    lookup(url: string): Promise<ProductLookup>;
+}
+declare class AgentMallPurchases {
+    private client;
+    constructor(client: AgentMall);
+    /**
+     * Create a purchase. The first call returns a 402 MPP payment challenge.
+     * 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>;
+    /** List purchases. Requires apiSecret. */
+    list(filters?: PurchaseFilters): Promise<Purchase[]>;
+}
+declare class AgentMallPayments {
+    private client;
+    constructor(client: AgentMall);
+    /** Get a single payment by ID. Requires apiSecret. */
+    get(id: string): Promise<Payment>;
+    /** List payments. Requires apiSecret. */
+    list(filters?: PaymentFilters): Promise<Payment[]>;
+}
+declare class AgentMallRefunds {
+    private client;
+    constructor(client: AgentMall);
+    /** Get a single refund by public ID. Requires apiSecret. */
+    get(id: string): Promise<Refund>;
+    /** List refunds. Requires apiSecret. */
+    list(filters?: RefundFilters): Promise<Refund[]>;
+}
+
+type PurchaseConfig = CreatePurchaseRequest & {
+    /** viem Account for MPP payment (from privateKeyToAccount or mppx resolveAccount). */
+    account: unknown;
+    /** API base URL. Defaults to https://api.agentmall.sh */
+    baseUrl?: string;
+};
+/**
+ * High-level purchase helper that handles the full 402→pay→retry flow.
+ * Requires mppx to be installed.
+ *
+ * ```ts
+ * import { purchase } from 'agentmall'
+ * import { privateKeyToAccount } from 'viem/accounts'
+ *
+ * const account = privateKeyToAccount('0x...')
+ * const order = await purchase({
+ *   account,
+ *   items: [{ product_url: 'https://amazon.com/dp/...', quantity: 1 }],
+ *   delivery_address: { ... },
+ *   max_budget: 9085,
+ * })
+ * ```
+ */
+declare function purchase(config: PurchaseConfig): Promise<CreatePurchaseResponse>;
+
+declare class AgentMallError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown);
+}
+declare class RateLimitError extends AgentMallError {
+    retryAfterMs: number;
+    constructor(body: unknown, retryAfterMs: number);
+}
+declare class PaymentRequiredError extends AgentMallError {
+    headers: Headers;
+    constructor(body: unknown, headers: Headers);
+}
+declare class ValidationError extends AgentMallError {
+    constructor(body: unknown);
+}
+declare class ConflictError extends AgentMallError {
+    constructor(body: unknown);
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,254 @@
+// src/constants.ts
+var BASE_URL = "https://api.agentmall.sh";
+var SERVICE_FEE_CENTS = 150;
+var SUPPORTED_RETAILERS = [
+  "amazon.com",
+  "walmart.com",
+  "target.com",
+  "bestbuy.com",
+  "homedepot.com",
+  "ebay.com",
+  "lowes.com",
+  "wayfair.com",
+  "acehardware.com",
+  "1800flowers.com",
+  "pokemoncenter.com"
+];
+
+// src/errors.ts
+var AgentMallError = class extends Error {
+  status;
+  body;
+  constructor(status, body) {
+    const message = typeof body === "object" && body !== null && "error" in body ? body.error : `Request failed with status ${status}`;
+    super(message);
+    this.name = "AgentMallError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var RateLimitError = class extends AgentMallError {
+  retryAfterMs;
+  constructor(body, retryAfterMs) {
+    super(429, body);
+    this.name = "RateLimitError";
+    this.retryAfterMs = retryAfterMs;
+  }
+};
+var PaymentRequiredError = class extends AgentMallError {
+  headers;
+  constructor(body, headers) {
+    super(402, body);
+    this.name = "PaymentRequiredError";
+    this.headers = headers;
+  }
+};
+var ValidationError = class extends AgentMallError {
+  constructor(body) {
+    super(400, body);
+    this.name = "ValidationError";
+  }
+};
+var ConflictError = class extends AgentMallError {
+  constructor(body) {
+    super(409, body);
+    this.name = "ConflictError";
+  }
+};
+
+// src/client.ts
+function createIdempotencyKey() {
+  return globalThis.crypto?.randomUUID?.() ?? `agentmall_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+var AgentMall = class {
+  baseUrl;
+  apiSecret;
+  _fetch;
+  products;
+  purchases;
+  payments;
+  refunds;
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl ?? BASE_URL).replace(/\/$/, "");
+    this.apiSecret = config.apiSecret;
+    this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    this.products = new AgentMallProducts(this);
+    this.purchases = new AgentMallPurchases(this);
+    this.payments = new AgentMallPayments(this);
+    this.refunds = new AgentMallRefunds(this);
+  }
+  /** @internal */
+  async request(method, path, options) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (options?.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value !== void 0) url.searchParams.set(key, value);
+      }
+    }
+    const headers = { ...options?.headers ?? {} };
+    if (options?.auth) {
+      if (!this.apiSecret) {
+        throw new Error("apiSecret is required for this endpoint");
+      }
+      headers["Authorization"] = `Bearer ${this.apiSecret}`;
+    }
+    if (options?.body) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await this._fetch(url.toString(), {
+      method,
+      headers,
+      body: options?.body ? JSON.stringify(options.body) : void 0
+    });
+    if (!response.ok) {
+      let body;
+      try {
+        body = await response.json();
+      } catch {
+        body = await response.text().catch(() => null);
+      }
+      if (response.status === 429) {
+        const retryAfter = response.headers.get("Retry-After");
+        const retryMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : 6e4;
+        throw new RateLimitError(body, retryMs);
+      }
+      if (response.status === 402) {
+        throw new PaymentRequiredError(body, response.headers);
+      }
+      if (response.status === 400) {
+        throw new ValidationError(body);
+      }
+      if (response.status === 409) {
+        throw new ConflictError(body);
+      }
+      throw new AgentMallError(response.status, body);
+    }
+    return await response.json();
+  }
+};
+var AgentMallProducts = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Look up product info by URL. Returns price, availability, variants, and suggested max_budget. */
+  async lookup(url) {
+    return this.client.request("GET", "/api/products", {
+      params: { url }
+    });
+  }
+};
+var AgentMallPurchases = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a purchase. The first call returns a 402 MPP payment challenge.
+   * Use mppx-wrapped fetch to handle payment automatically, or catch PaymentRequiredError.
+   */
+  async create(body) {
+    const idempotencyKey = body.idempotency_key ?? createIdempotencyKey();
+    return this.client.request("POST", "/api/purchases", {
+      body: {
+        ...body,
+        idempotency_key: idempotencyKey
+      },
+      headers: {
+        "X-Idempotency-Key": idempotencyKey
+      }
+    });
+  }
+  /** Get a single purchase by ID. Requires apiSecret. */
+  async get(id) {
+    return this.client.request("GET", "/api/purchases", {
+      auth: true,
+      params: { id }
+    });
+  }
+  /** List purchases. Requires apiSecret. */
+  async list(filters) {
+    const result = await this.client.request(
+      "GET",
+      "/api/purchases",
+      { auth: true, params: filters }
+    );
+    return result.purchases;
+  }
+};
+var AgentMallPayments = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get a single payment by ID. Requires apiSecret. */
+  async get(id) {
+    return this.client.request("GET", "/api/payments", {
+      auth: true,
+      params: { id }
+    });
+  }
+  /** List payments. Requires apiSecret. */
+  async list(filters) {
+    const result = await this.client.request(
+      "GET",
+      "/api/payments",
+      { auth: true, params: filters }
+    );
+    return result.payments;
+  }
+};
+var AgentMallRefunds = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get a single refund by public ID. Requires apiSecret. */
+  async get(id) {
+    return this.client.request("GET", "/api/refunds", {
+      auth: true,
+      params: { id }
+    });
+  }
+  /** List refunds. Requires apiSecret. */
+  async list(filters) {
+    const result = await this.client.request(
+      "GET",
+      "/api/refunds",
+      { auth: true, params: filters }
+    );
+    return result.refunds;
+  }
+};
+
+// 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);
+}
+export {
+  AgentMall,
+  AgentMallError,
+  BASE_URL,
+  ConflictError,
+  PaymentRequiredError,
+  RateLimitError,
+  SERVICE_FEE_CENTS,
+  SUPPORTED_RETAILERS,
+  ValidationError,
+  purchase
+};

package/package.json

@@ -1,17 +1,45 @@
 {
   "name": "agentmall",
-  "version": "0.0.1",
-  "description": "Universal checkout for AI agents. Buy any item with a URL, pay with stablecoins via MPP or x402.",
-  "keywords": ["ai", "agents", "checkout", "mpp", "x402", "stablecoins", "ecommerce"],
-  "author": "signetsai",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/signetsai/agentmall"
+  "version": "0.1.1",
+  "description": "SDK and CLI for the AgentMall API — let AI agents buy physical products from US retailers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
   },
-  "homepage": "https://agentmall.com",
   "bin": {
-    "agentmall": "./bin/cli.js"
+    "agentmall": "dist/cli.js"
   },
-  "main": "index.js"
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "mppx": "^0.4.7",
+    "viem": "^2.47.5",
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5"
+  },
+  "keywords": [
+    "agentmall",
+    "ai",
+    "agent",
+    "ecommerce",
+    "mpp",
+    "checkout"
+  ],
+  "license": "MIT"
 }

package/bin/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("agentmall v0.0.1 — coming soon")

package/index.js

@@ -1 +0,0 @@
-module.exports = {}