@solvapay/server 2.4.1 → 2.5.0-preview-4e9e88853847575b5dbe7c2d36163333a2364b7a

package/dist/edge.d.ts

@@ -817,6 +817,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;
@@ -829,6 +835,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.
@@ -858,6 +866,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'];
             /**
@@ -878,9 +888,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
@@ -893,10 +901,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
@@ -906,9 +925,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
@@ -3899,7 +3916,7 @@ type AttachBusinessDetailsParams = {
 type AttachBusinessDetailsResult = components['schemas']['AttachBusinessDetailsResponse'];
 type CheckLimitsRequest = components['schemas']['CheckLimitRequest'];
 /**
- * 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
@@ -3907,9 +3924,13 @@ type CheckLimitsRequest = components['schemas']['CheckLimitRequest'];
  * `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;
 };
 /**
  * Extended CustomerResponse with proper field mapping
@@ -4182,6 +4203,16 @@ interface SolvaPayClient {
 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];
 /**
  * Arguments passed to protected handlers
  */
@@ -4218,8 +4249,10 @@ interface PaywallMetadata {
  * 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. */
@@ -4239,6 +4272,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';
@@ -5181,6 +5245,7 @@ interface SolvaPay {
         customerRef: string;
         planRef?: string;
         returnUrl?: string;
+        purpose?: 'credit_topup';
     }): Promise<{
         sessionId: string;
         checkoutUrl: string;
@@ -5431,6 +5496,7 @@ declare function paywallErrorToClientPayload(error: PaywallError): Record<string
 
 declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     planRef: z.ZodOptional<z.ZodString>;
+    planName: z.ZodOptional<z.ZodString>;
     plans: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     meterName: z.ZodOptional<z.ZodString>;
     unitPriceMinor: z.ZodOptional<z.ZodNumber>;
@@ -5443,12 +5509,41 @@ declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     creditBalance: z.ZodOptional<z.ZodNumber>;
     balance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     productDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        topup_required: "topup_required";
+        payment_required: "payment_required";
+        activation_required: "activation_required";
+        upgrade_required: "upgrade_required";
+        limit_reached: "limit_reached";
+        reactivation_required: "reactivation_required";
+    }>>;
+    nextAction: z.ZodOptional<z.ZodEnum<{
+        topup: "topup";
+        checkout: "checkout";
+        activate: "activate";
+        account: "account";
+    }>>;
+    creditsPerCall: z.ZodOptional<z.ZodNumber>;
+    shortfallCredits: z.ZodOptional<z.ZodNumber>;
+    remainingCalls: z.ZodOptional<z.ZodNumber>;
+    purchaseRef: z.ZodOptional<z.ZodString>;
+    planStatus: z.ZodOptional<z.ZodString>;
+    autoRecharge: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    links: z.ZodOptional<z.ZodObject<{
+        topup: z.ZodOptional<z.ZodString>;
+        checkout: z.ZodOptional<z.ZodString>;
+        manage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     kind: z.ZodLiteral<"payment_required">;
     product: z.ZodString;
     checkoutUrl: z.ZodString;
     message: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     planRef: z.ZodOptional<z.ZodString>;
+    planName: z.ZodOptional<z.ZodString>;
     plans: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     meterName: z.ZodOptional<z.ZodString>;
     unitPriceMinor: z.ZodOptional<z.ZodNumber>;
@@ -5461,6 +5556,34 @@ declare const PaywallStructuredContentSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     creditBalance: z.ZodOptional<z.ZodNumber>;
     balance: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     productDetails: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    reason: z.ZodOptional<z.ZodEnum<{
+        topup_required: "topup_required";
+        payment_required: "payment_required";
+        activation_required: "activation_required";
+        upgrade_required: "upgrade_required";
+        limit_reached: "limit_reached";
+        reactivation_required: "reactivation_required";
+    }>>;
+    nextAction: z.ZodOptional<z.ZodEnum<{
+        topup: "topup";
+        checkout: "checkout";
+        activate: "activate";
+        account: "account";
+    }>>;
+    creditsPerCall: z.ZodOptional<z.ZodNumber>;
+    shortfallCredits: z.ZodOptional<z.ZodNumber>;
+    remainingCalls: z.ZodOptional<z.ZodNumber>;
+    purchaseRef: z.ZodOptional<z.ZodString>;
+    planStatus: z.ZodOptional<z.ZodString>;
+    autoRecharge: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodBoolean;
+        status: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    links: z.ZodOptional<z.ZodObject<{
+        topup: z.ZodOptional<z.ZodString>;
+        checkout: z.ZodOptional<z.ZodString>;
+        manage: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     kind: z.ZodLiteral<"activation_required">;
     product: z.ZodString;
     checkoutUrl: z.ZodString;
@@ -5498,38 +5621,41 @@ type PaywallState = {
 } | {
     kind: 'reactivation_required';
 };
+type CreditSignals = {
+    creditBalance?: number;
+    creditsPerCall?: number;
+    shortfallCredits?: number;
+    remainingCalls?: number;
+    isCreditBased: boolean;
+};
+/**
+ * Coalesce the two credit-balance channels and derive shortfall /
+ * remaining-call counts. Nested `balance` wins when present.
+ */
+declare function creditSignals(limits: LimitResponseWithPlan | null): CreditSignals;
+declare function nextActionFor(state: PaywallState): PaywallNextAction;
 /**
  * Classify a `LimitResponseWithPlan` (or `null` on degraded paths) into
  * a `PaywallState`. Pure — safe to call multiple times per request.
  *
  * Precedence:
- *  1. `activationRequired === true` — trumps everything else; the
- *     backend explicitly flagged that no plan is live yet.
- *  2. Authoritative `needsTopUp` / `needsUpgrade` flags from
- *     `decideLimit`, when the backend sent them. Prefer these over
- *     the credit-balance heuristic so a top-up deny and an
- *     auto-upgrade deny are not re-derived from plan type.
- *  3. Usage-based plan out of credits — the customer has a plan but
- *     ran out, so a topup is the right action. "Out of credits" is
- *     determined from (in order): the nested
- *     `balance.creditBalance === 0` block, the top-level
- *     `creditBalance === 0` field, or `remaining === 0` as a
- *     fallback for older backend responses that omit both credit
- *     fields on usage-based plans.
- *  4. Active plan at included cap (`plan` is a non-empty ref and
- *     `remaining <= 0`) → `limit_reached`. This is the "on Free, used
- *     3 of 3" case — not "no plan".
- *  5. Everything else → `upgrade_required`, including:
- *     - `limits === null` (defensive),
- *     - no active plan on the product.
+ *  1. `activationRequired` / `paywallReason === 'activation_required'`.
+ *  2. `paywallReason === 'topup_required'` — backend stays authoritative
+ *     for credit-based denials (same rule as Managed MCP).
+ *  3. Authoritative `needsTopUp` / `needsUpgrade` flags from `decideLimit`.
+ *  4. Credit-field presence + a real shortfall (`balance < cost`).
+ *  5. Active purchase / plan at included cap → `limit_reached`.
+ *  6. Floor: never `upgrade_required` when credit fields or a purchase
+ *     are present. Everything else → `upgrade_required`.
  *
  * `reactivation_required` is deferred — it needs a distinct backend
- * signal (future `LimitResponse.inactivePurchaseRef`) which isn't
- * emitted yet. Kept in the type so downstream code compiles against
- * the full discriminated union; `classifyPaywallState` will never
- * return it under current backend behaviour.
+ * signal which isn't emitted yet. Kept in the type so downstream code
+ * compiles against the full discriminated union.
  */
 declare function classifyPaywallState(limits: LimitResponseWithPlan | null): PaywallState;
+/** Escape markdown link-label delimiters — plan names are provider-authored. */
+declare function linkLabel(name: string): string;
+declare function planLadder(gate: PaywallStructuredContent): string | null;
 /**
  * Produce the terminal-friendly gate message. Names the `account`
  * viewer (with a `view` hint when the landing screen matters) or
@@ -5574,13 +5700,10 @@ declare function buildNudgeMessage(state: PaywallState, limits: LimitResponseWit
  */
 
 /**
- * Subset of `LimitResponseWithPlan` the helper actually reads. Keeps the
- * signature flexible — callers can pass the raw `apiClient.checkLimits`
- * result without first asserting the `plan` field.
+ * `LimitResponseWithPlan` as returned by `apiClient.checkLimits`.
+ * `plan` is optional and deprecated — the backend never sends it.
  */
-type LimitsLike = Omit<LimitResponseWithPlan, 'plan'> & {
-    plan?: LimitResponseWithPlan['plan'];
-};
+type LimitsLike = LimitResponseWithPlan;
 declare function buildPaywallGate(productRef: string, limits: LimitsLike): PaywallStructuredContent;
 
 /**
@@ -6022,6 +6145,7 @@ declare function createCheckoutSessionCore(request: Request, body: {
     productRef: string;
     planRef?: string;
     returnUrl?: string;
+    purpose?: 'credit_topup';
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -6309,4 +6433,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): Promise<WebhookEvent>;
 
-export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, 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 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, PaywallStructuredContentSchema, type ProcessPaymentResult, type ProductConfigurationStatus, type PurchaseCheckResult, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, type TopupProcessResult, type VerifyProductConfigurationOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, attachBusinessDetailsCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, deriveUsageSnapshot, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getHistoryCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditSignals, 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 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, PaywallStructuredContentSchema, type ProcessPaymentResult, type ProductConfigurationStatus, type PurchaseCheckResult, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, type TopupProcessResult, type VerifyProductConfigurationOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, attachBusinessDetailsCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, creditSignals, deriveUsageSnapshot, disableAutoRechargeCore, getAuthenticatedUserCore, getAutoRechargeCore, getCustomerBalanceCore, getHistoryCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, linkLabel, listPlansCore, nextActionFor, paywallErrorToClientPayload, planLadder, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, saveAutoRechargeCore, syncCustomerCore, trackUsageCore, verifyProductConfiguration, verifyWebhook, withRetry };