@opencardsdk/sdk 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# @opencard/sdk
+
+Client SDK for OpenCard — create virtual cards with USDC payments via the x402 protocol.
+
+Wraps the raw x402 flow (402 → parse challenge → pay USDC → retry with proof) into one-liner methods.
+
+## Install
+
+```bash
+npm install @opencard/sdk viem
+```
+
+## Quick Start
+
+```typescript
+import { OpenCardClient } from '@opencard/sdk';
+
+const client = new OpenCardClient({
+  privateKey: '0x...',       // or pass a viem WalletClient
+  baseUrl: 'https://api.opencard.com',
+});
+
+// One line — SDK handles payment automatically
+const card = await client.createCard({
+  amount: 10,               // $10 tier
+  nameOnCard: 'AI AGENT',
+  email: 'agent@example.com',
+});
+
+console.log(card.cardDetails); // { cardNumber, cvv, expiry, ... }
+```
+
+## API
+
+### `new OpenCardClient(config)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `privateKey` | `0x${string}` | One of | Hex private key — SDK creates wallet internally |
+| `walletClient` | `WalletClient` | One of | Your own viem WalletClient (takes precedence) |
+| `baseUrl` | `string` | No | API URL (default: `https://api.opencard.com`) |
+| `rpcUrl` | `string` | No | Base RPC URL (default: public RPC) |
+| `timeout` | `number` | No | Request timeout in ms (default: 60000) |
+
+### `client.createCard(params): Promise<CardResult>`
+
+Create a virtual card. Pays USDC automatically.
+
+```typescript
+const result = await client.createCard({
+  amount: 50,               // 10 | 25 | 50 | 100 | 200 | 500
+  nameOnCard: 'AI AGENT',
+  email: 'agent@example.com',
+});
+```
+
+### `client.fundCard(params): Promise<FundResult>`
+
+Fund an existing card.
+
+```typescript
+const result = await client.fundCard({
+  amount: 25,
+  cardId: 'card-uuid',
+});
+```
+
+### `client.getTiers(): Promise<TiersResponse>`
+
+Get pricing tiers and fee breakdown (no payment required).
+
+### `client.health(): Promise<{ status: string }>`
+
+Check if the OpenCard API is reachable.
+
+### `client.address: 0x${string}`
+
+The wallet address being used for payments.
+
+## Error Handling
+
+```typescript
+import {
+  OpenCardClient,
+  InsufficientBalanceError,
+  PaymentError,
+  ApiError,
+  TimeoutError,
+} from '@opencard/sdk';
+
+try {
+  const card = await client.createCard({ ... });
+} catch (error) {
+  if (error instanceof InsufficientBalanceError) {
+    console.log(`Need ${error.required}, have ${error.available}`);
+  } else if (error instanceof PaymentError) {
+    console.log(`Payment failed: ${error.message}, tx: ${error.txHash}`);
+  } else if (error instanceof ApiError) {
+    console.log(`Server error ${error.status}:`, error.body);
+  } else if (error instanceof TimeoutError) {
+    console.log('Request timed out');
+  }
+}
+```
+
+## Advanced: Low-Level x402 Utilities
+
+For custom integrations, the x402 protocol helpers are exported directly:
+
+```typescript
+import {
+  parseChallenge,
+  checkBalance,
+  executePayment,
+  buildPaymentProof,
+  handleX402Payment,
+} from '@opencard/sdk';
+```
+
+## How It Works
+
+```
+Your Code          SDK                    OpenCard API          Base Chain
+   |                |                         |                    |
+   |-- createCard ->|                         |                    |
+   |                |--- POST /create/tier -->|                    |
+   |                |<-- 402 + challenge -----|                    |
+   |                |                         |                    |
+   |                |--- USDC.transfer() -----|-------- tx ------->|
+   |                |<-- txHash --------------|-------- receipt ---|
+   |                |                         |                    |
+   |                |--- POST + X-Payment --->|                    |
+   |                |<-- 201 + card details --|                    |
+   |<- CardResult --|                         |                    |
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import type { OpenCardConfig, CreateCardParams, FundCardParams, CardResult, FundResult, TiersResponse } from "./types.js";
+export declare class OpenCardClient {
+    private walletClient;
+    private baseUrl;
+    private timeout;
+    constructor(config: OpenCardConfig);
+    /** The wallet address used for payments */
+    get address(): `0x${string}`;
+    /**
+     * Create a virtual card with automatic USDC payment.
+     *
+     * Handles the full x402 flow:
+     * 1. Sends request → gets 402 with payment requirements
+     * 2. Executes USDC transfer on Base
+     * 3. Retries with payment proof
+     * 4. Returns card details
+     */
+    createCard(params: CreateCardParams): Promise<CardResult>;
+    /**
+     * Fund an existing card with automatic USDC payment.
+     */
+    fundCard(params: FundCardParams): Promise<FundResult>;
+    /**
+     * Get available tiers and pricing breakdown (no payment required).
+     */
+    getTiers(): Promise<TiersResponse>;
+    /**
+     * Health check — verify the server is reachable.
+     */
+    health(): Promise<{
+        status: string;
+    }>;
+    /**
+     * Execute a paid request with automatic x402 handling.
+     *
+     * 1. POST to endpoint → expect 402
+     * 2. Parse challenge → execute USDC payment → build proof
+     * 3. Retry POST with X-Payment header
+     */
+    private paidRequest;
+    private fetch;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAC;AAOpB,qBAAa,cAAc;IACzB,OAAO,CAAC,YAAY,CAA0C;IAC9D,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,cAAc;IAqBlC,2CAA2C;IAC3C,IAAI,OAAO,IAAI,KAAK,MAAM,EAAE,CAE3B;IAID;;;;;;;;OAQG;IACG,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAU/D;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAU3D;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;IAgBxC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAO3C;;;;;;OAMG;YACW,WAAW;YAqDX,KAAK;CAepB"}

package/dist/client.js

@@ -0,0 +1,143 @@
+import { createWalletClient, http, } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { base } from "viem/chains";
+import { handleX402Payment } from "./x402.js";
+import { ConfigError, ApiError, TimeoutError } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.opencard.com";
+const DEFAULT_TIMEOUT = 60_000;
+export class OpenCardClient {
+    walletClient;
+    baseUrl;
+    timeout;
+    constructor(config) {
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        if (config.walletClient) {
+            if (!config.walletClient.account) {
+                throw new ConfigError("walletClient must have an account attached");
+            }
+            this.walletClient = config.walletClient;
+        }
+        else if (config.privateKey) {
+            const account = privateKeyToAccount(config.privateKey);
+            this.walletClient = createWalletClient({
+                account,
+                chain: base,
+                transport: http(config.rpcUrl),
+            });
+        }
+        else {
+            throw new ConfigError("Provide either privateKey or walletClient");
+        }
+    }
+    /** The wallet address used for payments */
+    get address() {
+        return this.walletClient.account.address;
+    }
+    // ── Card Creation ───────────────────────────────────────────────────
+    /**
+     * Create a virtual card with automatic USDC payment.
+     *
+     * Handles the full x402 flow:
+     * 1. Sends request → gets 402 with payment requirements
+     * 2. Executes USDC transfer on Base
+     * 3. Retries with payment proof
+     * 4. Returns card details
+     */
+    async createCard(params) {
+        const { amount, nameOnCard, email } = params;
+        const endpoint = `${this.baseUrl}/cards/create/tier/${amount}`;
+        const body = JSON.stringify({ nameOnCard, email });
+        return this.paidRequest(endpoint, body);
+    }
+    // ── Card Funding ────────────────────────────────────────────────────
+    /**
+     * Fund an existing card with automatic USDC payment.
+     */
+    async fundCard(params) {
+        const { amount, cardId } = params;
+        const endpoint = `${this.baseUrl}/cards/fund/tier/${amount}`;
+        const body = JSON.stringify({ cardId });
+        return this.paidRequest(endpoint, body);
+    }
+    // ── Pricing ─────────────────────────────────────────────────────────
+    /**
+     * Get available tiers and pricing breakdown (no payment required).
+     */
+    async getTiers() {
+        const res = await this.fetch(`${this.baseUrl}/cards/tiers`, {
+            method: "GET",
+        });
+        if (!res.ok) {
+            throw new ApiError(`Failed to fetch tiers: ${res.statusText}`, res.status, await res.json().catch(() => null));
+        }
+        return res.json();
+    }
+    /**
+     * Health check — verify the server is reachable.
+     */
+    async health() {
+        const res = await this.fetch(`${this.baseUrl}/health`, { method: "GET" });
+        return res.json();
+    }
+    // ── Internal: x402 Payment Flow ─────────────────────────────────────
+    /**
+     * Execute a paid request with automatic x402 handling.
+     *
+     * 1. POST to endpoint → expect 402
+     * 2. Parse challenge → execute USDC payment → build proof
+     * 3. Retry POST with X-Payment header
+     */
+    async paidRequest(endpoint, body) {
+        // Step 1: Initial request — expect 402
+        const initialRes = await this.fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        });
+        // If server doesn't return 402, handle accordingly
+        if (initialRes.status !== 402) {
+            if (initialRes.ok) {
+                // No payment needed (shouldn't happen but handle gracefully)
+                return initialRes.json();
+            }
+            const errorBody = await initialRes.json().catch(() => null);
+            throw new ApiError(`Unexpected response: ${initialRes.status} ${initialRes.statusText}`, initialRes.status, errorBody);
+        }
+        // Step 2: Parse 402, pay, get proof
+        const challengeBody = await initialRes.json();
+        const { header, txHash } = await handleX402Payment(this.walletClient, challengeBody);
+        // Step 3: Retry with payment proof
+        const paidRes = await this.fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Payment": header,
+            },
+            body,
+        });
+        if (!paidRes.ok) {
+            const errorBody = await paidRes.json().catch(() => null);
+            throw new ApiError(`Request failed after payment (tx: ${txHash}): ${paidRes.status}`, paidRes.status, errorBody);
+        }
+        return paidRes.json();
+    }
+    // ── Internal: Fetch with timeout ────────────────────────────────────
+    async fetch(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === "AbortError") {
+                throw new TimeoutError(this.timeout);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/** Base error for all OpenCard SDK errors */
+export declare class OpenCardError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Configuration is invalid or missing */
+export declare class ConfigError extends OpenCardError {
+    constructor(message: string);
+}
+/** Server returned 402 but payment failed */
+export declare class PaymentError extends OpenCardError {
+    readonly txHash?: string;
+    constructor(message: string, options?: {
+        txHash?: string;
+    });
+}
+/** Insufficient USDC balance to cover the payment */
+export declare class InsufficientBalanceError extends OpenCardError {
+    readonly required: bigint;
+    readonly available: bigint;
+    constructor(required: bigint, available: bigint);
+}
+/** Server returned a non-402 error */
+export declare class ApiError extends OpenCardError {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+/** Request timed out */
+export declare class TimeoutError extends OpenCardError {
+    constructor(ms: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,qBAAa,aAAc,SAAQ,KAAK;aAGpB,IAAI,EAAE,MAAM;gBAD5B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B;AAED,0CAA0C;AAC1C,qBAAa,WAAY,SAAQ,aAAa;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,6CAA6C;AAC7C,qBAAa,YAAa,SAAQ,aAAa;IAC7C,SAAgB,MAAM,CAAC,EAAE,MAAM,CAAC;gBAG9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAMhC;AAED,qDAAqD;AACrD,qBAAa,wBAAyB,SAAQ,aAAa;aAEvC,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,MAAM;gBADjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM;CAQpC;AAED,sCAAsC;AACtC,qBAAa,QAAS,SAAQ,aAAa;aAGvB,MAAM,EAAE,MAAM;aACd,IAAI,CAAC,EAAE,OAAO;gBAF9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED,wBAAwB;AACxB,qBAAa,YAAa,SAAQ,aAAa;gBACjC,EAAE,EAAE,MAAM;CAIvB"}

package/dist/errors.js

@@ -0,0 +1,55 @@
+/** Base error for all OpenCard SDK errors */
+export class OpenCardError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "OpenCardError";
+    }
+}
+/** Configuration is invalid or missing */
+export class ConfigError extends OpenCardError {
+    constructor(message) {
+        super(message, "CONFIG_ERROR");
+        this.name = "ConfigError";
+    }
+}
+/** Server returned 402 but payment failed */
+export class PaymentError extends OpenCardError {
+    txHash;
+    constructor(message, options) {
+        super(message, "PAYMENT_ERROR");
+        this.name = "PaymentError";
+        this.txHash = options?.txHash;
+    }
+}
+/** Insufficient USDC balance to cover the payment */
+export class InsufficientBalanceError extends OpenCardError {
+    required;
+    available;
+    constructor(required, available) {
+        super(`Insufficient USDC balance: need ${required} but have ${available} (amounts in 6-decimal units)`, "INSUFFICIENT_BALANCE");
+        this.required = required;
+        this.available = available;
+        this.name = "InsufficientBalanceError";
+    }
+}
+/** Server returned a non-402 error */
+export class ApiError extends OpenCardError {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message, "API_ERROR");
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+/** Request timed out */
+export class TimeoutError extends OpenCardError {
+    constructor(ms) {
+        super(`Request timed out after ${ms}ms`, "TIMEOUT");
+        this.name = "TimeoutError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,OAAO,aAAc,SAAQ,KAAK;IAGpB;IAFlB,YACE,OAAe,EACC,IAAY;QAE5B,KAAK,CAAC,OAAO,CAAC,CAAC;QAFC,SAAI,GAAJ,IAAI,CAAQ;QAG5B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,0CAA0C;AAC1C,MAAM,OAAO,WAAY,SAAQ,aAAa;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,6CAA6C;AAC7C,MAAM,OAAO,YAAa,SAAQ,aAAa;IAC7B,MAAM,CAAU;IAEhC,YACE,OAAe,EACf,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAChC,CAAC;CACF;AAED,qDAAqD;AACrD,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IAEvC;IACA;IAFlB,YACkB,QAAgB,EAChB,SAAiB;QAEjC,KAAK,CACH,mCAAmC,QAAQ,aAAa,SAAS,+BAA+B,EAChG,sBAAsB,CACvB,CAAC;QANc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAQ;QAMjC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,sCAAsC;AACtC,MAAM,OAAO,QAAS,SAAQ,aAAa;IAGvB;IACA;IAHlB,YACE,OAAe,EACC,MAAc,EACd,IAAc;QAE9B,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAHZ,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAU;QAG9B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,wBAAwB;AACxB,MAAM,OAAO,YAAa,SAAQ,aAAa;IAC7C,YAAY,EAAU;QACpB,KAAK,CAAC,2BAA2B,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { OpenCardClient } from "./client.js";
+export type { OpenCardConfig, CreateCardParams, FundCardParams, CardResult, FundResult, TiersResponse, TierBreakdown, X402Challenge, X402PaymentOption, X402PaymentProof, } from "./types.js";
+export { OpenCardError, ConfigError, PaymentError, InsufficientBalanceError, ApiError, TimeoutError, } from "./errors.js";
+export { parseChallenge, checkBalance, executePayment, buildPaymentProof, handleX402Payment, } from "./x402.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,UAAU,EACV,UAAU,EACV,aAAa,EACb,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,aAAa,EACb,WAAW,EACX,YAAY,EACZ,wBAAwB,EACxB,QAAQ,EACR,YAAY,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// ── Main Client ─────────────────────────────────────────────────────
+export { OpenCardClient } from "./client.js";
+// ── Errors ──────────────────────────────────────────────────────────
+export { OpenCardError, ConfigError, PaymentError, InsufficientBalanceError, ApiError, TimeoutError, } from "./errors.js";
+// ── Low-level x402 utilities (for advanced usage) ───────────────────
+export { parseChallenge, checkBalance, executePayment, buildPaymentProof, handleX402Payment, } from "./x402.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgB7C,uEAAuE;AACvE,OAAO,EACL,aAAa,EACb,WAAW,EACX,YAAY,EACZ,wBAAwB,EACxB,QAAQ,EACR,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,uEAAuE;AACvE,OAAO,EACL,cAAc,EACd,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,WAAW,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+import type { Account, Chain, Transport, WalletClient } from "viem";
+export interface OpenCardConfig {
+    /** Private key (hex string with 0x prefix) — creates a wallet client internally */
+    privateKey?: `0x${string}`;
+    /** Or pass your own viem WalletClient (takes precedence over privateKey) */
+    walletClient?: WalletClient<Transport, Chain, Account>;
+    /** OpenCard API base URL (default: https://api.opencard.com) */
+    baseUrl?: string;
+    /** RPC URL for Base network (default: public Base RPC) */
+    rpcUrl?: string;
+    /** Request timeout in ms (default: 60000) */
+    timeout?: number;
+}
+export interface CreateCardParams {
+    /** Tier amount in USD (10, 25, 50, 100, 200, 500) */
+    amount: number;
+    /** Name printed on the card (auto-uppercased) */
+    nameOnCard: string;
+    /** Email for card notifications */
+    email: string;
+}
+export interface FundCardParams {
+    /** Tier amount in USD (10, 25, 50, 100, 200, 500) */
+    amount: number;
+    /** Card ID to fund */
+    cardId: string;
+}
+export interface CardResult {
+    success: boolean;
+    card: {
+        cardId: string;
+        kripiCardId: string;
+        nameOnCard: string;
+        lastFour?: string;
+        balance: number | null;
+        status: string;
+        createdAt: string;
+    };
+    cardDetails?: {
+        cardNumber: string;
+        expiryMonth: number;
+        expiryYear: number;
+        cvv: string;
+        billingAddress: {
+            street: string;
+            city: string;
+            state: string;
+            zip: string;
+            country: string;
+        };
+    };
+    payment: {
+        walletAddress: string;
+        txHash?: string;
+        amountUsd: number;
+    };
+}
+export interface FundResult {
+    success: boolean;
+    card: {
+        cardId: string;
+        newBalance?: number;
+    };
+    payment: {
+        walletAddress: string;
+        txHash?: string;
+        amountUsd: number;
+    };
+}
+export interface TierBreakdown {
+    loadAmount?: number;
+    fundAmount?: number;
+    totalCost: number;
+    endpoint: string;
+    breakdown: {
+        cardLoad?: number;
+        fundAmount?: number;
+        issuanceFee?: number;
+        topUpFee: number;
+        ourFee: number;
+        buffer?: number;
+    };
+}
+export interface TiersResponse {
+    creation: TierBreakdown[];
+    funding: TierBreakdown[];
+}
+export interface X402Challenge {
+    x402Version: number;
+    accepts: X402PaymentOption[];
+    error?: string;
+}
+export interface X402PaymentOption {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    mimeType: string;
+    payTo: `0x${string}`;
+    maxTimeoutSeconds: number;
+    asset: `0x${string}`;
+    extra?: Record<string, unknown>;
+}
+export interface X402PaymentProof {
+    scheme: string;
+    network: string;
+    payload: {
+        authorization: {
+            from: string;
+            to: string;
+            value: string;
+            validAfter: string;
+            validBefore: string;
+            nonce: string;
+        };
+        signature: string;
+        txHash: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/x402.d.ts

@@ -0,0 +1,37 @@
+import { type Account, type Chain, type Transport, type WalletClient } from "viem";
+import type { X402Challenge, X402PaymentOption } from "./types.js";
+/**
+ * Parse a 402 response body into a structured challenge.
+ */
+export declare function parseChallenge(body: unknown): X402Challenge;
+/**
+ * Check if the wallet has enough USDC to cover the payment.
+ * Uses a public client for read-only calls.
+ */
+export declare function checkBalance(walletClient: WalletClient<Transport, Chain, Account>, amount: bigint): Promise<void>;
+/**
+ * Execute USDC transfer on Base to the specified recipient.
+ * Returns the transaction hash.
+ */
+export declare function executePayment(walletClient: WalletClient<Transport, Chain, Account>, payTo: `0x${string}`, amount: bigint): Promise<`0x${string}`>;
+/**
+ * Construct the x402 payment proof from the completed transaction.
+ */
+export declare function buildPaymentProof(paymentOption: X402PaymentOption, from: `0x${string}`, txHash: `0x${string}`): string;
+/**
+ * Full x402 payment flow:
+ * 1. Parse 402 challenge
+ * 2. Check USDC balance
+ * 3. Execute USDC transfer
+ * 4. Build payment proof header
+ *
+ * Returns the encoded X-Payment header value.
+ */
+export declare function handleX402Payment(walletClient: WalletClient<Transport, Chain, Account>, challengeBody: unknown, options?: {
+    skipBalanceCheck?: boolean;
+}): Promise<{
+    header: string;
+    txHash: `0x${string}`;
+    amountPaid: bigint;
+}>;
+//# sourceMappingURL=x402.d.ts.map

package/dist/x402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.d.ts","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,SAAS,EACd,KAAK,YAAY,EAGlB,MAAM,MAAM,CAAC;AAEd,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAoB,MAAM,YAAY,CAAC;AA0BrF;;GAEG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,CAM3D;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACrD,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACrD,KAAK,EAAE,KAAK,MAAM,EAAE,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAcxB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,iBAAiB,EAChC,IAAI,EAAE,KAAK,MAAM,EAAE,EACnB,MAAM,EAAE,KAAK,MAAM,EAAE,GACpB,MAAM,CAmBR;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,YAAY,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACrD,aAAa,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GACvC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CAqBxE"}

package/dist/x402.js

@@ -0,0 +1,118 @@
+import { createPublicClient, http, } from "viem";
+import { base } from "viem/chains";
+import { PaymentError, InsufficientBalanceError } from "./errors.js";
+// USDC on Base
+const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const USDC_ABI = [
+    {
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        name: "transfer",
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "nonpayable",
+        type: "function",
+    },
+    {
+        inputs: [{ name: "account", type: "address" }],
+        name: "balanceOf",
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+        type: "function",
+    },
+];
+/**
+ * Parse a 402 response body into a structured challenge.
+ */
+export function parseChallenge(body) {
+    const challenge = body;
+    if (!challenge.accepts || !Array.isArray(challenge.accepts) || challenge.accepts.length === 0) {
+        throw new PaymentError("Invalid 402 response: missing payment options");
+    }
+    return challenge;
+}
+/**
+ * Check if the wallet has enough USDC to cover the payment.
+ * Uses a public client for read-only calls.
+ */
+export async function checkBalance(walletClient, amount) {
+    const publicClient = createPublicClient({
+        chain: walletClient.chain ?? base,
+        transport: http(),
+    });
+    const available = await publicClient.readContract({
+        address: USDC_BASE,
+        abi: USDC_ABI,
+        functionName: "balanceOf",
+        args: [walletClient.account.address],
+    });
+    if (available < amount) {
+        throw new InsufficientBalanceError(amount, available);
+    }
+}
+/**
+ * Execute USDC transfer on Base to the specified recipient.
+ * Returns the transaction hash.
+ */
+export async function executePayment(walletClient, payTo, amount) {
+    try {
+        const hash = await walletClient.writeContract({
+            address: USDC_BASE,
+            abi: USDC_ABI,
+            functionName: "transfer",
+            args: [payTo, amount],
+        });
+        return hash;
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : "USDC transfer failed";
+        throw new PaymentError(`Payment transaction failed: ${msg}`);
+    }
+}
+/**
+ * Construct the x402 payment proof from the completed transaction.
+ */
+export function buildPaymentProof(paymentOption, from, txHash) {
+    const proof = {
+        scheme: paymentOption.scheme,
+        network: paymentOption.network,
+        payload: {
+            authorization: {
+                from,
+                to: paymentOption.payTo,
+                value: paymentOption.maxAmountRequired,
+                validAfter: "0",
+                validBefore: "9999999999",
+                nonce: "0",
+            },
+            signature: "0x",
+            txHash,
+        },
+    };
+    return btoa(JSON.stringify(proof));
+}
+/**
+ * Full x402 payment flow:
+ * 1. Parse 402 challenge
+ * 2. Check USDC balance
+ * 3. Execute USDC transfer
+ * 4. Build payment proof header
+ *
+ * Returns the encoded X-Payment header value.
+ */
+export async function handleX402Payment(walletClient, challengeBody, options) {
+    const challenge = parseChallenge(challengeBody);
+    const paymentOption = challenge.accepts[0];
+    const amount = BigInt(paymentOption.maxAmountRequired);
+    // Optionally check balance first to give a better error
+    if (!options?.skipBalanceCheck) {
+        await checkBalance(walletClient, amount);
+    }
+    // Execute the USDC transfer
+    const txHash = await executePayment(walletClient, paymentOption.payTo, amount);
+    // Build the proof header
+    const header = buildPaymentProof(paymentOption, walletClient.account.address, txHash);
+    return { header, txHash, amountPaid: amount };
+}
+//# sourceMappingURL=x402.js.map

package/dist/x402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402.js","sourceRoot":"","sources":["../src/x402.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@opencardsdk/sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for OpenCard — create virtual cards with USDC payments via x402",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencard",
+    "x402",
+    "usdc",
+    "virtual-card",
+    "ai-agent",
+    "crypto-payments",
+    "base"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  }
+}