@alleyboss/micropay-solana-x402-paywall 3.2.1 → 3.3.0

package/README.md

@@ -166,6 +166,36 @@ if (result.success) {
 }
 ```
 
+## 🎣 React Hooks (New in v3.2.2)
+
+```typescript
+import { usePricing, useFormatPrice } from '@alleyboss/micropay-solana-x402-paywall/client';
+
+function PaywallBanner({ priceInLamports }) {
+  const { formatted, isLoading } = useFormatPrice(priceInLamports);
+  
+  return (
+    <div className="paywall">
+      <span>Unlock for {isLoading ? '...' : formatted}</span>
+    </div>
+  );
+}
+```
+
+## 🗺️ Roadmap
+
+We're actively working on these exciting features:
+
+| Feature | Status | Description |
+|---------|--------|-------------|
+| ⚡ **Jupiter Swap-on-Pay** | 🔜 Coming Soon | Pay with any token, auto-swap to SOL/USDC |
+| 🖼️ **NFT/Token-Gating** | 🔜 Coming Soon | Verify NFT ownership for access discounts |
+| 📊 **Payment Analytics** | 🔜 Coming Soon | Webhooks & callbacks for payment events |
+| 🌳 **Compressed NFTs** | 🔜 Planned | Scalable access tokens via cNFTs |
+| 🔄 **Payment Streaming** | 🔜 Planned | Pay-as-you-consume for APIs |
+
+Want to contribute or sponsor a feature? Open an issue on [GitHub](https://github.com/AlleyBo55/micropay-solana-x402-paywall)!
+
 ## 📚 Documentation
 
 For full documentation:

package/dist/agent/index.cjs

@@ -146,9 +146,9 @@ async function getAgentBalance(connection, agentKeypair) {
     balanceSol: balance / web3_js.LAMPORTS_PER_SOL
   };
 }
-async function hasAgentSufficientBalance(connection, agentKeypair, requiredLamports) {
+async function hasAgentSufficientBalance(connection, agentKeypair, requiredLamports, feeBufferLamports = 5000000n) {
   const { balance } = await getAgentBalance(connection, agentKeypair);
-  const totalRequired = requiredLamports + 10000n;
+  const totalRequired = requiredLamports + feeBufferLamports;
   return {
     sufficient: balance >= totalRequired,
     balance,

package/dist/agent/index.d.cts

@@ -88,7 +88,7 @@ declare function getAgentBalance(connection: Connection, agentKeypair: Keypair):
 /**
  * Check if agent has sufficient balance for a payment
  */
-declare function hasAgentSufficientBalance(connection: Connection, agentKeypair: Keypair, requiredLamports: bigint): Promise<{
+declare function hasAgentSufficientBalance(connection: Connection, agentKeypair: Keypair, requiredLamports: bigint, feeBufferLamports?: bigint): Promise<{
     sufficient: boolean;
     balance: bigint;
     required: bigint;

package/dist/agent/index.d.ts

@@ -88,7 +88,7 @@ declare function getAgentBalance(connection: Connection, agentKeypair: Keypair):
 /**
  * Check if agent has sufficient balance for a payment
  */
-declare function hasAgentSufficientBalance(connection: Connection, agentKeypair: Keypair, requiredLamports: bigint): Promise<{
+declare function hasAgentSufficientBalance(connection: Connection, agentKeypair: Keypair, requiredLamports: bigint, feeBufferLamports?: bigint): Promise<{
     sufficient: boolean;
     balance: bigint;
     required: bigint;

package/dist/agent/index.js

@@ -140,9 +140,9 @@ async function getAgentBalance(connection, agentKeypair) {
     balanceSol: balance / LAMPORTS_PER_SOL
   };
 }
-async function hasAgentSufficientBalance(connection, agentKeypair, requiredLamports) {
+async function hasAgentSufficientBalance(connection, agentKeypair, requiredLamports, feeBufferLamports = 5000000n) {
   const { balance } = await getAgentBalance(connection, agentKeypair);
-  const totalRequired = requiredLamports + 10000n;
+  const totalRequired = requiredLamports + feeBufferLamports;
   return {
     sufficient: balance >= totalRequired,
     balance,

package/dist/client/index.cjs

@@ -241,9 +241,229 @@ function usePaywallResource({
   };
 }
 
+// src/pricing/index.ts
+var priceCache = null;
+var currentConfig = {};
+var PROVIDERS = [
+  {
+    name: "coincap",
+    url: "https://api.coincap.io/v2/assets/solana",
+    parse: (data) => parseFloat(data.data?.priceUsd || "0")
+  },
+  {
+    name: "binance",
+    url: "https://api.binance.com/api/v3/ticker/price?symbol=SOLUSDT",
+    parse: (data) => parseFloat(data.price || "0")
+  },
+  {
+    name: "coingecko",
+    url: "https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd",
+    parse: (data) => data.solana?.usd || 0
+  },
+  {
+    name: "kraken",
+    url: "https://api.kraken.com/0/public/Ticker?pair=SOLUSD",
+    parse: (data) => parseFloat(data.result?.SOLUSD?.c?.[0] || "0")
+  }
+];
+async function fetchFromProvider(provider, timeout) {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+  try {
+    const response = await fetch(provider.url, {
+      headers: { "Accept": "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+    const data = await response.json();
+    const price = provider.parse(data);
+    if (!price || price <= 0) {
+      throw new Error("Invalid price");
+    }
+    return { price, source: provider.name };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+async function fetchPriceParallel(timeout) {
+  const promises = PROVIDERS.map(
+    (provider) => fetchFromProvider(provider, timeout).catch(() => null)
+  );
+  const results = await Promise.all(promises);
+  const validResult = results.find((r) => r !== null);
+  if (validResult) {
+    return validResult;
+  }
+  throw new Error("All providers failed");
+}
+async function fetchPriceSequential(timeout) {
+  for (const provider of PROVIDERS) {
+    try {
+      return await fetchFromProvider(provider, timeout);
+    } catch {
+      continue;
+    }
+  }
+  throw new Error("All providers failed");
+}
+async function getSolPrice() {
+  const cacheTTL = currentConfig.cacheTTL ?? 6e4;
+  const timeout = currentConfig.timeout ?? 3e3;
+  const useParallel = currentConfig.parallelFetch ?? true;
+  const now = Date.now();
+  if (priceCache && now - priceCache.timestamp < cacheTTL) {
+    return priceCache.data;
+  }
+  if (currentConfig.customProvider) {
+    try {
+      const price = await currentConfig.customProvider();
+      if (price > 0) {
+        const data = {
+          solPrice: price,
+          fetchedAt: /* @__PURE__ */ new Date(),
+          source: "custom"
+        };
+        priceCache = { data, timestamp: now };
+        return data;
+      }
+    } catch {
+    }
+  }
+  try {
+    const result = useParallel ? await fetchPriceParallel(timeout) : await fetchPriceSequential(timeout);
+    const data = {
+      solPrice: result.price,
+      fetchedAt: /* @__PURE__ */ new Date(),
+      source: result.source
+    };
+    priceCache = { data, timestamp: now };
+    return data;
+  } catch {
+    if (priceCache) {
+      return {
+        ...priceCache.data,
+        source: `${priceCache.data.source} (stale)`
+      };
+    }
+    throw new Error(
+      "Failed to fetch SOL price from all providers. Configure a custom provider or ensure network connectivity."
+    );
+  }
+}
+
+// src/client/hooks.ts
+function usePricing(refreshIntervalMs = 6e4) {
+  const [priceData, setPriceData] = react.useState(null);
+  const [isLoading, setIsLoading] = react.useState(true);
+  const [error, setError] = react.useState(null);
+  const intervalRef = react.useRef(null);
+  const fetchPrice = react.useCallback(async () => {
+    try {
+      setIsLoading(true);
+      setError(null);
+      const data = await getSolPrice();
+      setPriceData(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch price");
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+  react.useEffect(() => {
+    fetchPrice();
+    if (refreshIntervalMs > 0) {
+      intervalRef.current = setInterval(fetchPrice, refreshIntervalMs);
+    }
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+      }
+    };
+  }, [fetchPrice, refreshIntervalMs]);
+  return {
+    solPrice: priceData?.solPrice ?? null,
+    source: priceData?.source ?? null,
+    fetchedAt: priceData?.fetchedAt ?? null,
+    isLoading,
+    error,
+    refresh: fetchPrice
+  };
+}
+function useLamportsToUsd(lamports) {
+  const { solPrice, isLoading } = usePricing();
+  if (isLoading || !solPrice || lamports === null) {
+    return { usd: null, formatted: null, isLoading };
+  }
+  const lamportsBigInt = typeof lamports === "number" ? BigInt(lamports) : lamports;
+  const sol = Number(lamportsBigInt) / 1e9;
+  const usd = sol * solPrice;
+  return {
+    usd,
+    formatted: `$${usd.toFixed(2)}`,
+    isLoading: false
+  };
+}
+function useMicropay() {
+  const [status, setStatus] = react.useState("idle");
+  const [error, setError] = react.useState(null);
+  const [signature, setSignature] = react.useState(null);
+  const reset = react.useCallback(() => {
+    setStatus("idle");
+    setError(null);
+    setSignature(null);
+  }, []);
+  const pay = react.useCallback(async (_options) => {
+    setStatus("pending");
+    setError(null);
+    try {
+      throw new Error(
+        "useMicropay requires implementation of onSign/onSend callbacks. See documentation for wallet adapter integration."
+      );
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "Payment failed";
+      setError(errorMessage);
+      setStatus("error");
+      return { success: false, error: errorMessage };
+    }
+  }, []);
+  return {
+    status,
+    error,
+    signature,
+    pay,
+    reset
+  };
+}
+function useFormatPrice(lamports) {
+  const { solPrice, isLoading } = usePricing();
+  if (isLoading || !solPrice || lamports === null) {
+    return {
+      sol: null,
+      usd: null,
+      formatted: "Loading...",
+      isLoading
+    };
+  }
+  const lamportsBigInt = typeof lamports === "number" ? BigInt(lamports) : lamports;
+  const sol = Number(lamportsBigInt) / 1e9;
+  const usd = sol * solPrice;
+  return {
+    sol,
+    usd,
+    formatted: `${sol.toFixed(4)} SOL (~$${usd.toFixed(2)})`,
+    isLoading: false
+  };
+}
+
 exports.buildSolanaPayUrl = buildSolanaPayUrl;
 exports.createPaymentFlow = createPaymentFlow;
 exports.createPaymentReference = createPaymentReference;
 exports.createX402AuthorizationHeader = createX402AuthorizationHeader;
 exports.sendSolanaPayment = sendSolanaPayment;
+exports.useFormatPrice = useFormatPrice;
+exports.useLamportsToUsd = useLamportsToUsd;
+exports.useMicropay = useMicropay;
 exports.usePaywallResource = usePaywallResource;
+exports.usePricing = usePricing;

package/dist/client/index.d.cts

@@ -219,4 +219,104 @@ interface PaywallState<T> {
  */
 declare function usePaywallResource<T = any>({ url, connection, wallet }: PaywallConfig): PaywallState<T>;
 
-export { type PaymentFlowConfig, type PaymentResult, type PaywallConfig, type PaywallState, type SendPaymentParams, type SolanaPayUrlParams, type WalletAdapterInterface, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader, sendSolanaPayment, usePaywallResource };
+/**
+ * Hook to fetch and display SOL price with auto-refresh
+ *
+ * @example
+ * ```tsx
+ * function PriceDisplay() {
+ *   const { solPrice, source, isLoading, error, refresh } = usePricing();
+ *
+ *   if (isLoading) return <span>Loading...</span>;
+ *   if (error) return <span>Price unavailable</span>;
+ *
+ *   return <span>SOL: ${solPrice?.toFixed(2)} (via {source})</span>;
+ * }
+ * ```
+ */
+declare function usePricing(refreshIntervalMs?: number): {
+    solPrice: number | null;
+    source: string | null;
+    fetchedAt: Date | null;
+    isLoading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Format lamports to USD display with live price
+ */
+declare function useLamportsToUsd(lamports: bigint | number | null): {
+    usd: null;
+    formatted: null;
+    isLoading: boolean;
+} | {
+    usd: number;
+    formatted: string;
+    isLoading: boolean;
+};
+/**
+ * Payment status for useMicropay hook
+ */
+type PaymentStatus = 'idle' | 'pending' | 'confirming' | 'success' | 'error';
+/**
+ * Hook for client-side micropayment flow state management
+ *
+ * @example
+ * ```tsx
+ * function PayButton({ articleId, priceInLamports }) {
+ *   const { status, error, pay, reset } = useMicropay();
+ *
+ *   const handlePay = async () => {
+ *     const result = await pay({
+ *       priceInLamports,
+ *       recipientAddress: 'CREATOR_WALLET',
+ *       onSign: (tx) => wallet.signTransaction(tx),
+ *       onSend: (signedTx) => connection.sendTransaction(signedTx),
+ *     });
+ *
+ *     if (result.success) {
+ *       // Refresh page or unlock content
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handlePay} disabled={status === 'pending'}>
+ *       {status === 'pending' ? 'Processing...' : 'Pay to Unlock'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useMicropay(): {
+    status: PaymentStatus;
+    error: string | null;
+    signature: string | null;
+    pay: (_options: {
+        priceInLamports: bigint;
+        recipientAddress: string;
+        onSign: (tx: any) => Promise<any>;
+        onSend: (signedTx: any) => Promise<string>;
+        onConfirm?: (sig: string) => Promise<void>;
+    }) => Promise<{
+        success: boolean;
+        signature?: string;
+        error?: string;
+    }>;
+    reset: () => void;
+};
+/**
+ * Hook to format price display in both SOL and USD
+ */
+declare function useFormatPrice(lamports: bigint | number | null): {
+    sol: null;
+    usd: null;
+    formatted: string;
+    isLoading: boolean;
+} | {
+    sol: number;
+    usd: number;
+    formatted: string;
+    isLoading: boolean;
+};
+
+export { type PaymentFlowConfig, type PaymentResult, type PaymentStatus, type PaywallConfig, type PaywallState, type SendPaymentParams, type SolanaPayUrlParams, type WalletAdapterInterface, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader, sendSolanaPayment, useFormatPrice, useLamportsToUsd, useMicropay, usePaywallResource, usePricing };

package/dist/client/index.d.ts

@@ -219,4 +219,104 @@ interface PaywallState<T> {
  */
 declare function usePaywallResource<T = any>({ url, connection, wallet }: PaywallConfig): PaywallState<T>;
 
-export { type PaymentFlowConfig, type PaymentResult, type PaywallConfig, type PaywallState, type SendPaymentParams, type SolanaPayUrlParams, type WalletAdapterInterface, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader, sendSolanaPayment, usePaywallResource };
+/**
+ * Hook to fetch and display SOL price with auto-refresh
+ *
+ * @example
+ * ```tsx
+ * function PriceDisplay() {
+ *   const { solPrice, source, isLoading, error, refresh } = usePricing();
+ *
+ *   if (isLoading) return <span>Loading...</span>;
+ *   if (error) return <span>Price unavailable</span>;
+ *
+ *   return <span>SOL: ${solPrice?.toFixed(2)} (via {source})</span>;
+ * }
+ * ```
+ */
+declare function usePricing(refreshIntervalMs?: number): {
+    solPrice: number | null;
+    source: string | null;
+    fetchedAt: Date | null;
+    isLoading: boolean;
+    error: string | null;
+    refresh: () => Promise<void>;
+};
+/**
+ * Format lamports to USD display with live price
+ */
+declare function useLamportsToUsd(lamports: bigint | number | null): {
+    usd: null;
+    formatted: null;
+    isLoading: boolean;
+} | {
+    usd: number;
+    formatted: string;
+    isLoading: boolean;
+};
+/**
+ * Payment status for useMicropay hook
+ */
+type PaymentStatus = 'idle' | 'pending' | 'confirming' | 'success' | 'error';
+/**
+ * Hook for client-side micropayment flow state management
+ *
+ * @example
+ * ```tsx
+ * function PayButton({ articleId, priceInLamports }) {
+ *   const { status, error, pay, reset } = useMicropay();
+ *
+ *   const handlePay = async () => {
+ *     const result = await pay({
+ *       priceInLamports,
+ *       recipientAddress: 'CREATOR_WALLET',
+ *       onSign: (tx) => wallet.signTransaction(tx),
+ *       onSend: (signedTx) => connection.sendTransaction(signedTx),
+ *     });
+ *
+ *     if (result.success) {
+ *       // Refresh page or unlock content
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handlePay} disabled={status === 'pending'}>
+ *       {status === 'pending' ? 'Processing...' : 'Pay to Unlock'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useMicropay(): {
+    status: PaymentStatus;
+    error: string | null;
+    signature: string | null;
+    pay: (_options: {
+        priceInLamports: bigint;
+        recipientAddress: string;
+        onSign: (tx: any) => Promise<any>;
+        onSend: (signedTx: any) => Promise<string>;
+        onConfirm?: (sig: string) => Promise<void>;
+    }) => Promise<{
+        success: boolean;
+        signature?: string;
+        error?: string;
+    }>;
+    reset: () => void;
+};
+/**
+ * Hook to format price display in both SOL and USD
+ */
+declare function useFormatPrice(lamports: bigint | number | null): {
+    sol: null;
+    usd: null;
+    formatted: string;
+    isLoading: boolean;
+} | {
+    sol: number;
+    usd: number;
+    formatted: string;
+    isLoading: boolean;
+};
+
+export { type PaymentFlowConfig, type PaymentResult, type PaymentStatus, type PaywallConfig, type PaywallState, type SendPaymentParams, type SolanaPayUrlParams, type WalletAdapterInterface, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader, sendSolanaPayment, useFormatPrice, useLamportsToUsd, useMicropay, usePaywallResource, usePricing };