@solvapay/server 2.5.0 → 2.6.0-preview-253dcb103840555309a5ff5e4ccfa6a07f7ca6ae

package/dist/edge.d.ts

@@ -826,9 +826,13 @@ interface components {
         LimitBalanceDto: {
             /** @description Credit balance in credits (100 credits = 1 minor currency unit) */
             creditBalance: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
             /** @description Credits deducted per metered item (wallet coverage: remainingUnits = balance / creditsPerUnit) */
             creditsPerUnit: number;
             currency: string;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
         };
@@ -1201,17 +1205,17 @@ interface components {
         };
         ProcessPaymentCancelled: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example cancelled
              * @enum {string}
              */
-            status: 'ProcessPaymentCancelled';
+            status: 'cancelled';
         };
         ProcessPaymentFailed: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example failed
              * @enum {string}
              */
-            status: 'ProcessPaymentFailed';
+            status: 'failed';
         };
         ProcessPaymentIntentDto: {
             customerRef: string;
@@ -1220,25 +1224,25 @@ interface components {
         };
         ProcessPaymentProcessing: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example processing
              * @enum {string}
              */
-            status: 'ProcessPaymentProcessing';
+            status: 'processing';
         };
         ProcessPaymentSucceededBare: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example succeeded
              * @enum {string}
              */
-            status: 'ProcessPaymentSucceededBare';
+            status: 'succeeded';
         };
         ProcessPaymentSucceededOneTime: {
             oneTimePurchase: components['schemas']['OneTimePurchaseInfo'];
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example succeeded
              * @enum {string}
              */
-            status: 'ProcessPaymentSucceededOneTime';
+            status: 'succeeded';
             /**
              * @example one-time
              * @enum {string}
@@ -1248,10 +1252,10 @@ interface components {
         ProcessPaymentSucceededRecurring: {
             purchase: components['schemas']['SdkPurchaseResponse'];
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example succeeded
              * @enum {string}
              */
-            status: 'ProcessPaymentSucceededRecurring';
+            status: 'succeeded';
             /**
              * @example recurring
              * @enum {string}
@@ -1262,10 +1266,10 @@ interface components {
             /** @description Detail message describing the timeout */
             message?: string;
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example timeout
              * @enum {string}
              */
-            status: 'ProcessPaymentTimeout';
+            status: 'timeout';
         };
         ProductConfigDto: {
             /**
@@ -3207,10 +3211,10 @@ interface operations {
                 content: {
                     'application/json': {
                         /**
-                         * Outcome of the delete: hard delete in sandbox, soft-delete or deactivation in live depending on existing purchases
+                         * Outcome of the delete: deactivation when purchases exist, otherwise soft-delete. Same in sandbox and live.
                          * @enum {string}
                          */
-                        action?: 'deleted' | 'deactivated' | 'soft_deleted';
+                        action?: 'deactivated' | 'soft_deleted';
                         success?: boolean;
                     };
                 };
@@ -3949,38 +3953,20 @@ type OneTimePurchaseInfo = components['schemas']['OneTimePurchaseInfo'];
 /**
  * Result from processing a payment intent.
  *
- * Mirrors the backend's discriminated `oneOf` response. The `succeeded`
- * branches are further discriminated on `type` so consumers can route to
- * recurring vs one-time purchase handling without guarding against
- * `purchase === undefined`. A bare `{ status: 'succeeded' }` is returned
- * when the webhook race means the backend can't yet enrich the response
- * with the created purchase — callers should fall back to refetching.
- *
- * `failed` and `cancelled` are returned by the backend when the Stripe
- * PaymentIntent is in a terminal non-success state and are routed to
- * `onError` by `reconcilePayment`. `timeout` carries a retry hint and is
- * routed to the timeout branch.
+ * Derived from the generated `/v1/sdk/payment-intents/{id}/process` 200
+ * response. The `succeeded` branches further discriminate on `type` so
+ * consumers can route to recurring vs one-time handling without guarding
+ * against `purchase === undefined`. A bare `{ status: 'succeeded' }` is
+ * returned when the webhook race means the backend can't yet enrich the
+ * response with the created purchase — callers should fall back to
+ * refetching.
+ *
+ * `failed` and `cancelled` are returned when the Stripe PaymentIntent is
+ * in a terminal non-success state and are routed to `onError` by
+ * `reconcilePayment`. `timeout` carries a retry hint and is routed to
+ * the timeout branch.
  */
-type ProcessPaymentResult = {
-    status: 'succeeded';
-    type: 'recurring';
-    purchase: PurchaseInfo;
-} | {
-    status: 'succeeded';
-    type: 'one-time';
-    oneTimePurchase: OneTimePurchaseInfo;
-} | {
-    status: 'succeeded';
-} | {
-    status: 'processing';
-} | {
-    status: 'timeout';
-    message?: string;
-} | {
-    status: 'failed';
-} | {
-    status: 'cancelled';
-};
+type ProcessPaymentResult = operations['PaymentIntentSdkController_processPaymentIntent']['responses']['200']['content']['application/json'];
 /**
  * Result from processing a credit-topup payment intent.
  *
@@ -4291,6 +4277,10 @@ type PaywallGateRecoveryFields = {
     shortfallCredits?: number;
     /** How many calls the current allowance or wallet still covers. */
     remainingCalls?: number;
+    /** Credits per minor currency unit, from the limits balance peg. */
+    creditsPerMinorUnit?: number;
+    /** USD → display-currency rate used with `creditsPerMinorUnit`. */
+    displayExchangeRate?: number;
     /** Active purchase reference when the customer already holds a purchase. */
     purchaseRef?: string;
     /** Purchase/plan status when the backend sent one. */
@@ -5354,6 +5344,12 @@ interface SolvaPay {
      */
     paywall: {
         decide<TArgs extends PaywallArgs>(args: TArgs, metadata?: PaywallMetadata, getCustomerRef?: (args: TArgs) => string): Promise<PaywallDecision<TArgs>>;
+        /**
+         * Drop cached `checkLimits` snapshots for this customer (optionally
+         * scoped to one product). Call after `activate_plan`, a completed
+         * checkout, or a top-up so the next payable call refetches.
+         */
+        invalidateLimits(customerRef: string, product?: string): void;
     };
     /**
      * Direct access to the API client for advanced operations.
@@ -6144,7 +6140,13 @@ declare function processTopupPaymentIntentCore(request: Request, body: {
 declare function createCheckoutSessionCore(request: Request, body: {
     productRef: string;
     planRef?: string;
-    returnUrl?: string;
+    /**
+     * URL to send the customer back to after payment. Pass `null` to omit
+     * the field entirely — skips `options.returnUrl` and the request-origin
+     * fallback. Use this when the caller has no browsable page to return to
+     * (MCP servers whose public URL is an API endpoint, not a website).
+     */
+    returnUrl?: string | null;
     purpose?: 'credit_topup';
 }, options?: {
     solvaPay?: SolvaPay;

package/dist/edge.js

@@ -683,9 +683,8 @@ async function verifyProductConfiguration(options) {
 }
 
 // src/paywall-state.ts
-import { minorUnitsPerMajor } from "@solvapay/core";
+import { creditsToDisplayMinorUnits, minorUnitsPerMajor } from "@solvapay/core";
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -769,6 +768,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = creditsToDisplayMinorUnits({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -812,49 +829,51 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 function buildNudgeMessage(state, limits) {
   const url = limits?.checkoutUrl && limits.checkoutUrl.length > 0 ? limits.checkoutUrl : null;
   const visitClause = url ? `, or ${namedCheckoutMarkdown(url)}` : "";
-  const remaining = creditSignals(limits).remainingCalls;
-  switch (state.kind) {
+  const signals = creditSignals(limits);
+  const remaining = signals.remainingCalls;
+  const kind = state.kind === "topup_required" && limits && !signals.isCreditBased ? "limit_reached" : state.kind;
+  switch (kind) {
     case "topup_required":
       if (remaining === 0) {
         return `Heads up \u2014 0 calls left \u2014 the next call needs a top-up. ${callViewer("topup").replace(/^c/, "C")} to add more${visitClause}.`;
@@ -939,6 +958,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1195,6 +1216,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2214,6 +2252,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2282,7 +2323,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -2981,12 +3022,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -2994,7 +3038,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/dist/fetch/index.cjs

@@ -841,7 +841,6 @@ function createSolvaPayClient(opts) {
 // src/paywall-state.ts
 var import_core3 = require("@solvapay/core");
 var CHECKOUT_SESSION_TTL_MINUTES = 15;
-var DOCS_HINT = "See docs://solvapay/overview.md.";
 function creditSignals(limits) {
   if (!limits) return { isCreditBased: false };
   const creditBalance = limits.balance?.creditBalance ?? limits.creditBalance;
@@ -925,6 +924,24 @@ function formatMinor(amountMinor, currency) {
 function formatCredits(value) {
   return value.toLocaleString("en-US");
 }
+function formatCreditsWithMoney(credits, gate) {
+  const amount = formatCredits(credits);
+  const peg = gate.creditsPerMinorUnit;
+  const currency = gate.currency;
+  const rate = gate.displayExchangeRate;
+  if (peg && peg > 0 && currency && rate != null && rate > 0) {
+    const minor = (0, import_core3.creditsToDisplayMinorUnits)({
+      credits,
+      creditsPerMinorUnit: peg,
+      displayExchangeRate: rate,
+      displayCurrency: currency
+    });
+    if (minor != null) {
+      return `${amount} credits (~${formatMinor(minor, currency)})`;
+    }
+  }
+  return `${amount} credits`;
+}
 function meterLabel(gate) {
   if (!gate.meterName) return "units";
   return gate.meterName.replace(/_/g, " ");
@@ -968,42 +985,42 @@ function buildGateMessage(state, gate) {
       const nextLine = price ? ` The next call is ${price}.` : "";
       const planName = gate.planName ?? "This plan";
       const antiTrap = gate.creditBalance !== void 0 && gate.creditBalance > 0 && (gate.creditsPerCall === void 0 || gate.creditsPerCall === 0) ? ` Adding credits will not help, because ${planName} does not spend them.` : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : recoverClause(url, "continue", "checkout");
-      return `${usedLine}${nextLine}${antiTrap}${switchLine} ${DOCS_HINT}`;
+      const switchLine = ladder ? ` Or switch plan: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.` : recoverClause(url, "continue", "checkout");
+      return `${usedLine}${nextLine}${antiTrap}${switchLine}`;
     }
     case "activation_required":
-      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`. ${DOCS_HINT}`;
+      return `Your plan needs activation.${recoverClause(url, "activate", "checkout")} Or call \`activate_plan\` with a \`planRef\`.`;
     case "topup_required": {
       const balance = gate.creditBalance;
       const cost = gate.creditsPerCall;
       const shortfall = gate.shortfallCredits;
       let lead;
       if (balance !== void 0 && cost !== void 0 && shortfall !== void 0) {
-        lead = `Out of credits for this call. Balance ${formatCredits(balance)} credits; this call costs ${formatCredits(cost)} credits \u2014 ${formatCredits(shortfall)} short.`;
+        lead = `Out of credits for this call. Balance ${formatCreditsWithMoney(balance, gate)}; this call costs ${formatCreditsWithMoney(cost, gate)} \u2014 ${formatCredits(shortfall)} short.`;
       } else {
         lead = "Included usage is exhausted.";
       }
       const topup = recoverClause(url, "add credits", "topup", "Add credits");
-      const auto = autoRechargeDisabled(gate) ? " Auto-recharge is off \u2014 turn it on from the account tool to avoid this next time." : "";
-      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : "";
-      return `${lead}${topup}${auto}${switchLine} ${DOCS_HINT}`;
+      const auto = autoRechargeDisabled(gate) ? ` Auto-recharge is off \u2014 ${callViewer("account")} to turn it on and avoid this next time.` : "";
+      const switchLine = ladder ? ` Or switch plan: ${ladder}.` : hasActivePlan(gate) ? "" : ` Or ${callViewer("checkout")} to pick a plan.`;
+      return `${lead}${topup}${auto}${switchLine}`;
     }
     case "upgrade_required": {
       if (hasActivePlan(gate)) {
         const planName = gate.planName ?? "This plan";
         const lead = `${planName} is active but its included usage is exhausted, and the automatic switch to the next plan did not complete.`;
         if (ladder) {
-          return `${lead} Switch here: ${ladder}. ${DOCS_HINT}`;
+          return `${lead} Switch here: ${ladder}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
         }
-        return `${lead}${recoverClause(url, "switch plan", "checkout")} ${DOCS_HINT}`;
+        return `${lead}${recoverClause(url, "switch plan", "checkout")}`;
       }
       if (ladder) {
-        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${DOCS_HINT}`;
+        return `You don't have an active plan for this tool. Pick a plan to use this tool: ${ladder} (links expire in ${CHECKOUT_SESSION_TTL_MINUTES} minutes), or ${callViewer("checkout")}. ${callViewer("account").replace(/^c/, "C")} for usage and recovery.`;
       }
-      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")} ${DOCS_HINT}`;
+      return `You don't have an active plan for this tool.${recoverClause(url, "pick a plan", "checkout")}`;
     }
     case "reactivation_required":
-      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan. ${DOCS_HINT}`;
+      return `Your previous plan is no longer active. ${callViewer("account").replace(/^c/, "C")} to reactivate it, or ${callViewer("checkout")} to pick a new plan.`;
   }
 }
 
@@ -1073,6 +1090,8 @@ function recoveryFields(limits, state) {
     ...signals.creditsPerCall !== void 0 ? { creditsPerCall: signals.creditsPerCall } : {},
     ...signals.shortfallCredits !== void 0 ? { shortfallCredits: signals.shortfallCredits } : {},
     ...signals.remainingCalls !== void 0 ? { remainingCalls: signals.remainingCalls } : {},
+    ...limits.balance?.creditsPerMinorUnit !== void 0 ? { creditsPerMinorUnit: limits.balance.creditsPerMinorUnit } : {},
+    ...limits.balance?.displayExchangeRate !== void 0 ? { displayExchangeRate: limits.balance.displayExchangeRate } : {},
     ...limits.purchaseRef !== void 0 ? { purchaseRef: limits.purchaseRef } : {},
     ...limits.autoRecharge !== void 0 ? { autoRecharge: limits.autoRecharge } : {},
     ...links ? { links } : {}
@@ -1329,6 +1348,23 @@ var SolvaPayPaywall = class {
       console.log(...args);
     }
   }
+  /**
+   * Drop cached limits for `customerRef`. When `product` is omitted every
+   * meter/product entry for that customer is removed. Matches both the
+   * backend `cus_…` ref and an unmapped external ref used as a cache key.
+   */
+  invalidateLimits(customerRef, product) {
+    const aliases = /* @__PURE__ */ new Set([customerRef]);
+    const mapped = this.customerRefMapping.get(customerRef);
+    if (mapped) aliases.add(mapped);
+    if (!customerRef.startsWith("cus_")) aliases.add(`cus_${customerRef}`);
+    for (const key of [...this.limitsCache.keys()]) {
+      const [ref, prod] = key.split(":");
+      if (!ref || !aliases.has(ref)) continue;
+      if (product && prod !== product) continue;
+      this.limitsCache.delete(key);
+    }
+  }
   resolveProduct(metadata) {
     return requireProductRef(metadata.product);
   }
@@ -2348,6 +2384,9 @@ function createSolvaPay(config) {
     paywall: {
       decide(args, metadata, getCustomerRef) {
         return paywall.decide(args, metadata, getCustomerRef);
+      },
+      invalidateLimits(customerRef, product) {
+        paywall.invalidateLimits(customerRef, product);
       }
     },
     // Common API methods exposed directly for convenience
@@ -2416,7 +2455,7 @@ function createSolvaPay(config) {
         customerRef: params.customerRef,
         productRef: params.productRef,
         planRef: params.planRef,
-        returnUrl: params.returnUrl,
+        ...params.returnUrl ? { returnUrl: params.returnUrl } : {},
         ...params.purpose ? { purpose: params.purpose } : {}
       });
     },
@@ -2762,12 +2801,15 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       return customerResult;
     }
     const customerRef = customerResult;
-    let returnUrl = body.returnUrl || options.returnUrl;
-    if (!returnUrl) {
-      try {
-        const url = new URL(request.url);
-        returnUrl = url.origin;
-      } catch {
+    let returnUrl;
+    if (body.returnUrl !== null) {
+      returnUrl = body.returnUrl || options.returnUrl;
+      if (!returnUrl) {
+        try {
+          const url = new URL(request.url);
+          returnUrl = url.origin;
+        } catch {
+        }
       }
     }
     const solvaPay = options.solvaPay || createSolvaPay();
@@ -2775,7 +2817,7 @@ async function createCheckoutSessionCore(request, body, options = {}) {
       productRef: body.productRef,
       customerRef,
       planRef: body.planRef || void 0,
-      returnUrl,
+      ...returnUrl ? { returnUrl } : {},
       ...body.purpose ? { purpose: body.purpose } : {}
     });
     return {

package/dist/fetch/index.d.cts

@@ -823,9 +823,13 @@ interface components {
         LimitBalanceDto: {
             /** @description Credit balance in credits (100 credits = 1 minor currency unit) */
             creditBalance: number;
+            /** @description Credits per minor unit of `currency` (typically 100) */
+            creditsPerMinorUnit?: number;
             /** @description Credits deducted per metered item (wallet coverage: remainingUnits = balance / creditsPerUnit) */
             creditsPerUnit: number;
             currency: string;
+            /** @description USD → display-currency rate used with creditsPerMinorUnit */
+            displayExchangeRate?: number;
             /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
         };
@@ -1198,17 +1202,17 @@ interface components {
         };
         ProcessPaymentCancelled: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example cancelled
              * @enum {string}
              */
-            status: 'ProcessPaymentCancelled';
+            status: 'cancelled';
         };
         ProcessPaymentFailed: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example failed
              * @enum {string}
              */
-            status: 'ProcessPaymentFailed';
+            status: 'failed';
         };
         ProcessPaymentIntentDto: {
             customerRef: string;
@@ -1217,25 +1221,25 @@ interface components {
         };
         ProcessPaymentProcessing: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example processing
              * @enum {string}
              */
-            status: 'ProcessPaymentProcessing';
+            status: 'processing';
         };
         ProcessPaymentSucceededBare: {
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example succeeded
              * @enum {string}
              */
-            status: 'ProcessPaymentSucceededBare';
+            status: 'succeeded';
         };
         ProcessPaymentSucceededOneTime: {
             oneTimePurchase: components['schemas']['OneTimePurchaseInfo'];
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example succeeded
              * @enum {string}
              */
-            status: 'ProcessPaymentSucceededOneTime';
+            status: 'succeeded';
             /**
              * @example one-time
              * @enum {string}
@@ -1245,10 +1249,10 @@ interface components {
         ProcessPaymentSucceededRecurring: {
             purchase: components['schemas']['SdkPurchaseResponse'];
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example succeeded
              * @enum {string}
              */
-            status: 'ProcessPaymentSucceededRecurring';
+            status: 'succeeded';
             /**
              * @example recurring
              * @enum {string}
@@ -1259,10 +1263,10 @@ interface components {
             /** @description Detail message describing the timeout */
             message?: string;
             /**
-             * discriminator enum property added by openapi-typescript
+             * @example timeout
              * @enum {string}
              */
-            status: 'ProcessPaymentTimeout';
+            status: 'timeout';
         };
         ProductConfigDto: {
             /**