@comfyorg/account-core 1.0.0-alpha.0 → 1.0.0-alpha.1

package/dist/core/billing/operationPolicy.js

@@ -9,7 +9,9 @@ export const OPERATION_POLL_TIMING = {
     maxMs: 8_000,
     multiplier: 1.5,
     /** An operation parked on the customer is checked on a slow, flat cadence. */
-    parkedMs: 30_000
+    parkedMs: 30_000,
+    /** Fast backoff for an actionless blocked wait: 20 turns of the 3 s PI status cache. */
+    actionDiscoveryMs: 60_000
 };
 export const OPERATION_POLL_BUDGET = {
     defaultMs: 120_000,
@@ -18,6 +20,40 @@ export const OPERATION_POLL_BUDGET = {
     /** Once the customer is involved, a bank challenge can idle for hours. */
     customerActionMs: 23 * 60 * 60_000
 };
+/**
+ * The one "customer can act here" rule both billing rails park on: a
+ * retryable failure to retry, a hosted page to visit, or an embedded
+ * challenge the server still says is required. A non-retryable decline never
+ * reaches it; the operation is terminal by then.
+ */
+export function customerCanActHere(hold) {
+    if (hold.authenticationState === 'failed_retryable')
+        return true;
+    if (hold.offersHostedPage)
+        return true;
+    return (hold.authenticationState === 'requires_action' &&
+        (hold.challenge === 'required' || hold.challenge === 'in_progress'));
+}
+/**
+ * The SDK renders one presentation: a hosted operation offers only its page,
+ * an embedded one only its challenge. The cloud app's
+ * `legacyOperationActionHold` names the rows where the two surfaces differ.
+ */
+export function pendingOperationActionHold(state) {
+    return state.presentation === 'hosted'
+        ? {
+            authenticationState: state.authenticationState,
+            offersHostedPage: state.actionUrl !== undefined
+        }
+        : {
+            authenticationState: state.authenticationState,
+            offersHostedPage: false,
+            challenge: state.challenge?.status
+        };
+}
+function customerCanAct(state) {
+    return customerCanActHere(pendingOperationActionHold(state));
+}
 /**
  * Waiting on the customer, not on the backend: a challenge to complete
  * elsewhere, a hosted page to finish, a phase the server reports as blocked on
@@ -25,16 +61,41 @@ export const OPERATION_POLL_BUDGET = {
  * challenge completes the state reads processing and nothing waits on the
  * customer anymore.
  */
-export function isParkedOnCustomer(state) {
+function isWaitingOnCustomer(state) {
     return (state.authenticationState === 'requires_action' ||
         state.actionUrl !== undefined ||
         isBlockedOnCustomerPhase(state.serverPhase) ||
         (state.authenticationState === 'failed_retryable' &&
             state.customerActionSeen));
 }
-export function nextPollDelayMs(state, previousDelayMs) {
+/**
+ * Parked only while the customer can act here. The server can report a
+ * blocked phase and a client secret before its cached `authentication_state`
+ * catches up, and the slow cadence would then hold a screen with no action.
+ */
+export function isParkedOnCustomer(state) {
+    return customerCanAct(state) && isWaitingOnCustomer(state);
+}
+/**
+ * Blocked on the customer with nothing to offer them yet: either the action
+ * is still on its way, or it belongs to someone else (a member without
+ * billing permission, a tab without embedded checkout).
+ */
+export function isWaitingOnCustomerWithoutAction(state) {
+    return !customerCanAct(state) && isWaitingOnCustomer(state);
+}
+/**
+ * `waitedWithoutActionMs` is how long the operation has continuously been
+ * {@link isWaitingOnCustomerWithoutAction}; past the discovery window it
+ * parks too, so an action that never arrives here costs the slow cadence.
+ */
+export function nextPollDelayMs(state, previousDelayMs, waitedWithoutActionMs = 0) {
     if (isParkedOnCustomer(state))
         return OPERATION_POLL_TIMING.parkedMs;
+    if (isWaitingOnCustomerWithoutAction(state) &&
+        waitedWithoutActionMs >= OPERATION_POLL_TIMING.actionDiscoveryMs) {
+        return OPERATION_POLL_TIMING.parkedMs;
+    }
     return Math.min((previousDelayMs ?? OPERATION_POLL_TIMING.initialMs) *
         OPERATION_POLL_TIMING.multiplier, OPERATION_POLL_TIMING.maxMs);
 }

package/dist/core/billing/operationState.d.ts

@@ -1,20 +1,71 @@
-/**
- * One billing operation as the SDK sees it: a discriminated union over the
- * lifecycle a `billing_op_id` moves through, and the pure transition that
- * advances it. The identity is fixed at adoption and survives every
- * presentation change, so switching a checkout from the embedded challenge
- * to the hosted page (or back) is a transition on the same operation, never
- * a replacement one.
- *
- * The transition consumes the generated `BillingOpStatusResponse`. It reads
- * the coded `decline_reason` and `recovery_action` and never `error_message`,
- * so no server or payment-provider text can reach a consumer through this
- * state.
- */
-import type { zBillingOpStatusResponse } from '@comfyorg/ingest-types/zod';
 import type { z } from 'zod';
 import type { BillingScope } from './billingScope.js';
-export type BillingOpStatus = z.infer<typeof zBillingOpStatusResponse>;
+export declare const BillingOpStatusSchema: z.ZodObject<{
+    action_url: z.ZodOptional<z.ZodString>;
+    authentication_state: z.ZodOptional<z.ZodEnum<["requires_action", "processing", "failed_retryable", "succeeded", "reconciliation_needed"]>>;
+    completed_at: z.ZodOptional<z.ZodString>;
+    decline_reason: z.ZodOptional<z.ZodEnum<["card_declined", "insufficient_funds", "expired_card", "incorrect_cvc", "authentication_required", "authentication_failed", "processing_error", "payment_not_completed", "generic"]>>;
+    error_message: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    payment_intent_client_secret: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodEnum<["awaiting_payment_method", "awaiting_invoice_payment", "in_progress"]>>;
+    plan: z.ZodOptional<z.ZodObject<{
+        duration: z.ZodEnum<["MONTHLY", "ANNUAL"]>;
+        slug: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        duration: "MONTHLY" | "ANNUAL";
+        slug: string;
+    }, {
+        duration: "MONTHLY" | "ANNUAL";
+        slug: string;
+    }>>;
+    recovery_action: z.ZodOptional<z.ZodEnum<["retry", "replace_payment_method", "authenticate_payment", "contact_support"]>>;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+    started_at: z.ZodString;
+    status: z.ZodEnum<["pending", "succeeded", "failed", "reconciliation_needed"]>;
+} & {
+    amount_charged_cents: z.ZodOptional<z.ZodNumber>;
+    credits_added: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: "failed" | "pending" | "succeeded" | "reconciliation_needed";
+    id: string;
+    started_at: string;
+    completed_at?: string | undefined;
+    error_message?: string | undefined;
+    plan?: {
+        duration: "MONTHLY" | "ANNUAL";
+        slug: string;
+    } | undefined;
+    action_url?: string | undefined;
+    payment_intent_client_secret?: string | undefined;
+    amount_charged_cents?: number | undefined;
+    authentication_state?: "requires_action" | "processing" | "failed_retryable" | "succeeded" | "reconciliation_needed" | undefined;
+    credits_added?: number | undefined;
+    decline_reason?: "card_declined" | "insufficient_funds" | "expired_card" | "incorrect_cvc" | "authentication_required" | "authentication_failed" | "processing_error" | "payment_not_completed" | "generic" | undefined;
+    phase?: "in_progress" | "awaiting_payment_method" | "awaiting_invoice_payment" | undefined;
+    recovery_action?: "retry" | "replace_payment_method" | "authenticate_payment" | "contact_support" | undefined;
+    retryable?: boolean | undefined;
+}, {
+    status: "failed" | "pending" | "succeeded" | "reconciliation_needed";
+    id: string;
+    started_at: string;
+    completed_at?: string | undefined;
+    error_message?: string | undefined;
+    plan?: {
+        duration: "MONTHLY" | "ANNUAL";
+        slug: string;
+    } | undefined;
+    action_url?: string | undefined;
+    payment_intent_client_secret?: string | undefined;
+    amount_charged_cents?: number | undefined;
+    authentication_state?: "requires_action" | "processing" | "failed_retryable" | "succeeded" | "reconciliation_needed" | undefined;
+    credits_added?: number | undefined;
+    decline_reason?: "card_declined" | "insufficient_funds" | "expired_card" | "incorrect_cvc" | "authentication_required" | "authentication_failed" | "processing_error" | "payment_not_completed" | "generic" | undefined;
+    phase?: "in_progress" | "awaiting_payment_method" | "awaiting_invoice_payment" | undefined;
+    recovery_action?: "retry" | "replace_payment_method" | "authenticate_payment" | "contact_support" | undefined;
+    retryable?: boolean | undefined;
+}>;
+export type BillingOpStatus = z.infer<typeof BillingOpStatusSchema>;
 export type BillingOperationKind = 'subscription' | 'topup' | 'cancel';
 /**
  * Where the customer completes the operation: the challenge this tab drives
@@ -52,6 +103,13 @@ export type BillingOperationIdentity = BillingPresentationState & {
     readonly observedAt: number;
     /** When the attempt began, before the command was issued; telemetry durations count from here. */
     readonly attemptStartedAt: number;
+    /**
+     * This tab issued the operation and was still waiting on its outcome when
+     * it adopted it: from its own command, or after a reload or a return from
+     * a provider page. Absent for an operation another tab issued, and for one
+     * this tab already saw succeed.
+     */
+    readonly awaitedHere?: true;
 };
 /**
  * The in-page challenge for an embedded presentation. `completed` and
@@ -82,9 +140,22 @@ export type FailedBillingOperation = BillingOperationIdentity & {
     readonly recoveryAction?: BillingRecoveryAction;
     readonly retryable: boolean;
 };
-export type BillingOperationState = PendingBillingOperation | (BillingOperationIdentity & {
+/**
+ * What the server reports a succeeded operation did, for display only. Each
+ * fact is absent while the server cannot say it: a charge billed outside a
+ * Stripe invoice, a grant not recorded yet, or an operation that is not a
+ * plan change.
+ */
+export interface BillingOperationReceipt {
+    readonly amountChargedCents?: number;
+    readonly creditsAdded?: number;
+    readonly plan?: NonNullable<BillingOpStatus['plan']>;
+}
+export type SucceededBillingOperation = BillingOperationIdentity & {
     readonly phase: 'succeeded';
-}) | FailedBillingOperation
+    readonly receipt?: BillingOperationReceipt;
+};
+export type BillingOperationState = PendingBillingOperation | SucceededBillingOperation | FailedBillingOperation
 /** This tab's poll budget ran out; the server may still settle the operation. */
  | (BillingOperationIdentity & {
     readonly phase: 'timed_out';
@@ -93,7 +164,10 @@ export type BillingOperationState = PendingBillingOperation | (BillingOperationI
  | (BillingOperationIdentity & {
     readonly phase: 'reconciliation_needed';
 })
-/** The session or workspace changed underneath it; nothing here may be attributed to the new scope. */
+/**
+ * The session or workspace changed underneath it, or the server replaced it
+ * with a newer operation; nothing here may be attributed to this tab now.
+ */
  | (BillingOperationIdentity & {
     readonly phase: 'superseded';
 });
@@ -118,6 +192,11 @@ export type BillingOperationEvent = {
     readonly presentation: 'embedded';
 } | {
     readonly type: 'challenge_started';
+}
+/** The server answered a resubmit with a fresh hosted step for this same operation. */
+ | {
+    readonly type: 'action_reissued';
+    readonly actionUrl: string;
 } | {
     readonly type: 'challenge_settled';
     readonly outcome: 'completed' | 'failed';
@@ -125,4 +204,9 @@ export type BillingOperationEvent = {
 export declare function isTerminal(state: BillingOperationState): state is Exclude<BillingOperationState, PendingBillingOperation>;
 /** A continuation link the SDK will hand to a host: absolute and https, nothing else. */
 export declare function validateActionUrl(value: string | undefined): string | undefined;
+/**
+ * The charge went through and the server has not recorded its credits yet;
+ * reading the operation again fills them in.
+ */
+export declare function isGrantLanding(state: BillingOperationState): boolean;
 export declare function reduceBillingOperation(state: BillingOperationState, event: BillingOperationEvent): BillingOperationState;

package/dist/core/billing/operationState.js

@@ -1,3 +1,22 @@
+/**
+ * One billing operation as the SDK sees it: a discriminated union over the
+ * lifecycle a `billing_op_id` moves through, and the pure transition that
+ * advances it. The identity is fixed at adoption and survives every
+ * presentation change, so switching a checkout from the embedded challenge
+ * to the hosted page (or back) is a transition on the same operation, never
+ * a replacement one.
+ *
+ * The transition consumes the generated `BillingOpStatusResponse`. It reads
+ * the coded `decline_reason` and `recovery_action` and never `error_message`,
+ * so no server or payment-provider text can reach a consumer through this
+ * state.
+ */
+import { zBillingOpStatusResponse } from '@comfyorg/ingest-types/zod';
+import { wireCents } from './wireCents.js';
+export const BillingOpStatusSchema = zBillingOpStatusResponse.extend({
+    amount_charged_cents: wireCents.optional(),
+    credits_added: wireCents.optional()
+});
 /**
  * The phases the contract defines as blocked on the customer. Neither advances
  * on its own, so an operation reporting one waits on them even before it has a
@@ -32,6 +51,7 @@ function identityOf(state) {
         scope: state.scope,
         observedAt: state.observedAt,
         attemptStartedAt: state.attemptStartedAt,
+        ...(state.awaitedHere ? { awaitedHere: true } : {}),
         ...presentationOf(state)
     };
 }
@@ -69,7 +89,7 @@ function nextChallenge(state, status) {
 }
 function terminalFromStatus(state, status) {
     if (status.status === 'succeeded')
-        return withPhase(state, 'succeeded');
+        return succeeded(state, status);
     if (status.status === 'failed') {
         return {
             ...identityOf(state),
@@ -87,16 +107,62 @@ function terminalFromStatus(state, status) {
     }
     return undefined;
 }
+function receiptOf(status) {
+    const receipt = {
+        ...(status.amount_charged_cents === undefined
+            ? {}
+            : { amountChargedCents: status.amount_charged_cents }),
+        ...(status.credits_added === undefined
+            ? {}
+            : { creditsAdded: status.credits_added }),
+        ...(status.plan === undefined ? {} : { plan: status.plan })
+    };
+    return Object.keys(receipt).length === 0 ? undefined : receipt;
+}
+function succeeded(state, status) {
+    const receipt = receiptOf(status);
+    return {
+        ...withPhase(state, 'succeeded'),
+        ...(receipt === undefined ? {} : { receipt })
+    };
+}
+/**
+ * The charge went through and the server has not recorded its credits yet;
+ * reading the operation again fills them in.
+ */
+export function isGrantLanding(state) {
+    return (state.phase === 'succeeded' &&
+        state.receipt?.amountChargedCents !== undefined &&
+        state.receipt.creditsAdded === undefined);
+}
 /**
  * A link echoed while this tab's completed challenge is still processing
  * points at that same challenge; surfacing it would ask the customer to
- * redo a step they just finished.
+ * redo a step they just finished. A checkout waiting on a card keeps the
+ * link a resubmit reissued, because the server stores none for that phase.
  */
 function nextActionUrl(state, status, authenticationState) {
-    return state.challenge?.status === 'completed' &&
-        authenticationState !== 'requires_action'
+    if (state.challenge?.status === 'completed' &&
+        authenticationState !== 'requires_action') {
+        return state.actionUrl;
+    }
+    const served = validateActionUrl(status.action_url);
+    return served === undefined && status.phase === 'awaiting_payment_method'
         ? state.actionUrl
-        : validateActionUrl(status.action_url);
+        : served;
+}
+/**
+ * A retryable failure served without a reason reads as `generic`, as a
+ * terminal failure does, so the customer is offered the retry the state
+ * promises. A challenge this tab saw fail supplies its own reason.
+ */
+function nextDeclineReason(state, status, authenticationState) {
+    if (authenticationState !== 'failed_retryable')
+        return undefined;
+    const known = status.decline_reason ?? state.declineReason;
+    if (known !== undefined || state.challenge?.status === 'failed')
+        return known;
+    return 'generic';
 }
 function reducePending(state, status) {
     if (status.id !== state.id)
@@ -108,9 +174,7 @@ function reducePending(state, status) {
         ? state.authenticationState
         : status.authentication_state;
     const actionUrl = nextActionUrl(state, status, authenticationState);
-    const declineReason = authenticationState === 'failed_retryable'
-        ? (status.decline_reason ?? state.declineReason)
-        : undefined;
+    const declineReason = nextDeclineReason(state, status, authenticationState);
     return {
         ...state,
         challenge: nextChallenge(state, status),
@@ -183,5 +247,11 @@ export function reduceBillingOperation(state, event) {
                 : state;
         case 'challenge_settled':
             return settleChallenge(state, event.outcome);
+        case 'action_reissued': {
+            const actionUrl = validateActionUrl(event.actionUrl);
+            return actionUrl === undefined
+                ? state
+                : { ...state, actionUrl, customerActionSeen: true };
+        }
     }
 }

package/dist/core/billing/paymentCopy.d.ts

@@ -3,13 +3,18 @@
  * a host may override — except the safety line, which only the projection's
  * `noChargeConfirmed` may ever unlock.
  */
+import type { BillingDeclineReason, BillingRecoveryAction } from './operationState.js';
 import type { PaymentProjection, PaymentReasonKey, PaymentStep } from './paymentProjection.js';
-export type PaymentCopyKey = `billing.step.${PaymentStep}.header` | `billing.step.${PaymentStep}.body` | `billing.reason.${PaymentReasonKey}` | 'billing.action.retry' | 'billing.action.continue_verification' | 'billing.safety.nothing_was_charged';
+export type PaymentCopyKey = `billing.step.${PaymentStep}.header` | `billing.step.${PaymentStep}.body` | `billing.reason.${PaymentReasonKey}` | `billing.recovery.${BillingRecoveryAction}` | 'billing.action.retry' | 'billing.action.replace_payment_method' | 'billing.action.contact_support' | 'billing.action.continue_verification' | 'billing.safety.nothing_was_charged';
 declare const SAFETY_KEY = "billing.safety.nothing_was_charged";
 export declare const DEFAULT_PAYMENT_COPY: Readonly<Record<PaymentCopyKey, string>>;
+/** The host's toast detail for a payment the server declined. */
+export type DeclineDetailKey = 'insufficientFundsDetail' | 'expiredCardDetail' | 'incorrectCvcDetail' | 'authenticationFailedDetail' | 'processingErrorDetail' | 'paymentDeclinedDetail';
+export declare function declineDetailKey(reason: BillingDeclineReason): DeclineDetailKey;
 export declare function createPaymentCopy(overrides?: Partial<Record<PaymentCopyKey, string>>): Readonly<Record<PaymentCopyKey, string>>;
 export interface PaymentCopyKeys {
     readonly header: PaymentCopyKey;
+    /** The server's recovery line when it names one, else the step's own body. */
     readonly body: PaymentCopyKey;
     readonly reason?: PaymentCopyKey;
     readonly safety?: typeof SAFETY_KEY;

package/dist/core/billing/paymentCopy.js

@@ -24,19 +24,52 @@ export const DEFAULT_PAYMENT_COPY = {
     'billing.reason.incorrect_cvc': 'The security code did not match.',
     'billing.reason.authentication_required': 'Your bank requires authentication.',
     'billing.reason.authentication_failed': 'Authentication with your bank did not complete.',
+    'billing.reason.payment_not_completed': 'The payment was not completed.',
     'billing.reason.processing_error': 'The payment could not be processed right now.',
+    'billing.recovery.retry': 'Please try again.',
+    'billing.recovery.replace_payment_method': 'Try again with a different payment method.',
+    'billing.recovery.authenticate_payment': 'Try again and complete the verification your bank asks for.',
+    'billing.recovery.contact_support': 'This payment cannot be retried. Contact support@comfy.org and we will help you finish it.',
     'billing.action.retry': 'Try again',
+    'billing.action.replace_payment_method': 'Use a different payment method',
+    'billing.action.contact_support': 'Contact support',
     'billing.action.continue_verification': 'Continue verification',
     [SAFETY_KEY]: 'Nothing was charged.'
 };
+export function declineDetailKey(reason) {
+    switch (reason) {
+        case 'insufficient_funds':
+            return 'insufficientFundsDetail';
+        case 'expired_card':
+            return 'expiredCardDetail';
+        case 'incorrect_cvc':
+            return 'incorrectCvcDetail';
+        case 'authentication_required':
+        case 'authentication_failed':
+        case 'payment_not_completed':
+            return 'authenticationFailedDetail';
+        case 'processing_error':
+            return 'processingErrorDetail';
+        case 'card_declined':
+        case 'generic':
+            return 'paymentDeclinedDetail';
+    }
+}
 export function createPaymentCopy(overrides = {}) {
     const { [SAFETY_KEY]: _protected, ...safe } = overrides;
     return { ...DEFAULT_PAYMENT_COPY, ...safe };
 }
+function recoveryCopyKey(action) {
+    if (action === undefined)
+        return undefined;
+    const key = `billing.recovery.${action}`;
+    return key in DEFAULT_PAYMENT_COPY ? key : undefined;
+}
 export function paymentCopyKeys(projection) {
     return {
         header: `billing.step.${projection.step}.header`,
-        body: `billing.step.${projection.step}.body`,
+        body: recoveryCopyKey(projection.recoveryAction) ??
+            `billing.step.${projection.step}.body`,
         ...(projection.reasonKey === undefined
             ? {}
             : { reason: `billing.reason.${projection.reasonKey}` }),

package/dist/core/billing/paymentProjection.d.ts

@@ -4,9 +4,10 @@
  * operation exists; it never advances the machine itself.
  *
  * A server verdict outranks anything the host reports: a customer who backed
- * out of a page after the charge went through still sees the success.
+ * out of a page after the charge went through still sees the success. A
+ * challenge this tab completed is not offered again while the server settles.
  */
-import type { BillingDeclineReason, BillingOperationState, BillingRecoveryAction } from './operationState.js';
+import type { BillingDeclineReason, BillingOperationState, BillingRecoveryAction, PendingBillingOperation } from './operationState.js';
 export type PaymentStep = 'select' | 'preview' | 'verifying' | 'canceled' | 'declined' | 'processing_error'
 /** Reserved: the contract cannot yet tell "paid, entitlement pending" from "needs a human". */
  | 'payment_received_hold' | 'success';
@@ -22,6 +23,11 @@ export type PaymentReasonKey = BillingDeclineReason | 'checkout_expired' | 'gene
 export interface PaymentProjection {
     readonly step: PaymentStep;
     readonly reasonKey?: PaymentReasonKey;
+    /**
+     * What the server tells the customer to do next. A failed operation the
+     * server marks non-retryable without naming a recovery reads as
+     * `contact_support`, so no dead end ever offers a retry.
+     */
     readonly recoveryAction?: BillingRecoveryAction;
     /** Present whenever an operation backs the projection; the id support can act on. */
     readonly operationId?: string;
@@ -31,4 +37,10 @@ export interface PaymentProjection {
      */
     readonly noChargeConfirmed: boolean;
 }
+/**
+ * Whether a pending payment's progress reads as a prompt rather than a
+ * spinner: only a hosted page the customer still has to visit asks them for
+ * anything. An in-page challenge is driven by the host itself.
+ */
+export declare function awaitsHostedAction(state: PendingBillingOperation): boolean;
 export declare function projectPaymentStep(operation: BillingOperationState | undefined, hostStep: HostPaymentStep): PaymentProjection;

package/dist/core/billing/paymentProjection.js

@@ -3,9 +3,35 @@ const PROCESSING_REASONS = new Set([
     'processing_error',
     'generic'
 ]);
+const RECOVERY_ACTIONS = {
+    retry: true,
+    replace_payment_method: true,
+    authenticate_payment: true,
+    contact_support: true
+};
+/** A recovery action this build cannot act on reads as none named. */
+function knownRecoveryAction(action) {
+    return action !== undefined && isRecoveryAction(action) ? action : undefined;
+}
+function isRecoveryAction(action) {
+    return Object.hasOwn(RECOVERY_ACTIONS, action);
+}
 function stepForReason(reason) {
     return PROCESSING_REASONS.has(reason) ? 'processing_error' : 'declined';
 }
+/** A completed challenge waits on the server, not on the customer. */
+function awaitsVerification(state) {
+    const challengeOpen = state.challenge !== undefined && state.challenge.status !== 'completed';
+    return challengeOpen || state.actionUrl !== undefined;
+}
+/**
+ * Whether a pending payment's progress reads as a prompt rather than a
+ * spinner: only a hosted page the customer still has to visit asks them for
+ * anything. An in-page challenge is driven by the host itself.
+ */
+export function awaitsHostedAction(state) {
+    return state.actionUrl !== undefined;
+}
 function projectPending(state, hostStep) {
     const base = { operationId: state.id, noChargeConfirmed: false };
     if (hostStep === 'canceled')
@@ -13,17 +39,18 @@ function projectPending(state, hostStep) {
     const reason = state.declineReason ??
         (state.challenge?.status === 'failed' ? 'authentication_failed' : undefined);
     if (reason !== undefined) {
+        const recoveryAction = knownRecoveryAction(state.recoveryAction);
         return {
             ...base,
             step: stepForReason(reason),
             reasonKey: reason,
-            ...(state.recoveryAction === undefined
-                ? {}
-                : { recoveryAction: state.recoveryAction })
+            ...(recoveryAction === undefined ? {} : { recoveryAction })
         };
     }
-    const parked = state.challenge !== undefined || state.actionUrl !== undefined;
-    return { ...base, step: parked ? 'verifying' : 'preview' };
+    return {
+        ...base,
+        step: awaitsVerification(state) ? 'verifying' : 'preview'
+    };
 }
 export function projectPaymentStep(operation, hostStep) {
     if (operation === undefined) {
@@ -35,15 +62,16 @@ export function projectPaymentStep(operation, hostStep) {
             return projectPending(operation, hostStep);
         case 'succeeded':
             return { ...base, step: 'success' };
-        case 'failed':
+        case 'failed': {
+            const recoveryAction = knownRecoveryAction(operation.recoveryAction) ??
+                (operation.retryable ? undefined : 'contact_support');
             return {
                 ...base,
                 step: stepForReason(operation.declineReason),
                 reasonKey: operation.declineReason,
-                ...(operation.recoveryAction === undefined
-                    ? {}
-                    : { recoveryAction: operation.recoveryAction })
+                ...(recoveryAction === undefined ? {} : { recoveryAction })
             };
+        }
         case 'reconciliation_needed':
             return { ...base, step: 'processing_error', reasonKey: 'generic' };
         case 'timed_out':

package/dist/core/billing/scopedReader.d.ts

@@ -5,10 +5,10 @@
  * between reads, so only those live in the readers.
  *
  * What the skeleton owns is what a reader therefore cannot get wrong on its
- * own: one shared request per scope, a caller's signal releasing only that
- * caller, the publish fence that reports a late answer as `SUPERSEDED`, and
- * the denial that drops a published snapshot unless it predates a change the
- * host reported.
+ * own: one shared request per scope and route, a caller's signal releasing
+ * only that caller, the publish fence that reports a late answer as
+ * `SUPERSEDED`, and the denial that drops a published snapshot unless it
+ * predates a change the host reported.
  */
 import type { BillingResult, BillingTransport } from './billingContracts.js';
 import type { BillingScope, BillingScopeSource } from './billingScope.js';
@@ -21,7 +21,13 @@ export interface ScopedReaderDefinition<TData, TSnapshot, TOptions extends Scope
     readonly transport: BillingTransport;
     /** Where the core learns which user, workspace, and role it runs as. */
     readonly scopeSource: BillingScopeSource;
-    readonly route: string;
+    /**
+     * The route to request, as a function for a read whose query varies per
+     * call. The resolved route joins the scope in identifying an in-flight
+     * read, so two callers asking for different pages each get their own answer
+     * rather than the first one's.
+     */
+    readonly route: string | ((options: TOptions | undefined) => string);
     readonly parse: (body: unknown) => ParsedBillingBody<TData>;
     /**
      * The reader's own reading of a validated response. Returning a failure is