LCOV - code coverage report
Current view: top level - packages/account-core/src/core/billing - operationPolicy.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 6.7 % 30 2
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : /**
       2              :  * The cadence and budget for observing one operation, taken from the cloud
       3              :  * app's `billingOperationStore` rather than invented, so a consumer moving
       4              :  * onto the SDK sees the same request rate and the same give-up points.
       5              :  */
       6              : import { isBlockedOnCustomerPhase } from './operationState'
       7              : import type {
       8              :   BillingAuthenticationState,
       9              :   EmbeddedChallenge,
      10              :   PendingBillingOperation
      11              : } from './operationState'
      12              : 
      13         2356 : export const OPERATION_POLL_TIMING = {
      14              :   initialMs: 1_000,
      15              :   maxMs: 8_000,
      16              :   multiplier: 1.5,
      17              :   /** An operation parked on the customer is checked on a slow, flat cadence. */
      18              :   parkedMs: 30_000,
      19              :   /** Fast backoff for an actionless blocked wait: 20 turns of the 3 s PI status cache. */
      20              :   actionDiscoveryMs: 60_000
      21              : } as const
      22              : 
      23         2356 : export const OPERATION_POLL_BUDGET = {
      24              :   defaultMs: 120_000,
      25              :   /** A subscription may take minutes to discover that it needs the customer. */
      26              :   subscriptionDiscoveryMs: 5 * 60_000,
      27              :   /** Once the customer is involved, a bank challenge can idle for hours. */
      28              :   customerActionMs: 23 * 60 * 60_000
      29              : } as const
      30              : 
      31              : /**
      32              :  * What one tab holds for the customer on a pending operation. Each rail
      33              :  * builds it from its own state, because each renders a different surface:
      34              :  * the legacy cloud store offers the hosted link beside the embedded
      35              :  * challenge, while the SDK renders exactly one presentation.
      36              :  */
      37              : export interface CustomerActionHold {
      38              :   readonly authenticationState?: BillingAuthenticationState | null
      39              :   /** A hosted page this tab would open for the customer. */
      40              :   readonly offersHostedPage: boolean
      41              :   /** The embedded challenge this tab holds, whatever became of it. */
      42              :   readonly challenge?: EmbeddedChallenge['status']
      43              : }
      44              : 
      45              : /**
      46              :  * The one "customer can act here" rule both billing rails park on: a
      47              :  * retryable failure to retry, a hosted page to visit, or an embedded
      48              :  * challenge the server still says is required. A non-retryable decline never
      49              :  * reaches it; the operation is terminal by then.
      50              :  */
      51            0 : export function customerCanActHere(hold: CustomerActionHold): boolean {
      52            0 :   if (hold.authenticationState === 'failed_retryable') return true
      53            0 :   if (hold.offersHostedPage) return true
      54            0 :   return (
      55              :     hold.authenticationState === 'requires_action' &&
      56              :     (hold.challenge === 'required' || hold.challenge === 'in_progress')
      57              :   )
      58              : }
      59              : 
      60              : /**
      61              :  * The SDK renders one presentation: a hosted operation offers only its page,
      62              :  * an embedded one only its challenge. The cloud app's
      63              :  * `legacyOperationActionHold` names the rows where the two surfaces differ.
      64              :  */
      65            0 : export function pendingOperationActionHold(
      66              :   state: PendingBillingOperation
      67              : ): CustomerActionHold {
      68            0 :   return state.presentation === 'hosted'
      69              :     ? {
      70              :         authenticationState: state.authenticationState,
      71              :         offersHostedPage: state.actionUrl !== undefined
      72              :       }
      73              :     : {
      74              :         authenticationState: state.authenticationState,
      75              :         offersHostedPage: false,
      76              :         challenge: state.challenge?.status
      77              :       }
      78              : }
      79              : 
      80            0 : function customerCanAct(state: PendingBillingOperation): boolean {
      81            0 :   return customerCanActHere(pendingOperationActionHold(state))
      82              : }
      83              : 
      84              : /**
      85              :  * Waiting on the customer, not on the backend: a challenge to complete
      86              :  * elsewhere, a hosted page to finish, a phase the server reports as blocked on
      87              :  * them, or a declined attempt awaiting their retry. Once this tab's own
      88              :  * challenge completes the state reads processing and nothing waits on the
      89              :  * customer anymore.
      90              :  */
      91            0 : function isWaitingOnCustomer(state: PendingBillingOperation): boolean {
      92            0 :   return (
      93              :     state.authenticationState === 'requires_action' ||
      94              :     state.actionUrl !== undefined ||
      95              :     isBlockedOnCustomerPhase(state.serverPhase) ||
      96              :     (state.authenticationState === 'failed_retryable' &&
      97              :       state.customerActionSeen)
      98              :   )
      99              : }
     100              : 
     101              : /**
     102              :  * Parked only while the customer can act here. The server can report a
     103              :  * blocked phase and a client secret before its cached `authentication_state`
     104              :  * catches up, and the slow cadence would then hold a screen with no action.
     105              :  */
     106            0 : export function isParkedOnCustomer(state: PendingBillingOperation): boolean {
     107            0 :   return customerCanAct(state) && isWaitingOnCustomer(state)
     108              : }
     109              : 
     110              : /**
     111              :  * Blocked on the customer with nothing to offer them yet: either the action
     112              :  * is still on its way, or it belongs to someone else (a member without
     113              :  * billing permission, a tab without embedded checkout).
     114              :  */
     115            0 : export function isWaitingOnCustomerWithoutAction(
     116              :   state: PendingBillingOperation
     117              : ): boolean {
     118            0 :   return !customerCanAct(state) && isWaitingOnCustomer(state)
     119              : }
     120              : 
     121              : /**
     122              :  * `waitedWithoutActionMs` is how long the operation has continuously been
     123              :  * {@link isWaitingOnCustomerWithoutAction}; past the discovery window it
     124              :  * parks too, so an action that never arrives here costs the slow cadence.
     125              :  */
     126            0 : export function nextPollDelayMs(
     127              :   state: PendingBillingOperation,
     128              :   previousDelayMs: number | undefined,
     129              :   waitedWithoutActionMs = 0
     130              : ): number {
     131            0 :   if (state.challenge?.status !== 'failed' && isParkedOnCustomer(state)) {
     132            0 :     return OPERATION_POLL_TIMING.parkedMs
     133              :   }
     134            0 :   if (
     135              :     isWaitingOnCustomerWithoutAction(state) &&
     136              :     waitedWithoutActionMs >= OPERATION_POLL_TIMING.actionDiscoveryMs
     137              :   ) {
     138            0 :     return OPERATION_POLL_TIMING.parkedMs
     139              :   }
     140            0 :   return backoffDelayMs(previousDelayMs)
     141              : }
     142              : 
     143              : /** The wait before the next read of an operation nothing is parked on: longer after each read, up to a cap. */
     144            0 : export function backoffDelayMs(previousDelayMs: number | undefined): number {
     145            0 :   return Math.min(
     146              :     (previousDelayMs ?? OPERATION_POLL_TIMING.initialMs) *
     147              :       OPERATION_POLL_TIMING.multiplier,
     148              :     OPERATION_POLL_TIMING.maxMs
     149              :   )
     150              : }
     151              : 
     152            0 : export function pollBudgetMs(state: PendingBillingOperation): number {
     153            0 :   if (state.kind !== 'cancel' && state.customerActionSeen) {
     154            0 :     return OPERATION_POLL_BUDGET.customerActionMs
     155              :   }
     156            0 :   return state.kind === 'subscription'
     157              :     ? OPERATION_POLL_BUDGET.subscriptionDiscoveryMs
     158              :     : OPERATION_POLL_BUDGET.defaultMs
     159              : }
     160              : 
     161            0 : export function hasExhaustedPollBudget(
     162              :   state: PendingBillingOperation,
     163              :   now: number
     164              : ): boolean {
     165            0 :   return now - state.observedAt > pollBudgetMs(state)
     166              : }
        

Generated by: LCOV version 2.0-1