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 : }
|