@solvapay/react 1.0.9-preview.1 → 1.0.9

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';
-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';
+import React from 'react';
+import { S as SolvaPayProviderProps, P as PaymentFormProps, a as PrefillCustomer, T as TopupFormProps, C as CheckoutResult, b as Plan, A as ActivationResult, c as PurchaseStatus, d as SolvaPayContextValue, U as UsePlansOptions, e as UsePlansReturn, f as UsePlanOptions, g as UsePlanReturn, h as UseProductReturn, i as UseMerchantReturn, j as SolvaPayCopy, k as PurchaseStatusReturn, l as CancelResult, R as ReactivateResult, m as ActivatePlanResult, n as UseTopupOptions, o as UseTopupReturn, B as BalanceStatus, p as UseTopupAmountSelectorOptions, q as UseTopupAmountSelectorReturn, r as UsePaymentMethodReturn, s as SolvaPayTransport, t as PaywallStructuredContent, u as PartialSolvaPayCopy, v as PurchaseInfo, w as Product, x as SolvaPayConfig } from './index-onWNU7iT.js';
+export { y as CustomerPurchaseData, M as MandateContext, z as MandateTemplate, D as Merchant, E as PaymentError, F as PaymentIntentResult, G as PaymentMethodInfo, H as PaymentResult, I as PurchaseStatusValue, J as TopupPaymentResult, K as TransportBalanceResult, L as TransportCheckoutSessionResult, N as TransportCustomerSessionResult, O as UnsupportedTransportMethodError } from './index-onWNU7iT.js';
+import { P as PaymentFormSummary, a as PaymentFormCustomerFields, b as PaymentFormPaymentElement, c as PaymentFormCardElement, d as PaymentFormMandateText, e as PaymentFormTermsCheckbox, f as PaymentFormSubmitButton, g as PaymentFormLoading, h as PaymentFormError, C as CheckoutVariant } from './useUsage-nD7zwSbG.js';
+export { A as ActivationFlowStep, B as BalanceBadge, i as CancelPlanButton, j as CheckoutSummary, k as CheckoutSummaryProps, M as MandateText, l as MandateTextProps, m as PlanBadge, n as ProductBadge, o as PurchaseGate, U as UsageSnapshot, p as UseUsageReturn, q as deriveVariant, u as useUsage } from './useUsage-nD7zwSbG.js';
+import { PaymentIntent, Stripe, StripeElements } from '@stripe/stripe-js';
+export { AuthAdapter, defaultAuthAdapter } from './adapters/auth.js';
+import '@stripe/react-stripe-js';
 
 /**
  * SolvaPay Provider - Headless Context Provider for React.
@@ -527,243 +14,415 @@ type PurchaseStatusValue = 'pending' | 'active' | 'trialing' | 'past_due' | 'can
  * via React Context. This is the root component that must wrap your app to use
  * SolvaPay React hooks and components.
  *
- * Features:
- * - Automatic purchase status checking
- * - Customer reference caching in localStorage
- * - Payment intent creation and processing
- * - Authentication adapter support (Supabase, custom, etc.)
- * - Zero-config with sensible defaults, or full customization
- *
- * @param props - Provider configuration
- * @param props.config - Configuration object for API routes and authentication
- * @param props.config.api - API route configuration (optional, uses defaults if not provided)
- * @param props.config.api.checkPurchase - Endpoint for checking purchase status (default: '/api/check-purchase')
- * @param props.config.api.createPayment - Endpoint for creating payment intents (default: '/api/create-payment-intent')
- * @param props.config.api.processPayment - Endpoint for processing payments (default: '/api/process-payment')
- * @param props.config.auth - Authentication configuration (optional)
- * @param props.config.auth.adapter - Auth adapter for extracting user ID and token
- * @param props.children - React children components
+ * All data access flows through `config.transport`. When omitted, a default
+ * HTTP transport is built from `config.api` + `config.fetch`. Integrators who
+ * need to route calls somewhere else (e.g. MCP hosts) pass a custom transport
+ * — see `@solvapay/react/mcp` and `createHttpTransport` for building blocks.
  *
  * @example
  * ```tsx
- * import { SolvaPayProvider } from '@solvapay/react';
+ * import { SolvaPayProvider } from '@solvapay/react'
  *
- * // Zero config (uses defaults)
  * function App() {
  *   return (
  *     <SolvaPayProvider>
  *       <YourApp />
  *     </SolvaPayProvider>
- *   );
+ *   )
  * }
+ * ```
  *
- * // Custom API routes
- * function App() {
- *   return (
- *     <SolvaPayProvider
- *       config={{
- *         api: {
- *           checkPurchase: '/custom/api/purchase',
- *           createPayment: '/custom/api/payment'
- *         }
- *       }}
- *     >
- *       <YourApp />
- *     </SolvaPayProvider>
- *   );
- * }
+ * @example MCP App
+ * ```tsx
+ * import { SolvaPayProvider } from '@solvapay/react'
+ * import { createMcpAppAdapter } from '@solvapay/react/mcp'
  *
- * // With Supabase auth adapter
- * import { createSupabaseAuthAdapter } from '@solvapay/react-supabase';
+ * const transport = createMcpAppAdapter(app)
  *
  * function App() {
- *   const adapter = createSupabaseAuthAdapter({
- *     supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
- *     supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
- *   });
- *
  *   return (
- *     <SolvaPayProvider
- *       config={{
- *         auth: { adapter }
- *       }}
- *     >
+ *     <SolvaPayProvider config={{ transport }}>
  *       <YourApp />
  *     </SolvaPayProvider>
- *   );
+ *   )
  * }
  * ```
- *
- * @see {@link usePurchase} for accessing purchase data
- * @see {@link useCheckout} for payment checkout flow
- * @see {@link useSolvaPay} for accessing provider methods
- * @since 1.0.0
  */
-declare const SolvaPayProvider: React$1.FC<SolvaPayProviderProps>;
+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
- *
- * @example
- * ```tsx
- * // Explicit plan
- * <PaymentForm planRef="pln_premium" productRef="prd_myapi" onSuccess={...} />
- *
- * // Auto-resolve plan (product must have exactly one plan or a default)
- * <PaymentForm productRef="prd_myapi" onSuccess={...} />
- * ```
+ * 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>;
+
+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;
+};
 
 /**
- * Credit top-up form with Stripe Elements.
+ * Default-tree shim over the `TopupForm` primitive.
  *
- * 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.
+ * 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 TopupForm: React$1.FC<TopupFormProps>;
+
+declare const TopupForm: React.FC<TopupFormProps>;
 
 /**
- * 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" />
- * ```
+ * SDK-scoped SVG spinner. Self-contained: SVG `width`/`height` and inline
+ * stroke/fill opacity guarantee the visual regardless of consumer CSS.
+ * Rotation is driven by the `[data-solvapay-spinner]` rule in `styles.css`,
+ * so it only animates when consumers import `@solvapay/react/styles.css`
+ * (or target the attribute themselves).
+ */
+declare const SIZE_PX: {
+    readonly sm: 16;
+    readonly md: 20;
+    readonly lg: 24;
+};
+declare const Spinner: React.FC<{
+    className?: string;
+    size?: keyof typeof SIZE_PX;
+}>;
+
+interface StripePaymentFormWrapperProps {
+    onSuccess?: (paymentIntent: unknown) => void | Promise<void>;
+    onError?: (error: Error) => void;
+    returnUrl?: string;
+    submitButtonText?: string;
+    buttonClassName?: string;
+    clientSecret: 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 ProductBadge: React$1.FC<ProductBadgeProps>;
-/** @deprecated Use ProductBadge instead */
-declare const PlanBadge: React$1.FC<ProductBadgeProps>;
+declare const StripePaymentFormWrapper: React.FC<StripePaymentFormWrapperProps>;
 
 /**
- * Headless Purchase Gate Component
+ * 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.
  *
- * Controls access to content based on purchase status.
- * Uses render props to give developers full control over locked/unlocked states.
+ * 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.
  *
- * @example
- * ```tsx
- * <PurchaseGate requireProduct="Pro Plan">
- *   {({ hasAccess, loading }) => {
- *     if (loading) return <Skeleton />;
- *     if (!hasAccess) return <Paywall />;
- *     return <PremiumContent />;
- *   }}
- * </PurchaseGate>
- * ```
+ * 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.
  */
-declare const PurchaseGate: React$1.FC<PurchaseGateProps>;
+
+interface AmountPickerProps {
+    currency: string;
+    minAmount?: number;
+    maxAmount?: number;
+    showCreditEstimate?: boolean;
+    onChange?: (amount: number | null) => void;
+    className?: string;
+}
+declare const AmountPicker: React.FC<AmountPickerProps>;
 
 /**
- * Headless Pricing Selector Component
+ * Default-tree shim over the `ActivationFlow` primitive.
  *
- * Provides pricing selection logic with complete styling control via render props.
- * Integrates plan fetching, purchase status, and selection state management.
+ * 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.
  *
- * Features:
- * - Fetches and manages pricing options
- * - Tracks selected option
- * - Provides helpers for checking if option is current/paid
- * - Integrates with purchase context
+ * 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.
  *
- * @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>
- * ```
+ * 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.
  */
-declare const PricingSelector: React$1.FC<PricingSelectorProps>;
-/** @deprecated Use PricingSelector instead */
-declare const PlanSelector: React$1.FC<PricingSelectorProps>;
+
+interface CreditGateProps {
+    minCredits?: number;
+    productRef?: string;
+    topupAmount?: number;
+    topupCurrency?: string;
+    fallback?: React.ReactNode;
+    className?: string;
+    children?: React.ReactNode;
+}
+declare const CreditGate: React.FC<CreditGateProps>;
 
 /**
- * SVG-based spinner component using CSS animations
- * Uses the same spinner design as the rest of the site
+ * `<CurrentPlanCard>` — summary card for the customer's active purchase.
+ *
+ * Pure projection of existing provider state (`usePurchase`,
+ * `usePurchaseStatus`, `useBalance`, `usePaymentMethod`) plus Phase 1
+ * action components (`<CancelPlanButton>`, Phase 2's
+ * `<UpdatePaymentMethodButton>`). No Stripe Elements dependency, so the
+ * default tree renders identically inside an MCP host sandbox and a
+ * standalone HTTP app.
+ *
+ * Returns `null` when `usePurchase()` reports no active purchase, so
+ * integrators can drop it into account pages without wrapping in
+ * `{hasPaidPurchase && ...}`.
+ *
+ * Plan-type-aware lines:
+ * - `recurring` — "Next billing: {date}"
+ * - `one-time`  — "Expires {date}" or "Valid indefinitely"
+ * - `usage-based` — `<BalanceBadge>` line; no date
  */
-declare const Spinner: React$1.FC<{
+
+interface CurrentPlanCardClassNames {
+    root?: string;
+    heading?: string;
+    planName?: string;
+    productContext?: string;
+    price?: string;
+    dateLine?: string;
+    balanceLine?: string;
+    usageMeter?: string;
+    paymentMethod?: string;
+    actions?: string;
+}
+interface CurrentPlanCardProps {
+    /** Hide the payment-method line even when the endpoint returns a card. Default: `false`. */
+    hidePaymentMethod?: boolean;
+    /** Hide the "Cancel plan" action. Default: `false`. */
+    hideCancelButton?: boolean;
+    /** Hide the "Update card" action. Default: `false`. */
+    hideUpdatePaymentButton?: boolean;
+    /**
+     * Hide the `<UsageMeter>` that automatically renders for usage-based
+     * plans. Default: `false` (meter renders whenever the active plan has
+     * a quota).
+     */
+    hideUsageMeter?: boolean;
+    /** Per-element classNames. */
+    classNames?: CurrentPlanCardClassNames;
+    /**
+     * Custom className on the root. Appended after `solvapay-current-plan-card`
+     * so integrators can tweak without losing the SDK baseline.
+     */
     className?: string;
-    size?: 'sm' | 'md' | 'lg';
-}>;
+}
+declare const CurrentPlanCard: React.FC<CurrentPlanCardProps>;
 
-interface StripePaymentFormWrapperProps {
-    onSuccess?: (paymentIntent: unknown) => void | Promise<void>;
+/**
+ * `<LaunchCustomerPortalButton>` — opens the SolvaPay hosted customer
+ * portal in a new browser tab.
+ *
+ * Works identically in HTTP and MCP contexts because it routes through
+ * `transport.createCustomerSession()` (either HTTP `/api/create-customer-session`
+ * or MCP `create_customer_session` tool). The portal URL is pre-fetched on
+ * mount so the click handler can navigate via a real `<a target="_blank">`,
+ * which MCP host sandboxes permit (scripted `window.open` after an async
+ * round-trip is blocked — see `mcp-checkout-app` for prior art).
+ */
+
+interface LaunchCustomerPortalButtonProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'target' | 'rel' | 'onError'> {
+    /** Override the default "Manage billing" label. */
+    children?: React.ReactNode;
+    /** Called immediately before the user navigates to `href`. */
+    onLaunch?: (href: string) => void;
+    /** Called when the portal session fetch fails. */
     onError?: (error: Error) => void;
-    returnUrl?: string;
-    submitButtonText?: string;
-    buttonClassName?: string;
-    clientSecret: string;
+    /** Optional className applied to the disabled <button> shown while loading. */
+    loadingClassName?: string;
+    /** Optional className applied to the disabled <button> shown on error. */
+    errorClassName?: string;
+    /**
+     * Render the ready-state anchor via `Slot` so consumers can substitute
+     * their own element (typically a real `<button>`) while preserving the
+     * `href`, `target`, `rel`, and click chain. The loading/error fallback
+     * buttons are untouched — `asChild` only swaps the ready-state shell.
+     */
+    asChild?: boolean;
 }
+declare const LaunchCustomerPortalButton: React.ForwardRefExoticComponent<LaunchCustomerPortalButtonProps & React.RefAttributes<HTMLAnchorElement>>;
+
 /**
- * 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
+ * `<UpdatePaymentMethodButton>` — trigger that opens the SolvaPay hosted
+ * customer portal so the customer can update their card on file.
+ *
+ * This MCP-first slice ships `mode="portal"` only (thin wrapper around
+ * `<LaunchCustomerPortalButton>`). A future Lovable-focused PR will add
+ * `mode="inline"` — a drawer containing `<PaymentMethodForm>` (Stripe
+ * Elements + SetupIntent). The `mode` prop is defined now so the API
+ * stays stable across both PRs.
  */
-declare const StripePaymentFormWrapper: React$1.FC<StripePaymentFormWrapperProps>;
 
-declare function BalanceBadge({ className, numberOnly, children }: BalanceBadgeProps): react_jsx_runtime.JSX.Element | null;
+type UpdatePaymentMethodButtonMode = 'portal';
+interface UpdatePaymentMethodButtonProps extends Omit<LaunchCustomerPortalButtonProps, 'children'> {
+    /**
+     * How card updates are collected. `"portal"` (default, only value shipped
+     * today) opens the SolvaPay hosted customer portal in a new tab. A
+     * future PR adds `"inline"` for Stripe Elements; keep the prop stable so
+     * callers don't need to migrate when that lands.
+     */
+    mode?: UpdatePaymentMethodButtonMode;
+    /** Override the default "Update card" label. */
+    children?: React.ReactNode;
+}
+declare const UpdatePaymentMethodButton: React.ForwardRefExoticComponent<UpdatePaymentMethodButtonProps & React.RefAttributes<HTMLAnchorElement>>;
+
+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 +545,7 @@ interface UseCheckoutReturn {
 declare function useCheckout(options: {
     planRef?: string;
     productRef?: string;
+    customer?: PrefillCustomer;
 }): UseCheckoutReturn;
 
 /**
@@ -942,6 +602,44 @@ 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` (and transport identity) 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 transport
+ * (or HTTP route when no transport is provided) 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 +765,83 @@ declare function useBalance(): BalanceStatus;
  */
 declare function useTopupAmountSelector(options: UseTopupAmountSelectorOptions): UseTopupAmountSelectorReturn;
 
+/**
+ * Hook that loads the customer's default payment method for rendering
+ * under `<CurrentPlanCard>`. Mirrors `useMerchant`'s caching semantics:
+ * module-level single-flight cache keyed by transport identity (or HTTP
+ * route when no custom transport is provided).
+ *
+ * The hook **does not throw** on transport errors — it sets `error` and
+ * keeps `paymentMethod: null` so the consuming component can hide the
+ * payment-method line. This lets `<CurrentPlanCard>` degrade gracefully
+ * when the backend endpoint isn't deployed yet or the MCP server doesn't
+ * expose the `get_payment_method` tool.
+ *
+ * @example
+ * ```tsx
+ * const { paymentMethod, loading } = usePaymentMethod()
+ *
+ * if (loading) return null
+ * if (!paymentMethod || paymentMethod.kind === 'none') return null
+ *
+ * return <span>{paymentMethod.brand} •••• {paymentMethod.last4}</span>
+ * ```
+ */
+declare function usePaymentMethod(): UsePaymentMethodReturn;
+
+/**
+ * Returns the effective data-access transport for the current provider.
+ *
+ * If the consumer passed a custom `transport` on `SolvaPayConfig`, that
+ * instance is returned. Otherwise a fresh HTTP transport is built from
+ * `config.api` + `config.fetch`. Memoised on the config identity so
+ * HTTP-default consumers don't re-create a transport on every render.
+ *
+ * Use this from components that need a transport method the provider
+ * doesn't already expose on its context (e.g. `createCustomerSession`,
+ * `getPaymentMethod`, `listPlans`).
+ */
+declare function useTransport(): SolvaPayTransport;
+
+interface UsePaywallResolverReturn {
+    /** `true` once the paywall requirement is met. */
+    resolved: boolean;
+    /** Refetch the underlying purchase + balance state. */
+    refetch: () => Promise<void>;
+}
+declare function usePaywallResolver(content: PaywallStructuredContent): UsePaywallResolverReturn;
+
+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
  *
@@ -1123,5 +898,140 @@ declare function getPrimaryPurchase(purchases: PurchaseInfo[]): PurchaseInfo | n
  * @returns true if purchase is paid (amount > 0)
  */
 declare function isPaidPurchase(purchase: PurchaseInfo): boolean;
+/**
+ * Classify a purchase as a plan (subscription / one-time / usage-based) vs a
+ * balance transaction (credit top-up, and any future non-plan purposes).
+ *
+ * Primary signal is structural: a purchase with no `planSnapshot` was never a
+ * plan. The `metadata.purpose` check is defense in depth — it keeps obvious
+ * top-ups out of plan selectors even if a future backend regression
+ * accidentally attaches a snapshot to one.
+ *
+ * @param purchase - Purchase to classify
+ * @returns true when the purchase represents a plan
+ */
+declare function isPlanPurchase(purchase: PurchaseInfo): boolean;
+/**
+ * Inverse of `isPlanPurchase` — balance transactions (credit top-ups today,
+ * gift credits / refunds / bonuses tomorrow).
+ */
+declare function isTopupPurchase(purchase: PurchaseInfo): boolean;
+
+/**
+ * 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;
+};
+/**
+ * Number of minor units per one major unit of `currency`. 1 for zero-decimal
+ * currencies (JPY, KRW, …), 100 for everything else. Use this to convert
+ * between the units a user types (major, e.g. dollars) and the units Stripe
+ * and the SolvaPay API consume (minor, e.g. cents).
+ */
+declare function getMinorUnitsPerMajor(currency: string): number;
+/**
+ * Convert a minor-unit amount to its major-unit equivalent. Zero-decimal
+ * currencies pass through unchanged (1000 JPY minor = 1000 JPY major);
+ * two-decimal currencies divide by 100 (1999 USD minor = 19.99 USD).
+ */
+declare function toMajorUnits(amountMinor: number, currency: string): number;
+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>;
+
+/**
+ * Default HTTP transport — wraps `config.api` + `config.fetch` so every SDK
+ * hook and component routes through a single place. Extracted from the
+ * inline `buildDefault*` callbacks that used to live inside
+ * `SolvaPayProvider`.
+ */
+
+declare const DEFAULT_ROUTES: {
+    readonly checkPurchase: "/api/check-purchase";
+    readonly createPayment: "/api/create-payment-intent";
+    readonly processPayment: "/api/process-payment";
+    readonly createTopupPayment: "/api/create-topup-payment-intent";
+    readonly customerBalance: "/api/customer-balance";
+    readonly cancelRenewal: "/api/cancel-renewal";
+    readonly reactivateRenewal: "/api/reactivate-renewal";
+    readonly activatePlan: "/api/activate-plan";
+    readonly createCheckoutSession: "/api/create-checkout-session";
+    readonly createCustomerSession: "/api/create-customer-session";
+    readonly getMerchant: "/api/merchant";
+    readonly getProduct: "/api/get-product";
+    readonly listPlans: "/api/list-plans";
+    readonly getPaymentMethod: "/api/payment-method";
+    readonly getUsage: "/api/usage";
+};
+declare function createHttpTransport(config: SolvaPayConfig | undefined): SolvaPayTransport;
 
-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 };
+export { ActivatePlanResult, 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, CurrentPlanCard, type CurrentPlanCardClassNames, type CurrentPlanCardProps, type CustomerInfo, DEFAULT_ROUTES, type FormatPriceOptions, LaunchCustomerPortalButton, type LaunchCustomerPortalButtonProps, PartialSolvaPayCopy, type PaymentElementKind, PaymentForm, PaymentFormContext, type PaymentFormContextValue, PaymentFormProps, PaymentFormProvider, Plan, PlanSelector, type PlanSelectorProps, PrefillCustomer, Product, type PurchaseActions, PurchaseInfo, PurchaseStatus, PurchaseStatusReturn, ReactivateResult, SolvaPayConfig, SolvaPayContextValue, SolvaPayCopy, SolvaPayProvider, SolvaPayProviderProps, SolvaPayTransport, Spinner, StripePaymentFormWrapper, TopupForm, TopupFormProps, UpdatePaymentMethodButton, type UpdatePaymentMethodButtonMode, type UpdatePaymentMethodButtonProps, type UseActivationReturn, UseMerchantReturn, UsePaymentMethodReturn, type UsePaywallResolverReturn, UsePlanOptions, UsePlanReturn, UsePlansOptions, UsePlansReturn, UseProductReturn, UseTopupAmountSelectorOptions, UseTopupAmountSelectorReturn, UseTopupOptions, UseTopupReturn, confirmPayment, createHttpTransport, enCopy, filterPurchases, formatPrice, getActivePurchases, getCancelledPurchasesWithEndDate, getMinorUnitsPerMajor, getMostRecentPurchase, getPrimaryPurchase, interpolate, isPaidPurchase, isPlanPurchase, isTopupPurchase, mergeCopy, resolveCta, toMajorUnits, useActivation, useBalance, useCheckout, useCopy, useCustomer, useLocale, useMerchant, usePaymentForm, usePaymentMethod, usePaywallResolver, usePlan, usePlans, useProduct, usePurchase, usePurchaseActions, usePurchaseStatus, useSolvaPay, useTopup, useTopupAmountSelector, useTransport };