@agentspend/sdk 0.3.8 → 0.3.9

package/src/core/helpers.ts

@@ -0,0 +1,87 @@
+export function toCardId(input: unknown): string | null {
+  if (typeof input !== "string") {
+    return null;
+  }
+  const trimmed = input.trim();
+  if (!trimmed.startsWith("card_")) {
+    return null;
+  }
+  return trimmed;
+}
+
+export function joinUrl(base: string, path: string): string {
+  const normalizedBase = base.endsWith("/") ? base.slice(0, -1) : base;
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  return `${normalizedBase}${normalizedPath}`;
+}
+
+export function bestEffortIdempotencyKey(): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) {
+    return uuid;
+  }
+  return `auto_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+}
+
+export function toStringMetadata(input: unknown): Record<string, string> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    return {};
+  }
+
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+    if (typeof value === "string") {
+      result[key] = value;
+    } else if (typeof value === "number" && Number.isFinite(value)) {
+      result[key] = String(value);
+    } else if (typeof value === "boolean") {
+      result[key] = value ? "true" : "false";
+    }
+  }
+  return result;
+}
+
+const DEFAULT_PLATFORM_API_BASE_URL = "https://api.agentspend.co";
+
+export function resolvePlatformApiBaseUrl(explicitBaseUrl: string | undefined): string {
+  if (explicitBaseUrl && explicitBaseUrl.trim().length > 0) {
+    return explicitBaseUrl.trim();
+  }
+
+  const envValue =
+    typeof process !== "undefined" && process.env ? process.env.AGENTSPEND_API_URL : undefined;
+
+  if (typeof envValue === "string" && envValue.trim().length > 0) {
+    return envValue.trim();
+  }
+
+  return DEFAULT_PLATFORM_API_BASE_URL;
+}
+
+export function resolveAmount(amount: number | string | ((body: unknown) => number), body: unknown): number {
+  if (typeof amount === "number") {
+    return amount;
+  } else if (typeof amount === "string") {
+    const raw = (body as Record<string, unknown>)?.[amount];
+    return typeof raw === "number" ? raw : 0;
+  } else {
+    return amount(body);
+  }
+}
+
+export function extractCardId(headers: Record<string, string | undefined>, body: unknown): string | null {
+  const cardIdFromHeader = headers["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;
+    cardId = toCardId(bodyCardId);
+  }
+  return cardId;
+}
+
+export function extractPaymentHeader(headers: Record<string, string | undefined>): string | undefined {
+  return headers["payment-signature"] ?? headers["x-payment"] ?? undefined;
+}

package/src/core/index.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./error.js";
+export * from "./helpers.js";
+export { createAgentSpendClient } from "./client.js";
+export type { AgentSpendClient } from "./client.js";

package/src/core/types.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// 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;
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface AgentSpendOptions {
+  /**
+   * Base URL for the AgentSpend Platform API.
+   *
+   * If omitted, the SDK will use `process.env.AGENTSPEND_API_URL` when available,
+   * otherwise it falls back to the hosted default.
+   */
+  platformApiBaseUrl?: string;
+  /** Service API key. Optional — crypto-only services don't need one. */
+  serviceApiKey?: string;
+  fetchImpl?: typeof fetch;
+  /** Crypto / x402 configuration. */
+  crypto?: {
+    /** Static payTo address for crypto-only services. */
+    receiverAddress?: string;
+    /** Chain identifier. Default: "eip155:8453" (Base). */
+    network?: string;
+    /** x402 facilitator URL. Default: "https://x402.org/facilitator". */
+    facilitatorUrl?: string;
+  };
+}
+
+export interface ChargeOptions {
+  amount_cents: number;
+  currency?: string;
+  description?: string;
+  metadata?: Record<string, string>;
+  idempotency_key?: string;
+}
+
+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>;
+}
+
+// ---------------------------------------------------------------------------
+// Framework-agnostic request / result types
+// ---------------------------------------------------------------------------
+
+export interface PaywallRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string | undefined>;
+  body: unknown;
+}
+
+export type PaywallResult =
+  | { outcome: "charged"; paymentContext: PaywallPaymentContext }
+  | { outcome: "crypto_paid"; paymentContext: PaywallPaymentContext }
+  | { outcome: "payment_required"; statusCode: 402; body: Record<string, unknown>; headers: Record<string, string> }
+  | { outcome: "error"; statusCode: number; body: Record<string, unknown> };

package/src/express/index.ts

@@ -0,0 +1,101 @@
+import { createAgentSpendClient } from "../core/client.js";
+import type {
+  AgentSpendOptions,
+  ChargeOptions,
+  ChargeResponse,
+  PaywallOptions,
+  PaywallPaymentContext,
+  PaywallRequest
+} from "../core/types.js";
+
+export * from "../core/index.js";
+
+// ---------------------------------------------------------------------------
+// Express type abstractions (avoid hard dependency on @types/express)
+// ---------------------------------------------------------------------------
+
+interface ExpressRequest {
+  body: unknown;
+  url: string;
+  method: string;
+  get(name: string): string | undefined;
+  header(name: string): string | undefined;
+  paymentContext?: PaywallPaymentContext;
+}
+
+interface ExpressResponse {
+  status(code: number): ExpressResponse;
+  set(name: string, value: string): ExpressResponse;
+  json(body: unknown): void;
+}
+
+type NextFunction = (err?: unknown) => void;
+
+// ---------------------------------------------------------------------------
+// Payment context helper
+// ---------------------------------------------------------------------------
+
+export function getPaymentContext(req: ExpressRequest): PaywallPaymentContext | null {
+  return req.paymentContext ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface AgentSpend {
+  charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+  paywall(opts: PaywallOptions): (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
+  const client = createAgentSpendClient(options);
+
+  function paywall(opts: PaywallOptions) {
+    return function paywallMiddleware(
+      req: ExpressRequest,
+      res: ExpressResponse,
+      next: NextFunction
+    ): void {
+      const headerGet = (name: string) => req.get?.(name) ?? req.header?.(name);
+
+      const request: PaywallRequest = {
+        url: req.url,
+        method: req.method,
+        headers: {
+          "x-card-id": headerGet("x-card-id"),
+          "payment-signature": headerGet("payment-signature"),
+          "x-payment": headerGet("x-payment"),
+          "x-request-id": headerGet("x-request-id"),
+          "idempotency-key": headerGet("idempotency-key"),
+        },
+        body: req.body
+      };
+
+      client.processPaywall(opts, request).then((result) => {
+        switch (result.outcome) {
+          case "charged":
+          case "crypto_paid":
+            req.paymentContext = result.paymentContext;
+            next();
+            return;
+          case "payment_required":
+            for (const [key, value] of Object.entries(result.headers)) {
+              res.set(key, value);
+            }
+            res.status(result.statusCode).json(result.body);
+            return;
+          case "error":
+            res.status(result.statusCode).json(result.body);
+            return;
+        }
+      }).catch((err) => next(err));
+    };
+  }
+
+  return { charge: client.charge, paywall };
+}

package/src/fastify/index.ts

@@ -0,0 +1,120 @@
+import { createAgentSpendClient } from "../core/client.js";
+import type {
+  AgentSpendOptions,
+  ChargeOptions,
+  ChargeResponse,
+  PaywallOptions,
+  PaywallPaymentContext,
+  PaywallRequest
+} from "../core/types.js";
+
+export * from "../core/index.js";
+
+// ---------------------------------------------------------------------------
+// Fastify type abstractions (avoid hard dependency on fastify)
+// ---------------------------------------------------------------------------
+
+interface FastifyRequest {
+  body: unknown;
+  url: string;
+  method: string;
+  headers: Record<string, string | string[] | undefined>;
+  paymentContext?: PaywallPaymentContext;
+}
+
+interface FastifyReply {
+  code(statusCode: number): FastifyReply;
+  header(name: string, value: string): FastifyReply;
+  send(body: unknown): FastifyReply;
+}
+
+interface FastifyInstance {
+  decorate(name: string, value: unknown): void;
+  decorateRequest(name: string, value: unknown): void;
+  addHook(name: string, handler: (req: FastifyRequest, reply: FastifyReply) => Promise<void>): void;
+}
+
+type DoneCallback = (err?: Error) => void;
+
+// ---------------------------------------------------------------------------
+// Payment context helper
+// ---------------------------------------------------------------------------
+
+export function getPaymentContext(req: FastifyRequest): PaywallPaymentContext | null {
+  return req.paymentContext ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface AgentSpend {
+  charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+  paywall(opts: PaywallOptions): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  plugin(opts: PaywallOptions): (fastify: FastifyInstance, _options: unknown, done: DoneCallback) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
+  const client = createAgentSpendClient(options);
+
+  function paywall(opts: PaywallOptions) {
+    return async function preHandler(
+      req: FastifyRequest,
+      reply: FastifyReply
+    ): Promise<void> {
+      const headerGet = (name: string): string | undefined => {
+        const val = req.headers[name];
+        return Array.isArray(val) ? val[0] : val;
+      };
+
+      const request: PaywallRequest = {
+        url: req.url,
+        method: req.method,
+        headers: {
+          "x-card-id": headerGet("x-card-id"),
+          "payment-signature": headerGet("payment-signature"),
+          "x-payment": headerGet("x-payment"),
+          "x-request-id": headerGet("x-request-id"),
+          "idempotency-key": headerGet("idempotency-key"),
+        },
+        body: req.body
+      };
+
+      const result = await client.processPaywall(opts, request);
+
+      switch (result.outcome) {
+        case "charged":
+        case "crypto_paid":
+          req.paymentContext = result.paymentContext;
+          return;
+        case "payment_required":
+          for (const [key, value] of Object.entries(result.headers)) {
+            reply.header(key, value);
+          }
+          reply.code(result.statusCode).send(result.body);
+          return;
+        case "error":
+          reply.code(result.statusCode).send(result.body);
+          return;
+      }
+    };
+  }
+
+  function plugin(opts: PaywallOptions) {
+    return function agentSpendPlugin(
+      fastify: FastifyInstance,
+      _options: unknown,
+      done: DoneCallback
+    ): void {
+      fastify.decorateRequest("paymentContext", null);
+      fastify.addHook("preHandler", paywall(opts));
+      done();
+    };
+  }
+
+  return { charge: client.charge, paywall, plugin };
+}

package/src/hono/index.ts

@@ -0,0 +1,97 @@
+import { createAgentSpendClient } from "../core/client.js";
+import type {
+  AgentSpendOptions,
+  ChargeOptions,
+  ChargeResponse,
+  PaywallOptions,
+  PaywallPaymentContext,
+  PaywallRequest
+} from "../core/types.js";
+
+export * from "../core/index.js";
+
+// ---------------------------------------------------------------------------
+// Hono context abstraction
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// Payment context helper
+// ---------------------------------------------------------------------------
+
+const PAYMENT_CONTEXT_KEY = "payment";
+
+export function getPaymentContext(c: HonoContextLike): PaywallPaymentContext | null {
+  const ctx = c.get(PAYMENT_CONTEXT_KEY);
+  return (ctx as PaywallPaymentContext) ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface AgentSpend {
+  charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+  paywall(opts: PaywallOptions): (c: HonoContextLike, next: () => Promise<void>) => Promise<Response | void>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
+  const client = createAgentSpendClient(options);
+
+  function paywall(opts: PaywallOptions) {
+    return async function paywallMiddleware(
+      c: HonoContextLike,
+      next: () => Promise<void>
+    ): Promise<Response | void> {
+      const body: unknown = await c.req.json().catch(() => ({}));
+
+      const request: PaywallRequest = {
+        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/src/next/index.ts

@@ -0,0 +1,92 @@
+import { createAgentSpendClient } from "../core/client.js";
+import type {
+  AgentSpendOptions,
+  ChargeOptions,
+  ChargeResponse,
+  PaywallOptions,
+  PaywallPaymentContext,
+  PaywallRequest
+} from "../core/types.js";
+
+export * from "../core/index.js";
+
+// ---------------------------------------------------------------------------
+// Next.js type abstractions (avoid hard dependency on next)
+// ---------------------------------------------------------------------------
+
+interface NextRequest {
+  url: string;
+  method: string;
+  headers: {
+    get(name: string): string | null;
+  };
+  json(): Promise<unknown>;
+}
+
+interface NextResponseInit {
+  status?: number;
+  headers?: Record<string, string>;
+}
+
+declare const NextResponse: {
+  json(body: unknown, init?: NextResponseInit): Response;
+};
+
+// ---------------------------------------------------------------------------
+// Public interface
+// ---------------------------------------------------------------------------
+
+export interface AgentSpend {
+  charge(cardId: string, opts: ChargeOptions): Promise<ChargeResponse>;
+  withPaywall(
+    opts: PaywallOptions,
+    handler: (req: NextRequest, paymentContext: PaywallPaymentContext) => Promise<Response>
+  ): (req: NextRequest) => Promise<Response>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createAgentSpend(options: AgentSpendOptions): AgentSpend {
+  const client = createAgentSpendClient(options);
+
+  function withPaywall(
+    opts: PaywallOptions,
+    handler: (req: NextRequest, paymentContext: PaywallPaymentContext) => Promise<Response>
+  ) {
+    return async function wrappedHandler(req: NextRequest): Promise<Response> {
+      const body: unknown = await req.json().catch(() => ({}));
+
+      const request: PaywallRequest = {
+        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 };
+}