@alleyboss/micropay-solana-x402-paywall 3.1.3 → 3.2.0

package/dist/client/index.d.cts

@@ -1,3 +1,5 @@
+import { PublicKey, Transaction, Connection, TransactionSignature } from '@solana/web3.js';
+
 /** SPL Token asset specification */
 interface SPLTokenAsset {
     /** Token mint address */
@@ -126,4 +128,95 @@ declare function createPaymentReference(): string;
  */
 declare function createX402AuthorizationHeader(signature: string, paymentRequiredHeader: string): string;
 
-export { type PaymentFlowConfig, type SolanaPayUrlParams, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader };
+/**
+ * Minimal wallet adapter interface compatible with @solana/wallet-adapter-base
+ */
+interface WalletAdapterInterface {
+    publicKey: PublicKey | null;
+    signTransaction?: (transaction: Transaction) => Promise<Transaction>;
+    sendTransaction: (transaction: Transaction, connection: Connection, options?: any) => Promise<TransactionSignature>;
+}
+interface SendPaymentParams {
+    /** Solana Connection object */
+    connection: Connection;
+    /** Connected wallet adapter */
+    wallet: WalletAdapterInterface;
+    /** Recipient wallet address */
+    recipientAddress: string;
+    /** Amount in lamports */
+    amount: bigint;
+    /** Optional memo for the transaction */
+    memo?: string;
+    /** Commitment level (default: 'confirmed') */
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+}
+interface PaymentResult {
+    signature: string;
+    amountSol: number;
+}
+/**
+ * Send a SOL payment from the client-side wallet
+ *
+ * Handles transaction creation, recent blockhash, and sending.
+ *
+ * @example
+ * ```typescript
+ * const result = await sendSolanaPayment({
+ *   connection,
+ *   wallet,
+ *   recipientAddress: '...',
+ *   amount: 10_000_000n // 0.01 SOL
+ * });
+ * ```
+ */
+declare function sendSolanaPayment({ connection, wallet, recipientAddress, amount, commitment }: SendPaymentParams): Promise<PaymentResult>;
+
+interface PaywallConfig {
+    /** URL to fetch protected content from */
+    url: string;
+    /** Solana Connection */
+    connection: Connection;
+    /** Wallet Adapter */
+    wallet: WalletAdapterInterface;
+}
+interface PaywallState<T> {
+    /** Content data if unlocked */
+    data: T | null;
+    /** Whether content is currently locked by 402 */
+    isLocked: boolean;
+    /** Whether an operation is in progress (initial load or unlocking) */
+    isLoading: boolean;
+    /** Payment amount required (in lamports) */
+    price?: bigint;
+    /** Recipient address */
+    recipient?: string;
+    /** Error message */
+    error: string | null;
+    /** Function to trigger unlock flow */
+    unlock: () => Promise<void>;
+}
+/**
+ * React Hook to manage x402 Payment Loop
+ *
+ * Handles:
+ * 1. Initial fetch
+ * 2. 402 Payment Required detection
+ * 3. Payment execution (via wallet)
+ * 4. Auth header creation
+ * 5. Re-fetch with proof
+ *
+ * @example
+ * ```tsx
+ * const { data, isLocked, unlock, price } = usePaywallResource<Article>({
+ *   url: `/api/articles/${slug}`,
+ *   connection,
+ *   wallet
+ * });
+ *
+ * if (isLocked) return <Button onClick={unlock}>Pay {price} Lamports</Button>;
+ * return <Article data={data} />;
+ * ```
+ */
+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 };

package/dist/client/index.d.ts

@@ -1,3 +1,5 @@
+import { PublicKey, Transaction, Connection, TransactionSignature } from '@solana/web3.js';
+
 /** SPL Token asset specification */
 interface SPLTokenAsset {
     /** Token mint address */
@@ -126,4 +128,95 @@ declare function createPaymentReference(): string;
  */
 declare function createX402AuthorizationHeader(signature: string, paymentRequiredHeader: string): string;
 
-export { type PaymentFlowConfig, type SolanaPayUrlParams, buildSolanaPayUrl, createPaymentFlow, createPaymentReference, createX402AuthorizationHeader };
+/**
+ * Minimal wallet adapter interface compatible with @solana/wallet-adapter-base
+ */
+interface WalletAdapterInterface {
+    publicKey: PublicKey | null;
+    signTransaction?: (transaction: Transaction) => Promise<Transaction>;
+    sendTransaction: (transaction: Transaction, connection: Connection, options?: any) => Promise<TransactionSignature>;
+}
+interface SendPaymentParams {
+    /** Solana Connection object */
+    connection: Connection;
+    /** Connected wallet adapter */
+    wallet: WalletAdapterInterface;
+    /** Recipient wallet address */
+    recipientAddress: string;
+    /** Amount in lamports */
+    amount: bigint;
+    /** Optional memo for the transaction */
+    memo?: string;
+    /** Commitment level (default: 'confirmed') */
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+}
+interface PaymentResult {
+    signature: string;
+    amountSol: number;
+}
+/**
+ * Send a SOL payment from the client-side wallet
+ *
+ * Handles transaction creation, recent blockhash, and sending.
+ *
+ * @example
+ * ```typescript
+ * const result = await sendSolanaPayment({
+ *   connection,
+ *   wallet,
+ *   recipientAddress: '...',
+ *   amount: 10_000_000n // 0.01 SOL
+ * });
+ * ```
+ */
+declare function sendSolanaPayment({ connection, wallet, recipientAddress, amount, commitment }: SendPaymentParams): Promise<PaymentResult>;
+
+interface PaywallConfig {
+    /** URL to fetch protected content from */
+    url: string;
+    /** Solana Connection */
+    connection: Connection;
+    /** Wallet Adapter */
+    wallet: WalletAdapterInterface;
+}
+interface PaywallState<T> {
+    /** Content data if unlocked */
+    data: T | null;
+    /** Whether content is currently locked by 402 */
+    isLocked: boolean;
+    /** Whether an operation is in progress (initial load or unlocking) */
+    isLoading: boolean;
+    /** Payment amount required (in lamports) */
+    price?: bigint;
+    /** Recipient address */
+    recipient?: string;
+    /** Error message */
+    error: string | null;
+    /** Function to trigger unlock flow */
+    unlock: () => Promise<void>;
+}
+/**
+ * React Hook to manage x402 Payment Loop
+ *
+ * Handles:
+ * 1. Initial fetch
+ * 2. 402 Payment Required detection
+ * 3. Payment execution (via wallet)
+ * 4. Auth header creation
+ * 5. Re-fetch with proof
+ *
+ * @example
+ * ```tsx
+ * const { data, isLocked, unlock, price } = usePaywallResource<Article>({
+ *   url: `/api/articles/${slug}`,
+ *   connection,
+ *   wallet
+ * });
+ *
+ * if (isLocked) return <Button onClick={unlock}>Pay {price} Lamports</Button>;
+ * return <Article data={data} />;
+ * ```
+ */
+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 };