@solvapay/react 1.0.0-preview.8 → 1.0.1-preview.1

package/dist/index.d.cts

@@ -1,26 +1,52 @@
 import React$1 from 'react';
 import { PaymentIntent, Stripe } from '@stripe/stripe-js';
 import { ProcessPaymentResult } from '@solvapay/server';
+import { AuthAdapter } from './adapters/auth.cjs';
+export { defaultAuthAdapter } from './adapters/auth.cjs';
 
 /**
  * TypeScript type definitions for @solvapay/react
  */
 
-interface SubscriptionInfo {
+interface PurchaseInfo {
     reference: string;
-    planName: string;
-    agentName: 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 CustomerSubscriptionData {
+interface CustomerPurchaseData {
     customerRef?: string;
     email?: string;
     name?: string;
-    subscriptions: SubscriptionInfo[];
+    purchases: PurchaseInfo[];
 }
 interface PaymentIntentResult {
     clientSecret: string;
@@ -28,64 +54,159 @@ interface PaymentIntentResult {
     accountId?: string;
     customerRef?: string;
 }
-interface SubscriptionStatus {
+interface PurchaseStatus {
     loading: boolean;
     customerRef?: string;
     email?: string;
     name?: string;
-    subscriptions: SubscriptionInfo[];
-    hasActiveSubscription: boolean;
-    hasPlan: (planName: string) => boolean;
+    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 {
-    subscription: SubscriptionStatus;
-    refetchSubscription: () => Promise<void>;
+    purchase: PurchaseStatus;
+    refetchPurchase: () => Promise<void>;
     createPayment: (params: {
         planRef: string;
-        customerRef: string;
+        productRef?: string;
     }) => Promise<PaymentIntentResult>;
     processPayment?: (params: {
         paymentIntentId: string;
-        agentRef: string;
-        customerRef: string;
+        productRef: string;
         planRef?: string;
     }) => Promise<ProcessPaymentResult>;
     customerRef?: string;
     updateCustomerRef?: (newCustomerRef: string) => void;
 }
 interface SolvaPayProviderProps {
-    createPayment: (params: {
+    /**
+     * 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;
-        customerRef: string;
+        productRef?: string;
     }) => Promise<PaymentIntentResult>;
-    checkSubscription: (customerRef: string) => Promise<CustomerSubscriptionData>;
+    checkPurchase?: () => Promise<CustomerPurchaseData>;
     processPayment?: (params: {
         paymentIntentId: string;
-        agentRef: string;
-        customerRef: string;
+        productRef: string;
         planRef?: string;
     }) => Promise<ProcessPaymentResult>;
-    customerRef?: string;
-    onCustomerRefUpdate?: (newCustomerRef: string) => void;
     children: React.ReactNode;
 }
-interface PlanBadgeProps {
+interface ProductBadgeProps {
     children?: (props: {
-        subscriptions: SubscriptionInfo[];
+        purchases: PurchaseInfo[];
         loading: boolean;
         displayPlan: string | null;
         shouldShow: boolean;
     }) => React.ReactNode;
     as?: React.ElementType;
     className?: string | ((props: {
-        subscriptions: SubscriptionInfo[];
+        purchases: PurchaseInfo[];
     }) => string);
 }
-interface SubscriptionGateProps {
+/** @deprecated Use ProductBadgeProps instead */
+type PlanBadgeProps = ProductBadgeProps;
+interface PurchaseGateProps {
+    /** @deprecated Use requireProduct instead */
     requirePlan?: string;
+    requireProduct?: string;
     children: (props: {
         hasAccess: boolean;
-        subscriptions: SubscriptionInfo[];
+        purchases: PurchaseInfo[];
         loading: boolean;
     }) => React.ReactNode;
 }
@@ -97,18 +218,16 @@ interface PaymentError extends Error {
     type?: string;
 }
 /**
- * Plan interface for subscription plans
+ * Plan interface for plans
  */
 interface Plan {
     reference: string;
-    name: string;
-    description?: string;
     price?: number;
     currency?: string;
     interval?: string;
     features?: string[];
     isFreeTier?: boolean;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Options for usePlans hook
@@ -117,11 +236,11 @@ interface UsePlansOptions {
     /**
      * Fetcher function to retrieve plans
      */
-    fetcher: (agentRef: string) => Promise<Plan[]>;
+    fetcher: (productRef: string) => Promise<Plan[]>;
     /**
-     * Agent reference to fetch plans for
+     * Product reference to fetch plans for
      */
-    agentRef?: string;
+    productRef?: string;
     /**
      * Optional filter function to filter plans
      */
@@ -149,17 +268,17 @@ interface UsePlansReturn {
     refetch: () => Promise<void>;
 }
 /**
- * Props for headless PlanSelector component
+ * Props for headless PricingSelector component
  */
-interface PlanSelectorProps {
+interface PricingSelectorProps {
     /**
-     * Agent reference to fetch plans for
+     * Product reference to fetch plans for
      */
-    agentRef?: string;
+    productRef?: string;
     /**
      * Fetcher function to retrieve plans
      */
-    fetcher: (agentRef: string) => Promise<Plan[]>;
+    fetcher: (productRef: string) => Promise<Plan[]>;
     /**
      * Optional filter function
      */
@@ -176,45 +295,39 @@ interface PlanSelectorProps {
      * Render prop function
      */
     children: (props: UsePlansReturn & {
-        subscriptions: SubscriptionInfo[];
-        isPaidPlan: (planName: string) => boolean;
-        isCurrentPlan: (planName: string) => boolean;
+        purchases: PurchaseInfo[];
+        isPaidPlan: (planRef: string) => boolean;
+        isCurrentPlan: (planRef: string) => boolean;
     }) => React.ReactNode;
 }
+/** @deprecated Use PricingSelectorProps instead */
+type PlanSelectorProps = PricingSelectorProps;
 /**
- * Return type for useSubscriptionHelpers hook
+ * 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 SubscriptionHelpersReturn {
-    /**
-     * Check if a plan name is a paid plan
-     */
-    isPaidPlan: (planName: string) => boolean;
-    /**
-     * Get active paid subscription
-     */
-    activePaidSubscription: SubscriptionInfo | null;
-    /**
-     * Get cancelled subscription
-     */
-    cancelledSubscription: SubscriptionInfo | null;
+interface PurchaseStatusReturn {
     /**
-     * Check if user has any paid subscription
+     * Most recent cancelled paid purchase (sorted by startDate)
+     * null if no cancelled paid purchase exists
      */
-    hasPaidSubscription: boolean;
+    cancelledPurchase: PurchaseInfo | null;
     /**
-     * Check if should show cancelled notice
+     * Whether to show cancelled purchase notice
+     * true if cancelledPurchase exists
      */
     shouldShowCancelledNotice: boolean;
     /**
-     * Get active plan name
-     */
-    activePlanName: string | null;
-    /**
-     * Format a date string
+     * Format a date string to locale format (e.g., "January 15, 2024")
+     * Returns null if dateString is not provided
      */
     formatDate: (dateString?: string) => string | null;
     /**
-     * Get days until a date
+     * Calculate days until expiration date
+     * Returns null if endDate is not provided, otherwise returns days (0 or positive)
      */
     getDaysUntilExpiration: (endDate?: string) => number | null;
 }
@@ -228,9 +341,9 @@ interface PaymentFormProps {
      */
     planRef: string;
     /**
-     * Agent reference. Required for processing payment after confirmation.
+     * Product reference. Required for processing payment after confirmation.
      */
-    agentRef?: string;
+    productRef?: string;
     /**
      * Callback when payment succeeds
      */
@@ -256,123 +369,207 @@ interface PaymentFormProps {
      */
     buttonClassName?: string;
 }
+type PurchaseStatusValue = 'pending' | 'active' | 'trialing' | 'past_due' | 'cancelled' | 'expired' | 'suspended' | 'refunded';
 
 /**
- * SolvaPay Provider - Headless Context Provider
+ * 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.
+ *
+ * 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
  *
- * Provides subscription state and payment methods to child components.
- * This is a headless provider that manages state without rendering UI.
+ * @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
- * <SolvaPayProvider
- *   customerRef={user?.id}
- *   createPayment={async ({ planRef, customerRef }) => {
- *     const res = await fetch('/api/payments/create', {
- *       method: 'POST',
- *       body: JSON.stringify({ planRef, customerRef })
- *     });
- *     return res.json();
- *   }}
- *   checkSubscription={async (customerRef) => {
- *     const res = await fetch(`/api/subscriptions/${customerRef}`);
- *     return res.json();
- *   }}
- * >
- *   <App />
- * </SolvaPayProvider>
+ * import { SolvaPayProvider } from '@solvapay/react';
+ *
+ * // Zero config (uses defaults)
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider>
+ *       <YourApp />
+ *     </SolvaPayProvider>
+ *   );
+ * }
+ *
+ * // Custom API routes
+ * function App() {
+ *   return (
+ *     <SolvaPayProvider
+ *       config={{
+ *         api: {
+ *           checkPurchase: '/custom/api/purchase',
+ *           createPayment: '/custom/api/payment'
+ *         }
+ *       }}
+ *     >
+ *       <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$1.FC<SolvaPayProviderProps>;
 
 /**
- * SolvaPay Payment Form Component
+ * 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
  *
- * A simplified, minimal payment form that handles the checkout flow.
- * Automatically initializes Stripe and displays the payment form.
+ * @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';
  *
- * <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"
+ *       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 Plan Badge Component
+ * Headless Product Badge Component
  *
- * Displays subscription status with complete styling control.
+ * 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 subscription exists.
- * Only shows the badge once loading completes AND a subscription value is available.
- * Badge only updates when the plan name actually changes (prevents unnecessary re-renders).
+ * Hidden while loading or when no active purchase exists to prevent flickering.
  *
  * @example
  * ```tsx
  * // Render prop pattern
- * <PlanBadge>
- *   {({ subscriptions, loading, displayPlan, shouldShow }) => (
+ * <ProductBadge>
+ *   {({ purchases, loading, displayPlan, shouldShow }) => (
  *     shouldShow ? (
  *       <div>{displayPlan}</div>
  *     ) : null
  *   )}
- * </PlanBadge>
+ * </ProductBadge>
  *
- * //ClassName pattern
- * <PlanBadge className="badge badge-primary" />
+ * // ClassName pattern
+ * <ProductBadge className="badge badge-primary" />
  * ```
  */
-declare const PlanBadge: React$1.FC<PlanBadgeProps>;
+declare const ProductBadge: React$1.FC<ProductBadgeProps>;
+/** @deprecated Use ProductBadge instead */
+declare const PlanBadge: React$1.FC<ProductBadgeProps>;
 
 /**
- * Headless Subscription Gate Component
+ * Headless Purchase Gate Component
  *
- * Controls access to content based on subscription status.
+ * Controls access to content based on purchase status.
  * Uses render props to give developers full control over locked/unlocked states.
  *
  * @example
  * ```tsx
- * <SubscriptionGate requirePlan="Pro Plan">
+ * <PurchaseGate requireProduct="Pro Plan">
  *   {({ hasAccess, loading }) => {
  *     if (loading) return <Skeleton />;
  *     if (!hasAccess) return <Paywall />;
  *     return <PremiumContent />;
  *   }}
- * </SubscriptionGate>
+ * </PurchaseGate>
  * ```
  */
-declare const SubscriptionGate: React$1.FC<SubscriptionGateProps>;
+declare const PurchaseGate: React$1.FC<PurchaseGateProps>;
 
 /**
- * Headless Plan Selector Component
+ * Headless Pricing Selector Component
  *
- * Provides plan selection logic with complete styling control via render props.
- * Integrates plan fetching, subscription status, and selection state management.
+ * Provides pricing selection logic with complete styling control via render props.
+ * Integrates plan fetching, purchase status, and selection state management.
  *
  * Features:
- * - Fetches and manages plans
- * - Tracks selected plan
- * - Provides helpers for checking if plan is current/paid
- * - Integrates with subscription context
+ * - Fetches and manages pricing options
+ * - Tracks selected option
+ * - Provides helpers for checking if option is current/paid
+ * - Integrates with purchase context
  *
  * @example
  * ```tsx
- * <PlanSelector
- *   agentRef="agent_123"
- *   fetcher={async (agentRef) => {
- *     const res = await fetch(`/api/list-plans?agentRef=${agentRef}`);
+ * <PricingSelector
+ *   productRef="prd_123"
+ *   fetcher={async (productRef) => {
+ *     const res = await fetch(`/api/list-plans?productRef=${productRef}`);
  *     const data = await res.json();
  *     return data.plans;
  *   }}
@@ -382,28 +579,31 @@ declare const SubscriptionGate: React$1.FC<SubscriptionGateProps>;
  *   {({ plans, selectedPlan, setSelectedPlanIndex, loading, isPaidPlan, isCurrentPlan }) => (
  *     <div>
  *       {loading ? (
- *         <div>Loading plans...</div>
+ *         <div>Loading...</div>
  *       ) : (
  *         plans.map((plan, index) => (
  *           <button
  *             key={plan.reference}
  *             onClick={() => setSelectedPlanIndex(index)}
- *             disabled={!isPaidPlan(plan.name)}
+ *             disabled={!isPaidPlan(plan.reference)}
  *           >
- *             {plan.name} - ${plan.price}
- *             {isCurrentPlan(plan.name) && ' (Current)'}
+ *             ${plan.price}/{plan.interval}
+ *             {isCurrentPlan(plan.reference) && ' (Current)'}
  *           </button>
  *         ))
  *       )}
  *     </div>
  *   )}
- * </PlanSelector>
+ * </PricingSelector>
  * ```
  */
-declare const PlanSelector: React$1.FC<PlanSelectorProps>;
+declare const PricingSelector: React$1.FC<PricingSelectorProps>;
+/** @deprecated Use PricingSelector instead */
+declare const PlanSelector: React$1.FC<PricingSelectorProps>;
 
 /**
- * Simple spinner component using CSS animations
+ * 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;
@@ -411,11 +611,12 @@ declare const Spinner: React$1.FC<{
 }>;
 
 interface StripePaymentFormWrapperProps {
-    onSuccess?: (paymentIntent: any) => void;
+    onSuccess?: (paymentIntent: unknown) => void | Promise<void>;
     onError?: (error: Error) => void;
     returnUrl?: string;
     submitButtonText?: string;
     buttonClassName?: string;
+    clientSecret: string;
 }
 /**
  * Stripe Payment Form Wrapper Component
@@ -425,13 +626,93 @@ 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 purchase status and information.
+ *
+ * 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 { usePurchase } from '@solvapay/react';
+ *
+ * function Dashboard() {
+ *   const { purchases, hasPaidPurchase, isLoading, refetch } = usePurchase();
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   if (!hasPaidPurchase) {
+ *     return <UpgradePrompt />;
+ *   }
+ *
+ *   return (
+ *     <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 useSubscription(): SubscriptionStatus & {
+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 function useCustomer(): CustomerInfo;
+
 interface UseCheckoutReturn {
     loading: boolean;
     error: Error | null;
@@ -441,31 +722,115 @@ 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 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();
+ *   }, []);
  *
- * @param planRef - The plan reference to checkout
+ *   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(planRef: string): UseCheckoutReturn;
+declare function useCheckout(options: {
+    planRef: string;
+    productRef?: 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 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 subscription plans.
+ * 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({
- *   agentRef: 'agent_123',
- *   fetcher: async (agentRef) => {
- *     const res = await fetch(`/api/list-plans?agentRef=${agentRef}`);
+ *   productRef: 'prd_123',
+ *   fetcher: async (productRef) => {
+ *     const res = await fetch(`/api/list-plans?productRef=${productRef}`);
  *     const data = await res.json();
  *     return data.plans;
  *   },
@@ -481,74 +846,78 @@ declare function useSolvaPay(): SolvaPayContextValue;
 declare function usePlans(options: UsePlansOptions): UsePlansReturn;
 
 /**
- * Hook providing helper functions for subscription management
+ * Hook providing advanced status and helper functions for purchase management
  *
- * Provides utilities for checking subscription status, formatting dates,
- * and working with paid vs free plans.
- *
- * @param plans - Array of available plans to determine if a subscription is paid
+ * Focuses on cancelled purchase logic and date formatting utilities.
+ * For basic purchase data and paid status checks, use usePurchase() instead.
  *
  * @example
  * ```tsx
- * const helpers = useSubscriptionHelpers(plans);
+ * const { cancelledPurchase, shouldShowCancelledNotice, formatDate, getDaysUntilExpiration } = usePurchaseStatus();
  *
- * if (helpers.isPaidPlan('Pro Plan')) {
- *   // Handle paid plan
+ * if (shouldShowCancelledNotice && cancelledPurchase) {
+ *   const formattedDate = formatDate(cancelledPurchase.endDate);
+ *   const daysLeft = getDaysUntilExpiration(cancelledPurchase.endDate);
  * }
- *
- * const daysLeft = helpers.getDaysUntilExpiration(subscription.endDate);
  * ```
  */
-declare function useSubscriptionHelpers(plans: Plan[]): SubscriptionHelpersReturn;
+declare function usePurchaseStatus(): PurchaseStatusReturn;
 
 /**
- * Subscription utility functions
+ * Purchase utility functions
  *
- * Provides shared logic for filtering and prioritizing subscriptions
+ * Provides shared logic for filtering and prioritizing purchases
  */
 
 /**
- * Filter subscriptions based on cancellation status and endDate
+ * Filter purchases to only include active ones
  *
  * Rules:
- * - Keep all non-cancelled subscriptions
- * - A subscription is considered cancelled if:
- *   1. status === 'cancelled', OR
- *   2. cancelledAt is set (even if status is still 'active' - this is expected behavior)
- * - Keep cancelled subscriptions only if they have an endDate in the future
- *   (meaning the subscription is cancelled but still active until the endDate)
- * - Filter out cancelled subscriptions without endDate or with past endDate
+ * - 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 filterSubscriptions(subscriptions: SubscriptionInfo[]): SubscriptionInfo[];
+declare function filterPurchases(purchases: PurchaseInfo[]): PurchaseInfo[];
 /**
- * Get active subscriptions (excluding cancelled ones)
- * Also excludes subscriptions with cancelledAt set, even if status is still 'active'
+ * 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 getActiveSubscriptions(subscriptions: SubscriptionInfo[]): SubscriptionInfo[];
+declare function getActivePurchases(purchases: PurchaseInfo[]): PurchaseInfo[];
 /**
- * Get cancelled subscriptions with valid endDate (not expired)
- * Includes subscriptions with cancelledAt set, even if status is still 'active'
+ * 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 getCancelledSubscriptionsWithEndDate(subscriptions: SubscriptionInfo[]): SubscriptionInfo[];
+declare function getCancelledPurchasesWithEndDate(purchases: PurchaseInfo[]): PurchaseInfo[];
 /**
- * Get the most recent subscription by startDate
+ * Get the most recent purchase by startDate
  */
-declare function getMostRecentSubscription(subscriptions: SubscriptionInfo[]): SubscriptionInfo | null;
+declare function getMostRecentPurchase(purchases: PurchaseInfo[]): PurchaseInfo | null;
 /**
- * Get the primary subscription to display
+ * Get the primary purchase to display
  *
  * Prioritization:
- * 1. Active subscriptions (most recent by startDate)
- * 2. Cancelled subscriptions with endDate in the future (most recent by startDate)
- * 3. null if no valid subscriptions
+ * 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 getPrimarySubscription(subscriptions: SubscriptionInfo[]): SubscriptionInfo | null;
+declare function getPrimaryPurchase(purchases: PurchaseInfo[]): PurchaseInfo | null;
 /**
- * Check if user has an active paid subscription
+ * Check if a purchase is paid
+ * Uses purchase amount field: amount > 0 = paid, amount === 0 or undefined = free
  *
- * @param subscriptions - Array of subscriptions
- * @param isPaidPlan - Function to check if a plan name represents a paid plan
+ * @param purchase - Purchase to check
+ * @returns true if purchase is paid (amount > 0)
  */
-declare function hasActivePaidSubscription(subscriptions: SubscriptionInfo[], isPaidPlan: (planName: string) => boolean): boolean;
+declare function isPaidPurchase(purchase: PurchaseInfo): boolean;
 
-export { type CustomerSubscriptionData, type PaymentError, PaymentForm, type PaymentFormProps, type PaymentIntentResult, type Plan, PlanBadge, type PlanBadgeProps, PlanSelector, type PlanSelectorProps, type SolvaPayContextValue, SolvaPayProvider, type SolvaPayProviderProps, Spinner, StripePaymentFormWrapper, SubscriptionGate, type SubscriptionGateProps, type SubscriptionHelpersReturn, type SubscriptionInfo, type SubscriptionStatus, type UsePlansOptions, type UsePlansReturn, filterSubscriptions, getActiveSubscriptions, getCancelledSubscriptionsWithEndDate, getMostRecentSubscription, getPrimarySubscription, hasActivePaidSubscription, useCheckout, usePlans, useSolvaPay, useSubscription, useSubscriptionHelpers };
+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 };