@solvapay/react 1.0.9-preview.1 → 1.0.9

package/dist/useUsage-nD7zwSbG.d.ts

@@ -0,0 +1,413 @@
+import React from 'react';
+import { PaymentElement, CardElement } from '@stripe/react-stripe-js';
+import { b as Plan, P as PaymentFormProps, a as PrefillCustomer, A as ActivationResult, q as UseTopupAmountSelectorReturn } from './index-onWNU7iT.js';
+
+/**
+ * Default-tree shim over the `CheckoutSummary` primitive.
+ *
+ * Renders a product/plan/price line with optional trial + tax-note slots.
+ * Full control (ordering, custom elements, Tailwind variants) is available
+ * via the primitives at `@solvapay/react/primitives`.
+ */
+
+type CheckoutSummaryProps = {
+    planRef?: string;
+    productRef?: string;
+    showTrial?: boolean;
+    showTaxNote?: boolean;
+    className?: string;
+};
+declare const CheckoutSummary: React.FC<CheckoutSummaryProps>;
+
+/**
+ * Checkout "shape" — drives the mandate variant, the submit-button CTA, and
+ * the button `aria-label` in lockstep so those three strings always agree.
+ */
+type CheckoutVariant = 'recurring' | 'oneTime' | 'topup' | 'usageMetered' | 'freeTier';
+/**
+ * Derive the variant from the plan's type + billing model. Unknown or missing
+ * plans default to `'oneTime'`, which matches the canonical "Pay Now" UX.
+ *
+ * Free plans (`requiresPayment === false`) that are NOT usage-metered route
+ * to the `'freeTier'` variant. Metered free/usage plans stay on
+ * `'usageMetered'` because the mandate copy there already covers pay-as-you-go.
+ */
+declare function deriveVariant(plan: Plan | null | undefined, mode?: 'topup'): CheckoutVariant;
+
+/**
+ * MandateText leaf primitive.
+ *
+ * Renders SCA-compliant authorization copy derived from the resolved plan,
+ * product, and merchant identity. Variant is derived from the plan type +
+ * billing model and can be forced via the `variant` or `mode` props (use
+ * `mode="topup"` inside `<TopupForm>` where there is no plan). All strings
+ * resolve through the localized copy bundle so integrators can override
+ * text without forking the component.
+ */
+
+type MandateTextProps = {
+    planRef?: string;
+    productRef?: string;
+    variant?: CheckoutVariant;
+    mode?: 'topup';
+    amountMinor?: number;
+    currency?: string;
+    asChild?: boolean;
+} & Omit<React.HTMLAttributes<HTMLParagraphElement>, 'children'> & {
+    children?: React.ReactNode;
+};
+declare const MandateText: React.ForwardRefExoticComponent<{
+    planRef?: string;
+    productRef?: string;
+    variant?: CheckoutVariant;
+    mode?: "topup";
+    amountMinor?: number;
+    currency?: string;
+    asChild?: boolean;
+} & Omit<React.HTMLAttributes<HTMLParagraphElement>, "children"> & {
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLParagraphElement>>;
+
+/**
+ * PaymentForm compound primitive.
+ *
+ * Unstyled, accessible building blocks for running the paid OR free checkout
+ * step inside a <SolvaPayProvider>. `Root` detects paid vs free plans via
+ * `usePlan`, wires Stripe Elements for paid plans, or falls through to
+ * `useActivation` for free plans; both paths expose the same
+ * `PaymentFormContext` so the same subcomponents compose identically in
+ * either mode.
+ *
+ * Every leaf accepts `asChild` for Slot-style composition. The `SubmitButton`
+ * emits `data-state=idle|processing|disabled` + `data-variant=paid|free|topup|activate`.
+ */
+
+type SummaryProps = Omit<React.ComponentProps<typeof CheckoutSummary>, 'planRef' | 'productRef'>;
+type MandateTextPrimitiveProps = Omit<React.ComponentProps<typeof MandateText>, 'planRef' | 'productRef'>;
+type PaymentElementProps = {
+    options?: React.ComponentProps<typeof PaymentElement>['options'];
+};
+type CardElementProps = {
+    options?: React.ComponentProps<typeof CardElement>['options'];
+};
+declare const PaymentFormRoot: React.ForwardRefExoticComponent<PaymentFormProps & {
+    prefillCustomer?: PrefillCustomer;
+    requireTermsAcceptance?: boolean;
+    children?: React.ReactNode;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PaymentFormSummary: React.FC<SummaryProps>;
+declare const PaymentFormCustomerFields: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+    readOnly?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PaymentFormPaymentElement: React.FC<PaymentElementProps>;
+declare const PaymentFormCardElement: React.FC<CardElementProps>;
+declare const PaymentFormMandateText: React.FC<MandateTextPrimitiveProps>;
+declare const PaymentFormTermsCheckbox: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLLabelElement> & {
+    asChild?: boolean;
+    label?: React.ReactNode;
+} & React.RefAttributes<HTMLLabelElement>>;
+declare const PaymentFormSubmitButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const PaymentFormLoading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PaymentFormError: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PaymentForm: {
+    readonly Root: React.ForwardRefExoticComponent<PaymentFormProps & {
+        prefillCustomer?: PrefillCustomer;
+        requireTermsAcceptance?: boolean;
+        children?: React.ReactNode;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Summary: React.FC<SummaryProps>;
+    readonly CustomerFields: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+        readOnly?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly PaymentElement: React.FC<PaymentElementProps>;
+    readonly CardElement: React.FC<CardElementProps>;
+    readonly MandateText: React.FC<MandateTextPrimitiveProps>;
+    readonly TermsCheckbox: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLLabelElement> & {
+        asChild?: boolean;
+        label?: React.ReactNode;
+    } & React.RefAttributes<HTMLLabelElement>>;
+    readonly SubmitButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLButtonElement>>;
+    readonly Loading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Error: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+};
+
+/**
+ * ProductBadge compound primitive.
+ *
+ * Single leaf that renders the customer's current product name when an
+ * active purchase exists. Emits `data-has-purchase` + `data-has-paid-purchase`
+ * flags and forwards an `aria-label` derived from the copy bundle.
+ * `PlanBadge` is an alias retained for backwards compatibility with older
+ * integrations — both point at the same component.
+ */
+
+declare const ProductBadge: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLElement>>;
+/** @deprecated Use `ProductBadge` instead. Kept as an alias for existing integrations. */
+declare const PlanBadge: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLElement>>;
+
+/**
+ * PurchaseGate compound primitive.
+ *
+ * Controls access to gated content based on whether the customer has an
+ * active purchase (optionally scoped to a product). `Root` exposes
+ * `data-state=allowed|blocked|loading` and context-drives the
+ * `Allowed`, `Blocked`, `Loading`, and `Error` subcomponents.
+ */
+
+type GateState = 'allowed' | 'blocked' | 'loading';
+type PurchaseGateContextValue = {
+    state: GateState;
+    loading: boolean;
+    hasAccess: boolean;
+    error: Error | null;
+};
+declare const PurchaseGateRoot: React.ForwardRefExoticComponent<{
+    /** @deprecated Use `requireProduct`. */
+    requirePlan?: string;
+    requireProduct?: string;
+    asChild?: boolean;
+    children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & React.RefAttributes<HTMLDivElement>>;
+declare const PurchaseGateAllowed: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PurchaseGateBlocked: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PurchaseGateLoading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PurchaseGateError: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const PurchaseGate: {
+    readonly Root: React.ForwardRefExoticComponent<{
+        /** @deprecated Use `requireProduct`. */
+        requirePlan?: string;
+        requireProduct?: string;
+        asChild?: boolean;
+        children?: React.ReactNode;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & React.RefAttributes<HTMLDivElement>>;
+    readonly Allowed: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Blocked: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Loading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Error: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+};
+declare function usePurchaseGate(): PurchaseGateContextValue;
+
+/**
+ * BalanceBadge leaf primitive.
+ *
+ * Renders the customer's credit balance with an optional currency-equivalent
+ * suffix. Emits `data-state=loading|zero|low|ok` plus a `data-credits`
+ * attribute for CSS targeting. Low-balance threshold is configurable via the
+ * `lowThreshold` prop (defaults to 10).
+ */
+
+declare const BalanceBadge: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & {
+    asChild?: boolean;
+    /** Hide the trailing " credits" label + currency equivalent. */
+    numberOnly?: boolean;
+    /** Balance threshold (inclusive) treated as `data-state="low"`. Defaults to 10. */
+    lowThreshold?: number;
+} & React.RefAttributes<HTMLSpanElement>>;
+
+/**
+ * ActivationFlow compound primitive.
+ *
+ * Drives the usage-based plan activation state machine:
+ *   summary → activating → (topup_required → selectAmount → topupPayment →
+ *     retrying) → activated | error.
+ *
+ * `Root` exposes `data-state` set to the current step and publishes the
+ * shared context consumed by leaves. Leaves render only during their
+ * matching step:
+ *  - `Summary` — `summary` | `activating`
+ *  - `ActivateButton` — `summary` | `activating`
+ *  - `AmountPicker` — `selectAmount`
+ *  - `ContinueButton` — `selectAmount`
+ *  - `Retrying` — `retrying`
+ *  - `Activated` — `activated`
+ *  - `Loading` — renders when plan is not yet resolved
+ *  - `Error` — `error`
+ */
+
+type ActivationFlowStep = 'summary' | 'activating' | 'selectAmount' | 'topupPayment' | 'retrying' | 'activated' | 'error';
+type ActivationFlowContextValue = {
+    step: ActivationFlowStep;
+    plan: Plan | null;
+    productRef: string;
+    planRef: string;
+    amountSelector: UseTopupAmountSelectorReturn;
+    /**
+     * Resolved top-up amount in the currency's minor units. Respects
+     * zero-decimal currencies (JPY → whole yen, USD → cents).
+     */
+    amountMinor: number;
+    /**
+     * @deprecated Use `amountMinor`. Kept as an alias for back-compat; will
+     * be removed in the next major. For zero-decimal currencies this is the
+     * same value as `amountMinor` (not cents).
+     */
+    amountCents: number;
+    currency: string;
+    activate: () => Promise<void>;
+    reset: () => void;
+    goToTopupPayment: () => void;
+    backToSelectAmount: () => void;
+    onTopupSuccess: () => Promise<void>;
+    error: string | null;
+    onError?: (error: Error) => void;
+};
+type AmountPickerMountProps = {
+    children?: React.ReactNode;
+};
+declare const ActivationFlowRoot: React.ForwardRefExoticComponent<{
+    productRef?: string;
+    /** Defaults to PlanSelectionContext selection when omitted. */
+    planRef?: string;
+    onSuccess?: (result: ActivationResult) => void;
+    onError?: (error: Error) => void;
+    retryDelayMs?: number;
+    retryBackoffMs?: number;
+    asChild?: boolean;
+    children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "onError" | "children"> & React.RefAttributes<HTMLDivElement>>;
+declare const ActivationFlowSummary: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const ActivationFlowActivateButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const ActivationFlowAmountPicker: React.FC<AmountPickerMountProps>;
+declare const ActivationFlowContinueButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const ActivationFlowRetrying: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const ActivationFlowActivated: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const ActivationFlowLoading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const ActivationFlowError: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    asChild?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const ActivationFlow: {
+    readonly Root: React.ForwardRefExoticComponent<{
+        productRef?: string;
+        /** Defaults to PlanSelectionContext selection when omitted. */
+        planRef?: string;
+        onSuccess?: (result: ActivationResult) => void;
+        onError?: (error: Error) => void;
+        retryDelayMs?: number;
+        retryBackoffMs?: number;
+        asChild?: boolean;
+        children?: React.ReactNode;
+    } & Omit<React.HTMLAttributes<HTMLDivElement>, "onError" | "children"> & React.RefAttributes<HTMLDivElement>>;
+    readonly Summary: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly ActivateButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLButtonElement>>;
+    readonly AmountPicker: React.FC<AmountPickerMountProps>;
+    readonly ContinueButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLButtonElement>>;
+    readonly Retrying: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Activated: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Loading: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+    readonly Error: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+        asChild?: boolean;
+    } & React.RefAttributes<HTMLDivElement>>;
+};
+declare function useActivationFlow(): ActivationFlowContextValue;
+
+/**
+ * CancelPlanButton leaf primitive.
+ *
+ * Cancels the active (or specified) purchase via `usePurchaseActions`.
+ * Emits `data-state=idle|cancelling` and auto-derives the confirm dialog
+ * copy from the plan type (`recurring` vs. `usage-based`) unless overridden
+ * via the `confirm` prop (`false` to skip, string to replace).
+ */
+
+declare const CancelPlanButton: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & {
+    asChild?: boolean;
+    /** Defaults to the active purchase from `usePurchase()`. */
+    purchaseRef?: string;
+    reason?: string;
+    /**
+     * Built-in confirm dialog. `true` (default) uses plan-type-aware copy;
+     * a string replaces the copy; `false` skips confirmation.
+     */
+    confirm?: boolean | string;
+    onCancelled?: () => void;
+    onError?: (error: Error) => void;
+} & React.RefAttributes<HTMLButtonElement>>;
+
+interface UseUsageReturn {
+    /** Raw usage snapshot (`null` when no usage-based plan is active). */
+    usage: UsageSnapshot | null;
+    loading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+    /** 0-100, rounded to 2dp. `null` when total is unknown (unlimited/empty). */
+    percentUsed: number | null;
+    /** Plan is usage-based, `percentUsed >= 80`. */
+    isApproachingLimit: boolean;
+    /** Plan is usage-based, `percentUsed >= 100`. */
+    isAtLimit: boolean;
+    /** True when `usage.total === null` (no quota on this plan). */
+    isUnlimited: boolean;
+    /** The meter reference (e.g. `'tokens'`). `null` when not usage-based. */
+    meterRef: string | null;
+}
+interface UsageSnapshot {
+    meterRef: string | null;
+    total: number | null;
+    used: number;
+    remaining: number | null;
+    percentUsed: number | null;
+    periodStart?: string;
+    periodEnd?: string;
+    purchaseRef?: string;
+}
+declare function useUsage(): UseUsageReturn;
+
+export { type ActivationFlowStep as A, BalanceBadge as B, type CheckoutVariant as C, ActivationFlowRoot as D, ActivationFlowSummary as E, PaymentForm as F, PaymentFormRoot as G, PurchaseGateAllowed as H, PurchaseGateBlocked as I, PurchaseGateError as J, PurchaseGateLoading as K, PurchaseGateRoot as L, MandateText as M, useActivationFlow as N, usePurchaseGate as O, PaymentFormSummary as P, type UsageSnapshot as U, PaymentFormCustomerFields as a, PaymentFormPaymentElement as b, PaymentFormCardElement as c, PaymentFormMandateText as d, PaymentFormTermsCheckbox as e, PaymentFormSubmitButton as f, PaymentFormLoading as g, PaymentFormError as h, CancelPlanButton as i, CheckoutSummary as j, type CheckoutSummaryProps as k, type MandateTextProps as l, PlanBadge as m, ProductBadge as n, PurchaseGate as o, type UseUsageReturn as p, deriveVariant as q, ActivationFlow as r, ActivationFlowActivateButton as s, ActivationFlowActivated as t, useUsage as u, ActivationFlowAmountPicker as v, ActivationFlowContinueButton as w, ActivationFlowError as x, ActivationFlowLoading as y, ActivationFlowRetrying as z };