@solvapay/react 1.0.7 → 1.0.8-preview.2

package/dist/index.d.ts

@@ -1,524 +1,11 @@
-import React$1 from 'react';
-import * as _stripe_stripe_js from '@stripe/stripe-js';
-import { PaymentIntent, Stripe } from '@stripe/stripe-js';
-import { ProcessPaymentResult, ActivatePlanResult } from '@solvapay/server';
+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-f56UlQN-.js';
+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-f56UlQN-.js';
+import { PaymentIntent, Stripe, StripeElements } from '@stripe/stripe-js';
+import { ActivatePlanResult } from '@solvapay/server';
 export { ActivatePlanResult } from '@solvapay/server';
-import { AuthAdapter } from './adapters/auth.js';
-export { defaultAuthAdapter } from './adapters/auth.js';
-import * as react_jsx_runtime from 'react/jsx-runtime';
-
-interface PurchaseInfo {
-    reference: string;
-    productName: string;
-    productRef?: string;
-    status: string;
-    startDate: string;
-    endDate?: string;
-    cancelledAt?: string;
-    cancellationReason?: string;
-    amount?: number;
-    currency?: string;
-    planType?: string;
-    isRecurring?: boolean;
-    nextBillingDate?: string;
-    billingCycle?: string;
-    planRef?: string;
-    planSnapshot?: {
-        reference?: string;
-        price?: number;
-        meterRef?: string;
-        limit?: number;
-        freeUnits?: number;
-        creditsPerUnit?: 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 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;
-    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 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
-     * Defaults to standard Next.js API routes
-     */
-    api?: {
-        checkPurchase?: string;
-        createPayment?: string;
-        processPayment?: string;
-        createTopupPayment?: string;
-        customerBalance?: string;
-        cancelRenewal?: string;
-        reactivateRenewal?: string;
-        activatePlan?: string;
-        listPlans?: 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 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;
-        productRef?: string;
-    }) => Promise<PaymentIntentResult>;
-    processPayment?: (params: {
-        paymentIntentId: string;
-        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 {
-    /**
-     * 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>;
-    createTopupPayment?: (params: {
-        amount: number;
-        currency?: string;
-    }) => Promise<TopupPaymentResult>;
-    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 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;
-    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.
-     * Receives plan and its index (after sorting, if sortBy is provided).
-     */
-    filter?: (plan: Plan, index: number) => boolean;
-    /**
-     * Optional sort function to sort plans
-     */
-    sortBy?: (a: Plan, b: Plan) => number;
-    /**
-     * 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
- */
-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>;
-    /** True after the one-shot initial selection has been applied */
-    isSelectionReady: boolean;
-}
-/**
- * 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, index: number) => 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. 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;
-    /**
-     * Product reference. Required when planRef is omitted (for plan resolution)
-     * and 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;
-}
-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';
+export { AuthAdapter, defaultAuthAdapter } from './adapters/auth.js';
+import '@stripe/react-stripe-js';
 
 /**
  * SolvaPay Provider - Headless Context Provider for React.
@@ -599,151 +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.
- *
- * 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 (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)
- * @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
+ * Default-tree shim over the `PaymentForm` primitive.
  *
- * @example
- * ```tsx
- * // Explicit plan
- * <PaymentForm planRef="pln_premium" productRef="prd_myapi" onSuccess={...} />
+ * 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.
  *
- * // Auto-resolve plan (product must have exactly one plan or a default)
- * <PaymentForm productRef="prd_myapi" onSuccess={...} />
- * ```
+ * 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>;
 
-/**
- * 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>;
+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 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.
+ * Default-tree shim over the `TopupForm` primitive.
  *
- * @example
- * ```tsx
- * // Render prop pattern
- * <ProductBadge>
- *   {({ purchases, loading, displayPlan, shouldShow }) => (
- *     shouldShow ? (
- *       <div>{displayPlan}</div>
- *     ) : null
- *   )}
- * </ProductBadge>
- *
- * // ClassName pattern
- * <ProductBadge className="badge badge-primary" />
- * ```
+ * 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 ProductBadge: React$1.FC<ProductBadgeProps>;
-/** @deprecated Use ProductBadge instead */
-declare const PlanBadge: React$1.FC<ProductBadgeProps>;
 
-/**
- * Headless Purchase Gate Component
- *
- * Controls access to content based on purchase status.
- * Uses render props to give developers full control over locked/unlocked states.
- *
- * @example
- * ```tsx
- * <PurchaseGate requireProduct="Pro Plan">
- *   {({ hasAccess, loading }) => {
- *     if (loading) return <Skeleton />;
- *     if (!hasAccess) return <Paywall />;
- *     return <PremiumContent />;
- *   }}
- * </PurchaseGate>
- * ```
- */
-declare const PurchaseGate: React$1.FC<PurchaseGateProps>;
-
-/**
- * Headless Pricing Selector Component
- *
- * Provides pricing selection logic with complete styling control via render props.
- * Integrates plan fetching, purchase status, and selection state management.
- *
- * Features:
- * - Fetches and manages pricing options
- * - Tracks selected option
- * - Provides helpers for checking if option is current/paid
- * - Integrates with purchase context
- *
- * @example
- * ```tsx
- * <PricingSelector
- *   productRef="prd_123"
- *   fetcher={async (productRef) => {
- *     const res = await fetch(`/api/list-plans?productRef=${productRef}`);
- *     const data = await res.json();
- *     return data.plans;
- *   }}
- *   sortBy={(a, b) => (a.price || 0) - (b.price || 0)}
- *   autoSelectFirstPaid
- * >
- *   {({ plans, selectedPlan, setSelectedPlanIndex, loading, isPaidPlan, isCurrentPlan }) => (
- *     <div>
- *       {loading ? (
- *         <div>Loading...</div>
- *       ) : (
- *         plans.map((plan, index) => (
- *           <button
- *             key={plan.reference}
- *             onClick={() => setSelectedPlanIndex(index)}
- *             disabled={!isPaidPlan(plan.reference)}
- *           >
- *             ${plan.price}/{plan.interval}
- *             {isCurrentPlan(plan.reference) && ' (Current)'}
- *           </button>
- *         ))
- *       )}
- *     </div>
- *   )}
- * </PricingSelector>
- * ```
- */
-declare const PricingSelector: React$1.FC<PricingSelectorProps>;
-/** @deprecated Use PricingSelector instead */
-declare const PlanSelector: React$1.FC<PricingSelectorProps>;
+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';
 }>;
@@ -761,9 +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>;
 
-declare function BalanceBadge({ className, numberOnly, children }: BalanceBadgeProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * 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.
@@ -886,6 +462,7 @@ interface UseCheckoutReturn {
 declare function useCheckout(options: {
     planRef?: string;
     productRef?: string;
+    customer?: PrefillCustomer;
 }): UseCheckoutReturn;
 
 /**
@@ -942,6 +519,43 @@ declare function useSolvaPay(): SolvaPayContextValue;
  */
 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
  *
@@ -1067,6 +681,37 @@ declare function useBalance(): BalanceStatus;
  */
 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
  *
@@ -1124,4 +769,82 @@ declare function getPrimaryPurchase(purchases: PurchaseInfo[]): PurchaseInfo | n
  */
 declare function isPaidPurchase(purchase: PurchaseInfo): boolean;
 
-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 };
+/**
+ * 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 };