From bcdc0e8526cefd809815a35b9640464eb43621df Mon Sep 17 00:00:00 2001 From: dante01yoon Date: Tue, 15 Sep 2026 11:48:00 -0400 Subject: [PATCH] [backport cloud/1.54] feat(billing): embedded checkout journey instrumentation (#17348) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Manual backport of 6a6a4a2 — the automated cherry-pick hit conflicts. Resolutions against this branch: - billingOperationStore: this branch has no try/cleanup restructure, so the journey clear sits before the success telemetry instead. - TopUpCreditsDialogContentWorkspace.test: this branch mocks the operation store with hoisted mocks and has no billingOperationTestUtils helper, so only the journey setup was added onto its own structure, plus a firebase/auth spy so useAuthStore() does not reach real Firebase. - ADR index and provider imports merged with this branch's entries. --- ...eckout-journey-instrumentation-contract.md | 172 +++++++ docs/adr/README.md | 1 + src/locales/en/main.json | 1 + .../telemetry/TelemetryRegistry.test.ts | 23 + src/platform/telemetry/TelemetryRegistry.ts | 5 + .../telemetry/checkoutJourneyEvent.test.ts | 128 +++++ .../cloud/DatadogRumTelemetryProvider.ts | 10 + .../cloud/MixpanelTelemetryProvider.ts | 11 +- .../cloud/PostHogTelemetryProvider.ts | 16 +- src/platform/telemetry/types.ts | 180 ++++++- ...TopUpCreditsDialogContentWorkspace.test.ts | 109 +++- .../TopUpCreditsDialogContentWorkspace.vue | 73 ++- .../UnifiedStripePaymentSelector.test.ts | 302 ++++++++++- .../UnifiedStripePaymentSelector.vue | 186 ++++++- .../useSubscriptionCheckout.test.ts | 153 +++++- .../composables/useSubscriptionCheckout.ts | 119 +++++ .../stores/billingOperationStore.test.ts | 86 ++++ .../workspace/stores/billingOperationStore.ts | 8 + .../workspace/utils/checkoutJourney.test.ts | 334 ++++++++++++ .../workspace/utils/checkoutJourney.ts | 482 ++++++++++++++++++ 20 files changed, 2351 insertions(+), 48 deletions(-) create mode 100644 docs/adr/BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md create mode 100644 src/platform/telemetry/checkoutJourneyEvent.test.ts create mode 100644 src/platform/workspace/utils/checkoutJourney.test.ts create mode 100644 src/platform/workspace/utils/checkoutJourney.ts diff --git a/docs/adr/BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md b/docs/adr/BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md new file mode 100644 index 00000000000..8937da8d7db --- /dev/null +++ b/docs/adr/BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md @@ -0,0 +1,172 @@ +# ADR-BILLING-CHECKOUT-0031: Checkout Journey Instrumentation Contract + +Date: 2026-09-09 + +## Status + +Proposed + +## Context + +The embedded-checkout rollout replaces the hosted Stripe redirect (control) +with an in-app Payment Element (treatment), gated by the fail-closed boolean +server feature `embedded_checked_enabled`. To compare the two arms fairly we +need observable, correlated checkout journeys, but the existing billing +telemetry only records terminal business outcomes +(`billing..started|succeeded|failed|timeout`). Those events cannot +answer where a journey stalled (preview, card entry, submission), cannot tell a +resolved `control` from an unknown assignment, and rotate their only stable +identifier — `billing_op_id`, minted by the backend — on retry. + +Two existing utilities own fragments of this state and neither is sufficient +alone: + +- `subscriptionCheckoutTracker` — a personal-tier `attempt_id` in + `localStorage` (6h). Excludes team and top-up. +- `pendingSubscriptionCheckout` — a server `operationId` in `sessionStorage` + (24h) for polling recovery. Only exists once the initiating request succeeds. + +ADR-AUTH-BILLING-0014 (Proposed) already argues for a rail-neutral _attempt +context_ (`billing_attempt_id` + `workspace_id`) captured before the first +`await` and handed to `startOperation()`. That decision is not yet implemented. +This ADR ratifies the wider _journey_ contract the rollout dashboard consumes +and is realized by the same PR (commits FE-02/FE-03), superseding nothing but +extending 0014's attempt context with a durable, arm-frozen journey identity. + +## Decision + +### 1. A dedicated journey event union, separate from terminal outcomes + +Intermediate lifecycle stages are modelled as a `CheckoutJourneyTelemetryEvent` +discriminated union on `phase`, emitted as `billing.checkout.`, kept +deliberately separate from the `BillingTelemetryEvent` terminal taxonomy. A +client observation of progress (preview ready, element mounted, token created) +must never be readable as a business success/failure/timeout. Phases: + +| Event | Emission boundary | +| ------------------------------------------- | ------------------------------------------------------------------------------ | +| `billing.checkout.entered` | Once at eligible intent, before preview, card collection, or arm-specific work | +| `billing.checkout.preview_ready` | A successful quote accepted into usable UI, once per accepted revision | +| `billing.checkout.preview_failed` | Preview cannot become usable; sanitized category/code + revision identity | +| `billing.checkout.payment_element_ready` | Stripe element readiness callback for the current live mount | +| `billing.checkout.payment_element_failed` | SDK init, mount/load, or config-update failure; phase-distinguished | +| `billing.checkout.payment_submit_attempted` | Submission passes local busy/eligibility guards, before Elements validation | +| `billing.checkout.payment_submit_failed` | Elements validation or token-creation failure; phase-distinguished | +| `billing.checkout.submitted` | Immediately before the checkout API request, after any token creation | +| `billing.checkout.operation_linked` | Response or validated recovery binds the journey to an operation ID | + +Every event carries a frozen `CheckoutJourneyContext`: `checkout_journey_id`, +`checkout_entered_at` (UTC), `assignment_status`, optional `assigned_arm`, +`entry_flow`, `entry_source`, and optional `ui_mode`/`billing_op_id`. +`ui_mode` records the checkout UI the user actually saw (`embedded`/`hosted`), +so a frozen arm can be reconciled against real experience. The two +`payment_element_*` phases additionally carry `element` (`payment`/`address`), +because the shared Elements group mounts more than one element and a funnel +that counts readiness or attributes a mount failure must know which one +reported it. `schema_version` is +stamped on every payload. Correlation rides on `checkout_journey_id` (all +events) and `billing_op_id` (from `operation_linked` onward, the join to the +terminal `billing.*` taxonomy), plus each provider's own native event id +(PostHog event UUID, Datadog RUM `action.id`); the dispatcher does not mint a +redundant shared id. + +### 2. Assignment is frozen from the server response, never fabricated + +The arm is derived once, at entry, from the presence and value of +`embedded_checked_enabled` in the server feature payload: + +- key present, `true` → `assignment_status: resolved`, `assigned_arm: treatment` +- key present, non-`true` → `resolved`, `assigned_arm: control` +- key absent → `assignment_status: unavailable`, **`assigned_arm` omitted** + +An unknown assignment never masquerades as a resolved `control`. The UI keeps +its current fail-closed behaviour; a later flag refresh changes observed +behaviour but not the frozen assignment. Checkout is never blocked waiting on +flag or identity resolution. + +### 3. Journey scope and lifecycle transitions + +A journey is one authenticated actor, one workspace, and one intended purchase. +Persistence is per-tab `sessionStorage` (24h), surviving reload. The lifecycle +owner exposes four named transitions: + +| Transition | Rule | +| ---------- | -------------------------------------------------------------------------------------------------------- | +| **resume** | Same actor, workspace, and `entry_flow`, unexpired → reuse the stored record (no new entry) | +| **create** | No record, or a changed actor / workspace / entry flow, or expired → discard stale, mint a fresh journey | +| **end** | A bound operation succeeding, or an explicit clear, removes the record | +| **retain** | A bound operation failing or timing out keeps the record, so a retry stays on the same journey | + +UI remount is not an entry. A changed sign-in or workspace switch cannot inherit +the previous context. Finer intent boundaries within a rail (tier change, top-up +amount change) are enforced by the calling composable choosing to start a fresh +journey; the owner enforces the actor/workspace/flow boundary. Stale or corrupt +storage is discarded safely and legacy records without journey metadata are +treated as unknown, never assigned retroactively. Persisted timestamps are +validated at the boundary — a non-finite `started_at_ms` would make the record +unexpirable, and an unparseable `entered_at` would reach telemetry as the +journey's declared UTC entry time. When a storage write fails the persisted +record is treated as stale for the rest of the session rather than rehydrated, +so a clear that could not reach storage does not resurrect the journey. + +Storage is a single per-tab slot, so two rails cannot hold independent journeys +at once. A journey already bound to an in-flight operation (`billing_op_id` set) +takes precedence: a differing rail's entry is refused — it is given no journey +rather than the foreign one, and so emits no `entered`. A journey binds to +exactly one operation and is never rebound, and the bound journey's poller owns +the terminal clear (gated on `billing_op_id`) until it resolves. + +**Known limitation.** Refusing entry does not make the blocked rail silent. Every +later phase emitter re-reads the shared slot through `getActiveCheckoutJourney()` +rather than carrying the record it was given at entry, so a blocked rail's +`preview_*`, `payment_*` and `submitted` phases are still emitted against the +owning rail's record — under its `entry_flow`, `journey_id` and `billing_op_id`. +Queries that split by `entry_flow` must therefore treat an overlap window as +contaminated rather than authoritative. Closing this needs the record to be +threaded from entry through to each emitter (including +`UnifiedStripePaymentSelector`, which today resolves the journey itself), which +is deferred with full per-rail isolation. + +### 4. Privacy + +Never capture confirmation tokens, client secrets, card details, raw Stripe +payloads, action URLs, or unbounded error messages. Only reviewed error-code +allowlists and categorical metadata cross the wire. Error reporting reuses +`reportError()`; no raw Sentry/Datadog sinks and no user identifiers in URLs. + +## Consequences + +### Positive + +- The dashboard can compare arms on one denominator (`checkout_journey_id`) and + see where journeys stall, not just whether they ended. +- A resolved `control` is distinguishable from an unavailable assignment, so + fail-closed fallbacks are not miscounted as intended control exposure. +- The journey identity survives reload and retry, and is rail-neutral, so the + top-up rail and team paths correlate for free. +- Intermediate observations cannot be mistaken for business truth. + +### Negative + +- Client observations are not authoritative completion. Grant/outcome joins + remain a backend/data integration (see below); the completion tile is not + decision-ready until that owner verifies the joins. +- Per-tab `sessionStorage` does not share a journey across tabs; cross-tab + operation recovery continues to rely on `pendingSubscriptionCheckout`. +- Finer intent boundaries are a caller responsibility, not enforced centrally. + +## Notes + +Backend/data handoffs this frontend work depends on but does not deliver: + +| Dependency | Owner | Blocks | +| ------------------------------------------------------------------------------- | ------------- | ------------------------------ | +| Backend outcomes in PostHog (timestamped status + grant evidence, lag contract) | Billing/data | Authoritative completion tiles | +| Durable correlation (retain attempt/journey join across retries) | Billing | Cross-system funnel | +| Rollout stage source (effective-time allocation log) | Rollout/data | Stage-separated enrollment | +| Identity/flow mapping (UID convention, eligible scope, unknown-flow handling) | Frontend/data | Valid denominators | + +Realized by this PR's FE-02 (`CheckoutJourneyTelemetryEvent` + provider +delivery) and FE-03 (`checkoutJourney` lifecycle owner). Emission wiring +(FE-04..FE-08) and the diagnostics follow-ups (FE-09/FE-10) build on this +contract. diff --git a/docs/adr/README.md b/docs/adr/README.md index b8e84f57b61..b138f68f7a2 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -12,6 +12,7 @@ An Architecture Decision Record captures an important architectural decision mad | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | ---------- | | [AUTH-BILLING-0014](AUTH-BILLING-0014-billing-attempt-context-and-workspace-scope.md) | Billing Attempt Context and Workspace Scope | Proposed | 2026-07-28 | | [AUTH-CREDENTIALS-0011](AUTH-CREDENTIALS-0011-cloud-credential-lifecycle-invariants.md) | Cloud Credential Lifecycle Invariants | Proposed | 2026-07-09 | +| [BILLING-CHECKOUT-0031](BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md) | Checkout Journey Instrumentation Contract | Proposed | 2026-09-09 | | [CRDT-FOLLOWER-0025](CRDT-FOLLOWER-0025-in-app-agent-crdt-follower-and-distribution-resolved-boundaries.md) | In-App Agent CRDT Follower and Distribution-Resolved Boundaries | Proposed | 2026-08-21 | | [CRDT-LAYOUT-0003](CRDT-LAYOUT-0003-crdt-layout-intent-and-local-measurement.md) | CRDT Layout Intent and Local Measurement | Proposed | 2025-08-27 | | [CRDT-MINT-0018](CRDT-MINT-0018-merge-identity-for-node-transfers.md) | Merge Identity for Node Transfers | Proposed | 2026-08-25 | diff --git a/src/locales/en/main.json b/src/locales/en/main.json index 7a67cfb284e..9b9405bf36d 100644 --- a/src/locales/en/main.json +++ b/src/locales/en/main.json @@ -3108,6 +3108,7 @@ "confirmChangeTitle": "Review your scheduled change", "paymentPopupBlocked": "Couldn't open the payment page — please allow popups and try again.", "paymentMethod": "Payment method", + "billingAddress": "Billing address", "stripeMethodChoice": "Your payment details are handled securely by Stripe.", "alipayRenewalNote": "Alipay authorization will also be used for automatic renewals and future purchases.", "payAndSubscribe": "Pay and subscribe", diff --git a/src/platform/telemetry/TelemetryRegistry.test.ts b/src/platform/telemetry/TelemetryRegistry.test.ts index 9d589f8b02a..2da26094624 100644 --- a/src/platform/telemetry/TelemetryRegistry.test.ts +++ b/src/platform/telemetry/TelemetryRegistry.test.ts @@ -10,6 +10,7 @@ import type { AgentPanelOpenedMetadata, AgentWorkflowAppliedMetadata, BillingTelemetryEvent, + CheckoutJourneyTelemetryEvent, TelemetryProvider } from './types' @@ -223,6 +224,28 @@ describe('TelemetryRegistry', () => { expect(b.trackBillingEvent).toHaveBeenCalledExactlyOnceWith(event) }) + it('dispatches the same checkout journey event to every provider', () => { + const a: TelemetryProvider = { trackCheckoutJourneyEvent: vi.fn() } + const b: TelemetryProvider = { trackCheckoutJourneyEvent: vi.fn() } + const registry = new TelemetryRegistry() + registry.registerProvider(a) + registry.registerProvider(b) + + const event: CheckoutJourneyTelemetryEvent = { + phase: 'entered', + checkout_journey_id: 'journey-1', + checkout_entered_at: '2026-09-09T00:00:00.000Z', + assignment_status: 'resolved', + assigned_arm: 'treatment', + entry_flow: 'initial_subscription', + entry_source: 'pricing' + } + registry.trackCheckoutJourneyEvent(event) + + expect(a.trackCheckoutJourneyEvent).toHaveBeenCalledExactlyOnceWith(event) + expect(b.trackCheckoutJourneyEvent).toHaveBeenCalledExactlyOnceWith(event) + }) + it('dispatches trackWidgetFavoriteToggled to every registered provider', () => { const a: TelemetryProvider = { trackWidgetFavoriteToggled: vi.fn() } const b: TelemetryProvider = { trackWidgetFavoriteToggled: vi.fn() } diff --git a/src/platform/telemetry/TelemetryRegistry.ts b/src/platform/telemetry/TelemetryRegistry.ts index 5cfc8327def..c88c9113951 100644 --- a/src/platform/telemetry/TelemetryRegistry.ts +++ b/src/platform/telemetry/TelemetryRegistry.ts @@ -12,6 +12,7 @@ import type { BeginCheckoutMetadata, BillingTelemetryEvent, BootstrapCompleteMetadata, + CheckoutJourneyTelemetryEvent, DefaultViewSetMetadata, EnterLinearMetadata, ExecutionErrorMetadata, @@ -192,6 +193,10 @@ export class TelemetryRegistry implements TelemetryDispatcher { this.dispatch((provider) => provider.trackBillingEvent?.(event)) } + trackCheckoutJourneyEvent(event: CheckoutJourneyTelemetryEvent): void { + this.dispatch((provider) => provider.trackCheckoutJourneyEvent?.(event)) + } + trackRunButton(properties: RunButtonProperties): void { this.dispatch((provider) => provider.trackRunButton?.(properties)) } diff --git a/src/platform/telemetry/checkoutJourneyEvent.test.ts b/src/platform/telemetry/checkoutJourneyEvent.test.ts new file mode 100644 index 00000000000..e696b73d966 --- /dev/null +++ b/src/platform/telemetry/checkoutJourneyEvent.test.ts @@ -0,0 +1,128 @@ +import { describe, expect, it } from 'vitest' + +import { + CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE, + CHECKOUT_JOURNEY_SCHEMA_VERSION, + getCheckoutJourneyTelemetryEventName, + getCheckoutJourneyTelemetryEventPayload +} from './types' +import type { CheckoutJourneyTelemetryEvent } from './types' + +const baseContext = { + checkout_journey_id: 'journey-1', + checkout_entered_at: '2026-09-09T00:00:00.000Z', + entry_flow: 'initial_subscription', + entry_source: 'pricing' +} as const + +describe('getCheckoutJourneyTelemetryEventName', () => { + it('derives the wire name from the phase', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'preview_ready', + assignment_status: 'resolved', + assigned_arm: 'treatment' + } + expect(getCheckoutJourneyTelemetryEventName(event)).toBe( + 'billing.checkout.preview_ready' + ) + }) + + // The table is a total Record, so a missing phase fails to compile — but a + // swapped value (entered -> 'billing.checkout.submitted') would not. Comparing + // each key against its own value restores what the template literal proved. + it.for(Object.entries(CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE))( + 'names %s after its own phase', + ([phase, name]) => { + expect(name).toBe(`billing.checkout.${phase}`) + + const event = { + ...baseContext, + phase, + assignment_status: 'unavailable' + } as CheckoutJourneyTelemetryEvent + expect(getCheckoutJourneyTelemetryEventName(event)).toBe(name) + } + ) +}) + +describe('getCheckoutJourneyTelemetryEventPayload', () => { + it('stamps schema version and carries the resolved arm', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'entered', + assignment_status: 'resolved', + assigned_arm: 'control' + } + const payload = getCheckoutJourneyTelemetryEventPayload(event) + expect(payload.schema_version).toBe(CHECKOUT_JOURNEY_SCHEMA_VERSION) + expect(payload.assigned_arm).toBe('control') + }) + + it('omits assigned_arm when assignment is unavailable', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'entered', + assignment_status: 'unavailable' + } + const payload = getCheckoutJourneyTelemetryEventPayload(event) + expect(payload.assignment_status).toBe('unavailable') + expect('assigned_arm' in payload).toBe(false) + }) + + it('omits absent optional context rather than emitting undefined keys', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'entered', + assignment_status: 'unavailable' + } + const payload = getCheckoutJourneyTelemetryEventPayload(event) + expect('billing_op_id' in payload).toBe(false) + expect('ui_mode' in payload).toBe(false) + }) + + it('carries the ui_mode the user actually saw', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'entered', + assignment_status: 'resolved', + assigned_arm: 'treatment', + ui_mode: 'embedded' + } + const payload = getCheckoutJourneyTelemetryEventPayload(event) + expect(payload.ui_mode).toBe('embedded') + }) + + it('carries phase-specific fields for a failed preview', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'preview_failed', + assignment_status: 'resolved', + assigned_arm: 'treatment', + failure_category: 'network', + preview_revision: 'rev-7' + } + const payload = getCheckoutJourneyTelemetryEventPayload(event) + expect(payload).toMatchObject({ + phase: 'preview_failed', + failure_category: 'network', + preview_revision: 'rev-7' + }) + }) + + it('distinguishes the failing element from the failure phase', () => { + const event: CheckoutJourneyTelemetryEvent = { + ...baseContext, + phase: 'payment_element_failed', + assignment_status: 'resolved', + assigned_arm: 'treatment', + element: 'address', + element_phase: 'mount' + } + const payload = getCheckoutJourneyTelemetryEventPayload(event) + expect(payload).toMatchObject({ + element: 'address', + element_phase: 'mount' + }) + }) +}) diff --git a/src/platform/telemetry/providers/cloud/DatadogRumTelemetryProvider.ts b/src/platform/telemetry/providers/cloud/DatadogRumTelemetryProvider.ts index b65d75e808e..8910bfe61aa 100644 --- a/src/platform/telemetry/providers/cloud/DatadogRumTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/DatadogRumTelemetryProvider.ts @@ -4,6 +4,7 @@ import { datadogRum } from '@datadog/browser-rum' import type { BillingTelemetryEvent, BootstrapCompleteMetadata, + CheckoutJourneyTelemetryEvent, ExecutionOutcomeMetadata, ImageLoadFailureMetadata, TelemetryProvider, @@ -13,6 +14,8 @@ import type { import { getBillingTelemetryEventName, getBillingTelemetryEventPayload, + getCheckoutJourneyTelemetryEventName, + getCheckoutJourneyTelemetryEventPayload, TelemetryEvents } from '../../types' @@ -64,6 +67,13 @@ export class DatadogRumTelemetryProvider implements TelemetryProvider { ) } + trackCheckoutJourneyEvent(event: CheckoutJourneyTelemetryEvent): void { + datadogRum.addAction( + getCheckoutJourneyTelemetryEventName(event), + getCheckoutJourneyTelemetryEventPayload(event) + ) + } + trackExecutionOutcome({ startTime, submissionAcceptedAt, diff --git a/src/platform/telemetry/providers/cloud/MixpanelTelemetryProvider.ts b/src/platform/telemetry/providers/cloud/MixpanelTelemetryProvider.ts index 88bc21a9361..d9cda2ae291 100644 --- a/src/platform/telemetry/providers/cloud/MixpanelTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/MixpanelTelemetryProvider.ts @@ -40,7 +40,11 @@ import type { } from '../../types' import { remoteConfig } from '@/platform/remoteConfig/remoteConfig' import type { RemoteConfig } from '@/platform/remoteConfig/types' -import { OnboardingTourEvents, TelemetryEvents } from '../../types' +import { + CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE, + OnboardingTourEvents, + TelemetryEvents +} from '../../types' import { normalizeSurveyResponses } from '../../utils/surveyNormalization' const DEFAULT_DISABLED_EVENTS = [ @@ -55,7 +59,10 @@ const DEFAULT_DISABLED_EVENTS = [ TelemetryEvents.WORKFLOW_CREATED ] as const satisfies TelemetryEventName[] -const TELEMETRY_EVENT_SET = new Set(Object.values(TelemetryEvents)) +const TELEMETRY_EVENT_SET = new Set([ + ...Object.values(TelemetryEvents), + ...Object.values(CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE) +]) interface QueuedEvent { eventName: TelemetryEventName diff --git a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts index 0c1b1814118..f40177b1000 100644 --- a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts @@ -26,6 +26,7 @@ import type { UnifiedAuthRetryMetadata, BeginCheckoutMetadata, BillingTelemetryEvent, + CheckoutJourneyTelemetryEvent, DefaultViewSetMetadata, EnterLinearMetadata, ExecutionErrorMetadata, @@ -74,8 +75,11 @@ import type { } from '../../types' import { CANCELLATION_STAGE_EVENTS, + CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE, getBillingTelemetryEventName, getBillingTelemetryEventPayload, + getCheckoutJourneyTelemetryEventName, + getCheckoutJourneyTelemetryEventPayload, OnboardingTourEvents, TelemetryEvents } from '../../types' @@ -95,7 +99,10 @@ const DEFAULT_DISABLED_EVENTS = [ TelemetryEvents.WORKFLOW_CREATED ] as const satisfies TelemetryEventName[] -const TELEMETRY_EVENT_SET = new Set(Object.values(TelemetryEvents)) +const TELEMETRY_EVENT_SET = new Set([ + ...Object.values(TelemetryEvents), + ...Object.values(CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE) +]) interface QueuedEvent { eventName: TelemetryEventName @@ -482,6 +489,13 @@ export class PostHogTelemetryProvider implements TelemetryProvider { ) } + trackCheckoutJourneyEvent(event: CheckoutJourneyTelemetryEvent): void { + this.trackEvent( + getCheckoutJourneyTelemetryEventName(event), + getCheckoutJourneyTelemetryEventPayload(event) + ) + } + trackRunButton(properties: RunButtonProperties): void { this.lastTriggerSource = properties.trigger_source this.trackEvent(TelemetryEvents.RUN_BUTTON_CLICKED, properties) diff --git a/src/platform/telemetry/types.ts b/src/platform/telemetry/types.ts index 8ebec412783..f203a483e31 100644 --- a/src/platform/telemetry/types.ts +++ b/src/platform/telemetry/types.ts @@ -997,6 +997,179 @@ export function getBillingTelemetryEventPayload(event: BillingTelemetryEvent) { } } +/** + * Checkout-journey lifecycle events for the embedded-checkout rollout. + * + * These intermediate stages are kept deliberately separate from the terminal + * billing taxonomy above (`billing..`): entry, preview, and + * Payment Element observations are client observations of progress, never + * business success/failure/timeout. They share one frozen journey context so + * the two rollout arms can be compared on the same denominator. + */ +export const CHECKOUT_JOURNEY_SCHEMA_VERSION = 1 + +export type CheckoutJourneyArm = 'control' | 'treatment' +export type CheckoutAssignmentStatus = 'resolved' | 'unavailable' +export type CheckoutUiMode = 'embedded' | 'hosted' | 'unknown' +export type CheckoutEntryFlow = + | 'initial_subscription' + | 'paid_upgrade' + | 'topup' + | 'other' + | 'unknown' +export type CheckoutEntrySource = + | 'pricing' + | 'deep_link' + | 'recovery' + | 'settings_billing' + | 'other' + | 'unknown' +type CheckoutElementPhase = 'init' | 'mount' | 'update' +/** Which Stripe element in the shared group the observation came from. */ +type CheckoutElementKind = 'payment' | 'address' +type CheckoutSubmitPhase = 'validation' | 'token_creation' + +/** + * The frozen arm assignment. A resolved assignment always carries an arm; an + * unavailable one never does, so an unknown assignment cannot masquerade as a + * resolved `control`. Encoded as a discriminated union so the invariant is a + * compile-time guarantee rather than a convention. + */ +type CheckoutJourneyAssignment = + | { assignment_status: 'resolved'; assigned_arm: CheckoutJourneyArm } + | { assignment_status: 'unavailable'; assigned_arm?: never } + +/** + * Non-sensitive entry context frozen at journey creation and replayed on every + * journey event. + */ +export type CheckoutJourneyContext = { + checkout_journey_id: string + /** UTC ISO-8601 timestamp captured at common intent, preserved across reload. */ + checkout_entered_at: string + ui_mode?: CheckoutUiMode + entry_flow: CheckoutEntryFlow + entry_source: CheckoutEntrySource + billing_op_id?: string +} & CheckoutJourneyAssignment + +type CheckoutJourneyEntered = { phase: 'entered' } +type CheckoutJourneyPreviewReady = { + phase: 'preview_ready' + preview_revision?: string +} +type CheckoutJourneyPreviewFailed = { + phase: 'preview_failed' + failure_category: BillingFailureCategory + error_code?: BillingErrorCode + preview_revision?: string +} +type CheckoutJourneyPaymentElementReady = { + phase: 'payment_element_ready' + element: CheckoutElementKind +} +type CheckoutJourneyPaymentElementFailed = { + phase: 'payment_element_failed' + element: CheckoutElementKind + element_phase: CheckoutElementPhase + error_code?: string +} +type CheckoutJourneyPaymentSubmitAttempted = { + phase: 'payment_submit_attempted' +} +type CheckoutJourneyPaymentSubmitFailed = { + phase: 'payment_submit_failed' + submit_phase: CheckoutSubmitPhase + error_code?: string +} +type CheckoutJourneySubmitted = { phase: 'submitted' } +type CheckoutJourneyOperationLinked = { + phase: 'operation_linked' + billing_op_id: string +} + +export type CheckoutJourneyPhaseEvent = + | CheckoutJourneyEntered + | CheckoutJourneyPreviewReady + | CheckoutJourneyPreviewFailed + | CheckoutJourneyPaymentElementReady + | CheckoutJourneyPaymentElementFailed + | CheckoutJourneyPaymentSubmitAttempted + | CheckoutJourneyPaymentSubmitFailed + | CheckoutJourneySubmitted + | CheckoutJourneyOperationLinked + +type CheckoutJourneyPhase = CheckoutJourneyPhaseEvent['phase'] + +export type CheckoutJourneyTelemetryEvent = CheckoutJourneyContext & + CheckoutJourneyPhaseEvent + +export type CheckoutJourneyTelemetryEventName = + `billing.checkout.${CheckoutJourneyPhase}` + +/** + * The wire name for every phase. Typed as a total `Record` over the phase + * union, so a phase added to the union without a name here fails to compile — + * and so the runtime list below can never drift from the emitted names. + */ +export const CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE: Record< + CheckoutJourneyPhase, + CheckoutJourneyTelemetryEventName +> = { + entered: 'billing.checkout.entered', + preview_ready: 'billing.checkout.preview_ready', + preview_failed: 'billing.checkout.preview_failed', + payment_element_ready: 'billing.checkout.payment_element_ready', + payment_element_failed: 'billing.checkout.payment_element_failed', + payment_submit_attempted: 'billing.checkout.payment_submit_attempted', + payment_submit_failed: 'billing.checkout.payment_submit_failed', + submitted: 'billing.checkout.submitted', + operation_linked: 'billing.checkout.operation_linked' +} + +export function getCheckoutJourneyTelemetryEventName( + event: CheckoutJourneyTelemetryEvent +): CheckoutJourneyTelemetryEventName { + return CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE[event.phase] +} + +export function getCheckoutJourneyTelemetryEventPayload( + event: CheckoutJourneyTelemetryEvent +) { + return { + schema_version: CHECKOUT_JOURNEY_SCHEMA_VERSION, + phase: event.phase, + checkout_journey_id: event.checkout_journey_id, + checkout_entered_at: event.checkout_entered_at, + assignment_status: event.assignment_status, + entry_flow: event.entry_flow, + entry_source: event.entry_source, + ...(event.assigned_arm !== undefined && { + assigned_arm: event.assigned_arm + }), + ...(event.ui_mode !== undefined && { ui_mode: event.ui_mode }), + ...(event.billing_op_id !== undefined && { + billing_op_id: event.billing_op_id + }), + ...('preview_revision' in event && + event.preview_revision !== undefined && { + preview_revision: event.preview_revision + }), + ...('failure_category' in event && { + failure_category: event.failure_category + }), + ...('error_code' in event && + event.error_code !== undefined && { error_code: event.error_code }), + ...('element' in event && { element: event.element }), + ...('element_phase' in event && { element_phase: event.element_phase }), + ...('submit_phase' in event && { submit_phase: event.submit_phase }) + } +} + +type CheckoutJourneyTelemetryEventPayload = ReturnType< + typeof getCheckoutJourneyTelemetryEventPayload +> + /** * Telemetry provider interface for individual providers. * All methods are optional - providers only implement what they need. @@ -1038,6 +1211,9 @@ export interface TelemetryProvider { trackBillingEvent?(event: BillingTelemetryEvent): void + /** Emit a checkout-journey lifecycle event to this provider. */ + trackCheckoutJourneyEvent?(event: CheckoutJourneyTelemetryEvent): void + // Survey flow events trackSurvey?(stage: 'opened' | 'submitted', responses?: SurveyResponses): void @@ -1304,7 +1480,8 @@ export const TelemetryEvents = { } as const export type TelemetryEventName = - (typeof TelemetryEvents)[keyof typeof TelemetryEvents] + | (typeof TelemetryEvents)[keyof typeof TelemetryEvents] + | CheckoutJourneyTelemetryEventName export const OnboardingTourEvents: Record< OnboardingTourStage, @@ -1395,3 +1572,4 @@ export type TelemetryEventProperties = | SubscriptionSuccessMetadata | WorkspaceInviteFailedMetadata | BillingTelemetryEvent + | CheckoutJourneyTelemetryEventPayload diff --git a/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.test.ts b/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.test.ts index 74e03258813..b2f4144e93f 100644 --- a/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.test.ts +++ b/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.test.ts @@ -1,3 +1,9 @@ +import { + onAuthStateChanged, + onIdTokenChanged, + setPersistence +} from 'firebase/auth' + import { render, screen, waitFor } from '@testing-library/vue' import userEvent from '@testing-library/user-event' import { beforeEach, describe, expect, it, vi } from 'vitest' @@ -6,6 +12,14 @@ import { createI18n } from 'vue-i18n' import enMessages from '@/locales/en/main.json' with { type: 'json' } +import { useTeamWorkspaceStore } from '@/platform/workspace/stores/teamWorkspaceStore' +import { + clearCheckoutJourney, + getActiveCheckoutJourney, + resolveCheckoutJourney +} from '@/platform/workspace/utils/checkoutJourney' +import { useAuthStore } from '@/stores/authStore' + import { WorkspaceApiError } from '@/platform/workspace/api/workspaceApi' import type { CreateTopupResponse } from '@/platform/workspace/api/workspaceApi' @@ -19,6 +33,8 @@ const mockReportError = vi.hoisted(() => vi.fn()) vi.mock('@/platform/telemetry/reportError', () => ({ reportError: mockReportError })) + +vi.mock(import('firebase/auth'), { spy: true }) const mockTopup = vi.fn<(amountCents: number) => Promise>() const mockStartOperation = vi.fn() @@ -36,6 +52,7 @@ const mockToastAdd = vi.fn() const mockCloseDialog = vi.fn() const mockTrackTopUpPurchase = vi.fn() const mockTrackBillingEvent = vi.fn() +const mockTrackCheckoutJourneyEvent = vi.hoisted(() => vi.fn()) const mockCanTopUp = vi.hoisted(() => ({ ref: undefined as { value: boolean } | undefined })) @@ -125,10 +142,13 @@ vi.mock('@/stores/dialogStore', () => ({ vi.mock('@/platform/telemetry', () => ({ useTelemetry: () => ({ trackApiCreditTopupButtonPurchaseClicked: mockTrackTopUpPurchase, - trackBillingEvent: mockTrackBillingEvent + trackBillingEvent: mockTrackBillingEvent, + trackCheckoutJourneyEvent: mockTrackCheckoutJourneyEvent }) })) +vi.mock(import('firebase/auth'), { spy: true }) + const mockClearPendingTopup = vi.hoisted(() => vi.fn()) vi.mock('@/composables/billing/usePendingTopup', () => ({ usePendingTopup: () => ({ clearPendingTopup: mockClearPendingTopup }) @@ -215,6 +235,16 @@ async function clickAddCredits() { describe('TopUpCreditsDialogContentWorkspace', () => { beforeEach(() => { + vi.mocked(setPersistence).mockResolvedValue(undefined) + vi.mocked(onAuthStateChanged).mockReturnValue(vi.fn()) + vi.mocked(onIdTokenChanged).mockReturnValue(vi.fn()) + Object.assign(useAuthStore(), { userId: 'user-1' }) + Object.assign(useTeamWorkspaceStore(), { + activeWorkspaceId: 'workspace-1' + }) + mockTrackCheckoutJourneyEvent.mockClear() + sessionStorage.clear() + clearCheckoutJourney() mockDistributionTypes.isCloud = true setCanTopUp(true) setIsAddingCredits(false) @@ -250,6 +280,83 @@ describe('TopUpCreditsDialogContentWorkspace', () => { }) }) + it('enters a topup journey on mount and correlates the purchase', async () => { + mockTopup.mockResolvedValue(topupResponse('pending')) + + renderDialog() + await waitFor(() => + expect(mockTrackCheckoutJourneyEvent).toHaveBeenCalledWith( + expect.objectContaining({ phase: 'entered', entry_flow: 'topup' }) + ) + ) + + await clickAddCredits() + await userEvent.click(screen.getByRole('button', { name: 'Pay $50.00' })) + + await waitFor(() => + expect(mockTrackCheckoutJourneyEvent).toHaveBeenCalledWith( + expect.objectContaining({ + phase: 'operation_linked', + billing_op_id: 'op-1' + }) + ) + ) + const phases = mockTrackCheckoutJourneyEvent.mock.calls.map( + ([event]) => event.phase + ) + expect(phases.indexOf('submitted')).toBeLessThan( + phases.indexOf('operation_linked') + ) + expect(phases.filter((phase) => phase === 'entered')).toHaveLength(1) + + // One denominator: every phase of a top-up must carry the same journey. + const journeyIds = new Set( + mockTrackCheckoutJourneyEvent.mock.calls.map( + ([event]) => event.checkout_journey_id + ) + ) + expect(journeyIds.size).toBe(1) + }) + + it('does not correlate the operation to a journey replaced mid-request', async () => { + let resolveTopup: (value: CreateTopupResponse) => void = () => {} + mockTopup.mockReturnValue( + new Promise((resolve) => { + resolveTopup = resolve + }) + ) + + renderDialog() + await clickAddCredits() + await userEvent.click(screen.getByRole('button', { name: 'Pay $50.00' })) + await waitFor(() => + expect(mockTrackCheckoutJourneyEvent).toHaveBeenCalledWith( + expect.objectContaining({ phase: 'submitted' }) + ) + ) + + // A different journey takes the slot while the request is pending, so the + // response must not bind to whatever happens to be active when it lands. + clearCheckoutJourney() + const replacement = resolveCheckoutJourney({ + actorUid: 'user-1', + workspaceId: 'workspace-1', + entryFlow: 'initial_subscription', + entrySource: 'pricing', + assignment: { status: 'unavailable' } + }) + resolveTopup(topupResponse('completed')) + await waitFor(() => expect(mockFetchBalance).toHaveBeenCalled()) + + const phases = mockTrackCheckoutJourneyEvent.mock.calls.map( + ([event]) => event.phase + ) + expect(phases).toContain('submitted') + expect(phases).not.toContain('operation_linked') + expect(replacement.status).toBe('active') + expect(getActiveCheckoutJourney()?.billing_op_id).toBeUndefined() + }) + it('reports failure telemetry when topup resolves with no response', async () => { mockTopup.mockResolvedValue(undefined) diff --git a/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.vue b/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.vue index ef3a8aa83fd..82d11f14f96 100644 --- a/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.vue +++ b/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.vue @@ -286,7 +286,7 @@