@solvapay/react 1.3.0 → 1.4.0-preview-ecd61384a4e849717e13d47ab2daa086cdcd91c5

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @solvapay/react changelog
 
+## 1.4.0-preview-ecd61384a4e849717e13d47ab2daa086cdcd91c5
+
+### Minor Changes
+
+- 6e4f5cf: Collapse auto-recharge transport route overrides to a single `api.autoRecharge` key (replaces `getAutoRecharge`, `saveAutoRecharge`, and `disableAutoRecharge` route keys).
+- 349777e: Auto-recharge can now be configured in the same top-up payment as the initial card charge, so integrators do not need a separate SetupIntent step before checkout.
+  - **`@solvapay/react`**: `AutoRecharge` adds `deferCardSetup` and `onPendingConfig` to stage settings until payment; `useTopup`, `TopupForm`, and `createTopupPayment` accept optional `autoRecharge`; `balance.reconcileAfterUsageDebit()` starts post-debit polling without false bumps from optimistic debits alone.
+  - **`@solvapay/server`**: `createTopupPaymentIntentCore` forwards optional `autoRecharge` to the SDK payment-intent API.
+  - **`@solvapay/next`**: `createTopupPaymentIntent` route helper accepts the same `autoRecharge` body field.
+
+### Patch Changes
+
+- 2644836: Fix balance reconciliation stopping after the first auto-recharge when multiple usage debits trigger back-to-back.
+  - **`balance.reconcileAfterUsageDebit`**: tracks a pending recharge count so each expected top-up is polled and applied before reconciliation finishes, instead of clearing after the first observed increase.
+
+- 5aa4aee: Fix lossy credit↔currency rounding when toggling auto-recharge amount units.
+  - **`estimateCredits`** now uses `Math.round` (matching credits→currency) instead of `Math.floor`.
+  - **Unit toggle** snaps back to the last user-entered value instead of re-deriving from the rounded display, so repeated flips no longer drift by a minor unit.
+
+- 349777e: Financial boundary hardening: backend `display.*` blocks are the source of truth for credit and currency rendering.
+  - **`@solvapay/core`**: conversion-contract e2e extended to pin backend display formulas against the core reference.
+  - **`@solvapay/react`**: `TransportBalanceResult` and `BalanceStatus` accept optional `display` from the balance API; negative `adjustBalance` schedules a grace refetch; usage demo refetches after debit.
+  - **`@solvapay/server`**: `AutoRechargeConfig`, balance, and credit-debit types document backend-computed `display` blocks and `autoRecharge.triggered` as charge-initiated (not credits booked inline).
+
+- Updated dependencies [349777e]
+  - @solvapay/core@1.1.1-preview-ecd61384a4e849717e13d47ab2daa086cdcd91c5
+  - @solvapay/mcp-core@0.2.7-preview-ecd61384a4e849717e13d47ab2daa086cdcd91c5
+
 ## 1.3.0
 
 ### Minor Changes

package/dist/adapters/auth.js

@@ -4,6 +4,7 @@ import {
   getOrCreateAnonymousCustomerRef,
   resetAnonymousCustomerRef
 } from "../chunk-UMXOAUW7.js";
+import "../chunk-MLKGABMK.js";
 export {
   createAnonymousAuthAdapter,
   defaultAuthAdapter,

package/dist/adapters/auth0.js

@@ -1,6 +1,7 @@
 import {
   createSessionAuthAdapter
 } from "../chunk-JTW665JR.js";
+import "../chunk-MLKGABMK.js";
 
 // src/adapters/auth0.ts
 function createAuth0ClientAuthAdapter(options) {

package/dist/adapters/session-auth.js

@@ -1,6 +1,7 @@
 import {
   createSessionAuthAdapter
 } from "../chunk-JTW665JR.js";
+import "../chunk-MLKGABMK.js";
 export {
   createSessionAuthAdapter
 };

package/dist/{chunk-DW5FJUUG.js → chunk-6RR4J74H.js}

@@ -149,6 +149,7 @@ var DEFAULT_ROUTES = {
   getProduct: "/api/get-product",
   listPlans: "/api/list-plans",
   getPaymentMethod: "/api/payment-method",
+  autoRecharge: "/api/auto-recharge",
   getUsage: "/api/usage",
   getLimits: "/api/limits"
 };
@@ -186,7 +187,11 @@ function createHttpTransport(config) {
     }),
     createTopupPayment: (params) => request(config, routeFor(config, "createTopupPayment"), {
       method: "POST",
-      body: { amount: params.amount, currency: params.currency },
+      body: {
+        amount: params.amount,
+        currency: params.currency,
+        ...params.autoRecharge ? { autoRecharge: params.autoRecharge } : {}
+      },
       onErrorContext: "createTopupPayment",
       errorPrefix: "Failed to create topup payment"
     }),
@@ -235,16 +240,12 @@ function createHttpTransport(config) {
         }
       );
     },
-    createCustomerSession: () => request(
-      config,
-      routeFor(config, "createCustomerSession"),
-      {
-        method: "POST",
-        body: {},
-        onErrorContext: "createCustomerSession",
-        errorPrefix: "Failed to create customer session"
-      }
-    ),
+    createCustomerSession: () => request(config, routeFor(config, "createCustomerSession"), {
+      method: "POST",
+      body: {},
+      onErrorContext: "createCustomerSession",
+      errorPrefix: "Failed to create customer session"
+    }),
     getMerchant: () => request(config, routeFor(config, "getMerchant"), {
       method: "GET",
       onErrorContext: "getMerchant",
@@ -274,6 +275,22 @@ function createHttpTransport(config) {
       onErrorContext: "getPaymentMethod",
       errorPrefix: "Failed to load payment method"
     }),
+    getAutoRecharge: () => request(config, routeFor(config, "autoRecharge"), {
+      method: "GET",
+      onErrorContext: "getAutoRecharge",
+      errorPrefix: "Failed to load auto-recharge"
+    }),
+    saveAutoRecharge: (input) => request(config, routeFor(config, "autoRecharge"), {
+      method: "PUT",
+      body: input,
+      onErrorContext: "saveAutoRecharge",
+      errorPrefix: "Failed to save auto-recharge"
+    }),
+    disableAutoRecharge: () => request(config, routeFor(config, "autoRecharge"), {
+      method: "DELETE",
+      onErrorContext: "disableAutoRecharge",
+      errorPrefix: "Failed to disable auto-recharge"
+    }),
     getUsage: () => request(config, routeFor(config, "getUsage"), {
       method: "GET",
       onErrorContext: "getUsage",
@@ -409,6 +426,42 @@ var enCopy = {
     creditEstimateExact: "= {credits} credits",
     creditEstimateApprox: "~ {credits} credits"
   },
+  autoRecharge: {
+    heading: "Auto recharge",
+    description: "Automatically top up so you never run out \u2014 recommended for production. You can turn this off anytime.",
+    settingsHeading: "Auto recharge settings",
+    setupTriggerLabel: "Set up auto-recharge",
+    modifyTriggerLabel: "Modify",
+    notConfiguredHint: "Automatic top-ups are off. Set up auto-recharge if you want credits added when your balance runs low.",
+    enableLabel: "Enable auto-recharge",
+    enableQuestion: "Would you like to set up automatic recharge?",
+    enableSentence: "Yes, automatically recharge my card when my credit balance falls below a threshold",
+    thresholdLabel: "When balance falls below",
+    thresholdAriaLabel: "Balance threshold",
+    fixedAmountLabel: "Add this amount",
+    fixedAmountAriaLabel: "Fixed top-up amount",
+    saveButton: "Save settings",
+    cancelButton: "Cancel",
+    disableButton: "Disable automatic top-up",
+    savedMessage: "Automatic top-up settings saved.",
+    disabledMessage: "Automatic top-ups disabled.",
+    setupRequiredMessage: "Confirm your card to activate automatic top-ups.",
+    setupHeading: "Authorize card",
+    setupDescription: "Authorize a card for automatic top-ups. You will not be charged now.",
+    setupSubmit: "Save card for auto-recharge",
+    setupProcessing: "Authorizing...",
+    setupAwaitingConfirmation: "Card authorized. Finishing activation \u2014 this can take a moment.",
+    setupAuthFailed: "Card authentication failed. Please try a different card.",
+    invalidThreshold: "Enter a valid balance threshold.",
+    thresholdTooLow: "Balance threshold must be greater than zero.",
+    minTopupAmount: "Top-up amount must be at least {amount}.",
+    topupBelowThreshold: "Top-up amount must be at least your balance threshold ({amount}).",
+    creditsPerRecharge: "\u2248 {credits} credits per recharge",
+    creditsPerRechargeApprox: "~ {credits} credits per recharge",
+    currencyPerRecharge: "\u2248 {amount} per recharge",
+    currencyPerRechargeApprox: "~ {amount} per recharge",
+    statusFailed: "Payment failed \u2014 update your card to resume"
+  },
   activationFlow: {
     heading: "Confirm your plan",
     activateButton: "Activate",
@@ -592,6 +645,31 @@ function useCopyContext() {
 
 // src/SolvaPayProvider.tsx
 import { createContext as createContext2, useState, useEffect, useCallback, useMemo as useMemo2, useRef } from "react";
+
+// ../server/src/index.ts
+import crypto from "crypto";
+import { SolvaPayError } from "@solvapay/core";
+
+// ../server/src/helpers/balance-poll.ts
+var BALANCE_RECONCILE_DELAYS_MS = [500, 1e3, 2e3, 4e3, 8e3, 16e3];
+async function pollBalanceUntilIncreased(getBalance, baseline, delays = BALANCE_RECONCILE_DELAYS_MS) {
+  for (const delay of delays) {
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    try {
+      const post = await getBalance();
+      if (post.credits > baseline) {
+        return { creditsAdded: post.credits - baseline };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+
+// src/helpers/auto-recharge-cache.ts
+var BALANCE_RECONCILE_GRACE_MS = BALANCE_RECONCILE_DELAYS_MS.reduce((sum, delay) => sum + delay, 0) + 1e3;
+
+// src/SolvaPayProvider.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
 var SolvaPayContext = createContext2(null);
 function resolveTransport(config) {
@@ -638,12 +716,18 @@ var SolvaPayProvider = ({ config, children }) => {
   const [displayExchangeRateValue, setDisplayExchangeRateValue] = useState(
     initial?.balance?.displayExchangeRate ?? null
   );
+  const [displayBlockValue, setDisplayBlockValue] = useState(
+    initial?.balance?.display ?? null
+  );
   const [balanceLoading, setBalanceLoading] = useState(false);
   const balanceInFlightRef = useRef(false);
   const balanceLoadedRef = useRef(!!initial?.balance);
+  const creditsValueRef = useRef(initial?.balance?.credits ?? null);
   const optimisticUntilRef = useRef(0);
   const optimisticTimerRef = useRef(null);
   const fetchBalanceRef = useRef(null);
+  const reconcileRunningRef = useRef(false);
+  const reconcilePollRef = useRef(null);
   const inFlightRef = useRef(null);
   const loadedCacheKeysRef = useRef(
     new Set(initial?.customerRef ? [initial.customerRef] : [])
@@ -661,10 +745,12 @@ var SolvaPayProvider = ({ config, children }) => {
   const fetchBalanceImpl = useCallback(async () => {
     if (optimisticUntilRef.current > Date.now()) return;
     if (!isAuthenticated && !internalCustomerRef) {
+      creditsValueRef.current = null;
       setCreditsValue(null);
       setDisplayCurrencyValue(null);
       setCreditsPerMinorUnitValue(null);
       setDisplayExchangeRateValue(null);
+      setDisplayBlockValue(null);
       setBalanceLoading(false);
       balanceLoadedRef.current = false;
       return;
@@ -681,10 +767,12 @@ var SolvaPayProvider = ({ config, children }) => {
         return;
       }
       const data = await transportRef.current.getBalance();
+      creditsValueRef.current = data.credits ?? null;
       setCreditsValue(data.credits ?? null);
       setDisplayCurrencyValue(data.displayCurrency ?? null);
       setCreditsPerMinorUnitValue(data.creditsPerMinorUnit ?? null);
       setDisplayExchangeRateValue(data.displayExchangeRate ?? null);
+      setDisplayBlockValue(data.display ?? null);
       balanceLoadedRef.current = true;
     } catch (error) {
       console.error("[SolvaPayProvider] Failed to fetch balance:", error);
@@ -699,18 +787,112 @@ var SolvaPayProvider = ({ config, children }) => {
   useEffect(() => {
     return () => {
       if (optimisticTimerRef.current) clearTimeout(optimisticTimerRef.current);
+      reconcilePollRef.current = null;
+      reconcileRunningRef.current = false;
     };
   }, []);
   const OPTIMISTIC_GRACE_MS = 8e3;
-  const adjustBalanceImpl = useCallback((credits) => {
-    setCreditsValue((prev) => (prev ?? 0) + credits);
-    optimisticUntilRef.current = Date.now() + OPTIMISTIC_GRACE_MS;
+  const DEBIT_GRACE_MS = 2e3;
+  const clearOptimisticGrace = useCallback(() => {
+    optimisticUntilRef.current = 0;
+    if (optimisticTimerRef.current) {
+      clearTimeout(optimisticTimerRef.current);
+      optimisticTimerRef.current = null;
+    }
+  }, []);
+  const applyBalanceSnapshot = useCallback(
+    (data) => {
+      creditsValueRef.current = data.credits ?? null;
+      setCreditsValue(data.credits ?? null);
+      setDisplayCurrencyValue(data.displayCurrency ?? null);
+      setCreditsPerMinorUnitValue(data.creditsPerMinorUnit ?? null);
+      setDisplayExchangeRateValue(data.displayExchangeRate ?? null);
+      setDisplayBlockValue(data.display ?? null);
+      balanceLoadedRef.current = true;
+    },
+    []
+  );
+  const reconcileBalanceIncreaseImpl = useCallback(async () => {
+    if (!transportRef.current.getBalance) return;
+    const finishReconcilePoll = () => {
+      reconcilePollRef.current = null;
+      clearOptimisticGrace();
+    };
+    reconcileRunningRef.current = true;
+    try {
+      while (reconcilePollRef.current) {
+        const { baseline: activeBaseline, generation: activeGeneration } = reconcilePollRef.current;
+        const pollResult = await pollBalanceUntilIncreased(
+          async () => {
+            const data = await transportRef.current.getBalance();
+            return { credits: data.credits ?? 0 };
+          },
+          activeBaseline,
+          BALANCE_RECONCILE_DELAYS_MS
+        );
+        const pollState = reconcilePollRef.current;
+        if (!pollState || pollState.generation !== activeGeneration) {
+          continue;
+        }
+        if (!pollResult) {
+          finishReconcilePoll();
+          break;
+        }
+        try {
+          const data = await transportRef.current.getBalance();
+          applyBalanceSnapshot(data);
+          pollState.pending -= 1;
+          if (pollState.pending > 0) {
+            pollState.baseline = data.credits ?? 0;
+            continue;
+          }
+        } catch (error) {
+          console.error("[SolvaPayProvider] Failed to reconcile balance after auto-recharge:", error);
+        }
+        finishReconcilePoll();
+        break;
+      }
+    } finally {
+      reconcileRunningRef.current = false;
+    }
+  }, [applyBalanceSnapshot, clearOptimisticGrace]);
+  const scheduleGraceRefetch = useCallback((graceMs) => {
+    optimisticUntilRef.current = Date.now() + graceMs;
     if (optimisticTimerRef.current) clearTimeout(optimisticTimerRef.current);
     optimisticTimerRef.current = setTimeout(() => {
       optimisticUntilRef.current = 0;
       fetchBalanceRef.current?.();
-    }, OPTIMISTIC_GRACE_MS);
+    }, graceMs);
   }, []);
+  const adjustBalanceImpl = useCallback(
+    (credits) => {
+      const nextCredits = (creditsValueRef.current ?? 0) + credits;
+      creditsValueRef.current = nextCredits;
+      setCreditsValue(nextCredits);
+      if (credits >= 0) {
+        scheduleGraceRefetch(OPTIMISTIC_GRACE_MS);
+      } else {
+        scheduleGraceRefetch(DEBIT_GRACE_MS);
+      }
+    },
+    [scheduleGraceRefetch]
+  );
+  const reconcileAfterUsageDebitImpl = useCallback(
+    (opts) => {
+      if (opts?.expectIncrease !== true) {
+        return;
+      }
+      const nextCredits = creditsValueRef.current ?? 0;
+      const generation = (reconcilePollRef.current?.generation ?? 0) + 1;
+      const pending = (reconcilePollRef.current?.pending ?? 0) + 1;
+      reconcilePollRef.current = { baseline: nextCredits, generation, pending };
+      scheduleGraceRefetch(BALANCE_RECONCILE_GRACE_MS);
+      if (!reconcileRunningRef.current) {
+        void reconcileBalanceIncreaseImpl();
+      }
+    },
+    [reconcileBalanceIncreaseImpl, scheduleGraceRefetch]
+  );
   const createPayment = useCallback(
     (params) => transportRef.current.createPayment(params),
     []
@@ -882,6 +1064,7 @@ var SolvaPayProvider = ({ config, children }) => {
     setDisplayCurrencyValue(next.balance?.displayCurrency ?? null);
     setCreditsPerMinorUnitValue(next.balance?.creditsPerMinorUnit ?? null);
     setDisplayExchangeRateValue(next.balance?.displayExchangeRate ?? null);
+    setDisplayBlockValue(next.balance?.display ?? null);
     balanceLoadedRef.current = !!next.balance;
   }, []);
   useEffect(() => {
@@ -986,8 +1169,10 @@ var SolvaPayProvider = ({ config, children }) => {
       displayCurrency: displayCurrencyValue,
       creditsPerMinorUnit: creditsPerMinorUnitValue,
       displayExchangeRate: displayExchangeRateValue,
+      display: displayBlockValue,
       refetch: fetchBalanceImpl,
-      adjustBalance: adjustBalanceImpl
+      adjustBalance: adjustBalanceImpl,
+      reconcileAfterUsageDebit: reconcileAfterUsageDebitImpl
     }),
     [
       balanceLoading,
@@ -995,8 +1180,10 @@ var SolvaPayProvider = ({ config, children }) => {
       displayCurrencyValue,
       creditsPerMinorUnitValue,
       displayExchangeRateValue,
+      displayBlockValue,
       fetchBalanceImpl,
-      adjustBalanceImpl
+      adjustBalanceImpl,
+      reconcileAfterUsageDebitImpl
     ]
   );
   const contextValue = useMemo2(
@@ -1974,7 +2161,7 @@ import { createContext as createContext5, forwardRef as forwardRef2, useContext
 
 // src/utils/errors.ts
 var DOCS_BASE_URL = "https://solvapay.com/docs";
-var SolvaPayError = class extends Error {
+var SolvaPayError2 = class extends Error {
   code;
   docsUrl;
   constructor(code, message, docsUrl) {
@@ -1984,7 +2171,7 @@ var SolvaPayError = class extends Error {
     this.docsUrl = docsUrl;
   }
 };
-var MissingProviderError = class extends SolvaPayError {
+var MissingProviderError = class extends SolvaPayError2 {
   constructor(primitiveName) {
     const docsUrl = `${DOCS_BASE_URL}/troubleshooting/missing-provider`;
     super(
@@ -1995,7 +2182,7 @@ var MissingProviderError = class extends SolvaPayError {
     this.name = "MissingProviderError";
   }
 };
-var MissingProductRefError = class extends SolvaPayError {
+var MissingProductRefError = class extends SolvaPayError2 {
   constructor(primitiveName) {
     const docsUrl = `${DOCS_BASE_URL}/primitives/product-ref`;
     super(
@@ -3509,7 +3696,7 @@ function getStripeCacheKey2(publishableKey, accountId) {
   return accountId ? `${publishableKey}:${accountId}` : publishableKey;
 }
 function useTopup(options) {
-  const { amount, currency } = options;
+  const { amount, currency, autoRecharge } = options;
   const { createTopupPayment, customerRef, updateCustomerRef } = useSolvaPay();
   const [loading, setLoading] = useState10(false);
   const [error, setError] = useState10(null);
@@ -3528,7 +3715,7 @@ function useTopup(options) {
     setLoading(true);
     setError(null);
     try {
-      const result = await createTopupPayment({ amount, currency });
+      const result = await createTopupPayment({ amount, currency, autoRecharge });
       if (!result || typeof result !== "object") {
         throw new Error("Invalid topup payment intent response from server");
       }
@@ -3560,7 +3747,7 @@ function useTopup(options) {
       setLoading(false);
       isStartingRef.current = false;
     }
-  }, [amount, currency, createTopupPayment, customerRef, updateCustomerRef, loading]);
+  }, [amount, currency, autoRecharge, createTopupPayment, customerRef, updateCustomerRef, loading]);
   const reset = useCallback11(() => {
     isStartingRef.current = false;
     setLoading(false);
@@ -3608,6 +3795,7 @@ var Root4 = forwardRef6(function TopupFormRoot(props, forwardedRef) {
   const {
     amount,
     currency,
+    autoRecharge,
     onSuccess,
     onError,
     returnUrl,
@@ -3631,7 +3819,8 @@ var Root4 = forwardRef6(function TopupFormRoot(props, forwardedRef) {
     stripePromise
   } = useTopup({
     amount,
-    currency
+    currency,
+    autoRecharge
   });
   const hasInitializedRef = useRef6(false);
   const hasAmount = amount > 0;
@@ -5410,6 +5599,7 @@ export {
   useCopy,
   useLocale,
   LegalFooter,
+  withPaymentElementDefaults,
   MissingProviderError,
   MissingProductRefError,
   useSolvaPay,