@solvapay/server 1.2.1 → 1.3.0-preview-ecd61384a4e849717e13d47ab2daa086cdcd91c5

package/dist/index.cjs

@@ -30,7 +30,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BALANCE_RECONCILE_DELAYS_MS: () => BALANCE_RECONCILE_DELAYS_MS,
   PaywallError: () => PaywallError,
+  TOPUP_BALANCE_POLL_DELAYS_MS: () => TOPUP_BALANCE_POLL_DELAYS_MS,
   VIRTUAL_TOOL_DEFINITIONS: () => VIRTUAL_TOOL_DEFINITIONS,
   activatePlanCore: () => activatePlanCore,
   buildGateMessage: () => buildGateMessage,
@@ -47,7 +49,9 @@ __export(index_exports, {
   createSolvaPayClient: () => createSolvaPayClient,
   createTopupPaymentIntentCore: () => createTopupPaymentIntentCore,
   createVirtualTools: () => createVirtualTools,
+  disableAutoRechargeCore: () => disableAutoRechargeCore,
   getAuthenticatedUserCore: () => getAuthenticatedUserCore,
+  getAutoRechargeCore: () => getAutoRechargeCore,
   getCustomerBalanceCore: () => getCustomerBalanceCore,
   getMerchantCore: () => getMerchantCore,
   getPaymentMethodCore: () => getPaymentMethodCore,
@@ -59,10 +63,12 @@ __export(index_exports, {
   jsonSchemaToZodRawShape: () => jsonSchemaToZodRawShape,
   listPlansCore: () => listPlansCore,
   paywallErrorToClientPayload: () => paywallErrorToClientPayload,
+  pollBalanceUntilIncreased: () => pollBalanceUntilIncreased,
   processPaymentIntentCore: () => processPaymentIntentCore,
   processTopupPaymentIntentCore: () => processTopupPaymentIntentCore,
   reactivatePurchaseCore: () => reactivatePurchaseCore,
   registerVirtualToolsMcpImpl: () => registerVirtualToolsMcpImpl,
+  saveAutoRechargeCore: () => saveAutoRechargeCore,
   syncCustomerCore: () => syncCustomerCore,
   trackUsageCore: () => trackUsageCore,
   verifyWebhook: () => verifyWebhook,
@@ -522,7 +528,8 @@ function createSolvaPayClient(opts) {
           purpose: "credit_topup",
           amount: params.amount,
           currency: params.currency,
-          description: params.description
+          description: params.description,
+          ...params.autoRecharge ? { autoRecharge: params.autoRecharge } : {}
         })
       });
       if (!res.ok) {
@@ -760,6 +767,47 @@ function createSolvaPayClient(opts) {
         });
       }
       return await res.json();
+    },
+    async getAutoRecharge(params) {
+      const url = new URL(`${base}/v1/sdk/auto-recharge`);
+      url.searchParams.set("customerRef", params.customerRef);
+      const res = await fetch(url.toString(), { method: "GET", headers });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new import_core.SolvaPayError(`Get auto-recharge failed (${res.status}): ${error}`, {
+          status: res.status
+        });
+      }
+      return await res.json();
+    },
+    async saveAutoRecharge(params) {
+      const res = await fetch(`${base}/v1/sdk/auto-recharge`, {
+        method: "PUT",
+        headers,
+        body: JSON.stringify(params)
+      });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new import_core.SolvaPayError(`Save auto-recharge failed (${res.status}): ${error}`, {
+          status: res.status
+        });
+      }
+      return await res.json();
+    },
+    async disableAutoRecharge(params) {
+      const url = new URL(`${base}/v1/sdk/auto-recharge`);
+      url.searchParams.set("customerRef", params.customerRef);
+      const res = await fetch(url.toString(), { method: "DELETE", headers });
+      if (!res.ok) {
+        const error = await res.text();
+        log(`\u274C API Error: ${res.status} - ${error}`);
+        throw new import_core.SolvaPayError(`Disable auto-recharge failed (${res.status}): ${error}`, {
+          status: res.status
+        });
+      }
+      return await res.json();
     }
   };
 }
@@ -2442,6 +2490,23 @@ async function getCustomerBalanceCore(request, options = {}) {
   }
 }
 
+// src/helpers/balance-poll.ts
+var TOPUP_BALANCE_POLL_DELAYS_MS = [500, 1e3, 2e3, 4e3];
+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/payment.ts
 async function createPaymentIntentCore(request, body, options = {}) {
   try {
@@ -2512,7 +2577,8 @@ async function createTopupPaymentIntentCore(request, body, options = {}) {
       customerRef,
       amount: body.amount,
       currency: body.currency,
-      description: body.description
+      description: body.description,
+      ...body.autoRecharge ? { autoRecharge: body.autoRecharge } : {}
     });
     return {
       processorPaymentId: paymentIntent.processorPaymentId,
@@ -2556,7 +2622,6 @@ async function processPaymentIntentCore(request, body, options = {}) {
     return handleRouteError(error, "Process payment intent", "Payment processing failed");
   }
 }
-var TOPUP_BALANCE_POLL_DELAYS_MS = [500, 1e3, 2e3, 4e3];
 async function processTopupPaymentIntentCore(request, body, options = {}) {
   try {
     if (!body.paymentIntentId) {
@@ -2599,15 +2664,13 @@ async function processTopupPaymentIntentCore(request, body, options = {}) {
     if (preCredits === null || typeof solvaPay.getCustomerBalance !== "function") {
       return { status: "succeeded" };
     }
-    for (const delay of TOPUP_BALANCE_POLL_DELAYS_MS) {
-      await new Promise((resolve) => setTimeout(resolve, delay));
-      try {
-        const post = await solvaPay.getCustomerBalance({ customerRef });
-        if (post.credits > preCredits) {
-          return { status: "succeeded", creditsAdded: post.credits - preCredits };
-        }
-      } catch {
-      }
+    const pollResult = await pollBalanceUntilIncreased(
+      () => solvaPay.getCustomerBalance({ customerRef }),
+      preCredits,
+      TOPUP_BALANCE_POLL_DELAYS_MS
+    );
+    if (pollResult) {
+      return { status: "succeeded", creditsAdded: pollResult.creditsAdded };
     }
     return { status: "succeeded" };
   } catch (error) {
@@ -2876,6 +2939,54 @@ async function getPaymentMethodCore(request, options = {}) {
   }
 }
 
+// src/helpers/auto-recharge.ts
+async function resolveCustomerRef(request, options) {
+  return syncCustomerCore(request, {
+    solvaPay: options.solvaPay,
+    includeEmail: options.includeEmail,
+    includeName: options.includeName
+  });
+}
+async function getAutoRechargeCore(request, options = {}) {
+  try {
+    const customerRef = await resolveCustomerRef(request, options);
+    if (isErrorResult(customerRef)) return customerRef;
+    const solvaPay = options.solvaPay ?? createSolvaPay();
+    if (!solvaPay.apiClient.getAutoRecharge) {
+      return { error: "getAutoRecharge is not implemented on this API client", status: 500 };
+    }
+    return solvaPay.apiClient.getAutoRecharge({ customerRef });
+  } catch (error) {
+    return handleRouteError(error, "Get auto-recharge", "Failed to load auto-recharge");
+  }
+}
+async function saveAutoRechargeCore(request, input, options = {}) {
+  try {
+    const customerRef = await resolveCustomerRef(request, options);
+    if (isErrorResult(customerRef)) return customerRef;
+    const solvaPay = options.solvaPay ?? createSolvaPay();
+    if (!solvaPay.apiClient.saveAutoRecharge) {
+      return { error: "saveAutoRecharge is not implemented on this API client", status: 500 };
+    }
+    return solvaPay.apiClient.saveAutoRecharge({ customerRef, ...input });
+  } catch (error) {
+    return handleRouteError(error, "Save auto-recharge", "Failed to save auto-recharge");
+  }
+}
+async function disableAutoRechargeCore(request, options = {}) {
+  try {
+    const customerRef = await resolveCustomerRef(request, options);
+    if (isErrorResult(customerRef)) return customerRef;
+    const solvaPay = options.solvaPay ?? createSolvaPay();
+    if (!solvaPay.apiClient.disableAutoRecharge) {
+      return { error: "disableAutoRecharge is not implemented on this API client", status: 500 };
+    }
+    return solvaPay.apiClient.disableAutoRecharge({ customerRef });
+  } catch (error) {
+    return handleRouteError(error, "Disable auto-recharge", "Failed to disable auto-recharge");
+  }
+}
+
 // src/helpers/plans.ts
 var import_core5 = require("@solvapay/core");
 async function listPlansCore(request, options = {}) {
@@ -3175,7 +3286,9 @@ function verifyWebhook({
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BALANCE_RECONCILE_DELAYS_MS,
   PaywallError,
+  TOPUP_BALANCE_POLL_DELAYS_MS,
   VIRTUAL_TOOL_DEFINITIONS,
   activatePlanCore,
   buildGateMessage,
@@ -3192,7 +3305,9 @@ function verifyWebhook({
   createSolvaPayClient,
   createTopupPaymentIntentCore,
   createVirtualTools,
+  disableAutoRechargeCore,
   getAuthenticatedUserCore,
+  getAutoRechargeCore,
   getCustomerBalanceCore,
   getMerchantCore,
   getPaymentMethodCore,
@@ -3204,10 +3319,12 @@ function verifyWebhook({
   jsonSchemaToZodRawShape,
   listPlansCore,
   paywallErrorToClientPayload,
+  pollBalanceUntilIncreased,
   processPaymentIntentCore,
   processTopupPaymentIntentCore,
   reactivatePurchaseCore,
   registerVirtualToolsMcpImpl,
+  saveAutoRechargeCore,
   syncCustomerCore,
   trackUsageCore,
   verifyWebhook,

package/dist/index.d.cts

@@ -838,6 +838,14 @@ interface components {
              * @example 99
              */
             unitsRemaining: number;
+            autoRecharge?: components["schemas"]["AutoRechargeTriggeredResponse"];
+        };
+        AutoRechargeTriggeredResponse: {
+            /**
+             * Whether the server initiated an auto-recharge charge after this debit
+             * @example true
+             */
+            triggered: boolean;
         };
         CreditDebitSkippedResponse: {
             /** @enum {number} */
@@ -3123,6 +3131,68 @@ type ActivatePlanResult = components['schemas']['ActivatePlanResponseDto'];
  * `{ kind: 'card', ... } | { kind: 'none' }` discriminated union here.
  */
 type PaymentMethodInfo = operations['PaymentMethodSdkController_getPaymentMethod']['responses']['200']['content']['application/json'];
+type AutoRechargeStatus = 'active' | 'disabled' | 'failed' | 'pending_setup';
+type AutoRechargeConfig = {
+    enabled: boolean;
+    trigger: {
+        type: 'balance';
+        thresholdAmountMinor: number;
+    };
+    topup: {
+        mode: 'fixed';
+        amountMinor: number;
+        currency: string;
+    };
+    fundingSourceType?: 'saved_card' | 'tokenized_card';
+    paymentMethodId?: string;
+    status: AutoRechargeStatus;
+    failureCount: number;
+    lastChargeAt?: string;
+    updatedAt?: string;
+    /** Backend-computed display values — render verbatim; do not derive from trigger fields. */
+    display?: AutoRechargeDisplayBlock;
+};
+type AutoRechargeDisplayBlock = {
+    thresholdAmountMajor: number;
+    topupAmountMajor: number;
+    currency: string;
+    formatted: {
+        threshold: string;
+        topup: string;
+    };
+    exchangeRate: number;
+    rateSource: 'parity' | 'db' | 'fallback';
+};
+type CreditDisplayBlock = {
+    amountMajor: number;
+    currency: string;
+    formatted: string;
+    exchangeRate: number;
+    rateSource: 'parity' | 'db' | 'fallback';
+};
+type AutoRechargeInput = {
+    enabled: boolean;
+    triggerType: 'balance';
+    thresholdAmountMajor?: number;
+    topupAmountMajor?: number;
+    maxRecharges?: number;
+    currency: string;
+};
+/** PUT /sdk/auto-recharge — input plus request-only flags. */
+type SaveAutoRechargeInput = AutoRechargeInput & {
+    deferSetupIntent?: boolean;
+};
+type AutoRechargeResponse = {
+    config: AutoRechargeConfig | null;
+    display?: AutoRechargeDisplayBlock;
+};
+type SaveAutoRechargeResponse = {
+    config: AutoRechargeConfig;
+    display?: AutoRechargeDisplayBlock;
+    setupClientSecret?: string;
+    publishableKey?: string;
+    stripeAccountId?: string;
+};
 /**
  * SDK-facing merchant identity (source: GET /v1/sdk/merchant).
  */
@@ -3286,6 +3356,7 @@ interface SolvaPayClient {
         currency: string;
         description?: string;
         idempotencyKey?: string;
+        autoRecharge?: AutoRechargeInput;
     }): Promise<{
         processorPaymentId: string;
         clientSecret: string;
@@ -3317,6 +3388,7 @@ interface SolvaPayClient {
         displayCurrency: string;
         creditsPerMinorUnit: number;
         displayExchangeRate: number;
+        display?: CreditDisplayBlock;
     }>;
     createCheckoutSession(params: operations['CheckoutSessionSdkController_createCheckoutSession']['requestBody']['content']['application/json']): Promise<components['schemas']['CreateCheckoutSessionResponse']>;
     createCustomerSession(params: components['schemas']['CreateCustomerSessionRequest']): Promise<components['schemas']['CreateCustomerSessionResponse']>;
@@ -3324,6 +3396,17 @@ interface SolvaPayClient {
     getPaymentMethod?(params: {
         customerRef: string;
     }): Promise<PaymentMethodInfo>;
+    getAutoRecharge?(params: {
+        customerRef: string;
+    }): Promise<AutoRechargeResponse>;
+    saveAutoRecharge?(params: SaveAutoRechargeInput & {
+        customerRef: string;
+    }): Promise<SaveAutoRechargeResponse>;
+    disableAutoRecharge?(params: {
+        customerRef: string;
+    }): Promise<{
+        success: true;
+    }>;
 }
 
 /**
@@ -4006,6 +4089,7 @@ interface SolvaPay {
         currency: string;
         description?: string;
         idempotencyKey?: string;
+        autoRecharge?: AutoRechargeInput;
     }): Promise<{
         processorPaymentId: string;
         clientSecret: string;
@@ -4803,6 +4887,7 @@ type CustomerBalanceResult = {
     displayCurrency: string;
     creditsPerMinorUnit: number;
     displayExchangeRate: number;
+    display?: CreditDisplayBlock;
 };
 /**
  * Sync customer with SolvaPay backend (ensure customer exists).
@@ -4933,6 +5018,7 @@ declare function createTopupPaymentIntentCore(request: Request, body: {
     amount: number;
     currency: string;
     description?: string;
+    autoRecharge?: AutoRechargeInput;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -5171,6 +5257,17 @@ declare function getPaymentMethodCore(request: Request, options?: {
     includeName?: boolean;
 }): Promise<PaymentMethodInfo | ErrorResult>;
 
+type HelperOptions = {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+};
+declare function getAutoRechargeCore(request: Request, options?: HelperOptions): Promise<AutoRechargeResponse | ErrorResult>;
+declare function saveAutoRechargeCore(request: Request, input: AutoRechargeInput, options?: HelperOptions): Promise<SaveAutoRechargeResponse | ErrorResult>;
+declare function disableAutoRechargeCore(request: Request, options?: HelperOptions): Promise<{
+    success: true;
+} | ErrorResult>;
+
 /**
  * Plans Helper (Core)
  *
@@ -5316,6 +5413,15 @@ declare function trackUsageCore(request: Request, body: {
     solvaPay?: SolvaPay;
 }): Promise<TrackUsageResponse | ErrorResult>;
 
+declare const TOPUP_BALANCE_POLL_DELAYS_MS: readonly [500, 1000, 2000, 4000];
+/** Backoff for client-side balance reconciliation after async credit top-ups (e.g. auto-recharge). */
+declare const BALANCE_RECONCILE_DELAYS_MS: readonly [500, 1000, 2000, 4000, 8000, 16000];
+declare function pollBalanceUntilIncreased(getBalance: () => Promise<{
+    credits: number;
+}>, baseline: number, delays?: readonly number[]): Promise<{
+    creditsAdded: number;
+} | null>;
+
 /**
  * SolvaPay Server SDK
  *
@@ -5371,4 +5477,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, getAuthenticatedUserCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AuthenticatedUser, type AutoRechargeConfig, type AutoRechargeDisplayBlock, type AutoRechargeInput, type AutoRechargeResponse, BALANCE_RECONCILE_DELAYS_MS, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SaveAutoRechargeInput, type SaveAutoRechargeResponse, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, TOPUP_BALANCE_POLL_DELAYS_MS, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };

package/dist/index.d.ts

@@ -838,6 +838,14 @@ interface components {
              * @example 99
              */
             unitsRemaining: number;
+            autoRecharge?: components["schemas"]["AutoRechargeTriggeredResponse"];
+        };
+        AutoRechargeTriggeredResponse: {
+            /**
+             * Whether the server initiated an auto-recharge charge after this debit
+             * @example true
+             */
+            triggered: boolean;
         };
         CreditDebitSkippedResponse: {
             /** @enum {number} */
@@ -3123,6 +3131,68 @@ type ActivatePlanResult = components['schemas']['ActivatePlanResponseDto'];
  * `{ kind: 'card', ... } | { kind: 'none' }` discriminated union here.
  */
 type PaymentMethodInfo = operations['PaymentMethodSdkController_getPaymentMethod']['responses']['200']['content']['application/json'];
+type AutoRechargeStatus = 'active' | 'disabled' | 'failed' | 'pending_setup';
+type AutoRechargeConfig = {
+    enabled: boolean;
+    trigger: {
+        type: 'balance';
+        thresholdAmountMinor: number;
+    };
+    topup: {
+        mode: 'fixed';
+        amountMinor: number;
+        currency: string;
+    };
+    fundingSourceType?: 'saved_card' | 'tokenized_card';
+    paymentMethodId?: string;
+    status: AutoRechargeStatus;
+    failureCount: number;
+    lastChargeAt?: string;
+    updatedAt?: string;
+    /** Backend-computed display values — render verbatim; do not derive from trigger fields. */
+    display?: AutoRechargeDisplayBlock;
+};
+type AutoRechargeDisplayBlock = {
+    thresholdAmountMajor: number;
+    topupAmountMajor: number;
+    currency: string;
+    formatted: {
+        threshold: string;
+        topup: string;
+    };
+    exchangeRate: number;
+    rateSource: 'parity' | 'db' | 'fallback';
+};
+type CreditDisplayBlock = {
+    amountMajor: number;
+    currency: string;
+    formatted: string;
+    exchangeRate: number;
+    rateSource: 'parity' | 'db' | 'fallback';
+};
+type AutoRechargeInput = {
+    enabled: boolean;
+    triggerType: 'balance';
+    thresholdAmountMajor?: number;
+    topupAmountMajor?: number;
+    maxRecharges?: number;
+    currency: string;
+};
+/** PUT /sdk/auto-recharge — input plus request-only flags. */
+type SaveAutoRechargeInput = AutoRechargeInput & {
+    deferSetupIntent?: boolean;
+};
+type AutoRechargeResponse = {
+    config: AutoRechargeConfig | null;
+    display?: AutoRechargeDisplayBlock;
+};
+type SaveAutoRechargeResponse = {
+    config: AutoRechargeConfig;
+    display?: AutoRechargeDisplayBlock;
+    setupClientSecret?: string;
+    publishableKey?: string;
+    stripeAccountId?: string;
+};
 /**
  * SDK-facing merchant identity (source: GET /v1/sdk/merchant).
  */
@@ -3286,6 +3356,7 @@ interface SolvaPayClient {
         currency: string;
         description?: string;
         idempotencyKey?: string;
+        autoRecharge?: AutoRechargeInput;
     }): Promise<{
         processorPaymentId: string;
         clientSecret: string;
@@ -3317,6 +3388,7 @@ interface SolvaPayClient {
         displayCurrency: string;
         creditsPerMinorUnit: number;
         displayExchangeRate: number;
+        display?: CreditDisplayBlock;
     }>;
     createCheckoutSession(params: operations['CheckoutSessionSdkController_createCheckoutSession']['requestBody']['content']['application/json']): Promise<components['schemas']['CreateCheckoutSessionResponse']>;
     createCustomerSession(params: components['schemas']['CreateCustomerSessionRequest']): Promise<components['schemas']['CreateCustomerSessionResponse']>;
@@ -3324,6 +3396,17 @@ interface SolvaPayClient {
     getPaymentMethod?(params: {
         customerRef: string;
     }): Promise<PaymentMethodInfo>;
+    getAutoRecharge?(params: {
+        customerRef: string;
+    }): Promise<AutoRechargeResponse>;
+    saveAutoRecharge?(params: SaveAutoRechargeInput & {
+        customerRef: string;
+    }): Promise<SaveAutoRechargeResponse>;
+    disableAutoRecharge?(params: {
+        customerRef: string;
+    }): Promise<{
+        success: true;
+    }>;
 }
 
 /**
@@ -4006,6 +4089,7 @@ interface SolvaPay {
         currency: string;
         description?: string;
         idempotencyKey?: string;
+        autoRecharge?: AutoRechargeInput;
     }): Promise<{
         processorPaymentId: string;
         clientSecret: string;
@@ -4803,6 +4887,7 @@ type CustomerBalanceResult = {
     displayCurrency: string;
     creditsPerMinorUnit: number;
     displayExchangeRate: number;
+    display?: CreditDisplayBlock;
 };
 /**
  * Sync customer with SolvaPay backend (ensure customer exists).
@@ -4933,6 +5018,7 @@ declare function createTopupPaymentIntentCore(request: Request, body: {
     amount: number;
     currency: string;
     description?: string;
+    autoRecharge?: AutoRechargeInput;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -5171,6 +5257,17 @@ declare function getPaymentMethodCore(request: Request, options?: {
     includeName?: boolean;
 }): Promise<PaymentMethodInfo | ErrorResult>;
 
+type HelperOptions = {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+};
+declare function getAutoRechargeCore(request: Request, options?: HelperOptions): Promise<AutoRechargeResponse | ErrorResult>;
+declare function saveAutoRechargeCore(request: Request, input: AutoRechargeInput, options?: HelperOptions): Promise<SaveAutoRechargeResponse | ErrorResult>;
+declare function disableAutoRechargeCore(request: Request, options?: HelperOptions): Promise<{
+    success: true;
+} | ErrorResult>;
+
 /**
  * Plans Helper (Core)
  *
@@ -5316,6 +5413,15 @@ declare function trackUsageCore(request: Request, body: {
     solvaPay?: SolvaPay;
 }): Promise<TrackUsageResponse | ErrorResult>;
 
+declare const TOPUP_BALANCE_POLL_DELAYS_MS: readonly [500, 1000, 2000, 4000];
+/** Backoff for client-side balance reconciliation after async credit top-ups (e.g. auto-recharge). */
+declare const BALANCE_RECONCILE_DELAYS_MS: readonly [500, 1000, 2000, 4000, 8000, 16000];
+declare function pollBalanceUntilIncreased(getBalance: () => Promise<{
+    credits: number;
+}>, baseline: number, delays?: readonly number[]): Promise<{
+    creditsAdded: number;
+} | null>;
+
 /**
  * SolvaPay Server SDK
  *
@@ -5371,4 +5477,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, getAuthenticatedUserCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AuthenticatedUser, type AutoRechargeConfig, type AutoRechargeDisplayBlock, type AutoRechargeInput, type AutoRechargeResponse, BALANCE_RECONCILE_DELAYS_MS, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CreditDisplayBlock, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SaveAutoRechargeInput, type SaveAutoRechargeResponse, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, TOPUP_BALANCE_POLL_DELAYS_MS, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, pollBalanceUntilIncreased, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };