Types are the declared TypeScript contract. Where a surface sends a different subset, that is called out.

Shared events — the ten in `SharedEventMap`

`chat.prompt_submitted`

Attribute	Type	chat	mobile
`conversation_id`	`string`	—	●
`session_id`	`string` @deprecated — web alias for `conversation_id`	●	—
`request_id`	`string` — join key for server-side `$ai_generation`	—	●
`agent_slug`	`string`	●	—
`has_attachments`	`boolean`	●	—
`mention_count`	`number` — `@`-tagged files/records pinned to the prompt	●	—
`prompt_source`	`'library' \	'freeform' \	'voice'`
`char_count`	`number`	—	●

Mobile hard-codes prompt_source: 'freeform' at the only call site (chat-provider.tsx:1103) — the library and voice values are declared but never sent. See §6.8.

`chat.ai_response_received`

Attribute	Type	chat	mobile
`conversation_id`	`string`	—	●
`session_id`	`string` @deprecated	●	—
`request_id`	`string`	—	●
`agent_slug`	`string`	●	—
`is_error`	`boolean`	—	●

`chat.feedback_submitted`

Attribute	Type	chat	mobile
`rating`	`'up' \	'down'`	●
`conversation_id`	`string`	●	●
`feedback_type`	`'thumbs' \	'comment'` — required	●
`categories`	`('incorrect_info' \	'jurisdiction' \	'unanswered' \
`dismissed`	`boolean`	—	declared, not sent

Count ratings by filtering feedback_type = 'thumbs'. Rating then commenting fires the event twice for one message on both platforms; ORing them double-counts the rating. The comment text is deliberately absent from analytics on both platforms — prose on a legal product can carry privileged detail, and the sanitizer only scrubs email/phone/code shapes. The body lives in the trace-feedback store.

`experiment.exposed`

Attribute	Type	Notes
`experiment`	`string`	The flag key, e.g. `onboarding-stepped-form`
`variant`	`string`	The resolved variant key
`$feature/<flag-key>`	`string`	Required. PostHog reads the variant from this and nothing else when a custom exposure event is configured

`onboarding.profile_completed`

Attribute	Type	web (SetupForm)	mobile
`distinct_id`	`string`	●	—
`persona`	`'legal_pro' \	'legal_seeker'`	—
`signup_method`	`'email' \	'google' \	'apple' \
`country`	`string`	—	●
`locale`	`string`	—	●
`experiment_variant`	`string` — set while an onboarding experiment is running	—	●
`referral_code_used`	`boolean` — referral-loop guardrail	—	●
`position`	`string`	—	● legal_pro only
`organization_name`	`string`	—	● legal_pro only
`organization_type`	`string`	—	● legal_pro only
`organization_size`	`string`	—	● legal_pro only

experiment_variant is set only when PostHog actually bucketed the user. An unbucketed user renders the control path and carries no variant — grouping by this property must never fold undefined into the control arm.

The four organization_* / position fields sit around 19% populated because the legal_seeker path sends none of them. That is by design.

`credits.topup_opened`

Attribute	Type	Surfaces
`source`	narrowed per app — see §6.3	auth, chat, mobile

`credits.topup_package_selected`

Attribute	Type	auth	chat	mobile
`package_id`	`string`	●	●	●
`credit_amount`	`number`	●	●	●
`current_tier`	`string`	●	●	●
`price_amount`	`number` — convergence target	—	—	●
`currency`	`string`	—	—	●
`price_usd`	`number` @deprecated	●	●	—
`source`	`string`	—	—	●

`credits.topup_payment_success`

Attribute	Type	auth	chat	mobile
`package_id`	`string`	●	●	●
`credits_added`	`number`	●	●	●
`price_amount`	`number`	●	●	●
`currency`	`string`	●	●	●
`amount_usd`	`number` @deprecated	—	—	—
`source`	`string`	—	—	●
`rc_app_user_id`	`string` — RevenueCat join key	—	—	●

price_amount and currency were added on web in ENG-2580. The dialog reads them off the package the user actually bought (credit-topup-dialog.tsx handleConfirmed) and passes them through onPurchaseConfirmed, so the success event is self-describing even when no topup_package_selected preceded it — which is the common case, since that event fires only on a deliberate pick and never on the pre-selected default. currency is 'USD' on web because the top-up API exposes a single price_usd field; the constant lives in the dialog so there is one place to widen when pricing is localized. Meta can only use this from the deploy forward; historical web purchases carry no value and cannot be backfilled.

`credits.topup_payment_failed`

package_id?: string · error: string (required) · source?: string — mobile sends all three, both web apps send package_id + error.

`credits.topup_upsell_clicked`

from_tier: string · to_tier: string — chat and mobile. Chat hard-codes from_tier: 'unknown'.

Auth-portal events

Event	Attributes
`auth.login_started`	auth portal: `method: 'otp' \
`auth.login_success`	auth portal: `method` (5-value union) · LoginFlow: `method: 'otp' \
`auth.login_failed`	auth portal: `method` (5-value union) · `error: string` · LoginFlow: `method: 'otp' \
`auth.login_otp_requested`	none
`auth.login_otp_verified`	none
`auth.login_password_submitted`	none
`auth.magic_link_requested`	none
`auth.register_started`	`method?: 'google' \
`auth.register_otp_requested`	none
`auth.register_otp_verified`	none
`auth.register_success`	none
`auth.logout_clicked`	web: none · mobile: `confirmed: boolean` — captured before `onLogout()`, because that resets the PostHog identity and an event fired after it lands on a fresh anonymous person
`auth.language_changed`	`from: string` · `to: string`
`auth.profile_updated`	`fields_changed: string[]`
`auth.password_changed`	none
`auth.workspace_created`	`company_id: string` · `firm_size: string` · `country: string`
`workspace.selected`	`workspace_id: string`
`workspace.creation_started`	`flow: string` — `'workspace_wizard'` from the shared form
`workspace.workspace_created`	`company_id: string` · `firm_size: string` · `country: string`
`workspace.delete_initiated`	`workspace_id: string`
`workspace.delete_confirmed`	`workspace_id: string`
`marketing.complete_registration`	none
`marketing.page_view`	none
`marketing.start_trial`	none — not emitted
`marketing.added_payment_info`	`value?: number` · `currency: string` · `plan_name: string` · `workspace_id?: string` — not emitted

Onboarding wizard (`SetupForm`, shared)

Event	Attributes
`onboarding.step_viewed`	`step: number` · `step_name: string` · `flow: string`
`onboarding.step_completed`	`step: number` · `step_name: string` · `flow: string`
`onboarding.product_selected`	`product: string`
`onboarding.completed`	`flow: string` — falls back to `'unknown'` when the host passes no `completionFlow`

SetupForm also takes an onIdentify callback, bound by all three web hosts. At profile completion it calls identify(user.id, { first_name, last_name, email }) before emitting onboarding.profile_completed, so the completion event and everything after it lands on the identified person rather than the anonymous one.

Workspace wizard (`WorkspaceCreateForm`, shared — chat + eFirm)

Event	Attributes	Emitted from
`onboarding.step_viewed`	`step: number` · `step_name: 'legal_context' \	'workspace' `·` flow: 'workspace_wizard'`
`onboarding.step_completed`	same	`:156` — `handleNext` only, never `handleFinish`; see §6.6
`workspace.creation_started`	`flow: 'workspace_wizard'`	`:149` — on mount, unconditionally; see §6.6
`workspace.workspace_created`	`company_id: string` · `firm_size: string` · `country: string`	`:184`

Team administration (`TeamManagement`, shared)

Event	Attributes
`team.member_invited`	`efirm: boolean` · `ai: boolean`
`team.access_toggled`	`product: 'efirm' \
`team.member_removed`	none

eFirm's members-page.tsx emits the same three names with the same shapes from its own page-level UI. Two emitters, one event name — a per-app breakdown will not separate the modal from the page.

Chat web

Event	Attributes
`chat.prompt_attempted_pre_auth`	`source: 'composer_submit' \
`chat.chat_session_created`	`session_id?: string` · `agent_slug?: string`
`chat.artifact_created`	`artifact_type: string` · `document_id: string` — unreachable
`chat.tool_used`	`tool_name: string` · `session_id: string`
`marketing.activated`	`session_id?: string` · `agent_slug?: string`

Subscription (web, `SubscriptionManagement`)

SubscriptionSurface is 'overview' | 'select_plan' — the overview cards' inline picker vs. the dedicated plan-selection step. Two routes into the same checkout; without this property they were indistinguishable.

Event	Attributes
`subscription.page_viewed`	`has_subscription: boolean` · `plan_name?: string`
`subscription.plan_selected`	`plan: string` · `billing_cycle: 'monthly' \
`subscription.billing_cycle_toggled`	`from` · `to` · `surface: SubscriptionSurface`
`subscription.seats_adjusted`	`from: number` · `to: number` · `surface: SubscriptionSurface`
`subscription.checkout_opened`	`plan: string` · `amount?: number` · `surface: SubscriptionSurface` · `product?: string`
`subscription.checkout_canceled`	none
`subscription.payment_success`	`plan: string` · `amount?: number` · `billing_cycle` · `seats: number` · `has_promo: boolean`
`subscription.payment_failed`	`error: string` — `error.message` verbatim, see §6.12
`subscription.cancel_initiated` / `cancel_confirmed`	none
`subscription.reactivate_initiated` / `reactivate_confirmed`	none
`subscription.seats_updated`	`from: number` · `to: number`

cancel_initiated and reactivate_initiated fire from a mount useEffect, so they count views of the cancel/reactivate screen, not deliberate taps. cancel_confirmed over cancel_initiated is therefore a screen-to-confirm rate, not a click-to-confirm rate.

Mobile — app lifecycle

Event	Attributes
`app.installed`	`install_timestamp: string` (required) · `install_referrer?` · `install_source?` · `utm_source?` · `utm_medium?` · `utm_campaign?` · `utm_content?`
`app.opened`	`is_first_open: boolean` · `user_status: 'new' \
`app.cold_start_completed`	`duration_ms: number`
`app.api_request_failed`	`endpoint: string` · `status_code: number` · `duration_ms: number` · `request_id?: string`
`app.legal_doc_viewed`	`doc_type: 'tos' \
`app.env_switched`	`from: string` · `to: string` · `channel: string`

Mobile — auth and onboarding

Event	Attributes
`auth.screen_viewed`	`is_returning?: boolean` — optional because the unified screen only learns which after email submit
`auth.method_selected`	`method: 'email' \
`auth.submitted`	`method: 'email'` — email only, by construction. OAuth hands off to the provider at `method_selected` and never reaches a submit of ours · `email_domain?: string`. The OAuth funnel is `method_selected → login_success` instead
`auth.registration_completed`	`registration_method` (same union) · `user_id: string` · `country: string`
`onboarding.persona_selected`	`persona: 'legal_pro' \
`onboarding.step_viewed` (stepped arm)	`step_id: 'name' \
`onboarding.step_back`	`step_id` — the step the user left, not the one they landed on
`onboarding.start_choice_selected`	`choice: 'guided' \
`onboarding.start_choice_viewed`	`variant: 'onboarding' \
`onboarding.start_choice_skipped`	`reason: 'already_seen_version' \
`onboarding.tour_started`	`source: 'onboarding' \
`onboarding.tour_step_viewed`	`step_id: string` · `index: number` · `step_count: number` · `direction: 'start' \
`onboarding.tour_finished`	`completed: boolean` · `last_step: number` · `last_step_id: string \
`home.screen_viewed`	`agent_slug: string`

Build both step funnels on step_id, never on the index. The help-seeker path is one step shorter than the professional one, so index 3 is contact for one population and work for the other; an index-keyed funnel silently averages two flows. Same trap as tour_step_viewed, for the same reason.

Mobile — chat

Event	Attributes
`chat.limit_reached`	`limit_type: 'daily' \
`chat.limit_warning_shown`	`limit_type` · `messages_used: number` — never emitted
`chat.prompt_tapped`	`prompt_id: string` · `category: string`
`chat.category_selected`	`category: string`
`chat.agent_switched`	`from_agent_slug: string` · `to_agent_slug: string` · `prompt_count_at_switch: number`
`chat.citation_clicked`	`citation_type: 'case_law' \
`chat.response_copied`	`conversation_id: string`
`chat.response_shared`	`conversation_id: string` · `share_target: 'system_share' \
`chat.rag_search_completed`	`result_count: number` · `has_relevant_match: boolean` · `request_id?: string` — never emitted
`chat.web_search_completed`	`result_count: number` · `returned_no_data: boolean` · `request_id?: string` — never emitted

Mobile — monetization

Event	Attributes
`subscription.status_viewed`	`provider?` · `plan_name?` · `workspace_type?`
`subscription.manage_clicked`	`provider: string` · `platform: string`
`subscription.upgrade_prompted`	`trigger: 'limit_hit' \
`subscription.downgrade_prompted`	`from_plan?` · `to_plan?` · `cycle?`
`subscription.cycle_switch_prompted`	`plan?` · `from_cycle?` · `to_cycle?`
`subscription.switch_to_personal_prompted`	`from_workspace_type?`
`subscription.cancel_started`	`plan_name: string` · `provider: string` · `billing_period?` — the first churn signal the app has ever emitted
`subscription.cancel_reason_selected`	`reason: CancelReason` · `plan_name: string`. `CancelReason` is `'too_expensive' \
`subscription.cancel_retention_shown`	`reason: CancelReason` · `offer: 'downgrade_plan' \
`subscription.cancel_retention_accepted`	`reason` · `offer` — `cancel_retention_shown` minus this is the offer's miss rate, per reason
`subscription.cancel_store_opened`	`reason: CancelReason` · `plan_name: string` — not a confirmed cancellation. Only the provider's webhook knows that, and it arrives as `state_changed` with `change_type: 'cancelled'`
`subscription.cancel_abandoned`	`step: 'reason' \
`subscription.upgraded`	`from_tier: 'free' \
`subscription.credits_purchased`	retired — see §5
`subscription.trial_started`	`user_id: string` · `trial_type: 'free_trial' \
`subscription.purchased`	`user_id` · `value: number` · `currency` · `plan_name` · `billing_period: 'monthly' \
`subscription.state_changed` (server)	Declared: `old_tier` · `new_tier` · `old_monetization_state` · `new_monetization_state` · `change_type` · `provider` · `surface`. Actually sent: `workspace_id`, `change_type`, `provider`, `surface`, plus per-webhook extras. The four tier/state fields are never populated — §6.13
`paywall.viewed`	`trigger: 'limit_hit' \
`paywall.cta_tapped`	`trigger` · `context` · `cta: 'upgrade' \
`paywall.dismissed`	`trigger` · `context` · `dwell_ms: number`
`paywall.purchase_initiated`	`plan` · `cycle` · `direction` · `product_id`
`paywall.purchase_completed`	`plan` · `cycle` · `direction` · `product_id` · `rc_app_user_id`
`paywall.purchase_confirmed`	`plan` · `cycle` · `product_id` · `rc_app_user_id`
`paywall.purchase_stuck`	`plan` · `cycle` · `product_id` · `rc_app_user_id` (the workspace's canonical RC id) · `rc_original_app_user_id: string \
`paywall.purchase_failed`	`plan` · `cycle` · `direction` · `error: string`
`paywall.purchase_cancelled`	`plan` · `cycle` · `product_id` · `dwell_ms: number` — a cancel-then-close is two events; `paywall.dismissed` still fires on unmount, because a cancellation is not a purchase
`paywall.restore_initiated`	`outcome: 'restored' \

Event	Attributes
`upload.started`	none
`upload.completed`	`file_extension: string` · `file_size_kb: number` · `duration_ms: number`
`upload.failed`	`reason: 'unsupported_format' \
`push.permission_requested`	none
`push.permission_responded`	`granted: boolean`
`push.opened`	`notification_type: 'response_ready' \
`share.sheet_opened`	`entry_point: 'share_extension' \
`share.sent`	`entry_point` · `payload_type` · `destination: 'new' \
`share.cancelled`	`entry_point` · `payload_type`
`share.failed`	`stage: 'upload' \
`share.received`	`destination` · `file_count` · `handled: boolean` · `auto_sent: boolean` · `latency_s: number`

Properties added to every event

UtmEnrichmentClient wraps every client on all four instrumented apps. On each capture it merges, without overwriting anything the call site set:

utm_source, utm_medium, utm_campaign, utm_content, utm_term — last-touch, from cookies
utm_source_first, utm_medium_first, utm_campaign_first, utm_content_first, utm_term_first — first-touch

Mobile registers super properties at module load in lib/posthog.ts: $environment, platform, app_version, os_version, device_model, locale, primary_country. Meta App Events on mobile additionally carry app_version, platform, device_type, injected by getGlobalParams().

Identity, person properties, groups

Bound identically on all four surfaces via buildUserIdentityTraits / buildUserPersonProperties (libs/analytics/src/user-properties.ts). Null, undefined and empty-string values are dropped before send. Person-property cohorts from before 2026-08-10 are mobile-only — the web apps pushed no firmographics before #1127.

Call	Fields
`identify(user.id, traits)`	`email` · `first_name` · `last_name` · `phone_number` · `email_domain` · `locale` · `signup_date` — deliberately PII. Every one of these keys is in the sanitizer's `ALLOW_PII_FIELDS`, and `identify` traits bypass the sanitizer entirely in both adapters, so they land intact
`setPersonProperties(props)`	`legal_role` · `persona` (derived from `legal_role`) · `position` (from `job_title`) · `organization_name` · `organization_type` · `organization_size` · `annual_legal_spend` · `sign_up_from` · `country` · `locale` · `signup_date`. Mobile additionally pushes the workspace set — `workspace_id`, `workspace_type`, `workspace_name`, `workspace_country`, `has_active_subscription`, `subscription_plan_name`, `subscription_provider`, and `rc_app_user_id`, which is what lets a cohort be joined to RevenueCat revenue rather than only an individual event
`group('company', companyId, …)`	Workspace-level cohorting. Called on auth, chat, eFirm and mobile. `group()` is sticky — one call tags every subsequent event with `$group_0`, so an event that fires before the company query resolves is untagged forever

distinct_id is user.id on every surface, including Langfuse and the backend's $ai_generation, so cross-tool joins by user work. Web uses cross_subdomain_cookie: true, so a session stitches across auth.haqq.ai, chat.haqq.ai and efirm.haqq.ai.

Where mobile identifies matters more than that it identifies. identify() runs inside usePostLogin, before the auth flow's own captures. It used to run only from AnalyticsIdentityBinder, which mounts inside MainStack — i.e. after the auth gate passes — so every event fired during the auth flow carried the anonymous id 100% of the time, regardless of ATT. PostHog stamps distinct_id at capture time and never rewrites it, so the alias-on-identify merge fixed the person and left the events. The binder remains, as the re-identify path for sessions that never pass through a login.

On mobile, identify, setPersonProperties and group all sit behind the App Tracking Transparency gate; aggregate events still flow when ATT is denied. Workspace-tag coverage on mobile therefore cannot exceed the ATT opt-in rate — that is Apple 5.1.2(i), not a bug to fix. On web there is no such gate, so a missing workspace tag is a race against the company query, not a ceiling.

Non-taxonomy events also in the project

These are not in any event map — they arrive from SDK defaults and will show up in PostHog alongside the taxonomy:

$pageview, $pageleave, $autocapture, $rageclick, $web_vitals (chat, eFirm, auth) · $screen on mobile, emitted manually from root-navigator.tsx:55 (SDK screen autocapture is off) · Application Opened / Application Backgrounded / Application Installed / Application Updated from captureAppLifecycleEvents: true on mobile · $set (mobile's setPersonProperties shim) · $feature_flag_called from PostHog's flag evaluation · $ai_generation, $ai_trace, $ai_span from @posthog/ai withTracing in the backend, joined to client events on request_id.