@solvapay/react 1.0.0-preview.6 → 1.0.0-preview.7

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import React$1 from 'react';
 import { PaymentIntent, Stripe } from '@stripe/stripe-js';
+import { ProcessPaymentResult } from '@solvapay/server';
 
 /**
  * TypeScript type definitions for @solvapay/react
@@ -11,6 +12,9 @@ interface SubscriptionInfo {
     agentName: string;
     status: string;
     startDate: string;
+    endDate?: string;
+    cancelledAt?: string;
+    cancellationReason?: string;
 }
 interface CustomerSubscriptionData {
     customerRef?: string;
@@ -40,6 +44,12 @@ interface SolvaPayContextValue {
         planRef: string;
         customerRef: string;
     }) => Promise<PaymentIntentResult>;
+    processPayment?: (params: {
+        paymentIntentId: string;
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
+    }) => Promise<ProcessPaymentResult>;
     customerRef?: string;
     updateCustomerRef?: (newCustomerRef: string) => void;
 }
@@ -49,6 +59,12 @@ interface SolvaPayProviderProps {
         customerRef: string;
     }) => Promise<PaymentIntentResult>;
     checkSubscription: (customerRef: string) => Promise<CustomerSubscriptionData>;
+    processPayment?: (params: {
+        paymentIntentId: string;
+        agentRef: string;
+        customerRef: string;
+        planRef?: string;
+    }) => Promise<ProcessPaymentResult>;
     customerRef?: string;
     onCustomerRefUpdate?: (newCustomerRef: string) => void;
     children: React.ReactNode;
@@ -57,6 +73,8 @@ interface PlanBadgeProps {
     children?: (props: {
         subscriptions: SubscriptionInfo[];
         loading: boolean;
+        displayPlan: string | null;
+        shouldShow: boolean;
     }) => React.ReactNode;
     as?: React.ElementType;
     className?: string | ((props: {
@@ -79,7 +97,129 @@ interface PaymentError extends Error {
     type?: string;
 }
 /**
- * Payment form props with proper Stripe types
+ * Plan interface for subscription plans
+ */
+interface Plan {
+    reference: string;
+    name: string;
+    description?: string;
+    price?: number;
+    currency?: string;
+    interval?: string;
+    features?: string[];
+    isFreeTier?: boolean;
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for usePlans hook
+ */
+interface UsePlansOptions {
+    /**
+     * Fetcher function to retrieve plans
+     */
+    fetcher: (agentRef: string) => Promise<Plan[]>;
+    /**
+     * Agent reference to fetch plans for
+     */
+    agentRef?: 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 PlanSelector component
+ */
+interface PlanSelectorProps {
+    /**
+     * Agent reference to fetch plans for
+     */
+    agentRef?: string;
+    /**
+     * Fetcher function to retrieve plans
+     */
+    fetcher: (agentRef: 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 & {
+        subscriptions: SubscriptionInfo[];
+        isPaidPlan: (planName: string) => boolean;
+        isCurrentPlan: (planName: string) => boolean;
+    }) => React.ReactNode;
+}
+/**
+ * Return type for useSubscriptionHelpers hook
+ */
+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;
+    /**
+     * Check if user has any paid subscription
+     */
+    hasPaidSubscription: boolean;
+    /**
+     * Check if should show cancelled notice
+     */
+    shouldShowCancelledNotice: boolean;
+    /**
+     * Get active plan name
+     */
+    activePlanName: string | null;
+    /**
+     * Format a date string
+     */
+    formatDate: (dateString?: string) => string | null;
+    /**
+     * Get days until a date
+     */
+    getDaysUntilExpiration: (endDate?: string) => number | null;
+}
+/**
+ * Payment form props - simplified and minimal
  */
 interface PaymentFormProps {
     /**
@@ -87,30 +227,34 @@ interface PaymentFormProps {
      * including Stripe initialization and payment intent creation.
      */
     planRef: string;
+    /**
+     * Agent reference. Required for processing payment after confirmation.
+     */
+    agentRef?: 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 (wraps form, messages, and cancel button)
+     * Optional className for the form container
      */
     className?: string;
     /**
      * Optional className for the submit button
      */
     buttonClassName?: string;
-    /**
-     * Text for the initial checkout button. If provided, shows a button first instead of
-     * auto-starting checkout.
-     */
-    initialButtonText?: string;
-    /**
-     * Text for the cancel button. Set to empty string to hide cancel button.
-     */
-    cancelButtonText?: string;
 }
 
 /**
@@ -144,9 +288,8 @@ declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
 /**
  * SolvaPay Payment Form Component
  *
- * Handles the entire checkout flow internally including Stripe initialization,
- * payment intent creation, and form rendering. Simply provide a planRef and
- * handle success/error callbacks.
+ * A simplified, minimal payment form that handles the checkout flow.
+ * Automatically initializes Stripe and displays the payment form.
  *
  * @example
  * ```tsx
@@ -154,6 +297,7 @@ declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
  *
  * <PaymentForm
  *   planRef="pro_plan"
+ *   agentRef="agent_123"
  *   onSuccess={(paymentIntent) => {
  *     console.log('Payment successful!');
  *   }}
@@ -171,14 +315,18 @@ declare const PaymentForm: React$1.FC<PaymentFormProps>;
  * Displays subscription 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).
+ *
  * @example
  * ```tsx
  * // Render prop pattern
  * <PlanBadge>
- *   {({ subscriptions, loading }) => (
- *     <div>
- *       {subscriptions.map(sub => <span key={sub.reference}>{sub.planName}</span>)}
- *     </div>
+ *   {({ subscriptions, loading, displayPlan, shouldShow }) => (
+ *     shouldShow ? (
+ *       <div>{displayPlan}</div>
+ *     ) : null
  *   )}
  * </PlanBadge>
  *
@@ -207,6 +355,75 @@ declare const PlanBadge: React$1.FC<PlanBadgeProps>;
  */
 declare const SubscriptionGate: React$1.FC<SubscriptionGateProps>;
 
+/**
+ * Headless Plan Selector Component
+ *
+ * Provides plan selection logic with complete styling control via render props.
+ * Integrates plan fetching, subscription 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
+ *
+ * @example
+ * ```tsx
+ * <PlanSelector
+ *   agentRef="agent_123"
+ *   fetcher={async (agentRef) => {
+ *     const res = await fetch(`/api/list-plans?agentRef=${agentRef}`);
+ *     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 plans...</div>
+ *       ) : (
+ *         plans.map((plan, index) => (
+ *           <button
+ *             key={plan.reference}
+ *             onClick={() => setSelectedPlanIndex(index)}
+ *             disabled={!isPaidPlan(plan.name)}
+ *           >
+ *             {plan.name} - ${plan.price}
+ *             {isCurrentPlan(plan.name) && ' (Current)'}
+ *           </button>
+ *         ))
+ *       )}
+ *     </div>
+ *   )}
+ * </PlanSelector>
+ * ```
+ */
+declare const PlanSelector: React$1.FC<PlanSelectorProps>;
+
+/**
+ * Simple spinner component using CSS animations
+ */
+declare const Spinner: React$1.FC<{
+    className?: string;
+    size?: 'sm' | 'md' | 'lg';
+}>;
+
+interface StripePaymentFormWrapperProps {
+    onSuccess?: (paymentIntent: any) => void;
+    onError?: (error: Error) => void;
+    returnUrl?: string;
+    submitButtonText?: string;
+    buttonClassName?: string;
+}
+/**
+ * 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 access subscription status
  * Returns the current subscription state and a refetch function
@@ -237,4 +454,101 @@ declare function useCheckout(planRef: string): UseCheckoutReturn;
  */
 declare function useSolvaPay(): SolvaPayContextValue;
 
-export { type CustomerSubscriptionData, type PaymentError, PaymentForm, type PaymentFormProps, type PaymentIntentResult, PlanBadge, type PlanBadgeProps, type SolvaPayContextValue, SolvaPayProvider, type SolvaPayProviderProps, SubscriptionGate, type SubscriptionGateProps, type SubscriptionInfo, type SubscriptionStatus, useCheckout, useSolvaPay, useSubscription };
+/**
+ * Hook to manage plan fetching and selection
+ *
+ * Provides a reusable way to fetch, filter, sort and select subscription plans.
+ * Handles loading and error states automatically.
+ *
+ * @example
+ * ```tsx
+ * const plans = usePlans({
+ *   agentRef: 'agent_123',
+ *   fetcher: async (agentRef) => {
+ *     const res = await fetch(`/api/list-plans?agentRef=${agentRef}`);
+ *     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 helper functions for subscription 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
+ *
+ * @example
+ * ```tsx
+ * const helpers = useSubscriptionHelpers(plans);
+ *
+ * if (helpers.isPaidPlan('Pro Plan')) {
+ *   // Handle paid plan
+ * }
+ *
+ * const daysLeft = helpers.getDaysUntilExpiration(subscription.endDate);
+ * ```
+ */
+declare function useSubscriptionHelpers(plans: Plan[]): SubscriptionHelpersReturn;
+
+/**
+ * Subscription utility functions
+ *
+ * Provides shared logic for filtering and prioritizing subscriptions
+ */
+
+/**
+ * Filter subscriptions based on cancellation status and endDate
+ *
+ * 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
+ */
+declare function filterSubscriptions(subscriptions: SubscriptionInfo[]): SubscriptionInfo[];
+/**
+ * Get active subscriptions (excluding cancelled ones)
+ * Also excludes subscriptions with cancelledAt set, even if status is still 'active'
+ */
+declare function getActiveSubscriptions(subscriptions: SubscriptionInfo[]): SubscriptionInfo[];
+/**
+ * Get cancelled subscriptions with valid endDate (not expired)
+ * Includes subscriptions with cancelledAt set, even if status is still 'active'
+ */
+declare function getCancelledSubscriptionsWithEndDate(subscriptions: SubscriptionInfo[]): SubscriptionInfo[];
+/**
+ * Get the most recent subscription by startDate
+ */
+declare function getMostRecentSubscription(subscriptions: SubscriptionInfo[]): SubscriptionInfo | null;
+/**
+ * Get the primary subscription 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
+ */
+declare function getPrimarySubscription(subscriptions: SubscriptionInfo[]): SubscriptionInfo | null;
+/**
+ * Check if user has an active paid subscription
+ *
+ * @param subscriptions - Array of subscriptions
+ * @param isPaidPlan - Function to check if a plan name represents a paid plan
+ */
+declare function hasActivePaidSubscription(subscriptions: SubscriptionInfo[], isPaidPlan: (planName: string) => boolean): 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 };