@solvapay/react 1.0.0-preview.17 → 1.0.0-preview.19

package/dist/index.d.cts

@@ -200,7 +200,7 @@ interface Plan {
     interval?: string;
     features?: string[];
     isFreeTier?: boolean;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Options for usePlans hook
@@ -342,66 +342,137 @@ interface PaymentFormProps {
 }
 
 /**
- * SolvaPay Provider - Headless Context Provider
+ * SolvaPay Provider - Headless Context Provider for React.
  *
- * Provides subscription state and payment methods to child components.
- * Supports zero-config with sensible defaults, or full customization.
+ * Provides subscription state, payment methods, and customer data to child components
+ * via React Context. This is the root component that must wrap your app to use
+ * SolvaPay React hooks and components.
+ *
+ * Features:
+ * - Automatic subscription status checking
+ * - Customer reference caching in localStorage
+ * - Payment intent creation and processing
+ * - Authentication adapter support (Supabase, custom, etc.)
+ * - Zero-config with sensible defaults, or full customization
+ *
+ * @param props - Provider configuration
+ * @param props.config - Configuration object for API routes and authentication
+ * @param props.config.api - API route configuration (optional, uses defaults if not provided)
+ * @param props.config.api.checkSubscription - Endpoint for checking subscription status (default: '/api/check-subscription')
+ * @param props.config.api.createPayment - Endpoint for creating payment intents (default: '/api/create-payment-intent')
+ * @param props.config.api.processPayment - Endpoint for processing payments (default: '/api/process-payment')
+ * @param props.config.auth - Authentication configuration (optional)
+ * @param props.config.auth.adapter - Auth adapter for extracting user ID and token
+ * @param props.children - React children components
  *
  * @example
  * ```tsx
+ * import { SolvaPayProvider } from '@solvapay/react';
+ *
  * // Zero config (uses defaults)
- * <SolvaPayProvider>
- *   <App />
- * </SolvaPayProvider>
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider>
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
  *
  * // Custom API routes
- * <SolvaPayProvider
- *   config={{
- *     api: {
- *       checkSubscription: '/custom/api/subscription',
- *       createPayment: '/custom/api/payment'
- *     }
- *   }}
- * >
- *   <App />
- * </SolvaPayProvider>
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider
+ *       config={{
+ *         api: {
+ *           checkSubscription: '/custom/api/subscription',
+ *           createPayment: '/custom/api/payment'
+ *         }
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
  *
- * // Fully custom
- * <SolvaPayProvider
- *   checkSubscription={async () => {
- *     return await myCustomAPI.checkSubscription();
- *   }}
- *   createPayment={async ({ planRef, agentRef }) => {
- *     return await myCustomAPI.createPayment(planRef, agentRef);
- *   }}
- * >
- *   <App />
- * </SolvaPayProvider>
+ * // With Supabase auth adapter
+ * import { createSupabaseAuthAdapter } from '@solvapay/react-supabase';
+ *
+ * function App() {
+ *   const adapter = createSupabaseAuthAdapter({
+ *     supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
+ *     supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+ *   });
+ *
+ *   return (
+ *     <SolvaPayProvider
+ *       config={{
+ *         auth: { adapter }
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
  * ```
+ *
+ * @see {@link useSubscription} for accessing subscription data
+ * @see {@link useCheckout} for payment checkout flow
+ * @see {@link useSolvaPay} for accessing provider methods
+ * @since 1.0.0
  */
 declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
 
 /**
- * SolvaPay Payment Form Component
+ * Payment form component for handling Stripe checkout.
  *
- * A simplified, minimal payment form that handles the checkout flow.
- * Automatically initializes Stripe and displays the payment form.
+ * This component provides a complete payment form with Stripe integration,
+ * including card input, plan selection, and payment processing. It handles
+ * the entire checkout flow including payment intent creation and confirmation.
+ *
+ * Features:
+ * - Automatic Stripe Elements initialization
+ * - Payment intent creation on mount
+ * - Card input and validation
+ * - Payment processing with error handling
+ * - Automatic subscription refresh after payment
+ *
+ * @param props - Payment form configuration
+ * @param props.planRef - Plan reference to subscribe to (required)
+ * @param props.agentRef - Agent reference for usage tracking (required)
+ * @param props.onSuccess - Callback when payment succeeds
+ * @param props.onError - Callback when payment fails
+ * @param props.returnUrl - Optional return URL after payment (for redirects)
+ * @param props.submitButtonText - Custom text for submit button (default: 'Pay Now')
+ * @param props.className - Custom CSS class for the form container
+ * @param props.buttonClassName - Custom CSS class for the submit button
  *
  * @example
  * ```tsx
  * import { PaymentForm } from '@solvapay/react';
+ * import { useRouter } from 'next/navigation';
  *
- * <PaymentForm
- *   planRef="pro_plan"
- *   agentRef="agent_123"
- *   onSuccess={(paymentIntent) => {
- *     console.log('Payment successful!');
- *   }}
- *   onError={(error) => {
- *     console.error('Payment failed:', error);
- *   }}
- * />
+ * function CheckoutPage() {
+ *   const router = useRouter();
+ *
+ *   return (
+ *     <PaymentForm
+ *       planRef="pln_premium"
+ *       agentRef="agt_myapi"
+ *       onSuccess={() => {
+ *         console.log('Payment successful!');
+ *         router.push('/dashboard');
+ *       }}
+ *       onError={(error) => {
+ *         console.error('Payment failed:', error);
+ *       }}
+ *     />
+ *   );
+ * }
  * ```
+ *
+ * @see {@link useCheckout} for programmatic checkout handling
+ * @see {@link SolvaPayProvider} for required context provider
+ * @since 1.0.0
  */
 declare const PaymentForm: React$1.FC<PaymentFormProps>;
 
@@ -510,7 +581,7 @@ declare const Spinner: React$1.FC<{
 }>;
 
 interface StripePaymentFormWrapperProps {
-    onSuccess?: (paymentIntent: any) => void | Promise<void>;
+    onSuccess?: (paymentIntent: unknown) => void | Promise<void>;
     onError?: (error: Error) => void;
     returnUrl?: string;
     submitButtonText?: string;
@@ -525,8 +596,45 @@ interface StripePaymentFormWrapperProps {
 declare const StripePaymentFormWrapper: React$1.FC<StripePaymentFormWrapperProps>;
 
 /**
- * Hook to access subscription status
- * Returns the current subscription state and a refetch function
+ * Hook to get current subscription status and information.
+ *
+ * Returns the current user's subscription status, including active
+ * subscriptions, plan details, and payment information. Automatically
+ * syncs with the SolvaPay backend and handles loading and error states.
+ *
+ * @returns Subscription data and status
+ * @returns subscriptions - Array of active subscriptions
+ * @returns hasPaidSubscription - Whether user has any paid subscription
+ * @returns isLoading - Loading state
+ * @returns error - Error state if subscription check fails
+ * @returns refetch - Function to manually refetch subscription data
+ *
+ * @example
+ * ```tsx
+ * import { useSubscription } from '@solvapay/react';
+ *
+ * function Dashboard() {
+ *   const { subscriptions, hasPaidSubscription, isLoading, refetch } = useSubscription();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (!hasPaidSubscription) {
+ *     return <UpgradePrompt />;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h2>Welcome, Premium User!</h2>
+ *       <p>Active subscriptions: {subscriptions.length}</p>
+ *       <button onClick={() => refetch()}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link SolvaPayProvider} for required context provider
+ * @see {@link useSubscriptionStatus} for detailed status information
+ * @since 1.0.0
  */
 declare function useSubscription(): SubscriptionStatus & {
     refetch: () => Promise<void>;
@@ -584,17 +692,95 @@ interface UseCheckoutReturn {
     reset: () => void;
 }
 /**
- * Hook to manage checkout flow
- * Handles payment intent creation and Stripe initialization
+ * Hook to manage checkout flow for payment processing.
+ *
+ * Handles payment intent creation and Stripe initialization. This hook
+ * manages the checkout state including loading, errors, Stripe instance,
+ * and client secret. Use this for programmatic checkout flows.
+ *
+ * @param planRef - Plan reference to subscribe to (required)
+ * @param agentRef - Optional agent reference for usage tracking
+ * @returns Checkout state and methods
+ * @returns loading - Whether checkout is in progress
+ * @returns error - Error state if checkout fails
+ * @returns stripePromise - Promise resolving to Stripe instance
+ * @returns clientSecret - Stripe payment intent client secret
+ * @returns startCheckout - Function to start the checkout process
+ * @returns reset - Function to reset checkout state
+ *
+ * @example
+ * ```tsx
+ * import { useCheckout } from '@solvapay/react';
+ * import { PaymentElement } from '@stripe/react-stripe-js';
+ *
+ * function CustomCheckout() {
+ *   const { loading, error, stripePromise, clientSecret, startCheckout } = useCheckout(
+ *     'pln_premium',
+ *     'agt_myapi'
+ *   );
+ *
+ *   useEffect(() => {
+ *     startCheckout();
+ *   }, []);
+ *
+ *   if (loading) return <Spinner />;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!clientSecret || !stripePromise) return null;
  *
- * @param planRef - The plan reference to checkout
- * @param agentRef - Optional agent reference
+ *   return (
+ *     <Elements stripe={await stripePromise} options={{ clientSecret }}>
+ *       <PaymentElement />
+ *     </Elements>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link PaymentForm} for a complete payment form component
+ * @see {@link SolvaPayProvider} for required context provider
+ * @since 1.0.0
  */
 declare function useCheckout(planRef: string, agentRef?: string): UseCheckoutReturn;
 
 /**
- * Hook to access SolvaPay context
- * Must be used within a SolvaPayProvider
+ * Hook to access SolvaPay context and provider methods.
+ *
+ * This is the base hook that provides access to all SolvaPay functionality
+ * including subscription data, payment methods, and customer information.
+ * Other hooks like `useSubscription` and `useCheckout` use this internally.
+ *
+ * Must be used within a `SolvaPayProvider` component.
+ *
+ * @returns SolvaPay context value with all provider methods and state
+ * @returns subscription - Subscription status and data
+ * @returns createPayment - Function to create payment intents
+ * @returns processPayment - Function to process payments
+ * @returns customerRef - Current customer reference
+ * @returns refetchSubscription - Function to refetch subscription data
+ *
+ * @example
+ * ```tsx
+ * import { useSolvaPay } from '@solvapay/react';
+ *
+ * function CustomComponent() {
+ *   const { subscription, createPayment, processPayment } = useSolvaPay();
+ *
+ *   const handlePayment = async () => {
+ *     const intent = await createPayment({
+ *       planRef: 'pln_premium',
+ *       agentRef: 'agt_myapi'
+ *     });
+ *     // Process payment...
+ *   };
+ *
+ *   return <div>Subscription status: {subscription.hasPaidSubscription ? 'Active' : 'None'}</div>;
+ * }
+ * ```
+ *
+ * @throws {Error} If used outside of SolvaPayProvider
+ * @see {@link SolvaPayProvider} for required context provider
+ * @see {@link useSubscription} for subscription-specific hook
+ * @see {@link useCheckout} for checkout-specific hook
+ * @since 1.0.0
  */
 declare function useSolvaPay(): SolvaPayContextValue;
 

package/dist/index.d.ts

@@ -200,7 +200,7 @@ interface Plan {
     interval?: string;
     features?: string[];
     isFreeTier?: boolean;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Options for usePlans hook
@@ -342,66 +342,137 @@ interface PaymentFormProps {
 }
 
 /**
- * SolvaPay Provider - Headless Context Provider
+ * SolvaPay Provider - Headless Context Provider for React.
  *
- * Provides subscription state and payment methods to child components.
- * Supports zero-config with sensible defaults, or full customization.
+ * Provides subscription state, payment methods, and customer data to child components
+ * via React Context. This is the root component that must wrap your app to use
+ * SolvaPay React hooks and components.
+ *
+ * Features:
+ * - Automatic subscription status checking
+ * - Customer reference caching in localStorage
+ * - Payment intent creation and processing
+ * - Authentication adapter support (Supabase, custom, etc.)
+ * - Zero-config with sensible defaults, or full customization
+ *
+ * @param props - Provider configuration
+ * @param props.config - Configuration object for API routes and authentication
+ * @param props.config.api - API route configuration (optional, uses defaults if not provided)
+ * @param props.config.api.checkSubscription - Endpoint for checking subscription status (default: '/api/check-subscription')
+ * @param props.config.api.createPayment - Endpoint for creating payment intents (default: '/api/create-payment-intent')
+ * @param props.config.api.processPayment - Endpoint for processing payments (default: '/api/process-payment')
+ * @param props.config.auth - Authentication configuration (optional)
+ * @param props.config.auth.adapter - Auth adapter for extracting user ID and token
+ * @param props.children - React children components
  *
  * @example
  * ```tsx
+ * import { SolvaPayProvider } from '@solvapay/react';
+ *
  * // Zero config (uses defaults)
- * <SolvaPayProvider>
- *   <App />
- * </SolvaPayProvider>
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider>
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
  *
  * // Custom API routes
- * <SolvaPayProvider
- *   config={{
- *     api: {
- *       checkSubscription: '/custom/api/subscription',
- *       createPayment: '/custom/api/payment'
- *     }
- *   }}
- * >
- *   <App />
- * </SolvaPayProvider>
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider
+ *       config={{
+ *         api: {
+ *           checkSubscription: '/custom/api/subscription',
+ *           createPayment: '/custom/api/payment'
+ *         }
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
  *
- * // Fully custom
- * <SolvaPayProvider
- *   checkSubscription={async () => {
- *     return await myCustomAPI.checkSubscription();
- *   }}
- *   createPayment={async ({ planRef, agentRef }) => {
- *     return await myCustomAPI.createPayment(planRef, agentRef);
- *   }}
- * >
- *   <App />
- * </SolvaPayProvider>
+ * // With Supabase auth adapter
+ * import { createSupabaseAuthAdapter } from '@solvapay/react-supabase';
+ *
+ * function App() {
+ *   const adapter = createSupabaseAuthAdapter({
+ *     supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
+ *     supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+ *   });
+ *
+ *   return (
+ *     <SolvaPayProvider
+ *       config={{
+ *         auth: { adapter }
+ *       }}
+ *     >
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
  * ```
+ *
+ * @see {@link useSubscription} for accessing subscription data
+ * @see {@link useCheckout} for payment checkout flow
+ * @see {@link useSolvaPay} for accessing provider methods
+ * @since 1.0.0
  */
 declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
 
 /**
- * SolvaPay Payment Form Component
+ * Payment form component for handling Stripe checkout.
  *
- * A simplified, minimal payment form that handles the checkout flow.
- * Automatically initializes Stripe and displays the payment form.
+ * This component provides a complete payment form with Stripe integration,
+ * including card input, plan selection, and payment processing. It handles
+ * the entire checkout flow including payment intent creation and confirmation.
+ *
+ * Features:
+ * - Automatic Stripe Elements initialization
+ * - Payment intent creation on mount
+ * - Card input and validation
+ * - Payment processing with error handling
+ * - Automatic subscription refresh after payment
+ *
+ * @param props - Payment form configuration
+ * @param props.planRef - Plan reference to subscribe to (required)
+ * @param props.agentRef - Agent reference for usage tracking (required)
+ * @param props.onSuccess - Callback when payment succeeds
+ * @param props.onError - Callback when payment fails
+ * @param props.returnUrl - Optional return URL after payment (for redirects)
+ * @param props.submitButtonText - Custom text for submit button (default: 'Pay Now')
+ * @param props.className - Custom CSS class for the form container
+ * @param props.buttonClassName - Custom CSS class for the submit button
  *
  * @example
  * ```tsx
  * import { PaymentForm } from '@solvapay/react';
+ * import { useRouter } from 'next/navigation';
  *
- * <PaymentForm
- *   planRef="pro_plan"
- *   agentRef="agent_123"
- *   onSuccess={(paymentIntent) => {
- *     console.log('Payment successful!');
- *   }}
- *   onError={(error) => {
- *     console.error('Payment failed:', error);
- *   }}
- * />
+ * function CheckoutPage() {
+ *   const router = useRouter();
+ *
+ *   return (
+ *     <PaymentForm
+ *       planRef="pln_premium"
+ *       agentRef="agt_myapi"
+ *       onSuccess={() => {
+ *         console.log('Payment successful!');
+ *         router.push('/dashboard');
+ *       }}
+ *       onError={(error) => {
+ *         console.error('Payment failed:', error);
+ *       }}
+ *     />
+ *   );
+ * }
  * ```
+ *
+ * @see {@link useCheckout} for programmatic checkout handling
+ * @see {@link SolvaPayProvider} for required context provider
+ * @since 1.0.0
  */
 declare const PaymentForm: React$1.FC<PaymentFormProps>;
 
@@ -510,7 +581,7 @@ declare const Spinner: React$1.FC<{
 }>;
 
 interface StripePaymentFormWrapperProps {
-    onSuccess?: (paymentIntent: any) => void | Promise<void>;
+    onSuccess?: (paymentIntent: unknown) => void | Promise<void>;
     onError?: (error: Error) => void;
     returnUrl?: string;
     submitButtonText?: string;
@@ -525,8 +596,45 @@ interface StripePaymentFormWrapperProps {
 declare const StripePaymentFormWrapper: React$1.FC<StripePaymentFormWrapperProps>;
 
 /**
- * Hook to access subscription status
- * Returns the current subscription state and a refetch function
+ * Hook to get current subscription status and information.
+ *
+ * Returns the current user's subscription status, including active
+ * subscriptions, plan details, and payment information. Automatically
+ * syncs with the SolvaPay backend and handles loading and error states.
+ *
+ * @returns Subscription data and status
+ * @returns subscriptions - Array of active subscriptions
+ * @returns hasPaidSubscription - Whether user has any paid subscription
+ * @returns isLoading - Loading state
+ * @returns error - Error state if subscription check fails
+ * @returns refetch - Function to manually refetch subscription data
+ *
+ * @example
+ * ```tsx
+ * import { useSubscription } from '@solvapay/react';
+ *
+ * function Dashboard() {
+ *   const { subscriptions, hasPaidSubscription, isLoading, refetch } = useSubscription();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (!hasPaidSubscription) {
+ *     return <UpgradePrompt />;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h2>Welcome, Premium User!</h2>
+ *       <p>Active subscriptions: {subscriptions.length}</p>
+ *       <button onClick={() => refetch()}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link SolvaPayProvider} for required context provider
+ * @see {@link useSubscriptionStatus} for detailed status information
+ * @since 1.0.0
  */
 declare function useSubscription(): SubscriptionStatus & {
     refetch: () => Promise<void>;
@@ -584,17 +692,95 @@ interface UseCheckoutReturn {
     reset: () => void;
 }
 /**
- * Hook to manage checkout flow
- * Handles payment intent creation and Stripe initialization
+ * Hook to manage checkout flow for payment processing.
+ *
+ * Handles payment intent creation and Stripe initialization. This hook
+ * manages the checkout state including loading, errors, Stripe instance,
+ * and client secret. Use this for programmatic checkout flows.
+ *
+ * @param planRef - Plan reference to subscribe to (required)
+ * @param agentRef - Optional agent reference for usage tracking
+ * @returns Checkout state and methods
+ * @returns loading - Whether checkout is in progress
+ * @returns error - Error state if checkout fails
+ * @returns stripePromise - Promise resolving to Stripe instance
+ * @returns clientSecret - Stripe payment intent client secret
+ * @returns startCheckout - Function to start the checkout process
+ * @returns reset - Function to reset checkout state
+ *
+ * @example
+ * ```tsx
+ * import { useCheckout } from '@solvapay/react';
+ * import { PaymentElement } from '@stripe/react-stripe-js';
+ *
+ * function CustomCheckout() {
+ *   const { loading, error, stripePromise, clientSecret, startCheckout } = useCheckout(
+ *     'pln_premium',
+ *     'agt_myapi'
+ *   );
+ *
+ *   useEffect(() => {
+ *     startCheckout();
+ *   }, []);
+ *
+ *   if (loading) return <Spinner />;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!clientSecret || !stripePromise) return null;
  *
- * @param planRef - The plan reference to checkout
- * @param agentRef - Optional agent reference
+ *   return (
+ *     <Elements stripe={await stripePromise} options={{ clientSecret }}>
+ *       <PaymentElement />
+ *     </Elements>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link PaymentForm} for a complete payment form component
+ * @see {@link SolvaPayProvider} for required context provider
+ * @since 1.0.0
  */
 declare function useCheckout(planRef: string, agentRef?: string): UseCheckoutReturn;
 
 /**
- * Hook to access SolvaPay context
- * Must be used within a SolvaPayProvider
+ * Hook to access SolvaPay context and provider methods.
+ *
+ * This is the base hook that provides access to all SolvaPay functionality
+ * including subscription data, payment methods, and customer information.
+ * Other hooks like `useSubscription` and `useCheckout` use this internally.
+ *
+ * Must be used within a `SolvaPayProvider` component.
+ *
+ * @returns SolvaPay context value with all provider methods and state
+ * @returns subscription - Subscription status and data
+ * @returns createPayment - Function to create payment intents
+ * @returns processPayment - Function to process payments
+ * @returns customerRef - Current customer reference
+ * @returns refetchSubscription - Function to refetch subscription data
+ *
+ * @example
+ * ```tsx
+ * import { useSolvaPay } from '@solvapay/react';
+ *
+ * function CustomComponent() {
+ *   const { subscription, createPayment, processPayment } = useSolvaPay();
+ *
+ *   const handlePayment = async () => {
+ *     const intent = await createPayment({
+ *       planRef: 'pln_premium',
+ *       agentRef: 'agt_myapi'
+ *     });
+ *     // Process payment...
+ *   };
+ *
+ *   return <div>Subscription status: {subscription.hasPaidSubscription ? 'Active' : 'None'}</div>;
+ * }
+ * ```
+ *
+ * @throws {Error} If used outside of SolvaPayProvider
+ * @see {@link SolvaPayProvider} for required context provider
+ * @see {@link useSubscription} for subscription-specific hook
+ * @see {@link useCheckout} for checkout-specific hook
+ * @since 1.0.0
  */
 declare function useSolvaPay(): SolvaPayContextValue;