From a62a575b4312725e247d87a864b9f16e002dd411 Mon Sep 17 00:00:00 2001 From: Luke Mino-Altherr Date: Tue, 15 Sep 2026 14:28:43 +0000 Subject: [PATCH] [backport core/1.53] 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: no try/cleanup restructure here, so the journey clear sits before the success telemetry instead. - TopUpCreditsDialogContentWorkspace.vue: this branch names the polling computed isPolling, not isAddingCredits. - Provider event sets: this branch types the Set as TelemetryEventName, so the checkout names are spread into that typed set rather than a Set. - TopUpCreditsDialogContentWorkspace.test / TelemetryRegistry.test: only the journey additions were applied onto this branch's own mocks, plus a firebase/auth spy so useAuthStore() does not reach real Firebase. - Dropped FetchTimeoutMetadata and BootstrapCompleteMetadata, which the conflict regions carried in from main-only features. --- ...eckout-journey-instrumentation-contract.md | 172 +++++++ docs/adr/README.md | 57 ++- src/locales/en/main.json | 1 + .../telemetry/TelemetryRegistry.test.ts | 28 +- src/platform/telemetry/TelemetryRegistry.ts | 5 + .../telemetry/checkoutJourneyEvent.test.ts | 128 +++++ .../cloud/DatadogRumTelemetryProvider.ts | 10 + .../cloud/MixpanelTelemetryProvider.ts | 13 +- .../cloud/PostHogTelemetryProvider.ts | 18 +- 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, 2383 insertions(+), 81 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 c2961ed8600..74b521ae4b5 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -8,34 +8,35 @@ An Architecture Decision Record captures an important technical decision made al ## ADR Index -| ADR | Title | Status | Date | -| --------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | ---------- | -| [0001](0001-merge-litegraph-into-frontend.md) | Merge LiteGraph.js into ComfyUI Frontend | Accepted | 2025-08-05 | -| [0002](0002-monorepo-conversion.md) | Restructure as a Monorepo | Accepted | 2025-08-25 | -| [0003](0003-crdt-based-layout-system.md) | Centralized Layout Management with CRDT | Proposed | 2025-08-27 | -| [0004](0004-fork-primevue-ui-library.md) | Fork PrimeVue UI Library | Rejected | 2025-08-27 | -| [0005](0005-remove-importmap-for-vue-extensions.md) | Remove Import Map for Vue Extensions | Accepted | 2025-12-13 | -| [0006](0006-primitive-node-copy-paste-lifecycle.md) | PrimitiveNode Copy/Paste Lifecycle | Proposed | 2026-02-22 | -| [0007](0007-node-execution-output-passthrough-schema.md) | NodeExecutionOutput Passthrough Schema | Accepted | 2026-03-11 | -| [0008](0008-entity-component-system.md) | Entity Component System | Proposed | 2026-03-23 | -| [0009](0009-subgraph-promoted-widgets-use-linked-inputs.md) | Subgraph Promoted Widgets Use Linked Inputs | Proposed | 2026-05-05 | -| [0010](0010-remove-nx-orchestration.md) | Remove Nx Orchestration | Accepted | 2026-05-19 | -| [0011](0011-derived-credential-lifecycle.md) | Derived Credential Lifecycle for Cloud Auth | Proposed | 2026-07-09 | -| [0012](0012-cloud-release-notes-use-comfyui-version.md) | Cloud Release Notes Use the ComfyUI Version | Accepted | 2026-07-13 | -| [0013](0013-telemetry-service-selection.md) | Telemetry Service Selection | Accepted | 2026-07-28 | -| [0014](0014-billing-telemetry-attempt-correlation-and-workspace-scoping.md) | Billing Telemetry Attempt Correlation and Workspace Scoping | Proposed | 2026-07-28 | -| [0015](0015-adopt-fallow.md) | Adopt Fallow | Proposed | 2026-06-29 | -| [0016](0016-entity-registration-collision-and-recovery-boundaries.md) | Entity Registration Collision and Recovery Boundaries | Proposed | 2026-08-24 | -| [0017](0017-id-based-slot-records-are-the-slot-destination.md) | ID-Based Slot Records Own Slot State | Accepted | 2026-08-24 | -| [0018](0018-node-id-reminting-at-the-merge-boundary.md) | Node-ID Reminting at the Merge Boundary | Proposed | 2026-08-25 | -| [0019](0019-unified-recoverable-diagnostics.md) | Unified Recoverable Diagnostics | Proposed | 2026-08-25 | -| [0020](0020-bound-renderer-reactivity.md) | Bound Renderer Reactivity | Proposed | 2026-08-26 | -| [0021](0021-classify-and-coalesce-canvas-invalidation.md) | Classify and Coalesce Canvas Invalidation | Proposed | 2026-08-26 | -| [0022](0022-performance-measurement-and-ci-policy.md) | Performance Measurement and CI Policy | Proposed | 2026-08-26 | -| [0023](0023-widget-entities-and-legacy-behavior-boundary.md) | Widget Entities and Legacy Behavior Boundary | Proposed | 2026-08-26 | -| [0024](0024-in-app-agent-offscreen-graphs.md) | Graph Activation and Document Objects for In-App Agent Targets | Proposed | 2026-08-28 | -| [0025](0025-in-app-agent-crdt-follower-and-distribution.md) | In-App Agent CRDT Follower and Distribution-Resolved Boundaries | Proposed | 2026-08-21 | -| [0027](0027-defer-promoted-widget-registration-to-onadded.md) | Defer Promoted-Widget Registration to `onAdded()` | Accepted | 2026-09-01 | +| ADR | Title | Status | Date | +| ------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------- | ---------- | +| [0001](0001-merge-litegraph-into-frontend.md) | Merge LiteGraph.js into ComfyUI Frontend | Accepted | 2025-08-05 | +| [0002](0002-monorepo-conversion.md) | Restructure as a Monorepo | Accepted | 2025-08-25 | +| [0003](0003-crdt-based-layout-system.md) | Centralized Layout Management with CRDT | Proposed | 2025-08-27 | +| [0004](0004-fork-primevue-ui-library.md) | Fork PrimeVue UI Library | Rejected | 2025-08-27 | +| [0005](0005-remove-importmap-for-vue-extensions.md) | Remove Import Map for Vue Extensions | Accepted | 2025-12-13 | +| [0006](0006-primitive-node-copy-paste-lifecycle.md) | PrimitiveNode Copy/Paste Lifecycle | Proposed | 2026-02-22 | +| [0007](0007-node-execution-output-passthrough-schema.md) | NodeExecutionOutput Passthrough Schema | Accepted | 2026-03-11 | +| [0008](0008-entity-component-system.md) | Entity Component System | Proposed | 2026-03-23 | +| [0009](0009-subgraph-promoted-widgets-use-linked-inputs.md) | Subgraph Promoted Widgets Use Linked Inputs | Proposed | 2026-05-05 | +| [0010](0010-remove-nx-orchestration.md) | Remove Nx Orchestration | Accepted | 2026-05-19 | +| [0011](0011-derived-credential-lifecycle.md) | Derived Credential Lifecycle for Cloud Auth | Proposed | 2026-07-09 | +| [0012](0012-cloud-release-notes-use-comfyui-version.md) | Cloud Release Notes Use the ComfyUI Version | Accepted | 2026-07-13 | +| [0013](0013-telemetry-service-selection.md) | Telemetry Service Selection | Accepted | 2026-07-28 | +| [0014](0014-billing-telemetry-attempt-correlation-and-workspace-scoping.md) | Billing Telemetry Attempt Correlation and Workspace Scoping | Proposed | 2026-07-28 | +| [0015](0015-adopt-fallow.md) | Adopt Fallow | Proposed | 2026-06-29 | +| [0016](0016-entity-registration-collision-and-recovery-boundaries.md) | Entity Registration Collision and Recovery Boundaries | Proposed | 2026-08-24 | +| [0017](0017-id-based-slot-records-are-the-slot-destination.md) | ID-Based Slot Records Own Slot State | Accepted | 2026-08-24 | +| [0018](0018-node-id-reminting-at-the-merge-boundary.md) | Node-ID Reminting at the Merge Boundary | Proposed | 2026-08-25 | +| [0019](0019-unified-recoverable-diagnostics.md) | Unified Recoverable Diagnostics | Proposed | 2026-08-25 | +| [0020](0020-bound-renderer-reactivity.md) | Bound Renderer Reactivity | Proposed | 2026-08-26 | +| [0021](0021-classify-and-coalesce-canvas-invalidation.md) | Classify and Coalesce Canvas Invalidation | Proposed | 2026-08-26 | +| [0022](0022-performance-measurement-and-ci-policy.md) | Performance Measurement and CI Policy | Proposed | 2026-08-26 | +| [0023](0023-widget-entities-and-legacy-behavior-boundary.md) | Widget Entities and Legacy Behavior Boundary | Proposed | 2026-08-26 | +| [0024](0024-in-app-agent-offscreen-graphs.md) | Graph Activation and Document Objects for In-App Agent Targets | Proposed | 2026-08-28 | +| [0025](0025-in-app-agent-crdt-follower-and-distribution.md) | In-App Agent CRDT Follower and Distribution-Resolved Boundaries | Proposed | 2026-08-21 | +| [0027](0027-defer-promoted-widget-registration-to-onadded.md) | Defer Promoted-Widget Registration to `onAdded()` | Accepted | 2026-09-01 | +| [BILLING-CHECKOUT-0031](BILLING-CHECKOUT-0031-checkout-journey-instrumentation-contract.md) | Checkout Journey Instrumentation Contract | Proposed | 2026-09-09 | ## Creating a New ADR diff --git a/src/locales/en/main.json b/src/locales/en/main.json index a78c49a48e9..f8f6aa16b5f 100644 --- a/src/locales/en/main.json +++ b/src/locales/en/main.json @@ -3091,6 +3091,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 219a16ef2de..1d6447ef61c 100644 --- a/src/platform/telemetry/TelemetryRegistry.test.ts +++ b/src/platform/telemetry/TelemetryRegistry.test.ts @@ -1,7 +1,11 @@ import { describe, expect, it, vi } from 'vitest' import { TelemetryRegistry } from './TelemetryRegistry' -import type { BillingTelemetryEvent, TelemetryProvider } from './types' +import type { + BillingTelemetryEvent, + CheckoutJourneyTelemetryEvent, + TelemetryProvider +} from './types' describe('TelemetryRegistry', () => { it('dispatches trackSearchQuery to every registered provider', () => { @@ -199,6 +203,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 34e768fa510..9bffa28b87a 100644 --- a/src/platform/telemetry/TelemetryRegistry.ts +++ b/src/platform/telemetry/TelemetryRegistry.ts @@ -11,6 +11,7 @@ import type { AuthMetadata, BeginCheckoutMetadata, BillingTelemetryEvent, + CheckoutJourneyTelemetryEvent, DefaultViewSetMetadata, EnterLinearMetadata, ExecutionErrorMetadata, @@ -181,6 +182,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 58e3900fbcf..979697c87a4 100644 --- a/src/platform/telemetry/providers/cloud/DatadogRumTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/DatadogRumTelemetryProvider.ts @@ -3,6 +3,7 @@ import { datadogRum } from '@datadog/browser-rum' import type { BillingTelemetryEvent, + CheckoutJourneyTelemetryEvent, ExecutionOutcomeMetadata, ImageLoadFailureMetadata, TelemetryProvider, @@ -12,6 +13,8 @@ import type { import { getBillingTelemetryEventName, getBillingTelemetryEventPayload, + getCheckoutJourneyTelemetryEventName, + getCheckoutJourneyTelemetryEventPayload, TelemetryEvents } from '../../types' @@ -45,6 +48,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 ae2103f1a3f..6d6f2d36d08 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,9 +59,10 @@ const DEFAULT_DISABLED_EVENTS = [ TelemetryEvents.WORKFLOW_CREATED ] as const satisfies TelemetryEventName[] -const TELEMETRY_EVENT_SET = new Set( - Object.values(TelemetryEvents) as TelemetryEventName[] -) +const TELEMETRY_EVENT_SET = new Set([ + ...(Object.values(TelemetryEvents) as TelemetryEventName[]), + ...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 ec886f8d0e5..e9a2740e741 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,9 +99,10 @@ const DEFAULT_DISABLED_EVENTS = [ TelemetryEvents.WORKFLOW_CREATED ] as const satisfies TelemetryEventName[] -const TELEMETRY_EVENT_SET = new Set( - Object.values(TelemetryEvents) as TelemetryEventName[] -) +const TELEMETRY_EVENT_SET = new Set([ + ...(Object.values(TelemetryEvents) as TelemetryEventName[]), + ...Object.values(CHECKOUT_JOURNEY_EVENT_NAME_BY_PHASE) +]) interface QueuedEvent { eventName: TelemetryEventName @@ -483,6 +488,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 657dca663e0..40e5e5481c5 100644 --- a/src/platform/telemetry/types.ts +++ b/src/platform/telemetry/types.ts @@ -970,6 +970,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. @@ -1008,6 +1181,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 @@ -1273,7 +1449,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, @@ -1363,3 +1540,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 4029a370156..677902389d3 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() @@ -28,6 +44,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 })) @@ -116,10 +133,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 }) @@ -206,6 +226,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) @@ -241,6 +271,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 29e0515aa27..3aa1520e7bd 100644 --- a/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.vue +++ b/src/platform/workspace/components/TopUpCreditsDialogContentWorkspace.vue @@ -277,7 +277,7 @@