Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions apps/billing-web/src/session/billingWebClient.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -252,6 +252,36 @@ describe('SDK operation telemetry', () => {
}
)

it('reports a retryable decline inside an issued operation, as the SDK on billing web', async () => {
stubBillingRoutes({
status: 'pending',
authentication_state: 'failed_retryable',
decline_reason: 'card_declined'
})
const client = createBillingWebClient(authenticatedSession())
onTestFinished(() => disposeBillingClient(client))

await client.lifecycle.begin('subscription', issueOperation)

await vi.waitFor(() =>
expect(datadogRum.addAction).toHaveBeenCalledWith(
'billing.checkout.challenge_failed',
{
operation: 'checkout',
stage: 'challenge_failed',
outcome: 'pending',
operation_type: 'subscription',
billing_op_id: 'op_1',
presentation: 'hosted',
resumed: false,
decline_reason: 'card_declined',
billing_client: 'sdk',
billing_surface: 'billing_web'
}
)
)
})

it.for<{
name: string
run: (client: BillingClient) => Promise<unknown>
Expand Down
5 changes: 4 additions & 1 deletion packages/account-core/src/core/billing/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,10 @@ export {
createBillingOperationLifecycle,
operationRoute
} from './operationLifecycle.js'
export { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js'
export {
BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT,
BILLING_OPERATION_TELEMETRY_EVENT
} from '../../telemetry.js'
export * from './telemetry/index.js'
export type {
EmbeddedChallengeOutcome,
Expand Down
224 changes: 224 additions & 0 deletions packages/account-core/src/core/billing/operationLifecycle.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1553,3 +1553,227 @@ describe('createBillingOperationLifecycle', () => {
})
})
})

describe('payment friction telemetry', () => {
function frictionOf(telemetry: BillingOperationTelemetryEvent[]) {
return telemetry
.filter((event) => event.name.startsWith('billing.checkout.'))
.map(({ name, presentation, decline_reason }) =>
decline_reason === undefined
? { name, presentation }
: { name, presentation, decline_reason }
)
}

const challengeRequired = (clientSecret: string) =>
httpOk(
opStatus({
authentication_state: 'requires_action',
payment_intent_client_secret: clientSecret
})
)

it('reports a challenge the issued command already carried, with its operation', async () => {
const { lifecycle, telemetry } = harness({
embedded: true,
answers: [challengeRequired('pi_secret')]
})

await lifecycle.begin(
'subscription',
issued({ operationId: 'op-1', clientSecret: 'pi_secret' })
)
await flush()

expect(
telemetry.filter((event) => event.name.startsWith('billing.checkout.'))
).toEqual([
{
name: 'billing.checkout.challenge_required',
billing_op_id: 'op-1',
operation_type: 'subscription',
presentation: 'embedded',
resumed: false
}
])
})

it('reports a challenge a status read surfaces once, however often it is echoed', async () => {
const { lifecycle, telemetry } = harness({
embedded: true,
answers: [httpOk(opStatus()), challengeRequired('pi_secret')]
})

await lifecycle.begin('topup', issued())
await flush()
await vi.advanceTimersByTimeAsync(OPERATION_POLL_TIMING.parkedMs * 3)

expect(frictionOf(telemetry)).toEqual([
{ name: 'billing.checkout.challenge_required', presentation: 'embedded' }
])
})

it.for([
{ outcome: 'completed', expected: 'billing.checkout.challenge_completed' },
{ outcome: 'failed', expected: 'billing.checkout.challenge_failed' }
] as const)(
'reports the challenge this tab drove as $outcome',
async ({ outcome, expected }) => {
const { lifecycle, telemetry } = harness({
embedded: true,
answers: [challengeRequired('pi_secret')]
})
await lifecycle.begin(
'topup',
issued({ operationId: 'op-1', clientSecret: 'pi_secret' })
)
await flush()

lifecycle.reportChallengeStarted('op-1')
lifecycle.reportChallengeSettled('op-1', outcome)

expect(frictionOf(telemetry)).toEqual([
{
name: 'billing.checkout.challenge_required',
presentation: 'embedded'
},
{ name: expected, presentation: 'embedded' }
])
}
)

it('reports a failed challenge once when the server then echoes it as a retryable decline', async () => {
const { lifecycle, telemetry } = harness({
embedded: true,
answers: [
challengeRequired('pi_secret'),
httpOk(
opStatus({
authentication_state: 'failed_retryable',
decline_reason: 'authentication_failed',
payment_intent_client_secret: 'pi_secret'
})
)
]
})
await lifecycle.begin(
'topup',
issued({ operationId: 'op-1', clientSecret: 'pi_secret' })
)
await flush()

lifecycle.reportChallengeStarted('op-1')
lifecycle.reportChallengeSettled('op-1', 'failed')
await vi.advanceTimersByTimeAsync(OPERATION_POLL_TIMING.parkedMs * 2)

expect(lifecycle.get('op-1')).toMatchObject({
declineReason: 'authentication_failed'
})
expect(frictionOf(telemetry)).toEqual([
{ name: 'billing.checkout.challenge_required', presentation: 'embedded' },
{ name: 'billing.checkout.challenge_failed', presentation: 'embedded' }
])
})

it('reports a later, different decline after the failed challenge was echoed', async () => {
const declined = (reason: BillingOpStatus['decline_reason']) =>
httpOk(
opStatus({
authentication_state: 'failed_retryable',
decline_reason: reason,
payment_intent_client_secret: 'pi_secret'
})
)
const { lifecycle, telemetry } = harness({
embedded: true,
answers: [
challengeRequired('pi_secret'),
declined('authentication_failed'),
declined('card_declined')
]
})
await lifecycle.begin(
'topup',
issued({ operationId: 'op-1', clientSecret: 'pi_secret' })
)
await flush()

lifecycle.reportChallengeStarted('op-1')
lifecycle.reportChallengeSettled('op-1', 'failed')
await vi.advanceTimersByTimeAsync(OPERATION_POLL_TIMING.parkedMs * 3)

expect(frictionOf(telemetry)).toEqual([
{ name: 'billing.checkout.challenge_required', presentation: 'embedded' },
{ name: 'billing.checkout.challenge_failed', presentation: 'embedded' },
{
name: 'billing.checkout.challenge_failed',
presentation: 'embedded',
decline_reason: 'card_declined'
}
])
})

it('reports each retryable decline inside one hosted operation with its reason, once per decline', async () => {
const declined = (reason: BillingOpStatus['decline_reason']) =>
httpOk(
opStatus({
authentication_state: 'failed_retryable',
decline_reason: reason,
action_url: 'https://billing.example/continue'
})
)
const { lifecycle, telemetry } = harness({
answers: [
declined('card_declined'),
declined('card_declined'),
declined('insufficient_funds')
]
})

await lifecycle.begin('subscription', issued())
await flush()
await vi.advanceTimersByTimeAsync(OPERATION_POLL_TIMING.parkedMs * 3)

expect(frictionOf(telemetry)).toEqual([
{
name: 'billing.checkout.challenge_failed',
presentation: 'hosted',
decline_reason: 'card_declined'
},
{
name: 'billing.checkout.challenge_failed',
presentation: 'hosted',
decline_reason: 'insufficient_funds'
}
])
})

it('does not report the same challenge again when it returns from the hosted page', async () => {
const { lifecycle, telemetry } = harness({
embedded: true,
answers: [
challengeRequired('pi_secret'),
httpOk(
opStatus({
authentication_state: 'requires_action',
payment_intent_client_secret: 'pi_secret',
action_url: 'https://billing.example/continue'
})
)
]
})
await lifecycle.begin(
'topup',
issued({ operationId: 'op-1', clientSecret: 'pi_secret' })
)
await flush()
await vi.advanceTimersByTimeAsync(OPERATION_POLL_TIMING.parkedMs)

lifecycle.switchPresentation('op-1', 'hosted')
lifecycle.switchPresentation('op-1', 'embedded')

expect(frictionOf(telemetry)).toEqual([
{ name: 'billing.checkout.challenge_required', presentation: 'embedded' }
])
})
})
47 changes: 43 additions & 4 deletions packages/account-core/src/core/billing/operationLifecycle.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,10 @@
* contract is new.
*/

import { BILLING_OPERATION_TELEMETRY_EVENT } from '../../telemetry.js'
import {
BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT,
BILLING_OPERATION_TELEMETRY_EVENT
} from '../../telemetry.js'
import type {
BillingFailure,
BillingResult,
Expand Down Expand Up @@ -61,6 +64,8 @@ import {
reduceBillingOperation,
validateActionUrl
} from './operationState.js'
import type { PaymentFrictionSignal } from './paymentFriction.js'
import { paymentFrictionBetween } from './paymentFriction.js'
import { selectBillingPresentation } from './presentation.js'
import { readValidatedBillingResponse } from './sharedRead.js'
import type { BillingStatusData, BillingStatusReader } from './status.js'
Expand Down Expand Up @@ -90,8 +95,12 @@ export type BillingOperationFailureCategory =
| 'reconciliation_needed'
| 'stale_operation'

type BillingOperationTelemetryEventName =
| (typeof BILLING_OPERATION_TELEMETRY_EVENT)[keyof typeof BILLING_OPERATION_TELEMETRY_EVENT]
| (typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT)[keyof typeof BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT]

export interface BillingOperationTelemetryEvent {
readonly name: (typeof BILLING_OPERATION_TELEMETRY_EVENT)[keyof typeof BILLING_OPERATION_TELEMETRY_EVENT]
readonly name: BillingOperationTelemetryEventName
readonly billing_op_id: string
readonly operation_type: BillingOperationKind
readonly presentation: BillingPresentation
Expand Down Expand Up @@ -311,6 +320,14 @@ function failureCategoryFor(
}
}

const FRICTION_EVENT_NAME = {
challenge_required:
BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeRequired,
challenge_completed:
BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeCompleted,
challenge_failed: BILLING_CHECKOUT_FRICTION_TELEMETRY_EVENT.challengeFailed
} as const satisfies Record<PaymentFrictionSignal['stage'], string>

/** The pause is this tab's own challenge on screen; a hosted page never pauses. */
function isDrivingChallenge(state: PendingBillingOperation): boolean {
return (
Expand Down Expand Up @@ -390,10 +407,31 @@ export function createBillingOperationLifecycle(
})
}

function emitFrictionTelemetry(
record: OperationRecord,
before: BillingOperationState | undefined
) {
const state = record.state
for (const signal of paymentFrictionBetween(before, state)) {
onTelemetry?.({
name: FRICTION_EVENT_NAME[signal.stage],
billing_op_id: state.id,
operation_type: state.kind,
presentation: state.presentation,
resumed: record.resumed,
...('declineReason' in signal && signal.declineReason !== undefined
? { decline_reason: signal.declineReason }
: {})
})
}
}

function dispatch(record: OperationRecord, event: BillingOperationEvent) {
const next = reduceBillingOperation(record.state, event)
if (next === record.state) return
const before = record.state
const next = reduceBillingOperation(before, event)
if (next === before) return
record.state = next
emitFrictionTelemetry(record, before)
if (isTerminal(next)) {
stopTimer(record)
pointers.settle(next)
Expand Down Expand Up @@ -566,6 +604,7 @@ export function createBillingOperationLifecycle(
presentation: input.presentation,
resumed: input.resumed
})
emitFrictionTelemetry(record, undefined)
startObserving(record, input, state)
return record
}
Expand Down
Loading
Loading