@solvapay/react 1.0.0-preview.2 → 1.0.0-preview.21

package/dist/index.d.ts

@@ -1,84 +1,927 @@
-import React from 'react';
-import { Stripe } from '@stripe/stripe-js';
+import React$1 from 'react';
+import { PaymentIntent, Stripe } from '@stripe/stripe-js';
+import { ProcessPaymentResult } from '@solvapay/server';
+import { AuthAdapter } from './adapters/auth.js';
+export { defaultAuthAdapter } from './adapters/auth.js';
 
+/**
+ * TypeScript type definitions for @solvapay/react
+ */
+
+interface PurchaseInfo {
+    reference: string;
+    productName: string;
+    productReference?: string;
+    status: string;
+    startDate: string;
+    endDate?: string;
+    cancelledAt?: string;
+    cancellationReason?: string;
+    amount?: number;
+    currency?: string;
+    planType?: string;
+    isRecurring?: boolean;
+    nextBillingDate?: string;
+    billingCycle?: string;
+    transactionId?: string;
+    planSnapshot?: {
+        reference?: string;
+        meterId?: string;
+        limit?: number;
+        freeUnits?: number;
+        pricePerUnit?: number;
+        planType?: string;
+        billingCycle?: string | null;
+        features?: Record<string, unknown> | null;
+    };
+    usage?: {
+        used: number;
+        overageUnits?: number;
+        overageCost?: number;
+        periodStart?: string;
+        periodEnd?: string;
+    };
+}
+interface CustomerPurchaseData {
+    customerRef?: string;
+    email?: string;
+    name?: string;
+    purchases: PurchaseInfo[];
+}
+interface PaymentIntentResult {
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef?: string;
+}
+interface PurchaseStatus {
+    loading: boolean;
+    customerRef?: string;
+    email?: string;
+    name?: string;
+    purchases: PurchaseInfo[];
+    hasProduct: (productName: string) => boolean;
+    /** @deprecated Use hasProduct instead */
+    hasPlan: (productName: string) => boolean;
+    /**
+     * Primary active purchase (paid or free) - most recent purchase with status === 'active'
+     * Backend keeps purchases as 'active' until expiration, even when cancelled.
+     * null if no active purchase exists
+     */
+    activePurchase: PurchaseInfo | null;
+    /**
+     * Check if user has any active paid purchase (amount > 0)
+     * Checks purchases with status === 'active'.
+     * Backend keeps purchases as 'active' until expiration, even when cancelled.
+     */
+    hasPaidPurchase: boolean;
+    /**
+     * Most recent active paid purchase (sorted by startDate)
+     * Returns purchase with status === 'active' and amount > 0.
+     * null if no active paid purchase exists
+     */
+    activePaidPurchase: PurchaseInfo | null;
+}
+/**
+ * SolvaPay Provider Configuration
+ * Sensible defaults for minimal code, but fully customizable
+ */
+interface SolvaPayConfig {
+    /**
+     * API route configuration
+     * Defaults to standard Next.js API routes
+     */
+    api?: {
+        checkPurchase?: string;
+        createPayment?: string;
+        processPayment?: string;
+    };
+    /**
+     * Authentication configuration
+     * Uses adapter pattern for flexible auth provider support
+     */
+    auth?: {
+        /**
+         * Auth adapter instance
+         * Default: checks localStorage for 'auth_token' key
+         *
+         * @example
+         * ```tsx
+         * import { createSupabaseAuthAdapter } from '@solvapay/react-supabase';
+         *
+         * <SolvaPayProvider
+         *   config={{
+         *     auth: {
+         *       adapter: createSupabaseAuthAdapter({
+         *         supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
+         *         supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+         *       })
+         *     }
+         *   }}
+         * >
+         * ```
+         */
+        adapter?: AuthAdapter;
+        /**
+         * @deprecated Use `adapter` instead. Will be removed in a future version.
+         * Function to get auth token
+         */
+        getToken?: () => Promise<string | null>;
+        /**
+         * @deprecated Use `adapter` instead. Will be removed in a future version.
+         * Function to get user ID (for cache key)
+         */
+        getUserId?: () => Promise<string | null>;
+    };
+    /**
+     * Custom fetch implementation
+     * Default: uses global fetch
+     */
+    fetch?: typeof fetch;
+    /**
+     * Request headers to include in all API calls
+     * Default: empty
+     */
+    headers?: HeadersInit | (() => Promise<HeadersInit>);
+    /**
+     * Custom error handler
+     * Default: logs to console
+     */
+    onError?: (error: Error, context: string) => void;
+}
+interface SolvaPayContextValue {
+    purchase: PurchaseStatus;
+    refetchPurchase: () => Promise<void>;
+    createPayment: (params: {
+        planRef: string;
+        productRef?: string;
+    }) => Promise<PaymentIntentResult>;
+    processPayment?: (params: {
+        paymentIntentId: string;
+        productRef: string;
+        planRef?: string;
+    }) => Promise<ProcessPaymentResult>;
+    customerRef?: string;
+    updateCustomerRef?: (newCustomerRef: string) => void;
+}
 interface SolvaPayProviderProps {
+    /**
+     * Configuration object with sensible defaults
+     * If not provided, uses standard Next.js API routes
+     */
+    config?: SolvaPayConfig;
+    /**
+     * Custom API functions (override config defaults)
+     * Use only if you need custom logic beyond standard API routes
+     */
+    createPayment?: (params: {
+        planRef: string;
+        productRef?: string;
+    }) => Promise<PaymentIntentResult>;
+    checkPurchase?: () => Promise<CustomerPurchaseData>;
+    processPayment?: (params: {
+        paymentIntentId: string;
+        productRef: string;
+        planRef?: string;
+    }) => Promise<ProcessPaymentResult>;
     children: React.ReactNode;
-    amount?: number;
+}
+interface ProductBadgeProps {
+    children?: (props: {
+        purchases: PurchaseInfo[];
+        loading: boolean;
+        displayPlan: string | null;
+        shouldShow: boolean;
+    }) => React.ReactNode;
+    as?: React.ElementType;
+    className?: string | ((props: {
+        purchases: PurchaseInfo[];
+    }) => string);
+}
+/** @deprecated Use ProductBadgeProps instead */
+type PlanBadgeProps = ProductBadgeProps;
+interface PurchaseGateProps {
+    /** @deprecated Use requireProduct instead */
+    requirePlan?: string;
+    requireProduct?: string;
+    children: (props: {
+        hasAccess: boolean;
+        purchases: PurchaseInfo[];
+        loading: boolean;
+    }) => React.ReactNode;
+}
+/**
+ * Error type for payment operations
+ */
+interface PaymentError extends Error {
+    code?: string;
+    type?: string;
+}
+/**
+ * Plan interface for plans
+ */
+interface Plan {
+    reference: string;
+    price?: number;
     currency?: string;
+    interval?: string;
+    features?: string[];
+    isFreeTier?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for usePlans hook
+ */
+interface UsePlansOptions {
+    /**
+     * Fetcher function to retrieve plans
+     */
+    fetcher: (productRef: string) => Promise<Plan[]>;
+    /**
+     * Product reference to fetch plans for
+     */
+    productRef?: string;
+    /**
+     * Optional filter function to filter plans
+     */
+    filter?: (plan: Plan) => boolean;
+    /**
+     * Optional sort function to sort plans
+     */
+    sortBy?: (a: Plan, b: Plan) => number;
+    /**
+     * Auto-select first paid plan on load
+     */
+    autoSelectFirstPaid?: boolean;
+}
+/**
+ * Return type for usePlans hook
+ */
+interface UsePlansReturn {
+    plans: Plan[];
+    loading: boolean;
+    error: Error | null;
+    selectedPlanIndex: number;
+    selectedPlan: Plan | null;
+    setSelectedPlanIndex: (index: number) => void;
+    selectPlan: (planRef: string) => void;
+    refetch: () => Promise<void>;
+}
+/**
+ * Props for headless PricingSelector component
+ */
+interface PricingSelectorProps {
+    /**
+     * Product reference to fetch plans for
+     */
+    productRef?: string;
+    /**
+     * Fetcher function to retrieve plans
+     */
+    fetcher: (productRef: string) => Promise<Plan[]>;
+    /**
+     * Optional filter function
+     */
+    filter?: (plan: Plan) => boolean;
+    /**
+     * Optional sort function
+     */
+    sortBy?: (a: Plan, b: Plan) => number;
+    /**
+     * Auto-select first paid plan on load
+     */
+    autoSelectFirstPaid?: boolean;
+    /**
+     * Render prop function
+     */
+    children: (props: UsePlansReturn & {
+        purchases: PurchaseInfo[];
+        isPaidPlan: (planRef: string) => boolean;
+        isCurrentPlan: (planRef: string) => boolean;
+    }) => React.ReactNode;
+}
+/** @deprecated Use PricingSelectorProps instead */
+type PlanSelectorProps = PricingSelectorProps;
+/**
+ * Return type for usePurchaseStatus hook
+ *
+ * Provides advanced purchase status helpers and utilities.
+ * Focuses on cancelled purchase logic and date formatting.
+ * For basic purchase data and paid status, use usePurchase() instead.
+ */
+interface PurchaseStatusReturn {
+    /**
+     * Most recent cancelled paid purchase (sorted by startDate)
+     * null if no cancelled paid purchase exists
+     */
+    cancelledPurchase: PurchaseInfo | null;
+    /**
+     * Whether to show cancelled purchase notice
+     * true if cancelledPurchase exists
+     */
+    shouldShowCancelledNotice: boolean;
+    /**
+     * Format a date string to locale format (e.g., "January 15, 2024")
+     * Returns null if dateString is not provided
+     */
+    formatDate: (dateString?: string) => string | null;
+    /**
+     * Calculate days until expiration date
+     * Returns null if endDate is not provided, otherwise returns days (0 or positive)
+     */
+    getDaysUntilExpiration: (endDate?: string) => number | null;
+}
+/**
+ * Payment form props - simplified and minimal
+ */
+interface PaymentFormProps {
+    /**
+     * Plan reference to checkout. PaymentForm handles the entire checkout flow internally
+     * including Stripe initialization and payment intent creation.
+     */
     planRef: string;
-    agentRef: string;
-    apiBaseUrl?: string;
-    onPaymentReady?: (stripe: Stripe | null, clientSecret: string) => void;
+    /**
+     * Product reference. Required for processing payment after confirmation.
+     */
+    productRef?: string;
+    /**
+     * Callback when payment succeeds
+     */
+    onSuccess?: (paymentIntent: PaymentIntent) => void;
+    /**
+     * Callback when payment fails
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Return URL after payment completion. Defaults to current page URL if not provided.
+     */
+    returnUrl?: string;
+    /**
+     * Text for the submit button. Defaults to "Pay Now"
+     */
+    submitButtonText?: string;
+    /**
+     * Optional className for the form container
+     */
+    className?: string;
+    /**
+     * Optional className for the submit button
+     */
+    buttonClassName?: string;
 }
+type PurchaseStatusValue = 'pending' | 'active' | 'trialing' | 'past_due' | 'cancelled' | 'expired' | 'suspended' | 'refunded';
+
 /**
- * SolvaPay Payment Provider Component
+ * SolvaPay Provider - Headless Context Provider for React.
+ *
+ * Provides purchase 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.
  *
- * Wraps children with Stripe Elements context after initializing a payment intent
- * via the backend API. This component handles the secure payment flow:
+ * Features:
+ * - Automatic purchase 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
  *
- * 1. Calls backend API route to create payment intent (backend uses secret key)
- * 2. Backend returns clientSecret and publishableKey from Stripe
- * 3. Initializes Stripe.js with publishableKey
- * 4. Wraps children in Stripe Elements provider
+ * @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.checkPurchase - Endpoint for checking purchase status (default: '/api/check-purchase')
+ * @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
- * // In your Next.js page
- * import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
+ * import { SolvaPayProvider } from '@solvapay/react';
  *
- * export default function CheckoutPage() {
+ * // Zero config (uses defaults)
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider>
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
+ *
+ * // Custom API routes
+ * function App() {
  *   return (
  *     <SolvaPayProvider
- *       amount={999}
- *       currency="USD"
- *       planRef="pln_abc123"
- *       agentRef="agt_xyz789"
- *       onPaymentReady={(stripe, clientSecret) => {
- *         console.log('Payment ready!');
+ *       config={{
+ *         api: {
+ *           checkPurchase: '/custom/api/purchase',
+ *           createPayment: '/custom/api/payment'
+ *         }
  *       }}
  *     >
- *       <PaymentForm />
+ *       <YourApp />
+ *     </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 usePurchase} for accessing purchase data
+ * @see {@link useCheckout} for payment checkout flow
+ * @see {@link useSolvaPay} for accessing provider methods
+ * @since 1.0.0
  */
-declare const SolvaPayProvider: React.FC<SolvaPayProviderProps>;
+declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
 
-interface PaymentFormProps {
-    onSuccess?: (paymentIntent: any) => void;
+/**
+ * Payment form component for handling Stripe checkout.
+ *
+ * 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 purchase refresh after payment
+ *
+ * @param props - Payment form configuration
+ * @param props.planRef - Plan reference to purchase (required)
+ * @param props.productRef - Product reference for usage tracking
+ * @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';
+ *
+ * function CheckoutPage() {
+ *   const router = useRouter();
+ *
+ *   return (
+ *     <PaymentForm
+ *       planRef="pln_premium"
+ *       productRef="prd_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>;
+
+/**
+ * Headless Product Badge Component
+ *
+ * Displays purchase status with complete styling control.
+ * Supports render props, custom components, or className patterns.
+ *
+ * Prevents flickering by hiding the badge during initial load and when no purchase exists.
+ * Shows the badge once loading completes AND an active purchase exists (paid or free).
+ * Badge only updates when the product name actually changes (prevents unnecessary re-renders).
+ *
+ * Displays the primary active purchase (paid or free) to show current product status.
+ *
+ * @example
+ * ```tsx
+ * // Render prop pattern
+ * <ProductBadge>
+ *   {({ purchases, loading, displayPlan, shouldShow }) => (
+ *     shouldShow ? (
+ *       <div>{displayPlan}</div>
+ *     ) : null
+ *   )}
+ * </ProductBadge>
+ *
+ * //ClassName pattern
+ * <ProductBadge className="badge badge-primary" />
+ * ```
+ */
+declare const ProductBadge: React$1.FC<ProductBadgeProps>;
+/** @deprecated Use ProductBadge instead */
+declare const PlanBadge: React$1.FC<ProductBadgeProps>;
+
+/**
+ * Headless Purchase Gate Component
+ *
+ * Controls access to content based on purchase status.
+ * Uses render props to give developers full control over locked/unlocked states.
+ *
+ * @example
+ * ```tsx
+ * <PurchaseGate requireProduct="Pro Plan">
+ *   {({ hasAccess, loading }) => {
+ *     if (loading) return <Skeleton />;
+ *     if (!hasAccess) return <Paywall />;
+ *     return <PremiumContent />;
+ *   }}
+ * </PurchaseGate>
+ * ```
+ */
+declare const PurchaseGate: React$1.FC<PurchaseGateProps>;
+
+/**
+ * Headless Pricing Selector Component
+ *
+ * Provides pricing selection logic with complete styling control via render props.
+ * Integrates plan fetching, purchase status, and selection state management.
+ *
+ * Features:
+ * - Fetches and manages pricing options
+ * - Tracks selected option
+ * - Provides helpers for checking if option is current/paid
+ * - Integrates with purchase context
+ *
+ * @example
+ * ```tsx
+ * <PricingSelector
+ *   productRef="prd_123"
+ *   fetcher={async (productRef) => {
+ *     const res = await fetch(`/api/list-plans?productRef=${productRef}`);
+ *     const data = await res.json();
+ *     return data.plans;
+ *   }}
+ *   sortBy={(a, b) => (a.price || 0) - (b.price || 0)}
+ *   autoSelectFirstPaid
+ * >
+ *   {({ plans, selectedPlan, setSelectedPlanIndex, loading, isPaidPlan, isCurrentPlan }) => (
+ *     <div>
+ *       {loading ? (
+ *         <div>Loading...</div>
+ *       ) : (
+ *         plans.map((plan, index) => (
+ *           <button
+ *             key={plan.reference}
+ *             onClick={() => setSelectedPlanIndex(index)}
+ *             disabled={!isPaidPlan(plan.reference)}
+ *           >
+ *             ${plan.price}/{plan.interval}
+ *             {isCurrentPlan(plan.reference) && ' (Current)'}
+ *           </button>
+ *         ))
+ *       )}
+ *     </div>
+ *   )}
+ * </PricingSelector>
+ * ```
+ */
+declare const PricingSelector: React$1.FC<PricingSelectorProps>;
+/** @deprecated Use PricingSelector instead */
+declare const PlanSelector: React$1.FC<PricingSelectorProps>;
+
+/**
+ * SVG-based spinner component using CSS animations
+ * Uses the same spinner design as the rest of the site
+ */
+declare const Spinner: React$1.FC<{
+    className?: string;
+    size?: 'sm' | 'md' | 'lg';
+}>;
+
+interface StripePaymentFormWrapperProps {
+    onSuccess?: (paymentIntent: unknown) => void | Promise<void>;
     onError?: (error: Error) => void;
     returnUrl?: string;
     submitButtonText?: string;
-    className?: string;
+    buttonClassName?: string;
+    clientSecret: string;
 }
 /**
- * SolvaPay Payment Form Component
+ * Stripe Payment Form Wrapper Component
+ * Renders inside Stripe Elements context and handles the payment flow
+ * All hooks are called unconditionally to comply with React Rules of Hooks
+ */
+declare const StripePaymentFormWrapper: React$1.FC<StripePaymentFormWrapperProps>;
+
+/**
+ * Hook to get current purchase status and information.
  *
- * Renders a payment form using Stripe's PaymentElement for secure card input.
- * This component must be wrapped in a SolvaPayProvider to work properly.
+ * Returns the current user's purchase status, including active
+ * purchases, plan details, and payment information. Automatically
+ * syncs with the SolvaPay backend and handles loading and error states.
+ *
+ * @returns Purchase data and status
+ * @returns purchases - Array of active purchases
+ * @returns hasPaidPurchase - Whether user has any paid purchase
+ * @returns isLoading - Loading state
+ * @returns error - Error state if purchase check fails
+ * @returns refetch - Function to manually refetch purchase data
  *
  * @example
  * ```tsx
- * import { SolvaPayProvider, PaymentForm } from '@solvapay/react';
+ * import { usePurchase } from '@solvapay/react';
+ *
+ * function Dashboard() {
+ *   const { purchases, hasPaidPurchase, isLoading, refetch } = usePurchase();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (!hasPaidPurchase) {
+ *     return <UpgradePrompt />;
+ *   }
  *
- * export default function CheckoutPage() {
  *   return (
- *     <SolvaPayProvider amount={999} planRef="pln_abc123">
- *       <PaymentForm
- *         returnUrl={`${window.location.origin}/checkout/success`}
- *         onSuccess={(paymentIntent) => {
- *           console.log('Payment successful!', paymentIntent);
- *         }}
- *         onError={(error) => {
- *           console.error('Payment failed:', error);
- *         }}
- *       />
- *     </SolvaPayProvider>
+ *     <div>
+ *       <h2>Welcome, Premium User!</h2>
+ *       <p>Active purchases: {purchases.length}</p>
+ *       <button onClick={() => refetch()}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link SolvaPayProvider} for required context provider
+ * @see {@link usePurchaseStatus} for detailed status information
+ * @since 1.0.0
+ */
+declare function usePurchase(): PurchaseStatus & {
+    refetch: () => Promise<void>;
+};
+
+/**
+ * Customer information interface
+ */
+interface CustomerInfo {
+    /**
+     * Customer reference ID
+     */
+    customerRef?: string;
+    /**
+     * Customer email address
+     */
+    email?: string;
+    /**
+     * Customer name
+     */
+    name?: string;
+    /**
+     * Whether customer data is currently loading
+     */
+    loading: boolean;
+}
+/**
+ * Hook to access customer information
+ * Returns customer data (email, name, customerRef) separate from purchase data
+ *
+ * @example
+ * ```tsx
+ * import { useCustomer } from '@solvapay/react';
+ *
+ * function MyComponent() {
+ *   const { email, name, customerRef } = useCustomer();
+ *
+ *   return (
+ *     <div>
+ *       <p>Email: {email || 'Not provided'}</p>
+ *       <p>Name: {name || 'Not provided'}</p>
+ *     </div>
  *   );
  * }
  * ```
  */
-declare const PaymentForm: React.FC<PaymentFormProps>;
+declare function useCustomer(): CustomerInfo;
+
+interface UseCheckoutReturn {
+    loading: boolean;
+    error: Error | null;
+    stripePromise: Promise<Stripe | null> | null;
+    clientSecret: string | null;
+    startCheckout: () => Promise<void>;
+    reset: () => void;
+}
+/**
+ * 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 options - Checkout options
+ * @param options.planRef - Plan reference to purchase (required)
+ * @param options.productRef - Optional product 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({
+ *     planRef: 'pln_premium',
+ *     productRef: 'prd_myapi',
+ *   });
+ *
+ *   useEffect(() => {
+ *     startCheckout();
+ *   }, []);
+ *
+ *   if (loading) return <Spinner />;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *   if (!clientSecret || !stripePromise) return null;
+ *
+ *   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(options: {
+    planRef: string;
+    productRef?: string;
+}): UseCheckoutReturn;
+
+/**
+ * Hook to access SolvaPay context and provider methods.
+ *
+ * This is the base hook that provides access to all SolvaPay functionality
+ * including purchase data, payment methods, and customer information.
+ * Other hooks like `usePurchase` and `useCheckout` use this internally.
+ *
+ * Must be used within a `SolvaPayProvider` component.
+ *
+ * @returns SolvaPay context value with all provider methods and state
+ * @returns purchase - Purchase status and data
+ * @returns createPayment - Function to create payment intents
+ * @returns processPayment - Function to process payments
+ * @returns customerRef - Current customer reference
+ * @returns refetchPurchase - Function to refetch purchase data
+ *
+ * @example
+ * ```tsx
+ * import { useSolvaPay } from '@solvapay/react';
+ *
+ * function CustomComponent() {
+ *   const { purchase, createPayment, processPayment } = useSolvaPay();
+ *
+ *   const handlePayment = async () => {
+ *     const intent = await createPayment({
+ *       planRef: 'pln_premium',
+ *       productRef: 'prd_myapi'
+ *     });
+ *     // Process payment...
+ *   };
+ *
+ *   return <div>Purchase status: {purchase.hasPaidPurchase ? 'Active' : 'None'}</div>;
+ * }
+ * ```
+ *
+ * @throws {Error} If used outside of SolvaPayProvider
+ * @see {@link SolvaPayProvider} for required context provider
+ * @see {@link usePurchase} for purchase-specific hook
+ * @see {@link useCheckout} for checkout-specific hook
+ * @since 1.0.0
+ */
+declare function useSolvaPay(): SolvaPayContextValue;
+
+/**
+ * Hook to manage plan fetching and selection
+ *
+ * Provides a reusable way to fetch, filter, sort and select plans.
+ * Handles loading and error states automatically.
+ * Uses a global cache to prevent duplicate fetches when multiple components use the same productRef.
+ *
+ * @example
+ * ```tsx
+ * const plans = usePlans({
+ *   productRef: 'prd_123',
+ *   fetcher: async (productRef) => {
+ *     const res = await fetch(`/api/list-plans?productRef=${productRef}`);
+ *     const data = await res.json();
+ *     return data.plans;
+ *   },
+ *   sortBy: (a, b) => (a.price || 0) - (b.price || 0),
+ *   autoSelectFirstPaid: true,
+ * });
+ *
+ * // Use in component
+ * if (plans.loading) return <div>Loading...</div>;
+ * if (plans.error) return <div>Error: {plans.error.message}</div>;
+ * ```
+ */
+declare function usePlans(options: UsePlansOptions): UsePlansReturn;
+
+/**
+ * Hook providing advanced status and helper functions for purchase management
+ *
+ * Focuses on cancelled purchase logic and date formatting utilities.
+ * For basic purchase data and paid status checks, use usePurchase() instead.
+ *
+ * @example
+ * ```tsx
+ * const { cancelledPurchase, shouldShowCancelledNotice, formatDate, getDaysUntilExpiration } = usePurchaseStatus();
+ *
+ * if (shouldShowCancelledNotice && cancelledPurchase) {
+ *   const formattedDate = formatDate(cancelledPurchase.endDate);
+ *   const daysLeft = getDaysUntilExpiration(cancelledPurchase.endDate);
+ * }
+ * ```
+ */
+declare function usePurchaseStatus(): PurchaseStatusReturn;
+
+/**
+ * Purchase utility functions
+ *
+ * Provides shared logic for filtering and prioritizing purchases
+ */
+
+/**
+ * Filter purchases to only include active ones
+ *
+ * Rules:
+ * - Keep purchases with status === 'active'
+ * - Filter out purchases with status === 'cancelled', 'expired', 'suspended', 'refunded', etc.
+ *
+ * Note: Backend now keeps purchases with status 'active' until expiration,
+ * even when cancelled. Cancellation is tracked via cancelledAt field.
+ */
+declare function filterPurchases(purchases: PurchaseInfo[]): PurchaseInfo[];
+/**
+ * Get active purchases
+ *
+ * Returns purchases with status === 'active'.
+ * Note: Backend keeps purchases as 'active' until expiration, even when cancelled.
+ * Use cancelledAt field to check if a purchase is cancelled.
+ */
+declare function getActivePurchases(purchases: PurchaseInfo[]): PurchaseInfo[];
+/**
+ * Get cancelled purchases with valid endDate (not expired)
+ *
+ * Returns purchases with cancelledAt set and status === 'active' that have a future endDate.
+ * Backend keeps cancelled purchases as 'active' until expiration.
+ */
+declare function getCancelledPurchasesWithEndDate(purchases: PurchaseInfo[]): PurchaseInfo[];
+/**
+ * Get the most recent purchase by startDate
+ */
+declare function getMostRecentPurchase(purchases: PurchaseInfo[]): PurchaseInfo | null;
+/**
+ * Get the primary purchase to display
+ *
+ * Prioritization:
+ * 1. Active purchases (most recent by startDate)
+ * 2. null if no valid purchases
+ *
+ * Note: Backend keeps purchases as 'active' until expiration, so we only
+ * need to check for active purchases. Cancelled purchases are still
+ * active until their endDate.
+ */
+declare function getPrimaryPurchase(purchases: PurchaseInfo[]): PurchaseInfo | null;
+/**
+ * Check if a purchase is paid
+ * Uses purchase amount field: amount > 0 = paid, amount === 0 or undefined = free
+ *
+ * @param purchase - Purchase to check
+ * @returns true if purchase is paid (amount > 0)
+ */
+declare function isPaidPurchase(purchase: PurchaseInfo): boolean;
 
-export { PaymentForm, type PaymentFormProps, SolvaPayProvider, type SolvaPayProviderProps };
+export { AuthAdapter, type CustomerInfo, type CustomerPurchaseData, type PaymentError, PaymentForm, type PaymentFormProps, type PaymentIntentResult, type Plan, PlanBadge, type PlanBadgeProps, PlanSelector, type PlanSelectorProps, PricingSelector, type PricingSelectorProps, ProductBadge, type ProductBadgeProps, PurchaseGate, type PurchaseGateProps, type PurchaseInfo, type PurchaseStatus, type PurchaseStatusReturn, type PurchaseStatusValue, type SolvaPayConfig, type SolvaPayContextValue, SolvaPayProvider, type SolvaPayProviderProps, Spinner, StripePaymentFormWrapper, type UsePlansOptions, type UsePlansReturn, filterPurchases, getActivePurchases, getCancelledPurchasesWithEndDate, getMostRecentPurchase, getPrimaryPurchase, isPaidPurchase, useCheckout, useCustomer, usePlans, usePurchase, usePurchaseStatus, useSolvaPay };