diff --git a/apps/billing-web/README.md b/apps/billing-web/README.md index 3e649ab72f0..2e07d3f79b7 100644 --- a/apps/billing-web/README.md +++ b/apps/billing-web/README.md @@ -98,6 +98,23 @@ every URL's query and fragment. Billing events go through from `@comfyorg/account-core/billing`, keeps only its allowlisted fields, stamps `billing_surface: 'billing_web'` and sends to both sinks. +### Entry, session and return events + +These are client journey events: they carry `outcome: 'pending'` and never +claim an operation result. Each is reported once per tab, not per navigation: +`trackOncePerTab` remembers what the tab has reported in `sessionStorage`, so a +route change, the sign-in redirect and a reload send nothing more. A tab that +refuses storage still reports once per page load. + +- `billing.web_entry.received`: an entry link was admitted. Carries `intent`, + `product`, `has_plan`, and the link's `payment_intent_source` and + `correlation_id` (the Cloud journey id) when it has them. +- `billing.web_entry.rejected`: the link could not be used; `error_code` is the + entry parser's code. +- `billing.web_entry.bounced`: billing web sent the customer back to the host + (`pricing_link`, `planless_checkout`) or replaced a checkout's `return_to` + (`return_target_rewritten`); `to` is the return target or `pricing_table`. + ## Commands Run these commands from the repository root: diff --git a/apps/billing-web/src/router.entryTelemetry.test.ts b/apps/billing-web/src/router.entryTelemetry.test.ts new file mode 100644 index 00000000000..bbe688a1985 --- /dev/null +++ b/apps/billing-web/src/router.entryTelemetry.test.ts @@ -0,0 +1,298 @@ +import { createMemoryHistory } from 'vue-router' + +import { createBillingRouter } from '@/router' +import type { BillingWebSessionPhase } from '@/router' +import { billingWebTelemetry } from '@/telemetry/billingWebTelemetry' + +const ENTRY_QUERY = 'product=comfyui&return_to=comfyui_workspace' + +function trackedEvents() { + const track = vi + .spyOn(billingWebTelemetry, 'trackBillingEvent') + .mockImplementation(() => undefined) + return () => track.mock.calls.map(([event]) => event) +} + +function arrivalRouter( + readPhase: () => BillingWebSessionPhase = () => 'authenticated' +) { + const leave = vi.fn() + const router = createBillingRouter( + createMemoryHistory(), + readPhase, + vi.fn(), + leave + ) + return { router, leave } +} + +beforeEach(() => { + sessionStorage.clear() +}) + +describe('the entry link a tab arrives with', () => { + it.for([ + { + name: 'a plain subscription link', + path: `/v1/subscription?${ENTRY_QUERY}`, + received: { + intent: 'subscription', + product: 'comfyui', + has_plan: false + } + }, + { + name: 'a checkout that names its plan, source and journey', + path: `/v1/checkout?${ENTRY_QUERY}&plan=creator_monthly&source=agent_paywall&correlation_id=journey-1`, + received: { + intent: 'checkout', + product: 'comfyui', + has_plan: true, + payment_intent_source: 'agent_paywall', + correlation_id: 'journey-1' + } + }, + { + name: 'a link carrying values billing must never report', + path: `/v1/top-up?${ENTRY_QUERY}&amount_cents=500&workspace=ws-team&team_credit_stop_id=stop-1&promo=SPRING`, + received: { + intent: 'top-up', + product: 'comfyui', + has_plan: false + } + } + ])('reports $name once it is received', async ({ path, received }) => { + const sent = trackedEvents() + const { router } = arrivalRouter() + + await router.push(path) + + expect(sent()).toStrictEqual([ + { + operation: 'web_entry', + stage: 'received', + outcome: 'pending', + ...received + } + ]) + }) + + it.for([ + { + code: 'UNSUPPORTED_VERSION', + path: `/v2/subscription?${ENTRY_QUERY}` + }, + { code: 'UNKNOWN_INTENT', path: `/v1/refunds?${ENTRY_QUERY}` }, + { + code: 'UNKNOWN_PRODUCT', + path: '/v1/subscription?product=spreadsheet&return_to=comfyui_workspace' + }, + { + code: 'UNKNOWN_RETURN_TARGET', + path: '/v1/subscription?product=comfyui&return_to=https://evil.test' + }, + { + code: 'INVALID_PLAN', + path: `/v1/subscription?${ENTRY_QUERY}&plan=creator/monthly` + }, + { + code: 'INVALID_CORRELATION_ID', + path: `/v1/subscription?${ENTRY_QUERY}&correlation_id=a b` + }, + { + code: 'INVALID_WORKSPACE_ID', + path: `/v1/subscription?${ENTRY_QUERY}&workspace=ws/1` + }, + { + code: 'INVALID_TEAM_CREDIT_STOP_ID', + path: `/v1/subscription?${ENTRY_QUERY}&team_credit_stop_id=stop/1` + }, + { + code: 'INVALID_AMOUNT', + path: `/v1/top-up?${ENTRY_QUERY}&amount_cents=lots` + } + ])('reports a link rejected as $code and nothing else', async (row) => { + const sent = trackedEvents() + const { router } = arrivalRouter() + + await router.push(row.path) + + expect(sent()).toStrictEqual([ + { + operation: 'web_entry', + stage: 'rejected', + outcome: 'pending', + error_code: row.code + } + ]) + }) + + it('reports a link whose way back cannot be resolved as rejected, not received', async () => { + const sent = trackedEvents() + const { router, leave } = arrivalRouter() + + await router.push('/v1/pricing?product=platform&return_to=platform_account') + + expect(leave).not.toHaveBeenCalled() + expect(sent()).toStrictEqual([ + { + operation: 'web_entry', + stage: 'rejected', + outcome: 'pending', + error_code: 'UNKNOWN_RETURN_TARGET' + } + ]) + }) +}) + +describe('an entry link billing web sends back to the host', () => { + it('reports a pricing link as bounced to the target it named, without receiving it', async () => { + const sent = trackedEvents() + const { router, leave } = arrivalRouter(() => 'signed-out') + + await router.push(`/v1/pricing?${ENTRY_QUERY}`) + + expect(leave).toHaveBeenCalledOnce() + expect(sent()).toStrictEqual([ + { + operation: 'web_entry', + stage: 'bounced', + outcome: 'pending', + reason: 'pricing_link', + to: 'comfyui_workspace' + } + ]) + }) + + it('reports a checkout that names no plan as bounced to the pricing table', async () => { + const sent = trackedEvents() + const { router, leave } = arrivalRouter(() => 'signed-out') + + await router.push(`/v1/checkout?${ENTRY_QUERY}`) + + expect(leave).toHaveBeenCalledOnce() + expect(sent()).toStrictEqual([ + { + operation: 'web_entry', + stage: 'bounced', + outcome: 'pending', + reason: 'planless_checkout', + to: 'pricing_table' + } + ]) + }) + + it.for([ + { + name: 'none at all', + path: '/v1/checkout?product=comfyui&plan=creator_monthly' + }, + { + name: 'one outside the registry', + path: '/v1/checkout?product=comfyui&return_to=https://evil.test&plan=creator_monthly' + } + ])( + 'reports a checkout with $name as received, then as rewritten to Plan & Credits', + async ({ path }) => { + const sent = trackedEvents() + const { router, leave } = arrivalRouter() + + await router.push(path) + + expect(leave).not.toHaveBeenCalled() + expect(sent()).toStrictEqual([ + { + operation: 'web_entry', + stage: 'received', + outcome: 'pending', + intent: 'checkout', + product: 'comfyui', + has_plan: true + }, + { + operation: 'web_entry', + stage: 'bounced', + outcome: 'pending', + reason: 'return_target_rewritten', + to: 'comfyui_credits' + } + ]) + } + ) +}) + +describe('once per tab entry', () => { + it('reports a received link once across route changes inside the tab', async () => { + const sent = trackedEvents() + const { router } = arrivalRouter() + + await router.push(`/v1/subscription?${ENTRY_QUERY}`) + await router.push(`/v1/invoices?${ENTRY_QUERY}`) + await router.push('/') + await router.push(`/v1/subscription?${ENTRY_QUERY}`) + + expect(sent().map((event) => event.stage)).toStrictEqual(['received']) + }) + + it('reports a received link once across the sign-in redirect it takes', async () => { + const sent = trackedEvents() + let phase: BillingWebSessionPhase = 'signed-out' + const { router } = arrivalRouter(() => phase) + + await router.push(`/v1/subscription?${ENTRY_QUERY}`) + expect(router.currentRoute.value.path).toBe('/sign-in') + phase = 'authenticated' + await router.replace(`/v1/subscription?${ENTRY_QUERY}`) + + expect(router.currentRoute.value.path).toBe('/v1/subscription') + expect(sent().map((event) => event.stage)).toStrictEqual(['received']) + }) + + it('reports a rejected link once across route changes inside the tab', async () => { + const sent = trackedEvents() + const { router } = arrivalRouter() + + await router.push(`/v1/refunds?${ENTRY_QUERY}`) + await router.push(`/v1/orders?${ENTRY_QUERY}`) + await router.push(`/v2/subscription?${ENTRY_QUERY}`) + + expect(sent().map((event) => event.stage)).toStrictEqual(['rejected']) + }) + + it('reports a link once across a reload of the tab', async () => { + const before = trackedEvents() + await arrivalRouter().router.push(`/v1/subscription?${ENTRY_QUERY}`) + expect(before()).toHaveLength(1) + + vi.resetModules() + const reloaded = await import('@/router') + const { billingWebTelemetry: reloadedTelemetry } = + await import('@/telemetry/billingWebTelemetry') + const afterReload = vi + .spyOn(reloadedTelemetry, 'trackBillingEvent') + .mockImplementation(() => undefined) + const router = reloaded.createBillingRouter( + createMemoryHistory(), + () => 'authenticated' + ) + await router.push(`/v1/subscription?${ENTRY_QUERY}`) + + expect(afterReload).not.toHaveBeenCalled() + }) + + it('still reports once per page load when the tab keeps no storage', async () => { + vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => { + throw new DOMException('denied', 'SecurityError') + }) + vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => { + throw new DOMException('denied', 'SecurityError') + }) + const sent = trackedEvents() + const { router } = arrivalRouter() + + await router.push(`/v1/subscription?${ENTRY_QUERY}`) + await router.push(`/v1/invoices?${ENTRY_QUERY}`) + + expect(sent().map((event) => event.stage)).toStrictEqual(['received']) + }) +}) diff --git a/apps/billing-web/src/router.planless.test.ts b/apps/billing-web/src/router.planless.test.ts index cfed20ba4e2..4b42d2f0a14 100644 --- a/apps/billing-web/src/router.planless.test.ts +++ b/apps/billing-web/src/router.planless.test.ts @@ -1,12 +1,18 @@ import { createMemoryHistory } from 'vue-router' +import type { WebEntryBounceTarget } from '@comfyorg/account-core/billing' import type { BillingEnvironment } from '@comfyorg/billing-contract' import type { BillingWebSessionPhase } from '@/router' const h = vi.hoisted(() => ({ livePhase: undefined as BillingWebSessionPhase | undefined, - bind: vi.fn<(workspaceId: string) => void>() + bind: vi.fn<(workspaceId: string) => void>(), + track: vi.fn<(event: unknown) => void>() +})) + +vi.mock(import('@/telemetry/billingWebTelemetry'), () => ({ + billingWebTelemetry: { trackBillingEvent: h.track } })) vi.mock(import('@/session/billingWebAuth'), () => ({ @@ -51,12 +57,21 @@ function flagAnswers(variant: string) { const PLANLESS = '/v1/checkout?product=comfyui&return_to=comfyui_workspace&workspace=ws-team' const PRICING_TABLE = 'https://testcloud.comfy.org/?pricing=1&workspace=ws-team' +const PLANLESS_BOUNCE = { + operation: 'web_entry', + stage: 'bounced', + outcome: 'pending', + reason: 'planless_checkout', + to: 'pricing_table' +} beforeEach(() => { + sessionStorage.clear() vi.resetModules() vi.stubGlobal('fetch', fetchMock) fetchMock.mockReset() h.bind.mockReset() + h.track.mockReset() }) async function openPlanless( @@ -126,6 +141,7 @@ describe('a checkout link that names no plan', () => { expect(router.currentRoute.value.path).not.toBe('/sign-in') expect(h.bind).not.toHaveBeenCalled() expect(fetchMock).not.toHaveBeenCalled() + expect(h.track).toHaveBeenCalledExactlyOnceWith(PLANLESS_BOUNCE) } ) @@ -140,6 +156,7 @@ describe('a checkout link that names no plan', () => { expect(leave).toHaveBeenCalledExactlyOnceWith(PRICING_TABLE) expect(router.currentRoute.value.path).not.toBe('/sign-in') expect(h.bind).not.toHaveBeenCalled() + expect(h.track).toHaveBeenCalledExactlyOnceWith(PLANLESS_BOUNCE) } ) @@ -158,6 +175,14 @@ describe('a checkout link that names no plan', () => { }) expect(entry.value?.plan).toBeUndefined() expect(error.value).toBeUndefined() + expect(h.track).toHaveBeenCalledExactlyOnceWith({ + operation: 'web_entry', + stage: 'received', + outcome: 'pending', + intent: 'checkout', + product: 'comfyui', + has_plan: false + }) }) }) @@ -169,52 +194,61 @@ describe('where a checkout link that names no plan sends the customer to pick on env: BillingEnvironment query: string destination: string + to: WebEntryBounceTarget }>([ { name: 'a cloud link to the pricing table', env: 'staging', query: 'product=comfyui&return_to=comfyui_workspace&workspace=ws-1', - destination: 'https://stagingcloud.comfy.org/?pricing=1&workspace=ws-1' + destination: 'https://stagingcloud.comfy.org/?pricing=1&workspace=ws-1', + to: 'pricing_table' }, { name: 'a cloud link without a return_to to the pricing table', env: 'production', query: 'product=comfyui', - destination: 'https://cloud.comfy.org/?pricing=1' + destination: 'https://cloud.comfy.org/?pricing=1', + to: 'pricing_table' }, { name: 'a cloud link that names a team to the Team tab', env: 'staging', query: 'product=comfyui&return_to=comfyui_workspace&workspace=ws-1&team_credit_stop_id=stop_700', - destination: 'https://stagingcloud.comfy.org/?pricing=team&workspace=ws-1' + destination: + 'https://stagingcloud.comfy.org/?pricing=team&workspace=ws-1', + to: 'pricing_table' }, { name: 'a platform link to its return_to', env: 'staging', query: 'product=platform&return_to=platform_account&workspace=ws-1', - destination: 'https://stagingplatform.comfy.org/?workspace=ws-1' + destination: 'https://stagingplatform.comfy.org/?workspace=ws-1', + to: 'platform_account' }, { name: 'a platform link to a return_to in another product', env: 'production', query: 'product=platform&return_to=comfyui_credits', - destination: 'https://cloud.comfy.org/?settings=plan-credits' + destination: 'https://cloud.comfy.org/?settings=plan-credits', + to: 'comfyui_credits' }, { name: 'a platform link with an unregistered return_to to the platform billing page', env: 'staging', query: 'product=platform&return_to=https://evil.test&workspace=ws-1', destination: - 'https://stagingplatform.comfy.org/profile/billing?workspace=ws-1' + 'https://stagingplatform.comfy.org/profile/billing?workspace=ws-1', + to: 'platform_billing' }, { name: 'a platform link without a return_to to the platform billing page', env: 'production', query: 'product=platform', - destination: 'https://platform.comfy.org/profile/billing' + destination: 'https://platform.comfy.org/profile/billing', + to: 'platform_billing' } - ])('sends $name', async ({ env, query, destination }) => { + ])('sends $name', async ({ env, query, destination, to }) => { vi.stubEnv('VITE_BILLING_ENV', env) const { router, leave } = await openPlanless( @@ -226,6 +260,10 @@ describe('where a checkout link that names no plan sends the customer to pick on expect(router.currentRoute.value.path).not.toBe('/sign-in') expect(h.bind).not.toHaveBeenCalled() expect(fetchMock).not.toHaveBeenCalled() + expect(h.track).toHaveBeenCalledExactlyOnceWith({ + ...PLANLESS_BOUNCE, + to + }) }) it('explains a platform link where this deployment has no platform to send it to', async () => { @@ -237,6 +275,12 @@ describe('where a checkout link that names no plan sends the customer to pick on expect(leave).not.toHaveBeenCalled() expect(entry.value).toBeUndefined() expect(error.value).toBe('UNKNOWN_RETURN_TARGET') + expect(h.track).toHaveBeenCalledExactlyOnceWith({ + operation: 'web_entry', + stage: 'rejected', + outcome: 'pending', + error_code: 'UNKNOWN_RETURN_TARGET' + }) }) }) @@ -279,6 +323,9 @@ describe('a planless checkout link the customer navigates away from', () => { intent: 'subscription', workspaceId: 'ws-other' }) + expect(h.track).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ stage: 'received', intent: 'subscription' }) + ) } ) }) diff --git a/apps/billing-web/src/router.ts b/apps/billing-web/src/router.ts index 8178dea1473..747ea151f87 100644 --- a/apps/billing-web/src/router.ts +++ b/apps/billing-web/src/router.ts @@ -2,6 +2,10 @@ import type { Component } from 'vue' import type { RouterHistory, RouteRecordRaw } from 'vue-router' import { createRouter, createWebHistory } from 'vue-router' +import type { + WebEntryBounceReason, + WebEntryBounceTarget +} from '@comfyorg/account-core/billing' import type { SessionSnapshot } from '@comfyorg/account-core/session' import type { BillingEntry, @@ -25,6 +29,11 @@ import { billingWebPhase, onBillingWebEntryWorkspace } from '@/session/billingWebAuth' +import { + reportEntryBounced, + reportEntryReceived, + reportEntryRejected +} from '@/telemetry/webEntryTelemetry' import BillingHomeView from '@/views/BillingHomeView.vue' import CheckoutRouteView from '@/views/CheckoutRouteView.vue' import EntryErrorView from '@/views/EntryErrorView.vue' @@ -92,6 +101,17 @@ function fullPageKeepsPlanless(): false | Promise { return awaitCheckoutUiVariant().then((variant) => variant === 'full_page') } +/** A link read from the URL, and whether its checkout `return_to` was replaced to read it. */ +interface Arrival { + readonly entry: BillingEntry + readonly returnRewritten: boolean +} + +interface HostDestination { + readonly href: string | undefined + readonly to: WebEntryBounceTarget +} + /** Echoes the host's own workspace back, leaving this tab's binding alone. */ function returnHref( target: ReturnTarget, @@ -135,16 +155,20 @@ function withCheckoutReturn(fullPath: string): string { * no pricing table, so its link goes back to its own `return_to`, or to * Platform's billing page when that is not one billing may follow. */ -function planPickerHref( +function planPicker( entry: BillingEntry, followsReturn: boolean -): string | undefined { +): HostDestination { if (entry.product !== 'platform') - return pricingTableUrl( - entry.teamCreditStopId === undefined ? 'default' : 'team', - entry.workspaceId - ) - return returnHref(followsReturn ? entry.returnTo : 'platform_billing', entry) + return { + href: pricingTableUrl( + entry.teamCreditStopId === undefined ? 'default' : 'team', + entry.workspaceId + ), + to: 'pricing_table' + } + const to = followsReturn ? entry.returnTo : 'platform_billing' + return { href: returnHref(to, entry), to } } function leaveForHost(href: string): void { @@ -179,19 +203,30 @@ export function createBillingRouter( let latestNavigation = 0 function recordUnknownReturn(): boolean { + reportEntryRejected('UNKNOWN_RETURN_TARGET') recordBillingEntry({ status: 'error', code: 'UNKNOWN_RETURN_TARGET' }) return true } /** False once the link has left this tab for its host. */ - function sendToHost(href: string | undefined): boolean { + function sendToHost( + { href, to }: HostDestination, + reason: WebEntryBounceReason + ): boolean { if (href === undefined) return recordUnknownReturn() + reportEntryBounced({ reason, to }) leave(href) return false } - function admitEntry(entry: BillingEntry): boolean { + function admitEntry({ entry, returnRewritten }: Arrival): boolean { recordBillingEntry({ status: 'ok', entry }) + reportEntryReceived(entry) + if (returnRewritten) + reportEntryBounced({ + reason: 'return_target_rewritten', + to: entry.returnTo + }) if (entry.workspaceId !== undefined) onEntryWorkspace(entry.workspaceId) return true } @@ -201,33 +236,41 @@ export function createBillingRouter( * an answer that arrives after a newer navigation started acts on nothing. */ function readPlanless( - entry: BillingEntry, - pickPlanAt: string | undefined + arrival: Arrival, + pickPlanAt: HostDestination ): boolean | Promise { const kept = fullPageKeepsPlanless() - if (kept === false) return sendToHost(pickPlanAt) + if (kept === false) return sendToHost(pickPlanAt, 'planless_checkout') const navigation = latestNavigation return kept.then((full) => { if (navigation !== latestNavigation) return false - return full ? admitEntry(entry) : sendToHost(pickPlanAt) + return full + ? admitEntry(arrival) + : sendToHost(pickPlanAt, 'planless_checkout') }) } function readEntry(fullPath: string): boolean | Promise { - const result = parseBillingEntry(withCheckoutReturn(fullPath)) + const readable = withCheckoutReturn(fullPath) + const result = parseBillingEntry(readable) if (result.status === 'error') { + reportEntryRejected(result.code) recordBillingEntry(result) return true } const { entry } = result if (entry.intent === 'pricing') - return sendToHost(returnHref(entry.returnTo, entry)) + return sendToHost( + { href: returnHref(entry.returnTo, entry), to: entry.returnTo }, + 'pricing_link' + ) + const arrival = { entry, returnRewritten: readable !== fullPath } if (isPlanlessCheckout(entry)) return readPlanless( - entry, - planPickerHref(entry, followsLinkReturn(linkUrl(fullPath))) + arrival, + planPicker(entry, followsLinkReturn(linkUrl(fullPath))) ) - return admitEntry(entry) + return admitEntry(arrival) } router.beforeEach(async (to) => { diff --git a/apps/billing-web/src/telemetry/trackOncePerTab.ts b/apps/billing-web/src/telemetry/trackOncePerTab.ts new file mode 100644 index 00000000000..4098b38abe7 --- /dev/null +++ b/apps/billing-web/src/telemetry/trackOncePerTab.ts @@ -0,0 +1,32 @@ +import type { BillingTelemetryEvent } from '@comfyorg/account-core/billing' +import { getBillingTelemetryEventName } from '@comfyorg/account-core/billing' + +import { billingWebTelemetry } from '@/telemetry/billingWebTelemetry' + +const STORAGE_KEY = 'comfy.billing-web.reported-events.v1' + +const reportedWithoutStorage = new Set() + +/** + * sessionStorage outlives a reload and ends with the tab, which is the span + * of one tab entry. A tab that refuses storage still reports once per page. + */ +function claimReport(name: string): boolean { + try { + const reported = sessionStorage.getItem(STORAGE_KEY)?.split(',') ?? [] + if (reported.includes(name)) return false + sessionStorage.setItem(STORAGE_KEY, [...reported, name].join(',')) + return true + } catch { + if (reportedWithoutStorage.has(name)) return false + reportedWithoutStorage.add(name) + return true + } +} + +/** Reports an event the first time this tab produces it, whatever it navigates through after. */ +export function trackOncePerTab(event: BillingTelemetryEvent): void { + if (claimReport(getBillingTelemetryEventName(event))) { + billingWebTelemetry.trackBillingEvent(event) + } +} diff --git a/apps/billing-web/src/telemetry/webEntryTelemetry.ts b/apps/billing-web/src/telemetry/webEntryTelemetry.ts new file mode 100644 index 00000000000..e86032808b3 --- /dev/null +++ b/apps/billing-web/src/telemetry/webEntryTelemetry.ts @@ -0,0 +1,51 @@ +import type { + WebEntryBounceReason, + WebEntryBounceTarget +} from '@comfyorg/account-core/billing' +import type { + BillingEntry, + BillingEntryErrorCode +} from '@comfyorg/billing-contract' + +import { trackOncePerTab } from '@/telemetry/trackOncePerTab' + +interface EntryBounce { + readonly reason: WebEntryBounceReason + readonly to: WebEntryBounceTarget +} + +export function reportEntryReceived(entry: BillingEntry): void { + trackOncePerTab({ + operation: 'web_entry', + stage: 'received', + outcome: 'pending', + intent: entry.intent, + product: entry.product, + has_plan: entry.plan !== undefined, + ...(entry.source === undefined + ? {} + : { payment_intent_source: entry.source }), + ...(entry.correlationId === undefined + ? {} + : { correlation_id: entry.correlationId }) + }) +} + +export function reportEntryRejected(code: BillingEntryErrorCode): void { + trackOncePerTab({ + operation: 'web_entry', + stage: 'rejected', + outcome: 'pending', + error_code: code + }) +} + +export function reportEntryBounced({ reason, to }: EntryBounce): void { + trackOncePerTab({ + operation: 'web_entry', + stage: 'bounced', + outcome: 'pending', + reason, + to + }) +} diff --git a/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts b/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts index 502ead9bde0..4bb7343071b 100644 --- a/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts +++ b/packages/account-core/src/core/billing/telemetry/billingTelemetryEvent.ts @@ -4,6 +4,7 @@ import type { BillingOperationBillingEvent } from './operationEvent.js' import type { ResubscribeBillingEvent } from './resubscribeEvent.js' import type { SubscriptionCheckoutBillingEvent } from './subscriptionCheckoutEvent.js' import type { TopupBillingEvent } from './topupEvent.js' +import type { WebEntryBillingEvent } from './webEntryEvent.js' import type { WebHandoffBillingEvent } from './webHandoffEvent.js' export type BillingSurface = 'cloud_app' | 'billing_web' @@ -20,6 +21,7 @@ export type BillingTelemetryEvent = { | ResubscribeBillingEvent | TopupBillingEvent | DowngradeToPersonalBillingEvent + | WebEntryBillingEvent | WebHandoffBillingEvent ) diff --git a/packages/account-core/src/core/billing/telemetry/index.ts b/packages/account-core/src/core/billing/telemetry/index.ts index fd4da23badd..8f44feb4818 100644 --- a/packages/account-core/src/core/billing/telemetry/index.ts +++ b/packages/account-core/src/core/billing/telemetry/index.ts @@ -17,6 +17,13 @@ export { getCloudAppBillingTelemetryEventPayload } from './payload.js' export { BILLING_TELEMETRY_EVENTS } from './eventNames.js' +export type { + WebEntryBillingEvent, + WebEntryBounceReason, + WebEntryBounceTarget, + WebEntryErrorCode, + WebEntryProduct +} from './webEntryEvent.js' export type { CheckoutAssignmentStatus, CheckoutEntryFlow, diff --git a/packages/account-core/src/core/billing/telemetry/payload.ts b/packages/account-core/src/core/billing/telemetry/payload.ts index bdf9c108599..ae2d4ab0548 100644 --- a/packages/account-core/src/core/billing/telemetry/payload.ts +++ b/packages/account-core/src/core/billing/telemetry/payload.ts @@ -16,12 +16,16 @@ export const BILLING_PAYLOAD_FIELD_HANDLING = { checkout_status: 'required', correlation_id: 'required', failure_category: 'required', + has_plan: 'required', intent: 'required', member_removal_count: 'required', member_removal_failures: 'required', operation_type: 'required', + product: 'required', + reason: 'required', result: 'required', source: 'required', + to: 'required', billing_client: 'optional', billing_op_id: 'optional', checkout_attempt_id: 'optional', diff --git a/packages/account-core/src/core/billing/telemetry/webEntryEvent.test.ts b/packages/account-core/src/core/billing/telemetry/webEntryEvent.test.ts new file mode 100644 index 00000000000..97cf5820525 --- /dev/null +++ b/packages/account-core/src/core/billing/telemetry/webEntryEvent.test.ts @@ -0,0 +1,62 @@ +import { describe, expect, it } from 'vitest' + +import type { BillingTelemetryEvent } from './billingTelemetryEvent.js' +import { getBillingTelemetryEventName } from './billingTelemetryEvent.js' +import { getBillingWebTelemetryEventPayload } from './payload.js' + +describe('a web entry event', () => { + it.for([ + { + event: { + operation: 'web_entry', + stage: 'received', + outcome: 'pending', + intent: 'checkout', + product: 'comfyui', + has_plan: true, + payment_intent_source: 'agent_paywall', + correlation_id: 'journey-1' + }, + name: 'billing.web_entry.received' + }, + { + event: { + operation: 'web_entry', + stage: 'received', + outcome: 'pending', + intent: 'subscription', + product: 'platform', + has_plan: false + }, + name: 'billing.web_entry.received' + }, + { + event: { + operation: 'web_entry', + stage: 'rejected', + outcome: 'pending', + error_code: 'INVALID_AMOUNT' + }, + name: 'billing.web_entry.rejected' + }, + { + event: { + operation: 'web_entry', + stage: 'bounced', + outcome: 'pending', + reason: 'planless_checkout', + to: 'pricing_table' + }, + name: 'billing.web_entry.bounced' + } + ] satisfies { event: BillingTelemetryEvent; name: string }[])( + 'is named $name and reports every field it carries', + ({ event, name }) => { + expect(getBillingTelemetryEventName(event)).toBe(name) + expect(getBillingWebTelemetryEventPayload(event)).toStrictEqual({ + ...event, + billing_surface: 'billing_web' + }) + } + ) +}) diff --git a/packages/account-core/src/core/billing/telemetry/webEntryEvent.ts b/packages/account-core/src/core/billing/telemetry/webEntryEvent.ts new file mode 100644 index 00000000000..9e652c7c647 --- /dev/null +++ b/packages/account-core/src/core/billing/telemetry/webEntryEvent.ts @@ -0,0 +1,51 @@ +import type { HostedBillingIntent, PaymentIntentSource } from './vocabulary.js' + +/** Mirrors `BillingProduct` in `@comfyorg/billing-contract`; a type test there fails when the two drift. */ +export type WebEntryProduct = 'comfyui' | 'platform' | 'workshop' | 'models' + +/** Mirrors `BillingEntryErrorCode` in `@comfyorg/billing-contract`; a type test there fails when the two drift. */ +export type WebEntryErrorCode = + | 'UNSUPPORTED_VERSION' + | 'UNKNOWN_INTENT' + | 'UNKNOWN_PRODUCT' + | 'UNKNOWN_RETURN_TARGET' + | 'INVALID_AMOUNT' + | 'INVALID_PLAN' + | 'INVALID_CORRELATION_ID' + | 'INVALID_WORKSPACE_ID' + | 'INVALID_TEAM_CREDIT_STOP_ID' + | 'INVALID_PROMOTION_CODE' + +export type WebEntryBounceReason = + | 'pricing_link' + | 'planless_checkout' + | 'return_target_rewritten' + +/** A `ReturnTarget` of `@comfyorg/billing-contract` (a type test there pins them) or the host's pricing table. */ +export type WebEntryBounceTarget = + | 'comfyui_workspace' + | 'comfyui_credits' + | 'platform_account' + | 'platform_billing' + | 'pricing_table' + +export type WebEntryBillingEvent = { + operation: 'web_entry' + outcome: 'pending' +} & ( + | { + stage: 'received' + intent: HostedBillingIntent + product: WebEntryProduct + has_plan: boolean + payment_intent_source?: PaymentIntentSource + /** The cloud journey id the entry link carries; links from other products carry none. */ + correlation_id?: string + } + | { stage: 'rejected'; error_code: WebEntryErrorCode } + | { + stage: 'bounced' + reason: WebEntryBounceReason + to: WebEntryBounceTarget + } +) diff --git a/packages/billing-contract/src/eventVocabulary.test.ts b/packages/billing-contract/src/eventVocabulary.test.ts index 8cc34bc1044..c734e823697 100644 --- a/packages/billing-contract/src/eventVocabulary.test.ts +++ b/packages/billing-contract/src/eventVocabulary.test.ts @@ -1,10 +1,19 @@ import type { HostedBillingIntent, - PaymentIntentSource + PaymentIntentSource, + WebEntryBounceTarget, + WebEntryErrorCode, + WebEntryProduct } from '@comfyorg/account-core/billing' import { describe, expectTypeOf, it } from 'vitest' -import type { BillingIntent, BillingSource } from './contract.js' +import type { + BillingIntent, + BillingProduct, + BillingSource +} from './contract.js' +import type { BillingEntryErrorCode } from './entryParser.js' +import type { ReturnTarget } from './returnTargets.js' describe('the billing event vocabulary', () => { it('names the same sources as the entry URL contract', () => { @@ -14,4 +23,18 @@ describe('the billing event vocabulary', () => { it('names the same intents as the entry URL contract', () => { expectTypeOf().toEqualTypeOf() }) + + it('names the same products as the entry URL contract', () => { + expectTypeOf().toEqualTypeOf() + }) + + it('names the same entry errors as the entry parser', () => { + expectTypeOf().toEqualTypeOf() + }) + + it('names the return targets a bounced entry can go to, and the pricing table', () => { + expectTypeOf().toEqualTypeOf< + ReturnTarget | 'pricing_table' + >() + }) })