@solvapay/react 1.0.6 → 1.0.8-preview.1

package/dist/index.d.cts

@@ -1,375 +1,11 @@
-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 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;
-}
-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;
-    /**
-     * 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';
+import React from 'react';
+import { S as SolvaPayProviderProps, P as PaymentFormProps, a as PrefillCustomer, b as PaymentFormSummary, c as PaymentFormCustomerFields, d as PaymentFormPaymentElement, e as PaymentFormCardElement, f as PaymentFormMandateText, g as PaymentFormTermsCheckbox, h as PaymentFormSubmitButton, i as PaymentFormLoading, j as PaymentFormError, T as TopupFormProps, C as CheckoutResult, k as Plan, A as ActivationResult, l as PurchaseStatus, m as SolvaPayContextValue, U as UsePlansOptions, n as UsePlansReturn, o as UsePlanOptions, p as UsePlanReturn, q as UseProductReturn, r as UseMerchantReturn, s as SolvaPayCopy, t as PurchaseStatusReturn, u as CancelResult, R as ReactivateResult, v as UseTopupOptions, w as UseTopupReturn, B as BalanceStatus, x as UseTopupAmountSelectorOptions, y as UseTopupAmountSelectorReturn, z as PartialSolvaPayCopy, D as PurchaseInfo, E as CheckoutVariant, F as Product } from './CancelPlanButton-CieT9swn.cjs';
+export { G as ActivationFlowStep, H as BalanceBadge, I as CancelPlanButton, J as CheckoutSummary, K as CheckoutSummaryProps, L as CustomerPurchaseData, M as MandateContext, N as MandateTemplate, O as MandateText, Q as MandateTextProps, V as Merchant, W as PaymentError, X as PaymentIntentResult, Y as PaymentResult, Z as PlanBadge, _ as ProductBadge, $ as PurchaseGate, a0 as PurchaseStatusValue, a1 as SolvaPayConfig, a2 as TopupPaymentResult, a3 as deriveVariant } from './CancelPlanButton-CieT9swn.cjs';
+import { PaymentIntent, Stripe, StripeElements } from '@stripe/stripe-js';
+import { ActivatePlanResult } from '@solvapay/server';
+export { ActivatePlanResult } from '@solvapay/server';
+export { AuthAdapter, defaultAuthAdapter } from './adapters/auth.cjs';
+import '@stripe/react-stripe-js';
 
 /**
  * SolvaPay Provider - Headless Context Provider for React.
@@ -450,163 +86,56 @@ type PurchaseStatusValue = 'pending' | 'active' | 'trialing' | 'past_due' | 'can
  * @see {@link useSolvaPay} for accessing provider methods
  * @since 1.0.0
  */
-declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
+declare const SolvaPayProvider: React.FC<SolvaPayProviderProps>;
 
 /**
- * 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
+ * Default-tree shim over the `PaymentForm` primitive.
+ *
+ * Consumers who just want a drop-in payment form use this component. It
+ * renders the primitive's Root with a golden-path default tree composed of
+ * `PaymentForm.Summary`, `CustomerFields`, `PaymentElement`, `MandateText`,
+ * an optional `TermsCheckbox`, and `SubmitButton`. Free-plan activation
+ * flows through the same composition — `FreeInner` in the primitive swaps
+ * the submit handler so the default tree works identically for paid and
+ * free plans.
+ *
+ * Full control (swap PaymentElement for CardElement, reorder, compose with
+ * shadcn/Tailwind) is available via the primitives at
+ * `@solvapay/react/primitives`.
  */
-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.
- *
- * Hidden before initial data load or when no active purchase exists.
- * Remains visible during background refetches to avoid flickering.
- *
- * @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>;
+type PaymentFormRootProps = PaymentFormProps & {
+    prefillCustomer?: PrefillCustomer;
+    requireTermsAcceptance?: boolean;
+    children?: React.ReactNode;
+};
+declare const PaymentForm: React.FC<PaymentFormRootProps> & {
+    Summary: typeof PaymentFormSummary;
+    CustomerFields: typeof PaymentFormCustomerFields;
+    PaymentElement: typeof PaymentFormPaymentElement;
+    CardElement: typeof PaymentFormCardElement;
+    MandateText: typeof PaymentFormMandateText;
+    TermsCheckbox: typeof PaymentFormTermsCheckbox;
+    SubmitButton: typeof PaymentFormSubmitButton;
+    Loading: typeof PaymentFormLoading;
+    Error: typeof PaymentFormError;
+};
 
 /**
- * Headless Purchase Gate Component
- *
- * Controls access to content based on purchase status.
- * Uses render props to give developers full control over locked/unlocked states.
+ * Default-tree shim over the `TopupForm` primitive.
  *
- * @example
- * ```tsx
- * <PurchaseGate requireProduct="Pro Plan">
- *   {({ hasAccess, loading }) => {
- *     if (loading) return <Skeleton />;
- *     if (!hasAccess) return <Paywall />;
- *     return <PremiumContent />;
- *   }}
- * </PurchaseGate>
- * ```
+ * Drops in a golden-path credit top-up form: Stripe `PaymentElement` +
+ * submit button + loading/error states. Full control is available by
+ * composing the primitive at `@solvapay/react/primitives`.
  */
-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>;
+declare const TopupForm: React.FC<TopupFormProps>;
 
 /**
  * SVG-based spinner component using CSS animations
  * Uses the same spinner design as the rest of the site
  */
-declare const Spinner: React$1.FC<{
+declare const Spinner: React.FC<{
     className?: string;
     size?: 'sm' | 'md' | 'lg';
 }>;
@@ -624,7 +153,193 @@ interface StripePaymentFormWrapperProps {
  * 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>;
+declare const StripePaymentFormWrapper: React.FC<StripePaymentFormWrapperProps>;
+
+/**
+ * Opinionated one-line drop-in checkout built on top of `PlanSelector`,
+ * `PaymentForm`, and `ActivationFlow`. Renders the select → pay | activate
+ * machine internally, and auto-skips the select step when a product has a
+ * single selectable plan.
+ *
+ * Styling is done entirely via the `solvapay-*` class names documented in
+ * PR 5's `styles.css`. No inline styles. Full control (custom layouts,
+ * alternate CTAs, multi-step wizards) is available by composing the
+ * primitives at `@solvapay/react/primitives` directly.
+ */
+
+type CheckoutLayoutSize = 'chat' | 'mobile' | 'desktop' | 'auto';
+type CheckoutLayoutPlanSelectorOptions = {
+    filter?: (plan: Plan, index: number) => boolean;
+    sortBy?: (a: Plan, b: Plan) => number;
+    popularPlanRef?: string;
+};
+type CheckoutLayoutProps = {
+    /**
+     * Plan reference. When passed, skips plan selection and goes directly to
+     * payment or activation (routed based on plan type). Backwards compatible
+     * with today's payment-only behavior for non-usage-based plans.
+     */
+    planRef?: string;
+    productRef?: string;
+    prefillCustomer?: PrefillCustomer;
+    size?: CheckoutLayoutSize;
+    requireTermsAcceptance?: boolean;
+    /**
+     * Fires on paid completions only — preserved for backwards compatibility.
+     * For a unified callback across paid + activated flows, use `onResult`.
+     */
+    onSuccess?: (paymentIntent: PaymentIntent) => void;
+    /** Unified completion callback (paid + activated). */
+    onResult?: (result: CheckoutResult) => void;
+    /** Override the default free-plan activation step. Forwarded to PaymentForm. */
+    onFreePlan?: (plan: Plan) => Promise<unknown> | void;
+    onError?: (error: Error) => void;
+    /** Initial selection when rendering the selector step. */
+    initialPlanRef?: string;
+    /** Callback when the user picks a plan from the selector. */
+    onPlanSelect?: (planRef: string, plan: Plan) => void;
+    /** Controls for the internal `<PlanSelector>`. */
+    planSelector?: CheckoutLayoutPlanSelectorOptions;
+    /** Hide the "← Back to plans" affordance on the pay step. Defaults to true. */
+    showBackButton?: boolean;
+    submitButtonText?: string;
+    returnUrl?: string;
+};
+declare const CheckoutLayout: React.FC<CheckoutLayoutProps>;
+
+/**
+ * Default-tree shim over the `PlanSelector` primitive.
+ *
+ * Consumers who want a drop-in grid of plan cards use this component.
+ * Consumers who want full control compose `@solvapay/react/primitives`
+ * directly.
+ */
+
+interface PlanSelectorProps {
+    productRef: string;
+    fetcher?: (productRef: string) => Promise<Plan[]>;
+    filter?: (plan: Plan, index: number) => boolean;
+    sortBy?: (a: Plan, b: Plan) => number;
+    autoSelectFirstPaid?: boolean;
+    initialPlanRef?: string;
+    currentPlanRef?: string | null;
+    popularPlanRef?: string;
+    onSelect?: (planRef: string, plan: Plan) => void;
+    className?: string;
+    children?: React.ReactNode;
+}
+declare const PlanSelector: React.FC<PlanSelectorProps>;
+
+/**
+ * Default-tree shim over the `AmountPicker` primitive.
+ *
+ * Renders the golden-path pills + custom input combo consumers expect in
+ * drop-in usage. For full control (alternate layouts, custom confirm
+ * affordance, Tailwind variants), compose
+ * `@solvapay/react/primitives` directly.
+ */
+
+interface AmountPickerProps {
+    currency: string;
+    minAmount?: number;
+    maxAmount?: number;
+    showCreditEstimate?: boolean;
+    onChange?: (amount: number | null) => void;
+    className?: string;
+}
+declare const AmountPicker: React.FC<AmountPickerProps>;
+
+/**
+ * Default-tree shim over the `ActivationFlow` primitive.
+ *
+ * Renders the full usage-based activation state machine (summary →
+ * activating → selectAmount → topupPayment → retrying → activated | error)
+ * with the golden-path copy, the embedded `<CheckoutSummary>` + `<TopupForm>`,
+ * and an optional back button. Full control is available by composing the
+ * primitive at `@solvapay/react/primitives`.
+ */
+
+interface ActivationFlowProps {
+    productRef: string;
+    planRef?: string;
+    onSuccess?: (result: ActivationResult) => void;
+    onError?: (error: Error) => void;
+    onBack?: () => void;
+    retryDelayMs?: number;
+    retryBackoffMs?: number;
+    className?: string;
+}
+declare const ActivationFlow: React.FC<ActivationFlowProps>;
+
+/**
+ * Default-tree shim over the `CancelledPlanNotice` primitive.
+ *
+ * Renders the full cancellation banner (heading, expiry, days remaining,
+ * access-until, cancellation date, reason, reactivate CTA) when the
+ * customer has a cancelled-but-still-active purchase. Renders `null`
+ * otherwise.
+ */
+
+interface CancelledPlanNoticeProps {
+    onReactivated?: () => void;
+    onError?: (error: Error) => void;
+    className?: string;
+}
+declare const CancelledPlanNotice: React.FC<CancelledPlanNoticeProps>;
+
+/**
+ * Default-tree shim over the `CreditGate` primitive.
+ *
+ * Renders `children` when the customer has enough credits, otherwise renders
+ * a default top-up prompt (Heading + Subheading + Topup) or a user-provided
+ * `fallback`. Full control is available via
+ * `@solvapay/react/primitives` — compose `CreditGate.Root` with your own
+ * subcomponent arrangement.
+ */
+
+interface CreditGateProps {
+    minCredits?: number;
+    productRef?: string;
+    topupAmount?: number;
+    topupCurrency?: string;
+    fallback?: React.ReactNode;
+    className?: string;
+    children?: React.ReactNode;
+}
+declare const CreditGate: React.FC<CreditGateProps>;
+
+type PaymentElementKind = 'payment-element' | 'card-element' | null;
+interface PaymentFormContextValue {
+    planRef?: string;
+    productRef?: string;
+    prefillCustomer?: PrefillCustomer;
+    resolvedPlanRef: string | null;
+    plan: Plan | null;
+    clientSecret: string | null;
+    stripe: Stripe | null;
+    elements: StripeElements | null;
+    isProcessing: boolean;
+    isReady: boolean;
+    paymentInputComplete: boolean;
+    termsAccepted: boolean;
+    requireTermsAcceptance: boolean;
+    canSubmit: boolean;
+    error: string | null;
+    elementKind: PaymentElementKind;
+    returnUrl: string;
+    submitButtonText?: string;
+    buttonClassName?: string;
+    setElementKind: (k: PaymentElementKind) => void;
+    setPaymentInputComplete: (complete: boolean) => void;
+    setTermsAccepted: (accepted: boolean) => void;
+    submit: () => Promise<void>;
+}
+declare const PaymentFormContext: React.Context<PaymentFormContextValue | null>;
+declare function usePaymentForm(): PaymentFormContextValue;
+declare const PaymentFormProvider: React.FC<{
+    value: PaymentFormContextValue;
+    children: React.ReactNode;
+}>;
 
 /**
  * Hook to get current purchase status and information.
@@ -719,61 +434,35 @@ 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',
- *   });
+ * // Explicit planRef (no resolution needed)
+ * const checkout = 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>
- *   );
- * }
+ * // 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;
+    customer?: PrefillCustomer;
 }): UseCheckoutReturn;
 
 /**
@@ -820,32 +509,53 @@ declare function useCheckout(options: {
 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.
+ * Hook to manage plan fetching and selection.
  *
- * @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;
 
+/**
+ * Hook to load a single plan by reference.
+ *
+ * When `productRef` is known, piggybacks on the `usePlans` cache so there's
+ * no extra fetch. Otherwise fetches the full plan list and filters.
+ */
+declare function usePlan(options: UsePlanOptions): UsePlanReturn;
+
+/**
+ * Hook to load a single product by reference. Uses a module-level
+ * single-flight cache keyed by `productRef` so concurrent consumers share the
+ * same in-flight request.
+ */
+declare function useProduct(productRef: string | undefined): UseProductReturn;
+
+/**
+ * Hook to load merchant identity (legal name, support email, terms/privacy
+ * URLs, ...) for rendering mandate copy and trust signals.
+ *
+ * Uses a module-level single-flight cache keyed by the configured route so
+ * concurrent consumers share one in-flight request and response.
+ */
+declare function useMerchant(): UseMerchantReturn;
+
+/**
+ * Read the merged copy bundle from context. Used by every SDK component that
+ * renders user-visible strings; consumers rarely call it directly but it's
+ * exported as an escape hatch for custom UIs.
+ */
+declare function useCopy(): SolvaPayCopy;
+/**
+ * Current locale string (e.g. `'en'`, `'sv-SE'`). Used to thread the locale
+ * through `Intl.NumberFormat`, `Intl.DateTimeFormat`, and Stripe Elements.
+ * `undefined` means "runtime default".
+ */
+declare function useLocale(): string | undefined;
+
 /**
  * Hook providing advanced status and helper functions for purchase management
  *
@@ -864,6 +574,144 @@ 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;
+
+type CopyContextValue = {
+    locale?: string;
+    copy: SolvaPayCopy;
+};
+declare const CopyContext: React.Context<CopyContextValue>;
+type CopyProviderProps = {
+    locale?: string;
+    copy?: PartialSolvaPayCopy;
+    children: React.ReactNode;
+};
+declare const CopyProvider: React.FC<CopyProviderProps>;
+
+/**
+ * Canonical English copy. Preserves the exact copy shipped before the i18n
+ * refactor so no visible behavior changes for English consumers.
+ */
+declare const enCopy: SolvaPayCopy;
+
+/**
+ * Tiny templating helper: replaces `{name}` tokens in `template` with values
+ * from `vars`. Missing keys are left as-is so integrators can spot typos.
+ */
+declare function interpolate(template: string, vars: Record<string, string | number | undefined>): string;
+
+/**
+ * Shallow-per-section merge over the default English bundle. Each top-level
+ * section of `SolvaPayCopy` is itself a flat record, so a two-level spread is
+ * sufficient — no recursive walk needed.
+ */
+declare function mergeCopy(defaults: SolvaPayCopy, overrides?: PartialSolvaPayCopy): SolvaPayCopy;
+
 /**
  * Purchase utility functions
  *
@@ -921,4 +769,82 @@ 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 };
+/**
+ * Currency + interval price formatting utilities.
+ *
+ * `formatPrice` renders a minor-unit amount with `Intl.NumberFormat`, handling
+ * locale, symbol placement, zero-decimal currencies (JPY, KRW, ...), and an
+ * optional trailing interval suffix ("/ month", "/ 3 months").
+ */
+type FormatPriceOptions = {
+    /** BCP-47 locale tag. Falls back to the runtime default. */
+    locale?: string;
+    /** Recurring interval unit in English. Localize via the copy bundle if needed. */
+    interval?: string;
+    /** How many of `interval` per billing cycle. Defaults to 1. */
+    intervalCount?: number;
+    /**
+     * Copy used when `amountMinor` is 0. Defaults to `'Free'`.
+     * Pass `''` to disable the zero-check and always render the numeric zero.
+     */
+    free?: string;
+};
+declare function formatPrice(amountMinor: number, currency: string, opts?: FormatPriceOptions): string;
+
+type ResolveCtaInput = {
+    variant: CheckoutVariant;
+    plan?: Plan | null;
+    product?: Product | null;
+    amountFormatted: string;
+    copy: SolvaPayCopy;
+    /** Caller-provided override; short-circuits derivation. */
+    override?: string;
+};
+/**
+ * Build the submit-button label. Keeps the mapping between plan type and CTA
+ * in one place so the button, the aria-label, and `<MandateText>` agree.
+ */
+declare function resolveCta(input: ResolveCtaInput): string;
+
+type ConfirmPaymentMode = 'payment-element' | 'card-element';
+type ConfirmPaymentInput = {
+    stripe: Stripe;
+    elements: StripeElements;
+    clientSecret: string;
+    mode: ConfirmPaymentMode;
+    returnUrl: string;
+    /** Billing details from `useCustomer()` (echoed from backend). */
+    billingDetails?: {
+        email?: string;
+        name?: string;
+    };
+    /**
+     * When true, skip the browser redirect during PaymentElement confirmation
+     * and resolve only if the intent finishes synchronously. This is what
+     * SolvaPay's inline forms want so `onSuccess` fires in the same tab.
+     */
+    redirectIfRequired?: boolean;
+    /** Copy bundle for human-readable status messages. */
+    copy: SolvaPayCopy;
+};
+type ConfirmPaymentResult = {
+    status: 'succeeded';
+    paymentIntent: PaymentIntent;
+} | {
+    status: 'requires_action';
+    message: string;
+} | {
+    status: 'other';
+    message: string;
+    paymentIntent?: PaymentIntent;
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Wrap Stripe confirmation so callers don't have to branch between
+ * `confirmPayment` (PaymentElement) and `confirmCardPayment` (CardElement).
+ */
+declare function confirmPayment(input: ConfirmPaymentInput): Promise<ConfirmPaymentResult>;
+
+export { ActivationFlow, type ActivationFlowProps, ActivationResult, type ActivationState, AmountPicker, type AmountPickerProps, BalanceStatus, CancelResult, CancelledPlanNotice, type CancelledPlanNoticeProps, CheckoutLayout, type CheckoutLayoutPlanSelectorOptions, type CheckoutLayoutProps, type CheckoutLayoutSize, CheckoutResult, CheckoutVariant, type ConfirmPaymentInput, type ConfirmPaymentMode, type ConfirmPaymentResult, CopyContext, CopyProvider, CreditGate, type CreditGateProps, type CustomerInfo, type FormatPriceOptions, PartialSolvaPayCopy, type PaymentElementKind, PaymentForm, PaymentFormContext, type PaymentFormContextValue, PaymentFormProps, PaymentFormProvider, Plan, PlanSelector, type PlanSelectorProps, PrefillCustomer, Product, type PurchaseActions, PurchaseInfo, PurchaseStatus, PurchaseStatusReturn, ReactivateResult, SolvaPayContextValue, SolvaPayCopy, SolvaPayProvider, SolvaPayProviderProps, Spinner, StripePaymentFormWrapper, TopupForm, TopupFormProps, type UseActivationReturn, UseMerchantReturn, UsePlanOptions, UsePlanReturn, UsePlansOptions, UsePlansReturn, UseProductReturn, UseTopupAmountSelectorOptions, UseTopupAmountSelectorReturn, UseTopupOptions, UseTopupReturn, confirmPayment, enCopy, filterPurchases, formatPrice, getActivePurchases, getCancelledPurchasesWithEndDate, getMostRecentPurchase, getPrimaryPurchase, interpolate, isPaidPurchase, mergeCopy, resolveCta, useActivation, useBalance, useCheckout, useCopy, useCustomer, useLocale, useMerchant, usePaymentForm, usePlan, usePlans, useProduct, usePurchase, usePurchaseActions, usePurchaseStatus, useSolvaPay, useTopup, useTopupAmountSelector };