Line data Source code
1 : /**
2 : * Telemetry Provider Interface
3 : *
4 : * CRITICAL: OSS Build Safety
5 : * This module is excluded from OSS builds via conditional compilation.
6 : * When DISTRIBUTION is unset (OSS builds), Vite's tree-shaking removes this code entirely,
7 : * ensuring the open source build contains no telemetry dependencies.
8 : *
9 : * To verify OSS builds are clean:
10 : * 1. `DISTRIBUTION= pnpm build` (OSS build)
11 : * 2. `grep -RinE --include='*.js' 'trackWorkflow|trackEvent|mixpanel' dist/` (should find nothing)
12 : * 3. Check dist/assets/*.js files contain no tracking code
13 : */
14 :
15 : import {
16 : AUTH_TELEMETRY_EVENT,
17 : SESSION_TELEMETRY_EVENT,
18 : SSO_TELEMETRY_EVENT
19 : } from '@comfyorg/account-core/telemetry'
20 : import type {
21 : BillingCycle,
22 : BillingTelemetryEvent,
23 : BillingTelemetryEventName,
24 : CheckoutJourneyTelemetryEvent,
25 : CheckoutJourneyTelemetryEventName,
26 : CheckoutJourneyTelemetryEventPayload,
27 : ResubscribeSource,
28 : BillingTierKey as TierKey,
29 : SubscriptionCheckoutTier,
30 : SubscriptionCheckoutType
31 : } from '@comfyorg/account-core/billing'
32 : import { BILLING_TELEMETRY_EVENTS } from '@comfyorg/account-core/billing'
33 : import type { BillingSource } from '@comfyorg/billing-contract'
34 : import type {
35 : AgentRunMode,
36 : SubscriptionTier,
37 : WorkspaceWithRole
38 : } from '@comfyorg/ingest-types'
39 : import type {
40 : AuthErrorMetadata,
41 : AuthFlowAction,
42 : AuthMethod,
43 : SsoTelemetryEvent,
44 : WebSessionTelemetryEvent
45 : } from '@comfyorg/account-core/telemetry'
46 : import type { SessionRefreshOutcome } from '@comfyorg/account-core/session'
47 :
48 : import type { AppMode } from '@comfyorg/graph-model/appMode'
49 :
50 : export type { AuthMethod }
51 :
52 : export type PaymentIntentSource = BillingSource
53 :
54 : /**
55 : * Authentication metadata for sign-up tracking
56 : */
57 : export interface AuthMetadata {
58 : method?: AuthMethod
59 : is_new_user?: boolean
60 : user_id?: string
61 : email?: string
62 : share_id?: string
63 : referrer_url?: string
64 : utm_source?: string
65 : utm_medium?: string
66 : utm_campaign?: string
67 : }
68 :
69 : export type { AuthErrorMetadata, AuthFlowAction }
70 :
71 : export type UnifiedAuthRetryFailureReason =
72 : | 'missing_bearer'
73 : | 'non_replayable_body'
74 : | 'remint_failed'
75 : | 'retry_rejected'
76 : | 'retry_request_failed'
77 : | 'token_unavailable'
78 :
79 : export interface UnifiedAuthRetryMetadata {
80 : transport: 'axios' | 'fetch' | 'ws'
81 : outcome: 'succeeded' | 'failed'
82 : final_status?: number
83 : failure_reason?: UnifiedAuthRetryFailureReason
84 : }
85 :
86 : export type UnifiedAuthRefreshOutcome = SessionRefreshOutcome
87 :
88 : /**
89 : * Outcome of one proactive unified Cloud-JWT refresh attempt. This lifecycle
90 : * drives session-cookie rotation, so a dead refresh chain breaks every
91 : * cookie-authenticated <img>/media load (FE-1595).
92 : */
93 : export interface UnifiedAuthRefreshMetadata {
94 : outcome: UnifiedAuthRefreshOutcome
95 : retry_count?: number
96 : }
97 :
98 : /**
99 : * One failed image preview. An `<img>` error event reports no status, so
100 : * everything past `source` is reconstructed by `describeImageLoadFailure()`:
101 : * `status` comes from re-requesting the URL once, the rest from the URL and the
102 : * page. Fields are optional because a probe that was capped, blocked or never
103 : * applicable must still produce a report — a missing field is a real outcome,
104 : * recorded in `probe_outcome` rather than guessed at.
105 : */
106 : export interface ImageLoadFailureMetadata {
107 : /**
108 : * Which surface failed. `node_image_preview` / `node_video_preview` are the
109 : * Vue node renderer; `canvas_node_image` / `canvas_node_video` are the
110 : * litegraph canvas previews. `Comfy.VueNodes.Enabled` defaults off, but on
111 : * for Cloud and Desktop users whose `Comfy.InstalledVersion` is 1.41.0 or
112 : * later, and App Builder turns it on.
113 : * Splitting on this is what keeps a rate measured on one renderer from being
114 : * read as the rate for everyone.
115 : * Under Vue nodes, an upload widget still loads its preview through the
116 : * canvas loader, so one broken upload can report under both a `canvas_*`
117 : * and a `node_*` source. Count per source rather than summing them.
118 : */
119 : source:
120 : | 'node_image_preview'
121 : | 'node_video_preview'
122 : | 'canvas_node_image'
123 : | 'canvas_node_video'
124 : /** Load attempts made before giving up, including the first. */
125 : attempts?: number
126 : /** True when the load timed out rather than erroring — a stall, not a rejection. */
127 : timed_out?: boolean
128 : /** HTTP status of the follow-up probe. Absent unless `probe_outcome` is `probed`. */
129 : status?: number
130 : probe_outcome?:
131 : | 'probed'
132 : | 'probe_failed'
133 : | 'probe_timeout'
134 : | 'probe_capped'
135 : | 'probe_blocked'
136 : | 'probe_redirected'
137 : | 'probe_abandoned'
138 : | 'invalid_src'
139 : /** `/api/view?type=` — separates an expired output from a missing upload. */
140 : resource_kind?: 'output' | 'input' | 'temp' | 'unspecified' | 'not_api_view'
141 : /** Filename shape only; never the filename, which is user-authored. */
142 : filename_kind?: 'content_hash' | 'template' | 'named' | 'none'
143 : /** Time since this page loaded. Auth-expiry failures skew old; 404s do not. */
144 : page_age_ms?: number
145 : online?: boolean
146 : same_origin?: boolean
147 : }
148 :
149 : /**
150 : * One row per session describing how long startup took and where the time
151 : * went. `total_ms` is measured from navigation start, so it is directly
152 : * comparable to what a user experiences and can be percentiled across sessions
153 : * without joining per-phase events.
154 : *
155 : * `outcome` keeps the bad sessions in the data:
156 : * - `completed` — the loading screen came down normally.
157 : * - `failed` — startup threw; the loading screen came down anyway.
158 : * - `timed_out` — startup was still running at the watchdog deadline. Emitted
159 : * *in addition to* whichever terminal row eventually follows, so a load that
160 : * hangs is counted even when it never finishes. `pending` names the phases
161 : * still open, which is where the session is stuck.
162 : *
163 : * Without the `timed_out` row the sessions users complain about are precisely
164 : * the ones absent from the data.
165 : */
166 : export interface BootstrapCompleteMetadata {
167 : total_ms: number
168 : outcome: 'completed' | 'failed' | 'timed_out'
169 : phase_count: number
170 : /** Wall-clock ms not covered by any recorded phase. */
171 : untraced_ms: number
172 : /** Wall-clock ms the tab was hidden during startup. */
173 : hidden_ms: number
174 : /**
175 : * Per-phase durations, keyed `<namespace>/<phase>` (e.g.
176 : * `bootstrap/object-info`). Nested phases intentionally overlap their
177 : * aggregate parent, so consumers must not sum entries across the map.
178 : */
179 : phases: Record<string, number>
180 : /** Phases still running when this row was emitted. Only set for `timed_out`. */
181 : pending?: string[]
182 : }
183 :
184 : /**
185 : * Survey field ids mapped to answers. Fields are backend-overridable, so all
186 : * are optional.
187 : */
188 : export interface SurveyResponses {
189 : // Current default schema (see defaultSurveySchema.ts)
190 : intent?: string | string[]
191 : intentOther?: string
192 : experience?: string
193 : focus?: string
194 : source?: string
195 : sourceOther?: string
196 : source_social?: string
197 : // Legacy fields — only emitted by older backend-supplied schemas, never by
198 : // the current default. Kept so historical responses still typecheck.
199 : familiarity?: string
200 : industry?: string
201 : useCase?: string
202 : making?: string[]
203 : role?: string
204 : teamSize?: string
205 : usage?: string
206 : }
207 :
208 : /** Stages inside the coachmark sequence, which is what `step_count` counts. */
209 : export type OnboardingTourStepStage =
210 : | 'not_started'
211 : | 'started'
212 : | 'step_shown'
213 : | 'completed'
214 : | 'skipped'
215 :
216 : /** The nudge follows the tour, so it has no step to report. */
217 : export type OnboardingTourNudgeStage =
218 : | 'nudge_shown'
219 : | 'explore_templates_clicked'
220 :
221 : export type OnboardingTourStage =
222 : | OnboardingTourStepStage
223 : | OnboardingTourNudgeStage
224 :
225 : export type OnboardingTourSkipReason =
226 : | 'user'
227 : | 'target_timeout'
228 : | 'trigger_lost'
229 : | 'postponed'
230 :
231 : export type OnboardingTourNotStartedReason =
232 : | 'already_seen'
233 : | 'no_roles'
234 : | 'run_only'
235 : | 'no_steps'
236 : | 'resolver_failed'
237 :
238 : /**
239 : * `step_number` is 1-based and matches the "Step N of M" indicator the user
240 : * sees, with `step_count` as M. Both `step_number` and `coach_id` are absent
241 : * for steps with no numbered spotlight (e.g. the landing). `skip_reason` is
242 : * present only on the `skipped` stage.
243 : */
244 : export interface OnboardingTourStepMetadata {
245 : tour: string
246 : step_count: number
247 : step_number?: number
248 : coach_id?: string
249 : skip_reason?: OnboardingTourSkipReason
250 : not_started_reason?: OnboardingTourNotStartedReason
251 : }
252 :
253 : /** The nudge is post-tour, so it reports no step and no count. */
254 : export interface OnboardingTourNudgeMetadata {
255 : tour: string
256 : /**
257 : * Whether the tour was walked to the end. Without it `nudge_shown` and
258 : * `explore_templates_clicked` cannot be split by how the tour ended, so a
259 : * conversion from a completed tour and one from a tour that never started
260 : * land in the same bucket.
261 : */
262 : tour_completed?: boolean
263 : }
264 :
265 : export type OnboardingTourMetadata =
266 : | OnboardingTourStepMetadata
267 : | OnboardingTourNudgeMetadata
268 :
269 : export type InAppSurveyStage = 'shown' | 'sent' | 'dismissed'
270 :
271 : export interface InAppSurveyEvent {
272 : surveyId: string
273 : responses?: Record<string, string>
274 : properties?: Record<string, string>
275 : }
276 :
277 : export interface SurveyResponsesNormalized extends SurveyResponses {
278 : industry_normalized?: string
279 : industry_raw?: string
280 : useCase_normalized?: string
281 : useCase_raw?: string
282 : }
283 :
284 : type AuthRail = 'web_session' | 'token'
285 :
286 : /**
287 : * The selected workspace and the auth rail its requests ride on. The RUM
288 : * global context and the Run-gate events carry it, so a blocked run or a
289 : * failure can be split by the workspace it was scoped to.
290 : */
291 : export interface WorkspaceTelemetryContext {
292 : workspace_id: string
293 : workspace_type: WorkspaceWithRole['type']
294 : workspace_role: WorkspaceWithRole['role']
295 : workspace_tier: SubscriptionTier | null
296 : auth_rail: AuthRail
297 : }
298 :
299 : /** A billing read for the selected workspace that the server resolved for another. */
300 : export interface WorkspaceScopeMismatchMetadata extends WorkspaceTelemetryContext {
301 : resolved_workspace_id: string
302 : resolved_workspace_type: WorkspaceWithRole['type'] | 'unknown'
303 : }
304 :
305 : /**
306 : * Run button tracking properties
307 : */
308 : export interface RunButtonProperties extends Partial<WorkspaceTelemetryContext> {
309 : subscribe_to_run: boolean
310 : workflow_type: 'template' | 'custom'
311 : workflow_name: string
312 : custom_node_count: number
313 : total_node_count: number
314 : subgraph_count: number
315 : has_api_nodes: boolean
316 : api_node_names: string[]
317 : has_toolkit_nodes: boolean
318 : toolkit_node_names: string[]
319 : trigger_source?: ExecutionTriggerSource
320 : view_mode: AppMode
321 : is_app_mode: boolean
322 : dock_state: ActionbarDockState
323 : /** Whether the agent panel was open when the run was submitted. */
324 : agent_panel_open: boolean
325 : }
326 :
327 : /**
328 : * Execution context for workflow tracking
329 : */
330 : export interface ExecutionContext {
331 : is_template: boolean
332 : workflow_name?: string
333 : // Template metadata (only present when is_template = true)
334 : template_source?: string
335 : template_category?: string
336 : template_tags?: string[]
337 : template_models?: string[]
338 : template_use_case?: string
339 : template_license?: string
340 : // Node composition metrics
341 : custom_node_count: number
342 : api_node_count: number
343 : subgraph_count: number
344 : total_node_count: number
345 : has_api_nodes: boolean
346 : api_node_names: string[]
347 : has_toolkit_nodes: boolean
348 : toolkit_node_names: string[]
349 : toolkit_node_count: number
350 : trigger_source?: ExecutionTriggerSource
351 : }
352 :
353 : /**
354 : * Execution error metadata
355 : */
356 : export interface ExecutionErrorMetadata {
357 : jobId: string
358 : nodeId?: string
359 : nodeType?: string
360 : error?: string
361 : }
362 :
363 : export interface WorkflowExecutionContext {
364 : workflow_type: 'template' | 'custom'
365 : view_mode: AppMode
366 : execution_scope: 'full' | 'partial'
367 : total_node_count: number
368 : executable_node_count: number
369 : custom_node_count: number
370 : api_node_count: number
371 : subgraph_count: number
372 : }
373 :
374 : export interface WorkflowQueueIntent {
375 : trigger_source?: ExecutionTriggerSource
376 : }
377 :
378 : export interface WorkflowExecutionIntent {
379 : trigger_source: ExecutionTriggerSource
380 : }
381 :
382 : export type WorkflowExecutionFailureReason =
383 : | 'prompt_build_failed'
384 : | 'submission_rejected'
385 : | 'submission_failed'
386 : | 'execution_failed'
387 : | 'execution_interrupted'
388 :
389 : interface ExecutionOutcomeBaseMetadata extends WorkflowExecutionIntent {
390 : startTime: number
391 : submissionAcceptedAt?: number
392 : executionStartedAt?: number
393 : endTime: number
394 : workflowContext?: WorkflowExecutionContext
395 : }
396 :
397 : export type ExecutionOutcomeMetadata = ExecutionOutcomeBaseMetadata &
398 : (
399 : | {
400 : success: true
401 : failureReason: ''
402 : }
403 : | {
404 : success: false
405 : failureReason: WorkflowExecutionFailureReason
406 : }
407 : )
408 :
409 : /**
410 : * Execution success metadata
411 : */
412 : export interface ExecutionSuccessMetadata {
413 : jobId: string
414 : }
415 :
416 : export interface SharedWorkflowRunMetadata {
417 : job_id: string
418 : share_id: string
419 : view_mode: AppMode
420 : is_app_mode: boolean
421 : }
422 :
423 : export type ActionbarDockState = 'docked' | 'floating'
424 :
425 : /**
426 : * Template metadata for workflow tracking
427 : */
428 : export interface TemplateMetadata {
429 : workflow_name: string
430 : template_source?: string
431 : template_category?: string
432 : template_tags?: string[]
433 : template_models?: string[]
434 : template_use_case?: string
435 : template_license?: string
436 : }
437 :
438 : /**
439 : * Credit topup metadata
440 : */
441 : export interface CreditTopupMetadata {
442 : credit_amount: number
443 : }
444 :
445 : /**
446 : * Workflow import metadata
447 : */
448 : export interface MissingNodePack {
449 : /**
450 : * Custom node pack identifier (cnrId / aux_id from node properties).
451 : * `'unknown'` when the workflow JSON has no pack hint for the node.
452 : */
453 : pack_id: string
454 : node_types: string[]
455 : }
456 :
457 : export interface WorkflowImportMetadata {
458 : missing_node_count: number
459 : missing_node_types: string[]
460 : /**
461 : * Missing nodes grouped by their custom node pack. Populated from the
462 : * `cnr_id` / `aux_id` baked into node properties — no network lookups.
463 : */
464 : missing_node_packs?: MissingNodePack[]
465 : /**
466 : * The source of the workflow open/import action
467 : */
468 : open_source?:
469 : | 'file_button'
470 : | 'file_drop'
471 : | 'template'
472 : | 'shared_url'
473 : | 'unknown'
474 : share_id?: string
475 : }
476 :
477 : export interface EnterLinearMetadata {
478 : source?: string
479 : }
480 :
481 : export type WorkflowLinkOutOfSyncReason =
482 : | 'no_sidebar_path'
483 : | 'name_ambiguous'
484 : | 'file_missing'
485 : | 'content_mismatch'
486 : | 'unknown'
487 :
488 : export type WorkflowLinkOpenedMetadata =
489 : | {
490 : outcome: 'opened' | 'not_found' | 'error'
491 : workspace_id: string | null
492 : }
493 : | {
494 : outcome: 'out_of_sync'
495 : reason: WorkflowLinkOutOfSyncReason
496 : workspace_id: string | null
497 : }
498 :
499 : export interface WorkflowSavedMetadata {
500 : is_app: boolean
501 : is_new: boolean
502 : }
503 :
504 : export interface DefaultViewSetMetadata {
505 : default_view: 'app' | 'graph'
506 : }
507 :
508 : type ShareFlowStep =
509 : | 'dialog_opened'
510 : | 'save_prompted'
511 : | 'link_created'
512 : | 'link_copied'
513 :
514 : export interface ShareFlowMetadata {
515 : step: ShareFlowStep
516 : source?: 'app_mode' | 'graph_mode'
517 : share_id?: string
518 : view_mode: AppMode
519 : is_app_mode: boolean
520 : }
521 :
522 : export interface ShareLinkOpenedMetadata {
523 : share_id: string
524 : is_authenticated: boolean
525 : view_mode: AppMode
526 : is_app_mode: boolean
527 : }
528 :
529 : /**
530 : * Workflow open metadata
531 : */
532 : /**
533 : * Enumerated sources for workflow open/import actions.
534 : */
535 : export type WorkflowOpenSource = NonNullable<
536 : WorkflowImportMetadata['open_source']
537 : >
538 :
539 : /**
540 : * Template library metadata
541 : */
542 : export interface TemplateLibraryMetadata {
543 : source: 'sidebar' | 'menu' | 'command' | 'appbuilder' | 'first_run_nudge'
544 : }
545 :
546 : /**
547 : * Template library closed metadata
548 : */
549 : export interface TemplateLibraryClosedMetadata {
550 : template_selected: boolean
551 : time_spent_seconds: number
552 : }
553 :
554 : /**
555 : * Page visibility metadata
556 : */
557 : export interface PageVisibilityMetadata {
558 : visibility_state: 'visible' | 'hidden'
559 : agent_panel_open: boolean
560 : }
561 :
562 : /**
563 : * Tab count metadata
564 : */
565 : export interface TabCountMetadata {
566 : tab_count: number
567 : }
568 :
569 : /**
570 : * Shell layout snapshot, sent once per session when the app is ready
571 : */
572 : export interface ShellLayoutMetadata {
573 : view_mode: AppMode
574 : is_app_mode: boolean
575 : dock_state: ActionbarDockState
576 : actionbar_position: string
577 : active_sidebar_tab: string | null
578 : right_side_panel_open: boolean
579 : bottom_panel_open: boolean
580 : open_workflow_tabs: number
581 : }
582 :
583 : /**
584 : * Settings change metadata
585 : */
586 : export interface SettingChangedMetadata {
587 : setting_id: string
588 : previous_value?: unknown
589 : new_value?: unknown
590 : }
591 :
592 : /**
593 : * Node search metadata
594 : */
595 : export interface NodeSearchMetadata {
596 : query: string
597 : }
598 :
599 : /**
600 : * Search query metadata. One event per debounced query change across
601 : * each search surface.
602 : */
603 : export type SearchSurface =
604 : | 'node_modal'
605 : | 'node_sidebar'
606 : | 'apps'
607 : | 'templates'
608 : | 'settings'
609 :
610 : export interface SearchQueryMetadata {
611 : surface: SearchSurface
612 : query: string
613 : query_length: number
614 : result_count: number
615 : has_results: boolean
616 : }
617 :
618 : /**
619 : * Node added metadata. `source` indicates how the user initiated the add.
620 : * Bulk additions during workflow load are excluded — workflow_imported
621 : * already covers that.
622 : */
623 : export type NodeAddSource =
624 : | 'sidebar_drag'
625 : | 'asset_browser'
626 : | 'search_modal'
627 : | 'paste'
628 : | 'programmatic'
629 : | 'unknown'
630 :
631 : export interface NodeAddedMetadata {
632 : node_type: string
633 : source: NodeAddSource
634 : }
635 :
636 : /**
637 : * Node search result selection metadata
638 : */
639 : export interface NodeSearchResultMetadata {
640 : node_type: string
641 : last_query: string
642 : }
643 :
644 : /**
645 : * Template filter tracking metadata
646 : */
647 : export interface TemplateFilterMetadata {
648 : search_query?: string
649 : selected_models: string[]
650 : selected_use_cases: string[]
651 : selected_runs_on: string[]
652 : sort_by:
653 : | 'relevance'
654 : | 'default'
655 : | 'recommended'
656 : | 'popular'
657 : | 'alphabetical'
658 : | 'newest'
659 : | 'vram-low-to-high'
660 : | 'model-size-low-to-high'
661 : filtered_count: number
662 : total_count: number
663 : }
664 :
665 : /**
666 : * UI button click tracking metadata
667 : */
668 : export interface UiButtonClickMetadata {
669 : button_id: string
670 : element_group: string
671 : }
672 :
673 : /**
674 : * In-App Agent message rating metadata (PM-98). `vote` is null when the user retracts a
675 : * prior thumb, which the eval pipeline records as a retraction rather than dropping.
676 : */
677 : export interface AgentMessageFeedbackMetadata extends Record<string, unknown> {
678 : message_id: string
679 : turn_id: string
680 : vote: 'up' | 'down' | null
681 : workflow_id: string | null
682 : }
683 :
684 : export type AgentPanelCloseSource =
685 : | 'close_button'
686 : | 'workflow_switch'
687 : | 'topbar_button'
688 : | 'pagehide'
689 : export interface AgentPanelOpenedMetadata extends Record<string, unknown> {
690 : source:
691 : | 'restored'
692 : | 'topbar_button'
693 : | 'automatic_consent'
694 : | 'activation'
695 : | 'error_context'
696 : | 'cloud_button'
697 : }
698 : export type AgentConsentNotOfferedReason =
699 : | 'first_run_screen'
700 : | 'tour_active'
701 : | 'dialog_open'
702 : | 'boot_undecided'
703 : | 'storage_unavailable'
704 : export interface AgentConsentNotOfferedMetadata extends Record<
705 : string,
706 : unknown
707 : > {
708 : reason: AgentConsentNotOfferedReason
709 : }
710 : /**
711 : * Why an automatic consent offer ended without making the offer or naming a
712 : * surface that holds it. Query by `exit`; see the Agent README.
713 : */
714 : export type AgentConsentOfferExit =
715 : /** The stored consent read has not settled, so consent is unknown. */
716 : | 'consent_unresolved'
717 : /** The stored consent read rejected. */
718 : | 'consent_read_failed'
719 : /** Consent is already stored for this scope, so no card is needed. */
720 : | 'consent_already_accepted'
721 : /** Another offer attempt for this page load has not finished. */
722 : | 'offer_in_flight'
723 : /** The card has already been on screen for this scope this page load. */
724 : | 'card_already_seen'
725 : /** This launch is past the panel's automatic-open launches. */
726 : | 'activation_window_complete'
727 : /** The first-run startup probe rejected. */
728 : | 'startup_probe_failed'
729 : /**
730 : * The consent scope moved while it was being resolved - a different account,
731 : * a workspace transition, or a switch that started - so the read that would
732 : * have decided whether to ask was never made. `request` stage only.
733 : */
734 : | 'scope_changed_before_read'
735 : /**
736 : * Resolving the consent scope raised. The account or the workspace went away
737 : * between the offer decision and the request. `request` stage only.
738 : */
739 : | 'scope_probe_failed'
740 : /**
741 : * The consent scope moved while the stored-consent read was in flight, so the
742 : * answer that came back belonged to a scope that is no longer current.
743 : * `request` stage only.
744 : */
745 : | 'scope_changed_after_read'
746 : /**
747 : * The card was asked for and the dialog closed before it rendered, so there
748 : * is no `agent_consent_shown` and no outcome to record against one. `request`
749 : * stage only.
750 : */
751 : | 'card_closed_before_mount'
752 : /**
753 : * Which link in the offer chain exited. The same condition is checked at more
754 : * than one of these - the pair (`exit`, `stage`) is what identifies a single
755 : * exit in the code, so neither property is readable on its own.
756 : */
757 : export type AgentConsentOfferStage =
758 : /** `loadConsentIfEligible` - before the consent read, or on its result. */
759 : | 'load'
760 : /** Waiting on the first-run startup decision. */
761 : | 'startup'
762 : /** `offerConsentUnprompted` - the offer attempt itself. */
763 : | 'offer'
764 : /** The consent request itself, after the chain has decided to ask. */
765 : | 'request'
766 : export interface AgentConsentOfferExitedMetadata extends Record<
767 : string,
768 : unknown
769 : > {
770 : exit: AgentConsentOfferExit
771 : stage: AgentConsentOfferStage
772 : /**
773 : * Whether a hold was armed at the moment of the exit, i.e. whether this page
774 : * load still has a queued retry. False on an owed-and-not-made exit means the
775 : * offer is gone for this page load with nothing scheduled to bring it back.
776 : *
777 : * Two qualifications, both from the `request` stage. It is **structurally
778 : * false** there: the offer drops the hold immediately before requesting, and
779 : * the only thing that re-arms it is the `canShow` hook, which runs after
780 : * every `request` exit. And the hold is not the only wake-up - `withConsent`
781 : * settling re-drives the chain when the identity changed - so on the two
782 : * `scope_changed_*` exits a retry does happen, by a mechanism this property
783 : * does not describe.
784 : */
785 : retry_armed: boolean
786 : /**
787 : * Which surface asked. Set **only** at the `request` stage, which is the one
788 : * stage reachable from the topbar button as well as the automatic offer;
789 : * every other stage is inside `offerConsentUnprompted` and automatic by
790 : * construction. A query about automatic offers must therefore either restrict
791 : * to `stage != 'request'` or filter `trigger = 'first_load'` - counting the
792 : * `request` stage unsplit mixes a user-initiated click into the automatic
793 : * denominator.
794 : */
795 : trigger?: AgentConsentTrigger
796 : }
797 : export type AgentOnboardingNotShownMetadata =
798 : | { reason: 'app_mode' | 'tour_active' | 'dialog_open' }
799 : | { reason: 'target_missing'; step: number }
800 : export type AgentSendGate = 'composer' | 'consent' | 'coach'
801 : export type AgentComposerDropReason =
802 : | 'cannot_submit'
803 : | 'submission_pending'
804 : | 'no_target'
805 : | 'empty'
806 : | 'attachment_uploading'
807 : /**
808 : * The session refused a submitted send: `send_busy` while another is in
809 : * flight, `target_unavailable` when its workflow target changed or has no canvas.
810 : */
811 : export type AgentSessionRefusalReason = 'send_busy' | 'target_unavailable'
812 : /** `not_completed`: the consent flow ended without accept, decline or dismiss. */
813 : export type AgentConsentDropReason =
814 : | 'declined'
815 : | 'dismissed'
816 : | 'not_completed'
817 : | 'panel_closed'
818 : export type AgentCoachReleaseReason =
819 : | 'finished'
820 : | 'skipped'
821 : | 'elsewhere'
822 : | 'stalled'
823 : | 'deferred_app_mode'
824 : | 'deferred_tour_active'
825 : | 'deferred_dialog_open'
826 : export type AgentCoachDropReason =
827 : | 'panel_closed'
828 : | 'consent_cleared'
829 : | 'identity_changed'
830 : type AgentSendGateOutcome =
831 : | {
832 : gate: 'composer'
833 : outcome: 'dropped'
834 : reason: AgentComposerDropReason
835 : client_message_id: null
836 : held_ms: null
837 : }
838 : | {
839 : gate: 'composer'
840 : outcome: 'dropped'
841 : reason: AgentSessionRefusalReason
842 : client_message_id: string | null
843 : held_ms: null
844 : }
845 : | {
846 : gate: 'consent' | 'coach'
847 : outcome: 'held'
848 : reason: null
849 : client_message_id: string
850 : held_ms: null
851 : }
852 : | {
853 : gate: 'consent'
854 : outcome: 'released'
855 : reason: 'accepted'
856 : client_message_id: string
857 : held_ms: number
858 : }
859 : | {
860 : gate: 'consent'
861 : outcome: 'dropped'
862 : reason: AgentConsentDropReason
863 : client_message_id: string
864 : held_ms: number
865 : }
866 : | {
867 : gate: 'coach'
868 : outcome: 'released'
869 : reason: AgentCoachReleaseReason
870 : client_message_id: string
871 : held_ms: number
872 : }
873 : | {
874 : gate: 'coach'
875 : outcome: 'dropped'
876 : reason: AgentCoachDropReason
877 : client_message_id: string
878 : held_ms: number
879 : }
880 : /**
881 : * A first-send gate outcome, joinable to `app:agent_message_sent` by
882 : * `client_message_id`.
883 : */
884 : export type AgentSendGatedMetadata = AgentSendGateOutcome & {
885 : thread_id: string | null
886 : /** Page load id, also sent on the agent feedback form. */
887 : client_session_id: string
888 : }
889 : export interface AgentPanelClosedMetadata extends Record<string, unknown> {
890 : source: AgentPanelCloseSource
891 : open_duration_ms: number | null
892 : }
893 : /** How far the open panel got before its content was drawn. */
894 : export type AgentPanelRenderStage =
895 : | 'dock_unresolved'
896 : | 'root_unresolved'
897 : | 'root_resolved_not_mounted'
898 : export interface AgentPanelRenderStalledMetadata extends Record<
899 : string,
900 : unknown
901 : > {
902 : stage: AgentPanelRenderStage
903 : }
904 : export interface AgentEntryButtonClickedMetadata extends Record<
905 : string,
906 : unknown
907 : > {
908 : resulting_state: 'opened' | 'closed'
909 : }
910 : export type AgentConsentTrigger =
911 : | 'first_load'
912 : | 'button_click'
913 : | 'first_message'
914 : export interface AgentConsentShownMetadata extends Record<string, unknown> {
915 : trigger: AgentConsentTrigger
916 : }
917 : /**
918 : * How a consent card that was on screen ended, plus the moment consent becomes
919 : * stored. It used to carry only the two deciding values, which left a card that
920 : * was shown and then went quiet covering three different endings at once - a
921 : * dismissal, an acceptance whose save did not stick, and a signed-out
922 : * acceptance whose sign-in was abandoned. Those are now named, and
923 : * `save_error_shown` separates giving up after a failed save from walking away.
924 : *
925 : * **Only `accepted` means consent is stored.** That was this event's whole
926 : * meaning before the other values existed, so any query that counted it as "a
927 : * decision that stuck" must now filter `decision = 'accepted'`, and one that
928 : * wants "the user answered" wants `decision in ('accepted', 'rejected')`.
929 : *
930 : * **The pairing with `agent_consent_shown`, exactly.** For a signed-in user -
931 : * the whole cloud population - every impression ends in exactly one of these,
932 : * so an impression with no outcome is a defect rather than a dismissal. In the
933 : * signed-out (local) flow the card is only the first half: it ends at
934 : * `accepted_pending_sign_in`, and `accepted` follows separately if the sign-in
935 : * and the real save land. So `accepted` is the one value that is not always the
936 : * card's own ending, which is how it keeps meaning "consent is stored".
937 : */
938 : export type AgentConsentDecision =
939 : /** Accepted, and the acceptance is durably stored. */
940 : | 'accepted'
941 : /** Declined on the card. Nothing is stored; the card can be offered again. */
942 : | 'rejected'
943 : /**
944 : * Closed without deciding - Escape, the overlay mask, or a programmatic close
945 : * such as navigation. Distinguishing this from `accept_not_persisted` is the
946 : * difference between the user walking away and the product failing them.
947 : */
948 : | 'dismissed'
949 : /**
950 : * Accepted, and the write did not stick without raising: the scope moved
951 : * mid-save or the workspace auth header was gone. The user believes they
952 : * consented and no consent exists.
953 : */
954 : | 'accept_not_persisted'
955 : /**
956 : * Accepted the card in the signed-out flow, where the card is only the first
957 : * half: a sign-in and a real save still have to land before consent exists,
958 : * and they report `accepted` themselves when they do. So this value with no
959 : * later `accepted` is an abandoned sign-in, which is the third case this
960 : * event could not previously name.
961 : */
962 : | 'accepted_pending_sign_in'
963 : export interface AgentConsentResolvedMetadata extends Record<string, unknown> {
964 : decision: AgentConsentDecision
965 : /**
966 : * Whether the card had already shown a save error when it reached this
967 : * outcome. A raised save leaves the card open and retryable, so its ending is
968 : * one of the values above rather than an outcome of its own - this is what
969 : * tells "dismissed after the save failed" from "dismissed without trying",
970 : * and marks an `accepted` that only landed on a retry.
971 : */
972 : save_error_shown: boolean
973 : }
974 : export type AgentOnboardingAction = 'next' | 'finish' | 'skip'
975 : export type AgentOnboardingCard = 'intro' | 'workflow' | 'history'
976 : /**
977 : * `step` is 1-based and matches the "Step N of M" indicator on the card.
978 : * `finish` marks completion, so the gap from `agent_onboarding_shown` is the
979 : * onboarding time. `card` is the stable identity to funnel on, since `step`
980 : * shifts when cards change. `total` is the tour length at the time of the event.
981 : */
982 : export interface AgentOnboardingStepMetadata extends Record<string, unknown> {
983 : step: number
984 : card: AgentOnboardingCard
985 : total: number
986 : action: AgentOnboardingAction
987 : }
988 : /**
989 : * Where the composer's text came from, by the affordance that put it there:
990 : * `suggestion` is an empty-state suggestion chip, `edited` is an earlier prompt
991 : * reopened through the conversation's edit action, and `typed` is everything
992 : * the user wrote themselves. Each send falls into exactly one — a chip the user
993 : * then reworded stays `suggestion`, because the chip is still what it came from.
994 : */
995 : export type AgentInputMethod =
996 : | 'typed'
997 : | 'suggestion'
998 : | 'edited'
999 : | 'error_context'
1000 : /**
1001 : * A starter prompt by the slot it occupies in the empty state, not by the text
1002 : * it shows: the copy is owned elsewhere and changes without the funnel
1003 : * changing. `unregistered` means the rendered set is larger than this union —
1004 : * a prompt was appended to either English distribution list without a matching
1005 : * entry in `starterPrompts.ts`, so that extra chip reads as an unmapped slot.
1006 : */
1007 : export type AgentStarterPromptId =
1008 : | 'slot_1'
1009 : | 'slot_2'
1010 : | 'slot_3'
1011 : | 'slot_4'
1012 : | 'slot_5'
1013 : | 'unregistered'
1014 : /**
1015 : * Where the free-use notice was placed, for the DES-1221 placement experiment.
1016 : *
1017 : * Deliberately the PostHog variant keys verbatim: the analysis joins this property to
1018 : * `$feature/agent-free-use-message-placement`, and a translation layer between
1019 : * the two is one more place for the arms to drift apart.
1020 : */
1021 2356 : export const AGENT_FREE_USE_PLACEMENTS = [
1022 : 'top-banner',
1023 : 'near-composer',
1024 : 'above-input',
1025 : 'inside-input'
1026 : ] as const
1027 : export type AgentFreeUsePlacement = (typeof AGENT_FREE_USE_PLACEMENTS)[number]
1028 : export type AgentFreeUseVariant = 'control' | AgentFreeUsePlacement
1029 : export interface AgentFreeUseExposureMetadata extends Record<string, unknown> {
1030 : placement: AgentFreeUseVariant
1031 : '$feature/agent-free-use-message-placement': AgentFreeUseVariant
1032 : }
1033 : export type AgentCreditUsageVariant = 'control' | 'treatment'
1034 : export interface AgentCreditUsageExposureMetadata extends Record<
1035 : string,
1036 : unknown
1037 : > {
1038 : variant: AgentCreditUsageVariant
1039 : '$feature/agent-credit-usage-summary': AgentCreditUsageVariant
1040 : }
1041 : /**
1042 : * Interactions with the notice itself. This event adds what the existing
1043 : * outcome events cannot say: whether the notice was actually on screen in its
1044 : * assigned arm, and what the viewer did with it.
1045 : */
1046 : export interface AgentFreeUseNoticeMetadata extends Record<string, unknown> {
1047 : action: 'shown' | 'dismissed' | 'learn_more_clicked'
1048 : placement: AgentFreeUsePlacement
1049 : }
1050 : export interface AgentCreditTransitionNoticeMetadata extends Record<
1051 : string,
1052 : unknown
1053 : > {
1054 : action: 'shown' | 'dismissed'
1055 : }
1056 : export interface AgentStarterPromptClickedMetadata extends Record<
1057 : string,
1058 : unknown
1059 : > {
1060 : prompt_id: AgentStarterPromptId
1061 : /** Slot position, so a reorder is visible rather than silently re-labelling. */
1062 : prompt_index: number
1063 : /** Size of the rendered set, so a set that grew or shrank is visible too. */
1064 : prompt_count: number
1065 : /**
1066 : * How many of that set the viewer could actually see. A panel narrower than
1067 : * 460px hides everything past the third chip with a container query, so this
1068 : * is 3 there and `prompt_count` elsewhere. Deliberately not folded into
1069 : * `prompt_count`: that field has to keep meaning "set size", and a reader
1070 : * cannot otherwise tell a shrunken set from a narrow panel.
1071 : */
1072 : visible_prompt_count: number
1073 : /**
1074 : * FNV-1a of the *displayed* text, 8 hex chars. Here so a copy change under a
1075 : * stable `prompt_id` is detectable — without it, a before/after read cannot
1076 : * tell a better slot from a rewritten one. Not the text itself (job `Don't`
1077 : * #3), and not reversible.
1078 : */
1079 : prompt_text_hash: string
1080 : /** The i18n locale that produced `prompt_text_hash`; two locales are two hashes of one prompt. */
1081 : locale: string
1082 : /**
1083 : * Minted per click. Carried onto every `app:agent_message_sent` attempt
1084 : * attributable to this click as `starter_prompt_click_id`. Retries mint a
1085 : * new `client_message_id` but retain this id, so click conversion must count
1086 : * distinct `starter_prompt_click_id` values rather than send events. A click
1087 : * with no matching send attempt never converted.
1088 : */
1089 : click_id: string
1090 : /**
1091 : * Whether the composer was empty when the chip was clicked. Inserting
1092 : * appends, so `false` means the submitted text is a mix of this prompt and
1093 : * something else — do not read those as a clean per-prompt outcome.
1094 : */
1095 : draft_was_empty: boolean
1096 : }
1097 : export interface AgentMessageSentMetadata extends Record<string, unknown> {
1098 : attachment_count: number
1099 : node_tag_count: number
1100 : /**
1101 : * The thread the message was posted into, `null` when it starts a new one —
1102 : * the backend mints that id in its acknowledgement, after this event fires.
1103 : */
1104 : thread_id: string | null
1105 : /** The targeted workflow's cloud id, `null` when the tab has none yet. */
1106 : workflow_id: string | null
1107 : /**
1108 : * Minted client-side, one per send attempt, so duplicate deliveries of this
1109 : * event collapse onto one message. A retry after a failed send is a new
1110 : * attempt and gets a new id.
1111 : *
1112 : * Also sent to the backend on the turn POST (`client_message_id`), which
1113 : * echoes it onto its own `agent_turn_started` event. That is what makes this
1114 : * the join key for the message → turn step: the backend's `turn_id` is minted
1115 : * after the POST arrives, so it can never appear on this event, and
1116 : * `thread_id` is `null` for the first message in a thread — precisely the
1117 : * sends that matter most to activation. An older server that ignores the field
1118 : * leaves the correlation unknown for that turn, which is a gap in the read and
1119 : * never a failed send.
1120 : */
1121 : client_message_id: string
1122 : input_method: AgentInputMethod
1123 : /**
1124 : * Which starter prompt supplied this draft, `null` when none did. The last
1125 : * chip clicked before the send wins, because inserting appends and the send
1126 : * is one message. Starter-prompt suggestions always carry a non-null ID and
1127 : * use `input_method: 'suggestion'`.
1128 : */
1129 : starter_prompt_id: AgentStarterPromptId | null
1130 : /** `click_id` of the `app:agent_starter_prompt_clicked` this send came from, `null` when typed. */
1131 : starter_prompt_click_id: string | null
1132 : }
1133 : export interface AgentNodeTaggedMetadata extends Record<string, unknown> {
1134 : source: 'mention_picker'
1135 : }
1136 : export interface AgentAttachButtonClickedMetadata extends Record<
1137 : string,
1138 : unknown
1139 : > {
1140 : method: 'menu' | 'drag_drop' | 'paste'
1141 : }
1142 : export interface AgentWorkflowAppliedMetadata extends Record<string, unknown> {
1143 : workflow_id: string
1144 : target: 'active_tab_switch' | 'active_tab_open'
1145 : }
1146 : export type AgentGraphProjectionStage =
1147 : | 'received_no_graph'
1148 : | 'applied'
1149 : | 'applied_deferred'
1150 : | 'discarded'
1151 : | 'reverted'
1152 :
1153 : /**
1154 : * Projection telemetry for agent and actorless frames and for reverted human
1155 : * batches. `op_id` is the join key; no actor, node, widget, workflow or prompt
1156 : * identifier is sent.
1157 : */
1158 : export interface AgentGraphProjectionMetadata extends Record<string, unknown> {
1159 : /**
1160 : * First non-empty op id of the frame, or of the rejected batch on
1161 : * `reverted`. Not necessarily creator-owned: `reverted` carries the first
1162 : * rejected HUMAN op id. `null` when the frame carried no op ids.
1163 : */
1164 : op_id: string | null
1165 : /** How many non-empty op ids it carried; `op_id` is the first of them. */
1166 : op_count: number
1167 : sequence: number
1168 : /**
1169 : * - `received_no_graph` — delivered, nothing applied yet (no graph bound).
1170 : * - `applied` — this frame applied. If earlier no-graph frames were still
1171 : * collected, the counts are the whole batch's, as on `applied_deferred`.
1172 : * - `applied_deferred` — a batch flush applied this earlier no-graph frame.
1173 : * The counts are the WHOLE batch's and are repeated across its frames, so
1174 : * they must not be attributed to this `op_id` alone.
1175 : * - `discarded` — the collected changes were thrown away without applying
1176 : * (own-echo discard, `doc_reset`, `schema_error`, scope disposal, follower
1177 : * replacement, rebind). All counts are zero: nothing reached the canvas, so
1178 : * the size of what was dropped is deliberately not reported under a count a
1179 : * dashboard would read as applied work.
1180 : * - `reverted` — the host rejected a human batch and the document state it
1181 : * claimed was put back on the canvas. The counts are that revert's.
1182 : */
1183 : stage: AgentGraphProjectionStage
1184 : added_count: number
1185 : /**
1186 : * Newly reported document deletes. Excludes entries already reported on an
1187 : * earlier pending frame, and replace-mode `removeAbsent` removals.
1188 : */
1189 : removed_count: number
1190 : /**
1191 : * Apply steps that threw, plus reported degradations that did not throw
1192 : * (an unresolved link, a subgraph definition that failed to register).
1193 : */
1194 : apply_failure_count: number
1195 : }
1196 : export type AgentStopMethod = 'button' | 'escape'
1197 : export interface AgentStopClickedMetadata extends Record<string, unknown> {
1198 : method: AgentStopMethod
1199 : turn_id: string
1200 : turn_elapsed_ms: number | null
1201 : }
1202 : export type AgentWorkflowBindSource =
1203 : | 'active_tab'
1204 : | 'selector_chip'
1205 : | 'minted'
1206 : | 'restored'
1207 : export interface AgentWorkflowBoundMetadata extends Record<string, unknown> {
1208 : thread_id: string
1209 : workflow_id: string
1210 : prev_workflow_id: string | null
1211 : bind_source: AgentWorkflowBindSource
1212 : }
1213 : export interface AgentRunApprovalShownMetadata extends Record<string, unknown> {
1214 : turn_id: string
1215 : workflow_id: string | null
1216 : }
1217 : export type AgentRunApprovalDecision = 'run' | 'cancel' | 'open_workflow'
1218 : export interface AgentRunApprovalResolvedMetadata extends Record<
1219 : string,
1220 : unknown
1221 : > {
1222 : decision: AgentRunApprovalDecision
1223 : time_to_decide_ms: number
1224 : }
1225 : export interface AgentRunModeChangedMetadata extends Record<string, unknown> {
1226 : from: AgentRunMode['mode']
1227 : to: AgentRunMode['mode']
1228 : }
1229 : export type AgentThreadStartSource =
1230 : | 'new_chat_button'
1231 : | 'first_open'
1232 : | 'history_select'
1233 : | 'history_delete'
1234 : export interface AgentThreadStartedMetadata extends Record<string, unknown> {
1235 : source: AgentThreadStartSource
1236 : }
1237 :
1238 : export type AgentErrorClass =
1239 : | 'request_failed'
1240 : | 'malformed_stream_event'
1241 : | 'cancel_failed'
1242 : | 'history_load_failed'
1243 : | 'ask_answer_failed'
1244 : | 'thread_list_load_failed'
1245 : | 'workflow_open_failed'
1246 :
1247 : export type AgentRequestPath =
1248 : | '/agent/threads'
1249 : | '/agent/threads/{threadId}/messages'
1250 : | '/agent/threads/{threadId}/messages/{messageId}/cancel'
1251 : | '/agent/threads/{threadId}/asks/{askId}/answer'
1252 : | '/agent/run-mode'
1253 : | '/workflows'
1254 : | '/upload/image'
1255 : | '/other'
1256 :
1257 : export type AgentRequestErrorName =
1258 : | 'AgentApiError'
1259 : | 'AgentResponseUnreadableError'
1260 : | 'ZodError'
1261 : | 'TimeoutError'
1262 : | 'AbortError'
1263 : | 'TypeError'
1264 : | 'other'
1265 :
1266 : export interface AgentErrorMetadata extends Record<string, unknown> {
1267 : error_class: AgentErrorClass
1268 : failure_stage: 'pre_acceptance' | 'post_acceptance'
1269 : retryable: boolean
1270 : turn_accepted: boolean
1271 : /** `none` is a failure the user was never shown. */
1272 : ui_treatment: 'inline_notice' | 'error_overlay' | 'toast' | 'none'
1273 : /**
1274 : * FE-3200: which request failed, how, and with what status.
1275 : *
1276 : * Absent on the failure classes that are not a single REST request — a
1277 : * malformed stream event has no status, and a stage that pre-dates this
1278 : * carrier emits nothing rather than a placeholder, so an absent value in
1279 : * the data means "not instrumented here", never "no status".
1280 : *
1281 : * `request_path` is a route template from a closed set and `request_error`
1282 : * an error identity from a closed set, both defined in
1283 : * `services/agent/agentRequestFailure.ts`. Neither can carry a thread id,
1284 : * a workflow id, a message, or a user.
1285 : */
1286 : request_path?: AgentRequestPath
1287 : request_status?: number
1288 : request_error?: AgentRequestErrorName
1289 : }
1290 :
1291 : /**
1292 : * Widget (input/parameter) favorite toggle tracking metadata.
1293 : * Used to measure discoverability of the right side panel favoriting feature.
1294 : */
1295 : export interface WidgetFavoriteToggledMetadata {
1296 : node_type: string
1297 : widget_name: string
1298 : widget_type: string
1299 : is_favorited: boolean
1300 : source: 'right_side_panel'
1301 : }
1302 :
1303 : /**
1304 : * Fired once per duplicate link dropped during workflow load, when the loser
1305 : * has a *different origin* from the survivor — i.e. a connection the file
1306 : * recorded is silently discarded, not merely a redundant same-origin copy.
1307 : * Cloud cannot see the accompanying `console.warn`, so this is the only
1308 : * signal that a load lost a link. The survivor follows an authoritative
1309 : * serialized reference: `input.link` for node inputs, `linkIds` priority
1310 : * order for subgraph boundaries, and document order otherwise. `target`
1311 : * names the contested input slot.
1312 : */
1313 : export interface LinkDedupDropMetadata {
1314 : droppedLinkId: number
1315 : survivorLinkId: number
1316 : target: string
1317 : }
1318 :
1319 : /**
1320 : * Fired once per node when its `widgets_values_named` restore path
1321 : * disagrees with what the legacy positional `widgets_values` restore
1322 : * would have produced. Diagnostic only — never reflects an actual
1323 : * mis-restored widget value, since the legacy side is a shadow
1324 : * computation that's never applied when the flag is on.
1325 : */
1326 : export interface NamedValuesShadowDiffMismatchMetadata {
1327 : node_type: string
1328 : pack_id?: string
1329 : mismatch_widget_count: number
1330 : checked_widget_count: number
1331 : had_named_field: boolean
1332 : has_on_serialize_hook: boolean
1333 : has_on_configure_hook: boolean
1334 : }
1335 :
1336 : /**
1337 : * Fired once per workflow load (sampled), aggregating the shadow-diff
1338 : * results across every node checked during that load.
1339 : */
1340 : export interface NamedValuesShadowDiffSummaryMetadata {
1341 : total_nodes_checked: number
1342 : nodes_with_mismatch: number
1343 : distinct_node_types: string[]
1344 : distinct_pack_ids: string[]
1345 : }
1346 :
1347 : /**
1348 : * Help center opened metadata
1349 : */
1350 : export interface HelpCenterOpenedMetadata {
1351 : source: 'menu' | 'topbar' | 'sidebar'
1352 : }
1353 :
1354 : /**
1355 : * Help resource clicked metadata
1356 : */
1357 : export interface HelpResourceClickedMetadata {
1358 : resource_type:
1359 : | 'docs'
1360 : | 'discord'
1361 : | 'github'
1362 : | 'help_feedback'
1363 : | 'manager'
1364 : | 'release_notes'
1365 : | 'status'
1366 : is_external: boolean
1367 : source:
1368 : | 'menu'
1369 : | 'help_center'
1370 : | 'error_dialog'
1371 : | 'credits_panel'
1372 : | 'subscription'
1373 : }
1374 :
1375 : /**
1376 : * Help center closed metadata
1377 : */
1378 : export interface HelpCenterClosedMetadata {
1379 : time_spent_seconds: number
1380 : }
1381 :
1382 : /**
1383 : * Workflow created metadata
1384 : */
1385 : export interface WorkflowCreatedMetadata {
1386 : workflow_type: 'blank' | 'default'
1387 : previous_workflow_had_nodes: boolean
1388 : }
1389 :
1390 : /**
1391 : * Page view metadata for route tracking
1392 : */
1393 : export interface PageViewMetadata {
1394 : path?: string
1395 : referrer?: string
1396 : title?: string
1397 : [key: string]: unknown
1398 : }
1399 :
1400 : export interface CheckoutAttributionMetadata {
1401 : ga_client_id?: string
1402 : ga_session_id?: string
1403 : ga_session_number?: string
1404 : im_ref?: string
1405 : rewardful_referral?: string
1406 : utm_source?: string
1407 : utm_medium?: string
1408 : utm_campaign?: string
1409 : utm_term?: string
1410 : utm_content?: string
1411 : gclid?: string
1412 : gbraid?: string
1413 : wbraid?: string
1414 : }
1415 :
1416 : export interface SubscriptionMetadata extends Partial<WorkspaceTelemetryContext> {
1417 : current_tier?: string
1418 : reason?: PaymentIntentSource
1419 : /** Server `error.type` when a refused run opened the paywall. */
1420 : refusal_type?: string
1421 : }
1422 :
1423 : export interface AddCreditsClickMetadata {
1424 : source:
1425 : | 'credits_panel'
1426 : | 'avatar_menu'
1427 : | 'settings_billing_panel'
1428 : | 'deep_link'
1429 : | 'agent_paywall'
1430 : }
1431 :
1432 : export type AgentPaywallReason =
1433 : | 'no_funds'
1434 : | 'subscription_inactive'
1435 : | 'member_cannot_pay'
1436 : | 'sales_managed'
1437 : | 'unknown'
1438 :
1439 : /**
1440 : * Which moment put the paywall in front of the user. The two are not
1441 : * interchangeable and collapsing them made the funnel unreadable:
1442 : *
1443 : * - `refused_send` is reactive — a turn POST came back 402/`no_funds`, so the
1444 : * user had to compose and send a message to discover they could not.
1445 : * - `credits_exhausted` is standing — the client already knows the workspace
1446 : * has no funds and says so beside the composer, without a refusal first.
1447 : *
1448 : * Reported because `app:agent_paywall_shown` alone cannot tell a rise in
1449 : * impressions caused by the standing surface from one caused by more users
1450 : * being refused. Without the split, "the paywall is showing more" is
1451 : * ambiguous between the fix working and the product getting worse.
1452 : */
1453 : export type AgentPaywallSurface = 'refused_send' | 'credits_exhausted'
1454 :
1455 : export interface AgentPaywallShownMetadata {
1456 : reason: AgentPaywallReason
1457 : surface: AgentPaywallSurface
1458 : }
1459 :
1460 : export type AgentPaywallCta = 'subscribe' | 'add_credits' | 'upgrade'
1461 :
1462 : export interface AgentPaywallCtaMetadata {
1463 : cta: AgentPaywallCta
1464 : /** The surface whose impression this click follows. */
1465 : surface: AgentPaywallSurface
1466 : }
1467 :
1468 : export interface SubscriptionCancellationMetadata {
1469 : current_tier?: string
1470 : cycle?: BillingCycle
1471 : /**
1472 : * `manage_subscription_button` opens the external billing portal, where
1473 : * cancellation is one of the few possible actions but not the only one —
1474 : * treat it as probable, not certain, cancel intent.
1475 : */
1476 : source?: 'cancel_plan_menu' | 'manage_subscription_button'
1477 : /** ISO date the subscription runs until if the cancel goes through. */
1478 : end_date?: string
1479 : /** Present only on the `failed` stage. */
1480 : error_message?: string
1481 : }
1482 :
1483 : export interface ResubscribeClickMetadata {
1484 : source: ResubscribeSource
1485 : /** Why the pricing dialog was opened, when the click came from one. */
1486 : payment_intent_source?: PaymentIntentSource
1487 : }
1488 :
1489 : export interface BeginCheckoutMetadata
1490 : extends Record<string, unknown>, CheckoutAttributionMetadata {
1491 : user_id: string
1492 : tier: SubscriptionCheckoutTier
1493 : cycle: BillingCycle
1494 : checkout_type: SubscriptionCheckoutType
1495 : checkout_attempt_id?: string
1496 : billing_op_id?: string
1497 : previous_tier?: TierKey
1498 : payment_intent_source?: PaymentIntentSource
1499 : }
1500 :
1501 : interface EcommerceItemMetadata {
1502 : item_name: string
1503 : item_category: string
1504 : item_variant?: string
1505 : price: number
1506 : quantity: number
1507 : }
1508 :
1509 : interface EcommerceMetadata {
1510 : currency: string
1511 : value: number
1512 : items: EcommerceItemMetadata[]
1513 : }
1514 :
1515 : export interface SubscriptionSuccessMetadata extends Record<string, unknown> {
1516 : user_id?: string
1517 : checkout_attempt_id?: string
1518 : tier?: SubscriptionCheckoutTier
1519 : cycle?: BillingCycle
1520 : checkout_type?: SubscriptionCheckoutType
1521 : previous_tier?: TierKey
1522 : payment_intent_source?: PaymentIntentSource
1523 : /** Present when the success is reported off the workspace billing-op poller. */
1524 : billing_op_id?: string
1525 : value?: number
1526 : currency?: string
1527 : ecommerce?: EcommerceMetadata
1528 : /**
1529 : * Set when the underlying checkout attempt was initiated from the resubscribe
1530 : * flow, so the pending-checkout recovery in `useSubscription.ts` can emit the
1531 : * canonical `billing.resubscribe.succeeded` terminal instead of leaving the
1532 : * legacy rail's `started`/`pending` resubscribe event unclosed forever.
1533 : */
1534 : operation?: 'resubscribe'
1535 : /** The click-time source, carried through so the terminal event can report it. */
1536 : resubscribe_source?: ResubscribeClickMetadata['source']
1537 : recovery_outcome?: 'late_success'
1538 : }
1539 :
1540 : export interface WorkspaceInviteMetadata extends Record<string, unknown> {
1541 : source: 'post_upgrade_success' | 'settings_members'
1542 : count: number
1543 : }
1544 :
1545 : export interface WorkspaceInviteFailedMetadata extends Record<string, unknown> {
1546 : source: WorkspaceInviteMetadata['source']
1547 : attempted_count: number
1548 : failed_count: number
1549 : }
1550 :
1551 : export interface FetchTimeoutMetadata {
1552 : route: string
1553 : method: string
1554 : timeout_ms: number
1555 : }
1556 :
1557 : /** How a request that got a retryable status (429/502/503/504) ended. */
1558 : export type FetchStatusRetryOutcome =
1559 : | 'recovered'
1560 : | 'exhausted'
1561 : | 'retry_after_too_long'
1562 : | 'timeout_budget'
1563 : | 'failed'
1564 :
1565 : /** One request that hit a retryable status in the shared status retry. */
1566 : export interface FetchStatusRetryMetadata {
1567 : transport: 'fetch' | 'axios'
1568 : method: string
1569 : host: string
1570 : /** Route group only, as in `app:fetch_timeout`, e.g. `/billing/:resource`. */
1571 : route: string
1572 : /** Requests sent, including the first. */
1573 : attempts: number
1574 : /** The last status the request got, if any. */
1575 : final_status?: number
1576 : outcome: FetchStatusRetryOutcome
1577 : }
1578 :
1579 : /**
1580 : * Telemetry provider interface for individual providers.
1581 : * All methods are optional - providers only implement what they need.
1582 : */
1583 : export interface TelemetryProvider {
1584 : trackFeatureFlagEvaluation?(key: string, value: unknown): void
1585 :
1586 : // Authentication flow events
1587 : trackSignupOpened?(): void
1588 : trackAuth?(metadata: AuthMetadata): void
1589 : trackAuthFailed?(metadata: AuthErrorMetadata): void
1590 : trackUnifiedAuthRetry?(metadata: UnifiedAuthRetryMetadata): void
1591 : trackUnifiedAuthRefresh?(metadata: UnifiedAuthRefreshMetadata): void
1592 : trackWebSessionEvent?(event: WebSessionTelemetryEvent): void
1593 : trackSsoEvent?(event: SsoTelemetryEvent): void
1594 : trackImageLoadFailed?(metadata: ImageLoadFailureMetadata): void
1595 : trackUserLoggedIn?(): void
1596 : trackBootstrapComplete?(metadata: BootstrapCompleteMetadata): void
1597 :
1598 : // Subscription flow events
1599 : trackSubscription?(
1600 : event: 'modal_opened' | 'subscribe_clicked',
1601 : metadata?: SubscriptionMetadata
1602 : ): void
1603 : trackBeginCheckout?(metadata: BeginCheckoutMetadata): void
1604 : trackMonthlySubscriptionSucceeded?(
1605 : metadata?: SubscriptionSuccessMetadata
1606 : ): void
1607 : trackMonthlySubscriptionCancelled?(): void
1608 : trackSubscriptionCancellation?(
1609 : event: 'flow_opened' | 'confirmed' | 'abandoned' | 'failed',
1610 : metadata?: SubscriptionCancellationMetadata
1611 : ): void
1612 : trackResubscribeClicked?(metadata: ResubscribeClickMetadata): void
1613 : trackAddApiCreditButtonClicked?(metadata?: AddCreditsClickMetadata): void
1614 : trackApiCreditTopupButtonPurchaseClicked?(amount: number): void
1615 : trackApiCreditTopupSucceeded?(): void
1616 : trackWorkspaceInviteSent?(metadata: WorkspaceInviteMetadata): void
1617 : trackWorkspaceInviteFailed?(metadata: WorkspaceInviteFailedMetadata): void
1618 : trackRunButton?(properties: RunButtonProperties): void
1619 :
1620 : trackBillingEvent?(event: BillingTelemetryEvent): void
1621 :
1622 : setWorkspaceContext?(context: WorkspaceTelemetryContext | undefined): void
1623 : trackWorkspaceScopeMismatch?(metadata: WorkspaceScopeMismatchMetadata): void
1624 :
1625 : /** Emit a checkout-journey lifecycle event to this provider. */
1626 : trackCheckoutJourneyEvent?(event: CheckoutJourneyTelemetryEvent): void
1627 :
1628 : trackAgentPaywallShown?(metadata: AgentPaywallShownMetadata): void
1629 : trackAgentPaywallCtaClicked?(metadata: AgentPaywallCtaMetadata): void
1630 : trackAgentCreditTransitionNotice?(
1631 : metadata: AgentCreditTransitionNoticeMetadata
1632 : ): void
1633 :
1634 : // Survey flow events
1635 : trackSurvey?(stage: 'opened' | 'submitted', responses?: SurveyResponses): void
1636 : trackInAppSurvey?(stage: InAppSurveyStage, event: InAppSurveyEvent): void
1637 :
1638 : // Onboarding coachmark tour events
1639 : trackOnboardingTour?(
1640 : stage: OnboardingTourStepStage,
1641 : metadata: OnboardingTourStepMetadata
1642 : ): void
1643 : trackOnboardingTour?(
1644 : stage: OnboardingTourNudgeStage,
1645 : metadata: OnboardingTourNudgeMetadata
1646 : ): void
1647 :
1648 : // Email verification events
1649 : trackEmailVerification?(stage: 'opened' | 'requested' | 'completed'): void
1650 :
1651 : // Template workflow events
1652 : trackTemplate?(metadata: TemplateMetadata): void
1653 : trackTemplateLibraryOpened?(metadata: TemplateLibraryMetadata): void
1654 : trackTemplateLibraryClosed?(metadata: TemplateLibraryClosedMetadata): void
1655 :
1656 : // Workflow management events
1657 : trackWorkflowImported?(metadata: WorkflowImportMetadata): void
1658 : trackWorkflowOpened?(metadata: WorkflowImportMetadata): void
1659 : trackWorkflowLinkOpened?(metadata: WorkflowLinkOpenedMetadata): void
1660 : trackWorkflowSaved?(metadata: WorkflowSavedMetadata): void
1661 : trackDefaultViewSet?(metadata: DefaultViewSetMetadata): void
1662 : trackEnterLinear?(metadata: EnterLinearMetadata): void
1663 : trackShareFlow?(metadata: ShareFlowMetadata): void
1664 : trackShareLinkOpened?(metadata: ShareLinkOpenedMetadata): void
1665 :
1666 : // Page visibility events
1667 : trackPageVisibilityChanged?(metadata: PageVisibilityMetadata): void
1668 :
1669 : // Tab tracking events
1670 : trackTabCount?(metadata: TabCountMetadata): void
1671 :
1672 : // Shell layout snapshot events
1673 : trackShellLayout?(metadata: ShellLayoutMetadata): void
1674 :
1675 : // Node search analytics events
1676 : trackNodeSearch?(metadata: NodeSearchMetadata): void
1677 : trackNodeSearchResultSelected?(metadata: NodeSearchResultMetadata): void
1678 :
1679 : // Search query analytics
1680 : trackSearchQuery?(metadata: SearchQueryMetadata): void
1681 :
1682 : // Node-added-to-canvas analytics
1683 : trackNodeAdded?(metadata: NodeAddedMetadata): void
1684 :
1685 : // Template filter tracking events
1686 : trackTemplateFilterChanged?(metadata: TemplateFilterMetadata): void
1687 :
1688 : // Help center events
1689 : trackHelpCenterOpened?(metadata: HelpCenterOpenedMetadata): void
1690 : trackHelpResourceClicked?(metadata: HelpResourceClickedMetadata): void
1691 : trackHelpCenterClosed?(metadata: HelpCenterClosedMetadata): void
1692 :
1693 : // Workflow creation events
1694 : trackWorkflowCreated?(metadata: WorkflowCreatedMetadata): void
1695 :
1696 : // Workflow execution events
1697 : trackWorkflowExecution?(): void
1698 : trackExecutionOutcome?(metadata: ExecutionOutcomeMetadata): void
1699 : trackExecutionError?(metadata: ExecutionErrorMetadata): void
1700 : trackExecutionSuccess?(metadata: ExecutionSuccessMetadata): void
1701 : trackSharedWorkflowRun?(metadata: SharedWorkflowRunMetadata): void
1702 :
1703 : // Settings events
1704 : trackSettingChanged?(metadata: SettingChangedMetadata): void
1705 :
1706 : // Generic UI button click events
1707 : trackUiButtonClicked?(metadata: UiButtonClickMetadata): void
1708 :
1709 : // In-App Agent message rating (PM-98)
1710 : trackAgentMessageFeedback?(metadata: AgentMessageFeedbackMetadata): void
1711 : trackAgentPanelOpened?(metadata: AgentPanelOpenedMetadata): void
1712 : trackAgentPanelClosed?(metadata: AgentPanelClosedMetadata): void
1713 : trackAgentPanelRenderStalled?(metadata: AgentPanelRenderStalledMetadata): void
1714 : trackAgentEntryButtonClicked?(metadata: AgentEntryButtonClickedMetadata): void
1715 : trackAgentCloseButtonClicked?(): void
1716 : trackAgentConsentShown?(metadata: AgentConsentShownMetadata): void
1717 : trackAgentConsentResolved?(metadata: AgentConsentResolvedMetadata): void
1718 : trackAgentOnboardingShown?(): void
1719 : trackAgentOnboardingStep?(metadata: AgentOnboardingStepMetadata): void
1720 : trackAgentMessageSent?(metadata: AgentMessageSentMetadata): void
1721 : trackAgentStarterPromptClicked?(
1722 : metadata: AgentStarterPromptClickedMetadata
1723 : ): void
1724 : trackAgentFreeUseNotice?(metadata: AgentFreeUseNoticeMetadata): void
1725 : trackAgentFreeUseExposure?(metadata: AgentFreeUseExposureMetadata): void
1726 : trackAgentCreditUsageExposure?(
1727 : metadata: AgentCreditUsageExposureMetadata
1728 : ): void
1729 : trackAgentNodeTagged?(metadata: AgentNodeTaggedMetadata): void
1730 : trackAgentAttachButtonClicked?(
1731 : metadata: AgentAttachButtonClickedMetadata
1732 : ): void
1733 : trackAgentWorkflowApplied?(metadata: AgentWorkflowAppliedMetadata): void
1734 : trackAgentGraphProjection?(metadata: AgentGraphProjectionMetadata): void
1735 : trackAgentError?(metadata: AgentErrorMetadata): void
1736 : trackAgentStopClicked?(metadata: AgentStopClickedMetadata): void
1737 : trackAgentWorkflowBound?(metadata: AgentWorkflowBoundMetadata): void
1738 : trackAgentRunApprovalShown?(metadata: AgentRunApprovalShownMetadata): void
1739 : trackAgentRunApprovalResolved?(
1740 : metadata: AgentRunApprovalResolvedMetadata
1741 : ): void
1742 : trackAgentRunModeChanged?(metadata: AgentRunModeChangedMetadata): void
1743 : trackAgentThreadStarted?(metadata: AgentThreadStartedMetadata): void
1744 : trackAgentConsentNotOffered?(metadata: AgentConsentNotOfferedMetadata): void
1745 : trackAgentConsentOfferExited?(metadata: AgentConsentOfferExitedMetadata): void
1746 : trackAgentOnboardingNotShown?(metadata: AgentOnboardingNotShownMetadata): void
1747 : trackAgentSendGated?(metadata: AgentSendGatedMetadata): void
1748 :
1749 : // Right side panel widget favorite events
1750 : trackWidgetFavoriteToggled?(metadata: WidgetFavoriteToggledMetadata): void
1751 :
1752 : // Named values shadow-diff diagnostics
1753 : trackNamedValuesShadowDiffMismatch?(
1754 : metadata: NamedValuesShadowDiffMismatchMetadata
1755 : ): void
1756 : trackNamedValuesShadowDiffSummary?(
1757 : metadata: NamedValuesShadowDiffSummaryMetadata
1758 : ): void
1759 :
1760 : // Link deduplication diagnostics
1761 : trackLinkDedupDrop?(metadata: LinkDedupDropMetadata): void
1762 :
1763 : // Page view tracking
1764 : trackPageView?(pageName: string, properties?: PageViewMetadata): void
1765 :
1766 : // Network error events
1767 : trackFetchTimeout?(metadata: FetchTimeoutMetadata): void
1768 : trackFetchStatusRetry?(metadata: FetchStatusRetryMetadata): void
1769 : }
1770 :
1771 : /**
1772 : * Telemetry dispatcher interface returned by useTelemetry().
1773 : * All methods are required - the registry implements all methods and dispatches
1774 : * to registered providers using optional chaining.
1775 : */
1776 : export type TelemetryDispatcher = Required<TelemetryProvider>
1777 :
1778 : /**
1779 : * Telemetry event constants
1780 : *
1781 : * Event naming conventions:
1782 : * - 'app:' prefix: UI/user interaction events
1783 : * - No prefix: Backend/system events (execution lifecycle)
1784 : */
1785 2356 : export const TelemetryEvents = {
1786 : // Authentication Flow
1787 : USER_SIGN_UP_OPENED: AUTH_TELEMETRY_EVENT.signUpOpened,
1788 : USER_AUTH_COMPLETED: AUTH_TELEMETRY_EVENT.authCompleted,
1789 : USER_AUTH_FAILED: AUTH_TELEMETRY_EVENT.authFailed,
1790 : USER_LOGGED_IN: 'app:user_logged_in',
1791 : UNIFIED_AUTH_RETRY_SUCCEEDED: 'auth.unified.request_retry.succeeded',
1792 : UNIFIED_AUTH_RETRY_FAILED: 'auth.unified.request_retry.failed',
1793 : UNIFIED_AUTH_REFRESH_SUCCEEDED: SESSION_TELEMETRY_EVENT.refreshSucceeded,
1794 : UNIFIED_AUTH_REFRESH_FAILED: SESSION_TELEMETRY_EVENT.refreshFailed,
1795 : SSO_REQUIRED_SHOWN: SSO_TELEMETRY_EVENT.requiredShown,
1796 : SSO_CONTINUE_CLICKED: SSO_TELEMETRY_EVENT.continueClicked,
1797 : SSO_SIGN_IN_FAILED: SSO_TELEMETRY_EVENT.signInFailed,
1798 : SSO_SIGN_IN_COMPLETED: SSO_TELEMETRY_EVENT.signInCompleted,
1799 : SSO_WORKSPACE_LANDED: SSO_TELEMETRY_EVENT.workspaceLanded,
1800 : IMAGE_LOAD_FAILED: 'app:image_load_failed',
1801 : BOOTSTRAP_COMPLETE: 'app:bootstrap_complete',
1802 : THEME_LOADED: 'app:theme_loaded',
1803 :
1804 : // Subscription Flow
1805 : RUN_BUTTON_CLICKED: 'app:run_button_click',
1806 : SUBSCRIPTION_REQUIRED_MODAL_OPENED: 'app:subscription_required_modal_opened',
1807 : SUBSCRIBE_NOW_BUTTON_CLICKED: 'app:subscribe_now_button_clicked',
1808 : MONTHLY_SUBSCRIPTION_SUCCEEDED: 'app:monthly_subscription_succeeded',
1809 : MONTHLY_SUBSCRIPTION_CANCELLED: 'app:monthly_subscription_cancelled',
1810 : SUBSCRIPTION_CANCEL_FLOW_OPENED: 'app:subscription_cancel_flow_opened',
1811 : SUBSCRIPTION_CANCEL_CONFIRMED: 'app:subscription_cancel_confirmed',
1812 : SUBSCRIPTION_CANCEL_ABANDONED: 'app:subscription_cancel_abandoned',
1813 : SUBSCRIPTION_CANCEL_FAILED: 'app:subscription_cancel_failed',
1814 : RESUBSCRIBE_BUTTON_CLICKED: 'app:resubscribe_button_clicked',
1815 : ADD_API_CREDIT_BUTTON_CLICKED: 'app:add_api_credit_button_clicked',
1816 : API_CREDIT_TOPUP_BUTTON_PURCHASE_CLICKED:
1817 : 'app:api_credit_topup_button_purchase_clicked',
1818 : API_CREDIT_TOPUP_SUCCEEDED: 'app:api_credit_topup_succeeded',
1819 : WORKSPACE_INVITE_SENT: 'app:workspace_invite_sent',
1820 : WORKSPACE_INVITE_FAILED: 'app:workspace_invite_failed',
1821 : BEGIN_CHECKOUT: 'begin_checkout',
1822 :
1823 : AGENT_PAYWALL_SHOWN: 'app:agent_paywall_shown',
1824 : AGENT_PAYWALL_CTA_CLICKED: 'app:agent_paywall_cta_clicked',
1825 :
1826 : // Canonical Billing Lifecycle
1827 : ...BILLING_TELEMETRY_EVENTS,
1828 :
1829 : // Onboarding Survey
1830 : USER_SURVEY_OPENED: 'app:user_survey_opened',
1831 : USER_SURVEY_SUBMITTED: 'app:user_survey_submitted',
1832 :
1833 : // PostHog API surveys rendered by the app
1834 : IN_APP_SURVEY_SHOWN: 'survey shown',
1835 : IN_APP_SURVEY_SENT: 'survey sent',
1836 : IN_APP_SURVEY_DISMISSED: 'survey dismissed',
1837 :
1838 : // Onboarding Coachmarks
1839 : ONBOARDING_TOUR_NOT_STARTED: 'app:onboarding_tour_not_started',
1840 : ONBOARDING_TOUR_STARTED: 'app:onboarding_tour_started',
1841 : ONBOARDING_TOUR_STEP_SHOWN: 'app:onboarding_tour_step_shown',
1842 : ONBOARDING_TOUR_COMPLETED: 'app:onboarding_tour_completed',
1843 : ONBOARDING_TOUR_SKIPPED: 'app:onboarding_tour_skipped',
1844 : ONBOARDING_TOUR_NUDGE_SHOWN: 'app:onboarding_tour_nudge_shown',
1845 : ONBOARDING_TOUR_EXPLORE_TEMPLATES_CLICKED:
1846 : 'app:onboarding_tour_explore_templates_clicked',
1847 :
1848 : // Email Verification
1849 : USER_EMAIL_VERIFY_OPENED: 'app:user_email_verify_opened',
1850 : USER_EMAIL_VERIFY_REQUESTED: 'app:user_email_verify_requested',
1851 : USER_EMAIL_VERIFY_COMPLETED: 'app:user_email_verify_completed',
1852 :
1853 : // Template Tracking
1854 : TEMPLATE_WORKFLOW_OPENED: 'app:template_workflow_opened',
1855 : TEMPLATE_LIBRARY_OPENED: 'app:template_library_opened',
1856 : TEMPLATE_LIBRARY_CLOSED: 'app:template_library_closed',
1857 :
1858 : // Workflow Management
1859 : WORKFLOW_IMPORTED: 'app:workflow_imported',
1860 : WORKFLOW_OPENED: 'app:workflow_opened',
1861 : WORKFLOW_LINK_OPENED: 'app:workflow_link_opened',
1862 : ENTER_LINEAR_MODE: 'app:app_mode_opened',
1863 : SHARE_FLOW: 'app:share_flow',
1864 : SHARE_LINK_OPENED: 'app:share_link_opened',
1865 :
1866 : // Page Visibility
1867 : PAGE_VISIBILITY_CHANGED: 'app:page_visibility_changed',
1868 :
1869 : // Tab Tracking
1870 : TAB_COUNT_TRACKING: 'app:tab_count_tracking',
1871 :
1872 : // Shell Layout
1873 : SHELL_LAYOUT: 'app:shell_layout',
1874 :
1875 : // Node Search Analytics
1876 : NODE_SEARCH: 'app:node_search',
1877 : NODE_SEARCH_RESULT_SELECTED: 'app:node_search_result_selected',
1878 : SEARCH_QUERY: 'app:search_query',
1879 : NODE_ADDED: 'app:node_added_to_workflow',
1880 :
1881 : // Template Filter Analytics
1882 : TEMPLATE_FILTER_CHANGED: 'app:template_filter_changed',
1883 :
1884 : // Settings
1885 : SETTING_CHANGED: 'app:setting_changed',
1886 :
1887 : // Help Center Analytics
1888 : HELP_CENTER_OPENED: 'app:help_center_opened',
1889 : HELP_RESOURCE_CLICKED: 'app:help_resource_clicked',
1890 : HELP_CENTER_CLOSED: 'app:help_center_closed',
1891 :
1892 : // Workflow Creation
1893 : WORKFLOW_CREATED: 'app:workflow_created',
1894 : WORKFLOW_SAVED: 'app:workflow_saved',
1895 : DEFAULT_VIEW_SET: 'app:default_view_set',
1896 :
1897 : // Execution Lifecycle
1898 : EXECUTION_START: 'execution_start',
1899 : EXECUTION_ERROR: 'execution_error',
1900 : EXECUTION_SUCCESS: 'execution_success',
1901 : SHARED_WORKFLOW_RUN: 'app:shared_workflow_run',
1902 : // Generic UI Button Click
1903 : UI_BUTTON_CLICKED: 'app:ui_button_clicked',
1904 :
1905 : // In-App Agent
1906 : AGENT_MESSAGE_FEEDBACK: 'app:agent_message_feedback',
1907 : AGENT_PANEL_OPENED: 'app:agent_panel_opened',
1908 : AGENT_PANEL_CLOSED: 'app:agent_panel_closed',
1909 : AGENT_PANEL_RENDER_STALLED: 'app:agent_panel_render_stalled',
1910 : AGENT_ENTRY_BUTTON_CLICKED: 'app:agent_entry_button_clicked',
1911 : AGENT_CLOSE_BUTTON_CLICKED: 'app:agent_close_button_clicked',
1912 : AGENT_CONSENT_SHOWN: 'app:agent_consent_shown',
1913 : AGENT_CONSENT_RESOLVED: 'app:agent_consent_resolved',
1914 : AGENT_ONBOARDING_SHOWN: 'app:agent_onboarding_shown',
1915 : AGENT_ONBOARDING_STEP: 'app:agent_onboarding_step',
1916 : AGENT_MESSAGE_SENT: 'app:agent_message_sent',
1917 : AGENT_STARTER_PROMPT_CLICKED: 'app:agent_starter_prompt_clicked',
1918 : AGENT_FREE_USE_NOTICE: 'app:agent_free_use_notice',
1919 : AGENT_FREE_USE_EXPOSURE: 'app:agent_free_use_exposure',
1920 : AGENT_CREDIT_USAGE_EXPOSURE: 'app:agent_credit_usage_exposure',
1921 : AGENT_CREDIT_TRANSITION_NOTICE: 'app:agent_credit_transition_notice',
1922 : AGENT_NODE_TAGGED: 'app:agent_node_tagged',
1923 : AGENT_ATTACH_BUTTON_CLICKED: 'app:agent_attach_button_clicked',
1924 : AGENT_WORKFLOW_APPLIED: 'app:agent_workflow_applied',
1925 : AGENT_GRAPH_PROJECTION: 'app:agent_graph_projection',
1926 : AGENT_ERROR: 'app:agent_error',
1927 : AGENT_STOP_CLICKED: 'app:agent_stop_clicked',
1928 : AGENT_WORKFLOW_BOUND: 'app:agent_workflow_bound',
1929 : AGENT_RUN_APPROVAL_SHOWN: 'app:agent_run_approval_shown',
1930 : AGENT_RUN_APPROVAL_RESOLVED: 'app:agent_run_approval_resolved',
1931 : AGENT_RUN_MODE_CHANGED: 'app:agent_run_mode_changed',
1932 : AGENT_THREAD_STARTED: 'app:agent_thread_started',
1933 : AGENT_CONSENT_NOT_OFFERED: 'app:agent_consent_not_offered',
1934 : AGENT_CONSENT_OFFER_EXITED: 'app:agent_consent_offer_exited',
1935 : AGENT_ONBOARDING_NOT_SHOWN: 'app:agent_onboarding_not_shown',
1936 : AGENT_SEND_GATED: 'app:agent_send_gated',
1937 :
1938 : // Right Side Panel Widget Favorites
1939 : WIDGET_FAVORITE_TOGGLED: 'app:widget_favorite_toggled',
1940 :
1941 : // Named Values Shadow Diff (Comfy.Workflow.NamedValuesRestore diagnostics)
1942 : NAMED_VALUES_SHADOW_DIFF_MISMATCH: 'app:named_values_shadow_diff_mismatch',
1943 : NAMED_VALUES_SHADOW_DIFF_SUMMARY: 'app:named_values_shadow_diff_summary',
1944 :
1945 : // Link deduplication diagnostics
1946 : LINK_DEDUP_DROP: 'app:link_dedup_drop',
1947 :
1948 : // Page View
1949 : PAGE_VIEW: 'app:page_view',
1950 :
1951 : // Network
1952 : FETCH_TIMEOUT: 'app:fetch_timeout',
1953 : FETCH_STATUS_RETRY: 'app:fetch_status_retry',
1954 :
1955 : WORKSPACE_SCOPE_MISMATCH: 'workspace_scope_mismatch'
1956 : } as const
1957 :
1958 : export type TelemetryEventName =
1959 : | (typeof TelemetryEvents)[keyof typeof TelemetryEvents]
1960 : | BillingTelemetryEventName
1961 : | CheckoutJourneyTelemetryEventName
1962 : | WebSessionTelemetryEvent['name']
1963 :
1964 : export const OnboardingTourEvents: Record<
1965 : OnboardingTourStage,
1966 : TelemetryEventName
1967 : > = {
1968 2356 : not_started: TelemetryEvents.ONBOARDING_TOUR_NOT_STARTED,
1969 : started: TelemetryEvents.ONBOARDING_TOUR_STARTED,
1970 : step_shown: TelemetryEvents.ONBOARDING_TOUR_STEP_SHOWN,
1971 : completed: TelemetryEvents.ONBOARDING_TOUR_COMPLETED,
1972 : skipped: TelemetryEvents.ONBOARDING_TOUR_SKIPPED,
1973 : nudge_shown: TelemetryEvents.ONBOARDING_TOUR_NUDGE_SHOWN,
1974 : explore_templates_clicked:
1975 : TelemetryEvents.ONBOARDING_TOUR_EXPLORE_TEMPLATES_CLICKED
1976 : }
1977 :
1978 2356 : export const CANCELLATION_STAGE_EVENTS = {
1979 : flow_opened: TelemetryEvents.SUBSCRIPTION_CANCEL_FLOW_OPENED,
1980 : confirmed: TelemetryEvents.SUBSCRIPTION_CANCEL_CONFIRMED,
1981 : abandoned: TelemetryEvents.SUBSCRIPTION_CANCEL_ABANDONED,
1982 : failed: TelemetryEvents.SUBSCRIPTION_CANCEL_FAILED
1983 : } as const
1984 :
1985 2356 : const executionTriggerSources = [
1986 : 'button',
1987 : 'keybinding',
1988 : 'legacy_ui',
1989 : 'unknown',
1990 : 'linear',
1991 : 'auto_queue'
1992 : ] as const
1993 :
1994 : export type ExecutionTriggerSource = (typeof executionTriggerSources)[number]
1995 :
1996 193 : export function normalizeExecutionTriggerSource(
1997 : value: unknown
1998 : ): ExecutionTriggerSource {
1999 193 : return (
2000 : executionTriggerSources.find((triggerSource) => triggerSource === value) ??
2001 : 'unknown'
2002 : )
2003 : }
2004 :
2005 : /**
2006 : * Union type for all possible telemetry event properties
2007 : */
2008 : export type TelemetryEventProperties =
2009 : | AuthMetadata
2010 : | OnboardingTourMetadata
2011 : | AuthErrorMetadata
2012 : | UnifiedAuthRetryMetadata
2013 : | UnifiedAuthRefreshMetadata
2014 : | WebSessionTelemetryEvent['properties']
2015 : | SsoTelemetryEvent['properties']
2016 : | ImageLoadFailureMetadata
2017 : | BootstrapCompleteMetadata
2018 : | SurveyResponses
2019 : | TemplateMetadata
2020 : | ExecutionContext
2021 : | RunButtonProperties
2022 : | ExecutionErrorMetadata
2023 : | ExecutionSuccessMetadata
2024 : | SharedWorkflowRunMetadata
2025 : | CreditTopupMetadata
2026 : | WorkflowImportMetadata
2027 : | TemplateLibraryMetadata
2028 : | TemplateLibraryClosedMetadata
2029 : | PageVisibilityMetadata
2030 : | TabCountMetadata
2031 : | ShellLayoutMetadata
2032 : | NodeSearchMetadata
2033 : | NodeSearchResultMetadata
2034 : | SearchQueryMetadata
2035 : | TemplateFilterMetadata
2036 : | SettingChangedMetadata
2037 : | UiButtonClickMetadata
2038 : | WidgetFavoriteToggledMetadata
2039 : | NamedValuesShadowDiffMismatchMetadata
2040 : | NamedValuesShadowDiffSummaryMetadata
2041 : | LinkDedupDropMetadata
2042 : | HelpCenterOpenedMetadata
2043 : | HelpResourceClickedMetadata
2044 : | HelpCenterClosedMetadata
2045 : | WorkflowCreatedMetadata
2046 : | EnterLinearMetadata
2047 : | ShareFlowMetadata
2048 : | ShareLinkOpenedMetadata
2049 : | WorkflowLinkOpenedMetadata
2050 : | WorkflowSavedMetadata
2051 : | DefaultViewSetMetadata
2052 : | SubscriptionMetadata
2053 : | SubscriptionSuccessMetadata
2054 : | WorkspaceInviteFailedMetadata
2055 : | BillingTelemetryEvent
2056 : | CheckoutJourneyTelemetryEventPayload
2057 : | AgentPaywallShownMetadata
2058 : | AgentPaywallCtaMetadata
2059 : | AgentCreditTransitionNoticeMetadata
2060 : | FetchTimeoutMetadata
2061 : | FetchStatusRetryMetadata
2062 : | WorkspaceScopeMismatchMetadata
|