@solvapay/react 1.0.6 → 1.0.9-preview.1

package/dist/index.d.ts

@@ -1,17 +1,16 @@
 import React$1 from 'react';
+import * as _stripe_stripe_js from '@stripe/stripe-js';
 import { PaymentIntent, Stripe } from '@stripe/stripe-js';
-import { ProcessPaymentResult } from '@solvapay/server';
+import { ProcessPaymentResult, ActivatePlanResult } from '@solvapay/server';
+export { ActivatePlanResult } from '@solvapay/server';
 import { AuthAdapter } from './adapters/auth.js';
 export { defaultAuthAdapter } from './adapters/auth.js';
-
-/**
- * TypeScript type definitions for @solvapay/react
- */
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 interface PurchaseInfo {
     reference: string;
     productName: string;
-    productReference?: string;
+    productRef?: string;
     status: string;
     startDate: string;
     endDate?: string;
@@ -23,13 +22,14 @@ interface PurchaseInfo {
     isRecurring?: boolean;
     nextBillingDate?: string;
     billingCycle?: string;
-    transactionId?: string;
+    planRef?: string;
     planSnapshot?: {
         reference?: string;
-        meterId?: string;
+        price?: number;
+        meterRef?: string;
         limit?: number;
         freeUnits?: number;
-        pricePerUnit?: number;
+        creditsPerUnit?: number;
         planType?: string;
         billingCycle?: string | null;
         features?: Record<string, unknown> | null;
@@ -54,8 +54,40 @@ interface PaymentIntentResult {
     accountId?: string;
     customerRef?: string;
 }
+interface TopupPaymentResult {
+    clientSecret: string;
+    publishableKey: string;
+    accountId?: string;
+    customerRef?: string;
+}
+interface UseTopupOptions {
+    amount: number;
+    currency?: string;
+}
+interface UseTopupReturn {
+    loading: boolean;
+    error: Error | null;
+    stripePromise: Promise<_stripe_stripe_js.Stripe | null> | null;
+    clientSecret: string | null;
+    startTopup: () => Promise<void>;
+    reset: () => void;
+}
+interface TopupFormProps {
+    amount: number;
+    currency?: string;
+    onSuccess?: (paymentIntent: PaymentIntent) => void;
+    onError?: (error: Error) => void;
+    returnUrl?: string;
+    submitButtonText?: string;
+    className?: string;
+    buttonClassName?: string;
+}
 interface PurchaseStatus {
     loading: boolean;
+    /** True when data already exists but a background refetch is in progress */
+    isRefetching: boolean;
+    /** Last fetch error, or null if the most recent fetch succeeded */
+    error: Error | null;
     customerRef?: string;
     email?: string;
     name?: string;
@@ -86,6 +118,15 @@ interface PurchaseStatus {
  * SolvaPay Provider Configuration
  * Sensible defaults for minimal code, but fully customizable
  */
+interface BalanceStatus {
+    loading: boolean;
+    credits: number | null;
+    displayCurrency: string | null;
+    creditsPerMinorUnit: number | null;
+    displayExchangeRate: number | null;
+    refetch: () => Promise<void>;
+    adjustBalance: (credits: number) => void;
+}
 interface SolvaPayConfig {
     /**
      * API route configuration
@@ -95,6 +136,12 @@ interface SolvaPayConfig {
         checkPurchase?: string;
         createPayment?: string;
         processPayment?: string;
+        createTopupPayment?: string;
+        customerBalance?: string;
+        cancelRenewal?: string;
+        reactivateRenewal?: string;
+        activatePlan?: string;
+        listPlans?: string;
     };
     /**
      * Authentication configuration
@@ -149,11 +196,23 @@ interface SolvaPayConfig {
      */
     onError?: (error: Error, context: string) => void;
 }
+interface CancelResult {
+    reference?: string;
+    status?: string;
+    cancelledAt?: string;
+    [key: string]: unknown;
+}
+interface ReactivateResult {
+    reference?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+
 interface SolvaPayContextValue {
     purchase: PurchaseStatus;
     refetchPurchase: () => Promise<void>;
     createPayment: (params: {
-        planRef: string;
+        planRef?: string;
         productRef?: string;
     }) => Promise<PaymentIntentResult>;
     processPayment?: (params: {
@@ -161,8 +220,26 @@ interface SolvaPayContextValue {
         productRef: string;
         planRef?: string;
     }) => Promise<ProcessPaymentResult>;
+    createTopupPayment: (params: {
+        amount: number;
+        currency?: string;
+    }) => Promise<TopupPaymentResult>;
+    cancelRenewal: (params: {
+        purchaseRef: string;
+        reason?: string;
+    }) => Promise<CancelResult>;
+    reactivateRenewal: (params: {
+        purchaseRef: string;
+    }) => Promise<ReactivateResult>;
+    activatePlan: (params: {
+        productRef: string;
+        planRef: string;
+    }) => Promise<ActivatePlanResult>;
     customerRef?: string;
     updateCustomerRef?: (newCustomerRef: string) => void;
+    balance: BalanceStatus;
+    /** @internal Provider config — used by SDK hooks, not part of public API */
+    _config?: SolvaPayConfig;
 }
 interface SolvaPayProviderProps {
     /**
@@ -175,7 +252,7 @@ interface SolvaPayProviderProps {
      * Use only if you need custom logic beyond standard API routes
      */
     createPayment?: (params: {
-        planRef: string;
+        planRef?: string;
         productRef?: string;
     }) => Promise<PaymentIntentResult>;
     checkPurchase?: () => Promise<CustomerPurchaseData>;
@@ -184,6 +261,10 @@ interface SolvaPayProviderProps {
         productRef: string;
         planRef?: string;
     }) => Promise<ProcessPaymentResult>;
+    createTopupPayment?: (params: {
+        amount: number;
+        currency?: string;
+    }) => Promise<TopupPaymentResult>;
     children: React.ReactNode;
 }
 interface ProductBadgeProps {
@@ -218,15 +299,39 @@ interface PaymentError extends Error {
     type?: string;
 }
 /**
- * Plan interface for plans
+ * Plan returned by the SolvaPay API.
+ *
+ * All fields are optional except `reference` so the type stays compatible
+ * with partial JSON responses from custom fetcher functions.
  */
 interface Plan {
+    type?: 'recurring' | 'one-time' | 'usage-based';
     reference: string;
+    name?: string;
+    description?: string;
     price?: number;
     currency?: string;
+    currencySymbol?: string;
+    freeUnits?: number;
+    setupFee?: number;
+    trialDays?: number;
+    billingCycle?: string;
+    billingModel?: 'pre-paid' | 'post-paid';
+    creditsPerUnit?: number;
+    measures?: string;
+    limit?: number;
+    rolloverUnusedUnits?: boolean;
+    limits?: Record<string, unknown>;
+    features?: Record<string, unknown> | string[];
+    requiresPayment?: boolean;
+    default?: boolean;
+    isActive?: boolean;
+    maxActiveUsers?: number;
+    accessExpiryDays?: number;
+    status?: string;
+    createdAt?: string;
+    updatedAt?: string;
     interval?: string;
-    features?: string[];
-    isFreeTier?: boolean;
     metadata?: Record<string, unknown>;
 }
 /**
@@ -242,9 +347,10 @@ interface UsePlansOptions {
      */
     productRef?: string;
     /**
-     * Optional filter function to filter plans
+     * Optional filter function to filter plans.
+     * Receives plan and its index (after sorting, if sortBy is provided).
      */
-    filter?: (plan: Plan) => boolean;
+    filter?: (plan: Plan, index: number) => boolean;
     /**
      * Optional sort function to sort plans
      */
@@ -253,6 +359,18 @@ interface UsePlansOptions {
      * Auto-select first paid plan on load
      */
     autoSelectFirstPaid?: boolean;
+    /**
+     * Plan reference to select initially when plans load.
+     * Applied at most once when selectionReady is true.
+     * Takes priority over autoSelectFirstPaid.
+     */
+    initialPlanRef?: string;
+    /**
+     * When false, plans still fetch but auto-selection is deferred.
+     * When it transitions to true, one-shot initial selection fires.
+     * Defaults to true.
+     */
+    selectionReady?: boolean;
 }
 /**
  * Return type for usePlans hook
@@ -266,6 +384,8 @@ interface UsePlansReturn {
     setSelectedPlanIndex: (index: number) => void;
     selectPlan: (planRef: string) => void;
     refetch: () => Promise<void>;
+    /** True after the one-shot initial selection has been applied */
+    isSelectionReady: boolean;
 }
 /**
  * Props for headless PricingSelector component
@@ -282,7 +402,7 @@ interface PricingSelectorProps {
     /**
      * Optional filter function
      */
-    filter?: (plan: Plan) => boolean;
+    filter?: (plan: Plan, index: number) => boolean;
     /**
      * Optional sort function
      */
@@ -336,12 +456,14 @@ interface PurchaseStatusReturn {
  */
 interface PaymentFormProps {
     /**
-     * Plan reference to checkout. PaymentForm handles the entire checkout flow internally
-     * including Stripe initialization and payment intent creation.
+     * Plan reference to checkout. When omitted, the SDK auto-resolves the plan from
+     * productRef (requires exactly one active plan or a default plan). Pass explicitly
+     * when the product has multiple plans without a default.
      */
-    planRef: string;
+    planRef?: string;
     /**
-     * Product reference. Required for processing payment after confirmation.
+     * Product reference. Required when planRef is omitted (for plan resolution)
+     * and for processing payment after confirmation.
      */
     productRef?: string;
     /**
@@ -369,6 +491,33 @@ interface PaymentFormProps {
      */
     buttonClassName?: string;
 }
+interface BalanceBadgeProps {
+    className?: string;
+    numberOnly?: boolean;
+    children?: (props: {
+        credits: number | null;
+        loading: boolean;
+        displayCurrency: string | null;
+        creditsPerMinorUnit: number | null;
+    }) => React.ReactNode;
+}
+interface UseTopupAmountSelectorOptions {
+    currency: string;
+    minAmount?: number;
+    maxAmount?: number;
+}
+interface UseTopupAmountSelectorReturn {
+    quickAmounts: number[];
+    selectedAmount: number | null;
+    customAmount: string;
+    resolvedAmount: number | null;
+    selectQuickAmount: (amount: number) => void;
+    setCustomAmount: (value: string) => void;
+    error: string | null;
+    validate: () => boolean;
+    reset: () => void;
+    currencySymbol: string;
+}
 type PurchaseStatusValue = 'pending' | 'active' | 'trialing' | 'past_due' | 'cancelled' | 'expired' | 'suspended' | 'refunded';
 
 /**
@@ -459,16 +608,13 @@ declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
  * 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
+ * When `planRef` is omitted but `productRef` is provided, the component
+ * auto-resolves the plan by fetching the product's plans and selecting the
+ * single active plan or the one marked as default.
  *
  * @param props - Payment form configuration
- * @param props.planRef - Plan reference to purchase (required)
- * @param props.productRef - Product reference for usage tracking
+ * @param props.planRef - Plan reference (optional if product has single/default plan)
+ * @param props.productRef - Product reference (required when planRef is omitted)
  * @param props.onSuccess - Callback when payment succeeds
  * @param props.onError - Callback when payment fails
  * @param props.returnUrl - Optional return URL after payment (for redirects)
@@ -478,34 +624,25 @@ declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
  *
  * @example
  * ```tsx
- * import { PaymentForm } from '@solvapay/react';
- * import { useRouter } from 'next/navigation';
- *
- * function CheckoutPage() {
- *   const router = useRouter();
+ * // Explicit plan
+ * <PaymentForm planRef="pln_premium" productRef="prd_myapi" onSuccess={...} />
  *
- *   return (
- *     <PaymentForm
- *       planRef="pln_premium"
- *       productRef="prd_myapi"
- *       onSuccess={() => {
- *         console.log('Payment successful!');
- *         router.push('/dashboard');
- *       }}
- *       onError={(error) => {
- *         console.error('Payment failed:', error);
- *       }}
- *     />
- *   );
- * }
+ * // Auto-resolve plan (product must have exactly one plan or a default)
+ * <PaymentForm productRef="prd_myapi" onSuccess={...} />
  * ```
- *
- * @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>;
 
+/**
+ * Credit top-up form with Stripe Elements.
+ *
+ * Unlike `PaymentForm`, this component does **not** call `processPayment`
+ * after Stripe confirmation. Credits are recorded via the backend webhook
+ * handler (`CreditService.recordCredit`), so `onSuccess` is called
+ * immediately after `stripe.confirmCardPayment` succeeds.
+ */
+declare const TopupForm: React$1.FC<TopupFormProps>;
+
 /**
  * Headless Product Badge Component
  *
@@ -626,6 +763,8 @@ interface StripePaymentFormWrapperProps {
  */
 declare const StripePaymentFormWrapper: React$1.FC<StripePaymentFormWrapperProps>;
 
+declare function BalanceBadge({ className, numberOnly, children }: BalanceBadgeProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * Hook to get current purchase status and information.
  *
@@ -719,60 +858,33 @@ interface UseCheckoutReturn {
     error: Error | null;
     stripePromise: Promise<Stripe | null> | null;
     clientSecret: string | null;
+    resolvedPlanRef: 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.
+ * Handles payment intent creation and Stripe initialization. When `planRef`
+ * is omitted but `productRef` is provided, the hook auto-resolves the plan
+ * by fetching the product's plans and selecting the single/default one.
  *
  * @param options - Checkout options
- * @param options.planRef - Plan reference to purchase (required)
- * @param options.productRef - Optional product reference for usage tracking
+ * @param options.planRef - Plan reference (optional if product has single/default plan)
+ * @param options.productRef - Product reference (required when planRef is omitted)
  * @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;
+ * // Explicit planRef (no resolution needed)
+ * const checkout = useCheckout({ planRef: 'pln_premium', productRef: 'prd_myapi' })
  *
- *   return (
- *     <Elements stripe={await stripePromise} options={{ clientSecret }}>
- *       <PaymentElement />
- *     </Elements>
- *   );
- * }
+ * // Auto-resolve plan from product (single plan or default plan)
+ * const checkout = useCheckout({ productRef: 'prd_myapi' })
  * ```
- *
- * @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;
+    planRef?: string;
     productRef?: string;
 }): UseCheckoutReturn;
 
@@ -820,29 +932,13 @@ declare function useCheckout(options: {
 declare function useSolvaPay(): SolvaPayContextValue;
 
 /**
- * Hook to manage plan fetching and selection
+ * 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>;
- * ```
+ * Selection lifecycle:
+ * 1. While `selectionReady` is false, plans fetch but no auto-selection fires.
+ * 2. When `selectionReady` becomes true AND plans are loaded, one-shot initial
+ *    selection is applied (initialPlanRef > autoSelectFirstPaid > index 0).
+ * 3. After initial selection, user picks always win — the hook never overrides.
  */
 declare function usePlans(options: UsePlansOptions): UsePlansReturn;
 
@@ -864,6 +960,113 @@ declare function usePlans(options: UsePlansOptions): UsePlansReturn;
  */
 declare function usePurchaseStatus(): PurchaseStatusReturn;
 
+interface PurchaseActions {
+    cancelRenewal: (params: {
+        purchaseRef: string;
+        reason?: string;
+    }) => Promise<CancelResult>;
+    reactivateRenewal: (params: {
+        purchaseRef: string;
+    }) => Promise<ReactivateResult>;
+    activatePlan: (params: {
+        productRef: string;
+        planRef: string;
+    }) => Promise<ActivatePlanResult>;
+    isCancelling: boolean;
+    isReactivating: boolean;
+    isActivating: boolean;
+}
+/**
+ * Hook for purchase lifecycle mutations: cancel, reactivate, and activate.
+ *
+ * Wraps the context methods with per-operation loading states.
+ * Auto-refetches purchase data on success (handled by the context methods).
+ *
+ * @example
+ * ```tsx
+ * const { cancelRenewal, reactivateRenewal, isCancelling } = usePurchaseActions()
+ *
+ * await cancelRenewal({ purchaseRef: purchase.reference, reason: 'User requested' })
+ * ```
+ */
+declare function usePurchaseActions(): PurchaseActions;
+
+type ActivationState = 'idle' | 'activating' | 'activated' | 'topup_required' | 'payment_required' | 'error';
+interface UseActivationReturn {
+    activate: (params: {
+        productRef: string;
+        planRef: string;
+    }) => Promise<void>;
+    state: ActivationState;
+    error: string | null;
+    result: ActivatePlanResult | null;
+    reset: () => void;
+}
+/**
+ * State-machine hook for the plan activation flow.
+ *
+ * Wraps `activatePlan` from context and maps API response statuses
+ * to discrete UI states: idle → activating → activated | topup_required | payment_required | error.
+ *
+ * Auto-refetches purchase data on successful activation (handled by context).
+ *
+ * @example
+ * ```tsx
+ * const { activate, state, error, reset } = useActivation()
+ *
+ * if (state === 'topup_required') return <TopupPrompt />
+ * if (state === 'activated') return <SuccessMessage />
+ *
+ * <button onClick={() => activate({ productRef, planRef })} disabled={state === 'activating'}>
+ *   Activate
+ * </button>
+ * ```
+ */
+declare function useActivation(): UseActivationReturn;
+
+/**
+ * Hook to manage credit top-up flow.
+ *
+ * Handles payment intent creation (with `purpose: 'credit_topup'`) and
+ * Stripe initialization. Unlike `useCheckout`, there is no plan resolution
+ * and no `processPayment` step — credits are recorded via webhook.
+ *
+ * @param options.amount - Amount in smallest currency unit (e.g. cents)
+ * @param options.currency - ISO 4217 currency code (default: 'usd')
+ */
+declare function useTopup(options: UseTopupOptions): UseTopupReturn;
+
+/**
+ * Hook to get the current customer's credits.
+ *
+ * Automatically fetches on mount and re-fetches when
+ * authentication state changes (ensures credits load
+ * even when auth resolves after initial render).
+ *
+ * @example
+ * ```tsx
+ * const { credits, displayCurrency, loading, refetch } = useBalance()
+ * ```
+ */
+declare function useBalance(): BalanceStatus;
+
+/**
+ * Headless hook for top-up amount selection.
+ *
+ * Manages quick-pick presets, custom input, mutual exclusivity, and validation.
+ * Currency-aware: presets and symbol adjust based on the ISO 4217 code.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   quickAmounts, selectedAmount, customAmount,
+ *   resolvedAmount, selectQuickAmount, setCustomAmount,
+ *   error, validate, reset, currencySymbol,
+ * } = useTopupAmountSelector({ currency: 'usd' })
+ * ```
+ */
+declare function useTopupAmountSelector(options: UseTopupAmountSelectorOptions): UseTopupAmountSelectorReturn;
+
 /**
  * Purchase utility functions
  *
@@ -921,4 +1124,4 @@ declare function getPrimaryPurchase(purchases: PurchaseInfo[]): PurchaseInfo | n
  */
 declare function isPaidPurchase(purchase: PurchaseInfo): boolean;
 
-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 };
+export { type ActivationState, AuthAdapter, BalanceBadge, type BalanceBadgeProps, type BalanceStatus, type CancelResult, 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, type PurchaseActions, PurchaseGate, type PurchaseGateProps, type PurchaseInfo, type PurchaseStatus, type PurchaseStatusReturn, type PurchaseStatusValue, type ReactivateResult, type SolvaPayConfig, type SolvaPayContextValue, SolvaPayProvider, type SolvaPayProviderProps, Spinner, StripePaymentFormWrapper, TopupForm, type TopupFormProps, type TopupPaymentResult, type UseActivationReturn, type UsePlansOptions, type UsePlansReturn, type UseTopupAmountSelectorOptions, type UseTopupAmountSelectorReturn, type UseTopupOptions, type UseTopupReturn, filterPurchases, getActivePurchases, getCancelledPurchasesWithEndDate, getMostRecentPurchase, getPrimaryPurchase, isPaidPurchase, useActivation, useBalance, useCheckout, useCustomer, usePlans, usePurchase, usePurchaseActions, usePurchaseStatus, useSolvaPay, useTopup, useTopupAmountSelector };