@alleyboss/micropay-solana-x402-paywall 3.5.0 → 3.5.1

package/README.md

@@ -298,6 +298,25 @@ flowchart LR
     F --> G((Unlock Data))
 ```
 
+### ⚡ The Sexy Way (New in v3.5.1)
+
+```typescript
+import { createPayingAgent } from '@alleyboss/micropay-solana-x402-paywall/agent';
+
+// One liner - that's it!
+const agent = createPayingAgent(process.env.SOLANA_PRIVATE_KEY!);
+
+// Fetch with auto-payment
+const response = await agent.get('https://api.example.com/premium');
+const data = await response.json();
+
+// Check balance
+const { sol } = await agent.getBalance();
+console.log(`Agent has ${sol} SOL`);
+```
+
+### The Verbose Way (Full Control)
+
 ```typescript
 import { executeAgentPayment } from '@alleyboss/micropay-solana-x402-paywall/agent';
 import { Keypair, Connection } from '@solana/web3.js';

package/dist/agent/index.cjs

@@ -351,8 +351,440 @@ async function getRemainingCredits(token, secret) {
   };
 }
 
+// src/fetch/types.ts
+var X402ErrorCode = {
+  /** User rejected the payment */
+  USER_REJECTED: "USER_REJECTED",
+  /** Insufficient wallet balance */
+  INSUFFICIENT_BALANCE: "INSUFFICIENT_BALANCE",
+  /** Transaction failed on-chain */
+  TRANSACTION_FAILED: "TRANSACTION_FAILED",
+  /** Network/RPC error */
+  NETWORK_ERROR: "NETWORK_ERROR",
+  /** Invalid 402 response format */
+  INVALID_402_RESPONSE: "INVALID_402_RESPONSE",
+  /** Payment timeout */
+  TIMEOUT: "TIMEOUT",
+  /** Wallet not connected */
+  WALLET_NOT_CONNECTED: "WALLET_NOT_CONNECTED",
+  /** Payment amount exceeds maxPaymentPerRequest */
+  AMOUNT_EXCEEDS_LIMIT: "AMOUNT_EXCEEDS_LIMIT",
+  /** Recipient address not in allowedRecipients whitelist */
+  RECIPIENT_NOT_ALLOWED: "RECIPIENT_NOT_ALLOWED",
+  /** Rate limit exceeded */
+  RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED"
+};
+
+// src/fetch/errors.ts
+var X402PaymentError = class _X402PaymentError extends Error {
+  constructor(message, code, requirements, cause) {
+    super(message);
+    this.code = code;
+    this.requirements = requirements;
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _X402PaymentError);
+    }
+  }
+  name = "X402PaymentError";
+  /**
+   * Check if error is retryable
+   */
+  get isRetryable() {
+    const retryableCodes = [
+      X402ErrorCode.NETWORK_ERROR,
+      X402ErrorCode.TIMEOUT,
+      X402ErrorCode.TRANSACTION_FAILED
+    ];
+    return retryableCodes.includes(this.code);
+  }
+  /**
+   * Convert to JSON-serializable object
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      requirements: this.requirements,
+      isRetryable: this.isRetryable
+    };
+  }
+};
+function userRejectedError(requirements) {
+  return new X402PaymentError(
+    "User rejected the payment request",
+    X402ErrorCode.USER_REJECTED,
+    requirements
+  );
+}
+function insufficientBalanceError(requirements, balance) {
+  return new X402PaymentError(
+    `Insufficient balance: have ${balance} lamports, need ${requirements.amount}`,
+    X402ErrorCode.INSUFFICIENT_BALANCE,
+    requirements
+  );
+}
+function transactionFailedError(requirements, cause) {
+  return new X402PaymentError(
+    `Transaction failed: ${cause?.message ?? "Unknown error"}`,
+    X402ErrorCode.TRANSACTION_FAILED,
+    requirements,
+    cause
+  );
+}
+function networkError(cause) {
+  return new X402PaymentError(
+    `Network error: ${cause?.message ?? "Connection failed"}`,
+    X402ErrorCode.NETWORK_ERROR,
+    void 0,
+    cause
+  );
+}
+function invalid402ResponseError(details) {
+  return new X402PaymentError(
+    `Invalid 402 response: ${details ?? "Missing or malformed payment requirements"}`,
+    X402ErrorCode.INVALID_402_RESPONSE
+  );
+}
+function timeoutError(requirements) {
+  return new X402PaymentError(
+    "Payment flow timed out",
+    X402ErrorCode.TIMEOUT,
+    requirements
+  );
+}
+function walletNotConnectedError() {
+  return new X402PaymentError(
+    "Wallet is not connected",
+    X402ErrorCode.WALLET_NOT_CONNECTED
+  );
+}
+function amountExceedsLimitError(requirements, limit) {
+  return new X402PaymentError(
+    `Payment amount ${requirements.amount} exceeds limit of ${limit} lamports`,
+    X402ErrorCode.AMOUNT_EXCEEDS_LIMIT,
+    requirements
+  );
+}
+function recipientNotAllowedError(requirements, recipient) {
+  return new X402PaymentError(
+    `Recipient ${recipient} is not in the allowed recipients list`,
+    X402ErrorCode.RECIPIENT_NOT_ALLOWED,
+    requirements
+  );
+}
+function rateLimitExceededError(limit, windowMs) {
+  return new X402PaymentError(
+    `Rate limit exceeded: max ${limit} payments per ${windowMs / 1e3}s`,
+    X402ErrorCode.RATE_LIMIT_EXCEEDED
+  );
+}
+
+// src/shared/constants.ts
+var RPC_ENDPOINTS = {
+  "mainnet-beta": "https://api.mainnet-beta.solana.com",
+  "devnet": "https://api.devnet.solana.com",
+  "testnet": "https://api.testnet.solana.com"
+};
+var DEFAULT_CONFIRMATION_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_RATE_LIMIT_WINDOW_MS = 6e4;
+var DEFAULT_RATE_LIMIT_MAX_PAYMENTS = 10;
+
+// src/fetch/x402Fetch.ts
+function isKeypair(wallet) {
+  return wallet instanceof web3_js.Keypair;
+}
+function isWalletConnected(wallet) {
+  if (isKeypair(wallet)) return true;
+  return wallet.connected && wallet.publicKey != null;
+}
+function getPublicKey(wallet) {
+  if (isKeypair(wallet)) return wallet.publicKey;
+  if (!wallet.publicKey) throw walletNotConnectedError();
+  return wallet.publicKey;
+}
+function parse402Response(response) {
+  const x402Header = response.headers.get("X-Payment-Requirements");
+  if (x402Header) {
+    try {
+      const parsed = JSON.parse(x402Header);
+      return {
+        payTo: parsed.payTo ?? parsed.recipient,
+        amount: String(parsed.amount),
+        asset: parsed.asset ?? "SOL",
+        network: parsed.network ?? "solana-mainnet",
+        description: parsed.description,
+        resource: parsed.resource,
+        maxAge: parsed.maxAge
+      };
+    } catch {
+      throw invalid402ResponseError("Invalid X-Payment-Requirements header");
+    }
+  }
+  const wwwAuth = response.headers.get("WWW-Authenticate");
+  if (wwwAuth?.startsWith("X402")) {
+    try {
+      const base64Part = wwwAuth.slice(5).trim();
+      const jsonStr = atob(base64Part);
+      const parsed = JSON.parse(jsonStr);
+      return {
+        payTo: parsed.payTo ?? parsed.recipient,
+        amount: String(parsed.amount),
+        asset: parsed.asset ?? "SOL",
+        network: parsed.network ?? "solana-mainnet",
+        description: parsed.description,
+        resource: parsed.resource,
+        maxAge: parsed.maxAge
+      };
+    } catch {
+      throw invalid402ResponseError("Invalid WWW-Authenticate header");
+    }
+  }
+  throw invalid402ResponseError("No payment requirements found in 402 response");
+}
+function buildPaymentHeader(signature) {
+  const payload = {
+    x402Version: 2,
+    scheme: "exact",
+    payload: { signature }
+  };
+  return `X402 ${btoa(JSON.stringify(payload))}`;
+}
+function createX402Fetch(config) {
+  const {
+    wallet,
+    network = "mainnet-beta",
+    connection: providedConnection,
+    // Reserved for future facilitator integration
+    onPaymentRequired,
+    onPaymentSuccess,
+    onPaymentError,
+    priorityFee,
+    maxRetries = DEFAULT_MAX_RETRIES,
+    timeout = DEFAULT_CONFIRMATION_TIMEOUT,
+    // Security options
+    maxPaymentPerRequest,
+    allowedRecipients,
+    // UX options
+    commitment = "confirmed",
+    rateLimit
+  } = config;
+  const paymentTimestamps = [];
+  const rateLimitMax = rateLimit?.maxPayments ?? DEFAULT_RATE_LIMIT_MAX_PAYMENTS;
+  const rateLimitWindow = rateLimit?.windowMs ?? DEFAULT_RATE_LIMIT_WINDOW_MS;
+  function checkRateLimit() {
+    const now = Date.now();
+    while (paymentTimestamps.length > 0 && paymentTimestamps[0] < now - rateLimitWindow) {
+      paymentTimestamps.shift();
+    }
+    if (paymentTimestamps.length >= rateLimitMax) {
+      throw rateLimitExceededError(rateLimitMax, rateLimitWindow);
+    }
+  }
+  function recordPayment() {
+    paymentTimestamps.push(Date.now());
+  }
+  function validateSecurityRequirements(requirements) {
+    const amountLamports = BigInt(requirements.amount);
+    if (maxPaymentPerRequest !== void 0 && amountLamports > maxPaymentPerRequest) {
+      throw amountExceedsLimitError(requirements, maxPaymentPerRequest);
+    }
+    if (allowedRecipients !== void 0 && allowedRecipients.length > 0) {
+      if (!allowedRecipients.includes(requirements.payTo)) {
+        throw recipientNotAllowedError(requirements, requirements.payTo);
+      }
+    }
+  }
+  const connection = providedConnection ?? new web3_js.Connection(RPC_ENDPOINTS[network], {
+    commitment
+  });
+  async function executePayment(requirements) {
+    const payer = getPublicKey(wallet);
+    const recipient = new web3_js.PublicKey(requirements.payTo);
+    const amountLamports = BigInt(requirements.amount);
+    const balance = await connection.getBalance(payer);
+    if (BigInt(balance) < amountLamports) {
+      throw insufficientBalanceError(requirements, BigInt(balance));
+    }
+    const instructions = [];
+    if (priorityFee?.enabled) {
+      instructions.push(
+        web3_js.ComputeBudgetProgram.setComputeUnitPrice({
+          microLamports: priorityFee.microLamports ?? 5e3
+        })
+      );
+    }
+    instructions.push(
+      web3_js.SystemProgram.transfer({
+        fromPubkey: payer,
+        toPubkey: recipient,
+        lamports: amountLamports
+      })
+    );
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();
+    const messageV0 = new web3_js.TransactionMessage({
+      payerKey: payer,
+      recentBlockhash: blockhash,
+      instructions
+    }).compileToV0Message();
+    const tx = new web3_js.VersionedTransaction(messageV0);
+    if (isKeypair(wallet)) {
+      tx.sign([wallet]);
+    } else {
+      const signerWallet = wallet;
+      if (!signerWallet.signTransaction) {
+        throw new X402PaymentError(
+          "Wallet does not support transaction signing. Use a SignerWalletAdapter.",
+          "WALLET_NOT_CONNECTED"
+        );
+      }
+      const signedTx = await signerWallet.signTransaction(tx);
+      if (signedTx.signatures[0]) {
+        tx.signatures[0] = signedTx.signatures[0];
+      }
+    }
+    const signature = await connection.sendTransaction(tx, {
+      maxRetries
+    });
+    await connection.confirmTransaction({
+      signature,
+      blockhash,
+      lastValidBlockHeight
+    }, commitment);
+    return signature;
+  }
+  async function x402Fetch(input, init) {
+    const { skipPayment, paymentOverride, ...fetchInit } = init ?? {};
+    let response;
+    try {
+      response = await fetch(input, fetchInit);
+    } catch (error) {
+      throw networkError(error instanceof Error ? error : void 0);
+    }
+    if (response.status !== 402) {
+      return response;
+    }
+    if (skipPayment) {
+      return response;
+    }
+    if (!isWalletConnected(wallet)) {
+      throw walletNotConnectedError();
+    }
+    let requirements;
+    try {
+      requirements = parse402Response(response);
+      if (paymentOverride) {
+        requirements = { ...requirements, ...paymentOverride };
+      }
+    } catch (error) {
+      if (error instanceof X402PaymentError) throw error;
+      throw invalid402ResponseError(error instanceof Error ? error.message : void 0);
+    }
+    validateSecurityRequirements(requirements);
+    checkRateLimit();
+    if (onPaymentRequired) {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      const shouldProceed = await onPaymentRequired(requirements, url);
+      if (!shouldProceed) {
+        throw userRejectedError(requirements);
+      }
+    }
+    let signature;
+    try {
+      const paymentPromise = executePayment(requirements);
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(timeoutError(requirements)), timeout);
+      });
+      signature = await Promise.race([paymentPromise, timeoutPromise]);
+      recordPayment();
+      if (onPaymentSuccess) {
+        await onPaymentSuccess(signature, requirements);
+      }
+    } catch (error) {
+      if (error instanceof X402PaymentError) {
+        if (onPaymentError) {
+          await onPaymentError(error, requirements);
+        }
+        throw error;
+      }
+      const wrappedError = transactionFailedError(
+        requirements,
+        error instanceof Error ? error : void 0
+      );
+      if (onPaymentError) {
+        await onPaymentError(wrappedError, requirements);
+      }
+      throw wrappedError;
+    }
+    const retryHeaders = new Headers(fetchInit?.headers);
+    retryHeaders.set("Authorization", buildPaymentHeader(signature));
+    try {
+      return await fetch(input, {
+        ...fetchInit,
+        headers: retryHeaders
+      });
+    } catch (error) {
+      throw networkError(error instanceof Error ? error : void 0);
+    }
+  }
+  return x402Fetch;
+}
+
+// src/agent/payingAgent.ts
+function createPayingAgent(privateKey, config = {}) {
+  const {
+    network = "mainnet-beta",
+    rpcUrl,
+    maxPaymentPerRequest,
+    allowedRecipients,
+    priorityFee = true
+  } = config;
+  let keypair;
+  if (privateKey.includes(",")) {
+    const bytes = new Uint8Array(privateKey.split(",").map((n) => parseInt(n.trim(), 10)));
+    keypair = web3_js.Keypair.fromSecretKey(bytes);
+  } else {
+    keypair = web3_js.Keypair.fromSecretKey(bs58__default.default.decode(privateKey));
+  }
+  const endpoint = rpcUrl ?? RPC_ENDPOINTS[network];
+  const connection = new web3_js.Connection(endpoint, "confirmed");
+  const fetchConfig = {
+    wallet: keypair,
+    network,
+    connection,
+    maxPaymentPerRequest,
+    allowedRecipients,
+    priorityFee: priorityFee ? { enabled: true, microLamports: 5e3 } : void 0
+  };
+  const x402Fetch = createX402Fetch(fetchConfig);
+  return {
+    get: (url, init) => x402Fetch(url, { ...init, method: "GET" }),
+    post: (url, body, init) => x402Fetch(url, {
+      ...init,
+      method: "POST",
+      body: JSON.stringify(body),
+      headers: {
+        "Content-Type": "application/json",
+        ...init?.headers
+      }
+    }),
+    fetch: (url, init) => x402Fetch(url, init),
+    publicKey: keypair.publicKey.toBase58(),
+    getBalance: async () => {
+      const lamports = await connection.getBalance(keypair.publicKey);
+      return {
+        lamports: BigInt(lamports),
+        sol: lamports / 1e9
+      };
+    }
+  };
+}
+
 exports.addCredits = addCredits;
 exports.createCreditSession = createCreditSession;
+exports.createPayingAgent = createPayingAgent;
 exports.executeAgentPayment = executeAgentPayment;
 exports.generateAgentKeypair = generateAgentKeypair;
 exports.getAgentBalance = getAgentBalance;

package/dist/agent/index.d.cts

@@ -218,4 +218,80 @@ declare function getRemainingCredits(token: string, secret: string): Promise<{
     bundleExpiry?: number;
 }>;
 
-export { type AgentPaymentResult, type CreditSessionClaims, type CreditSessionConfig, type CreditSessionData, type CreditValidation, type ExecuteAgentPaymentParams, type UseCreditResult, addCredits, createCreditSession, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession };
+/**
+ * Supported Solana networks
+ */
+declare const SOLANA_NETWORKS: readonly ["mainnet-beta", "devnet", "testnet"];
+type SolanaNetwork = (typeof SOLANA_NETWORKS)[number];
+
+/**
+ * @fileoverview Shaw-style Agent Helper
+ * The sexiest way to create a paying AI agent
+ *
+ * @example
+ * ```typescript
+ * import { createPayingAgent } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ *
+ * const agent = createPayingAgent(process.env.SOLANA_PRIVATE_KEY!);
+ * const data = await agent.get('https://api.example.com/premium');
+ * ```
+ */
+
+/**
+ * Configuration for creating a paying agent
+ */
+interface PayingAgentConfig {
+    /** Network: 'mainnet-beta' | 'devnet' | 'testnet' */
+    network?: SolanaNetwork;
+    /** Custom RPC URL */
+    rpcUrl?: string;
+    /** Max payment per request in lamports (safety limit) */
+    maxPaymentPerRequest?: bigint;
+    /** Allowed recipient addresses (whitelist) */
+    allowedRecipients?: string[];
+    /** Enable priority fees for faster confirmation */
+    priorityFee?: boolean;
+}
+/**
+ * Paying agent interface - fetch-like methods with auto-payment
+ */
+interface PayingAgent {
+    /** GET request with auto-payment */
+    get: (url: string, init?: RequestInit) => Promise<Response>;
+    /** POST request with auto-payment */
+    post: (url: string, body: unknown, init?: RequestInit) => Promise<Response>;
+    /** Generic fetch with auto-payment */
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Get the agent's public key */
+    publicKey: string;
+    /** Get the agent's balance */
+    getBalance: () => Promise<{
+        lamports: bigint;
+        sol: number;
+    }>;
+}
+/**
+ * Create a paying AI agent - the sexiest one-liner for agent developers
+ *
+ * @param privateKey - Base58 or comma-separated Uint8Array string
+ * @param config - Optional configuration
+ * @returns PayingAgent with fetch-like methods
+ *
+ * @example
+ * ```typescript
+ * const agent = createPayingAgent(process.env.SOLANA_PRIVATE_KEY!);
+ *
+ * // Simple GET
+ * const response = await agent.get('https://api.example.com/premium');
+ *
+ * // POST with body
+ * const result = await agent.post('https://api.example.com/ai', { prompt: 'Hello' });
+ *
+ * // Check balance
+ * const { sol } = await agent.getBalance();
+ * console.log(`Agent has ${sol} SOL`);
+ * ```
+ */
+declare function createPayingAgent(privateKey: string, config?: PayingAgentConfig): PayingAgent;
+
+export { type AgentPaymentResult, type CreditSessionClaims, type CreditSessionConfig, type CreditSessionData, type CreditValidation, type ExecuteAgentPaymentParams, type PayingAgent, type PayingAgentConfig, type UseCreditResult, addCredits, createCreditSession, createPayingAgent, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession };

package/dist/agent/index.d.ts

@@ -218,4 +218,80 @@ declare function getRemainingCredits(token: string, secret: string): Promise<{
     bundleExpiry?: number;
 }>;
 
-export { type AgentPaymentResult, type CreditSessionClaims, type CreditSessionConfig, type CreditSessionData, type CreditValidation, type ExecuteAgentPaymentParams, type UseCreditResult, addCredits, createCreditSession, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession };
+/**
+ * Supported Solana networks
+ */
+declare const SOLANA_NETWORKS: readonly ["mainnet-beta", "devnet", "testnet"];
+type SolanaNetwork = (typeof SOLANA_NETWORKS)[number];
+
+/**
+ * @fileoverview Shaw-style Agent Helper
+ * The sexiest way to create a paying AI agent
+ *
+ * @example
+ * ```typescript
+ * import { createPayingAgent } from '@alleyboss/micropay-solana-x402-paywall/agent';
+ *
+ * const agent = createPayingAgent(process.env.SOLANA_PRIVATE_KEY!);
+ * const data = await agent.get('https://api.example.com/premium');
+ * ```
+ */
+
+/**
+ * Configuration for creating a paying agent
+ */
+interface PayingAgentConfig {
+    /** Network: 'mainnet-beta' | 'devnet' | 'testnet' */
+    network?: SolanaNetwork;
+    /** Custom RPC URL */
+    rpcUrl?: string;
+    /** Max payment per request in lamports (safety limit) */
+    maxPaymentPerRequest?: bigint;
+    /** Allowed recipient addresses (whitelist) */
+    allowedRecipients?: string[];
+    /** Enable priority fees for faster confirmation */
+    priorityFee?: boolean;
+}
+/**
+ * Paying agent interface - fetch-like methods with auto-payment
+ */
+interface PayingAgent {
+    /** GET request with auto-payment */
+    get: (url: string, init?: RequestInit) => Promise<Response>;
+    /** POST request with auto-payment */
+    post: (url: string, body: unknown, init?: RequestInit) => Promise<Response>;
+    /** Generic fetch with auto-payment */
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Get the agent's public key */
+    publicKey: string;
+    /** Get the agent's balance */
+    getBalance: () => Promise<{
+        lamports: bigint;
+        sol: number;
+    }>;
+}
+/**
+ * Create a paying AI agent - the sexiest one-liner for agent developers
+ *
+ * @param privateKey - Base58 or comma-separated Uint8Array string
+ * @param config - Optional configuration
+ * @returns PayingAgent with fetch-like methods
+ *
+ * @example
+ * ```typescript
+ * const agent = createPayingAgent(process.env.SOLANA_PRIVATE_KEY!);
+ *
+ * // Simple GET
+ * const response = await agent.get('https://api.example.com/premium');
+ *
+ * // POST with body
+ * const result = await agent.post('https://api.example.com/ai', { prompt: 'Hello' });
+ *
+ * // Check balance
+ * const { sol } = await agent.getBalance();
+ * console.log(`Agent has ${sol} SOL`);
+ * ```
+ */
+declare function createPayingAgent(privateKey: string, config?: PayingAgentConfig): PayingAgent;
+
+export { type AgentPaymentResult, type CreditSessionClaims, type CreditSessionConfig, type CreditSessionData, type CreditValidation, type ExecuteAgentPaymentParams, type PayingAgent, type PayingAgentConfig, type UseCreditResult, addCredits, createCreditSession, createPayingAgent, executeAgentPayment, generateAgentKeypair, getAgentBalance, getRemainingCredits, hasAgentSufficientBalance, keypairFromBase58, useCredit, validateCreditSession };