mpp-test-sdk 1.0.0 → 1.1.1

package/README.md

@@ -4,7 +4,7 @@
 [![Node.js](https://img.shields.io/node/v/mpp-test-sdk)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-zinc.svg)](LICENSE)
 
-Test pay-per-request APIs on Tempo testnet. Auto-creates wallets, funds from faucet, handles 402 payments — zero setup required.
+Test pay-per-request APIs on **Solana devnet**. Auto-creates wallets, airdrops SOL, handles HTTP 402 MPP payments — zero setup required.
 
 **[mpptestkit.com](https://mpptestkit.com)** · [GitHub](https://github.com/mpptestkit/mpp-test-sdk) · [X](https://x.com/mpptestkit)
 
@@ -25,6 +25,7 @@ Requires Node.js 22+.
 ```ts
 import { mppFetch } from "mpp-test-sdk";
 
+// Auto-creates Solana wallet, airdrops SOL, handles 402
 const res = await mppFetch("https://your-api.com/api/data");
 const data = await res.json();
 ```
@@ -41,7 +42,7 @@ const client = await createTestClient({
 const res = await client.fetch("https://your-api.com/api/data");
 ```
 
-The SDK handles the full flow: wallet generation, testnet faucet funding, 402 detection, on-chain payment, and automatic retry with payment proof.
+The SDK handles the full flow: Solana keypair generation, devnet SOL airdrop, 402 detection, on-chain SOL transfer, and automatic retry with payment proof.
 
 ---
 
@@ -52,13 +53,15 @@ import express from "express";
 import { createTestServer } from "mpp-test-sdk";
 
 const app = express();
-const mpp = createTestServer({ secretKey: process.env.MPP_SECRET_KEY });
+
+// No config needed — auto-generates a server wallet
+const mpp = createTestServer();
 
 // Free — no middleware
 app.get("/api/ping", (req, res) => res.json({ ok: true }));
 
-// Paid — one line
-app.get("/api/data", mpp.charge({ amount: "0.01" }), (req, res) => {
+// Paid — one line (0.001 SOL)
+app.get("/api/data", mpp.charge({ amount: "0.001" }), (req, res) => {
   res.json({ data: "premium content" });
 });
 
@@ -77,41 +80,40 @@ Call `mppFetch.reset()` to discard the shared client and generate a new wallet o
 
 ### `createTestClient(config?)`
 
-Creates a client with its own isolated wallet.
+Creates a client with its own isolated Solana wallet.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `privateKey` | `` `0x${string}` `` | auto-generated | Reuse a pre-funded wallet |
+| `secretKey` | `Uint8Array` | auto-generated | Reuse a pre-funded Solana keypair |
 | `onStep` | `(step: PaymentStep) => void` | — | Lifecycle event callback |
 | `timeout` | `number` | `30000` | Full flow timeout in ms |
-| `maxRetries` | `number` | `1` | Max retry attempts |
+| `rpcUrl` | `string` | devnet RPC | Solana RPC endpoint |
 
 Returns `Promise<TestClient>` with `{ address, method, fetch }`.
 
-**Throws:** `MppFaucetError` if the testnet faucet is unreachable.
+**Throws:** `MppFaucetError` if the Solana devnet airdrop fails.
 
-### `createTestServer(config)`
+### `createTestServer(config?)`
 
-Creates Express middleware that enforces payment on any route.
+Creates Express middleware that enforces MPP payment on any route.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `secretKey` | `string` | **required** | MPP secret key for payment verification |
-| `privateKey` | `` `0x${string}` `` | auto-generated | Server wallet private key |
-| `currency` | `` `0x${string}` `` | PathUSD | ERC-20 token address to accept |
+| `secretKey` | `Uint8Array` | auto-generated | Server wallet keypair |
+| `recipientAddress` | `string` | derived from keypair | Override recipient base58 address |
+| `rpcUrl` | `string` | devnet RPC | Solana RPC for verification |
+| `network` | `"devnet" \| "mainnet-beta"` | `"devnet"` | Network label in headers |
 
 Returns `MppServer` with `.charge({ amount })` middleware.
 
-**Throws:** `Error` synchronously if `secretKey` is missing.
-
 ### `PaymentStep` events
 
 | `step.type` | When |
 |---|---|
-| `"wallet-created"` | New ephemeral wallet generated |
-| `"funded"` | Faucet funding confirmed |
+| `"wallet-created"` | Solana keypair generated |
+| `"funded"` | Devnet airdrop confirmed |
 | `"request"` | Outgoing HTTP request |
-| `"payment"` | On-chain payment submitted |
+| `"payment"` | SOL transfer submitted or confirmed |
 | `"success"` | Final 200 response received |
 | `"error"` | Flow failed |
 
@@ -126,40 +128,52 @@ try {
   const res = await client.fetch("https://api.example.com/data");
 } catch (err) {
   if (err instanceof MppFaucetError) {
-    // Testnet faucet unreachable — err.address
+    // Devnet airdrop failed (rate limited) — err.address
   } else if (err instanceof MppPaymentError) {
-    // Payment rejected — err.status, err.url
+    // Server rejected payment — err.status, err.url
   } else if (err instanceof MppTimeoutError) {
     // Flow timed out — err.url, err.timeoutMs
   }
 }
 ```
 
-**Tip:** Pass a pre-funded `privateKey` to `createTestClient` during development to skip faucet calls.
+**Tip:** Pass a pre-funded `secretKey` to `createTestClient` to skip the airdrop step.
 
 ---
 
-## Network
+## Protocol
+
+The SDK implements **MPP (Machine Payments Protocol)** on Solana. The wire format is plain HTTP headers:
+
+```
+# Server → Client (402)
+Payment-Request: solana; amount="0.001"; recipient="<base58>"; network="devnet"
 
-All payments use **PathUSD** test tokens on **Tempo Moderato Testnet** (chain ID 42431). Real on-chain transactions, zero financial risk.
+# Client → Server (retry)
+Payment-Receipt: solana; signature="<base58_sig>"; network="devnet"; amount="0.001"
+```
+
+---
+
+## Network
 
 | | Value |
 |---|---|
-| Chain ID | `42431` |
-| RPC | `https://rpc.testnet.tempo.xyz` |
-| Explorer | `https://explorer.testnet.tempo.xyz` |
-| PathUSD | `0x20c0000000000000000000000000000000000000` |
-| Faucet | Automatic via SDK |
+| Network | Solana Devnet |
+| Currency | SOL (test) |
+| RPC | `https://api.devnet.solana.com` |
+| Explorer | `https://explorer.solana.com/?cluster=devnet` |
+| Faucet | Automatic via `connection.requestAirdrop()` |
 
 ---
 
 ## Troubleshooting
 
-**`MppFaucetError`** — Faucet has rate limits. Wait a few seconds and retry, or pass a pre-funded `privateKey` to skip faucet calls.
+**`MppFaucetError`** — Devnet airdrop is rate limited. Wait 30–60 seconds and retry, or pass a pre-funded `secretKey` to skip the faucet.
 
-**`MppTimeoutError`** — Increase `timeout` in `createTestClient`. On-chain confirmations typically take 2–5 seconds.
+**`MppTimeoutError`** — Increase `timeout` in `createTestClient`. Solana devnet confirmations typically take 1–5 seconds.
 
-**402 not handled** — Ensure `createTestServer` is called with a valid `secretKey` and the middleware is placed before the route handler.
+**402 not handled** — Ensure the server has `createTestServer()` middleware in place before the route handler.
 
 ---
 

package/dist/index.d.mts

@@ -1,62 +1,86 @@
 import { RequestHandler } from 'express';
 
+/** Solana network to connect to. */
+type SolanaNetwork = "devnet" | "testnet" | "mainnet";
 interface PaymentStep {
-    type: "wallet-created" | "funded" | "request" | "payment" | "success" | "error";
+    type: "wallet-created" | "funded" | "request" | "payment" | "retry" | "success" | "error";
     message: string;
     data?: Record<string, unknown>;
 }
 interface TestClientConfig {
-    /** Use a specific wallet. If omitted, a new wallet is auto-generated. */
-    privateKey?: `0x${string}`;
+    /**
+     * Solana network to connect to.
+     * - `"devnet"` (default) — Free SOL airdrop, fast confirmation.
+     * - `"testnet"` — Solana's testnet. Also has free airdrop.
+     * - `"mainnet"` — Real SOL. Requires a pre-funded `secretKey`.
+     */
+    network?: SolanaNetwork;
+    /**
+     * Pre-funded Solana keypair secret key (32 or 64 bytes).
+     * - On `devnet`/`testnet`: optional — wallet is auto-funded via airdrop.
+     * - On `mainnet`: **required** — no airdrop available.
+     */
+    secretKey?: Uint8Array;
     /** Lifecycle event callback for observing the payment flow. */
     onStep?: (step: PaymentStep) => void;
-    /** Request timeout in milliseconds. Default: 30000 (30s). */
+    /** Full flow timeout in ms (wallet + payment + retry). Default: 30000. */
     timeout?: number;
-    /** Maximum retry attempts for transient failures. Default: 1 (single 402 retry). */
-    maxRetries?: number;
+    /** Override the Solana RPC endpoint. Takes precedence over `network`. */
+    rpcUrl?: string;
 }
 interface TestClient {
-    /** The wallet address. */
+    /** Solana wallet address (base58 public key). */
     address: string;
-    /** The payment method being used. */
-    method: "tempo";
-    /** Fetch a URL with automatic 402 payment handling. */
+    /** Network this client is connected to. */
+    network: SolanaNetwork;
+    /** Payment method. */
+    method: "solana";
+    /** Fetch a URL with automatic 402 MPP payment handling. */
     fetch: (url: string, init?: RequestInit) => Promise<Response>;
 }
 /**
- * Create an MPP test client.
+ * Create a Solana MPP test client.
  *
- * Auto-generates a wallet, funds it from the Tempo testnet faucet,
- * and handles 402 payments automatically.
+ * Automatically creates a Solana wallet, funds it (via airdrop on devnet/testnet),
+ * and handles HTTP 402 MPP payments with automatic retry.
  *
  * @example
  * ```ts
- * import { createTestClient } from "mpp-test-sdk";
- *
+ * // devnet (default) — zero config
  * const client = await createTestClient();
- * const res = await client.fetch("http://localhost:3001/api/ping/paid");
- * const data = await res.json();
+ *
+ * // testnet
+ * const client = await createTestClient({ network: "testnet" });
+ *
+ * // mainnet — must provide pre-funded wallet
+ * const client = await createTestClient({
+ *   network: "mainnet",
+ *   secretKey: loadKeypairFromFile("./wallet.json").secretKey,
+ * });
+ *
+ * const res = await client.fetch("http://localhost:3001/api/data");
  * ```
  *
- * @throws {MppFaucetError} When the testnet faucet is unreachable or returns an error.
+ * @throws {MppNetworkError} When `mainnet` is specified without a `secretKey`.
+ * @throws {MppFaucetError} When the devnet/testnet airdrop fails after retries.
  */
 declare function createTestClient(config?: TestClientConfig): Promise<TestClient>;
 /**
- * One-shot fetch with automatic wallet creation, funding, and 402 payment.
+ * Drop-in replacement for `fetch` with automatic Solana MPP payment.
  *
- * Uses a shared client instance across calls (lazy-initialized on first call).
- * Call `mppFetch.reset()` to discard the shared instance.
+ * Uses a shared client instance lazily created on first call (devnet by default).
+ * Call `mppFetch.reset()` to discard the shared instance and generate a new wallet.
  *
  * @example
  * ```ts
  * import { mppFetch } from "mpp-test-sdk";
  *
- * const res = await mppFetch("http://localhost:3001/api/ping/paid");
+ * const res = await mppFetch("http://localhost:3001/api/data");
  * const data = await res.json();
  * ```
  *
- * @throws {MppFaucetError} When the testnet faucet is unreachable.
- * @throws {MppTimeoutError} When the request times out.
+ * @throws {MppFaucetError} When the devnet airdrop fails after retries.
+ * @throws {MppTimeoutError} When the full flow exceeds the timeout.
  */
 declare function mppFetch(url: string, init?: RequestInit): Promise<Response>;
 declare namespace mppFetch {
@@ -64,23 +88,46 @@ declare namespace mppFetch {
 }
 
 interface ChargeOptions {
-    /** Amount to charge in PathUSD (e.g. "0.01"). */
+    /** Amount to charge in SOL (e.g. "0.001"). */
     amount: string;
 }
 interface MppServer {
-    /** Express middleware that charges the specified amount before passing through. */
+    /**
+     * Express middleware that requires SOL payment before passing to the route handler.
+     *
+     * - No receipt → 402 with `Payment-Request` header.
+     * - Valid receipt + on-chain confirmation → calls `next()`.
+     * - Invalid or insufficient payment → 403.
+     */
     charge: (opts: ChargeOptions) => RequestHandler;
+    /** The Solana address where payments are sent. */
+    recipientAddress: string;
+    /** Network this server is configured for. */
+    network: SolanaNetwork;
 }
 interface TestServerConfig {
-    /** Your MPP secret key. Required. */
-    secretKey: string;
-    /** Optional private key for the server wallet. Auto-generated if omitted. */
-    privateKey?: `0x${string}`;
-    /** Optional currency token address. Defaults to PathUSD on Tempo testnet. */
-    currency?: `0x${string}`;
+    /**
+     * Solana network to connect to.
+     * - `"devnet"` (default) — Solana devnet.
+     * - `"testnet"` — Solana testnet.
+     * - `"mainnet"` — Solana mainnet (real SOL).
+     */
+    network?: SolanaNetwork;
+    /** Server wallet keypair secret key. Auto-generated if omitted. */
+    secretKey?: Uint8Array;
+    /**
+     * Override the recipient Solana address (base58).
+     * Defaults to the server keypair's public key.
+     */
+    recipientAddress?: string;
+    /** Override the Solana RPC endpoint. Takes precedence over `network`. */
+    rpcUrl?: string;
 }
 /**
- * Create an MPP-enabled Express middleware.
+ * Create a Solana MPP-enabled Express server.
+ *
+ * Handles the HTTP 402 payment flow and verifies SOL transfers on-chain.
+ * No config needed — auto-generates a server wallet.
  *
  * @example
  * ```ts
@@ -88,11 +135,15 @@ interface TestServerConfig {
  * import { createTestServer } from "mpp-test-sdk";
  *
  * const app = express();
- * const mpp = createTestServer({ secretKey: "sk_test_..." });
- * app.get("/api/paid", mpp.charge({ amount: "0.01" }), (req, res) => res.json({ ok: true }));
+ * const mpp = createTestServer();  // or createTestServer({ network: "mainnet" })
+ *
+ * // Charge 0.001 SOL per request
+ * app.get("/api/data", mpp.charge({ amount: "0.001" }), (req, res) => {
+ *   res.json({ data: "premium content" });
+ * });
  * ```
  */
-declare function createTestServer(config: TestServerConfig): MppServer;
+declare function createTestServer(config?: TestServerConfig): MppServer;
 
 declare class MppError extends Error {
     constructor(message: string);
@@ -111,5 +162,9 @@ declare class MppTimeoutError extends MppError {
     readonly timeoutMs: number;
     constructor(url: string, timeoutMs: number);
 }
+declare class MppNetworkError extends MppError {
+    readonly network: string;
+    constructor(network: string, message?: string);
+}
 
-export { type ChargeOptions, MppError, MppFaucetError, MppPaymentError, type MppServer, MppTimeoutError, type PaymentStep, type TestClient, type TestClientConfig, type TestServerConfig, createTestClient, createTestServer, mppFetch };
+export { type ChargeOptions, MppError, MppFaucetError, MppNetworkError, MppPaymentError, type MppServer, MppTimeoutError, type PaymentStep, type SolanaNetwork, type TestClient, type TestClientConfig, type TestServerConfig, createTestClient, createTestServer, mppFetch };

package/dist/index.d.ts

@@ -1,62 +1,86 @@
 import { RequestHandler } from 'express';
 
+/** Solana network to connect to. */
+type SolanaNetwork = "devnet" | "testnet" | "mainnet";
 interface PaymentStep {
-    type: "wallet-created" | "funded" | "request" | "payment" | "success" | "error";
+    type: "wallet-created" | "funded" | "request" | "payment" | "retry" | "success" | "error";
     message: string;
     data?: Record<string, unknown>;
 }
 interface TestClientConfig {
-    /** Use a specific wallet. If omitted, a new wallet is auto-generated. */
-    privateKey?: `0x${string}`;
+    /**
+     * Solana network to connect to.
+     * - `"devnet"` (default) — Free SOL airdrop, fast confirmation.
+     * - `"testnet"` — Solana's testnet. Also has free airdrop.
+     * - `"mainnet"` — Real SOL. Requires a pre-funded `secretKey`.
+     */
+    network?: SolanaNetwork;
+    /**
+     * Pre-funded Solana keypair secret key (32 or 64 bytes).
+     * - On `devnet`/`testnet`: optional — wallet is auto-funded via airdrop.
+     * - On `mainnet`: **required** — no airdrop available.
+     */
+    secretKey?: Uint8Array;
     /** Lifecycle event callback for observing the payment flow. */
     onStep?: (step: PaymentStep) => void;
-    /** Request timeout in milliseconds. Default: 30000 (30s). */
+    /** Full flow timeout in ms (wallet + payment + retry). Default: 30000. */
     timeout?: number;
-    /** Maximum retry attempts for transient failures. Default: 1 (single 402 retry). */
-    maxRetries?: number;
+    /** Override the Solana RPC endpoint. Takes precedence over `network`. */
+    rpcUrl?: string;
 }
 interface TestClient {
-    /** The wallet address. */
+    /** Solana wallet address (base58 public key). */
     address: string;
-    /** The payment method being used. */
-    method: "tempo";
-    /** Fetch a URL with automatic 402 payment handling. */
+    /** Network this client is connected to. */
+    network: SolanaNetwork;
+    /** Payment method. */
+    method: "solana";
+    /** Fetch a URL with automatic 402 MPP payment handling. */
     fetch: (url: string, init?: RequestInit) => Promise<Response>;
 }
 /**
- * Create an MPP test client.
+ * Create a Solana MPP test client.
  *
- * Auto-generates a wallet, funds it from the Tempo testnet faucet,
- * and handles 402 payments automatically.
+ * Automatically creates a Solana wallet, funds it (via airdrop on devnet/testnet),
+ * and handles HTTP 402 MPP payments with automatic retry.
  *
  * @example
  * ```ts
- * import { createTestClient } from "mpp-test-sdk";
- *
+ * // devnet (default) — zero config
  * const client = await createTestClient();
- * const res = await client.fetch("http://localhost:3001/api/ping/paid");
- * const data = await res.json();
+ *
+ * // testnet
+ * const client = await createTestClient({ network: "testnet" });
+ *
+ * // mainnet — must provide pre-funded wallet
+ * const client = await createTestClient({
+ *   network: "mainnet",
+ *   secretKey: loadKeypairFromFile("./wallet.json").secretKey,
+ * });
+ *
+ * const res = await client.fetch("http://localhost:3001/api/data");
  * ```
  *
- * @throws {MppFaucetError} When the testnet faucet is unreachable or returns an error.
+ * @throws {MppNetworkError} When `mainnet` is specified without a `secretKey`.
+ * @throws {MppFaucetError} When the devnet/testnet airdrop fails after retries.
  */
 declare function createTestClient(config?: TestClientConfig): Promise<TestClient>;
 /**
- * One-shot fetch with automatic wallet creation, funding, and 402 payment.
+ * Drop-in replacement for `fetch` with automatic Solana MPP payment.
  *
- * Uses a shared client instance across calls (lazy-initialized on first call).
- * Call `mppFetch.reset()` to discard the shared instance.
+ * Uses a shared client instance lazily created on first call (devnet by default).
+ * Call `mppFetch.reset()` to discard the shared instance and generate a new wallet.
  *
  * @example
  * ```ts
  * import { mppFetch } from "mpp-test-sdk";
  *
- * const res = await mppFetch("http://localhost:3001/api/ping/paid");
+ * const res = await mppFetch("http://localhost:3001/api/data");
  * const data = await res.json();
  * ```
  *
- * @throws {MppFaucetError} When the testnet faucet is unreachable.
- * @throws {MppTimeoutError} When the request times out.
+ * @throws {MppFaucetError} When the devnet airdrop fails after retries.
+ * @throws {MppTimeoutError} When the full flow exceeds the timeout.
  */
 declare function mppFetch(url: string, init?: RequestInit): Promise<Response>;
 declare namespace mppFetch {
@@ -64,23 +88,46 @@ declare namespace mppFetch {
 }
 
 interface ChargeOptions {
-    /** Amount to charge in PathUSD (e.g. "0.01"). */
+    /** Amount to charge in SOL (e.g. "0.001"). */
     amount: string;
 }
 interface MppServer {
-    /** Express middleware that charges the specified amount before passing through. */
+    /**
+     * Express middleware that requires SOL payment before passing to the route handler.
+     *
+     * - No receipt → 402 with `Payment-Request` header.
+     * - Valid receipt + on-chain confirmation → calls `next()`.
+     * - Invalid or insufficient payment → 403.
+     */
     charge: (opts: ChargeOptions) => RequestHandler;
+    /** The Solana address where payments are sent. */
+    recipientAddress: string;
+    /** Network this server is configured for. */
+    network: SolanaNetwork;
 }
 interface TestServerConfig {
-    /** Your MPP secret key. Required. */
-    secretKey: string;
-    /** Optional private key for the server wallet. Auto-generated if omitted. */
-    privateKey?: `0x${string}`;
-    /** Optional currency token address. Defaults to PathUSD on Tempo testnet. */
-    currency?: `0x${string}`;
+    /**
+     * Solana network to connect to.
+     * - `"devnet"` (default) — Solana devnet.
+     * - `"testnet"` — Solana testnet.
+     * - `"mainnet"` — Solana mainnet (real SOL).
+     */
+    network?: SolanaNetwork;
+    /** Server wallet keypair secret key. Auto-generated if omitted. */
+    secretKey?: Uint8Array;
+    /**
+     * Override the recipient Solana address (base58).
+     * Defaults to the server keypair's public key.
+     */
+    recipientAddress?: string;
+    /** Override the Solana RPC endpoint. Takes precedence over `network`. */
+    rpcUrl?: string;
 }
 /**
- * Create an MPP-enabled Express middleware.
+ * Create a Solana MPP-enabled Express server.
+ *
+ * Handles the HTTP 402 payment flow and verifies SOL transfers on-chain.
+ * No config needed — auto-generates a server wallet.
  *
  * @example
  * ```ts
@@ -88,11 +135,15 @@ interface TestServerConfig {
  * import { createTestServer } from "mpp-test-sdk";
  *
  * const app = express();
- * const mpp = createTestServer({ secretKey: "sk_test_..." });
- * app.get("/api/paid", mpp.charge({ amount: "0.01" }), (req, res) => res.json({ ok: true }));
+ * const mpp = createTestServer();  // or createTestServer({ network: "mainnet" })
+ *
+ * // Charge 0.001 SOL per request
+ * app.get("/api/data", mpp.charge({ amount: "0.001" }), (req, res) => {
+ *   res.json({ data: "premium content" });
+ * });
  * ```
  */
-declare function createTestServer(config: TestServerConfig): MppServer;
+declare function createTestServer(config?: TestServerConfig): MppServer;
 
 declare class MppError extends Error {
     constructor(message: string);
@@ -111,5 +162,9 @@ declare class MppTimeoutError extends MppError {
     readonly timeoutMs: number;
     constructor(url: string, timeoutMs: number);
 }
+declare class MppNetworkError extends MppError {
+    readonly network: string;
+    constructor(network: string, message?: string);
+}
 
-export { type ChargeOptions, MppError, MppFaucetError, MppPaymentError, type MppServer, MppTimeoutError, type PaymentStep, type TestClient, type TestClientConfig, type TestServerConfig, createTestClient, createTestServer, mppFetch };
+export { type ChargeOptions, MppError, MppFaucetError, MppNetworkError, MppPaymentError, type MppServer, MppTimeoutError, type PaymentStep, type SolanaNetwork, type TestClient, type TestClientConfig, type TestServerConfig, createTestClient, createTestServer, mppFetch };