@agentspend/sdk 0.3.7 → 0.3.9

package/dist/hono/index.d.ts

@@ -0,0 +1,20 @@
+import type { AgentSpendOptions, ChargeOptions, ChargeResponse, PaywallOptions, PaywallPaymentContext } from "../core/types.js";
+export * from "../core/index.js";
+export interface HonoContextLike {
+    req: {
+        header(name: string): string | undefined;
+        json(): Promise<unknown>;
+        url: string;
+        method: string;
+    };
+    json(body: unknown, status?: number): Response;
+    header(name: string, value: string): void;
+    set(key: string, value: unknown): void;
+    get(key: string): unknown;
+}
+export declare function getPaymentContext(c: HonoContextLike): PaywallPaymentContext | null;
+export interface AgentSpend {
+    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/hono/index.js

@@ -0,0 +1,49 @@
+import { createAgentSpendClient } from "../core/client.js";
+export * from "../core/index.js";
+// ---------------------------------------------------------------------------
+// Payment context helper
+// ---------------------------------------------------------------------------
+const PAYMENT_CONTEXT_KEY = "payment";
+export function getPaymentContext(c) {
+    const ctx = c.get(PAYMENT_CONTEXT_KEY);
+    return ctx ?? null;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createAgentSpend(options) {
+    const client = createAgentSpendClient(options);
+    function paywall(opts) {
+        return async function paywallMiddleware(c, next) {
+            const body = await c.req.json().catch(() => ({}));
+            const request = {
+                url: c.req.url,
+                method: c.req.method,
+                headers: {
+                    "x-card-id": c.req.header("x-card-id"),
+                    "payment-signature": c.req.header("payment-signature"),
+                    "x-payment": c.req.header("x-payment"),
+                    "x-request-id": c.req.header("x-request-id"),
+                    "idempotency-key": c.req.header("idempotency-key"),
+                },
+                body
+            };
+            const result = await client.processPaywall(opts, request);
+            switch (result.outcome) {
+                case "charged":
+                case "crypto_paid":
+                    c.set(PAYMENT_CONTEXT_KEY, result.paymentContext);
+                    await next();
+                    return;
+                case "payment_required":
+                    for (const [key, value] of Object.entries(result.headers)) {
+                        c.header(key, value);
+                    }
+                    return c.json(result.body, result.statusCode);
+                case "error":
+                    return c.json(result.body, result.statusCode);
+            }
+        };
+    }
+    return { charge: client.charge, paywall };
+}

package/dist/next/index.d.ts

@@ -0,0 +1,15 @@
+import type { AgentSpendOptions, ChargeOptions, ChargeResponse, PaywallOptions, PaywallPaymentContext } from "../core/types.js";
+export * from "../core/index.js";
+interface NextRequest {
+    url: string;
+    method: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}
+export interface AgentSpend {
+    charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+    withPaywall(opts: PaywallOptions, handler: (req: NextRequest, paymentContext: PaywallPaymentContext) => Promise<Response>): (req: NextRequest) => Promise<Response>;
+}
+export declare function createAgentSpend(options: AgentSpendOptions): AgentSpend;

package/dist/next/index.js

@@ -0,0 +1,39 @@
+import { createAgentSpendClient } from "../core/client.js";
+export * from "../core/index.js";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createAgentSpend(options) {
+    const client = createAgentSpendClient(options);
+    function withPaywall(opts, handler) {
+        return async function wrappedHandler(req) {
+            const body = await req.json().catch(() => ({}));
+            const request = {
+                url: req.url,
+                method: req.method,
+                headers: {
+                    "x-card-id": req.headers.get("x-card-id") ?? undefined,
+                    "payment-signature": req.headers.get("payment-signature") ?? undefined,
+                    "x-payment": req.headers.get("x-payment") ?? undefined,
+                    "x-request-id": req.headers.get("x-request-id") ?? undefined,
+                    "idempotency-key": req.headers.get("idempotency-key") ?? undefined,
+                },
+                body
+            };
+            const result = await client.processPaywall(opts, request);
+            switch (result.outcome) {
+                case "charged":
+                case "crypto_paid":
+                    return handler(req, result.paymentContext);
+                case "payment_required":
+                    return Response.json(result.body, {
+                        status: result.statusCode,
+                        headers: result.headers
+                    });
+                case "error":
+                    return Response.json(result.body, { status: result.statusCode });
+            }
+        };
+    }
+    return { charge: client.charge, withPaywall };
+}

package/package.json

@@ -1,8 +1,31 @@
 {
   "name": "@agentspend/sdk",
-  "version": "0.3.7",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "0.3.9",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./hono": {
+      "import": "./dist/hono/index.js",
+      "types": "./dist/hono/index.d.ts"
+    },
+    "./express": {
+      "import": "./dist/express/index.js",
+      "types": "./dist/express/index.d.ts"
+    },
+    "./fastify": {
+      "import": "./dist/fastify/index.js",
+      "types": "./dist/fastify/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next/index.js",
+      "types": "./dist/next/index.d.ts"
+    }
+  },
+  "main": "dist/core/index.js",
+  "types": "dist/core/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -10,6 +33,30 @@
     "@x402/core": "^2.3.1",
     "@x402/evm": "^2.3.1"
   },
+  "peerDependencies": {
+    "hono": ">=4",
+    "express": ">=4",
+    "@types/express": ">=4",
+    "fastify": ">=4",
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "@types/express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit"

package/src/core/client.ts

@@ -0,0 +1,433 @@
+import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
+import { registerExactEvmScheme } from "@x402/evm/exact/server";
+import type {
+  PaymentRequirements,
+  PaymentPayload,
+  VerifyResponse,
+  SettleResponse,
+  Network
+} from "@x402/core/types";
+
+import type {
+  AgentSpendOptions,
+  ChargeOptions,
+  ChargeRequest,
+  ChargeResponse,
+  ErrorResponse,
+  PaywallOptions,
+  PaywallPaymentContext,
+  PaywallRequest,
+  PaywallResult
+} from "./types.js";
+import { AgentSpendChargeError } from "./error.js";
+import {
+  toCardId,
+  joinUrl,
+  bestEffortIdempotencyKey,
+  toStringMetadata,
+  resolvePlatformApiBaseUrl,
+  resolveAmount,
+  extractCardId,
+  extractPaymentHeader
+} from "./helpers.js";
+
+// ---------------------------------------------------------------------------
+// Core client interface
+// ---------------------------------------------------------------------------
+
+export interface AgentSpendClient {
+  charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+  processPaywall(opts: PaywallOptions, request: PaywallRequest): Promise<PaywallResult>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createAgentSpendClient(options: AgentSpendOptions): AgentSpendClient {
+  if (!options.serviceApiKey && !options.crypto) {
+    throw new AgentSpendChargeError(
+      "At least one of serviceApiKey or crypto config must be provided",
+      500
+    );
+  }
+
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new AgentSpendChargeError("No fetch implementation available", 500);
+  }
+
+  const platformApiBaseUrl = resolvePlatformApiBaseUrl(options.platformApiBaseUrl);
+
+  // -------------------------------------------------------------------
+  // Lazy service_id fetch + cache
+  // -------------------------------------------------------------------
+  let cachedServiceId: string | null = null;
+
+  async function getServiceId(): Promise<string | null> {
+    if (cachedServiceId) return cachedServiceId;
+    if (!options.serviceApiKey) return null;
+    try {
+      const res = await fetchImpl(joinUrl(platformApiBaseUrl, "/v1/service/me"), {
+        headers: { authorization: `Bearer ${options.serviceApiKey}` }
+      });
+      if (res.ok) {
+        const data = (await res.json()) as { id?: string };
+        cachedServiceId = data.id ?? null;
+      }
+    } catch { /* graceful fallback */ }
+    return cachedServiceId;
+  }
+
+  // -------------------------------------------------------------------
+  // x402 singleton setup
+  // -------------------------------------------------------------------
+  let facilitator: HTTPFacilitatorClient | null = null;
+  let resourceServer: x402ResourceServer | null = null;
+  const cryptoNetwork: Network = (options.crypto?.network ?? "eip155:8453") as Network;
+
+  if (options.crypto || options.serviceApiKey) {
+    const facilitatorUrl =
+      options.crypto?.facilitatorUrl ?? "https://facilitator.openx402.ai";
+    facilitator = new HTTPFacilitatorClient({ url: facilitatorUrl });
+    resourceServer = new x402ResourceServer(facilitator);
+    registerExactEvmScheme(resourceServer);
+  }
+
+  // -------------------------------------------------------------------
+  // charge() — card-only
+  // -------------------------------------------------------------------
+
+  async function charge(cardIdInput: string, opts: ChargeOptions): Promise<ChargeResponse> {
+    if (!options.serviceApiKey) {
+      throw new AgentSpendChargeError("charge() requires serviceApiKey", 500);
+    }
+
+    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 = {
+      card_id: cardId,
+      amount_cents: opts.amount_cents,
+      currency: opts.currency ?? "usd",
+      ...(opts.description ? { description: opts.description } : {}),
+      ...(opts.metadata ? { metadata: opts.metadata } : {}),
+      idempotency_key: opts.idempotency_key ?? bestEffortIdempotencyKey()
+    };
+
+    const response = await fetchImpl(joinUrl(platformApiBaseUrl, "/v1/charge"), {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${options.serviceApiKey}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    });
+
+    const responseBody = (await response.json().catch(() => ({}))) as Partial<ChargeResponse> &
+      Partial<ErrorResponse> &
+      Record<string, unknown>;
+    if (!response.ok) {
+      throw new AgentSpendChargeError(
+        typeof responseBody.error === "string" ? responseBody.error : "AgentSpend charge failed",
+        response.status,
+        responseBody
+      );
+    }
+
+    return responseBody as ChargeResponse;
+  }
+
+  // -------------------------------------------------------------------
+  // resolvePayToAddress
+  // -------------------------------------------------------------------
+
+  async function resolvePayToAddress(): Promise<string> {
+    if (options.crypto?.receiverAddress) {
+      return options.crypto.receiverAddress;
+    }
+
+    if (options.serviceApiKey) {
+      const response = await fetchImpl(
+        joinUrl(platformApiBaseUrl, "/v1/crypto/deposit-address"),
+        {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${options.serviceApiKey}`,
+            "content-type": "application/json"
+          },
+          body: JSON.stringify({ amount_cents: 0, currency: "usd" })
+        }
+      );
+
+      if (!response.ok) {
+        throw new AgentSpendChargeError("Failed to resolve crypto deposit address", 502);
+      }
+
+      const data = (await response.json()) as { deposit_address?: string };
+      if (!data.deposit_address) {
+        throw new AgentSpendChargeError("No deposit address returned", 502);
+      }
+      return data.deposit_address;
+    }
+
+    throw new AgentSpendChargeError("No crypto payTo address available", 500);
+  }
+
+  // -------------------------------------------------------------------
+  // build402Result — x402 Payment-Required format
+  // -------------------------------------------------------------------
+
+  async function build402Result(
+    requestUrl: string,
+    amountCents: number,
+    currency: string
+  ): Promise<PaywallResult> {
+    const serviceId = await getServiceId();
+
+    try {
+      const payTo = await resolvePayToAddress();
+
+      const paymentRequirements: PaymentRequirements = {
+        scheme: "exact",
+        network: cryptoNetwork,
+        amount: String(amountCents),
+        asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
+        payTo,
+        maxTimeoutSeconds: 300,
+        extra: { name: "USD Coin", version: "2" }
+      };
+
+      const paymentRequired = {
+        x402Version: 2,
+        error: "Payment required",
+        resource: {
+          url: requestUrl,
+          description: `Payment of ${amountCents} cents`,
+          mimeType: "application/json"
+        },
+        accepts: [paymentRequirements]
+      };
+
+      const headerValue = Buffer.from(
+        JSON.stringify(paymentRequired)
+      ).toString("base64");
+
+      return {
+        outcome: "payment_required",
+        statusCode: 402,
+        body: {
+          error: "Payment required",
+          amount_cents: amountCents,
+          currency,
+          ...(serviceId ? {
+            agentspend: {
+              service_id: serviceId,
+              amount_cents: amountCents,
+            }
+          } : {})
+        },
+        headers: { "Payment-Required": headerValue }
+      };
+    } catch (error) {
+      console.error(
+        "[agentspend] Failed to resolve crypto payTo address — returning card-only 402:",
+        error instanceof Error ? error.message : error
+      );
+      return {
+        outcome: "payment_required",
+        statusCode: 402,
+        body: {
+          error: "Payment required",
+          amount_cents: amountCents,
+          currency,
+          ...(serviceId ? {
+            agentspend: {
+              service_id: serviceId,
+              amount_cents: amountCents,
+            }
+          } : {})
+        },
+        headers: {}
+      };
+    }
+  }
+
+  // -------------------------------------------------------------------
+  // handleCardPayment
+  // -------------------------------------------------------------------
+
+  async function handleCardPayment(
+    request: PaywallRequest,
+    cardId: string,
+    amountCents: number,
+    currency: string,
+    body: unknown,
+    opts: PaywallOptions
+  ): Promise<PaywallResult> {
+    if (!options.serviceApiKey) {
+      return { outcome: "error", statusCode: 500, body: { error: "Card payments require serviceApiKey" } };
+    }
+
+    try {
+      const chargeResult = await charge(cardId, {
+        amount_cents: amountCents,
+        currency,
+        description: opts.description,
+        metadata: opts.metadata ? toStringMetadata(opts.metadata(body)) : undefined,
+        idempotency_key:
+          request.headers["x-request-id"] ?? request.headers["idempotency-key"] ?? undefined
+      });
+
+      const paymentContext: PaywallPaymentContext = {
+        method: "card",
+        amount_cents: amountCents,
+        currency,
+        card_id: cardId,
+        remaining_limit_cents: chargeResult.remaining_limit_cents
+      };
+      return { outcome: "charged", paymentContext };
+    } catch (error) {
+      if (error instanceof AgentSpendChargeError) {
+        if (error.statusCode === 403) {
+          return build402Result(request.url, amountCents, currency);
+        }
+        if (error.statusCode === 402) {
+          return { outcome: "error", statusCode: 402, body: { error: "Payment required", details: error.details } };
+        }
+        return { outcome: "error", statusCode: error.statusCode, body: { error: error.message, details: error.details } };
+      }
+      return { outcome: "error", statusCode: 500, body: { error: "Unexpected paywall failure" } };
+    }
+  }
+
+  // -------------------------------------------------------------------
+  // handleCryptoPayment
+  // -------------------------------------------------------------------
+
+  async function handleCryptoPayment(
+    paymentHeader: string,
+    amountCents: number,
+    currency: string
+  ): Promise<PaywallResult> {
+    if (!resourceServer) {
+      return { outcome: "error", statusCode: 500, body: { error: "Crypto payments not configured" } };
+    }
+
+    try {
+      let paymentPayload: PaymentPayload;
+      try {
+        paymentPayload = JSON.parse(
+          Buffer.from(paymentHeader, "base64").toString("utf-8")
+        ) as PaymentPayload;
+      } catch {
+        return { outcome: "error", statusCode: 400, body: { error: "Invalid payment payload encoding" } };
+      }
+
+      const acceptedPayTo = (paymentPayload as unknown as { accepted?: { payTo?: string } })
+        .accepted?.payTo;
+      const payTo: string = acceptedPayTo ?? await resolvePayToAddress();
+
+      const paymentRequirements: PaymentRequirements = {
+        scheme: "exact",
+        network: cryptoNetwork,
+        amount: String(amountCents),
+        asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
+        payTo,
+        maxTimeoutSeconds: 300,
+        extra: { name: "USD Coin", version: "2" }
+      };
+
+      const verifyResult: VerifyResponse = await resourceServer!.verifyPayment(
+        paymentPayload,
+        paymentRequirements
+      );
+
+      if (!verifyResult.isValid) {
+        return {
+          outcome: "error",
+          statusCode: 402,
+          body: { error: "Payment verification failed", details: verifyResult.invalidReason }
+        };
+      }
+
+      const settleResult: SettleResponse = await resourceServer!.settlePayment(
+        paymentPayload,
+        paymentRequirements
+      );
+
+      if (!settleResult.success) {
+        return {
+          outcome: "error",
+          statusCode: 402,
+          body: { error: "Payment settlement failed", details: settleResult.errorReason }
+        };
+      }
+
+      const paymentContext: PaywallPaymentContext = {
+        method: "crypto",
+        amount_cents: amountCents,
+        currency,
+        transaction_hash: settleResult.transaction,
+        payer_address: verifyResult.payer ?? undefined,
+        network: cryptoNetwork
+      };
+      return { outcome: "crypto_paid", paymentContext };
+    } catch (error) {
+      if (error instanceof AgentSpendChargeError) {
+        return { outcome: "error", statusCode: error.statusCode, body: { error: error.message, details: error.details } };
+      }
+      return {
+        outcome: "error",
+        statusCode: 500,
+        body: { error: "Crypto payment processing failed", details: (error as Error).message }
+      };
+    }
+  }
+
+  // -------------------------------------------------------------------
+  // processPaywall() — unified entry point for adapters
+  // -------------------------------------------------------------------
+
+  async function processPaywall(opts: PaywallOptions, request: PaywallRequest): Promise<PaywallResult> {
+    const { amount } = opts;
+
+    if (typeof amount === "number") {
+      if (!Number.isInteger(amount) || amount <= 0) {
+        throw new AgentSpendChargeError("amount must be a positive integer", 500);
+      }
+    }
+
+    const body = request.body;
+
+    const effectiveAmount = resolveAmount(amount, body);
+
+    if (!Number.isInteger(effectiveAmount) || effectiveAmount <= 0) {
+      return { outcome: "error", statusCode: 400, body: { error: "Could not determine payment amount from request" } };
+    }
+
+    const currency = opts.currency ?? "usd";
+
+    // Check for crypto payment header
+    const paymentHeader = extractPaymentHeader(request.headers);
+    if (paymentHeader) {
+      return handleCryptoPayment(paymentHeader, effectiveAmount, currency);
+    }
+
+    // Check for card payment
+    const cardId = extractCardId(request.headers, body);
+    if (cardId) {
+      return handleCardPayment(request, cardId, effectiveAmount, currency, body, opts);
+    }
+
+    // Neither → 402
+    return build402Result(request.url, effectiveAmount, currency);
+  }
+
+  return { charge, processPaywall };
+}

package/src/core/error.ts

@@ -0,0 +1,10 @@
+export class AgentSpendChargeError extends Error {
+  statusCode: number;
+  details: unknown;
+
+  constructor(message: string, statusCode: number, details?: unknown) {
+    super(message);
+    this.statusCode = statusCode;
+    this.details = details;
+  }
+}