@agentspend/sdk 0.2.0 → 0.3.2

package/README.md

@@ -0,0 +1,86 @@
+# @agentspend/sdk
+
+SDK for services to accept AI agent payments — cards (Stripe) and crypto (x402/USDC on Base).
+
+## Install
+
+```bash
+npm install @agentspend/sdk
+```
+
+## Paywall middleware (Hono)
+
+Add a paywall to any endpoint. Accepts both card and crypto payments automatically.
+
+```ts
+import { createAgentSpend, getPaymentContext } from "@agentspend/sdk";
+
+const spend = createAgentSpend({
+  serviceApiKey: process.env.AGENTSPEND_SERVICE_API_KEY,
+  crypto: {
+    receiverAddress: "0x...", // your USDC address on Base
+  },
+});
+
+app.post("/api/generate", spend.paywall({ amount: 100 }), async (c) => {
+  const payment = getPaymentContext(c);
+  // payment.method === "card" | "crypto"
+  // payment.amount_cents === 100
+  return c.json({ result: "..." });
+});
+```
+
+### Dynamic pricing
+
+```ts
+// Read amount from request body field
+spend.paywall({ amount: "amount_cents" });
+
+// Custom pricing function
+spend.paywall({ amount: (body) => calculatePrice(body) });
+```
+
+## Direct charge (card only)
+
+```ts
+const result = await spend.charge("card_abc123", {
+  amount_cents: 500,
+  description: "API call",
+});
+```
+
+## How agents pay
+
+**Card:** Agent sends `x-card-id: card_xxx` header or `card_id` in the request body.
+
+**Crypto:** Agent sends `x-payment` header with a signed x402 payment payload.
+
+If neither is provided, the service returns `402 Payment Required` with x402 payment requirements.
+
+## Configuration
+
+```ts
+const spend = createAgentSpend({
+  // Stripe card payments (get key from service onboarding)
+  serviceApiKey: "sk_...",
+
+  // Crypto payments (optional)
+  crypto: {
+    receiverAddress: "0x...",       // static payTo address
+    network: "eip155:8453",         // default: Base
+    facilitatorUrl: "https://...",  // default: x402.org
+  },
+
+  // Override platform API URL (optional)
+  platformApiBaseUrl: "https://api.agentspend.co",
+});
+```
+
+At least one of `serviceApiKey` or `crypto` must be provided.
+
+## Environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `AGENTSPEND_API_URL` | Platform API base URL (default: `https://api.agentspend.co`) |
+| `AGENTSPEND_SERVICE_API_KEY` | Service API key (from service onboarding) |

package/dist/index.d.ts

@@ -1,5 +1,35 @@
-import type { ChargeResponse, PaywallPaymentContext } from "@agentspend/types";
-export type { ChargeRequest, ChargeResponse, ErrorResponse, PaymentMethod, PaywallPaymentContext } from "@agentspend/types";
+export interface ChargeRequest {
+    card_id: string;
+    amount_cents: number;
+    currency?: string;
+    description?: string;
+    metadata?: Record<string, string>;
+    idempotency_key?: string;
+}
+export interface ChargeResponse {
+    charged: true;
+    card_id: string;
+    amount_cents: number;
+    currency: string;
+    remaining_limit_cents: number;
+    stripe_payment_intent_id: string;
+    stripe_charge_id: string;
+    charge_attempt_id: string;
+}
+export interface ErrorResponse {
+    error: string;
+}
+export type PaymentMethod = "card" | "crypto";
+export interface PaywallPaymentContext {
+    method: PaymentMethod;
+    amount_cents: number;
+    currency: string;
+    card_id?: string;
+    remaining_limit_cents?: number;
+    transaction_hash?: string;
+    payer_address?: string;
+    network?: string;
+}
 export interface AgentSpendOptions {
     /**
      * Base URL for the AgentSpend Platform API.
@@ -40,21 +70,26 @@ export interface HonoContextLike {
         url: string;
         method: string;
     };
-    json(body: unknown, status?: number): unknown;
+    json(body: unknown, status?: number): Response;
     header(name: string, value: string): void;
     set(key: string, value: unknown): void;
     get(key: string): unknown;
 }
 export interface PaywallOptions {
+    /**
+     * Amount in cents.
+     * - number: fixed price (e.g. 500 = $5.00)
+     * - string: body field name to read amount from (e.g. "amount_cents")
+     * - function: custom dynamic pricing (body: unknown) => number
+     */
+    amount: number | string | ((body: unknown) => number);
     currency?: string;
     description?: string;
     metadata?: (body: unknown) => Record<string, unknown>;
-    /** Dynamic pricing: derive amount from the parsed request body. */
-    amountFromRequest?: (body: unknown) => number;
 }
 export declare function getPaymentContext(c: HonoContextLike): PaywallPaymentContext | null;
 export interface AgentSpend {
-    charge(walletId: string, opts: ChargeOptions): Promise<ChargeResponse>;
-    paywall(amountCents: number, opts?: PaywallOptions): (c: HonoContextLike, next: () => Promise<void>) => Promise<unknown>;
+    charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+    paywall(opts: PaywallOptions): (c: HonoContextLike, next: () => Promise<void>) => Promise<Response | void>;
 }
 export declare function createAgentSpend(options: AgentSpendOptions): AgentSpend;

package/dist/index.js

@@ -1,4 +1,7 @@
 "use strict";
+// ---------------------------------------------------------------------------
+// Types (inlined from @agentspend/types to avoid cross-repo publish)
+// ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentSpendChargeError = void 0;
 exports.getPaymentContext = getPaymentContext;
@@ -54,19 +57,19 @@ function createAgentSpend(options) {
     // -------------------------------------------------------------------
     // charge() — card-only, unchanged
     // -------------------------------------------------------------------
-    async function charge(walletIdInput, opts) {
+    async function charge(cardIdInput, opts) {
         if (!options.serviceApiKey) {
             throw new AgentSpendChargeError("charge() requires serviceApiKey", 500);
         }
-        const walletId = toWalletId(walletIdInput);
-        if (!walletId) {
-            throw new AgentSpendChargeError("wallet_id must start with wal_", 400);
+        const cardId = toCardId(cardIdInput);
+        if (!cardId) {
+            throw new AgentSpendChargeError("card_id must start with card_", 400);
         }
         if (!Number.isInteger(opts.amount_cents) || opts.amount_cents <= 0) {
             throw new AgentSpendChargeError("amount_cents must be a positive integer", 400);
         }
         const payload = {
-            wallet_id: walletId,
+            card_id: cardId,
             amount_cents: opts.amount_cents,
             currency: opts.currency ?? "usd",
             ...(opts.description ? { description: opts.description } : {}),
@@ -90,41 +93,49 @@ function createAgentSpend(options) {
     // -------------------------------------------------------------------
     // paywall() — unified card + crypto middleware
     // -------------------------------------------------------------------
-    function paywall(amountCents, opts) {
-        // Allow amountCents === 0 when amountFromRequest is provided (dynamic pricing)
-        if (!opts?.amountFromRequest) {
-            if (!Number.isInteger(amountCents) || amountCents <= 0) {
-                throw new AgentSpendChargeError("amountCents must be a positive integer", 500);
+    function paywall(opts) {
+        const { amount } = opts;
+        // Validate fixed-price amount at creation time
+        if (typeof amount === "number") {
+            if (!Number.isInteger(amount) || amount <= 0) {
+                throw new AgentSpendChargeError("amount must be a positive integer", 500);
             }
         }
         return async function paywallMiddleware(c, next) {
             // Step 1: Parse body once (Decision 11)
             const body = await c.req.json().catch(() => ({}));
             // Step 2: Determine effective amount
-            let effectiveAmount = amountCents;
-            if (opts?.amountFromRequest) {
-                effectiveAmount = opts.amountFromRequest(body);
-                if (!Number.isInteger(effectiveAmount) || effectiveAmount <= 0) {
-                    return c.json({ error: "Could not determine payment amount from request" }, 400);
-                }
+            let effectiveAmount;
+            if (typeof amount === "number") {
+                effectiveAmount = amount;
+            }
+            else if (typeof amount === "string") {
+                const raw = body?.[amount];
+                effectiveAmount = typeof raw === "number" ? raw : 0;
+            }
+            else {
+                effectiveAmount = amount(body);
+            }
+            if (!Number.isInteger(effectiveAmount) || effectiveAmount <= 0) {
+                return c.json({ error: "Could not determine payment amount from request" }, 400);
             }
-            const currency = opts?.currency ?? "usd";
+            const currency = opts.currency ?? "usd";
             // Step 3: Check for x-payment header → crypto payment
             const paymentHeader = c.req.header("x-payment");
             if (paymentHeader) {
                 return handleCryptoPayment(c, next, paymentHeader, effectiveAmount, currency, body, opts);
             }
-            // Step 4: Check for x-wallet-id header or body.wallet_id → card payment
-            const walletIdFromHeader = c.req.header("x-wallet-id");
-            let walletId = walletIdFromHeader ? toWalletId(walletIdFromHeader) : null;
-            if (!walletId) {
-                const bodyWalletId = typeof body?.wallet_id === "string"
-                    ? body.wallet_id
+            // Step 4: Check for x-card-id header or body.card_id → card payment
+            const cardIdFromHeader = c.req.header("x-card-id");
+            let cardId = cardIdFromHeader ? toCardId(cardIdFromHeader) : null;
+            if (!cardId) {
+                const bodyCardId = typeof body?.card_id === "string"
+                    ? body.card_id
                     : null;
-                walletId = toWalletId(bodyWalletId);
+                cardId = toCardId(bodyCardId);
             }
-            if (walletId) {
-                return handleCardPayment(c, next, walletId, effectiveAmount, currency, body, opts);
+            if (cardId) {
+                return handleCardPayment(c, next, cardId, effectiveAmount, currency, body, opts);
             }
             // Step 5: Neither → return 402 with Payment-Required header (Decision 8)
             return return402Response(c, effectiveAmount, currency);
@@ -133,23 +144,23 @@ function createAgentSpend(options) {
     // -------------------------------------------------------------------
     // handleCardPayment — existing charge() flow
     // -------------------------------------------------------------------
-    async function handleCardPayment(c, next, walletId, amountCents, currency, body, opts) {
+    async function handleCardPayment(c, next, cardId, amountCents, currency, body, opts) {
         if (!options.serviceApiKey) {
             return c.json({ error: "Card payments require serviceApiKey" }, 500);
         }
         try {
-            const chargeResult = await charge(walletId, {
+            const chargeResult = await charge(cardId, {
                 amount_cents: amountCents,
                 currency,
-                description: opts?.description,
-                metadata: opts?.metadata ? toStringMetadata(opts.metadata(body)) : undefined,
+                description: opts.description,
+                metadata: opts.metadata ? toStringMetadata(opts.metadata(body)) : undefined,
                 idempotency_key: c.req.header("x-request-id") ?? c.req.header("idempotency-key") ?? undefined
             });
             const paymentContext = {
                 method: "card",
                 amount_cents: amountCents,
                 currency,
-                wallet_id: walletId,
+                card_id: cardId,
                 remaining_limit_cents: chargeResult.remaining_limit_cents
             };
             c.set(PAYMENT_CONTEXT_KEY, paymentContext);
@@ -258,7 +269,7 @@ function createAgentSpend(options) {
         }
     }
     // -------------------------------------------------------------------
-    // resolvePayToAddress — static wallet or Stripe Machine Payments
+    // resolvePayToAddress — static address or Stripe Machine Payments
     // -------------------------------------------------------------------
     async function resolvePayToAddress() {
         // Static address for crypto-only services
@@ -297,12 +308,12 @@ function createAgentSpend(options) {
 // ---------------------------------------------------------------------------
 // Helpers (unchanged from original)
 // ---------------------------------------------------------------------------
-function toWalletId(input) {
+function toCardId(input) {
     if (typeof input !== "string") {
         return null;
     }
     const trimmed = input.trim();
-    if (!trimmed.startsWith("wal_")) {
+    if (!trimmed.startsWith("card_")) {
         return null;
     }
     return trimmed;

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@agentspend/sdk",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@agentspend/types": "^0.2.0",
     "@x402/core": "^2.3.1"
   },
   "scripts": {

package/src/index.ts

@@ -1,18 +1,43 @@
-import type {
-  ChargeRequest,
-  ChargeResponse,
-  ErrorResponse,
-  PaymentMethod,
-  PaywallPaymentContext
-} from "@agentspend/types";
-
-export type {
-  ChargeRequest,
-  ChargeResponse,
-  ErrorResponse,
-  PaymentMethod,
-  PaywallPaymentContext
-} from "@agentspend/types";
+// ---------------------------------------------------------------------------
+// Types (inlined from @agentspend/types to avoid cross-repo publish)
+// ---------------------------------------------------------------------------
+
+export interface ChargeRequest {
+  card_id: string;
+  amount_cents: number;
+  currency?: string;
+  description?: string;
+  metadata?: Record<string, string>;
+  idempotency_key?: string;
+}
+
+export interface ChargeResponse {
+  charged: true;
+  card_id: string;
+  amount_cents: number;
+  currency: string;
+  remaining_limit_cents: number;
+  stripe_payment_intent_id: string;
+  stripe_charge_id: string;
+  charge_attempt_id: string;
+}
+
+export interface ErrorResponse {
+  error: string;
+}
+
+export type PaymentMethod = "card" | "crypto";
+
+export interface PaywallPaymentContext {
+  method: PaymentMethod;
+  amount_cents: number;
+  currency: string;
+  card_id?: string;
+  remaining_limit_cents?: number;
+  transaction_hash?: string;
+  payer_address?: string;
+  network?: string;
+}
 
 // ---------------------------------------------------------------------------
 // x402 imports – server-side only (HTTP calls to facilitator, no crypto deps)
@@ -82,7 +107,7 @@ export interface HonoContextLike {
     url: string;
     method: string;
   };
-  json(body: unknown, status?: number): unknown;
+  json(body: unknown, status?: number): Response;
   header(name: string, value: string): void;
   set(key: string, value: unknown): void;
   get(key: string): unknown;
@@ -93,11 +118,16 @@ export interface HonoContextLike {
 // ---------------------------------------------------------------------------
 
 export interface PaywallOptions {
+  /**
+   * Amount in cents.
+   * - number: fixed price (e.g. 500 = $5.00)
+   * - string: body field name to read amount from (e.g. "amount_cents")
+   * - function: custom dynamic pricing (body: unknown) => number
+   */
+  amount: number | string | ((body: unknown) => number);
   currency?: string;
   description?: string;
   metadata?: (body: unknown) => Record<string, unknown>;
-  /** Dynamic pricing: derive amount from the parsed request body. */
-  amountFromRequest?: (body: unknown) => number;
 }
 
 // ---------------------------------------------------------------------------
@@ -116,11 +146,8 @@ export function getPaymentContext(c: HonoContextLike): PaywallPaymentContext | n
 // ---------------------------------------------------------------------------
 
 export interface AgentSpend {
-  charge(walletId: string, opts: ChargeOptions): Promise<ChargeResponse>;
-  paywall(
-    amountCents: number,
-    opts?: PaywallOptions
-  ): (c: HonoContextLike, next: () => Promise<void>) => Promise<unknown>;
+  charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+  paywall(opts: PaywallOptions): (c: HonoContextLike, next: () => Promise<void>) => Promise<Response | void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -163,21 +190,21 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
   // charge() — card-only, unchanged
   // -------------------------------------------------------------------
 
-  async function charge(walletIdInput: string, opts: ChargeOptions): Promise<ChargeResponse> {
+  async function charge(cardIdInput: string, opts: ChargeOptions): Promise<ChargeResponse> {
     if (!options.serviceApiKey) {
       throw new AgentSpendChargeError("charge() requires serviceApiKey", 500);
     }
 
-    const walletId = toWalletId(walletIdInput);
-    if (!walletId) {
-      throw new AgentSpendChargeError("wallet_id must start with wal_", 400);
+    const cardId = toCardId(cardIdInput);
+    if (!cardId) {
+      throw new AgentSpendChargeError("card_id must start with card_", 400);
     }
     if (!Number.isInteger(opts.amount_cents) || opts.amount_cents <= 0) {
       throw new AgentSpendChargeError("amount_cents must be a positive integer", 400);
     }
 
     const payload: ChargeRequest = {
-      wallet_id: walletId,
+      card_id: cardId,
       amount_cents: opts.amount_cents,
       currency: opts.currency ?? "usd",
       ...(opts.description ? { description: opts.description } : {}),
@@ -212,31 +239,39 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
   // paywall() — unified card + crypto middleware
   // -------------------------------------------------------------------
 
-  function paywall(amountCents: number, opts?: PaywallOptions) {
-    // Allow amountCents === 0 when amountFromRequest is provided (dynamic pricing)
-    if (!opts?.amountFromRequest) {
-      if (!Number.isInteger(amountCents) || amountCents <= 0) {
-        throw new AgentSpendChargeError("amountCents must be a positive integer", 500);
+  function paywall(opts: PaywallOptions) {
+    const { amount } = opts;
+
+    // Validate fixed-price amount at creation time
+    if (typeof amount === "number") {
+      if (!Number.isInteger(amount) || amount <= 0) {
+        throw new AgentSpendChargeError("amount must be a positive integer", 500);
       }
     }
 
     return async function paywallMiddleware(
       c: HonoContextLike,
       next: () => Promise<void>
-    ): Promise<unknown> {
+    ): Promise<Response | void> {
       // Step 1: Parse body once (Decision 11)
       const body: unknown = await c.req.json().catch(() => ({}));
 
       // Step 2: Determine effective amount
-      let effectiveAmount = amountCents;
-      if (opts?.amountFromRequest) {
-        effectiveAmount = opts.amountFromRequest(body);
-        if (!Number.isInteger(effectiveAmount) || effectiveAmount <= 0) {
-          return c.json({ error: "Could not determine payment amount from request" }, 400);
-        }
+      let effectiveAmount: number;
+      if (typeof amount === "number") {
+        effectiveAmount = amount;
+      } else if (typeof amount === "string") {
+        const raw = (body as Record<string, unknown>)?.[amount];
+        effectiveAmount = typeof raw === "number" ? raw : 0;
+      } else {
+        effectiveAmount = amount(body);
+      }
+
+      if (!Number.isInteger(effectiveAmount) || effectiveAmount <= 0) {
+        return c.json({ error: "Could not determine payment amount from request" }, 400);
       }
 
-      const currency = opts?.currency ?? "usd";
+      const currency = opts.currency ?? "usd";
 
       // Step 3: Check for x-payment header → crypto payment
       const paymentHeader = c.req.header("x-payment");
@@ -244,19 +279,19 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
         return handleCryptoPayment(c, next, paymentHeader, effectiveAmount, currency, body, opts);
       }
 
-      // Step 4: Check for x-wallet-id header or body.wallet_id → card payment
-      const walletIdFromHeader = c.req.header("x-wallet-id");
-      let walletId = walletIdFromHeader ? toWalletId(walletIdFromHeader) : null;
-      if (!walletId) {
-        const bodyWalletId =
-          typeof (body as { wallet_id?: unknown })?.wallet_id === "string"
-            ? (body as { wallet_id: string }).wallet_id
+      // Step 4: Check for x-card-id header or body.card_id → card payment
+      const cardIdFromHeader = c.req.header("x-card-id");
+      let cardId = cardIdFromHeader ? toCardId(cardIdFromHeader) : null;
+      if (!cardId) {
+        const bodyCardId =
+          typeof (body as { card_id?: unknown })?.card_id === "string"
+            ? (body as { card_id: string }).card_id
             : null;
-        walletId = toWalletId(bodyWalletId);
+        cardId = toCardId(bodyCardId);
       }
 
-      if (walletId) {
-        return handleCardPayment(c, next, walletId, effectiveAmount, currency, body, opts);
+      if (cardId) {
+        return handleCardPayment(c, next, cardId, effectiveAmount, currency, body, opts);
       }
 
       // Step 5: Neither → return 402 with Payment-Required header (Decision 8)
@@ -271,22 +306,22 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
   async function handleCardPayment(
     c: HonoContextLike,
     next: () => Promise<void>,
-    walletId: string,
+    cardId: string,
     amountCents: number,
     currency: string,
     body: unknown,
-    opts?: PaywallOptions
-  ): Promise<unknown> {
+    opts: PaywallOptions
+  ): Promise<Response | void> {
     if (!options.serviceApiKey) {
       return c.json({ error: "Card payments require serviceApiKey" }, 500);
     }
 
     try {
-      const chargeResult = await charge(walletId, {
+      const chargeResult = await charge(cardId, {
         amount_cents: amountCents,
         currency,
-        description: opts?.description,
-        metadata: opts?.metadata ? toStringMetadata(opts.metadata(body)) : undefined,
+        description: opts.description,
+        metadata: opts.metadata ? toStringMetadata(opts.metadata(body)) : undefined,
         idempotency_key:
           c.req.header("x-request-id") ?? c.req.header("idempotency-key") ?? undefined
       });
@@ -295,7 +330,7 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
         method: "card",
         amount_cents: amountCents,
         currency,
-        wallet_id: walletId,
+        card_id: cardId,
         remaining_limit_cents: chargeResult.remaining_limit_cents
       };
       c.set(PAYMENT_CONTEXT_KEY, paymentContext);
@@ -323,8 +358,8 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
     amountCents: number,
     currency: string,
     _body: unknown,
-    _opts?: PaywallOptions
-  ): Promise<unknown> {
+    _opts: PaywallOptions
+  ): Promise<Response | void> {
     if (!facilitator) {
       return c.json({ error: "Crypto payments not configured" }, 500);
     }
@@ -410,7 +445,7 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
     c: HonoContextLike,
     amountCents: number,
     currency: string
-  ): Promise<unknown> {
+  ): Promise<Response> {
     try {
       const payTo = await resolvePayToAddress();
 
@@ -453,7 +488,7 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
   }
 
   // -------------------------------------------------------------------
-  // resolvePayToAddress — static wallet or Stripe Machine Payments
+  // resolvePayToAddress — static address or Stripe Machine Payments
   // -------------------------------------------------------------------
 
   async function resolvePayToAddress(): Promise<string> {
@@ -504,12 +539,12 @@ export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
 // Helpers (unchanged from original)
 // ---------------------------------------------------------------------------
 
-function toWalletId(input: unknown): string | null {
+function toCardId(input: unknown): string | null {
   if (typeof input !== "string") {
     return null;
   }
   const trimmed = input.trim();
-  if (!trimmed.startsWith("wal_")) {
+  if (!trimmed.startsWith("card_")) {
     return null;
   }
   return trimmed;