@alleyboss/micropay-solana-x402-paywall 1.0.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @alleyboss/micropay-solana-x402-paywall
 
-> Solana micropayments library implementing the x402 protocol for content paywalls.
+> Production-ready Solana micropayments library implementing the x402 protocol with SPL token support.
 
 [![npm version](https://img.shields.io/npm/v/@alleyboss/micropay-solana-x402-paywall)](https://www.npmjs.com/package/@alleyboss/micropay-solana-x402-paywall)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
@@ -8,10 +8,12 @@
 ## Features
 
 - 🔐 **x402 Protocol** — HTTP 402 Payment Required standard
-- ⚡ **Solana Native** — Fast, low-cost SOL micropayments
-- 🔑 **JWT Sessions** — Secure unlock tracking
-- 📦 **Framework Agnostic** — Works with Next.js, Express, or any Node.js project
-- 🌳 **Tree-shakeable** — Import only what you need
+- ⚡ **Solana Native** — Fast, low-cost SOL & USDC micropayments
+- 🔑 **JWT Sessions** — Secure unlock tracking with anti-replay
+- 📦 **Framework Agnostic** — Express, Next.js, Fastify ready
+- 🌳 **Tree-shakeable** — Import only what you need (35KB full, 1-13KB per module)
+- 💰 **SPL Tokens** — USDC, USDT, and custom token support
+- 🔄 **Retry Logic** — Built-in resilience for RPC failures
 
 ## Installation
 
@@ -21,212 +23,143 @@ npm install @alleyboss/micropay-solana-x402-paywall @solana/web3.js
 
 ## Quick Start
 
-### 1. Verify a Payment
+### Verify a Payment (SOL or USDC)
 
 ```typescript
-import { verifyPayment, type SolanaClientConfig } from '@alleyboss/micropay-solana-x402-paywall';
-
-const clientConfig: SolanaClientConfig = {
-  network: 'devnet',
-  tatumApiKey: 'your-tatum-api-key', // Optional: for better RPC
-};
+import { verifyPayment, verifySPLPayment } from '@alleyboss/micropay-solana-x402-paywall';
 
+// SOL payment
 const result = await verifyPayment({
-  signature: 'abc123...',
-  expectedRecipient: 'CreatorWalletAddress',
-  expectedAmount: BigInt(10000000), // 0.01 SOL
-  clientConfig,
+  signature: 'tx...',
+  expectedRecipient: 'CreatorWallet',
+  expectedAmount: 10_000_000n, // 0.01 SOL
+  clientConfig: { network: 'devnet' },
 });
 
-if (result.valid) {
-  console.log('Payment verified!', result.from, 'paid', result.amount);
-}
+// USDC payment
+const usdcResult = await verifySPLPayment({
+  signature: 'tx...',
+  expectedRecipient: 'CreatorWallet',
+  expectedAmount: 1_000_000n, // 1 USDC
+  asset: 'usdc',
+  clientConfig: { network: 'mainnet-beta' },
+});
 ```
 
-### 2. Create Session After Payment
+### Express Middleware (Zero Boilerplate)
 
 ```typescript
-import { createSession, validateSession } from '@alleyboss/micropay-solana-x402-paywall';
+import express from 'express';
+import { createExpressMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
 
-const sessionConfig = {
-  durationHours: 24,
-  secret: 'your-32-character-minimum-secret-key',
-};
+const app = express();
 
-// After payment verification
-const { token, session } = await createSession(
-  'UserWalletAddress',
-  'article-123',
-  sessionConfig
-);
-
-// Later, validate the session
-const validation = await validateSession(token, sessionConfig.secret);
-if (validation.valid) {
-  console.log('Session valid until', new Date(validation.session!.expiresAt * 1000));
-}
+app.use('/api/premium', createExpressMiddleware({
+  sessionSecret: process.env.SESSION_SECRET!,
+  protectedPaths: ['/**'],
+}));
+
+app.get('/api/premium/content', (req, res) => {
+  res.json({ content: 'Premium!', wallet: req.session?.walletAddress });
+});
 ```
 
-### 3. Build x402 Payment Requirement
+### Next.js Middleware
 
 ```typescript
-import { buildPaymentRequirement, create402Headers } from '@alleyboss/micropay-solana-x402-paywall';
-
-const requirement = buildPaymentRequirement({
-  articleId: 'article-123',
-  articleTitle: 'Premium Article',
-  priceInLamports: BigInt(10000000),
-  creatorWallet: 'CreatorWalletAddress',
-  resourceUrl: 'https://example.com/article/123',
-  network: 'devnet',
+// middleware.ts
+import { createPaywallMiddleware } from '@alleyboss/micropay-solana-x402-paywall/middleware';
+
+export const middleware = createPaywallMiddleware({
+  sessionSecret: process.env.SESSION_SECRET!,
+  protectedPaths: ['/api/premium/*', '/api/content/*'],
 });
 
-// Use in HTTP response
-const headers = create402Headers(requirement);
+export const config = { matcher: ['/api/premium/:path*'] };
 ```
 
-## API Reference
-
-### Solana Module
+### Prevent Signature Replay (Anti-Double-Spend)
 
 ```typescript
-import { 
-  getConnection,
-  verifyPayment,
-  waitForConfirmation,
-  lamportsToSol,
-  solToLamports 
-} from '@alleyboss/micropay-solana-x402-paywall/solana';
-```
+import { createMemoryStore, createRedisStore } from '@alleyboss/micropay-solana-x402-paywall/store';
 
-| Function | Description |
-|----------|-------------|
-| `getConnection(config)` | Get/create Solana RPC connection |
-| `verifyPayment(params)` | Verify on-chain SOL transfer |
-| `waitForConfirmation(sig, config)` | Wait for transaction confirmation |
-| `lamportsToSol(lamports)` | Convert lamports to SOL |
-| `solToLamports(sol)` | Convert SOL to lamports |
+// Development
+const store = createMemoryStore();
 
-### Session Module
+// Production (with ioredis or node-redis)
+const store = createRedisStore({ client: redisClient });
 
-```typescript
-import { 
-  createSession,
-  validateSession,
-  addArticleToSession,
-  isArticleUnlocked 
-} from '@alleyboss/micropay-solana-x402-paywall/session';
-```
+// Check before verification
+if (await store.hasBeenUsed(signature)) {
+  throw new Error('Payment already used');
+}
 
-| Function | Description |
-|----------|-------------|
-| `createSession(wallet, articleId, config)` | Create JWT session token |
-| `validateSession(token, secret)` | Validate and decode session |
-| `addArticleToSession(token, articleId, secret)` | Add article to existing session |
-| `isArticleUnlocked(token, articleId, secret)` | Check if article is unlocked |
+// Mark after successful verification
+await store.markAsUsed(signature, articleId, new Date(Date.now() + 86400000));
+```
 
-### x402 Module
+### Client-Side Payment Flow
 
 ```typescript
-import { 
-  buildPaymentRequirement,
-  verifyX402Payment,
-  parsePaymentHeader,
-  X402_HEADERS 
-} from '@alleyboss/micropay-solana-x402-paywall/x402';
-```
+import { createPaymentFlow, formatPriceDisplay } from '@alleyboss/micropay-solana-x402-paywall';
 
-| Function | Description |
-|----------|-------------|
-| `buildPaymentRequirement(params)` | Build x402 payment requirement |
-| `verifyX402Payment(payload, requirement, config)` | Verify x402 payment |
-| `parsePaymentHeader(header)` | Parse base64 payment header |
-| `encodePaymentRequired(requirement)` | Encode requirement for header |
+const flow = createPaymentFlow({
+  network: 'mainnet-beta',
+  recipientWallet: 'CreatorWallet',
+  amount: 10_000_000n,
+});
 
-## Next.js Integration Example
+// Generate QR code for mobile wallets
+const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });
 
-```typescript
-// app/api/payment/verify/route.ts
-import { 
-  verifyX402Payment,
-  createSession,
-  parsePaymentHeader,
-  decodePaymentRequired 
-} from '@alleyboss/micropay-solana-x402-paywall';
-import { cookies } from 'next/headers';
-
-export async function POST(request: Request) {
-  const { signature, articleId } = await request.json();
-  
-  const clientConfig = {
-    network: process.env.SOLANA_NETWORK as 'devnet' | 'mainnet-beta',
-    tatumApiKey: process.env.TATUM_API_KEY,
-  };
-
-  const sessionConfig = {
-    durationHours: 24,
-    secret: process.env.SESSION_SECRET!,
-  };
-
-  // Build requirement for the article
-  const requirement = buildPaymentRequirement({
-    articleId,
-    articleTitle: 'Article Title',
-    priceInLamports: BigInt(process.env.ARTICLE_PRICE || '10000000'),
-    creatorWallet: process.env.CREATOR_WALLET!,
-    resourceUrl: `${process.env.SITE_URL}/article/${articleId}`,
-    network: clientConfig.network,
-  });
-
-  // Verify payment
-  const payload = {
-    x402Version: 1,
-    scheme: 'exact' as const,
-    network: requirement.network,
-    payload: { signature },
-  };
-
-  const result = await verifyX402Payment(payload, requirement, clientConfig);
-
-  if (!result.valid) {
-    return Response.json({ error: result.invalidReason }, { status: 400 });
-  }
-
-  // Create session
-  const { token } = await createSession(
-    result.transaction!.signature, 
-    articleId, 
-    sessionConfig
-  );
-
-  // Set cookie
-  const cookieStore = await cookies();
-  cookieStore.set('x402_session', token, {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === 'production',
-    sameSite: 'strict',
-    maxAge: sessionConfig.durationHours * 3600,
-  });
-
-  return Response.json({ success: true });
-}
+// Display price with USD equivalent
+const price = await formatPriceDisplay(10_000_000n);
+// "0.0100 SOL (~$1.50)"
 ```
 
+## Module Exports
+
+Import only what you need for minimal bundle size:
+
+| Import Path | Size | Functions |
+|-------------|------|-----------|
+| `@.../solana` | 13KB | `verifyPayment`, `verifySPLPayment`, `getConnection` |
+| `@.../session` | 4.5KB | `createSession`, `validateSession`, `isArticleUnlocked` |
+| `@.../x402` | 10KB | `buildPaymentRequirement`, `verifyX402Payment` |
+| `@.../middleware` | 8KB | `createExpressMiddleware`, `createPaywallMiddleware` |
+| `@.../store` | 2.6KB | `createMemoryStore`, `createRedisStore` |
+| `@.../client` | 3.3KB | `createPaymentFlow`, `buildSolanaPayUrl` |
+| `@.../pricing` | 2KB | `getSolPrice`, `formatPriceDisplay` |
+| `@.../utils` | 1.7KB | `withRetry`, `isRetryableRPCError` |
+
 ## TypeScript Support
 
-Full TypeScript support with exported types:
+Full TypeScript with exported types:
 
 ```typescript
 import type {
   PaymentRequirement,
-  PaymentPayload,
-  VerificationResponse,
+  PaymentAsset,
   SessionData,
-  SessionConfig,
-  SolanaClientConfig,
+  SignatureStore,
+  PaywallMiddlewareConfig,
 } from '@alleyboss/micropay-solana-x402-paywall';
 ```
 
+## RPC Configuration
+
+Supports multiple RPC providers:
+
+```typescript
+const clientConfig = {
+  network: 'mainnet-beta',
+  // Option 1: Tatum.io
+  tatumApiKey: 'your-api-key',
+  // Option 2: Custom RPC (Helius, QuickNode, etc.)
+  rpcUrl: 'https://your-rpc-endpoint.com',
+};
+```
+
 ## License
 
 MIT © AlleyBoss

package/dist/client/index.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+// src/types/payment.ts
+var TOKEN_MINTS = {
+  /** USDC on mainnet */
+  USDC_MAINNET: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  /** USDC on devnet */
+  USDC_DEVNET: "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+  /** USDT on mainnet */
+  USDT_MAINNET: "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"
+};
+
+// src/client/payment.ts
+function buildSolanaPayUrl(params) {
+  const { recipient, amount, splToken, reference, label, message } = params;
+  const url = new URL(`solana:${recipient}`);
+  if (amount !== void 0) {
+    url.searchParams.set("amount", amount.toString());
+  }
+  if (splToken) {
+    url.searchParams.set("spl-token", splToken);
+  }
+  if (reference) {
+    url.searchParams.set("reference", reference);
+  }
+  if (label) {
+    url.searchParams.set("label", label);
+  }
+  if (message) {
+    url.searchParams.set("message", message);
+  }
+  return url.toString();
+}
+function createPaymentFlow(config) {
+  const { network, recipientWallet, amount, asset = "native", memo } = config;
+  let decimals = 9;
+  let mintAddress;
+  if (asset === "usdc") {
+    decimals = 6;
+    mintAddress = network === "mainnet-beta" ? TOKEN_MINTS.USDC_MAINNET : TOKEN_MINTS.USDC_DEVNET;
+  } else if (asset === "usdt") {
+    decimals = 6;
+    mintAddress = TOKEN_MINTS.USDT_MAINNET;
+  } else if (typeof asset === "object" && "mint" in asset) {
+    decimals = asset.decimals ?? 6;
+    mintAddress = asset.mint;
+  }
+  const naturalAmount = Number(amount) / Math.pow(10, decimals);
+  return {
+    /** Get the payment configuration */
+    getConfig: () => ({ ...config }),
+    /** Get amount in natural display units (e.g., 0.01 SOL) */
+    getDisplayAmount: () => naturalAmount,
+    /** Get amount formatted with symbol */
+    getFormattedAmount: () => {
+      const symbol = asset === "native" ? "SOL" : asset === "usdc" ? "USDC" : asset === "usdt" ? "USDT" : "tokens";
+      return `${naturalAmount.toFixed(decimals > 6 ? 4 : 2)} ${symbol}`;
+    },
+    /** Generate Solana Pay URL for QR codes */
+    getSolanaPayUrl: (options = {}) => {
+      return buildSolanaPayUrl({
+        recipient: recipientWallet,
+        amount: naturalAmount,
+        splToken: mintAddress,
+        label: options.label,
+        reference: options.reference,
+        message: memo
+      });
+    },
+    /** Get the token mint address (undefined for native SOL) */
+    getMintAddress: () => mintAddress,
+    /** Check if this is a native SOL payment */
+    isNativePayment: () => asset === "native",
+    /** Get network information */
+    getNetworkInfo: () => ({
+      network,
+      isMainnet: network === "mainnet-beta",
+      explorerUrl: network === "mainnet-beta" ? "https://explorer.solana.com" : "https://explorer.solana.com?cluster=devnet"
+    }),
+    /** Build explorer URL for a transaction */
+    getExplorerUrl: (signature) => {
+      const baseUrl = "https://explorer.solana.com/tx";
+      const cluster = network === "mainnet-beta" ? "" : "?cluster=devnet";
+      return `${baseUrl}/${signature}${cluster}`;
+    }
+  };
+}
+function createPaymentReference() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+exports.buildSolanaPayUrl = buildSolanaPayUrl;
+exports.createPaymentFlow = createPaymentFlow;
+exports.createPaymentReference = createPaymentReference;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/client/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/payment.ts","../../src/client/payment.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["// Payment-related TypeScript types for x402 protocol\n\n/** x402 network identifiers for Solana */\nexport type X402Network = 'solana-devnet' | 'solana-mainnet';\n\n/** Solana network types */\nexport type SolanaNetwork = 'devnet' | 'mainnet-beta';\n\n/** SPL Token asset specification */\nexport interface SPLTokenAsset {\n    /** Token mint address */\n    mint: string;\n    /** Token decimals (default: 6 for USDC/USDT) */\n    decimals?: number;\n}\n\n/** Asset types for payments */\nexport type PaymentAsset = 'native' | 'usdc' | 'usdt' | SPLTokenAsset;\n\n/** Known SPL token mint addresses */\nexport const TOKEN_MINTS = {\n    /** USDC on mainnet */\n    USDC_MAINNET: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',\n    /** USDC on devnet */\n    USDC_DEVNET: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',\n    /** USDT on mainnet */\n    USDT_MAINNET: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',\n} as const;\n\n/** Payment requirement for x402 protocol */\nexport interface PaymentRequirement {\n    /** Payment scheme - currently only 'exact' is supported */\n    scheme: 'exact';\n    /** Network identifier for x402 */\n    network: X402Network;\n    /** Amount in smallest unit as string (lamports for SOL, base units for tokens) */\n    maxAmountRequired: string;\n    /** URL of the protected resource */\n    resource: string;\n    /** Human-readable description */\n    description: string;\n    /** MIME type of the resource */\n    mimeType?: string;\n    /** Recipient wallet address */\n    payTo: string;\n    /** Maximum time in seconds to complete payment */\n    maxTimeoutSeconds: number;\n    /** Asset type - 'native' for SOL, 'usdc', 'usdt', or custom mint */\n    asset: PaymentAsset;\n    /** Additional metadata */\n    extra?: {\n        name?: string;\n        articleId?: string;\n        [key: string]: unknown;\n    };\n}\n\n/** Payment payload sent by client after transaction */\nexport interface PaymentPayload {\n    /** x402 protocol version */\n    x402Version: number;\n    /** Payment scheme */\n    scheme: 'exact';\n    /** Network identifier */\n    network: X402Network;\n    /** Transaction details */\n    payload: {\n        /** Transaction signature (base58) */\n        signature: string;\n        /** Base64 encoded transaction (optional) */\n        transaction?: string;\n    };\n}\n\n/** Request to verify a payment */\nexport interface VerificationRequest {\n    paymentPayload: PaymentPayload;\n    paymentRequirements: PaymentRequirement;\n}\n\n/** Response from payment verification */\nexport interface VerificationResponse {\n    /** Whether the payment is valid */\n    valid: boolean;\n    /** Reason for invalid payment */\n    invalidReason?: string;\n    /** Whether the transaction is settled on-chain */\n    settled?: boolean;\n    /** Transaction details */\n    transaction?: {\n        signature: string;\n        blockTime?: number;\n        slot?: number;\n    };\n}\n\n/** Payment status for tracking */\nexport interface PaymentStatus {\n    status: 'pending' | 'confirmed' | 'failed' | 'expired';\n    signature?: string;\n    confirmations?: number;\n    error?: string;\n}\n\n/** x402 HTTP header constants */\nexport const X402_HEADERS = {\n    PAYMENT_REQUIRED: 'x-payment-required',\n    PAYMENT: 'x-payment',\n    PAYMENT_RESPONSE: 'x-payment-response',\n} as const;\n\n/** Configuration for article pricing */\nexport interface ArticlePaymentConfig {\n    articleId: string;\n    priceInLamports: bigint;\n    title: string;\n    description?: string;\n}\n","// Client-Side Payment Flow Helper\n// Headless payment flow for frontend integration (no Node.js dependencies)\n\nimport { TOKEN_MINTS, type PaymentAsset, type SolanaNetwork } from '../types';\n\n/**\n * Payment flow configuration\n */\nexport interface PaymentFlowConfig {\n    /** Solana network */\n    network: SolanaNetwork;\n    /** Recipient wallet address */\n    recipientWallet: string;\n    /** Amount in smallest unit (lamports or token base units) */\n    amount: bigint;\n    /** Asset to pay with */\n    asset?: PaymentAsset;\n    /** Optional memo for the transaction */\n    memo?: string;\n}\n\n/**\n * Solana Pay URL parameters\n */\nexport interface SolanaPayUrlParams {\n    /** Recipient address */\n    recipient: string;\n    /** Amount in token's natural units (e.g., SOL, not lamports) */\n    amount?: number;\n    /** SPL token mint address */\n    splToken?: string;\n    /** Transaction reference */\n    reference?: string;\n    /** Label for the recipient */\n    label?: string;\n    /** Memo/message */\n    message?: string;\n}\n\n/**\n * Build a Solana Pay URL for QR codes and deep linking\n * Compatible with Phantom, Solflare, and other Solana Pay wallets\n * \n * @example\n * ```typescript\n * const url = buildSolanaPayUrl({\n *   recipient: 'CreatorWalletAddress',\n *   amount: 0.01,\n *   label: 'Article Unlock',\n *   message: 'Premium Content Access',\n * });\n * // Returns: solana:CreatorWalletAddress?amount=0.01&label=Article%20Unlock&message=Premium%20Content%20Access\n * ```\n */\nexport function buildSolanaPayUrl(params: SolanaPayUrlParams): string {\n    const { recipient, amount, splToken, reference, label, message } = params;\n\n    const url = new URL(`solana:${recipient}`);\n\n    if (amount !== undefined) {\n        url.searchParams.set('amount', amount.toString());\n    }\n\n    if (splToken) {\n        url.searchParams.set('spl-token', splToken);\n    }\n\n    if (reference) {\n        url.searchParams.set('reference', reference);\n    }\n\n    if (label) {\n        url.searchParams.set('label', label);\n    }\n\n    if (message) {\n        url.searchParams.set('message', message);\n    }\n\n    return url.toString();\n}\n\n/**\n * Create a payment flow helper for frontend use\n * Provides utilities for building transactions and generating QR codes\n * \n * @example\n * ```typescript\n * const flow = createPaymentFlow({\n *   network: 'devnet',\n *   recipientWallet: 'CreatorAddress',\n *   amount: 10000000n, // 0.01 SOL\n * });\n * \n * // Generate QR code URL\n * const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });\n * \n * // Get transaction amount in natural units\n * const amountInSol = flow.getDisplayAmount();\n * ```\n */\nexport function createPaymentFlow(config: PaymentFlowConfig) {\n    const { network, recipientWallet, amount, asset = 'native', memo } = config;\n\n    // Determine decimals and mint\n    let decimals = 9; // SOL default\n    let mintAddress: string | undefined;\n\n    if (asset === 'usdc') {\n        decimals = 6;\n        mintAddress = network === 'mainnet-beta' ? TOKEN_MINTS.USDC_MAINNET : TOKEN_MINTS.USDC_DEVNET;\n    } else if (asset === 'usdt') {\n        decimals = 6;\n        mintAddress = TOKEN_MINTS.USDT_MAINNET;\n    } else if (typeof asset === 'object' && 'mint' in asset) {\n        decimals = asset.decimals ?? 6;\n        mintAddress = asset.mint;\n    }\n\n    // Convert to natural units (from lamports/base units)\n    const naturalAmount = Number(amount) / Math.pow(10, decimals);\n\n    return {\n        /** Get the payment configuration */\n        getConfig: () => ({ ...config }),\n\n        /** Get amount in natural display units (e.g., 0.01 SOL) */\n        getDisplayAmount: () => naturalAmount,\n\n        /** Get amount formatted with symbol */\n        getFormattedAmount: () => {\n            const symbol = asset === 'native' ? 'SOL'\n                : asset === 'usdc' ? 'USDC'\n                    : asset === 'usdt' ? 'USDT'\n                        : 'tokens';\n            return `${naturalAmount.toFixed(decimals > 6 ? 4 : 2)} ${symbol}`;\n        },\n\n        /** Generate Solana Pay URL for QR codes */\n        getSolanaPayUrl: (options: { label?: string; reference?: string } = {}) => {\n            return buildSolanaPayUrl({\n                recipient: recipientWallet,\n                amount: naturalAmount,\n                splToken: mintAddress,\n                label: options.label,\n                reference: options.reference,\n                message: memo,\n            });\n        },\n\n        /** Get the token mint address (undefined for native SOL) */\n        getMintAddress: () => mintAddress,\n\n        /** Check if this is a native SOL payment */\n        isNativePayment: () => asset === 'native',\n\n        /** Get network information */\n        getNetworkInfo: () => ({\n            network,\n            isMainnet: network === 'mainnet-beta',\n            explorerUrl: network === 'mainnet-beta'\n                ? 'https://explorer.solana.com'\n                : 'https://explorer.solana.com?cluster=devnet',\n        }),\n\n        /** Build explorer URL for a transaction */\n        getExplorerUrl: (signature: string) => {\n            const baseUrl = 'https://explorer.solana.com/tx';\n            const cluster = network === 'mainnet-beta' ? '' : '?cluster=devnet';\n            return `${baseUrl}/${signature}${cluster}`;\n        },\n    };\n}\n\n/**\n * Create a unique reference for payment tracking\n * Uses crypto.randomUUID when available\n */\nexport function createPaymentReference(): string {\n    if (typeof crypto !== 'undefined' && crypto.randomUUID) {\n        return crypto.randomUUID();\n    }\n    // Fallback for environments without crypto.randomUUID\n    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;\n}\n"]}

package/dist/client/index.d.cts

@@ -0,0 +1,112 @@
+import { S as SolanaNetwork, d as PaymentAsset } from '../payment-CTxdtqmc.cjs';
+
+/**
+ * Payment flow configuration
+ */
+interface PaymentFlowConfig {
+    /** Solana network */
+    network: SolanaNetwork;
+    /** Recipient wallet address */
+    recipientWallet: string;
+    /** Amount in smallest unit (lamports or token base units) */
+    amount: bigint;
+    /** Asset to pay with */
+    asset?: PaymentAsset;
+    /** Optional memo for the transaction */
+    memo?: string;
+}
+/**
+ * Solana Pay URL parameters
+ */
+interface SolanaPayUrlParams {
+    /** Recipient address */
+    recipient: string;
+    /** Amount in token's natural units (e.g., SOL, not lamports) */
+    amount?: number;
+    /** SPL token mint address */
+    splToken?: string;
+    /** Transaction reference */
+    reference?: string;
+    /** Label for the recipient */
+    label?: string;
+    /** Memo/message */
+    message?: string;
+}
+/**
+ * Build a Solana Pay URL for QR codes and deep linking
+ * Compatible with Phantom, Solflare, and other Solana Pay wallets
+ *
+ * @example
+ * ```typescript
+ * const url = buildSolanaPayUrl({
+ *   recipient: 'CreatorWalletAddress',
+ *   amount: 0.01,
+ *   label: 'Article Unlock',
+ *   message: 'Premium Content Access',
+ * });
+ * // Returns: solana:CreatorWalletAddress?amount=0.01&label=Article%20Unlock&message=Premium%20Content%20Access
+ * ```
+ */
+declare function buildSolanaPayUrl(params: SolanaPayUrlParams): string;
+/**
+ * Create a payment flow helper for frontend use
+ * Provides utilities for building transactions and generating QR codes
+ *
+ * @example
+ * ```typescript
+ * const flow = createPaymentFlow({
+ *   network: 'devnet',
+ *   recipientWallet: 'CreatorAddress',
+ *   amount: 10000000n, // 0.01 SOL
+ * });
+ *
+ * // Generate QR code URL
+ * const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });
+ *
+ * // Get transaction amount in natural units
+ * const amountInSol = flow.getDisplayAmount();
+ * ```
+ */
+declare function createPaymentFlow(config: PaymentFlowConfig): {
+    /** Get the payment configuration */
+    getConfig: () => {
+        /** Solana network */
+        network: SolanaNetwork;
+        /** Recipient wallet address */
+        recipientWallet: string;
+        /** Amount in smallest unit (lamports or token base units) */
+        amount: bigint;
+        /** Asset to pay with */
+        asset?: PaymentAsset;
+        /** Optional memo for the transaction */
+        memo?: string;
+    };
+    /** Get amount in natural display units (e.g., 0.01 SOL) */
+    getDisplayAmount: () => number;
+    /** Get amount formatted with symbol */
+    getFormattedAmount: () => string;
+    /** Generate Solana Pay URL for QR codes */
+    getSolanaPayUrl: (options?: {
+        label?: string;
+        reference?: string;
+    }) => string;
+    /** Get the token mint address (undefined for native SOL) */
+    getMintAddress: () => string | undefined;
+    /** Check if this is a native SOL payment */
+    isNativePayment: () => boolean;
+    /** Get network information */
+    getNetworkInfo: () => {
+        network: SolanaNetwork;
+        isMainnet: boolean;
+        explorerUrl: string;
+    };
+    /** Build explorer URL for a transaction */
+    getExplorerUrl: (signature: string) => string;
+};
+/**
+ * Create a unique reference for payment tracking
+ * Uses crypto.randomUUID when available
+ */
+declare function createPaymentReference(): string;
+
+export { type PaymentFlowConfig, type SolanaPayUrlParams, buildSolanaPayUrl, createPaymentFlow, createPaymentReference };

package/dist/client/index.d.ts

@@ -0,0 +1,112 @@
+import { S as SolanaNetwork, d as PaymentAsset } from '../payment-CTxdtqmc.js';
+
+/**
+ * Payment flow configuration
+ */
+interface PaymentFlowConfig {
+    /** Solana network */
+    network: SolanaNetwork;
+    /** Recipient wallet address */
+    recipientWallet: string;
+    /** Amount in smallest unit (lamports or token base units) */
+    amount: bigint;
+    /** Asset to pay with */
+    asset?: PaymentAsset;
+    /** Optional memo for the transaction */
+    memo?: string;
+}
+/**
+ * Solana Pay URL parameters
+ */
+interface SolanaPayUrlParams {
+    /** Recipient address */
+    recipient: string;
+    /** Amount in token's natural units (e.g., SOL, not lamports) */
+    amount?: number;
+    /** SPL token mint address */
+    splToken?: string;
+    /** Transaction reference */
+    reference?: string;
+    /** Label for the recipient */
+    label?: string;
+    /** Memo/message */
+    message?: string;
+}
+/**
+ * Build a Solana Pay URL for QR codes and deep linking
+ * Compatible with Phantom, Solflare, and other Solana Pay wallets
+ *
+ * @example
+ * ```typescript
+ * const url = buildSolanaPayUrl({
+ *   recipient: 'CreatorWalletAddress',
+ *   amount: 0.01,
+ *   label: 'Article Unlock',
+ *   message: 'Premium Content Access',
+ * });
+ * // Returns: solana:CreatorWalletAddress?amount=0.01&label=Article%20Unlock&message=Premium%20Content%20Access
+ * ```
+ */
+declare function buildSolanaPayUrl(params: SolanaPayUrlParams): string;
+/**
+ * Create a payment flow helper for frontend use
+ * Provides utilities for building transactions and generating QR codes
+ *
+ * @example
+ * ```typescript
+ * const flow = createPaymentFlow({
+ *   network: 'devnet',
+ *   recipientWallet: 'CreatorAddress',
+ *   amount: 10000000n, // 0.01 SOL
+ * });
+ *
+ * // Generate QR code URL
+ * const qrUrl = flow.getSolanaPayUrl({ label: 'Unlock Article' });
+ *
+ * // Get transaction amount in natural units
+ * const amountInSol = flow.getDisplayAmount();
+ * ```
+ */
+declare function createPaymentFlow(config: PaymentFlowConfig): {
+    /** Get the payment configuration */
+    getConfig: () => {
+        /** Solana network */
+        network: SolanaNetwork;
+        /** Recipient wallet address */
+        recipientWallet: string;
+        /** Amount in smallest unit (lamports or token base units) */
+        amount: bigint;
+        /** Asset to pay with */
+        asset?: PaymentAsset;
+        /** Optional memo for the transaction */
+        memo?: string;
+    };
+    /** Get amount in natural display units (e.g., 0.01 SOL) */
+    getDisplayAmount: () => number;
+    /** Get amount formatted with symbol */
+    getFormattedAmount: () => string;
+    /** Generate Solana Pay URL for QR codes */
+    getSolanaPayUrl: (options?: {
+        label?: string;
+        reference?: string;
+    }) => string;
+    /** Get the token mint address (undefined for native SOL) */
+    getMintAddress: () => string | undefined;
+    /** Check if this is a native SOL payment */
+    isNativePayment: () => boolean;
+    /** Get network information */
+    getNetworkInfo: () => {
+        network: SolanaNetwork;
+        isMainnet: boolean;
+        explorerUrl: string;
+    };
+    /** Build explorer URL for a transaction */
+    getExplorerUrl: (signature: string) => string;
+};
+/**
+ * Create a unique reference for payment tracking
+ * Uses crypto.randomUUID when available
+ */
+declare function createPaymentReference(): string;
+
+export { type PaymentFlowConfig, type SolanaPayUrlParams, buildSolanaPayUrl, createPaymentFlow, createPaymentReference };