@solvapay/react 2.2.0 → 2.2.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @solvapay/react changelog
 
+## 2.2.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a
+
+### Patch Changes
+
+- d15f9ca: Classify each SDK paywall denial honestly and name the recovery. Credit shortfalls report balance, cost and shortfall instead of "no active plan"; included-usage exhaustion reaches `limit_reached`; failed auto-upgrades keep `upgrade_required` with distinct copy. Gate messages append a named per-plan checkout ladder when the backend sends `plans[].checkoutUrl`.
+
+  The `account` tool no longer crashes on a successful limits check (the backend never sends `plan`, and an unguarded `ref.length` threw). Tool errors now validate against the registered output schema so hosts report the real message instead of `-32602`. `attach_business_details` accepts every backend tax ID type. `already_purchased` completes activation. Top-up no longer invents a 100-credit peg when `creditsPerMinorUnit` is missing.
+
+- Updated dependencies [a67bb7c]
+- Updated dependencies [d15f9ca]
+  - @solvapay/mcp-core@0.4.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a
+  - @solvapay/core@1.7.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a
+
 ## 2.2.0
 
 ### Minor Changes

package/dist/{UsageMeter-BhxNHeRM.d.ts → UsageMeter-CkJ_nowq.d.ts}

@@ -1,5 +1,5 @@
 import React from 'react';
-import { _ as UsageSnapshot } from './useUsage-CMqxEF9d.js';
+import { _ as UsageSnapshot } from './useUsage-CfM9dQwB.js';
 
 /**
  * `<UsageMeter>` compound primitive — renders the authenticated customer's

package/dist/{UsageMeter-rga6cyfB.d.cts → UsageMeter-ClENA677.d.cts}

@@ -1,5 +1,5 @@
 import React from 'react';
-import { _ as UsageSnapshot } from './useUsage-CTgRBvFK.cjs';
+import { _ as UsageSnapshot } from './useUsage-x6DQG7xe.cjs';
 
 /**
  * `<UsageMeter>` compound primitive — renders the authenticated customer's

package/dist/{chunk-X65JBC2A.js → chunk-AW5PCAYK.js}

@@ -46,7 +46,7 @@ import {
   useTopupAmountSelector,
   validateAutoRechargeForm,
   withPaymentElementDefaults
-} from "./chunk-VTGYZIE2.js";
+} from "./chunk-LCBCOFXZ.js";
 
 // src/TopupForm.tsx
 import { jsx, jsxs } from "react/jsx-runtime";

package/dist/{chunk-VTGYZIE2.js → chunk-LCBCOFXZ.js}

@@ -2278,6 +2278,7 @@ function useActivation() {
         switch (data.status) {
           case "activated":
           case "already_active":
+          case "already_purchased":
             setState("activated");
             return "activated";
           case "topup_required":

package/dist/{chunk-FWT62B56.js → chunk-QZLY6SIU.js}

@@ -8,7 +8,7 @@ import {
   useOpenExternal,
   useSolvaPay,
   useTransport
-} from "./chunk-VTGYZIE2.js";
+} from "./chunk-LCBCOFXZ.js";
 
 // src/hooks/usePaymentMethod.ts
 import { useCallback, useEffect, useState } from "react";

package/dist/{index-BJGjKUtC.d.cts → index-D4EhOmYp.d.ts}

@@ -1,4 +1,4 @@
-import { a4 as components, b as Plan, P as PaymentFormProps, a as PrefillCustomer, A as ActivationResult, s as UseTopupAmountSelectorReturn, a5 as AutoRechargeInput, u as AutoRechargeConfig, a6 as AutoRechargeDisplayBlock, E as CheckoutStep, O as SuccessMeta } from './useUsage-CTgRBvFK.cjs';
+import { a4 as components, b as Plan, P as PaymentFormProps, a as PrefillCustomer, A as ActivationResult, s as UseTopupAmountSelectorReturn, a5 as AutoRechargeInput, u as AutoRechargeConfig, a6 as AutoRechargeDisplayBlock, E as CheckoutStep, O as SuccessMeta } from './useUsage-CfM9dQwB.js';
 import React from 'react';
 import { PaymentElement, CardElement } from '@stripe/react-stripe-js';
 import { TaxBreakdown } from '@solvapay/core';
@@ -14,6 +14,16 @@ import { PaymentIntent } from '@stripe/stripe-js';
 type LimitPlanSummary = components['schemas']['LimitPlanItemDto'];
 type LimitActivationBalance = components['schemas']['LimitBalanceDto'];
 type LimitActivationProduct = components['schemas']['LimitProductBriefDto'];
+type LimitAutoRechargeDto = components['schemas']['LimitAutoRechargeDto'];
+/**
+ * All paywall reasons the SDK recognises: every backend `paywallReason`
+ * plus the three SDK-only classifier kinds. Derived from a shared tuple
+ * so the Zod mirror in `paywall-schema.ts` cannot drift.
+ */
+declare const PAYWALL_REASONS: readonly ["activation_required", "topup_required", "payment_required", "upgrade_required", "limit_reached", "reactivation_required"];
+type PaywallReason = (typeof PAYWALL_REASONS)[number];
+declare const PAYWALL_NEXT_ACTIONS: readonly ["topup", "checkout", "activate", "account"];
+type PaywallNextAction = (typeof PAYWALL_NEXT_ACTIONS)[number];
 /**
  * Structured content for paywall errors (MCP structuredContent and manual handling).
  */
@@ -24,8 +34,10 @@ type LimitActivationProduct = components['schemas']['LimitProductBriefDto'];
  * when the backend did not send it — never defaulted.
  */
 type PaywallGateRecoveryFields = {
-    /** Active plan reference from `limits.plan`. */
+    /** Active plan reference from `limits.planRef` (falls back to deprecated `plan`). */
     planRef?: string;
+    /** Display name of the active or default plan. */
+    planName?: string;
     /** Product plans from `checkLimits` (activation already had this). */
     plans?: LimitPlanSummary[];
     /** Meter the gated call was charged against. */
@@ -45,6 +57,37 @@ type PaywallGateRecoveryFields = {
     };
     /** Prepaid credit balance, coalesced from nested or top-level fields. */
     creditBalance?: number;
+    /**
+     * `PaywallState.kind` — same vocabulary as the classifier, not a third enum.
+     * `upgrade_required` / `limit_reached` / `reactivation_required` are
+     * SDK-only; the backend's `paywallReason` is a smaller set
+     * (`activation_required` / `topup_required` / `payment_required`).
+     */
+    reason?: PaywallReason;
+    /** Single primary recovery the agent should take. */
+    nextAction?: PaywallNextAction;
+    /**
+     * Credits deducted per call. Named `creditsPerCall` on purpose:
+     * `balance.creditsPerUnit` is credits, but `plans[].creditsPerUnit`
+     * is a deprecated alias for `perUnitChargeMinor` (minor currency units).
+     */
+    creditsPerCall?: number;
+    /** `max(0, creditsPerCall - creditBalance)` when both are known. */
+    shortfallCredits?: number;
+    /** How many calls the current allowance or wallet still covers. */
+    remainingCalls?: number;
+    /** Active purchase reference when the customer already holds a purchase. */
+    purchaseRef?: string;
+    /** Purchase/plan status when the backend sent one. */
+    planStatus?: string;
+    /** Per-provider auto-recharge snapshot. Omitted when unknown. */
+    autoRecharge?: LimitAutoRechargeDto;
+    /** Global destinations. Per-plan URLs stay on `plans[].checkoutUrl`. */
+    links?: {
+        topup?: string;
+        checkout?: string;
+        manage?: string;
+    };
 };
 type PaywallStructuredContent = ({
     kind: 'payment_required';

package/dist/{index-PsjS_d7V.d.ts → index-DFtP872_.d.cts}

@@ -1,4 +1,4 @@
-import { a4 as components, b as Plan, P as PaymentFormProps, a as PrefillCustomer, A as ActivationResult, s as UseTopupAmountSelectorReturn, a5 as AutoRechargeInput, u as AutoRechargeConfig, a6 as AutoRechargeDisplayBlock, E as CheckoutStep, O as SuccessMeta } from './useUsage-CMqxEF9d.js';
+import { a4 as components, b as Plan, P as PaymentFormProps, a as PrefillCustomer, A as ActivationResult, s as UseTopupAmountSelectorReturn, a5 as AutoRechargeInput, u as AutoRechargeConfig, a6 as AutoRechargeDisplayBlock, E as CheckoutStep, O as SuccessMeta } from './useUsage-x6DQG7xe.cjs';
 import React from 'react';
 import { PaymentElement, CardElement } from '@stripe/react-stripe-js';
 import { TaxBreakdown } from '@solvapay/core';
@@ -14,6 +14,16 @@ import { PaymentIntent } from '@stripe/stripe-js';
 type LimitPlanSummary = components['schemas']['LimitPlanItemDto'];
 type LimitActivationBalance = components['schemas']['LimitBalanceDto'];
 type LimitActivationProduct = components['schemas']['LimitProductBriefDto'];
+type LimitAutoRechargeDto = components['schemas']['LimitAutoRechargeDto'];
+/**
+ * All paywall reasons the SDK recognises: every backend `paywallReason`
+ * plus the three SDK-only classifier kinds. Derived from a shared tuple
+ * so the Zod mirror in `paywall-schema.ts` cannot drift.
+ */
+declare const PAYWALL_REASONS: readonly ["activation_required", "topup_required", "payment_required", "upgrade_required", "limit_reached", "reactivation_required"];
+type PaywallReason = (typeof PAYWALL_REASONS)[number];
+declare const PAYWALL_NEXT_ACTIONS: readonly ["topup", "checkout", "activate", "account"];
+type PaywallNextAction = (typeof PAYWALL_NEXT_ACTIONS)[number];
 /**
  * Structured content for paywall errors (MCP structuredContent and manual handling).
  */
@@ -24,8 +34,10 @@ type LimitActivationProduct = components['schemas']['LimitProductBriefDto'];
  * when the backend did not send it — never defaulted.
  */
 type PaywallGateRecoveryFields = {
-    /** Active plan reference from `limits.plan`. */
+    /** Active plan reference from `limits.planRef` (falls back to deprecated `plan`). */
     planRef?: string;
+    /** Display name of the active or default plan. */
+    planName?: string;
     /** Product plans from `checkLimits` (activation already had this). */
     plans?: LimitPlanSummary[];
     /** Meter the gated call was charged against. */
@@ -45,6 +57,37 @@ type PaywallGateRecoveryFields = {
     };
     /** Prepaid credit balance, coalesced from nested or top-level fields. */
     creditBalance?: number;
+    /**
+     * `PaywallState.kind` — same vocabulary as the classifier, not a third enum.
+     * `upgrade_required` / `limit_reached` / `reactivation_required` are
+     * SDK-only; the backend's `paywallReason` is a smaller set
+     * (`activation_required` / `topup_required` / `payment_required`).
+     */
+    reason?: PaywallReason;
+    /** Single primary recovery the agent should take. */
+    nextAction?: PaywallNextAction;
+    /**
+     * Credits deducted per call. Named `creditsPerCall` on purpose:
+     * `balance.creditsPerUnit` is credits, but `plans[].creditsPerUnit`
+     * is a deprecated alias for `perUnitChargeMinor` (minor currency units).
+     */
+    creditsPerCall?: number;
+    /** `max(0, creditsPerCall - creditBalance)` when both are known. */
+    shortfallCredits?: number;
+    /** How many calls the current allowance or wallet still covers. */
+    remainingCalls?: number;
+    /** Active purchase reference when the customer already holds a purchase. */
+    purchaseRef?: string;
+    /** Purchase/plan status when the backend sent one. */
+    planStatus?: string;
+    /** Per-provider auto-recharge snapshot. Omitted when unknown. */
+    autoRecharge?: LimitAutoRechargeDto;
+    /** Global destinations. Per-plan URLs stay on `plans[].checkoutUrl`. */
+    links?: {
+        topup?: string;
+        checkout?: string;
+        manage?: string;
+    };
 };
 type PaywallStructuredContent = ({
     kind: 'payment_required';

package/dist/index.cjs

@@ -2748,6 +2748,7 @@ function useActivation() {
         switch (data.status) {
           case "activated":
           case "already_active":
+          case "already_purchased":
             setState("activated");
             return "activated";
           case "topup_required":

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import React from 'react';
-import { S as SolvaPayProviderProps, P as PaymentFormProps, a as PrefillCustomer, T as TopupFormProps, C as CheckoutResult, b as Plan, A as ActivationResult, B as BootstrapPlanLike, c as SaveAutoRechargeResponse, d as PurchaseStatus, e as SolvaPayContextValue, U as UsePlansOptions, f as UsePlansReturn, g as UsePlanOptions, h as UsePlanReturn, i as UseProductReturn, j as UseMerchantReturn, k as SolvaPayCopy, l as PurchaseStatusReturn, m as CancelResult, R as ReactivateResult, n as ActivatePlanResult, o as UseTopupOptions, p as UseTopupReturn, q as BalanceStatus, r as UseTopupAmountSelectorOptions, s as UseTopupAmountSelectorReturn, t as UsePaymentMethodReturn, u as AutoRechargeConfig, v as SaveAutoRechargeInput, w as SolvaPayTransport, x as PartialSolvaPayCopy, y as PurchaseInfo, z as Product, D as SolvaPayConfig } from './useUsage-CTgRBvFK.cjs';
-export { E as CheckoutStep, F as CustomerPurchaseData, M as MandateContext, G as MandateTemplate, H as Merchant, I as PaymentError, J as PaymentIntentResult, K as PaymentMethodInfo, L as PaymentResult, N as PurchaseStatusValue, O as SuccessMeta, Q as TopupPaymentResult, V as TransportBalanceResult, W as TransportCheckoutSessionResult, X as TransportCustomerSessionResult, Y as TransportLimitsResult, Z as UnsupportedTransportMethodError, _ as UsageSnapshot, $ as UseUsageReturn, a0 as useUsage } from './useUsage-CTgRBvFK.cjs';
-import { P as PaymentFormSummary, a as PaymentFormCustomerFields, b as PaymentFormPaymentElement, c as PaymentFormCardElement, d as PaymentFormMandateText, e as PaymentFormTermsCheckbox, f as PaymentFormSubmitButton, g as PaymentFormLoading, h as PaymentFormError, i as PaymentFormLegalFooter, j as PaymentFormBusinessDetails, k as PaymentFormTaxSummary, A as AutoRechargeInputPayload, l as PaywallStructuredContent, C as CheckoutVariant } from './index-BJGjKUtC.cjs';
-export { m as ActivationFlowStep, B as BalanceBadge, n as CancelPlanButton, o as CheckoutErrorPhase, p as CheckoutStatus, q as CheckoutSteps, r as CheckoutSummary, s as CheckoutSummaryProps, M as MandateText, t as MandateTextProps, u as PlanBadge, v as ProductBadge, w as PurchaseGate, U as UseCheckoutFlowOptions, x as UseCheckoutFlowReturn, y as configToAutoRechargeInput, z as deriveVariant, D as useCheckoutFlow, E as useCheckoutStepsContext } from './index-BJGjKUtC.cjs';
+import { S as SolvaPayProviderProps, P as PaymentFormProps, a as PrefillCustomer, T as TopupFormProps, C as CheckoutResult, b as Plan, A as ActivationResult, B as BootstrapPlanLike, c as SaveAutoRechargeResponse, d as PurchaseStatus, e as SolvaPayContextValue, U as UsePlansOptions, f as UsePlansReturn, g as UsePlanOptions, h as UsePlanReturn, i as UseProductReturn, j as UseMerchantReturn, k as SolvaPayCopy, l as PurchaseStatusReturn, m as CancelResult, R as ReactivateResult, n as ActivatePlanResult, o as UseTopupOptions, p as UseTopupReturn, q as BalanceStatus, r as UseTopupAmountSelectorOptions, s as UseTopupAmountSelectorReturn, t as UsePaymentMethodReturn, u as AutoRechargeConfig, v as SaveAutoRechargeInput, w as SolvaPayTransport, x as PartialSolvaPayCopy, y as PurchaseInfo, z as Product, D as SolvaPayConfig } from './useUsage-x6DQG7xe.cjs';
+export { E as CheckoutStep, F as CustomerPurchaseData, M as MandateContext, G as MandateTemplate, H as Merchant, I as PaymentError, J as PaymentIntentResult, K as PaymentMethodInfo, L as PaymentResult, N as PurchaseStatusValue, O as SuccessMeta, Q as TopupPaymentResult, V as TransportBalanceResult, W as TransportCheckoutSessionResult, X as TransportCustomerSessionResult, Y as TransportLimitsResult, Z as UnsupportedTransportMethodError, _ as UsageSnapshot, $ as UseUsageReturn, a0 as useUsage } from './useUsage-x6DQG7xe.cjs';
+import { P as PaymentFormSummary, a as PaymentFormCustomerFields, b as PaymentFormPaymentElement, c as PaymentFormCardElement, d as PaymentFormMandateText, e as PaymentFormTermsCheckbox, f as PaymentFormSubmitButton, g as PaymentFormLoading, h as PaymentFormError, i as PaymentFormLegalFooter, j as PaymentFormBusinessDetails, k as PaymentFormTaxSummary, A as AutoRechargeInputPayload, l as PaywallStructuredContent, C as CheckoutVariant } from './index-DFtP872_.cjs';
+export { m as ActivationFlowStep, B as BalanceBadge, n as CancelPlanButton, o as CheckoutErrorPhase, p as CheckoutStatus, q as CheckoutSteps, r as CheckoutSummary, s as CheckoutSummaryProps, M as MandateText, t as MandateTextProps, u as PlanBadge, v as ProductBadge, w as PurchaseGate, U as UseCheckoutFlowOptions, x as UseCheckoutFlowReturn, y as configToAutoRechargeInput, z as deriveVariant, D as useCheckoutFlow, E as useCheckoutStepsContext } from './index-DFtP872_.cjs';
 import { PaymentIntent, Stripe, StripeElements } from '@stripe/stripe-js';
 import { BusinessDetailsInput, TaxBreakdown } from '@solvapay/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import React from 'react';
-import { S as SolvaPayProviderProps, P as PaymentFormProps, a as PrefillCustomer, T as TopupFormProps, C as CheckoutResult, b as Plan, A as ActivationResult, B as BootstrapPlanLike, c as SaveAutoRechargeResponse, d as PurchaseStatus, e as SolvaPayContextValue, U as UsePlansOptions, f as UsePlansReturn, g as UsePlanOptions, h as UsePlanReturn, i as UseProductReturn, j as UseMerchantReturn, k as SolvaPayCopy, l as PurchaseStatusReturn, m as CancelResult, R as ReactivateResult, n as ActivatePlanResult, o as UseTopupOptions, p as UseTopupReturn, q as BalanceStatus, r as UseTopupAmountSelectorOptions, s as UseTopupAmountSelectorReturn, t as UsePaymentMethodReturn, u as AutoRechargeConfig, v as SaveAutoRechargeInput, w as SolvaPayTransport, x as PartialSolvaPayCopy, y as PurchaseInfo, z as Product, D as SolvaPayConfig } from './useUsage-CMqxEF9d.js';
-export { E as CheckoutStep, F as CustomerPurchaseData, M as MandateContext, G as MandateTemplate, H as Merchant, I as PaymentError, J as PaymentIntentResult, K as PaymentMethodInfo, L as PaymentResult, N as PurchaseStatusValue, O as SuccessMeta, Q as TopupPaymentResult, V as TransportBalanceResult, W as TransportCheckoutSessionResult, X as TransportCustomerSessionResult, Y as TransportLimitsResult, Z as UnsupportedTransportMethodError, _ as UsageSnapshot, $ as UseUsageReturn, a0 as useUsage } from './useUsage-CMqxEF9d.js';
-import { P as PaymentFormSummary, a as PaymentFormCustomerFields, b as PaymentFormPaymentElement, c as PaymentFormCardElement, d as PaymentFormMandateText, e as PaymentFormTermsCheckbox, f as PaymentFormSubmitButton, g as PaymentFormLoading, h as PaymentFormError, i as PaymentFormLegalFooter, j as PaymentFormBusinessDetails, k as PaymentFormTaxSummary, A as AutoRechargeInputPayload, l as PaywallStructuredContent, C as CheckoutVariant } from './index-PsjS_d7V.js';
-export { m as ActivationFlowStep, B as BalanceBadge, n as CancelPlanButton, o as CheckoutErrorPhase, p as CheckoutStatus, q as CheckoutSteps, r as CheckoutSummary, s as CheckoutSummaryProps, M as MandateText, t as MandateTextProps, u as PlanBadge, v as ProductBadge, w as PurchaseGate, U as UseCheckoutFlowOptions, x as UseCheckoutFlowReturn, y as configToAutoRechargeInput, z as deriveVariant, D as useCheckoutFlow, E as useCheckoutStepsContext } from './index-PsjS_d7V.js';
+import { S as SolvaPayProviderProps, P as PaymentFormProps, a as PrefillCustomer, T as TopupFormProps, C as CheckoutResult, b as Plan, A as ActivationResult, B as BootstrapPlanLike, c as SaveAutoRechargeResponse, d as PurchaseStatus, e as SolvaPayContextValue, U as UsePlansOptions, f as UsePlansReturn, g as UsePlanOptions, h as UsePlanReturn, i as UseProductReturn, j as UseMerchantReturn, k as SolvaPayCopy, l as PurchaseStatusReturn, m as CancelResult, R as ReactivateResult, n as ActivatePlanResult, o as UseTopupOptions, p as UseTopupReturn, q as BalanceStatus, r as UseTopupAmountSelectorOptions, s as UseTopupAmountSelectorReturn, t as UsePaymentMethodReturn, u as AutoRechargeConfig, v as SaveAutoRechargeInput, w as SolvaPayTransport, x as PartialSolvaPayCopy, y as PurchaseInfo, z as Product, D as SolvaPayConfig } from './useUsage-CfM9dQwB.js';
+export { E as CheckoutStep, F as CustomerPurchaseData, M as MandateContext, G as MandateTemplate, H as Merchant, I as PaymentError, J as PaymentIntentResult, K as PaymentMethodInfo, L as PaymentResult, N as PurchaseStatusValue, O as SuccessMeta, Q as TopupPaymentResult, V as TransportBalanceResult, W as TransportCheckoutSessionResult, X as TransportCustomerSessionResult, Y as TransportLimitsResult, Z as UnsupportedTransportMethodError, _ as UsageSnapshot, $ as UseUsageReturn, a0 as useUsage } from './useUsage-CfM9dQwB.js';
+import { P as PaymentFormSummary, a as PaymentFormCustomerFields, b as PaymentFormPaymentElement, c as PaymentFormCardElement, d as PaymentFormMandateText, e as PaymentFormTermsCheckbox, f as PaymentFormSubmitButton, g as PaymentFormLoading, h as PaymentFormError, i as PaymentFormLegalFooter, j as PaymentFormBusinessDetails, k as PaymentFormTaxSummary, A as AutoRechargeInputPayload, l as PaywallStructuredContent, C as CheckoutVariant } from './index-D4EhOmYp.js';
+export { m as ActivationFlowStep, B as BalanceBadge, n as CancelPlanButton, o as CheckoutErrorPhase, p as CheckoutStatus, q as CheckoutSteps, r as CheckoutSummary, s as CheckoutSummaryProps, M as MandateText, t as MandateTextProps, u as PlanBadge, v as ProductBadge, w as PurchaseGate, U as UseCheckoutFlowOptions, x as UseCheckoutFlowReturn, y as configToAutoRechargeInput, z as deriveVariant, D as useCheckoutFlow, E as useCheckoutStepsContext } from './index-D4EhOmYp.js';
 import { PaymentIntent, Stripe, StripeElements } from '@stripe/stripe-js';
 import { BusinessDetailsInput, TaxBreakdown } from '@solvapay/core';
 import * as react_jsx_runtime from 'react/jsx-runtime';

package/dist/index.js

@@ -4,7 +4,7 @@ import {
 import {
   LaunchCustomerPortalButton,
   usePaymentMethod
-} from "./chunk-FWT62B56.js";
+} from "./chunk-QZLY6SIU.js";
 import {
   ActivationFlow,
   AutoRecharge,
@@ -19,7 +19,7 @@ import {
   useCheckoutSteps,
   useCreditGate,
   usePaywallResolver
-} from "./chunk-X65JBC2A.js";
+} from "./chunk-AW5PCAYK.js";
 import {
   AmountPicker,
   BalanceBadge,
@@ -100,7 +100,7 @@ import {
   useTopupAmountSelector,
   useTransport,
   useUsage
-} from "./chunk-VTGYZIE2.js";
+} from "./chunk-LCBCOFXZ.js";
 import {
   createAnonymousAuthAdapter,
   defaultAuthAdapter,

package/dist/mcp/index.cjs

@@ -5343,6 +5343,7 @@ function useActivation() {
         switch (data.status) {
           case "activated":
           case "already_active":
+          case "already_purchased":
             setState("activated");
             return "activated";
           case "topup_required":
@@ -12334,7 +12335,9 @@ function EmbeddedTopup({
         autoRecharge: screen.autoRecharge,
         returnUrl,
         onSuccess: () => {
-          adjustBalance(committedAmountMinor * (creditsPerMinorUnit ?? 100));
+          if (creditsPerMinorUnit != null && creditsPerMinorUnit > 0) {
+            adjustBalance(committedAmountMinor * creditsPerMinorUnit);
+          }
           setScreen({ step: "success", amountMinor: committedAmountMinor });
           void notifyModelContext({
             text: `Topup of ${formatPrice(committedAmountMinor, currency, {

package/dist/mcp/index.d.cts

@@ -1,10 +1,10 @@
-import { w as SolvaPayTransport, a1 as SolvaPayProviderInitial, D as SolvaPayConfig, B as BootstrapPlanLike, y as PurchaseInfo, a2 as CreditActivityType, a3 as CreditActivityEntry, H as Merchant } from '../useUsage-CTgRBvFK.cjs';
+import { w as SolvaPayTransport, a1 as SolvaPayProviderInitial, D as SolvaPayConfig, B as BootstrapPlanLike, y as PurchaseInfo, a2 as CreditActivityType, a3 as CreditActivityEntry, H as Merchant } from '../useUsage-x6DQG7xe.cjs';
 import { TOOL_FOR_VIEW, SolvaPayMcpViewKind, BootstrapMerchant, BootstrapProduct, BootstrapPlan, BootstrapCustomer } from '@solvapay/mcp-core';
 export { MCP_TOOL_NAMES, McpToolName } from '@solvapay/mcp-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import { PricingOptionLike, PricedLike, BalancePegLike } from '@solvapay/core';
-import { U as UsageMeterRootProps } from '../UsageMeter-rga6cyfB.cjs';
+import { U as UsageMeterRootProps } from '../UsageMeter-ClENA677.cjs';
 import '@stripe/stripe-js';
 import '../adapters/auth.cjs';
 

package/dist/mcp/index.d.ts

@@ -1,10 +1,10 @@
-import { w as SolvaPayTransport, a1 as SolvaPayProviderInitial, D as SolvaPayConfig, B as BootstrapPlanLike, y as PurchaseInfo, a2 as CreditActivityType, a3 as CreditActivityEntry, H as Merchant } from '../useUsage-CMqxEF9d.js';
+import { w as SolvaPayTransport, a1 as SolvaPayProviderInitial, D as SolvaPayConfig, B as BootstrapPlanLike, y as PurchaseInfo, a2 as CreditActivityType, a3 as CreditActivityEntry, H as Merchant } from '../useUsage-CfM9dQwB.js';
 import { TOOL_FOR_VIEW, SolvaPayMcpViewKind, BootstrapMerchant, BootstrapProduct, BootstrapPlan, BootstrapCustomer } from '@solvapay/mcp-core';
 export { MCP_TOOL_NAMES, McpToolName } from '@solvapay/mcp-core';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import { PricingOptionLike, PricedLike, BalancePegLike } from '@solvapay/core';
-import { U as UsageMeterRootProps } from '../UsageMeter-BhxNHeRM.js';
+import { U as UsageMeterRootProps } from '../UsageMeter-CkJ_nowq.js';
 import '@stripe/stripe-js';
 import '../adapters/auth.js';
 

package/dist/mcp/index.js

@@ -3,7 +3,7 @@ import {
   LaunchCustomerPortalButton,
   paymentMethodCache,
   usePaymentMethod
-} from "../chunk-FWT62B56.js";
+} from "../chunk-QZLY6SIU.js";
 import {
   AmountPicker,
   BalanceBadge,
@@ -63,7 +63,7 @@ import {
   useTransport,
   useUsage,
   validateAutoRechargeForm
-} from "../chunk-VTGYZIE2.js";
+} from "../chunk-LCBCOFXZ.js";
 import "../chunk-UMXOAUW7.js";
 import "../chunk-MLKGABMK.js";
 
@@ -4221,7 +4221,9 @@ function EmbeddedTopup({
         autoRecharge: screen.autoRecharge,
         returnUrl,
         onSuccess: () => {
-          adjustBalance(committedAmountMinor * (creditsPerMinorUnit ?? 100));
+          if (creditsPerMinorUnit != null && creditsPerMinorUnit > 0) {
+            adjustBalance(committedAmountMinor * creditsPerMinorUnit);
+          }
           setScreen({ step: "success", amountMinor: committedAmountMinor });
           void notifyModelContext({
             text: `Topup of ${formatPrice(committedAmountMinor, currency, {

package/dist/primitives/index.cjs

@@ -3180,6 +3180,7 @@ function useActivation() {
         switch (data.status) {
           case "activated":
           case "already_active":
+          case "already_purchased":
             setState("activated");
             return "activated";
           case "topup_required":

package/dist/primitives/index.d.cts

@@ -1,13 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { Ref } from 'react';
-import { b as Plan, z as Product, s as UseTopupAmountSelectorReturn, y as PurchaseInfo, T as TopupFormProps, c as SaveAutoRechargeResponse, u as AutoRechargeConfig } from '../useUsage-CTgRBvFK.cjs';
-export { B as BootstrapPlanLike, E as CheckoutStep, O as SuccessMeta } from '../useUsage-CTgRBvFK.cjs';
+import { b as Plan, z as Product, s as UseTopupAmountSelectorReturn, y as PurchaseInfo, T as TopupFormProps, c as SaveAutoRechargeResponse, u as AutoRechargeConfig } from '../useUsage-x6DQG7xe.cjs';
+export { B as BootstrapPlanLike, E as CheckoutStep, O as SuccessMeta } from '../useUsage-x6DQG7xe.cjs';
 import { TaxBreakdown, BusinessDetailsInput } from '@solvapay/core';
-import { A as AutoRechargeInputPayload, F as AmountInputUnit, G as AutoRechargeFormState, l as PaywallStructuredContent } from '../index-BJGjKUtC.cjs';
-export { H as ActivationFlow, I as ActivationFlowActivateButton, J as ActivationFlowActivated, K as ActivationFlowAmountPicker, L as ActivationFlowContinueButton, N as ActivationFlowError, O as ActivationFlowLoading, Q as ActivationFlowRetrying, R as ActivationFlowRoot, m as ActivationFlowStep, S as ActivationFlowSummary, B as BalanceBadge, n as CancelPlanButton, p as CheckoutStatus, q as CheckoutSteps, T as CheckoutStepsAmountContinueButton, V as CheckoutStepsAmountPicker, W as CheckoutStepsBackLink, X as CheckoutStepsIfStep, Y as CheckoutStepsPayment, Z as CheckoutStepsPlanContinueButton, _ as CheckoutStepsPlanGrid, $ as CheckoutStepsRoot, a0 as CheckoutStepsStepHeading, a1 as CheckoutStepsStepMessage, a2 as CheckoutStepsSuccess, M as MandateText, t as MandateTextProps, a3 as PaymentForm, j as PaymentFormBusinessDetails, c as PaymentFormCardElement, a as PaymentFormCustomerFields, h as PaymentFormError, i as PaymentFormLegalFooter, g as PaymentFormLoading, d as PaymentFormMandateText, b as PaymentFormPaymentElement, a4 as PaymentFormRoot, f as PaymentFormSubmitButton, P as PaymentFormSummary, k as PaymentFormTaxSummary, e as PaymentFormTermsCheckbox, u as PlanBadge, v as ProductBadge, w as PurchaseGate, a5 as PurchaseGateAllowed, a6 as PurchaseGateBlocked, a7 as PurchaseGateError, a8 as PurchaseGateLoading, a9 as PurchaseGateRoot, aa as useActivationFlow, E as useCheckoutStepsContext, ab as usePurchaseGate } from '../index-BJGjKUtC.cjs';
+import { A as AutoRechargeInputPayload, F as AmountInputUnit, G as AutoRechargeFormState, l as PaywallStructuredContent } from '../index-DFtP872_.cjs';
+export { H as ActivationFlow, I as ActivationFlowActivateButton, J as ActivationFlowActivated, K as ActivationFlowAmountPicker, L as ActivationFlowContinueButton, N as ActivationFlowError, O as ActivationFlowLoading, Q as ActivationFlowRetrying, R as ActivationFlowRoot, m as ActivationFlowStep, S as ActivationFlowSummary, B as BalanceBadge, n as CancelPlanButton, p as CheckoutStatus, q as CheckoutSteps, T as CheckoutStepsAmountContinueButton, V as CheckoutStepsAmountPicker, W as CheckoutStepsBackLink, X as CheckoutStepsIfStep, Y as CheckoutStepsPayment, Z as CheckoutStepsPlanContinueButton, _ as CheckoutStepsPlanGrid, $ as CheckoutStepsRoot, a0 as CheckoutStepsStepHeading, a1 as CheckoutStepsStepMessage, a2 as CheckoutStepsSuccess, M as MandateText, t as MandateTextProps, a3 as PaymentForm, j as PaymentFormBusinessDetails, c as PaymentFormCardElement, a as PaymentFormCustomerFields, h as PaymentFormError, i as PaymentFormLegalFooter, g as PaymentFormLoading, d as PaymentFormMandateText, b as PaymentFormPaymentElement, a4 as PaymentFormRoot, f as PaymentFormSubmitButton, P as PaymentFormSummary, k as PaymentFormTaxSummary, e as PaymentFormTermsCheckbox, u as PlanBadge, v as ProductBadge, w as PurchaseGate, a5 as PurchaseGateAllowed, a6 as PurchaseGateBlocked, a7 as PurchaseGateError, a8 as PurchaseGateLoading, a9 as PurchaseGateRoot, aa as useActivationFlow, E as useCheckoutStepsContext, ab as usePurchaseGate } from '../index-DFtP872_.cjs';
 import { PaymentElement } from '@stripe/react-stripe-js';
 import { Stripe, StripeElements } from '@stripe/stripe-js';
-export { a as UsageMeter, B as UsageMeterBar, b as UsageMeterClassNames, E as UsageMeterEmpty, L as UsageMeterLabel, c as UsageMeterLoading, P as UsageMeterPercentage, R as UsageMeterResetsIn, d as UsageMeterRoot, U as UsageMeterRootProps, u as useUsageMeter } from '../UsageMeter-rga6cyfB.cjs';
+export { a as UsageMeter, B as UsageMeterBar, b as UsageMeterClassNames, E as UsageMeterEmpty, L as UsageMeterLabel, c as UsageMeterLoading, P as UsageMeterPercentage, R as UsageMeterResetsIn, d as UsageMeterRoot, U as UsageMeterRootProps, u as useUsageMeter } from '../UsageMeter-ClENA677.cjs';
 import '../adapters/auth.cjs';
 
 type PlanPricingOption = {

package/dist/primitives/index.d.ts

@@ -1,13 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React, { Ref } from 'react';
-import { b as Plan, z as Product, s as UseTopupAmountSelectorReturn, y as PurchaseInfo, T as TopupFormProps, c as SaveAutoRechargeResponse, u as AutoRechargeConfig } from '../useUsage-CMqxEF9d.js';
-export { B as BootstrapPlanLike, E as CheckoutStep, O as SuccessMeta } from '../useUsage-CMqxEF9d.js';
+import { b as Plan, z as Product, s as UseTopupAmountSelectorReturn, y as PurchaseInfo, T as TopupFormProps, c as SaveAutoRechargeResponse, u as AutoRechargeConfig } from '../useUsage-CfM9dQwB.js';
+export { B as BootstrapPlanLike, E as CheckoutStep, O as SuccessMeta } from '../useUsage-CfM9dQwB.js';
 import { TaxBreakdown, BusinessDetailsInput } from '@solvapay/core';
-import { A as AutoRechargeInputPayload, F as AmountInputUnit, G as AutoRechargeFormState, l as PaywallStructuredContent } from '../index-PsjS_d7V.js';
-export { H as ActivationFlow, I as ActivationFlowActivateButton, J as ActivationFlowActivated, K as ActivationFlowAmountPicker, L as ActivationFlowContinueButton, N as ActivationFlowError, O as ActivationFlowLoading, Q as ActivationFlowRetrying, R as ActivationFlowRoot, m as ActivationFlowStep, S as ActivationFlowSummary, B as BalanceBadge, n as CancelPlanButton, p as CheckoutStatus, q as CheckoutSteps, T as CheckoutStepsAmountContinueButton, V as CheckoutStepsAmountPicker, W as CheckoutStepsBackLink, X as CheckoutStepsIfStep, Y as CheckoutStepsPayment, Z as CheckoutStepsPlanContinueButton, _ as CheckoutStepsPlanGrid, $ as CheckoutStepsRoot, a0 as CheckoutStepsStepHeading, a1 as CheckoutStepsStepMessage, a2 as CheckoutStepsSuccess, M as MandateText, t as MandateTextProps, a3 as PaymentForm, j as PaymentFormBusinessDetails, c as PaymentFormCardElement, a as PaymentFormCustomerFields, h as PaymentFormError, i as PaymentFormLegalFooter, g as PaymentFormLoading, d as PaymentFormMandateText, b as PaymentFormPaymentElement, a4 as PaymentFormRoot, f as PaymentFormSubmitButton, P as PaymentFormSummary, k as PaymentFormTaxSummary, e as PaymentFormTermsCheckbox, u as PlanBadge, v as ProductBadge, w as PurchaseGate, a5 as PurchaseGateAllowed, a6 as PurchaseGateBlocked, a7 as PurchaseGateError, a8 as PurchaseGateLoading, a9 as PurchaseGateRoot, aa as useActivationFlow, E as useCheckoutStepsContext, ab as usePurchaseGate } from '../index-PsjS_d7V.js';
+import { A as AutoRechargeInputPayload, F as AmountInputUnit, G as AutoRechargeFormState, l as PaywallStructuredContent } from '../index-D4EhOmYp.js';
+export { H as ActivationFlow, I as ActivationFlowActivateButton, J as ActivationFlowActivated, K as ActivationFlowAmountPicker, L as ActivationFlowContinueButton, N as ActivationFlowError, O as ActivationFlowLoading, Q as ActivationFlowRetrying, R as ActivationFlowRoot, m as ActivationFlowStep, S as ActivationFlowSummary, B as BalanceBadge, n as CancelPlanButton, p as CheckoutStatus, q as CheckoutSteps, T as CheckoutStepsAmountContinueButton, V as CheckoutStepsAmountPicker, W as CheckoutStepsBackLink, X as CheckoutStepsIfStep, Y as CheckoutStepsPayment, Z as CheckoutStepsPlanContinueButton, _ as CheckoutStepsPlanGrid, $ as CheckoutStepsRoot, a0 as CheckoutStepsStepHeading, a1 as CheckoutStepsStepMessage, a2 as CheckoutStepsSuccess, M as MandateText, t as MandateTextProps, a3 as PaymentForm, j as PaymentFormBusinessDetails, c as PaymentFormCardElement, a as PaymentFormCustomerFields, h as PaymentFormError, i as PaymentFormLegalFooter, g as PaymentFormLoading, d as PaymentFormMandateText, b as PaymentFormPaymentElement, a4 as PaymentFormRoot, f as PaymentFormSubmitButton, P as PaymentFormSummary, k as PaymentFormTaxSummary, e as PaymentFormTermsCheckbox, u as PlanBadge, v as ProductBadge, w as PurchaseGate, a5 as PurchaseGateAllowed, a6 as PurchaseGateBlocked, a7 as PurchaseGateError, a8 as PurchaseGateLoading, a9 as PurchaseGateRoot, aa as useActivationFlow, E as useCheckoutStepsContext, ab as usePurchaseGate } from '../index-D4EhOmYp.js';
 import { PaymentElement } from '@stripe/react-stripe-js';
 import { Stripe, StripeElements } from '@stripe/stripe-js';
-export { a as UsageMeter, B as UsageMeterBar, b as UsageMeterClassNames, E as UsageMeterEmpty, L as UsageMeterLabel, c as UsageMeterLoading, P as UsageMeterPercentage, R as UsageMeterResetsIn, d as UsageMeterRoot, U as UsageMeterRootProps, u as useUsageMeter } from '../UsageMeter-BhxNHeRM.js';
+export { a as UsageMeter, B as UsageMeterBar, b as UsageMeterClassNames, E as UsageMeterEmpty, L as UsageMeterLabel, c as UsageMeterLoading, P as UsageMeterPercentage, R as UsageMeterResetsIn, d as UsageMeterRoot, U as UsageMeterRootProps, u as useUsageMeter } from '../UsageMeter-CkJ_nowq.js';
 import '../adapters/auth.js';
 
 type PlanPricingOption = {

package/dist/primitives/index.js

@@ -89,7 +89,7 @@ import {
   useCreditGate,
   usePaywallNotice,
   usePurchaseGate
-} from "../chunk-X65JBC2A.js";
+} from "../chunk-AW5PCAYK.js";
 import {
   AmountPicker,
   AmountPickerConfirm,
@@ -175,7 +175,7 @@ import {
   usePlanSelector,
   useTopupForm,
   useUsageMeter
-} from "../chunk-VTGYZIE2.js";
+} from "../chunk-LCBCOFXZ.js";
 import "../chunk-UMXOAUW7.js";
 import "../chunk-MLKGABMK.js";
 export {

package/dist/{useUsage-CMqxEF9d.d.ts → useUsage-CfM9dQwB.d.ts}

@@ -820,6 +820,12 @@ interface components {
             /** @description Whether the grant was recorded */
             success: boolean;
         };
+        LimitAutoRechargeDto: {
+            /** @description Whether auto-recharge is enabled for this provider */
+            enabled: boolean;
+            /** @description Stored auto-recharge status when a config exists */
+            status?: string;
+        };
         LimitBalanceDto: {
             /** @description Credit balance in credits (100 credits = 1 minor currency unit) */
             creditBalance: number;
@@ -832,6 +838,8 @@ interface components {
         LimitPlanItemDto: {
             /** @description Derived billing cycle */
             billingCycle?: string;
+            /** @description Deep link that opens hosted checkout with this plan preselected. Present only when a checkout session was minted for this response. */
+            checkoutUrl?: string;
             /**
              * @deprecated
              * @description Deprecated alias of perUnitChargeMinor. Same minor-units value — not credits. Prefer perUnitChargeMinor.
@@ -861,6 +869,8 @@ interface components {
         LimitResponse: {
             /** @description True when the customer must activate a priced default plan before usage is allowed */
             activationRequired?: boolean;
+            /** @description Per-provider auto-recharge snapshot read off the customer document. Omitted when no config exists. */
+            autoRecharge?: components['schemas']['LimitAutoRechargeDto'];
             /** @description Prepaid usage balance context when the default plan is usage-based */
             balance?: components['schemas']['LimitBalanceDto'];
             /**
@@ -881,9 +891,7 @@ interface components {
             creditsPerUnit?: number;
             /** @description ISO 4217 currency code for credit fields */
             currency?: string;
-            /**
-             * The effective finite cap for this meter. Present only when the backend measured a finite cap.
-             */
+            /** @description The effective finite cap for this meter. Present only when the backend measured a finite cap. */
             limit?: number;
             /**
              * The meter name to use when tracking usage events
@@ -896,10 +904,21 @@ interface components {
             needsUpgrade?: boolean;
             /** @description Access is granted and usage beyond the included cap accrues an overage charge — `onExceed: charge`. */
             overage?: boolean;
+            /**
+             * Authoritative paywall classification shared with Managed MCP. Present on denial responses only.
+             * @enum {string}
+             */
+            paywallReason?: 'activation_required' | 'topup_required' | 'payment_required';
+            /** @description Display name of the active or default plan */
+            planName?: string;
+            /** @description Active plan reference when the customer already holds a purchase */
+            planRef?: string;
             /** @description Active plans on the product available for activation or checkout */
             plans?: components['schemas']['LimitPlanItemDto'][];
             /** @description Product the limit check applies to */
             product?: components['schemas']['LimitProductBriefDto'];
+            /** @description Active purchase reference when the customer already holds a purchase */
+            purchaseRef?: string;
             /**
              * Remaining usage units before hitting the limit. `-1` means unlimited (no finite cap).
              * @example 997
@@ -909,9 +928,7 @@ interface components {
             throttled?: boolean;
             /** @description The customer was auto-upgraded to the target pricing to restore access — `onExceed: auto_upgrade` succeeded. */
             upgraded?: boolean;
-            /**
-             * Consumed usage units this period. Present only when the backend measured a finite cap.
-             */
+            /** @description Consumed usage units this period. Present only when the backend measured a finite cap. */
             used?: number;
             /**
              * Whether the customer is within their usage limits
@@ -3847,7 +3864,7 @@ interface operations {
 /** SDK purchase row. Generated from the OpenAPI `SdkPurchaseResponse` schema. */
 type PurchaseInfo = components['schemas']['SdkPurchaseResponse'];
 /**
- * Extended LimitResponse with SDK-added plan field.
+ * `LimitResponse` plus a deprecated SDK-only `plan` alias.
  *
  * The backend `LimitResponse` now natively carries the `onExceed` outcome flags
  * (`throttled` / `overage` / `needsTopUp` / `needsUpgrade` / `upgraded`, resolved
@@ -3855,9 +3872,13 @@ type PurchaseInfo = components['schemas']['SdkPurchaseResponse'];
  * `overage` ride the allow path (`withinLimits: true`) so a protected handler
  * can read them from `decision.limits` and degrade service or note overage; the
  * others accompany a gate outcome.
+ *
+ * Read `planRef` for the active plan. `plan` is never populated by the
+ * backend — it remains optional so older fixtures and callers still type-check.
  */
 type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
-    plan: string;
+    /** @deprecated Never populated by the backend. Read `planRef` instead. */
+    plan?: string;
 };
 type OneTimePurchaseInfo = components['schemas']['OneTimePurchaseInfo'];
 /**

package/dist/{useUsage-CTgRBvFK.d.cts → useUsage-x6DQG7xe.d.cts}

@@ -820,6 +820,12 @@ interface components {
             /** @description Whether the grant was recorded */
             success: boolean;
         };
+        LimitAutoRechargeDto: {
+            /** @description Whether auto-recharge is enabled for this provider */
+            enabled: boolean;
+            /** @description Stored auto-recharge status when a config exists */
+            status?: string;
+        };
         LimitBalanceDto: {
             /** @description Credit balance in credits (100 credits = 1 minor currency unit) */
             creditBalance: number;
@@ -832,6 +838,8 @@ interface components {
         LimitPlanItemDto: {
             /** @description Derived billing cycle */
             billingCycle?: string;
+            /** @description Deep link that opens hosted checkout with this plan preselected. Present only when a checkout session was minted for this response. */
+            checkoutUrl?: string;
             /**
              * @deprecated
              * @description Deprecated alias of perUnitChargeMinor. Same minor-units value — not credits. Prefer perUnitChargeMinor.
@@ -861,6 +869,8 @@ interface components {
         LimitResponse: {
             /** @description True when the customer must activate a priced default plan before usage is allowed */
             activationRequired?: boolean;
+            /** @description Per-provider auto-recharge snapshot read off the customer document. Omitted when no config exists. */
+            autoRecharge?: components['schemas']['LimitAutoRechargeDto'];
             /** @description Prepaid usage balance context when the default plan is usage-based */
             balance?: components['schemas']['LimitBalanceDto'];
             /**
@@ -881,9 +891,7 @@ interface components {
             creditsPerUnit?: number;
             /** @description ISO 4217 currency code for credit fields */
             currency?: string;
-            /**
-             * The effective finite cap for this meter. Present only when the backend measured a finite cap.
-             */
+            /** @description The effective finite cap for this meter. Present only when the backend measured a finite cap. */
             limit?: number;
             /**
              * The meter name to use when tracking usage events
@@ -896,10 +904,21 @@ interface components {
             needsUpgrade?: boolean;
             /** @description Access is granted and usage beyond the included cap accrues an overage charge — `onExceed: charge`. */
             overage?: boolean;
+            /**
+             * Authoritative paywall classification shared with Managed MCP. Present on denial responses only.
+             * @enum {string}
+             */
+            paywallReason?: 'activation_required' | 'topup_required' | 'payment_required';
+            /** @description Display name of the active or default plan */
+            planName?: string;
+            /** @description Active plan reference when the customer already holds a purchase */
+            planRef?: string;
             /** @description Active plans on the product available for activation or checkout */
             plans?: components['schemas']['LimitPlanItemDto'][];
             /** @description Product the limit check applies to */
             product?: components['schemas']['LimitProductBriefDto'];
+            /** @description Active purchase reference when the customer already holds a purchase */
+            purchaseRef?: string;
             /**
              * Remaining usage units before hitting the limit. `-1` means unlimited (no finite cap).
              * @example 997
@@ -909,9 +928,7 @@ interface components {
             throttled?: boolean;
             /** @description The customer was auto-upgraded to the target pricing to restore access — `onExceed: auto_upgrade` succeeded. */
             upgraded?: boolean;
-            /**
-             * Consumed usage units this period. Present only when the backend measured a finite cap.
-             */
+            /** @description Consumed usage units this period. Present only when the backend measured a finite cap. */
             used?: number;
             /**
              * Whether the customer is within their usage limits
@@ -3847,7 +3864,7 @@ interface operations {
 /** SDK purchase row. Generated from the OpenAPI `SdkPurchaseResponse` schema. */
 type PurchaseInfo = components['schemas']['SdkPurchaseResponse'];
 /**
- * Extended LimitResponse with SDK-added plan field.
+ * `LimitResponse` plus a deprecated SDK-only `plan` alias.
  *
  * The backend `LimitResponse` now natively carries the `onExceed` outcome flags
  * (`throttled` / `overage` / `needsTopUp` / `needsUpgrade` / `upgraded`, resolved
@@ -3855,9 +3872,13 @@ type PurchaseInfo = components['schemas']['SdkPurchaseResponse'];
  * `overage` ride the allow path (`withinLimits: true`) so a protected handler
  * can read them from `decision.limits` and degrade service or note overage; the
  * others accompany a gate outcome.
+ *
+ * Read `planRef` for the active plan. `plan` is never populated by the
+ * backend — it remains optional so older fixtures and callers still type-check.
  */
 type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
-    plan: string;
+    /** @deprecated Never populated by the backend. Read `planRef` instead. */
+    plan?: string;
 };
 type OneTimePurchaseInfo = components['schemas']['OneTimePurchaseInfo'];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/react",
-  "version": "2.2.0",
+  "version": "2.2.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -57,7 +57,7 @@
     "directory": "packages/react"
   },
   "peerDependencies": {
-    "@solvapay/mcp-core": "^0.2.8 || ^0.3.0 || ^0.4.0",
+    "@solvapay/mcp-core": "0.4.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0"
   },
@@ -69,7 +69,7 @@
   "dependencies": {
     "@stripe/react-stripe-js": "^6.0.0",
     "@stripe/stripe-js": "^9.0.0",
-    "@solvapay/core": "1.7.0"
+    "@solvapay/core": "1.7.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a"
   },
   "devDependencies": {
     "@testing-library/dom": "^10.4.1",
@@ -85,9 +85,9 @@
     "react-dom": "^19.2.5",
     "typescript": "^5.9.3",
     "vitest": "^4.1.2",
-    "@solvapay/mcp-core": "0.4.0",
-    "@solvapay/test-utils": "0.0.0",
-    "@solvapay/server": "2.4.0"
+    "@solvapay/mcp-core": "0.4.1-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a",
+    "@solvapay/server": "2.5.0-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a",
+    "@solvapay/test-utils": "0.0.0"
   },
   "scripts": {
     "build": "tsup src/index.tsx src/primitives/index.ts src/adapters/auth.ts src/adapters/auth0.ts src/adapters/session-auth.ts src/mcp/index.ts --format esm,cjs --dts --tsconfig tsconfig.build.json && cp src/styles.css dist/styles.css && mkdir -p dist/mcp && cp src/mcp/styles.css dist/mcp/styles.css",