diff --git a/packages/account-core/src/core/billing/telemetry/portalEvent.test.ts b/packages/account-core/src/core/billing/telemetry/portalEvent.test.ts index e910904a3c1..af7808ae4c6 100644 --- a/packages/account-core/src/core/billing/telemetry/portalEvent.test.ts +++ b/packages/account-core/src/core/billing/telemetry/portalEvent.test.ts @@ -68,6 +68,24 @@ describe('the portal events', () => { outcome: 'pending', target: 'manage_subscription' } + }, + { + name: 'the portal opening to recover a failed payment', + event: { + operation: 'portal', + stage: 'opened', + outcome: 'pending', + target: 'payment_recovery', + billing_client: 'legacy' + }, + eventName: 'billing.portal.opened', + payload: { + operation: 'portal', + stage: 'opened', + outcome: 'pending', + target: 'payment_recovery', + billing_client: 'legacy' + } } ])('names and reports $name', ({ event, eventName, payload }) => { expect(getBillingTelemetryEventName(event)).toBe(eventName) diff --git a/packages/account-core/src/core/billing/telemetry/portalEvent.ts b/packages/account-core/src/core/billing/telemetry/portalEvent.ts index 13ca67b343f..56e8b909124 100644 --- a/packages/account-core/src/core/billing/telemetry/portalEvent.ts +++ b/packages/account-core/src/core/billing/telemetry/portalEvent.ts @@ -1,10 +1,15 @@ import type { BillingFailed } from './stages.js' -/** The part of the provider's hosted portal the customer was sent to. */ +/** + * The part of the provider's hosted portal the customer was sent to. + * `payment_recovery` is a checkout that stopped on a failed or outstanding + * payment and sent the customer to settle it. + */ export type BillingPortalTarget = | 'payment_methods' | 'invoices' | 'manage_subscription' + | 'payment_recovery' /** * A trip to the provider's hosted portal. What the customer does there (adding, diff --git a/src/platform/workspace/composables/useSubscriptionCheckout.test.ts b/src/platform/workspace/composables/useSubscriptionCheckout.test.ts index caef95bb43b..56cfd94f269 100644 --- a/src/platform/workspace/composables/useSubscriptionCheckout.test.ts +++ b/src/platform/workspace/composables/useSubscriptionCheckout.test.ts @@ -1878,6 +1878,207 @@ describe('useSubscriptionCheckout', () => { }) }) + describe('payment recovery portal telemetry', () => { + function portalEvents() { + return (vi.mocked(useTelemetry()?.trackBillingEvent)?.mock.calls ?? []) + .map(([event]) => event) + .filter((event) => event.operation === 'portal') + } + + function leaveAndReturn() { + window.dispatchEvent(new Event('blur')) + window.dispatchEvent(new Event('focus')) + } + + function useRailPortal(outcome: SubscriptionRailOutcome) { + mockSubscriptionRail.value = railStub({ + openPaymentPortal: vi + .fn>() + .mockResolvedValue(outcome) + }) + } + + it.for<{ + name: string + arrange: () => void + billingClient: 'sdk' | 'legacy' + }>([ + { + name: 'the legacy client', + arrange: () => {}, + billingClient: 'legacy' + }, + { + name: 'the SDK rail', + arrange: () => + useRailPortal({ + status: 'ok', + value: 'https://billing.stripe.com/rail-portal' + }), + billingClient: 'sdk' + }, + { + name: 'the legacy client when the rail route is not deployed', + arrange: () => useRailPortal({ status: 'unavailable' }), + billingClient: 'legacy' + } + ])( + 'reports the recovery portal opening from $name and one return', + async ({ arrange, billingClient }) => { + arrange() + + await submitRejectedPreview('SUBSCRIPTION_PAYMENT_REQUIRED') + leaveAndReturn() + leaveAndReturn() + + expect(portalEvents()).toEqual([ + { + operation: 'portal', + stage: 'opened', + outcome: 'pending', + target: 'payment_recovery', + billing_client: billingClient + }, + { + operation: 'portal', + stage: 'returned', + outcome: 'pending', + target: 'payment_recovery', + billing_client: billingClient + } + ]) + } + ) + + it('reports a blocked recovery tab as a failed open and the retry as the open', async () => { + mockOpen.mockReturnValueOnce(null) + await submitRejectedPreview('SUBSCRIPTION_PAYMENT_REQUIRED') + + expect(portalEvents()).toEqual([ + { + operation: 'portal', + stage: 'failed', + outcome: 'failure', + target: 'payment_recovery', + billing_client: 'legacy', + failure_category: 'redirect', + error_code: 'payment_popup_blocked' + } + ]) + + const [{ detail }] = mockToastAdd.mock.calls.at(-1)! + mockOpen.mockReturnValueOnce({}) + detail.onAction() + leaveAndReturn() + + expect(portalEvents().slice(1)).toEqual([ + { + operation: 'portal', + stage: 'opened', + outcome: 'pending', + target: 'payment_recovery', + billing_client: 'legacy' + }, + { + operation: 'portal', + stage: 'returned', + outcome: 'pending', + target: 'payment_recovery', + billing_client: 'legacy' + } + ]) + }) + + it('reports a retry that is blocked again as a second failed open', async () => { + mockOpen.mockReturnValueOnce(null) + await submitRejectedPreview('SUBSCRIPTION_PAYMENT_REQUIRED') + + const [{ detail }] = mockToastAdd.mock.calls.at(-1)! + mockOpen.mockReturnValueOnce(null) + detail.onAction() + leaveAndReturn() + + const blocked = { + operation: 'portal', + stage: 'failed', + outcome: 'failure', + target: 'payment_recovery', + billing_client: 'legacy', + failure_category: 'redirect', + error_code: 'payment_popup_blocked' + } + expect(portalEvents()).toEqual([blocked, blocked]) + }) + + it.for<{ + name: string + arrange: () => void + failure: Record + }>([ + { + name: 'a refused legacy portal request', + arrange: () => + mockGetPaymentPortalUrl.mockRejectedValueOnce( + new WorkspaceApiError('Forbidden', 403) + ), + failure: { failure_category: 'api_rejected' } + }, + { + name: 'a legacy portal request that never reached the server', + arrange: () => + mockGetPaymentPortalUrl.mockRejectedValueOnce( + new WorkspaceApiError('Network down') + ), + failure: { failure_category: 'network' } + }, + { + name: 'a rail portal failure', + arrange: () => + useRailPortal({ + status: 'error', + error: new WorkspaceApiError('Forbidden', 403) + }), + failure: { failure_category: 'api_rejected' } + }, + { + name: 'a portal address that fails validation', + arrange: () => + mockGetPaymentPortalUrl.mockResolvedValueOnce({ + url: 'https://billing.stripe.com.evil.test/portal' + }), + failure: { billing_client: 'legacy', failure_category: 'unknown' } + } + ])( + 'reports $name as a failed open and keeps the error report', + async ({ arrange, failure }) => { + arrange() + + await submitRejectedPreview('SUBSCRIPTION_PAYMENT_REQUIRED') + leaveAndReturn() + + expect(portalEvents()).toEqual([ + { + operation: 'portal', + stage: 'failed', + outcome: 'failure', + target: 'payment_recovery', + ...failure + } + ]) + expect(mockReportError).toHaveBeenCalledWith(expect.any(Error), { + surface: 'workspace', + errorType: 'billing_portal_open_failure' + }) + } + ) + + it('reports nothing when the rejection needs no payment recovery', async () => { + await submitRejectedPreview('TRANSITION_NOT_ALLOWED') + + expect(portalEvents()).toEqual([]) + }) + }) + it('shows error toast when plan slug is not found', async () => { const checkout = await setup() mockPlans.value = [] diff --git a/src/platform/workspace/composables/useSubscriptionCheckout.ts b/src/platform/workspace/composables/useSubscriptionCheckout.ts index bd27e987e64..40ef762f0d7 100644 --- a/src/platform/workspace/composables/useSubscriptionCheckout.ts +++ b/src/platform/workspace/composables/useSubscriptionCheckout.ts @@ -1,4 +1,5 @@ import type { + BillingClient, CheckoutEntryFlow, CheckoutJourneyPhaseEvent, SubscriptionCheckoutType @@ -22,6 +23,7 @@ import { useTelemetry } from '@/platform/telemetry' import { reportError } from '@/platform/telemetry/reportError' import type { PaymentIntentSource } from '@/platform/telemetry/types' import { categorizeBillingApiError } from '@/platform/telemetry/utils/billingFailureCategory' +import { createBillingPortalReporter } from '@/platform/telemetry/utils/billingPortalTelemetry' import { api } from '@/scripts/api' import { useAuthStore } from '@/stores/authStore' import type { @@ -575,13 +577,18 @@ export function useSubscriptionCheckout( * a failure throws into the caller's catch, where a legacy throw already * lands. */ - async function readPaymentPortalUrl(returnUrl: string): Promise { + async function readPaymentPortalUrl( + returnUrl: string + ): Promise<{ url: string; billingClient: BillingClient }> { if (subscriptionRail) { const outcome = await subscriptionRail.openPaymentPortal(returnUrl) - if (outcome.status === 'ok') return outcome.value + if (outcome.status === 'ok') { + return { url: outcome.value, billingClient: 'sdk' } + } if (outcome.status === 'error') throw outcome.error } - return (await workspaceApi.getPaymentPortalUrl(returnUrl)).url + const { url } = await workspaceApi.getPaymentPortalUrl(returnUrl) + return { url, billingClient: 'legacy' } } async function recoverOutstandingPayment( @@ -608,11 +615,13 @@ export function useSubscriptionCheckout( } if (!requiresRecovery || !isCurrent()) return null + const portal = createBillingPortalReporter(telemetry, 'payment_recovery') + let billingClient: BillingClient | undefined try { const returnUrl = `${globalThis.location.origin}${globalThis.location.pathname}` - const portalUrl = parseBillingPortalUrl( - await readPaymentPortalUrl(returnUrl) - ) + const portalResponse = await readPaymentPortalUrl(returnUrl) + billingClient = portalResponse.billingClient + const portalUrl = parseBillingPortalUrl(portalResponse.url) if (!isCurrent()) return null if (!portalUrl) { throw new Error( @@ -623,6 +632,7 @@ export function useSubscriptionCheckout( } const paymentWindow = window.open(portalUrl.href, '_blank') if (!paymentWindow) { + portal.blocked(billingClient) // The open above ran after an await, so it had no user gesture behind // it and got blocked. The toast's own button click is a gesture, so // retrying from there isn't blocked. @@ -637,17 +647,23 @@ export function useSubscriptionCheckout( // checkout reset); a stale click must not reopen its captured URL. onAction: () => { if (!isCurrent()) return - window.open(portalUrl.href, '_blank') + if (window.open(portalUrl.href, '_blank')) { + portal.opened(billingClient) + } else { + portal.blocked(billingClient) + } armPaymentRecoveryReturnRefresh() } } }) return 'blocked' } + portal.opened(billingClient) armPaymentRecoveryReturnRefresh() return 'opened' } catch (portalError) { if (!isCurrent()) return null + portal.failed(portalError, billingClient) reportError(portalError, { surface: 'workspace', errorType: 'billing_portal_open_failure'