Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat: move PostHog server side (#14006)

HeyItsChloe0d2689ee2f88
diff --git a/enterprise/analytics/__init__.py b/enterprise/analytics/__init__.py
new file mode 100644
index 0000000000..444795cf9a
--- /dev/null
+++ b/enterprise/analytics/__init__.py
@@ -0,0 +1 @@
+# Enterprise analytics module
diff --git a/enterprise/analytics/saas_user_provider.py b/enterprise/analytics/saas_user_provider.py
new file mode 100644
index 0000000000..be7c699670
--- /dev/null
+++ b/enterprise/analytics/saas_user_provider.py
@@ -0,0 +1,31 @@
+"""SaaS implementation of AnalyticsUserProvider.
+
+This module provides the enterprise implementation of AnalyticsUserProvider
+that queries the actual UserStore to look up user information for analytics.
+"""
+
+from __future__ import annotations
+
+from storage.user_store import UserStore
+
+from openhands.analytics.user_base import UserBase
+from openhands.analytics.user_provider import AnalyticsUserProvider
+
+
+class SaasAnalyticsUserProvider(AnalyticsUserProvider):
+ """Enterprise implementation that queries the UserStore.
+
+ This implementation is used in SaaS deployments where user information
+ is stored in the database and accessible via UserStore.
+ """
+
+ async def get_user_by_id(self, user_id: str) -> UserBase | None:
+ """Look up a user by their ID using the UserStore.
+
+ Args:
+ user_id: The user's unique identifier.
+
+ Returns:
+ The User object from the database, or None if not found.
+ """
+ return await UserStore.get_user_by_id(user_id)
diff --git a/enterprise/poetry.lock b/enterprise/poetry.lock
index 25a6e7f17d..bb826f3404 100644
--- a/enterprise/poetry.lock
+++ b/enterprise/poetry.lock
@@ -7372,14 +7372,14 @@ tests = ["pytest (>=5.4.1)", "pytest-cov (>=2.8.1)", "pytest-mypy (>=0.8.0)", "p
[[package]]
name = "posthog"
-version = "6.9.3"
+version = "7.9.12"
description = "Integrate PostHog into any python application."
optional = false
-python-versions = ">=3.9"
+python-versions = ">=3.10"
groups = ["main"]
files = [
- {file = "posthog-6.9.3-py3-none-any.whl", hash = "sha256:c71e9cb7ac4ef13eb604f04c3161edd10b1d08a32499edd54437ba5eab591c58"},
- {file = "posthog-6.9.3.tar.gz", hash = "sha256:7d201774ea9eba156f1de46d34313e30b2384d523900fe8e425accc92486cc34"},
+ {file = "posthog-7.9.12-py3-none-any.whl", hash = "sha256:7175bd1698a566bfea98a016c64e3456399f8046aeeca8f1d04ae5bf6c5a38d0"},
+ {file = "posthog-7.9.12.tar.gz", hash = "sha256:ebabf2eb2e1c1fbf22b0759df4644623fa43cc6c9dcbe9fd429b7937d14251ec"},
]
[package.dependencies]
@@ -7393,7 +7393,7 @@ typing-extensions = ">=4.2.0"
[package.extras]
dev = ["django-stubs", "lxml", "mypy", "mypy-baseline", "packaging", "pre-commit", "pydantic", "ruff", "setuptools", "tomli", "tomli_w", "twine", "types-mock", "types-python-dateutil", "types-requests", "types-setuptools", "types-six", "wheel"]
langchain = ["langchain (>=0.2.0)"]
-test = ["anthropic", "coverage", "django", "freezegun (==1.5.1)", "google-genai", "langchain-anthropic (>=0.3.15)", "langchain-community (>=0.3.25)", "langchain-core (>=0.3.65)", "langchain-openai (>=0.3.22)", "langgraph (>=0.4.8)", "mock (>=2.0.0)", "openai", "parameterized (>=0.8.1)", "pydantic", "pytest", "pytest-asyncio", "pytest-timeout"]
+test = ["anthropic (>=0.72)", "coverage", "django", "freezegun (==1.5.1)", "google-genai", "langchain-anthropic (>=1.0)", "langchain-community (>=0.4)", "langchain-core (>=1.0)", "langchain-openai (>=1.0)", "langgraph (>=1.0)", "mock (>=2.0.0)", "openai (>=2.0)", "parameterized (>=0.8.1)", "pydantic", "pytest", "pytest-asyncio", "pytest-timeout"]
[[package]]
name = "pre-commit"
@@ -15242,4 +15242,4 @@ cffi = ["cffi (>=1.17,<2.0) ; platform_python_implementation != \"PyPy\" and pyt
[metadata]
lock-version = "2.1"
python-versions = "^3.12,<3.14"
-content-hash = "c468b13e2d26e31e0e8f84518bcb8379234d431ca3819625f49b91aa3589359c"
+content-hash = "55a09a40217bbbc876e5864b78c941d86a261e4111bce7e4495c1dd75df43fd7"
diff --git a/enterprise/pyproject.toml b/enterprise/pyproject.toml
index b029d2178f..8d45db4b19 100644
--- a/enterprise/pyproject.toml
+++ b/enterprise/pyproject.toml
@@ -36,7 +36,7 @@ resend = "^2.7.0"
tenacity = "^9.1.2"
slack-sdk = "^3.35.0"
ddtrace = "3.13.0" #pin to avoid yanked version 3.12.4
-posthog = "^6.0.0"
+posthog = "^7.0.0"
limits = "^5.2.0"
coredis = "^4.22.0"
httpx = "*"
diff --git a/enterprise/server/app_lifespan/__init__.py b/enterprise/server/app_lifespan/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/enterprise/server/app_lifespan/saas_app_lifespan_service.py b/enterprise/server/app_lifespan/saas_app_lifespan_service.py
new file mode 100644
index 0000000000..85b6ed42c8
--- /dev/null
+++ b/enterprise/server/app_lifespan/saas_app_lifespan_service.py
@@ -0,0 +1,44 @@
+"""SaaS-specific application lifespan service.
+
+Initializes PostHog analytics on startup and flushes buffered events on
+clean shutdown so no events are lost when the server exits gracefully.
+"""
+
+from __future__ import annotations
+
+import os
+
+from server.constants import IS_FEATURE_ENV
+
+from openhands.analytics import get_analytics_service, init_analytics_service
+from openhands.app_server.app_lifespan.app_lifespan_service import AppLifespanService
+from openhands.app_server.utils.logger import openhands_logger as logger
+from openhands.server.types import AppMode
+
+
+class SaasAppLifespanService(AppLifespanService):
+ """Lifespan service for the SaaS server.
+
+ On enter: initialises the PostHog analytics singleton from environment vars.
+ On exit: calls ``analytics_service.shutdown()`` to flush any buffered events.
+ """
+
+ async def __aenter__(self):
+ api_key = os.environ.get('POSTHOG_CLIENT_KEY', '')
+ host = os.environ.get('POSTHOG_HOST', 'https://us.i.posthog.com')
+
+ init_analytics_service(
+ api_key=api_key,
+ host=host,
+ app_mode=AppMode.SAAS,
+ is_feature_env=IS_FEATURE_ENV,
+ )
+ return self
+
+ async def __aexit__(self, exc_type, exc_value, traceback):
+ try:
+ svc = get_analytics_service()
+ if svc is not None:
+ svc.shutdown()
+ except Exception:
+ logger.exception('Error shutting down analytics service')
diff --git a/enterprise/server/config.py b/enterprise/server/config.py
index 0057d95759..162cb6c341 100644
--- a/enterprise/server/config.py
+++ b/enterprise/server/config.py
@@ -62,6 +62,9 @@ class SaaSServerConfig(ServerConfig):
settings_store_class: str = 'storage.saas_settings_store.SaasSettingsStore'
secret_store_class: str = 'storage.saas_secrets_store.SaasSecretsStore'
user_auth_class: str = 'server.auth.saas_user_auth.SaasUserAuth'
+ analytics_user_provider_class: str = (
+ 'analytics.saas_user_provider.SaasAnalyticsUserProvider'
+ )
# Maintenance window configuration
maintenance_start_time: str = os.environ.get(
'MAINTENANCE_START_TIME', ''
diff --git a/enterprise/server/middleware.py b/enterprise/server/middleware.py
index d550a088ee..cda15a82e3 100644
--- a/enterprise/server/middleware.py
+++ b/enterprise/server/middleware.py
@@ -191,3 +191,19 @@ class SetAuthCookieMiddleware:
await token_manager.logout(user_auth.refresh_token.get_secret_value())
except Exception:
logger.debug('Error logging out')
+
+
+class PostHogSessionMiddleware:
+ """Extract the PostHog session ID from the incoming request header.
+
+ Stores the value on ``request.state.posthog_session_id`` so that
+ subsequent event-capture call sites can link server-side events to the
+ corresponding frontend session-replay recording.
+
+ When the ``X-POSTHOG-SESSION-ID`` header is absent the attribute is set
+ to ``None`` β€” never raises, never blocks.
+ """
+
+ async def __call__(self, request: Request, call_next: Callable):
+ request.state.posthog_session_id = request.headers.get('X-POSTHOG-SESSION-ID')
+ return await call_next(request)
diff --git a/enterprise/server/routes/auth.py b/enterprise/server/routes/auth.py
index d7fac4798a..37f140bcba 100644
--- a/enterprise/server/routes/auth.py
+++ b/enterprise/server/routes/auth.py
@@ -8,8 +8,15 @@ from typing import Annotated, Optional, cast
from urllib.parse import quote, urlencode
from uuid import UUID as parse_uuid
-import posthog
-from fastapi import APIRouter, Header, HTTPException, Request, Response, status
+from fastapi import (
+ APIRouter,
+ BackgroundTasks,
+ Header,
+ HTTPException,
+ Request,
+ Response,
+ status,
+)
from fastapi.responses import JSONResponse, RedirectResponse
from pydantic import SecretStr
from server.auth.constants import (
@@ -46,6 +53,7 @@ from storage.database import a_session_maker
from storage.user import User
from storage.user_store import UserStore
+from openhands.analytics import get_analytics_service
from openhands.app_server.integrations.provider import (
PROVIDER_TOKEN_TYPE,
ProviderHandler,
@@ -141,9 +149,107 @@ def _extract_oauth_state(state: str | None) -> tuple[str, str | None, str | None
return state, None, None
+async def _get_user_orgs_with_data(user_id: str, org_member_ids: list) -> list:
+ """Load Org objects for a user's org memberships.
+
+ Uses OrgStore.get_orgs_by_ids() to batch-load all Org objects in a single
+ query, avoiding N+1.
+
+ Args:
+ user_id: The user's ID string
+ org_member_ids: List of org_id UUIDs from user.org_members
+
+ Returns:
+ List of Org objects the user belongs to
+ """
+ from storage.org_store import OrgStore
+
+ if not org_member_ids:
+ return []
+
+ try:
+ return await OrgStore.get_orgs_by_ids(org_member_ids)
+ except Exception:
+ logger.exception(
+ 'auth:_get_user_orgs_with_data:failed',
+ extra={'user_id': user_id, 'org_ids': [str(oid) for oid in org_member_ids]},
+ )
+ return []
+
+
+async def _track_login_analytics_background(
+ user_id: str,
+ email: str | None,
+ idp: str,
+ current_org_id: parse_uuid | None,
+ org_member_ids: list,
+ consented: bool,
+) -> None:
+ """Track login analytics in background to avoid blocking auth response."""
+ try:
+ from storage.org_member_store import OrgMemberStore
+ from storage.org_store import OrgStore
+
+ analytics = get_analytics_service()
+ if not analytics:
+ return
+
+ org_id_str = str(current_org_id) if current_org_id else None
+
+ # Load current org
+ current_org = (
+ await OrgStore.get_org_by_id(current_org_id) if current_org_id else None
+ )
+
+ # Load org data (orgs list with member_count)
+ user_orgs = await _get_user_orgs_with_data(user_id, org_member_ids)
+
+ orgs_data = []
+ for org in user_orgs:
+ try:
+ member_count = await OrgMemberStore.get_org_members_count(org_id=org.id)
+ except Exception:
+ logger.exception(
+ 'auth:identify_user:member_count_failed',
+ extra={'user_id': user_id, 'org_id': str(org.id)},
+ )
+ member_count = None
+ orgs_data.append(
+ {'id': str(org.id), 'name': org.name, 'member_count': member_count}
+ )
+
+ from openhands.analytics.analytics_context import AnalyticsContext
+
+ ctx = AnalyticsContext(
+ user_id=user_id,
+ consented=consented,
+ org_id=org_id_str,
+ user=None,
+ )
+
+ analytics.identify_user(
+ ctx=ctx,
+ email=email,
+ org_name=current_org.name if current_org else None,
+ idp=idp,
+ orgs=orgs_data,
+ )
+
+ analytics.track_user_logged_in(
+ ctx=ctx,
+ idp=idp,
+ )
+ except Exception:
+ logger.exception(
+ 'auth:_track_login_analytics_background:failed',
+ extra={'user_id': user_id},
+ )
+
+
@oauth_router.get('/keycloak/callback')
async def keycloak_callback(
request: Request,
+ background_tasks: BackgroundTasks,
code: Optional[str] = None,
state: Optional[str] = None,
error: Optional[str] = None,
@@ -352,36 +458,26 @@ async def keycloak_callback(
f'keycloakAccessToken: {keycloak_access_token}, keycloakUserId: {user_id}'
)
- # adding in posthog tracking
-
- # If this is a feature environment, add "FEATURE_" prefix to user_id for PostHog
- posthog_user_id = f'FEATURE_{user_id}' if IS_FEATURE_ENV else user_id
-
- try:
- posthog.set(
- distinct_id=posthog_user_id,
- properties={
- 'user_id': posthog_user_id,
- 'original_user_id': user_id,
- 'is_feature_env': IS_FEATURE_ENV,
- },
- )
- except Exception as e:
- logger.error(
- 'auth:posthog_set:failed',
- extra={
- 'user_id': user_id,
- 'error': str(e),
- },
- )
- # Continue execution as this is not critical
+ # Server-side identity β€” defer to background to avoid blocking auth response
+ consented = user.user_consents_to_analytics is True
+ org_member_ids = [om.org_id for om in user.org_members] if user.org_members else []
+
+ background_tasks.add_task(
+ _track_login_analytics_background,
+ user_id=user_id,
+ email=email,
+ idp=idp,
+ current_org_id=user.current_org_id,
+ org_member_ids=org_member_ids,
+ consented=consented,
+ )
logger.info(
'user_logged_in',
extra={
'idp': idp,
'idp_type': idp_type,
- 'posthog_user_id': posthog_user_id,
+ 'user_id': user_id,
'is_feature_env': IS_FEATURE_ENV,
},
)
@@ -696,10 +792,40 @@ async def accept_tos(request: Request):
content={'error': 'User does not exist'},
)
user.accepted_tos = accepted_tos
+ # SaaS users consent to analytics via Terms of Service acceptance
+ user.user_consents_to_analytics = True
await session.commit()
logger.info(f'User {user_id} accepted TOS')
+ # Analytics: user signed up event (fires on first TOS acceptance)
+ try:
+ analytics = get_analytics_service()
+ if analytics:
+ from openhands.analytics.analytics_context import AnalyticsContext
+
+ org_id_str = str(user.current_org_id) if user.current_org_id else None
+ email = user.email
+
+ ctx = AnalyticsContext(
+ user_id=user_id,
+ consented=True,
+ org_id=org_id_str,
+ user=user,
+ )
+ analytics.track_user_signed_up(
+ ctx=ctx,
+ email_domain=email.split('@')[1]
+ if email and '@' in email
+ else None,
+ )
+ analytics.set_person_properties(
+ ctx=ctx,
+ properties={'signed_up_at': datetime.now(timezone.utc).isoformat()},
+ )
+ except Exception:
+ logger.exception('analytics:user_signed_up:failed')
+
# Determine final redirect - but don't override if it's the offline token flow
# (the offline callback will handle post-auth redirect after storing the token)
is_offline_flow = 'offline' in redirect_url
diff --git a/enterprise/server/routes/billing.py b/enterprise/server/routes/billing.py
index dc2577906d..0bd8ecf55a 100644
--- a/enterprise/server/routes/billing.py
+++ b/enterprise/server/routes/billing.py
@@ -20,6 +20,7 @@ from storage.org import Org
from storage.subscription_access import SubscriptionAccess
from storage.user_store import UserStore
+from openhands.analytics import get_analytics_service
from openhands.app_server.config import get_global_config
from openhands.app_server.user_auth import get_user_id
@@ -28,9 +29,7 @@ billing_router = APIRouter(prefix='/api/billing', tags=['Billing'])
async def validate_billing_enabled() -> None:
- """
- Validate that the billing feature flag is enabled
- """
+ """Validate that the billing feature flag is enabled"""
config = get_global_config()
web_client_config = await config.web_client.get_web_client_config()
if not web_client_config.feature_flags.enable_billing:
@@ -299,6 +298,27 @@ async def success_callback(session_id: str, request: Request):
)
await session.commit()
+ # Analytics: credit purchased event (fires after commit so event only fires on success)
+ try:
+ analytics = get_analytics_service()
+ if analytics and user:
+ from openhands.analytics.analytics_context import AnalyticsContext
+
+ ctx = AnalyticsContext(
+ user_id=billing_session.user_id,
+ consented=user.user_consents_to_analytics is True,
+ org_id=str(user.current_org_id) if user.current_org_id else None,
+ user=user,
+ )
+ analytics.track_credit_purchased(
+ ctx=ctx,
+ amount_usd=add_credits,
+ credit_balance_before=max_budget,
+ credit_balance_after=new_max_budget,
+ )
+ except Exception:
+ logger.exception('analytics:credit_purchased:failed')
+
return RedirectResponse(
f'{get_web_url(request)}/settings/billing?checkout=success', status_code=302
)
diff --git a/enterprise/server/routes/oauth_device.py b/enterprise/server/routes/oauth_device.py
index 5c726a827d..22b9904662 100644
--- a/enterprise/server/routes/oauth_device.py
+++ b/enterprise/server/routes/oauth_device.py
@@ -10,6 +10,7 @@ from server.utils.url_utils import get_web_url
from storage.api_key_store import ApiKeyStore
from storage.device_code_store import DeviceCodeStore
+from openhands.analytics import get_analytics_service, resolve_analytics_context
from openhands.app_server.user_auth import get_user_id
from openhands.app_server.utils.logger import openhands_logger as logger
@@ -323,6 +324,38 @@ async def device_verification_authenticated(
'Device code authorized with API key successfully',
extra={'user_code': user_code, 'user_id': user_id},
)
+
+ # Server-side identity tracking for device auth flow
+ analytics = get_analytics_service()
+ if analytics:
+ try:
+ ctx = await resolve_analytics_context(user_id)
+
+ # Load current org name for identify_user
+ from storage.org_store import OrgStore
+
+ current_org = (
+ await OrgStore.get_org_by_id(ctx.user.current_org_id)
+ if ctx.user and ctx.user.current_org_id
+ else None
+ )
+
+ analytics.identify_user(
+ ctx=ctx,
+ org_name=current_org.name if current_org else None,
+ idp='device_auth',
+ )
+
+ analytics.track_user_logged_in(
+ ctx=ctx,
+ idp='device_auth',
+ )
+ except Exception:
+ logger.exception(
+ 'oauth_device:analytics:failed',
+ extra={'user_id': user_id},
+ )
+
return JSONResponse(
status_code=status.HTTP_200_OK,
content={'message': 'Device authorized successfully!'},
diff --git a/enterprise/server/routes/onboarding.py b/enterprise/server/routes/onboarding.py
new file mode 100644
index 0000000000..91c7370c70
--- /dev/null
+++ b/enterprise/server/routes/onboarding.py
@@ -0,0 +1,64 @@
+"""Onboarding submission endpoint.
+
+Receives user onboarding selections and fires analytics event.
+"""
+
+from datetime import datetime, timezone
+from typing import Union
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+
+from openhands.app_server.user_auth import get_user_id
+
+onboarding_router = APIRouter(prefix='/api', tags=['Onboarding'])
+
+
+class OnboardingSubmission(BaseModel):
+ selections: dict[str, Union[str, list[str]]]
+ # question_id -> selected option(s)
+ # e.g., {"role": "software_engineer", "org_size": "solo", "use_case": ["new_features", "fixing_bugs"]}
+
+
+class OnboardingResponse(BaseModel):
+ status: str
+ redirect_url: str
+
+
+@onboarding_router.post('/onboarding', response_model=OnboardingResponse)
+async def submit_onboarding(
+ body: OnboardingSubmission,
+ user_id: str | None = Depends(get_user_id),
+) -> OnboardingResponse:
+ """Submit onboarding form selections and fire analytics event."""
+ # ACTV-03: onboarding completed
+ try:
+ from openhands.analytics import get_analytics_service, resolve_analytics_context
+
+ analytics = get_analytics_service()
+ if analytics and user_id:
+ ctx = await resolve_analytics_context(user_id)
+
+ analytics.track_onboarding_completed(
+ ctx=ctx,
+ selections=body.selections,
+ )
+
+ # Associate onboarding timestamp with org group
+ if ctx.org_id:
+ analytics.group_identify(
+ ctx=ctx,
+ group_type='org',
+ group_key=ctx.org_id,
+ properties={
+ 'onboarding_completed_at': datetime.now(
+ timezone.utc
+ ).isoformat(),
+ },
+ )
+ except Exception:
+ import logging
+
+ logging.getLogger(__name__).exception('analytics:onboarding_completed:failed')
+
+ return OnboardingResponse(status='ok', redirect_url='/')
diff --git a/enterprise/server/routes/org_invitations.py b/enterprise/server/routes/org_invitations.py
index d1f95f1a32..5b6ebade9e 100644
--- a/enterprise/server/routes/org_invitations.py
+++ b/enterprise/server/routes/org_invitations.py
@@ -22,6 +22,7 @@ from server.utils.rate_limit_utils import check_rate_limit_by_user_id
from storage.org_store import OrgStore
from storage.role_store import RoleStore
+from openhands.analytics import get_analytics_service
from openhands.app_server.user_auth import get_user_id
from openhands.app_server.utils.logger import openhands_logger as logger
@@ -94,6 +95,33 @@ async def create_invitation(
},
)
+ # Analytics: track team members invited
+ try:
+ analytics = get_analytics_service()
+ if analytics and user_id:
+ from storage.user_store import UserStore
+
+ from openhands.analytics.analytics_context import AnalyticsContext
+
+ user_obj = await UserStore.get_user_by_id(user_id)
+ ctx = AnalyticsContext(
+ user_id=user_id,
+ consented=user_obj.user_consents_to_analytics is True
+ if user_obj
+ else False,
+ org_id=str(org_id),
+ user=user_obj,
+ )
+ analytics.track_team_members_invited(
+ ctx=ctx,
+ invited_count=len(invitation_data.emails),
+ successful_count=len(successful),
+ failed_count=len(failed),
+ role=invitation_data.role,
+ )
+ except Exception:
+ logger.exception('analytics:team_members_invited:failed')
+
successful_responses = [
await InvitationResponse.from_invitation(inv) for inv in successful
]
diff --git a/enterprise/server/routes/orgs.py b/enterprise/server/routes/orgs.py
index e21934eb8a..541a9cb176 100644
--- a/enterprise/server/routes/orgs.py
+++ b/enterprise/server/routes/orgs.py
@@ -50,6 +50,7 @@ from storage.org_service import OrgService
from storage.org_store import OrgStore
from storage.user_store import UserStore
+from openhands.analytics import get_analytics_service
from openhands.app_server.user_auth import get_user_id
from openhands.app_server.utils.logger import openhands_logger as logger
@@ -1134,6 +1135,28 @@ async def switch_org(
org_id=org_id,
)
+ # Refresh person profile with new active org on org switch
+ analytics = get_analytics_service()
+ if analytics:
+ try:
+ from openhands.analytics import resolve_analytics_context
+
+ ctx = await resolve_analytics_context(user_id)
+
+ analytics.set_person_properties(
+ ctx=ctx,
+ properties={
+ 'org_id': str(org_id),
+ 'org_name': org.name,
+ 'plan_tier': None, # plan_tier not yet on Org model
+ },
+ )
+ except Exception:
+ logger.exception(
+ 'orgs:switch_org:analytics:failed',
+ extra={'user_id': user_id, 'org_id': str(org_id)},
+ )
+
# Retrieve credits from LiteLLM for the new current org
credits = await OrgService.get_org_credits(user_id, org.id)
diff --git a/enterprise/storage/org_store.py b/enterprise/storage/org_store.py
index 3a1f151685..1557e6d0b6 100644
--- a/enterprise/storage/org_store.py
+++ b/enterprise/storage/org_store.py
@@ -101,6 +101,29 @@ class OrgStore:
org = result.scalars().first()
return await OrgStore._validate_org_version(org)
+ @staticmethod
+ async def get_orgs_by_ids(org_ids: list[UUID]) -> list[Org]:
+ """Get multiple organizations by IDs in a single query.
+
+ Args:
+ org_ids: List of organization UUIDs to fetch.
+
+ Returns:
+ List of Org objects (may be fewer than input if some IDs don't exist).
+ """
+ if not org_ids:
+ return []
+ async with a_session_maker() as session:
+ result = await session.execute(select(Org).filter(Org.id.in_(org_ids)))
+ orgs = list(result.scalars().all())
+ # Validate org versions for all returned orgs
+ validated_orgs = []
+ for org in orgs:
+ validated = await OrgStore._validate_org_version(org)
+ if validated:
+ validated_orgs.append(validated)
+ return validated_orgs
+
@staticmethod
async def get_current_org_from_keycloak_user_id(
keycloak_user_id: str,
diff --git a/enterprise/storage/user.py b/enterprise/storage/user.py
index ef63b52f7d..7af56ba464 100644
--- a/enterprise/storage/user.py
+++ b/enterprise/storage/user.py
@@ -20,7 +20,10 @@ if TYPE_CHECKING:
class User(Base):
- """User model with organizational relationships."""
+ """User model with organizational relationships.
+
+ This model satisfies the UserBase protocol via structural typing.
+ """
__tablename__ = 'user'
diff --git a/enterprise/tests/unit/server/routes/test_onboarding.py b/enterprise/tests/unit/server/routes/test_onboarding.py
new file mode 100644
index 0000000000..f8020a7f7f
--- /dev/null
+++ b/enterprise/tests/unit/server/routes/test_onboarding.py
@@ -0,0 +1,255 @@
+"""Tests for the onboarding route.
+
+Covers:
+- Successful onboarding submission with analytics tracking
+- Analytics tracking with org_id and group_identify
+- Handling when analytics service is not available
+- Handling when user_id is not available
+- Error handling when analytics fails
+"""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from server.routes.onboarding import (
+ OnboardingResponse,
+ OnboardingSubmission,
+ submit_onboarding,
+)
+
+from openhands.analytics.analytics_context import AnalyticsContext
+
+
+def mock_analytics_service():
+ """Create a mock analytics service."""
+ service = MagicMock()
+ service.track_onboarding_completed = MagicMock()
+ service.group_identify = MagicMock()
+ return service
+
+
+def mock_analytics_context():
+ """Create a mock analytics context with consent and org_id."""
+ return AnalyticsContext(
+ user_id='test-user-123',
+ consented=True,
+ org_id='org-abc-456',
+ user=None,
+ )
+
+
+def mock_analytics_context_no_org():
+ """Create a mock analytics context without org_id."""
+ return AnalyticsContext(
+ user_id='test-user-123',
+ consented=True,
+ org_id=None,
+ user=None,
+ )
+
+
+def mock_analytics_context_no_consent():
+ """Create a mock analytics context without consent."""
+ return AnalyticsContext(
+ user_id='test-user-123',
+ consented=False,
+ org_id='org-abc-456',
+ user=None,
+ )
+
+
+async def test_submit_onboarding_returns_ok_response():
+ """submit_onboarding returns OnboardingResponse with status ok and redirect_url /."""
+ body = OnboardingSubmission(selections={'role': 'developer', 'org_size': '11-50'})
+
+ with patch('openhands.analytics.get_analytics_service', return_value=None):
+ result = await submit_onboarding(body=body, user_id='test-user')
+
+ assert isinstance(result, OnboardingResponse)
+ assert result.status == 'ok'
+ assert result.redirect_url == '/'
+
+
+async def test_submit_onboarding_tracks_analytics_event(
+ mock_analytics_service, mock_analytics_context
+):
+ """submit_onboarding calls track_onboarding_completed with correct parameters."""
+ body = OnboardingSubmission(
+ selections={
+ 'role': 'software_engineer',
+ 'org_size': 'solo',
+ 'use_case': ['new_features', 'fixing_bugs'],
+ }
+ )
+
+ with (
+ patch(
+ 'openhands.analytics.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ patch(
+ 'openhands.analytics.resolve_analytics_context',
+ new_callable=AsyncMock,
+ return_value=mock_analytics_context,
+ ),
+ ):
+ await submit_onboarding(body=body, user_id='test-user-123')
+
+ mock_analytics_service.track_onboarding_completed.assert_called_once()
+ call_kwargs = mock_analytics_service.track_onboarding_completed.call_args.kwargs
+ assert call_kwargs['ctx'].user_id == 'test-user-123'
+ assert call_kwargs['ctx'].org_id == 'org-abc-456'
+ assert call_kwargs['ctx'].consented is True
+ assert call_kwargs['selections'] == {
+ 'role': 'software_engineer',
+ 'org_size': 'solo',
+ 'use_case': ['new_features', 'fixing_bugs'],
+ }
+
+
+async def test_submit_onboarding_calls_group_identify_when_org_id_present(
+ mock_analytics_service, mock_analytics_context
+):
+ """submit_onboarding calls group_identify when org_id is present."""
+ body = OnboardingSubmission(selections={'role': 'developer'})
+
+ with (
+ patch(
+ 'openhands.analytics.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ patch(
+ 'openhands.analytics.resolve_analytics_context',
+ new_callable=AsyncMock,
+ return_value=mock_analytics_context,
+ ),
+ ):
+ await submit_onboarding(body=body, user_id='test-user-123')
+
+ mock_analytics_service.group_identify.assert_called_once()
+ call_kwargs = mock_analytics_service.group_identify.call_args.kwargs
+ assert call_kwargs['ctx'].user_id == 'test-user-123'
+ assert call_kwargs['ctx'].consented is True
+ assert call_kwargs['group_type'] == 'org'
+ assert call_kwargs['group_key'] == 'org-abc-456'
+ assert 'onboarding_completed_at' in call_kwargs['properties']
+
+
+async def test_submit_onboarding_skips_group_identify_when_no_org_id(
+ mock_analytics_service, mock_analytics_context_no_org
+):
+ """submit_onboarding skips group_identify when org_id is None."""
+ body = OnboardingSubmission(selections={'role': 'developer'})
+
+ with (
+ patch(
+ 'openhands.analytics.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ patch(
+ 'openhands.analytics.resolve_analytics_context',
+ new_callable=AsyncMock,
+ return_value=mock_analytics_context_no_org,
+ ),
+ ):
+ await submit_onboarding(body=body, user_id='test-user-123')
+
+ mock_analytics_service.track_onboarding_completed.assert_called_once()
+ mock_analytics_service.group_identify.assert_not_called()
+
+
+async def test_submit_onboarding_skips_analytics_when_service_is_none():
+ """submit_onboarding skips analytics when get_analytics_service returns None."""
+ body = OnboardingSubmission(selections={'role': 'developer'})
+
+ with patch('openhands.analytics.get_analytics_service', return_value=None):
+ result = await submit_onboarding(body=body, user_id='test-user-123')
+
+ # Should still return success even without analytics
+ assert result.status == 'ok'
+
+
+async def test_submit_onboarding_skips_analytics_when_user_id_is_none(
+ mock_analytics_service,
+):
+ """submit_onboarding skips analytics when user_id is None."""
+ body = OnboardingSubmission(selections={'role': 'developer'})
+
+ with patch(
+ 'openhands.analytics.get_analytics_service',
+ return_value=mock_analytics_service,
+ ):
+ result = await submit_onboarding(body=body, user_id=None)
+
+ # Should still return success
+ assert result.status == 'ok'
+ # Analytics should not be called
+ mock_analytics_service.track_onboarding_completed.assert_not_called()
+
+
+async def test_submit_onboarding_handles_analytics_exception_gracefully(
+ mock_analytics_service,
+):
+ """submit_onboarding catches analytics exceptions and still returns success."""
+ body = OnboardingSubmission(selections={'role': 'developer'})
+ mock_analytics_service.track_onboarding_completed.side_effect = RuntimeError(
+ 'PostHog error'
+ )
+
+ mock_context = AnalyticsContext(
+ user_id='test-user-123',
+ consented=True,
+ org_id=None,
+ user=None,
+ )
+
+ with (
+ patch(
+ 'openhands.analytics.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ patch(
+ 'openhands.analytics.resolve_analytics_context',
+ new_callable=AsyncMock,
+ return_value=mock_context,
+ ),
+ ):
+ # Should not raise, should return success
+ result = await submit_onboarding(body=body, user_id='test-user-123')
+
+ assert result.status == 'ok'
+
+
+async def test_submit_onboarding_passes_consent_false_to_analytics(
+ mock_analytics_service, mock_analytics_context_no_consent
+):
+ """submit_onboarding passes consented=False when user has not consented."""
+ body = OnboardingSubmission(selections={'role': 'developer'})
+
+ with (
+ patch(
+ 'openhands.analytics.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ patch(
+ 'openhands.analytics.resolve_analytics_context',
+ new_callable=AsyncMock,
+ return_value=mock_analytics_context_no_consent,
+ ),
+ ):
+ await submit_onboarding(body=body, user_id='test-user-123')
+
+ call_kwargs = mock_analytics_service.track_onboarding_completed.call_args.kwargs
+ assert call_kwargs['ctx'].consented is False
diff --git a/enterprise/tests/unit/test_auth_routes.py b/enterprise/tests/unit/test_auth_routes.py
index 45712319ab..9dd7e7e8f6 100644
--- a/enterprise/tests/unit/test_auth_routes.py
+++ b/enterprise/tests/unit/test_auth_routes.py
@@ -3,7 +3,7 @@ import json
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from fastapi import HTTPException, Request, Response, status
+from fastapi import BackgroundTasks, HTTPException, Request, Response, status
from fastapi.responses import JSONResponse, RedirectResponse
from pydantic import SecretStr
from server.auth.auth_error import AuthError
@@ -50,6 +50,11 @@ def mock_response():
return MagicMock(spec=Response)
+def mock_background_tasks():
+ return MagicMock(spec=BackgroundTasks)
+
+
def test_set_response_cookie(mock_response, mock_request):
"""Test setting the auth cookie on a response."""
from openhands.app_server.services.jwt_service import JwtService
@@ -92,13 +97,14 @@ def test_set_response_cookie(mock_response, mock_request):
@pytest.mark.asyncio
-async def test_keycloak_callback_missing_code(mock_request):
+async def test_keycloak_callback_missing_code(mock_request, mock_background_tasks):
"""Test keycloak_callback with missing code."""
with pytest.raises(HTTPException) as exc_info:
await keycloak_callback(
code='',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -107,7 +113,9 @@ async def test_keycloak_callback_missing_code(mock_request):
@pytest.mark.asyncio
-async def test_keycloak_callback_token_retrieval_failure(mock_request):
+async def test_keycloak_callback_token_retrieval_failure(
+ mock_request, mock_background_tasks
+):
"""Test keycloak_callback when token retrieval fails."""
get_keycloak_tokens_mock = AsyncMock(return_value=(None, None))
with patch(
@@ -118,6 +126,7 @@ async def test_keycloak_callback_token_retrieval_failure(mock_request):
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -133,7 +142,7 @@ async def test_keycloak_callback_token_retrieval_failure(mock_request):
@pytest.mark.asyncio
async def test_keycloak_callback_user_not_authorized(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when user authorization fails."""
with (
@@ -174,6 +183,7 @@ async def test_keycloak_callback_user_not_authorized(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=mock_authorizer,
)
@@ -183,25 +193,47 @@ async def test_keycloak_callback_user_not_authorized(
@pytest.mark.asyncio
async def test_keycloak_callback_success_with_valid_offline_token(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test successful keycloak_callback with valid offline token."""
+ mock_analytics = MagicMock()
+ mock_org = MagicMock()
+ mock_org.id = 'test_org_id'
+ mock_org.name = 'Test Org'
+
with (
patch('server.routes.auth.token_manager') as mock_token_manager,
patch('server.routes.auth.set_response_cookie') as mock_set_cookie,
patch('server.routes.auth.UserStore') as mock_user_store,
- patch('server.routes.auth.posthog') as mock_posthog,
+ patch('server.routes.auth.get_analytics_service', return_value=mock_analytics),
+ patch(
+ 'storage.org_store.OrgStore.get_org_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_org,
+ ),
+ patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org],
+ ),
+ patch(
+ 'storage.org_member_store.OrgMemberStore.get_org_members_count',
+ new_callable=AsyncMock,
+ return_value=1,
+ ),
patch(
'server.routes.auth._should_redirect_to_onboarding',
new_callable=AsyncMock,
return_value=False,
),
):
- # Mock user with accepted_tos
+ # Mock user with accepted_tos and analytics consent
mock_user = MagicMock()
mock_user.id = 'test_user_id'
mock_user.current_org_id = 'test_org_id'
mock_user.accepted_tos = '2025-01-01'
+ mock_user.user_consents_to_analytics = True
+ mock_user.org_members = []
# Setup UserStore mocks
mock_user_store.get_user_by_id = AsyncMock(return_value=mock_user)
@@ -228,6 +260,7 @@ async def test_keycloak_callback_success_with_valid_offline_token(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -246,12 +279,33 @@ async def test_keycloak_callback_success_with_valid_offline_token(
secure=False,
accepted_tos=True,
)
- mock_posthog.set.assert_called_once()
+
+ # Verify background task was scheduled and execute it to test analytics
+ mock_background_tasks.add_task.assert_called_once()
+ background_fn = mock_background_tasks.add_task.call_args[0][0]
+ background_kwargs = mock_background_tasks.add_task.call_args[1]
+
+ # Execute the background function to verify analytics logic
+ await background_fn(**background_kwargs)
+
+ # Verify analytics service was called correctly
+ mock_analytics.identify_user.assert_called_once()
+ identify_kwargs = mock_analytics.identify_user.call_args.kwargs
+ assert identify_kwargs['ctx'].user_id == 'test_user_id'
+ assert identify_kwargs['ctx'].consented is True
+ assert identify_kwargs['idp'] == 'github'
+
+ mock_analytics.track_user_logged_in.assert_called_once()
+ track_kwargs = mock_analytics.track_user_logged_in.call_args.kwargs
+ assert track_kwargs['ctx'].user_id == 'test_user_id'
+ assert track_kwargs['ctx'].org_id == 'test_org_id'
+ assert track_kwargs['ctx'].consented is True
+ assert track_kwargs['idp'] == 'github'
@pytest.mark.asyncio
async def test_keycloak_callback_email_not_verified(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when email is not verified."""
# Arrange
@@ -290,6 +344,7 @@ async def test_keycloak_callback_email_not_verified(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -313,7 +368,7 @@ async def test_keycloak_callback_email_not_verified(
@pytest.mark.asyncio
async def test_keycloak_callback_email_not_verified_missing_field(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when email_verified field is missing (defaults to False)."""
# Arrange
@@ -352,6 +407,7 @@ async def test_keycloak_callback_email_not_verified_missing_field(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -367,7 +423,7 @@ async def test_keycloak_callback_email_not_verified_missing_field(
@pytest.mark.asyncio
async def test_keycloak_callback_email_verification_rate_limited(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when email verification is rate limited.
@@ -417,6 +473,7 @@ async def test_keycloak_callback_email_verification_rate_limited(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -435,9 +492,14 @@ async def test_keycloak_callback_email_verification_rate_limited(
@pytest.mark.asyncio
async def test_keycloak_callback_success_without_offline_token(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test successful keycloak_callback without valid offline token."""
+ mock_analytics = MagicMock()
+ mock_org = MagicMock()
+ mock_org.id = 'test_org_id'
+ mock_org.name = 'Test Org'
+
with (
patch('server.routes.auth.token_manager') as mock_token_manager,
patch('server.routes.auth.set_response_cookie') as mock_set_cookie,
@@ -447,18 +509,35 @@ async def test_keycloak_callback_success_without_offline_token(
patch('server.routes.auth.KEYCLOAK_REALM_NAME', 'test-realm'),
patch('server.routes.auth.KEYCLOAK_CLIENT_ID', 'test-client'),
patch('server.routes.auth.UserStore') as mock_user_store,
- patch('server.routes.auth.posthog') as mock_posthog,
+ patch('server.routes.auth.get_analytics_service', return_value=mock_analytics),
+ patch(
+ 'storage.org_store.OrgStore.get_org_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_org,
+ ),
+ patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org],
+ ),
+ patch(
+ 'storage.org_member_store.OrgMemberStore.get_org_members_count',
+ new_callable=AsyncMock,
+ return_value=1,
+ ),
patch(
'server.routes.auth._should_redirect_to_onboarding',
new_callable=AsyncMock,
return_value=False,
),
):
- # Mock user with accepted_tos
+ # Mock user with accepted_tos and analytics consent
mock_user = MagicMock()
mock_user.id = 'test_user_id'
mock_user.current_org_id = 'test_org_id'
mock_user.accepted_tos = '2025-01-01'
+ mock_user.user_consents_to_analytics = True
+ mock_user.org_members = []
# Setup UserStore mocks
mock_user_store.get_user_by_id = AsyncMock(return_value=mock_user)
@@ -486,6 +565,7 @@ async def test_keycloak_callback_success_without_offline_token(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -508,12 +588,33 @@ async def test_keycloak_callback_success_without_offline_token(
secure=False,
accepted_tos=True,
)
- mock_posthog.set.assert_called_once()
+
+ # Verify background task was scheduled and execute it to test analytics
+ mock_background_tasks.add_task.assert_called_once()
+ background_fn = mock_background_tasks.add_task.call_args[0][0]
+ background_kwargs = mock_background_tasks.add_task.call_args[1]
+
+ # Execute the background function to verify analytics logic
+ await background_fn(**background_kwargs)
+
+ # Verify analytics service was called correctly
+ mock_analytics.identify_user.assert_called_once()
+ identify_kwargs = mock_analytics.identify_user.call_args.kwargs
+ assert identify_kwargs['ctx'].user_id == 'test_user_id'
+ assert identify_kwargs['ctx'].consented is True
+ assert identify_kwargs['idp'] == 'github'
+
+ mock_analytics.track_user_logged_in.assert_called_once()
+ track_kwargs = mock_analytics.track_user_logged_in.call_args.kwargs
+ assert track_kwargs['ctx'].user_id == 'test_user_id'
+ assert track_kwargs['ctx'].org_id == 'test_org_id'
+ assert track_kwargs['ctx'].consented is True
+ assert track_kwargs['idp'] == 'github'
@pytest.mark.asyncio
async def test_keycloak_callback_redirects_to_keycloak_when_offline_token_invalid(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that keycloak_callback redirects to Keycloak when offline token is invalid.
@@ -529,7 +630,8 @@ async def test_keycloak_callback_redirects_to_keycloak_when_offline_token_invali
patch('server.routes.auth.KEYCLOAK_REALM_NAME', 'test-realm'),
patch('server.routes.auth.KEYCLOAK_CLIENT_ID', 'test-client'),
patch('server.routes.auth.UserStore') as mock_user_store,
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.auth.OrgInvitationService') as mock_invitation_service,
patch(
'server.routes.auth._should_redirect_to_onboarding',
@@ -577,6 +679,7 @@ async def test_keycloak_callback_redirects_to_keycloak_when_offline_token_invali
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -594,7 +697,9 @@ async def test_keycloak_callback_redirects_to_keycloak_when_offline_token_invali
@pytest.mark.asyncio
-async def test_keycloak_callback_account_linking_error(mock_request):
+async def test_keycloak_callback_account_linking_error(
+ mock_request, mock_background_tasks
+):
"""Test keycloak_callback with account linking error."""
# Test the case where error is 'temporarily_unavailable' and error_description is 'authentication_expired'
result = await keycloak_callback(
@@ -603,6 +708,7 @@ async def test_keycloak_callback_account_linking_error(mock_request):
error='temporarily_unavailable',
error_description='authentication_expired',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -668,7 +774,7 @@ async def test_keycloak_offline_callback_missing_user_info(mock_request):
@pytest.mark.asyncio
async def test_keycloak_offline_callback_success(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test successful keycloak_offline_callback."""
with (
@@ -710,7 +816,7 @@ async def test_keycloak_offline_callback_success(
@pytest.mark.asyncio
async def test_keycloak_offline_callback_redirects_to_onboarding(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_offline_callback redirects to onboarding when needed."""
with (
@@ -819,7 +925,7 @@ async def test_logout_without_refresh_token():
@pytest.mark.asyncio
async def test_keycloak_callback_blocked_email_domain(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when user authorization fails (blocked email domain)."""
# Arrange
@@ -859,6 +965,7 @@ async def test_keycloak_callback_blocked_email_domain(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=mock_authorizer,
)
@@ -879,7 +986,9 @@ async def test_keycloak_callback_blocked_email_domain(
@pytest.mark.asyncio
-async def test_keycloak_callback_missing_email(mock_request, create_keycloak_user_info):
+async def test_keycloak_callback_missing_email(
+ mock_request, mock_background_tasks, create_keycloak_user_info
+):
"""Test keycloak_callback when user info does not contain email."""
# Arrange
with (
@@ -930,6 +1039,7 @@ async def test_keycloak_callback_missing_email(mock_request, create_keycloak_use
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -941,7 +1051,7 @@ async def test_keycloak_callback_missing_email(mock_request, create_keycloak_use
@pytest.mark.asyncio
async def test_keycloak_callback_duplicate_email_detected(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when duplicate email is detected by UserAuthorizer.
@@ -986,6 +1096,7 @@ async def test_keycloak_callback_duplicate_email_detected(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=mock_authorizer,
)
@@ -995,7 +1106,7 @@ async def test_keycloak_callback_duplicate_email_detected(
@pytest.mark.asyncio
async def test_keycloak_callback_duplicate_email_deletes_new_keycloak_user(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that new Keycloak user is deleted when duplicate email is detected.
@@ -1035,6 +1146,7 @@ async def test_keycloak_callback_duplicate_email_deletes_new_keycloak_user(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=mock_authorizer,
)
@@ -1046,7 +1158,7 @@ async def test_keycloak_callback_duplicate_email_deletes_new_keycloak_user(
@pytest.mark.asyncio
async def test_keycloak_callback_duplicate_email_preserves_existing_user(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that existing users are not deleted when duplicate email is detected.
@@ -1088,6 +1200,7 @@ async def test_keycloak_callback_duplicate_email_preserves_existing_user(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=mock_authorizer,
)
@@ -1099,7 +1212,7 @@ async def test_keycloak_callback_duplicate_email_preserves_existing_user(
@pytest.mark.asyncio
async def test_keycloak_callback_duplicate_check_exception(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when duplicate check raises exception."""
with (
@@ -1150,6 +1263,7 @@ async def test_keycloak_callback_duplicate_check_exception(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1161,7 +1275,7 @@ async def test_keycloak_callback_duplicate_check_exception(
@pytest.mark.asyncio
async def test_keycloak_callback_no_duplicate_email(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when authorization succeeds (no duplicate email).
@@ -1213,6 +1327,7 @@ async def test_keycloak_callback_no_duplicate_email(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(success=True),
)
@@ -1223,7 +1338,7 @@ async def test_keycloak_callback_no_duplicate_email(
@pytest.mark.asyncio
async def test_keycloak_callback_no_email_in_user_info(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test keycloak_callback when email is not in user_info."""
with (
@@ -1271,6 +1386,7 @@ async def test_keycloak_callback_no_email_in_user_info(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1286,7 +1402,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_verify_recaptcha_and_allow_login_when_score_is_high(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that login proceeds when reCAPTCHA score is high."""
# Arrange
@@ -1311,7 +1427,8 @@ class TestKeycloakCallbackRecaptcha:
'storage.user_authorization_store.UserAuthorizationStore'
) as mock_user_auth_store,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1364,6 +1481,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1374,7 +1492,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_block_login_when_recaptcha_score_is_low(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that login is blocked and redirected when reCAPTCHA score is low."""
# Arrange
@@ -1434,6 +1552,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1444,7 +1563,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_extract_ip_from_x_forwarded_for_header(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that IP is extracted from X-Forwarded-For header when present."""
# Arrange
@@ -1471,7 +1590,8 @@ class TestKeycloakCallbackRecaptcha:
) as mock_user_auth_store,
patch('server.routes.auth.a_session_maker') as mock_session_maker,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1524,6 +1644,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1533,7 +1654,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_use_client_host_when_x_forwarded_for_missing(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that client.host is used when X-Forwarded-For is missing."""
# Arrange
@@ -1561,7 +1682,8 @@ class TestKeycloakCallbackRecaptcha:
) as mock_user_auth_store,
patch('server.routes.auth.a_session_maker') as mock_session_maker,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1614,6 +1736,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1623,7 +1746,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_use_unknown_ip_when_client_is_none(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that 'unknown' IP is used when client is None."""
# Arrange
@@ -1650,7 +1773,8 @@ class TestKeycloakCallbackRecaptcha:
) as mock_user_auth_store,
patch('server.routes.auth.a_session_maker') as mock_session_maker,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1703,6 +1827,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1712,7 +1837,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_include_email_in_assessment_when_available(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that email is included in assessment when available."""
# Arrange
@@ -1736,7 +1861,8 @@ class TestKeycloakCallbackRecaptcha:
) as mock_user_auth_store,
patch('server.routes.auth.a_session_maker') as mock_session_maker,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1789,6 +1915,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1798,7 +1925,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_skip_recaptcha_when_site_key_not_configured(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that reCAPTCHA is skipped when RECAPTCHA_SITE_KEY is not configured."""
# Arrange
@@ -1819,7 +1946,8 @@ class TestKeycloakCallbackRecaptcha:
'storage.user_authorization_store.UserAuthorizationStore'
) as mock_user_auth_store,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1867,6 +1995,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1875,7 +2004,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_skip_recaptcha_when_token_is_missing(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that reCAPTCHA is skipped when token is missing from state."""
# Arrange
@@ -1890,7 +2019,8 @@ class TestKeycloakCallbackRecaptcha:
'storage.user_authorization_store.UserAuthorizationStore'
) as mock_user_auth_store,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.email.verify_email', new_callable=AsyncMock),
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -1938,6 +2068,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -1946,7 +2077,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_fail_open_when_recaptcha_service_throws_exception(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that login proceeds (fail open) when reCAPTCHA service throws exception."""
# Arrange
@@ -1967,7 +2098,8 @@ class TestKeycloakCallbackRecaptcha:
'storage.user_authorization_store.UserAuthorizationStore'
) as mock_user_auth_store,
patch('server.routes.auth.set_response_cookie'),
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
patch('server.routes.auth.logger') as mock_logger,
patch('server.routes.auth.UserStore') as mock_user_store,
):
@@ -2019,6 +2151,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -2034,7 +2167,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_should_log_warning_when_recaptcha_blocks_user(
- self, mock_request, create_keycloak_user_info
+ self, mock_request, mock_background_tasks, create_keycloak_user_info
):
"""Test that warning is logged when reCAPTCHA blocks user."""
# Arrange
@@ -2096,6 +2229,7 @@ class TestKeycloakCallbackRecaptcha:
code='test_code',
state=encoded_state,
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -2109,7 +2243,7 @@ class TestKeycloakCallbackRecaptcha:
@pytest.mark.asyncio
async def test_keycloak_callback_calls_backfill_user_email_for_existing_user(
- mock_request, create_keycloak_user_info
+ mock_request, mock_background_tasks, create_keycloak_user_info
):
"""When an existing user logs in, backfill_user_email should be called."""
user_info = create_keycloak_user_info(
@@ -2124,7 +2258,8 @@ async def test_keycloak_callback_calls_backfill_user_email_for_existing_user(
patch('server.routes.auth.token_manager') as mock_token_manager,
patch('server.routes.auth.set_response_cookie'),
patch('server.routes.auth.UserStore') as mock_user_store,
- patch('server.routes.auth.posthog'),
+ patch('server.routes.auth.get_analytics_service'),
+ patch('storage.org_store.OrgStore.get_org_by_id', new_callable=AsyncMock),
):
mock_user = MagicMock()
mock_user.id = 'test_user_id'
@@ -2148,6 +2283,7 @@ async def test_keycloak_callback_calls_backfill_user_email_for_existing_user(
code='test_code',
state='test_state',
request=mock_request,
+ background_tasks=mock_background_tasks,
user_authorizer=create_mock_user_authorizer(),
)
@@ -2275,3 +2411,324 @@ async def test_accept_tos_preserves_offline_flow_redirect(mock_request):
response_body = json.loads(result.body.decode())
assert response_body['redirect_url'] == offline_redirect_url
+
+
+# ---------------------------------------------------------------------------
+# Tests for _get_user_orgs_with_data helper function
+# ---------------------------------------------------------------------------
+
+
+async def test_get_user_orgs_with_data_returns_orgs():
+ """_get_user_orgs_with_data returns list of Org objects for given org_member_ids."""
+ from uuid import uuid4
+
+ from server.routes.auth import _get_user_orgs_with_data
+
+ org_id_1 = uuid4()
+ org_id_2 = uuid4()
+
+ mock_org_1 = MagicMock()
+ mock_org_1.id = org_id_1
+ mock_org_1.name = 'Org 1'
+
+ mock_org_2 = MagicMock()
+ mock_org_2.id = org_id_2
+ mock_org_2.name = 'Org 2'
+
+ with patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org_1, mock_org_2],
+ ):
+ result = await _get_user_orgs_with_data('user-123', [org_id_1, org_id_2])
+
+ assert len(result) == 2
+ assert result[0].name == 'Org 1'
+ assert result[1].name == 'Org 2'
+
+
+async def test_get_user_orgs_with_data_returns_only_found_orgs():
+ """_get_user_orgs_with_data returns only orgs that exist."""
+ from uuid import uuid4
+
+ from server.routes.auth import _get_user_orgs_with_data
+
+ org_id_1 = uuid4()
+ org_id_2 = uuid4()
+
+ mock_org_1 = MagicMock()
+ mock_org_1.id = org_id_1
+ mock_org_1.name = 'Org 1'
+
+ # get_orgs_by_ids only returns orgs that exist (org_id_2 not found)
+ with patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org_1],
+ ):
+ result = await _get_user_orgs_with_data('user-123', [org_id_1, org_id_2])
+
+ assert len(result) == 1
+ assert result[0].name == 'Org 1'
+
+
+async def test_get_user_orgs_with_data_handles_exception_gracefully():
+ """_get_user_orgs_with_data catches exceptions and returns empty list."""
+ from uuid import uuid4
+
+ from server.routes.auth import _get_user_orgs_with_data
+
+ org_id_1 = uuid4()
+ org_id_2 = uuid4()
+
+ with patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ side_effect=RuntimeError('Database error'),
+ ):
+ result = await _get_user_orgs_with_data('user-123', [org_id_1, org_id_2])
+
+ # Should return empty list on exception
+ assert result == []
+
+
+async def test_get_user_orgs_with_data_returns_empty_list_for_empty_input():
+ """_get_user_orgs_with_data returns empty list when no org_member_ids provided."""
+ from server.routes.auth import _get_user_orgs_with_data
+
+ result = await _get_user_orgs_with_data('user-123', [])
+ assert result == []
+
+
+# ---------------------------------------------------------------------------
+# Tests for _track_login_analytics_background helper function
+# ---------------------------------------------------------------------------
+
+
+async def test_track_login_analytics_background_calls_identify_and_track():
+ """_track_login_analytics_background calls identify_user and track_user_logged_in."""
+ from uuid import uuid4
+
+ from server.routes.auth import _track_login_analytics_background
+
+ current_org_id = uuid4()
+ org_member_id = uuid4()
+
+ mock_analytics = MagicMock()
+ mock_analytics.identify_user = MagicMock()
+ mock_analytics.track_user_logged_in = MagicMock()
+
+ mock_org = MagicMock()
+ mock_org.id = org_member_id
+ mock_org.name = 'Test Org'
+
+ with (
+ patch('server.routes.auth.get_analytics_service', return_value=mock_analytics),
+ patch(
+ 'storage.org_store.OrgStore.get_org_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_org,
+ ),
+ patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org],
+ ),
+ patch(
+ 'storage.org_member_store.OrgMemberStore.get_org_members_count',
+ new_callable=AsyncMock,
+ return_value=5,
+ ),
+ ):
+ await _track_login_analytics_background(
+ user_id='user-123',
+ idp='github',
+ current_org_id=current_org_id,
+ org_member_ids=[org_member_id],
+ consented=True,
+ )
+
+ mock_analytics.identify_user.assert_called_once()
+ mock_analytics.track_user_logged_in.assert_called_once()
+
+ # Verify identify_user call
+ identify_kwargs = mock_analytics.identify_user.call_args.kwargs
+ assert identify_kwargs['ctx'].user_id == 'user-123'
+ assert identify_kwargs['ctx'].consented is True
+ assert identify_kwargs['email'] == '[email protected]'
+ assert identify_kwargs['idp'] == 'github'
+
+ # Verify track_user_logged_in call
+ track_kwargs = mock_analytics.track_user_logged_in.call_args.kwargs
+ assert track_kwargs['ctx'].user_id == 'user-123'
+ assert track_kwargs['ctx'].consented is True
+ assert track_kwargs['idp'] == 'github'
+
+
+async def test_track_login_analytics_background_skips_when_no_analytics_service():
+ """_track_login_analytics_background returns early when analytics service is None."""
+ from server.routes.auth import _track_login_analytics_background
+
+ with patch('server.routes.auth.get_analytics_service', return_value=None):
+ # Should not raise
+ await _track_login_analytics_background(
+ user_id='user-123',
+ idp='github',
+ current_org_id=None,
+ org_member_ids=[],
+ consented=True,
+ )
+
+
+async def test_track_login_analytics_background_handles_org_id_none():
+ """_track_login_analytics_background handles None current_org_id."""
+ from server.routes.auth import _track_login_analytics_background
+
+ mock_analytics = MagicMock()
+ mock_analytics.identify_user = MagicMock()
+ mock_analytics.track_user_logged_in = MagicMock()
+
+ with patch('server.routes.auth.get_analytics_service', return_value=mock_analytics):
+ await _track_login_analytics_background(
+ user_id='user-123',
+ idp='github',
+ current_org_id=None,
+ org_member_ids=[],
+ consented=True,
+ )
+
+ identify_kwargs = mock_analytics.identify_user.call_args.kwargs
+ assert identify_kwargs['ctx'].org_id is None
+ assert identify_kwargs['org_name'] is None
+
+
+async def test_track_login_analytics_background_handles_exception_gracefully():
+ """_track_login_analytics_background catches exceptions and does not raise."""
+ from server.routes.auth import _track_login_analytics_background
+
+ mock_analytics = MagicMock()
+ mock_analytics.identify_user.side_effect = RuntimeError('PostHog error')
+
+ with patch('server.routes.auth.get_analytics_service', return_value=mock_analytics):
+ # Should not raise
+ await _track_login_analytics_background(
+ user_id='user-123',
+ idp='github',
+ current_org_id=None,
+ org_member_ids=[],
+ consented=True,
+ )
+
+
+async def test_track_login_analytics_background_builds_orgs_data_with_member_count():
+ """_track_login_analytics_background builds orgs_data list with member counts."""
+ from uuid import uuid4
+
+ from server.routes.auth import _track_login_analytics_background
+
+ org_id = uuid4()
+
+ mock_analytics = MagicMock()
+ mock_analytics.identify_user = MagicMock()
+ mock_analytics.track_user_logged_in = MagicMock()
+
+ mock_org = MagicMock()
+ mock_org.id = org_id
+ mock_org.name = 'Test Org'
+
+ with (
+ patch('server.routes.auth.get_analytics_service', return_value=mock_analytics),
+ patch(
+ 'storage.org_store.OrgStore.get_org_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_org,
+ ),
+ patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org],
+ ),
+ patch(
+ 'storage.org_member_store.OrgMemberStore.get_org_members_count',
+ new_callable=AsyncMock,
+ return_value=10,
+ ),
+ ):
+ await _track_login_analytics_background(
+ user_id='user-123',
+ idp='github',
+ current_org_id=None,
+ org_member_ids=[org_id],
+ consented=True,
+ )
+
+ identify_kwargs = mock_analytics.identify_user.call_args.kwargs
+ orgs = identify_kwargs['orgs']
+ assert len(orgs) == 1
+ assert orgs[0]['id'] == str(org_id)
+ assert orgs[0]['name'] == 'Test Org'
+ assert orgs[0]['member_count'] == 10
+
+
+async def test_track_login_analytics_background_handles_member_count_error():
+ """_track_login_analytics_background sets member_count to None on error."""
+ from uuid import uuid4
+
+ from server.routes.auth import _track_login_analytics_background
+
+ org_id = uuid4()
+
+ mock_analytics = MagicMock()
+ mock_analytics.identify_user = MagicMock()
+ mock_analytics.track_user_logged_in = MagicMock()
+
+ mock_org = MagicMock()
+ mock_org.id = org_id
+ mock_org.name = 'Test Org'
+
+ with (
+ patch('server.routes.auth.get_analytics_service', return_value=mock_analytics),
+ patch(
+ 'storage.org_store.OrgStore.get_org_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_org,
+ ),
+ patch(
+ 'storage.org_store.OrgStore.get_orgs_by_ids',
+ new_callable=AsyncMock,
+ return_value=[mock_org],
+ ),
+ patch(
+ 'storage.org_member_store.OrgMemberStore.get_org_members_count',
+ new_callable=AsyncMock,
+ side_effect=RuntimeError('DB error'),
+ ),
+ ):
+ await _track_login_analytics_background(
+ user_id='user-123',
+ idp='github',
+ current_org_id=None,
+ org_member_ids=[org_id],
+ consented=True,
+ )
+
+ identify_kwargs = mock_analytics.identify_user.call_args.kwargs
+ orgs = identify_kwargs['orgs']
+ assert len(orgs) == 1
+ assert orgs[0]['member_count'] is None
diff --git a/enterprise/tests/unit/test_billing.py b/enterprise/tests/unit/test_billing.py
index 5f92cd383a..b6ed0b9575 100644
--- a/enterprise/tests/unit/test_billing.py
+++ b/enterprise/tests/unit/test_billing.py
@@ -615,3 +615,246 @@ async def test_create_customer_setup_session_success():
success_url='https://test.com?setup=success',
cancel_url='https://test.com',
)
+
+
+# ---------------------------------------------------------------------------
+# Tests for analytics tracking in success_callback
+# ---------------------------------------------------------------------------
+
+
+async def test_success_callback_tracks_credit_purchased_analytics(
+ async_session_maker, test_org, test_user
+):
+ """Test that success_callback calls track_credit_purchased on analytics service."""
+ mock_request = Request(scope={'type': 'http'})
+ mock_request._url = URL('http://test.com/')
+
+ session_id = 'test_analytics_session'
+ async with async_session_maker() as session:
+ billing_session = BillingSession(
+ id=session_id,
+ user_id=str(test_user.id),
+ org_id=test_org.id,
+ status='in_progress',
+ price=50,
+ price_code='NA',
+ )
+ session.add(billing_session)
+ await session.commit()
+
+ mock_analytics = MagicMock()
+ mock_analytics.track_credit_purchased = MagicMock()
+
+ mock_user = MagicMock()
+ mock_user.current_org_id = test_org.id
+ mock_user.user_consents_to_analytics = True
+
+ with (
+ patch('server.routes.billing.a_session_maker', async_session_maker),
+ patch('stripe.checkout.Session.retrieve') as mock_stripe_retrieve,
+ patch(
+ 'storage.user_store.UserStore.get_user_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_user,
+ ),
+ patch(
+ 'storage.lite_llm_manager.LiteLlmManager.get_user_team_info',
+ return_value={
+ 'spend': 10.0,
+ 'max_budget_in_team': 100.0,
+ },
+ ),
+ patch('storage.lite_llm_manager.LiteLlmManager.update_team_and_users_budget'),
+ patch(
+ 'server.routes.billing.get_analytics_service', return_value=mock_analytics
+ ),
+ ):
+ mock_stripe_retrieve.return_value = MagicMock(
+ status='complete', amount_subtotal=5000, customer='mock_customer_id'
+ )
+
+ await success_callback(session_id, mock_request)
+
+ mock_analytics.track_credit_purchased.assert_called_once()
+ call_kwargs = mock_analytics.track_credit_purchased.call_args.kwargs
+ assert call_kwargs['ctx'].user_id == str(test_user.id)
+ assert call_kwargs['ctx'].consented is True
+ assert call_kwargs['amount_usd'] == 50.0
+ assert call_kwargs['credit_balance_before'] == 100.0
+ assert call_kwargs['credit_balance_after'] == 150.0
+
+
+async def test_success_callback_skips_analytics_when_service_is_none(
+ async_session_maker, test_org, test_user
+):
+ """Test that success_callback doesn't fail when analytics service is None."""
+ mock_request = Request(scope={'type': 'http'})
+ mock_request._url = URL('http://test.com/')
+
+ session_id = 'test_no_analytics_session'
+ async with async_session_maker() as session:
+ billing_session = BillingSession(
+ id=session_id,
+ user_id=str(test_user.id),
+ org_id=test_org.id,
+ status='in_progress',
+ price=25,
+ price_code='NA',
+ )
+ session.add(billing_session)
+ await session.commit()
+
+ mock_user = MagicMock()
+ mock_user.current_org_id = test_org.id
+ mock_user.user_consents_to_analytics = True
+
+ with (
+ patch('server.routes.billing.a_session_maker', async_session_maker),
+ patch('stripe.checkout.Session.retrieve') as mock_stripe_retrieve,
+ patch(
+ 'storage.user_store.UserStore.get_user_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_user,
+ ),
+ patch(
+ 'storage.lite_llm_manager.LiteLlmManager.get_user_team_info',
+ return_value={
+ 'spend': 0.0,
+ 'max_budget_in_team': 50.0,
+ },
+ ),
+ patch('storage.lite_llm_manager.LiteLlmManager.update_team_and_users_budget'),
+ patch('server.routes.billing.get_analytics_service', return_value=None),
+ ):
+ mock_stripe_retrieve.return_value = MagicMock(
+ status='complete', amount_subtotal=2500, customer='mock_customer_id'
+ )
+
+ # Should not raise even without analytics service
+ response = await success_callback(session_id, mock_request)
+ assert response.status_code == 302
+
+
+async def test_success_callback_analytics_respects_consent_false(
+ async_session_maker, test_org, test_user
+):
+ """Test that success_callback passes consented=False when user has not consented."""
+ mock_request = Request(scope={'type': 'http'})
+ mock_request._url = URL('http://test.com/')
+
+ session_id = 'test_no_consent_session'
+ async with async_session_maker() as session:
+ billing_session = BillingSession(
+ id=session_id,
+ user_id=str(test_user.id),
+ org_id=test_org.id,
+ status='in_progress',
+ price=25,
+ price_code='NA',
+ )
+ session.add(billing_session)
+ await session.commit()
+
+ mock_analytics = MagicMock()
+ mock_analytics.track_credit_purchased = MagicMock()
+
+ mock_user = MagicMock()
+ mock_user.current_org_id = test_org.id
+ mock_user.user_consents_to_analytics = False # User has NOT consented
+
+ with (
+ patch('server.routes.billing.a_session_maker', async_session_maker),
+ patch('stripe.checkout.Session.retrieve') as mock_stripe_retrieve,
+ patch(
+ 'storage.user_store.UserStore.get_user_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_user,
+ ),
+ patch(
+ 'storage.lite_llm_manager.LiteLlmManager.get_user_team_info',
+ return_value={
+ 'spend': 0.0,
+ 'max_budget_in_team': 50.0,
+ },
+ ),
+ patch('storage.lite_llm_manager.LiteLlmManager.update_team_and_users_budget'),
+ patch(
+ 'server.routes.billing.get_analytics_service', return_value=mock_analytics
+ ),
+ ):
+ mock_stripe_retrieve.return_value = MagicMock(
+ status='complete', amount_subtotal=2500, customer='mock_customer_id'
+ )
+
+ await success_callback(session_id, mock_request)
+
+ call_kwargs = mock_analytics.track_credit_purchased.call_args.kwargs
+ assert call_kwargs['ctx'].consented is False
+
+
+async def test_success_callback_analytics_exception_does_not_fail_checkout(
+ async_session_maker, test_org, test_user
+):
+ """Test that analytics exception doesn't prevent successful checkout completion."""
+ mock_request = Request(scope={'type': 'http'})
+ mock_request._url = URL('http://test.com/')
+
+ session_id = 'test_analytics_error_session'
+ async with async_session_maker() as session:
+ billing_session = BillingSession(
+ id=session_id,
+ user_id=str(test_user.id),
+ org_id=test_org.id,
+ status='in_progress',
+ price=25,
+ price_code='NA',
+ )
+ session.add(billing_session)
+ await session.commit()
+
+ mock_analytics = MagicMock()
+ mock_analytics.track_credit_purchased.side_effect = RuntimeError('PostHog error')
+
+ mock_user = MagicMock()
+ mock_user.current_org_id = test_org.id
+ mock_user.user_consents_to_analytics = True
+
+ with (
+ patch('server.routes.billing.a_session_maker', async_session_maker),
+ patch('stripe.checkout.Session.retrieve') as mock_stripe_retrieve,
+ patch(
+ 'storage.user_store.UserStore.get_user_by_id',
+ new_callable=AsyncMock,
+ return_value=mock_user,
+ ),
+ patch(
+ 'storage.lite_llm_manager.LiteLlmManager.get_user_team_info',
+ return_value={
+ 'spend': 0.0,
+ 'max_budget_in_team': 50.0,
+ },
+ ),
+ patch('storage.lite_llm_manager.LiteLlmManager.update_team_and_users_budget'),
+ patch(
+ 'server.routes.billing.get_analytics_service', return_value=mock_analytics
+ ),
+ ):
+ mock_stripe_retrieve.return_value = MagicMock(
+ status='complete', amount_subtotal=2500, customer='mock_customer_id'
+ )
+
+ # Should not raise even when analytics fails
+ response = await success_callback(session_id, mock_request)
+ assert response.status_code == 302
+
+ # Verify database was still updated
+ async with async_session_maker() as session:
+ result = await session.execute(
+ select(BillingSession).where(BillingSession.id == session_id)
+ )
+ billing_session = result.scalar_one_or_none()
+ assert billing_session.status == 'completed'
diff --git a/enterprise/tests/unit/test_posthog_session_middleware.py b/enterprise/tests/unit/test_posthog_session_middleware.py
new file mode 100644
index 0000000000..ada27835c4
--- /dev/null
+++ b/enterprise/tests/unit/test_posthog_session_middleware.py
@@ -0,0 +1,97 @@
+"""Tests for PostHogSessionMiddleware."""
+
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from fastapi import Request, Response
+
+
+def mock_response():
+ return MagicMock(spec=Response)
+
+
+def make_mock_request(headers: dict | None = None):
+ """Create a mock FastAPI Request with a state object and headers dict."""
+ request = MagicMock(spec=Request)
+ request.headers = headers or {}
+ request.state = MagicMock()
+ return request
+
+
+async def test_middleware_sets_session_id_from_header(mock_response):
+ """PostHogSessionMiddleware sets posthog_session_id from X-POSTHOG-SESSION-ID header."""
+ from server.middleware import PostHogSessionMiddleware
+
+ session_id = 'sess_abc123'
+ request = make_mock_request({'X-POSTHOG-SESSION-ID': session_id})
+ call_next = AsyncMock(return_value=mock_response)
+
+ middleware = PostHogSessionMiddleware()
+ result = await middleware(request, call_next)
+
+ assert request.state.posthog_session_id == session_id
+ call_next.assert_called_once_with(request)
+ assert result == mock_response
+
+
+async def test_middleware_sets_none_when_header_absent(mock_response):
+ """PostHogSessionMiddleware sets posthog_session_id to None when header is absent."""
+ from server.middleware import PostHogSessionMiddleware
+
+ request = make_mock_request({}) # No X-POSTHOG-SESSION-ID header
+ call_next = AsyncMock(return_value=mock_response)
+
+ middleware = PostHogSessionMiddleware()
+ result = await middleware(request, call_next)
+
+ assert request.state.posthog_session_id is None
+ call_next.assert_called_once_with(request)
+ assert result == mock_response
+
+
+async def test_middleware_does_not_modify_response(mock_response):
+ """PostHogSessionMiddleware returns the response unchanged."""
+ from server.middleware import PostHogSessionMiddleware
+
+ request = make_mock_request({'X-POSTHOG-SESSION-ID': 'sess_xyz'})
+ call_next = AsyncMock(return_value=mock_response)
+
+ middleware = PostHogSessionMiddleware()
+ result = await middleware(request, call_next)
+
+ assert result is mock_response
+
+
+async def test_middleware_does_not_block_request(mock_response):
+ """PostHogSessionMiddleware always calls call_next (never blocks)."""
+ from server.middleware import PostHogSessionMiddleware
+
+ request = make_mock_request({})
+ call_next = AsyncMock(return_value=mock_response)
+
+ middleware = PostHogSessionMiddleware()
+ await middleware(request, call_next)
+
+ call_next.assert_called_once_with(request)
+
+
+async def test_middleware_handles_case_insensitive_header(mock_response):
+ """PostHogSessionMiddleware uses .get() which handles header lookup."""
+ from server.middleware import PostHogSessionMiddleware
+
+ # FastAPI/Starlette Headers are case-insensitive, but we test with dict mock
+ # Test the exact header name used in the implementation
+ session_id = 'sess_case_test'
+ request = make_mock_request({'X-POSTHOG-SESSION-ID': session_id})
+ call_next = AsyncMock(return_value=mock_response)
+
+ middleware = PostHogSessionMiddleware()
+ await middleware(request, call_next)
+
+ assert request.state.posthog_session_id == session_id
diff --git a/enterprise/tests/unit/test_saas_lifespan.py b/enterprise/tests/unit/test_saas_lifespan.py
new file mode 100644
index 0000000000..119007ddfc
--- /dev/null
+++ b/enterprise/tests/unit/test_saas_lifespan.py
@@ -0,0 +1,108 @@
+"""Tests for SaasAppLifespanService."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def mock_analytics_service():
+ svc = MagicMock()
+ svc.shutdown = MagicMock()
+ return svc
+
+
+async def test_aenter_calls_init_analytics_service():
+ """SaasAppLifespanService.__aenter__ initializes the analytics service."""
+ from server.app_lifespan.saas_app_lifespan_service import SaasAppLifespanService
+
+ with patch(
+ 'server.app_lifespan.saas_app_lifespan_service.init_analytics_service'
+ ) as mock_init:
+ svc = SaasAppLifespanService()
+ await svc.__aenter__()
+ mock_init.assert_called_once()
+
+
+async def test_aenter_passes_env_vars_to_init():
+ """SaasAppLifespanService reads config from env vars."""
+ from server.app_lifespan.saas_app_lifespan_service import SaasAppLifespanService
+
+ with (
+ patch(
+ 'server.app_lifespan.saas_app_lifespan_service.init_analytics_service'
+ ) as mock_init,
+ patch.dict(
+ 'os.environ',
+ {
+ 'POSTHOG_CLIENT_KEY': 'test-key',
+ 'POSTHOG_HOST': 'https://test.posthog.com',
+ 'OPENHANDS_CONFIG_CLS': 'enterprise.server.config.SaaSServerConfig',
+ },
+ ),
+ ):
+ svc = SaasAppLifespanService()
+ await svc.__aenter__()
+
+ call_kwargs = mock_init.call_args
+ assert call_kwargs.kwargs['api_key'] == 'test-key'
+ assert call_kwargs.kwargs['host'] == 'https://test.posthog.com'
+
+
+async def test_aexit_calls_shutdown_when_service_exists(mock_analytics_service):
+ """SaasAppLifespanService.__aexit__ calls shutdown on the analytics service."""
+ from server.app_lifespan.saas_app_lifespan_service import SaasAppLifespanService
+
+ with (
+ patch('server.app_lifespan.saas_app_lifespan_service.init_analytics_service'),
+ patch(
+ 'server.app_lifespan.saas_app_lifespan_service.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ ):
+ svc = SaasAppLifespanService()
+ await svc.__aenter__()
+ await svc.__aexit__(None, None, None)
+
+ mock_analytics_service.shutdown.assert_called_once()
+
+
+async def test_aexit_does_not_raise_when_service_is_none():
+ """SaasAppLifespanService.__aexit__ does not raise if analytics service is None."""
+ from server.app_lifespan.saas_app_lifespan_service import SaasAppLifespanService
+
+ with (
+ patch('server.app_lifespan.saas_app_lifespan_service.init_analytics_service'),
+ patch(
+ 'server.app_lifespan.saas_app_lifespan_service.get_analytics_service',
+ return_value=None,
+ ),
+ ):
+ svc = SaasAppLifespanService()
+ await svc.__aenter__()
+ # Must not raise
+ await svc.__aexit__(None, None, None)
+
+
+async def test_aexit_does_not_raise_on_shutdown_error(mock_analytics_service):
+ """SaasAppLifespanService.__aexit__ swallows errors from shutdown."""
+ from server.app_lifespan.saas_app_lifespan_service import SaasAppLifespanService
+
+ mock_analytics_service.shutdown.side_effect = RuntimeError('connection closed')
+
+ with (
+ patch('server.app_lifespan.saas_app_lifespan_service.init_analytics_service'),
+ patch(
+ 'server.app_lifespan.saas_app_lifespan_service.get_analytics_service',
+ return_value=mock_analytics_service,
+ ),
+ ):
+ svc = SaasAppLifespanService()
+ await svc.__aenter__()
+ # Must not raise even if shutdown errors
+ await svc.__aexit__(None, None, None)
diff --git a/frontend/__tests__/components/context-menu/context-menu-cta.test.tsx b/frontend/__tests__/components/context-menu/context-menu-cta.test.tsx
index ba80c81410..20402eaae0 100644
--- a/frontend/__tests__/components/context-menu/context-menu-cta.test.tsx
+++ b/frontend/__tests__/components/context-menu/context-menu-cta.test.tsx
@@ -1,13 +1,11 @@
import { render, screen } from "@testing-library/react";
import { describe, expect, it, vi } from "vitest";
-import userEvent from "@testing-library/user-event";
import { ContextMenuCTA } from "#/components/features/context-menu/context-menu-cta";
-// Mock useTracking hook
-const mockTrackSaasSelfhostedInquiry = vi.fn();
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackSaasSelfhostedInquiry: mockTrackSaasSelfhostedInquiry,
+vi.mock("#/hooks/use-client-analytics", () => ({
+ useClientAnalytics: () => ({
+ trackSaasSelfhostedInquiry: vi.fn(),
+ trackEnterpriseLeadFormSubmitted: vi.fn(),
}),
}));
@@ -20,20 +18,6 @@ describe("ContextMenuCTA", () => {
expect(screen.getByText("CTA$LEARN_MORE")).toBeInTheDocument();
});
- it("should call trackSaasSelfhostedInquiry with location 'context_menu' when Learn More is clicked", async () => {
- const user = userEvent.setup();
- render(<ContextMenuCTA />);
-
- const learnMoreLink = screen.getByRole("link", {
- name: "CTA$LEARN_MORE",
- });
- await user.click(learnMoreLink);
-
- expect(mockTrackSaasSelfhostedInquiry).toHaveBeenCalledWith({
- location: "context_menu",
- });
- });
-
it("should render Learn More as a link with correct href and target", () => {
render(<ContextMenuCTA />);
diff --git a/frontend/__tests__/components/features/auth/login-content.test.tsx b/frontend/__tests__/components/features/auth/login-content.test.tsx
index 8aadc507cb..64c706d40e 100644
--- a/frontend/__tests__/components/features/auth/login-content.test.tsx
+++ b/frontend/__tests__/components/features/auth/login-content.test.tsx
@@ -24,12 +24,6 @@ vi.mock("#/hooks/use-auth-url", () => ({
},
}));
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackLoginButtonClick: vi.fn(),
- }),
-}));
-
vi.mock("#/hooks/query/use-config", () => ({
useConfig: () => ({
data: undefined,
diff --git a/frontend/__tests__/components/features/auth/login-cta.test.tsx b/frontend/__tests__/components/features/auth/login-cta.test.tsx
index e1db11a2e4..c1ae93a763 100644
--- a/frontend/__tests__/components/features/auth/login-cta.test.tsx
+++ b/frontend/__tests__/components/features/auth/login-cta.test.tsx
@@ -4,11 +4,10 @@ import userEvent from "@testing-library/user-event";
import { createRoutesStub } from "react-router";
import { LoginCTA } from "#/components/features/auth/login-cta";
-// Mock useTracking hook
-const mockTrackSaasSelfhostedInquiry = vi.fn();
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackSaasSelfhostedInquiry: mockTrackSaasSelfhostedInquiry,
+vi.mock("#/hooks/use-client-analytics", () => ({
+ useClientAnalytics: () => ({
+ trackEnterpriseCTAClicked: vi.fn(),
+ trackEnterpriseLeadFormSubmitted: vi.fn(),
}),
}));
@@ -49,7 +48,7 @@ describe("LoginCTA", () => {
expect(screen.getByText("CTA$FEATURE_SUPPORT")).toBeInTheDocument();
});
- it("should track and navigate to information request page when Learn More is clicked", async () => {
+ it("should navigate to information request page when Learn More is clicked", async () => {
const user = userEvent.setup();
renderWithRouter();
@@ -58,9 +57,6 @@ describe("LoginCTA", () => {
});
await user.click(learnMoreLink);
- expect(mockTrackSaasSelfhostedInquiry).toHaveBeenCalledWith({
- location: "login_page",
- });
expect(screen.getByTestId("information-request-page")).toBeInTheDocument();
});
@@ -90,17 +86,4 @@ describe("LoginCTA", () => {
expect(learnMoreLink).toHaveAttribute("rel", "noopener noreferrer");
});
- it("should track device_verify location when Learn More is clicked in device verify mode", async () => {
- const user = userEvent.setup();
- renderWithRouter("device_verify");
-
- const learnMoreLink = screen.getByRole("link", {
- name: "CTA$LEARN_MORE",
- });
- await user.click(learnMoreLink);
-
- expect(mockTrackSaasSelfhostedInquiry).toHaveBeenCalledWith({
- location: "device_verify",
- });
- });
});
diff --git a/frontend/__tests__/components/features/home/homepage-cta.test.tsx b/frontend/__tests__/components/features/home/homepage-cta.test.tsx
index f44f6bd93b..fce819fd7e 100644
--- a/frontend/__tests__/components/features/home/homepage-cta.test.tsx
+++ b/frontend/__tests__/components/features/home/homepage-cta.test.tsx
@@ -23,19 +23,18 @@ vi.mock("react-i18next", async () => {
};
});
+vi.mock("#/hooks/use-client-analytics", () => ({
+ useClientAnalytics: () => ({
+ trackSaasSelfhostedInquiry: vi.fn(),
+ trackEnterpriseLeadFormSubmitted: vi.fn(),
+ }),
+}));
+
// Mock local storage
vi.mock("#/utils/local-storage", () => ({
setCTADismissed: vi.fn(),
}));
-// Mock useTracking hook
-const mockTrackSaasSelfhostedInquiry = vi.fn();
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackSaasSelfhostedInquiry: mockTrackSaasSelfhostedInquiry,
- }),
-}));
-
import { setCTADismissed } from "#/utils/local-storage";
describe("HomepageCTA", () => {
@@ -118,18 +117,6 @@ describe("HomepageCTA", () => {
});
describe("Learn More link behavior", () => {
- it("calls trackSaasSelfhostedInquiry with location 'home_page' when clicked", async () => {
- const user = userEvent.setup();
- renderHomepageCTA();
-
- const learnMoreLink = screen.getByRole("link", { name: "Learn More" });
- await user.click(learnMoreLink);
-
- expect(mockTrackSaasSelfhostedInquiry).toHaveBeenCalledWith({
- location: "home_page",
- });
- });
-
it("has correct href and target attributes", () => {
renderHomepageCTA();
diff --git a/frontend/__tests__/components/features/onboarding/information-request-form.test.tsx b/frontend/__tests__/components/features/onboarding/information-request-form.test.tsx
index 1082d44a96..eb62b948c3 100644
--- a/frontend/__tests__/components/features/onboarding/information-request-form.test.tsx
+++ b/frontend/__tests__/components/features/onboarding/information-request-form.test.tsx
@@ -9,11 +9,10 @@ import {
} from "#/components/features/onboarding/information-request-form";
import { EnterpriseFormData } from "#/utils/local-storage";
-// Mock useTracking
-const mockTrackEnterpriseLeadFormSubmitted = vi.fn();
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackEnterpriseLeadFormSubmitted: mockTrackEnterpriseLeadFormSubmitted,
+vi.mock("#/hooks/use-client-analytics", () => ({
+ useClientAnalytics: () => ({
+ trackSaasSelfhostedInquiry: vi.fn(),
+ trackEnterpriseLeadFormSubmitted: vi.fn(),
}),
}));
@@ -215,16 +214,6 @@ describe("InformationRequestForm", () => {
expect(screen.queryByTestId("login-page")).not.toBeInTheDocument();
});
- it("should not call tracking when form is submitted with empty fields", async () => {
- const user = userEvent.setup();
- renderWithRouter();
-
- const submitButton = screen.getByRole("button", { name: "ENTERPRISE$FORM_SUBMIT" });
- await user.click(submitButton);
-
- expect(mockTrackEnterpriseLeadFormSubmitted).not.toHaveBeenCalled();
- });
-
it("should navigate to login page when form is submitted with all fields filled", async () => {
const user = userEvent.setup();
renderWithRouter();
@@ -243,70 +232,6 @@ describe("InformationRequestForm", () => {
expect(screen.getByTestId("login-page")).toBeInTheDocument();
});
- it("should call tracking with form data when form is submitted successfully", async () => {
- const user = userEvent.setup();
- renderWithRouter({ ...defaultProps, requestType: "saas" });
-
- await user.type(screen.getByTestId("form-input-name"), "John Doe");
- await user.type(screen.getByTestId("form-input-company"), "Acme Inc");
- await user.type(screen.getByTestId("form-input-email"), "[email protected]");
- await user.type(screen.getByTestId("form-input-message"), "Hello world");
-
- const submitButton = screen.getByRole("button", { name: "ENTERPRISE$FORM_SUBMIT" });
- await user.click(submitButton);
-
- expect(mockTrackEnterpriseLeadFormSubmitted).toHaveBeenCalledTimes(1);
- expect(mockTrackEnterpriseLeadFormSubmitted).toHaveBeenCalledWith({
- requestType: "saas",
- name: "John Doe",
- company: "Acme Inc",
- email: "[email protected]",
- message: "Hello world",
- });
- });
-
- it("should call tracking with self-hosted request type", async () => {
- const user = userEvent.setup();
- renderWithRouter({ ...defaultProps, requestType: "self-hosted" });
-
- await user.type(screen.getByTestId("form-input-name"), "Jane Smith");
- await user.type(screen.getByTestId("form-input-company"), "Tech Corp");
- await user.type(screen.getByTestId("form-input-email"), "[email protected]");
- await user.type(screen.getByTestId("form-input-message"), "Interested in self-hosted");
-
- const submitButton = screen.getByRole("button", { name: "ENTERPRISE$FORM_SUBMIT" });
- await user.click(submitButton);
-
- expect(mockTrackEnterpriseLeadFormSubmitted).toHaveBeenCalledWith({
- requestType: "self-hosted",
- name: "Jane Smith",
- company: "Tech Corp",
- email: "[email protected]",
- message: "Interested in self-hosted",
- });
- });
-
- it("should trim whitespace from form fields before tracking", async () => {
- const user = userEvent.setup();
- renderWithRouter();
-
- await user.type(screen.getByTestId("form-input-name"), " John Doe ");
- await user.type(screen.getByTestId("form-input-company"), " Acme Inc ");
- await user.type(screen.getByTestId("form-input-email"), " [email protected] ");
- await user.type(screen.getByTestId("form-input-message"), " Hello world ");
-
- const submitButton = screen.getByRole("button", { name: "ENTERPRISE$FORM_SUBMIT" });
- await user.click(submitButton);
-
- expect(mockTrackEnterpriseLeadFormSubmitted).toHaveBeenCalledWith({
- requestType: "saas",
- name: "John Doe",
- company: "Acme Inc",
- email: "[email protected]",
- message: "Hello world",
- });
- });
-
it("should have valid aria-invalid state when field has value", async () => {
const user = userEvent.setup();
renderWithRouter();
@@ -335,7 +260,6 @@ describe("InformationRequestForm", () => {
// Should stay on form page, not navigate to login
expect(screen.getByTestId("information-request-form")).toBeInTheDocument();
expect(screen.queryByTestId("login-page")).not.toBeInTheDocument();
- expect(mockTrackEnterpriseLeadFormSubmitted).not.toHaveBeenCalled();
});
});
@@ -358,8 +282,6 @@ describe("InformationRequestForm", () => {
await user.click(submitButton);
await user.click(submitButton);
- // Should only track once
- expect(mockTrackEnterpriseLeadFormSubmitted).toHaveBeenCalledTimes(1);
// Should navigate to login page
expect(screen.getByTestId("login-page")).toBeInTheDocument();
});
diff --git a/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx b/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx
index 8d589ae65b..9e2c380bd7 100644
--- a/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx
+++ b/frontend/__tests__/components/features/onboarding/onboarding-form.test.tsx
@@ -12,7 +12,6 @@ import { onboardingService } from "#/api/onboarding-service/onboarding-service.a
const mockMutate = vi.fn();
const mockNavigate = vi.fn();
const mockUseMe = vi.fn();
-const mockTrackOnboardingCompleted = vi.fn();
// Loader data set in beforeEach for each test suite
let loaderData: { config: { app_mode: string; feature_flags: { deployment_mode: string } } };
@@ -35,12 +34,6 @@ vi.mock("#/hooks/query/use-me", () => ({
useMe: () => mockUseMe(),
}));
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackOnboardingCompleted: mockTrackOnboardingCompleted,
- }),
-}));
-
// Mocks for clientLoader tests
const mockQueryClientGetData = vi.fn();
const mockQueryClientSetData = vi.fn();
@@ -90,7 +83,6 @@ describe("OnboardingForm - Cloud Mode", () => {
beforeEach(() => {
mockMutate.mockClear();
mockNavigate.mockClear();
- mockTrackOnboardingCompleted.mockClear();
loaderData = {
config: {
app_mode: "saas",
@@ -194,28 +186,6 @@ describe("OnboardingForm - Cloud Mode", () => {
});
});
- it("should track onboarding completion to PostHog in cloud mode", async () => {
- const user = userEvent.setup();
- await renderOnboardingForm();
-
- // Complete the full cloud onboarding flow
- await user.click(screen.getByTestId("step-option-org_2_10"));
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-new_features"));
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-software_engineer"));
- await user.click(screen.getByRole("button", { name: /finish/i }));
-
- expect(mockTrackOnboardingCompleted).toHaveBeenCalledTimes(1);
- expect(mockTrackOnboardingCompleted).toHaveBeenCalledWith({
- role: "software_engineer",
- orgSize: "org_2_10",
- useCase: ["new_features"],
- });
- });
-
it("should render 5 options on step 1 (org size question)", async () => {
await renderOnboardingForm();
@@ -372,7 +342,6 @@ describe("OnboardingForm - Self-Hosted Mode", () => {
beforeEach(() => {
mockMutate.mockClear();
mockNavigate.mockClear();
- mockTrackOnboardingCompleted.mockClear();
loaderData = {
config: {
app_mode: "saas",
@@ -438,32 +407,6 @@ describe("OnboardingForm - Self-Hosted Mode", () => {
});
});
- it("should track onboarding completion in self-hosted mode", async () => {
- const user = userEvent.setup();
- await renderOnboardingForm();
-
- // Complete the full self-hosted onboarding flow (3 steps)
- const orgNameInput = screen.getByTestId("form-input-org_name");
- const orgDomainInput = screen.getByTestId("form-input-org_domain");
- await user.type(orgNameInput, "Test Company");
- await user.type(orgDomainInput, "test.com");
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-org_2_10"));
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-new_features"));
- await user.click(screen.getByRole("button", { name: /finish/i }));
-
- expect(mockTrackOnboardingCompleted).toHaveBeenCalledTimes(1);
- // Note: role is not included since role question is cloud-only
- expect(mockTrackOnboardingCompleted).toHaveBeenCalledWith({
- role: undefined,
- orgSize: "org_2_10",
- useCase: ["new_features"],
- });
- });
-
it("should show all 3 progress bars filled on the last step", async () => {
const user = userEvent.setup();
await renderOnboardingForm();
@@ -504,59 +447,6 @@ describe("OnboardingForm - Self-Hosted Mode", () => {
expect(nextButton).not.toBeDisabled();
});
- it("should NOT track onboarding completion for non-owners in self-hosted mode", async () => {
- // Override the mock to return a member (non-owner) role
- mockUseMe.mockReturnValue({ data: { role: "member" } });
-
- const user = userEvent.setup();
- await renderOnboardingForm();
-
- // Complete the full self-hosted onboarding flow (3 steps)
- const orgNameInput = screen.getByTestId("form-input-org_name");
- const orgDomainInput = screen.getByTestId("form-input-org_domain");
- await user.type(orgNameInput, "Test Company");
- await user.type(orgDomainInput, "test.com");
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-org_2_10"));
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-new_features"));
- await user.click(screen.getByRole("button", { name: /finish/i }));
-
- // Tracking should NOT be called for non-owners in self-hosted mode
- expect(mockTrackOnboardingCompleted).not.toHaveBeenCalled();
-
- // But onboarding submission should still work
- expect(mockMutate).toHaveBeenCalledTimes(1);
- });
-
- it("should NOT track onboarding completion for admins in self-hosted mode", async () => {
- // Override the mock to return an admin role
- mockUseMe.mockReturnValue({ data: { role: "admin" } });
-
- const user = userEvent.setup();
- await renderOnboardingForm();
-
- // Complete the full self-hosted onboarding flow (3 steps)
- const orgNameInput = screen.getByTestId("form-input-org_name");
- const orgDomainInput = screen.getByTestId("form-input-org_domain");
- await user.type(orgNameInput, "Test Company");
- await user.type(orgDomainInput, "test.com");
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-org_2_10"));
- await user.click(screen.getByRole("button", { name: /next/i }));
-
- await user.click(screen.getByTestId("step-option-new_features"));
- await user.click(screen.getByRole("button", { name: /finish/i }));
-
- // Tracking should NOT be called for admins in self-hosted mode (only owners)
- expect(mockTrackOnboardingCompleted).not.toHaveBeenCalled();
-
- // But onboarding submission should still work
- expect(mockMutate).toHaveBeenCalledTimes(1);
- });
});
describe("OnboardingForm - redirect when already onboarded", () => {
diff --git a/frontend/__tests__/components/features/user/user-context-menu.test.tsx b/frontend/__tests__/components/features/user/user-context-menu.test.tsx
index 4281fbbbe6..cb94615187 100644
--- a/frontend/__tests__/components/features/user/user-context-menu.test.tsx
+++ b/frontend/__tests__/components/features/user/user-context-menu.test.tsx
@@ -23,10 +23,10 @@ vi.mock("#/hooks/use-breakpoint", () => ({
useBreakpoint: vi.fn(() => false), // Default to desktop (not mobile)
}));
-// Mock useTracking hook for CTA
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
+vi.mock("#/hooks/use-client-analytics", () => ({
+ useClientAnalytics: () => ({
trackSaasSelfhostedInquiry: vi.fn(),
+ trackEnterpriseLeadFormSubmitted: vi.fn(),
}),
}));
diff --git a/frontend/__tests__/components/providers/posthog-wrapper.test.tsx b/frontend/__tests__/components/providers/posthog-wrapper.test.tsx
index 4d61f34935..66aa8c3de0 100644
--- a/frontend/__tests__/components/providers/posthog-wrapper.test.tsx
+++ b/frontend/__tests__/components/providers/posthog-wrapper.test.tsx
@@ -136,6 +136,28 @@ describe("PostHogWrapper", () => {
expect(sessionStorage.getItem("posthog_bootstrap")).toBeNull();
});
+ it("should initialize PostHog with health monitoring config (web vitals, error tracking, network timing)", async () => {
+ render(
+ <PostHogWrapper>
+ <div data-testid="child" />
+ </PostHogWrapper>,
+ );
+
+ await screen.findByTestId("child");
+
+ expect(mockPostHogProvider).toHaveBeenCalledWith(
+ expect.objectContaining({
+ options: expect.objectContaining({
+ capture_performance: {
+ network_timing: true,
+ web_vitals: true,
+ },
+ capture_exceptions: true,
+ }),
+ }),
+ );
+ });
+
it("should initialize without bootstrap when neither hash nor sessionStorage has IDs", async () => {
render(
<PostHogWrapper>
diff --git a/frontend/__tests__/hooks/mutation/use-create-conversation.test.tsx b/frontend/__tests__/hooks/mutation/use-create-conversation.test.tsx
index 0052960fff..9803a417f4 100644
--- a/frontend/__tests__/hooks/mutation/use-create-conversation.test.tsx
+++ b/frontend/__tests__/hooks/mutation/use-create-conversation.test.tsx
@@ -5,11 +5,20 @@ import V1ConversationService from "#/api/conversation-service/v1-conversation-se
import { useCreateConversation } from "#/hooks/mutation/use-create-conversation";
import { SuggestedTask } from "#/utils/types";
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackConversationCreated: vi.fn(),
- }),
-}));
+vi.mock("#/hooks/query/use-settings", async () => {
+ const actual = await vi.importActual<typeof import("#/hooks/query/use-settings")>(
+ "#/hooks/query/use-settings",
+ );
+ return {
+ ...actual,
+ useSettings: vi.fn().mockReturnValue({
+ data: {
+ v1_enabled: true,
+ },
+ isLoading: false,
+ }),
+ };
+});
describe("useCreateConversation", () => {
it("passes suggested tasks to the V1 create conversation API", async () => {
diff --git a/frontend/__tests__/posthog-tracking.test.tsx b/frontend/__tests__/posthog-tracking.test.tsx
deleted file mode 100644
index d6fff267aa..0000000000
--- a/frontend/__tests__/posthog-tracking.test.tsx
+++ /dev/null
@@ -1,158 +0,0 @@
-import {
- describe,
- it,
- expect,
- beforeAll,
- afterAll,
- afterEach,
- vi,
-} from "vitest";
-import { screen, waitFor, render, cleanup } from "@testing-library/react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import {
- createMockAgentErrorEvent,
- createMockConversationErrorEvent,
-} from "#/mocks/mock-ws-helpers";
-import { ConversationWebSocketProvider } from "#/contexts/conversation-websocket-context";
-import { conversationWebSocketTestSetup } from "./helpers/msw-websocket-setup";
-import { ConnectionStatusComponent } from "./helpers/websocket-test-components";
-
-// Mock the tracking function
-const mockTrackCreditLimitReached = vi.fn();
-
-// Mock useTracking hook
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackCreditLimitReached: mockTrackCreditLimitReached,
- trackLoginButtonClick: vi.fn(),
- trackConversationCreated: vi.fn(),
- trackPushButtonClick: vi.fn(),
- trackPullButtonClick: vi.fn(),
- trackCreatePrButtonClick: vi.fn(),
- trackGitProviderConnected: vi.fn(),
- trackUserSignupCompleted: vi.fn(),
- trackCreditsPurchased: vi.fn(),
- }),
-}));
-
-// Mock useActiveConversation hook
-vi.mock("#/hooks/query/use-active-conversation", () => ({
- useActiveConversation: () => ({
- data: null,
- isLoading: false,
- error: null,
- }),
-}));
-
-// MSW WebSocket mock setup
-const { wsLink, server: mswServer } = conversationWebSocketTestSetup();
-
-beforeAll(() => {
- // The global MSW server from vitest.setup.ts is already running
- // We just need to start our WebSocket-specific server
- mswServer.listen({ onUnhandledRequest: "bypass" });
-});
-
-afterEach(() => {
- // Clear all mocks before each test
- mockTrackCreditLimitReached.mockClear();
- mswServer.resetHandlers();
- // Clean up any React components
- cleanup();
-});
-
-afterAll(async () => {
- // Close the WebSocket MSW server
- mswServer.close();
-
- // Give time for any pending WebSocket connections to close. This is very important to prevent serious memory leaks
- await new Promise((resolve) => {
- setTimeout(resolve, 500);
- });
-});
-
-// Helper function to render components with all necessary providers
-function renderWithProviders(
- children: React.ReactNode,
- conversationId = "test-conversation-123",
- conversationUrl = "http://localhost:3000/api/conversations/test-conversation-123",
-) {
- const queryClient = new QueryClient({
- defaultOptions: {
- queries: { retry: false },
- mutations: { retry: false },
- },
- });
-
- return render(
- <QueryClientProvider client={queryClient}>
- <ConversationWebSocketProvider
- conversationId={conversationId}
- conversationUrl={conversationUrl}
- sessionApiKey={null}
- >
- {children}
- </ConversationWebSocketProvider>
- </QueryClientProvider>,
- );
-}
-
-describe("PostHog Analytics Tracking", () => {
- describe("Credit Limit Tracking", () => {
- it("should NOT track credit_limit_reached for non-budget errors", async () => {
- // Create a regular error without budget/credit keywords
- const mockRegularErrorEvent = createMockAgentErrorEvent({
- error: "Failed to execute command: Permission denied",
- });
-
- mswServer.use(
- wsLink.addEventListener("connection", ({ client, server }) => {
- server.connect();
- client.send(JSON.stringify(mockRegularErrorEvent));
- }),
- );
-
- renderWithProviders(<ConnectionStatusComponent />);
-
- // Wait for connection and error to be processed
- await waitFor(() => {
- expect(screen.getByTestId("connection-state")).toHaveTextContent(
- "OPEN",
- );
- });
-
- // Verify that credit_limit_reached was NOT tracked
- expect(mockTrackCreditLimitReached).not.toHaveBeenCalled();
- });
-
- it("should track credit_limit_reached when ConversationErrorEvent contains budget error", async () => {
- const mockBudgetConversationError = createMockConversationErrorEvent({
- detail:
- "Budget has been exceeded! Current cost: 18.51, Max budget: 18.24",
- });
-
- mswServer.use(
- wsLink.addEventListener("connection", ({ client, server }) => {
- server.connect();
- client.send(JSON.stringify(mockBudgetConversationError));
- }),
- );
-
- renderWithProviders(<ConnectionStatusComponent />);
-
- await waitFor(() => {
- expect(screen.getByTestId("connection-state")).toHaveTextContent(
- "OPEN",
- );
- });
-
- await waitFor(() => {
- expect(mockTrackCreditLimitReached).toHaveBeenCalledWith(
- expect.objectContaining({
- conversationId: "test-conversation-123",
- }),
- );
- });
- });
- });
-});
diff --git a/frontend/__tests__/routes/billing.test.tsx b/frontend/__tests__/routes/billing.test.tsx
index 8f018b1c5e..b7d22d95e8 100644
--- a/frontend/__tests__/routes/billing.test.tsx
+++ b/frontend/__tests__/routes/billing.test.tsx
@@ -34,17 +34,6 @@ vi.mock("#/utils/custom-toast-handlers", () => ({
displayErrorToast: (...args: unknown[]) => mockDisplayErrorToast(...args),
}));
-// Mock the underlying posthog service so the real useTracking hook runs.
-// This is intentional: the real hook produces a fresh `trackCreditsPurchased`
-// reference on every render, which is the production-side trigger for the
-// duplicate-toast bug we're guarding against.
-const mockPostHogCapture = vi.fn();
-vi.mock("posthog-js/react", () => ({
- usePostHog: () => ({
- capture: mockPostHogCapture,
- }),
-}));
-
// Allow individual tests to pin `useSearchParams` to a fixed value (e.g. to
// hold checkout=success across forced re-renders). When unset, the real
// react-router implementation is used.
@@ -401,7 +390,7 @@ describe("Billing Route", () => {
};
}
- it("should display success toast exactly once and capture credits_purchased even when the effect re-fires before the URL clears", async () => {
+ it("should display success toast exactly once even when the effect re-fires before the URL clears", async () => {
// Arrange + Act
const { forceReRenders } = renderWithForcedReRenders(
"checkout=success&amount=25&session_id=sess_123",
@@ -412,15 +401,6 @@ describe("Billing Route", () => {
await waitFor(() => {
expect(mockDisplaySuccessToast).toHaveBeenCalledTimes(1);
});
-
- const creditsPurchasedCalls = mockPostHogCapture.mock.calls.filter(
- ([event]) => event === "credits_purchased",
- );
- expect(creditsPurchasedCalls).toHaveLength(1);
- expect(creditsPurchasedCalls[0][1]).toMatchObject({
- amount_usd: 25,
- stripe_session_id: "sess_123",
- });
});
it("should display error toast exactly once on checkout cancel even when the effect re-fires", async () => {
@@ -432,12 +412,6 @@ describe("Billing Route", () => {
await waitFor(() => {
expect(mockDisplayErrorToast).toHaveBeenCalledTimes(1);
});
-
- expect(
- mockPostHogCapture.mock.calls.some(
- ([event]) => event === "credits_purchased",
- ),
- ).toBe(false);
});
});
diff --git a/frontend/__tests__/routes/information-request.test.tsx b/frontend/__tests__/routes/information-request.test.tsx
index c6b04e9396..c41d61f879 100644
--- a/frontend/__tests__/routes/information-request.test.tsx
+++ b/frontend/__tests__/routes/information-request.test.tsx
@@ -14,13 +14,6 @@ vi.mock("react-router", async () => {
};
});
-// Mock useTracking to avoid QueryClient dependency
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackEnterpriseLeadFormSubmitted: vi.fn(),
- }),
-}));
-
describe("InformationRequest", () => {
beforeEach(() => {
vi.clearAllMocks();
diff --git a/frontend/__tests__/routes/login.test.tsx b/frontend/__tests__/routes/login.test.tsx
index b26f0c67fc..a0a0b37f78 100644
--- a/frontend/__tests__/routes/login.test.tsx
+++ b/frontend/__tests__/routes/login.test.tsx
@@ -51,12 +51,6 @@ vi.mock("#/hooks/use-auth-url", () => ({
useAuthUrlMock(config),
}));
-vi.mock("#/hooks/use-tracking", () => ({
- useTracking: () => ({
- trackLoginButtonClick: vi.fn(),
- }),
-}));
-
const { useInvitationMock, buildOAuthStateDataMock } = vi.hoisted(() => ({
useInvitationMock: vi.fn(() => ({
invitationToken: null as string | null,
diff --git a/frontend/__tests__/utils/error-handler.test.ts b/frontend/__tests__/utils/error-handler.test.ts
index b0cf26bc64..cdd52f97c8 100644
--- a/frontend/__tests__/utils/error-handler.test.ts
+++ b/frontend/__tests__/utils/error-handler.test.ts
@@ -1,5 +1,4 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import posthog from "posthog-js";
import {
trackError,
showErrorToast,
@@ -8,12 +7,6 @@ import {
import * as Actions from "#/services/actions";
import * as CustomToast from "#/utils/custom-toast-handlers";
-vi.mock("posthog-js", () => ({
- default: {
- captureException: vi.fn(),
- },
-}));
-
vi.mock("#/services/actions", () => ({
handleStatusMessage: vi.fn(),
}));
@@ -28,163 +21,48 @@ describe("Error Handler", () => {
});
describe("trackError", () => {
- it("should send error to PostHog with basic info", () => {
- const error = {
- message: "Test error",
- source: "test",
- posthog,
- };
-
- trackError(error);
-
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Test error"),
- {
- error_source: "test",
- },
- );
+ it("should be a no-op (PostHog capture removed)", () => {
+ // trackError no longer does anything β€” error tracking is server-side
+ expect(() =>
+ trackError({ message: "Test error", source: "test" }),
+ ).not.toThrow();
});
- it("should include additional metadata in PostHog event", () => {
- const error = {
- message: "Test error",
- source: "test",
- metadata: {
- extra: "info",
- details: { foo: "bar" },
- },
- posthog,
- };
-
- trackError(error);
-
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Test error"),
- {
- error_source: "test",
- extra: "info",
- details: { foo: "bar" },
- },
- );
+ it("should accept ErrorDetails without throwing", () => {
+ expect(() =>
+ trackError({
+ message: "Test error",
+ source: "test",
+ metadata: { extra: "info" },
+ }),
+ ).not.toThrow();
});
});
describe("showErrorToast", () => {
const errorToastSpy = vi.spyOn(CustomToast, "displayErrorToast");
- it("should log error and show toast", () => {
- const error = {
- message: "Toast error",
- source: "toast-test",
- posthog,
- };
-
- showErrorToast(error);
-
- // Verify PostHog logging
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Toast error"),
- {
- error_source: "toast-test",
- },
- );
- // Verify toast was shown
- expect(errorToastSpy).toHaveBeenCalled();
- });
-
- it("should include metadata in PostHog event when showing toast", () => {
- const error = {
- message: "Toast error",
- source: "toast-test",
- metadata: { context: "testing" },
- posthog,
- };
+ it("should show toast with the error message", () => {
+ showErrorToast({ message: "Toast error", source: "toast-test" });
- showErrorToast(error);
-
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Toast error"),
- {
- error_source: "toast-test",
- context: "testing",
- },
- );
+ expect(errorToastSpy).toHaveBeenCalledWith("Toast error");
});
- it("should log errors from different sources with appropriate metadata", () => {
- // Test agent status error
- showErrorToast({
- message: "Agent error",
- source: "agent-status",
- metadata: { id: "error.agent" },
- posthog,
- });
-
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Agent error"),
- {
- error_source: "agent-status",
- id: "error.agent",
- },
- );
-
- showErrorToast({
- message: "Server error",
- source: "server",
- metadata: { error_code: 500, details: "Internal error" },
- posthog,
- });
+ it("should show toast even without source or metadata", () => {
+ showErrorToast({ message: "Simple error" });
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Server error"),
- {
- error_source: "server",
- error_code: 500,
- details: "Internal error",
- },
- );
- });
-
- it("should log feedback submission errors with conversation context", () => {
- const error = new Error("Feedback submission failed");
- showErrorToast({
- message: error.message,
- source: "feedback",
- metadata: { conversationId: "123", error },
- posthog,
- });
-
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Feedback submission failed"),
- {
- error_source: "feedback",
- conversationId: "123",
- error,
- },
- );
+ expect(errorToastSpy).toHaveBeenCalledWith("Simple error");
});
});
describe("showChatError", () => {
- it("should log error and show chat error message", () => {
- const error = {
+ it("should show chat error message via handleStatusMessage", () => {
+ showChatError({
message: "Chat error",
source: "chat-test",
msgId: "123",
- posthog,
- };
-
- showChatError(error);
-
- // Verify PostHog logging
- expect(posthog.captureException).toHaveBeenCalledWith(
- new Error("Chat error"),
- {
- error_source: "chat-test",
- },
- );
+ });
- // Verify error message was shown in chat
expect(Actions.handleStatusMessage).toHaveBeenCalledWith({
type: "error",
message: "Chat error",
@@ -192,5 +70,19 @@ describe("Error Handler", () => {
status_update: true,
});
});
+
+ it("should show chat error without msgId", () => {
+ showChatError({
+ message: "Chat error no id",
+ source: "chat-test",
+ });
+
+ expect(Actions.handleStatusMessage).toHaveBeenCalledWith({
+ type: "error",
+ message: "Chat error no id",
+ id: undefined,
+ status_update: true,
+ });
+ });
});
});
diff --git a/frontend/src/components/features/auth/login-content.tsx b/frontend/src/components/features/auth/login-content.tsx
index 73d0859751..1da88634dc 100644
--- a/frontend/src/components/features/auth/login-content.tsx
+++ b/frontend/src/components/features/auth/login-content.tsx
@@ -8,7 +8,6 @@ import BitbucketLogo from "#/assets/branding/bitbucket-logo.svg?react";
import { useAuthUrl } from "#/hooks/use-auth-url";
import { WebClientConfig } from "#/api/option-service/option.types";
import { Provider } from "#/types/settings";
-import { useTracking } from "#/hooks/use-tracking";
import { TermsAndPrivacyNotice } from "#/components/shared/terms-and-privacy-notice";
import { useRecaptcha } from "#/hooks/use-recaptcha";
import { useConfig } from "#/hooks/query/use-config";
@@ -43,7 +42,6 @@ export function LoginContent({
buildOAuthStateData,
}: LoginContentProps) {
const { t } = useTranslation();
- const { trackLoginButtonClick } = useTracking();
const { data: config } = useConfig();
const { isEnterpriseCloud } = useAppMode();
@@ -76,12 +74,7 @@ export function LoginContent({
authUrl,
});
- const handleAuthRedirect = async (
- redirectUrl: string,
- provider: Provider,
- ) => {
- trackLoginButtonClick({ provider });
-
+ const handleAuthRedirect = async (redirectUrl: string) => {
const url = new URL(redirectUrl);
const currentState =
url.searchParams.get("state") || window.location.origin;
@@ -116,31 +109,31 @@ export function LoginContent({
const handleGitHubAuth = () => {
if (githubAuthUrl) {
- handleAuthRedirect(githubAuthUrl, "github");
+ handleAuthRedirect(githubAuthUrl);
}
};
const handleGitLabAuth = () => {
if (gitlabAuthUrl) {
- handleAuthRedirect(gitlabAuthUrl, "gitlab");
+ handleAuthRedirect(gitlabAuthUrl);
}
};
const handleBitbucketAuth = () => {
if (bitbucketAuthUrl) {
- handleAuthRedirect(bitbucketAuthUrl, "bitbucket");
+ handleAuthRedirect(bitbucketAuthUrl);
}
};
const handleBitbucketDataCenterAuth = () => {
if (bitbucketDataCenterAuthUrl) {
- handleAuthRedirect(bitbucketDataCenterAuthUrl, "bitbucket_data_center");
+ handleAuthRedirect(bitbucketDataCenterAuthUrl);
}
};
const handleEnterpriseSsoAuth = () => {
if (enterpriseSsoAuthUrl) {
- handleAuthRedirect(enterpriseSsoAuthUrl, "enterprise_sso");
+ handleAuthRedirect(enterpriseSsoAuthUrl);
}
};
diff --git a/frontend/src/components/features/auth/login-cta.tsx b/frontend/src/components/features/auth/login-cta.tsx
index dd2d71b293..09c7e2b541 100644
--- a/frontend/src/components/features/auth/login-cta.tsx
+++ b/frontend/src/components/features/auth/login-cta.tsx
@@ -1,12 +1,12 @@
import { useTranslation } from "react-i18next";
import { Link } from "react-router";
+import { useClientAnalytics } from "#/hooks/use-client-analytics";
import { Card } from "#/ui/card";
import { CardTitle } from "#/ui/card-title";
import { Typography } from "#/ui/typography";
import { I18nKey } from "#/i18n/declaration";
import { cn } from "#/utils/utils";
import StackedIcon from "#/icons/stacked.svg?react";
-import { useTracking } from "#/hooks/use-tracking";
type LoginCTAProps = {
className?: string;
@@ -21,7 +21,7 @@ export function LoginCTA({
source = "login_page",
}: LoginCTAProps = {}) {
const { t } = useTranslation();
- const { trackSaasSelfhostedInquiry } = useTracking();
+ const { trackEnterpriseCTAClicked } = useClientAnalytics();
const isDeviceVerifySource = source === "device_verify";
const learnMoreButtonClassName = cn(
"inline-flex items-center justify-center",
@@ -33,7 +33,7 @@ export function LoginCTA({
);
const handleLearnMoreClick = () => {
- trackSaasSelfhostedInquiry({ location: source });
+ trackEnterpriseCTAClicked({ location: source });
};
return (
diff --git a/frontend/src/components/features/chat/chat-interface.tsx b/frontend/src/components/features/chat/chat-interface.tsx
index 41ea72edd4..40722c2aaf 100644
--- a/frontend/src/components/features/chat/chat-interface.tsx
+++ b/frontend/src/components/features/chat/chat-interface.tsx
@@ -1,5 +1,4 @@
import React from "react";
-import { usePostHog } from "posthog-js/react";
import { useParams } from "react-router";
import { useTranslation } from "react-i18next";
import { convertImageToBase64 } from "#/utils/convert-image-to-base-64";
@@ -12,7 +11,6 @@ import { useScrollToBottom } from "#/hooks/use-scroll-to-bottom";
import { TypingIndicator } from "./typing-indicator";
import { ChatSuggestions } from "./chat-suggestions";
import { ScrollProvider } from "#/context/scroll-context";
-import { useInitialQueryStore } from "#/stores/initial-query-store";
import { useSendMessage } from "#/hooks/use-send-message";
import { useAgentState } from "#/hooks/use-agent-state";
import { useHandleBuildPlanClick } from "#/hooks/use-handle-build-plan-click";
@@ -37,17 +35,7 @@ import { useNewConversationCommand } from "#/hooks/mutation/use-new-conversation
import { I18nKey } from "#/i18n/declaration";
import { ArchivedBanner } from "./archived-banner";
-function getEntryPoint(
- hasRepository: boolean | null,
- hasReplayJson: boolean | null,
-): string {
- if (hasRepository) return "github";
- if (hasReplayJson) return "replay";
- return "direct";
-}
-
export function ChatInterface() {
- const posthog = usePostHog();
const { setMessageToSend } = useConversationStore();
const { errorMessage, removeErrorMessage } = useErrorMessageStore();
const { isTask, taskStatus, taskDetail } = useTaskPolling();
@@ -112,7 +100,6 @@ export function ChatInterface() {
};
}, [isAgentRunning, handleBuildPlanClick, scrollDomToBottom]);
- const { selectedRepository, replayJson } = useInitialQueryStore();
const params = useParams();
const { mutateAsync: uploadFiles } = useUnifiedUploadFiles();
@@ -156,22 +143,6 @@ export function ChatInterface() {
// Create mutable copies of the arrays
const images = [...originalImages];
const files = [...originalFiles];
- if (totalEvents === 0) {
- posthog.capture("initial_query_submitted", {
- entry_point: getEntryPoint(
- selectedRepository !== null,
- replayJson !== null,
- ),
- query_character_length: content.length,
- replay_json_size: replayJson?.length,
- });
- } else {
- posthog.capture("user_message_sent", {
- session_message_count: totalEvents,
- current_message_length: content.length,
- });
- }
-
// Validate file sizes before any processing
const allFiles = [...images, ...files];
const validation = validateFiles(allFiles);
diff --git a/frontend/src/components/features/chat/git-control-bar-pr-button.tsx b/frontend/src/components/features/chat/git-control-bar-pr-button.tsx
index 3beb7628dd..498af84cab 100644
--- a/frontend/src/components/features/chat/git-control-bar-pr-button.tsx
+++ b/frontend/src/components/features/chat/git-control-bar-pr-button.tsx
@@ -4,7 +4,6 @@ import { cn, getCreatePRPrompt } from "#/utils/utils";
import { useUserProviders } from "#/hooks/use-user-providers";
import { I18nKey } from "#/i18n/declaration";
import { Provider } from "#/types/settings";
-import { useTracking } from "#/hooks/use-tracking";
interface GitControlBarPrButtonProps {
onSuggestionsClick: (value: string) => void;
@@ -20,8 +19,6 @@ export function GitControlBarPrButton({
isConversationReady = true,
}: GitControlBarPrButtonProps) {
const { t } = useTranslation();
- const { trackCreatePrButtonClick } = useTracking();
-
const { providers } = useUserProviders();
const providersAreSet = providers.length > 0;
@@ -29,7 +26,6 @@ export function GitControlBarPrButton({
providersAreSet && hasRepository && isConversationReady;
const handlePrClick = () => {
- trackCreatePrButtonClick();
onSuggestionsClick(getCreatePRPrompt(currentGitProvider));
};
diff --git a/frontend/src/components/features/chat/git-control-bar-pull-button.tsx b/frontend/src/components/features/chat/git-control-bar-pull-button.tsx
index d0a1374098..f34426d7b4 100644
--- a/frontend/src/components/features/chat/git-control-bar-pull-button.tsx
+++ b/frontend/src/components/features/chat/git-control-bar-pull-button.tsx
@@ -4,7 +4,6 @@ import { cn, getGitPullPrompt } from "#/utils/utils";
import { useActiveConversation } from "#/hooks/query/use-active-conversation";
import { useUserProviders } from "#/hooks/use-user-providers";
import { I18nKey } from "#/i18n/declaration";
-import { useTracking } from "#/hooks/use-tracking";
interface GitControlBarPullButtonProps {
onSuggestionsClick: (value: string) => void;
@@ -16,8 +15,6 @@ export function GitControlBarPullButton({
isConversationReady = true,
}: GitControlBarPullButtonProps) {
const { t } = useTranslation();
- const { trackPullButtonClick } = useTracking();
-
const { data: conversation } = useActiveConversation();
const { providers } = useUserProviders();
@@ -27,7 +24,6 @@ export function GitControlBarPullButton({
providersAreSet && hasRepository && isConversationReady;
const handlePullClick = () => {
- trackPullButtonClick();
onSuggestionsClick(getGitPullPrompt());
};
diff --git a/frontend/src/components/features/chat/git-control-bar-push-button.tsx b/frontend/src/components/features/chat/git-control-bar-push-button.tsx
index dec4e97bed..2b0c7037cb 100644
--- a/frontend/src/components/features/chat/git-control-bar-push-button.tsx
+++ b/frontend/src/components/features/chat/git-control-bar-push-button.tsx
@@ -4,7 +4,6 @@ import { cn, getGitPushPrompt } from "#/utils/utils";
import { useUserProviders } from "#/hooks/use-user-providers";
import { I18nKey } from "#/i18n/declaration";
import { Provider } from "#/types/settings";
-import { useTracking } from "#/hooks/use-tracking";
interface GitControlBarPushButtonProps {
onSuggestionsClick: (value: string) => void;
@@ -20,8 +19,6 @@ export function GitControlBarPushButton({
isConversationReady = true,
}: GitControlBarPushButtonProps) {
const { t } = useTranslation();
- const { trackPushButtonClick } = useTracking();
-
const { providers } = useUserProviders();
const providersAreSet = providers.length > 0;
@@ -29,7 +26,6 @@ export function GitControlBarPushButton({
providersAreSet && hasRepository && isConversationReady;
const handlePushClick = () => {
- trackPushButtonClick();
onSuggestionsClick(getGitPushPrompt(currentGitProvider));
};
diff --git a/frontend/src/components/features/context-menu/context-menu-cta.tsx b/frontend/src/components/features/context-menu/context-menu-cta.tsx
index 4117135326..122a8cd252 100644
--- a/frontend/src/components/features/context-menu/context-menu-cta.tsx
+++ b/frontend/src/components/features/context-menu/context-menu-cta.tsx
@@ -1,18 +1,18 @@
import { useTranslation } from "react-i18next";
+import { useClientAnalytics } from "#/hooks/use-client-analytics";
import { cn } from "#/utils/utils";
import { Card } from "#/ui/card";
import { CardTitle } from "#/ui/card-title";
import { Typography } from "#/ui/typography";
import { I18nKey } from "#/i18n/declaration";
import StackedIcon from "#/icons/stacked.svg?react";
-import { useTracking } from "#/hooks/use-tracking";
export function ContextMenuCTA() {
const { t } = useTranslation();
- const { trackSaasSelfhostedInquiry } = useTracking();
+ const { trackEnterpriseCTAClicked } = useClientAnalytics();
const handleLearnMoreClick = () => {
- trackSaasSelfhostedInquiry({ location: "context_menu" });
+ trackEnterpriseCTAClicked({ location: "context_menu" });
};
return (
diff --git a/frontend/src/components/features/conversation-panel/conversation-card/conversation-card.tsx b/frontend/src/components/features/conversation-panel/conversation-card/conversation-card.tsx
index cbca946c47..8829482df7 100644
--- a/frontend/src/components/features/conversation-panel/conversation-card/conversation-card.tsx
+++ b/frontend/src/components/features/conversation-panel/conversation-card/conversation-card.tsx
@@ -1,5 +1,4 @@
import React from "react";
-import { usePostHog } from "posthog-js/react";
import { cn } from "#/utils/utils";
import { transformVSCodeUrl } from "#/utils/vscode-url-helper";
import ConversationService from "#/api/conversation-service/conversation-service.api";
@@ -46,7 +45,6 @@ export function ConversationCard({
onContextMenuToggle,
llmModel,
}: ConversationCardProps) {
- const posthog = usePostHog();
const [titleMode, setTitleMode] = React.useState<"view" | "edit">("view");
const { mutateAsync: downloadConversation } = useDownloadConversation();
@@ -83,7 +81,6 @@ export function ConversationCard({
) => {
event.preventDefault();
event.stopPropagation();
- posthog.capture("download_via_vscode_button_clicked");
// Fetch the VS Code URL from the API
if (conversationId) {
diff --git a/frontend/src/components/features/home/homepage-cta.tsx b/frontend/src/components/features/home/homepage-cta.tsx
index e1438507be..84e1acc948 100644
--- a/frontend/src/components/features/home/homepage-cta.tsx
+++ b/frontend/src/components/features/home/homepage-cta.tsx
@@ -1,12 +1,12 @@
import { useTranslation } from "react-i18next";
import { Dispatch, SetStateAction } from "react";
+import { useClientAnalytics } from "#/hooks/use-client-analytics";
import { Card } from "#/ui/card";
import { CardTitle } from "#/ui/card-title";
import { Typography } from "#/ui/typography";
import { cn } from "#/utils/utils";
import { I18nKey } from "#/i18n/declaration";
import { setCTADismissed } from "#/utils/local-storage";
-import { useTracking } from "#/hooks/use-tracking";
import CloseIcon from "#/icons/close.svg?react";
interface HomepageCTAProps {
@@ -15,17 +15,17 @@ interface HomepageCTAProps {
export function HomepageCTA({ setShouldShowCTA }: HomepageCTAProps) {
const { t } = useTranslation();
- const { trackSaasSelfhostedInquiry } = useTracking();
+ const { trackEnterpriseCTAClicked } = useClientAnalytics();
+
+ const handleLearnMoreClick = () => {
+ trackEnterpriseCTAClicked({ location: "home_page" });
+ };
const handleClose = () => {
setCTADismissed("homepage");
setShouldShowCTA(false);
};
- const handleLearnMoreClick = () => {
- trackSaasSelfhostedInquiry({ location: "home_page" });
- };
-
return (
<Card theme="dark" className={cn("w-[320px] cta-card-gradient")}>
<button
diff --git a/frontend/src/components/features/onboarding/information-request-form.tsx b/frontend/src/components/features/onboarding/information-request-form.tsx
index b7f46164e0..de53b30e3b 100644
--- a/frontend/src/components/features/onboarding/information-request-form.tsx
+++ b/frontend/src/components/features/onboarding/information-request-form.tsx
@@ -1,8 +1,8 @@
import { useState } from "react";
import { useTranslation } from "react-i18next";
import { useNavigate } from "react-router";
+import { useClientAnalytics } from "#/hooks/use-client-analytics";
import { I18nKey } from "#/i18n/declaration";
-import { useTracking } from "#/hooks/use-tracking";
import { Card } from "#/ui/card";
import { Typography } from "#/ui/typography";
import {
@@ -32,7 +32,7 @@ export function InformationRequestForm({
}: InformationRequestFormProps) {
const { t } = useTranslation();
const navigate = useNavigate();
- const { trackEnterpriseLeadFormSubmitted } = useTracking();
+ const { trackEnterpriseLeadFormSubmitted } = useClientAnalytics();
const [hasAttemptedSubmit, setHasAttemptedSubmit] = useState(false);
const [isSubmitting, setIsSubmitting] = useState(false);
diff --git a/frontend/src/components/providers/posthog-wrapper.tsx b/frontend/src/components/providers/posthog-wrapper.tsx
index 7a66fff311..6f92dd8bb5 100644
--- a/frontend/src/components/providers/posthog-wrapper.tsx
+++ b/frontend/src/components/providers/posthog-wrapper.tsx
@@ -74,7 +74,13 @@ export function PostHogWrapper({ children }: { children: React.ReactNode }) {
options={{
api_host: "https://us.i.posthog.com",
person_profiles: "identified_only",
+ capture_performance: {
+ network_timing: true,
+ web_vitals: true,
+ },
+ capture_exceptions: true,
bootstrap: bootstrapIds,
+ __add_tracing_headers: [window.location.hostname],
}}
>
{children}
diff --git a/frontend/src/components/shared/modals/settings/settings-form.tsx b/frontend/src/components/shared/modals/settings/settings-form.tsx
index 11ec26fe6f..6e44c88651 100644
--- a/frontend/src/components/shared/modals/settings/settings-form.tsx
+++ b/frontend/src/components/shared/modals/settings/settings-form.tsx
@@ -1,7 +1,6 @@
import { useLocation } from "react-router";
import { useTranslation } from "react-i18next";
import React from "react";
-import { usePostHog } from "posthog-js/react";
import { I18nKey } from "#/i18n/declaration";
import { DangerModal } from "../confirmation-modals/danger-modal";
import { extractSettings } from "#/utils/settings-utils";
@@ -21,7 +20,6 @@ interface SettingsFormProps {
}
export function SettingsForm({ settings, onClose }: SettingsFormProps) {
- const posthog = usePostHog();
const { mutate: saveUserSettings } = useSaveSettings();
const location = useLocation();
@@ -38,17 +36,6 @@ export function SettingsForm({ settings, onClose }: SettingsFormProps) {
await saveUserSettings(newSettings, {
onSuccess: () => {
onClose();
-
- const agentLlm =
- ((newSettings.agent_settings_diff as Record<string, unknown>)
- ?.llm as Record<string, unknown>) ?? {};
- posthog.capture("settings_saved", {
- LLM_MODEL: agentLlm.model,
- LLM_API_KEY_SET: agentLlm.api_key ? "SET" : "UNSET",
- SEARCH_API_KEY_SET: newSettings.search_api_key ? "SET" : "UNSET",
- REMOTE_RUNTIME_RESOURCE_FACTOR:
- newSettings.remote_runtime_resource_factor,
- });
},
});
};
diff --git a/frontend/src/contexts/conversation-websocket-context.tsx b/frontend/src/contexts/conversation-websocket-context.tsx
index d924693666..25f651c1fe 100644
--- a/frontend/src/contexts/conversation-websocket-context.tsx
+++ b/frontend/src/contexts/conversation-websocket-context.tsx
@@ -8,7 +8,6 @@ import React, {
useRef,
} from "react";
import { useQueryClient } from "@tanstack/react-query";
-import { usePostHog } from "posthog-js/react";
import { useWebSocket, WebSocketHookOptions } from "#/hooks/use-websocket";
import { useEventStore } from "#/stores/use-event-store";
import { useErrorMessageStore } from "#/stores/error-message-store";
@@ -47,7 +46,6 @@ import EventService from "#/api/event-service/event-service.api";
import PendingMessageService from "#/api/pending-message-service/pending-message-service.api";
import { useConversationStore } from "#/stores/conversation-store";
import { isBudgetOrCreditError, trackError } from "#/utils/error-handler";
-import { useTracking } from "#/hooks/use-tracking";
import { useReadConversationFile } from "#/hooks/mutation/use-read-conversation-file";
import useMetricsStore from "#/stores/metrics-store";
import { I18nKey } from "#/i18n/declaration";
@@ -101,14 +99,12 @@ export function ConversationWebSocketProvider({
const hasConnectedRefMain = React.useRef(false);
const hasConnectedRefPlanning = React.useRef(false);
- const posthog = usePostHog();
const queryClient = useQueryClient();
const { addEvent } = useEventStore();
const { setErrorMessage, removeErrorMessage } = useErrorMessageStore();
const { removeOptimisticUserMessage } = useOptimisticUserMessageStore();
const { setExecutionStatus } = useV1ConversationStateStore();
const { appendInput, appendOutput } = useCommandStore();
- const { trackCreditLimitReached } = useTracking();
// History loading state - separate per connection
const [isLoadingHistoryMain, setIsLoadingHistoryMain] = useState(true);
@@ -397,13 +393,9 @@ export function ConversationWebSocketProvider({
eventId: errorEvent.id,
errorCode: errorEvent.code,
},
- posthog,
});
if (isBudgetOrCreditError(errorEvent.detail)) {
setErrorMessage(I18nKey.STATUS$ERROR_LLM_OUT_OF_CREDITS);
- trackCreditLimitReached({
- conversationId: conversationId || "unknown",
- });
} else {
setErrorMessage(errorEvent.detail);
}
@@ -421,9 +413,13 @@ export function ConversationWebSocketProvider({
toolName: event.tool_name,
toolCallId: event.tool_call_id,
},
- posthog,
});
- setErrorMessage(event.error);
+ // Use friendly i18n message for budget/credit errors instead of raw error
+ if (isBudgetOrCreditError(event.error)) {
+ setErrorMessage(I18nKey.STATUS$ERROR_LLM_OUT_OF_CREDITS);
+ } else {
+ setErrorMessage(event.error);
+ }
}
// Clear optimistic user message when a user message is confirmed
@@ -509,8 +505,6 @@ export function ConversationWebSocketProvider({
appendInput,
appendOutput,
updateMetricsFromStats,
- trackCreditLimitReached,
- posthog,
],
);
@@ -554,13 +548,9 @@ export function ConversationWebSocketProvider({
eventId: errorEvent.id,
errorCode: errorEvent.code,
},
- posthog,
});
if (isBudgetOrCreditError(errorEvent.detail)) {
setErrorMessage(I18nKey.STATUS$ERROR_LLM_OUT_OF_CREDITS);
- trackCreditLimitReached({
- conversationId: conversationId || "unknown",
- });
} else {
setErrorMessage(errorEvent.detail);
}
@@ -578,9 +568,13 @@ export function ConversationWebSocketProvider({
toolName: event.tool_name,
toolCallId: event.tool_call_id,
},
- posthog,
});
- setErrorMessage(event.error);
+ // Use friendly i18n message for budget/credit errors instead of raw error
+ if (isBudgetOrCreditError(event.error)) {
+ setErrorMessage(I18nKey.STATUS$ERROR_LLM_OUT_OF_CREDITS);
+ } else {
+ setErrorMessage(event.error);
+ }
}
// Clear optimistic user message when a user message is confirmed
@@ -692,8 +686,6 @@ export function ConversationWebSocketProvider({
readConversationFile,
setPlanContent,
updateMetricsFromStats,
- trackCreditLimitReached,
- posthog,
],
);
diff --git a/frontend/src/hooks/mutation/use-accept-tos.ts b/frontend/src/hooks/mutation/use-accept-tos.ts
index a159b1458c..058cb9a728 100644
--- a/frontend/src/hooks/mutation/use-accept-tos.ts
+++ b/frontend/src/hooks/mutation/use-accept-tos.ts
@@ -3,7 +3,6 @@ import { usePostHog } from "posthog-js/react";
import { useNavigate } from "react-router";
import { openHands } from "#/api/open-hands-axios";
import { handleCaptureConsent } from "#/utils/handle-capture-consent";
-import { useTracking } from "#/hooks/use-tracking";
interface AcceptTosVariables {
redirectUrl: string;
@@ -16,7 +15,6 @@ interface AcceptTosResponse {
export const useAcceptTos = () => {
const posthog = usePostHog();
const navigate = useNavigate();
- const { trackUserSignupCompleted } = useTracking();
return useMutation({
mutationFn: async ({ redirectUrl }: AcceptTosVariables) => {
@@ -29,9 +27,6 @@ export const useAcceptTos = () => {
});
},
onSuccess: (response, { redirectUrl }) => {
- // Track user signup completion
- trackUserSignupCompleted();
-
// Get the redirect URL from the response
const finalRedirectUrl = response.data.redirect_url || redirectUrl;
diff --git a/frontend/src/hooks/mutation/use-add-git-providers.ts b/frontend/src/hooks/mutation/use-add-git-providers.ts
index 782020f7d8..a3b5da2521 100644
--- a/frontend/src/hooks/mutation/use-add-git-providers.ts
+++ b/frontend/src/hooks/mutation/use-add-git-providers.ts
@@ -1,12 +1,10 @@
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { SecretsService } from "#/api/secrets-service";
import { Provider, ProviderToken } from "#/types/settings";
-import { useTracking } from "#/hooks/use-tracking";
import { useSelectedOrganizationId } from "#/context/use-selected-organization";
export const useAddGitProviders = () => {
const queryClient = useQueryClient();
- const { trackGitProviderConnected } = useTracking();
const { organizationId } = useSelectedOrganizationId();
return useMutation({
@@ -15,18 +13,7 @@ export const useAddGitProviders = () => {
}: {
providers: Record<Provider, ProviderToken>;
}) => SecretsService.addGitProvider(providers),
- onSuccess: async (_, { providers }) => {
- // Track which providers were connected (filter out empty tokens)
- const connectedProviders = Object.entries(providers)
- .filter(([, value]) => value.token && value.token.trim() !== "")
- .map(([key]) => key);
-
- if (connectedProviders.length > 0) {
- trackGitProviderConnected({
- providers: connectedProviders,
- });
- }
-
+ onSuccess: async () => {
await queryClient.invalidateQueries({
queryKey: ["settings", "personal", organizationId],
});
diff --git a/frontend/src/hooks/mutation/use-create-conversation.ts b/frontend/src/hooks/mutation/use-create-conversation.ts
index 68891d51d3..1f3e6c0d42 100644
--- a/frontend/src/hooks/mutation/use-create-conversation.ts
+++ b/frontend/src/hooks/mutation/use-create-conversation.ts
@@ -3,7 +3,6 @@ import V1ConversationService from "#/api/conversation-service/v1-conversation-se
import { PluginSpec } from "#/api/conversation-service/v1-conversation-service.types";
import { SuggestedTask } from "#/utils/types";
import { Provider } from "#/types/settings";
-import { useTracking } from "#/hooks/use-tracking";
interface CreateConversationVariables {
query?: string;
@@ -30,7 +29,6 @@ interface CreateConversationResponse {
export const useCreateConversation = () => {
const queryClient = useQueryClient();
- const { trackConversationCreated } = useTracking();
return useMutation({
mutationKey: ["create-conversation"],
@@ -72,11 +70,7 @@ export const useCreateConversation = () => {
is_v1: true,
};
},
- onSuccess: async (_, { repository }) => {
- trackConversationCreated({
- hasRepository: !!repository,
- });
-
+ onSuccess: async () => {
queryClient.removeQueries({
queryKey: ["user", "conversations"],
});
diff --git a/frontend/src/hooks/mutation/use-save-settings.ts b/frontend/src/hooks/mutation/use-save-settings.ts
index 2f0060d488..bfdecaafc7 100644
--- a/frontend/src/hooks/mutation/use-save-settings.ts
+++ b/frontend/src/hooks/mutation/use-save-settings.ts
@@ -1,15 +1,8 @@
import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { usePostHog } from "posthog-js/react";
import { useSelectedOrganizationId } from "#/context/use-selected-organization";
import { organizationService } from "#/api/organization-service/organization-service.api";
import SettingsService from "#/api/settings-service/settings-service.api";
-import {
- MCPConfig,
- Settings,
- SettingsScope,
- SettingsValue,
-} from "#/types/settings";
-import { useSettings } from "../query/use-settings";
+import { Settings, SettingsScope, SettingsValue } from "#/types/settings";
type SettingsUpdate = Partial<Settings> & Record<string, unknown>;
@@ -77,26 +70,11 @@ const saveSettingsMutationFn = async (
};
export const useSaveSettings = (scope: SettingsScope = "personal") => {
- const posthog = usePostHog();
const queryClient = useQueryClient();
- const { data: currentSettings } = useSettings(scope);
const { organizationId } = useSelectedOrganizationId();
return useMutation({
mutationFn: async (settings: SettingsUpdate) => {
- const nextMcpConfig = settings.mcp_config as MCPConfig | undefined;
- const currentMcpConfig = currentSettings?.mcp_config as
- | MCPConfig
- | undefined;
-
- if (nextMcpConfig && currentMcpConfig !== nextMcpConfig) {
- posthog.capture("mcp_config_updated", {
- has_mcp_config: true,
- sse_servers_count: nextMcpConfig.sse_servers?.length || 0,
- stdio_servers_count: nextMcpConfig.stdio_servers?.length || 0,
- });
- }
-
await saveSettingsMutationFn(scope, settings, organizationId);
},
onSuccess: async () => {
diff --git a/frontend/src/hooks/mutation/use-submit-onboarding.ts b/frontend/src/hooks/mutation/use-submit-onboarding.ts
index 87f21ac2e1..2c3ac7cce9 100644
--- a/frontend/src/hooks/mutation/use-submit-onboarding.ts
+++ b/frontend/src/hooks/mutation/use-submit-onboarding.ts
@@ -7,21 +7,28 @@ type SubmitOnboardingArgs = {
selections: Record<string, string | string[]>;
};
+interface OnboardingResponse {
+ status: string;
+ redirect_url: string;
+}
+
export const useSubmitOnboarding = () => {
const navigate = useNavigate();
const queryClient = useQueryClient();
return useMutation({
mutationFn: async ({ selections }: SubmitOnboardingArgs) => {
- // Mark onboarding as complete
- await openHands.post("/api/complete_onboarding");
- return { selections };
+ const { data } = await openHands.post<OnboardingResponse>(
+ "/api/complete_onboarding",
+ { selections },
+ );
+ return data;
},
- onSuccess: () => {
+ onSuccess: (data) => {
queryClient.invalidateQueries({ queryKey: ["settings"] });
queryClient.invalidateQueries({ queryKey: ["onboarding-status"] });
- const finalRedirectUrl = "/";
+ const finalRedirectUrl = data.redirect_url || "/";
// Check if the redirect URL is an external URL (starts with http or https)
if (
finalRedirectUrl.startsWith("http://") ||
diff --git a/frontend/src/hooks/use-client-analytics.ts b/frontend/src/hooks/use-client-analytics.ts
new file mode 100644
index 0000000000..650db824ec
--- /dev/null
+++ b/frontend/src/hooks/use-client-analytics.ts
@@ -0,0 +1,47 @@
+import { usePostHog } from "posthog-js/react";
+
+/**
+ * Lightweight client-side analytics for UI-only events that have
+ * no natural server round-trip. All server-side business events
+ * go through the backend AnalyticsService instead.
+ *
+ * These events are tracked directly via PostHog's client SDK,
+ * which automatically handles anonymous IDs and links them to
+ * the user when posthog.identify() is called on login.
+ */
+export const useClientAnalytics = () => {
+ const posthog = usePostHog();
+
+ const trackEnterpriseCTAClicked = ({ location }: { location: string }) => {
+ posthog?.capture("enterprise cta clicked", {
+ location,
+ });
+ };
+
+ const trackEnterpriseLeadFormSubmitted = ({
+ requestType,
+ name,
+ company,
+ email,
+ message,
+ }: {
+ requestType: string;
+ name: string;
+ company: string;
+ email: string;
+ message: string;
+ }) => {
+ posthog?.capture("enterprise lead form submitted", {
+ request_type: requestType,
+ name,
+ company,
+ email,
+ message,
+ });
+ };
+
+ return {
+ trackEnterpriseCTAClicked,
+ trackEnterpriseLeadFormSubmitted,
+ };
+};
diff --git a/frontend/src/hooks/use-download-conversation.ts b/frontend/src/hooks/use-download-conversation.ts
index ae2f4c507c..3a364d2936 100644
--- a/frontend/src/hooks/use-download-conversation.ts
+++ b/frontend/src/hooks/use-download-conversation.ts
@@ -1,5 +1,4 @@
import { useMutation } from "@tanstack/react-query";
-import { usePostHog } from "posthog-js/react";
import { useTranslation } from "react-i18next";
import V1ConversationService from "#/api/conversation-service/v1-conversation-service.api";
import { downloadBlob } from "#/utils/utils";
@@ -7,13 +6,11 @@ import { displayErrorToast } from "#/utils/custom-toast-handlers";
import { I18nKey } from "#/i18n/declaration";
export const useDownloadConversation = () => {
- const posthog = usePostHog();
const { t } = useTranslation();
return useMutation({
mutationKey: ["conversations", "download"],
mutationFn: async (conversationId: string) => {
- posthog.capture("download_trajectory_button_clicked");
const blob =
await V1ConversationService.downloadConversation(conversationId);
downloadBlob(blob, `conversation_${conversationId}.zip`);
diff --git a/frontend/src/hooks/use-tracking.ts b/frontend/src/hooks/use-tracking.ts
deleted file mode 100644
index 63fcbe2d24..0000000000
--- a/frontend/src/hooks/use-tracking.ts
+++ /dev/null
@@ -1,170 +0,0 @@
-import { usePostHog } from "posthog-js/react";
-import { useConfig } from "./query/use-config";
-import { useSettings } from "./query/use-settings";
-import { Provider } from "#/types/settings";
-
-/**
- * Hook that provides tracking functions with automatic data collection
- * from available hooks (config, settings, etc.)
- */
-export const useTracking = () => {
- const posthog = usePostHog();
- const { data: config } = useConfig();
- const { data: settings } = useSettings();
-
- // Common properties included in all tracking events
- const commonProperties = {
- app_surface: config?.app_mode || "unknown",
- plan_tier: null,
- current_url: window.location.href,
- user_email: settings?.email || settings?.git_user_email || null,
- };
-
- const trackLoginButtonClick = ({ provider }: { provider: Provider }) => {
- posthog.capture("login_button_clicked", {
- provider,
- ...commonProperties,
- });
- };
-
- const trackConversationCreated = ({
- hasRepository,
- }: {
- hasRepository: boolean;
- }) => {
- posthog.capture("conversation_created", {
- has_repository: hasRepository,
- ...commonProperties,
- });
- };
-
- const trackPushButtonClick = () => {
- posthog.capture("push_button_clicked", {
- ...commonProperties,
- });
- };
-
- const trackPullButtonClick = () => {
- posthog.capture("pull_button_clicked", {
- ...commonProperties,
- });
- };
-
- const trackCreatePrButtonClick = () => {
- posthog.capture("create_pr_button_clicked", {
- ...commonProperties,
- });
- };
-
- const trackGitProviderConnected = ({
- providers,
- }: {
- providers: string[];
- }) => {
- posthog.capture("git_provider_connected", {
- providers,
- ...commonProperties,
- });
- };
-
- const trackUserSignupCompleted = () => {
- posthog.capture("user_signup_completed", {
- signup_timestamp: new Date().toISOString(),
- ...commonProperties,
- });
- };
-
- const trackCreditsPurchased = ({
- amountUsd,
- stripeSessionId,
- }: {
- amountUsd: number;
- stripeSessionId: string;
- }) => {
- posthog.capture("credits_purchased", {
- amount_usd: amountUsd,
- stripe_session_id: stripeSessionId,
- ...commonProperties,
- });
- };
-
- const trackCreditLimitReached = ({
- conversationId,
- }: {
- conversationId: string;
- }) => {
- posthog.capture("credit_limit_reached", {
- conversation_id: conversationId,
- ...commonProperties,
- });
- };
-
- const trackAddTeamMembersButtonClick = () => {
- posthog.capture("exp_add_team_members", {
- ...commonProperties,
- });
- };
-
- const trackOnboardingCompleted = ({
- role,
- orgSize,
- useCase,
- }: {
- role?: string;
- orgSize?: string;
- useCase?: string[];
- }) => {
- posthog.capture("onboarding_completed", {
- role,
- org_size: orgSize,
- use_case: useCase,
- ...commonProperties,
- });
- };
-
- const trackSaasSelfhostedInquiry = ({ location }: { location: string }) => {
- posthog.capture("saas_selfhosted_inquiry", {
- location,
- ...commonProperties,
- });
- };
-
- const trackEnterpriseLeadFormSubmitted = ({
- requestType,
- name,
- company,
- email,
- message,
- }: {
- requestType: "saas" | "self-hosted";
- name: string;
- company: string;
- email: string;
- message: string;
- }) => {
- posthog.capture("enterprise_lead_form_submitted", {
- request_type: requestType,
- name,
- company,
- email,
- message,
- ...commonProperties,
- });
- };
-
- return {
- trackLoginButtonClick,
- trackConversationCreated,
- trackPushButtonClick,
- trackPullButtonClick,
- trackCreatePrButtonClick,
- trackGitProviderConnected,
- trackUserSignupCompleted,
- trackCreditsPurchased,
- trackCreditLimitReached,
- trackAddTeamMembersButtonClick,
- trackOnboardingCompleted,
- trackSaasSelfhostedInquiry,
- trackEnterpriseLeadFormSubmitted,
- };
-};
diff --git a/frontend/src/routes/billing.tsx b/frontend/src/routes/billing.tsx
index 11324045d2..17e22085a5 100644
--- a/frontend/src/routes/billing.tsx
+++ b/frontend/src/routes/billing.tsx
@@ -7,7 +7,6 @@ import {
displaySuccessToast,
} from "#/utils/custom-toast-handlers";
import { I18nKey } from "#/i18n/declaration";
-import { useTracking } from "#/hooks/use-tracking";
import { useMe } from "#/hooks/query/use-me";
import { usePermission } from "#/hooks/organizations/use-permissions";
import { getActiveOrganizationUser } from "#/utils/org/permission-checks";
@@ -52,13 +51,10 @@ export const clientLoader = async () => {
function BillingSettingsScreen() {
const { t } = useTranslation();
const [searchParams, setSearchParams] = useSearchParams();
- const { trackCreditsPurchased } = useTracking();
const { data: me } = useMe();
const { hasPermission } = usePermission(me?.role ?? "member");
const canAddCredits = !!me && hasPermission("add_credits");
const checkoutStatus = searchParams.get("checkout");
- const amount = searchParams.get("amount");
- const sessionId = searchParams.get("session_id");
const hasHandledCheckoutRef = React.useRef(false);
React.useEffect(() => {
@@ -67,29 +63,13 @@ function BillingSettingsScreen() {
hasHandledCheckoutRef.current = true;
if (checkoutStatus === "success") {
- // Track credits purchased if we have the necessary data
- if (amount && sessionId) {
- trackCreditsPurchased({
- amountUsd: parseFloat(amount),
- stripeSessionId: sessionId,
- });
- }
-
displaySuccessToast(t(I18nKey.PAYMENT$SUCCESS));
-
setSearchParams({});
} else if (checkoutStatus === "cancel") {
displayErrorToast(t(I18nKey.PAYMENT$CANCELLED));
setSearchParams({});
}
- }, [
- checkoutStatus,
- amount,
- sessionId,
- setSearchParams,
- t,
- trackCreditsPurchased,
- ]);
+ }, [checkoutStatus, setSearchParams, t]);
return <PaymentForm isDisabled={!canAddCredits} />;
}
diff --git a/frontend/src/routes/onboarding-form.tsx b/frontend/src/routes/onboarding-form.tsx
index 639738cc5d..eef9bb9b4b 100644
--- a/frontend/src/routes/onboarding-form.tsx
+++ b/frontend/src/routes/onboarding-form.tsx
@@ -8,9 +8,7 @@ import { I18nKey } from "#/i18n/declaration";
import OpenHandsLogoWhite from "#/assets/branding/openhands-logo-white.svg?react";
import { useSubmitOnboarding } from "#/hooks/mutation/use-submit-onboarding";
import { useOnboardingStatus } from "#/hooks/query/use-onboarding-status";
-import { useTracking } from "#/hooks/use-tracking";
import { cn } from "#/utils/utils";
-import { useMe } from "#/hooks/query/use-me";
import {
ONBOARDING_FORM,
OnboardingQuestion,
@@ -87,11 +85,9 @@ function OnboardingForm() {
const navigate = useNavigate();
const loaderData = useLoaderData<typeof clientLoader>();
const config = loaderData?.config;
- const { data: me } = useMe();
const { data: onboardingStatus, isLoading: isOnboardingStatusLoading } =
useOnboardingStatus();
const { mutate: submitOnboarding } = useSubmitOnboarding();
- const { trackOnboardingCompleted } = useTracking();
React.useEffect(() => {
if (isOnboardingStatusLoading) return;
@@ -186,26 +182,6 @@ function OnboardingForm() {
const handleNext = () => {
if (isLastStep) {
submitOnboarding({ selections: answers });
-
- // Track onboarding completion based on deployment mode:
- // - Cloud mode: track ALL users
- // - Self-hosted mode: track only org owners (SuperAdmin)
- const deploymentMode = config?.feature_flags?.deployment_mode;
- const isOwner = me?.role === "owner";
- const shouldTrack =
- deploymentMode === "cloud" ||
- (deploymentMode === "self_hosted" && isOwner);
-
- if (shouldTrack) {
- trackOnboardingCompleted({
- role: typeof answers.role === "string" ? answers.role : undefined,
- orgSize:
- typeof answers.org_size === "string" ? answers.org_size : undefined,
- useCase: Array.isArray(answers.use_case)
- ? answers.use_case
- : undefined,
- });
- }
} else {
setCurrentStepIndex((prev) => prev + 1);
}
diff --git a/frontend/src/services/actions.ts b/frontend/src/services/actions.ts
index 6f03c526e1..947db37161 100644
--- a/frontend/src/services/actions.ts
+++ b/frontend/src/services/actions.ts
@@ -72,7 +72,6 @@ export function handleStatusMessage(message: StatusMessage) {
message: message.message,
source: "chat",
metadata: { msgId: message.id },
- posthog: undefined, // Service file - can't use hooks
});
}
}
diff --git a/frontend/src/utils/error-handler.ts b/frontend/src/utils/error-handler.ts
index d479853b6d..2f1eaced6b 100644
--- a/frontend/src/utils/error-handler.ts
+++ b/frontend/src/utils/error-handler.ts
@@ -1,4 +1,3 @@
-import type { PostHog } from "posthog-js";
import { handleStatusMessage } from "#/services/actions";
import { displayErrorToast } from "./custom-toast-handlers";
@@ -7,31 +6,19 @@ interface ErrorDetails {
source?: string;
metadata?: Record<string, unknown>;
msgId?: string;
- posthog?: PostHog;
}
-export function trackError({
- message,
- source,
- metadata = {},
- posthog,
-}: ErrorDetails) {
- if (!posthog) return;
-
- const error = new Error(message);
- posthog.captureException(error, {
- error_source: source || "unknown",
- ...metadata,
- });
-}
+// PostHog capture removed β€” error tracking is now handled server-side
+export function trackError(
+ details: ErrorDetails, // eslint-disable-line @typescript-eslint/no-unused-vars
+): void {}
export function showErrorToast({
message,
source,
metadata = {},
- posthog,
}: ErrorDetails) {
- trackError({ message, source, metadata, posthog });
+ trackError({ message, source, metadata });
displayErrorToast(message);
}
@@ -40,9 +27,8 @@ export function showChatError({
source,
metadata = {},
msgId,
- posthog,
}: ErrorDetails) {
- trackError({ message, source, metadata, posthog });
+ trackError({ message, source, metadata });
handleStatusMessage({
type: "error",
message,
diff --git a/openhands/analytics/EVENTS.md b/openhands/analytics/EVENTS.md
new file mode 100644
index 0000000000..4cc0199be7
--- /dev/null
+++ b/openhands/analytics/EVENTS.md
@@ -0,0 +1,175 @@
+# PostHog Analytics β€” Event Catalog
+
+*Last updated: 2026-05-01*
+
+## Architecture Overview
+
+Analytics is split into three lanes:
+
+1. **Server-side business events** (SaaS only) β€” captured through a centralized `AnalyticsService`. Covers the core product lifecycle: signups, logins, conversations, credits, activation, onboarding, settings, and team management.
+2. **Client-side UI events** (SaaS only) β€” captured via `useClientAnalytics` hook for UI-only interactions that have no natural server round-trip (e.g. enterprise CTA clicks, lead form submissions).
+3. **Frontend automatic instrumentation** (SaaS and OSS) β€” web vitals, error tracking, network timing, pageviews. No explicit event code required.
+
+Every event respects user consent.
+
+---
+
+## Backend Events
+
+| # | Event | When It Fires | Key Properties |
+|---|---|---|---|
+| 1 | **user signed up** | New user completes OAuth registration (once per user) | `idp`, `email_domain`, `invitation_source` |
+| 2 | **user logged in** | Every successful authentication (Keycloak or device auth) | `idp` |
+| 3 | **conversation created** | A new conversation is initialized | `conversation_id`, `trigger`, `llm_model`, `agent_type`, `has_repository` |
+| 4 | **conversation finished** | Conversation reaches a successful or stopped terminal state | `conversation_id`, `terminal_state`, `turn_count`, `accumulated_cost_usd`, `prompt_tokens`, `completion_tokens`, `llm_model`, `trigger` |
+| 5 | **conversation errored** | Conversation reaches an error or stuck state | `conversation_id`, `error_type`\*, `error_message`, `llm_model`, `turn_count`, `terminal_state` |
+| 6 | **conversation deleted** | User deletes a conversation | `conversation_id` |
+| 7 | **credit purchased** | Stripe checkout completes successfully | `amount_usd`, `credit_balance_before`, `credit_balance_after` |
+| 8 | **credit limit reached** | Conversation fails due to insufficient credits (fires alongside #5) | `conversation_id`, `credit_balance`, `llm_model` |
+| 9 | **git provider connected** | User connects a git provider (GitHub, GitLab, etc.) | `provider_type` |
+| 10 | **onboarding completed** | User submits the onboarding form | (form selections passed as properties) |
+| 11 | **settings saved** | User saves their settings | `settings_changed`\*\* |
+| 12 | **trajectory downloaded** | User downloads a conversation trajectory | `conversation_id` |
+| 13 | **team members invited** | User invites team members to their organization | `invited_count`, `successful_count`, `failed_count`, `role` |
+
+\*Error types: `budget_exceeded`, `model_error`, `runtime_error`, `timeout`, `user_cancelled`, `unknown`
+
+\*\*`settings_changed` is a list of payload keys that were modified (e.g., `['llm_model']`, `['agent_settings_diff']`, etc.)
+
+Every event also carries: `app_mode` (saas/oss), `is_feature_env`, and `org_id` when available.
+
+**Note:** Backend events fire in SaaS only. The `AnalyticsService` is never initialized in OSS β€” `get_analytics_service()` returns `None` and all call sites are guarded.
+
+---
+
+## Identity & Group Tracking (SaaS only)
+
+| Action | When | What's Set |
+|---|---|---|
+| **Identify user** | Login (Keycloak or device auth) | Person: `email`, `org_id`, `org_name`, `idp`, `last_login_at`. Group (org): `org_name`, `member_count`. |
+| **Update person** | Signup, org switch | `signed_up_at` on signup; `org_id`, `org_name` on org switch |
+| **Update org group** | Login, onboarding | `member_count`, `onboarding_completed_at` |
+
+---
+
+## Client-Side UI Events (SaaS only)
+
+A small set of explicit frontend events captured via the `useClientAnalytics` hook. These are UI interactions with no natural server round-trip β€” they fire directly through the PostHog JS SDK.
+
+| # | Event | When It Fires | Key Properties |
+|---|---|---|---|
+| 1 | **enterprise cta clicked** | User clicks "Learn More" on an enterprise CTA (login page, homepage, context menu, device verify) | `location` |
+| 2 | **enterprise lead form submitted** | User submits the enterprise contact form | `request_type`, `name`, `company`, `email`, `message` |
+
+---
+
+## Frontend Automatic Instrumentation (SaaS and OSS)
+
+The frontend initializes PostHog in both SaaS and OSS deployments (OSS uses a hardcoded fallback project key).
+
+| Feature | What It Captures |
+|---|---|
+| **Web Vitals** | LCP, FCP, INP, CLS |
+| **Network Timing** | API request latencies |
+| **Error Tracking** | Uncaught JavaScript exceptions |
+| **Pageviews** | Automatic page navigation tracking |
+| **Session Linking** | Correlates frontend sessions with backend events via `X-POSTHOG-SESSION-ID` tracing header (SaaS only) |
+
+Person profiles are created for identified users only. Session replay is **not configured in code** β€” whether it is active depends on the PostHog project's server-side settings.
+
+---
+
+## Event Lifecycle
+
+```
+User signs up β†’ user signed up + identify
+User logs in β†’ user logged in + identify
+Onboarding β†’ onboarding completed
+Git connect β†’ git provider connected
+Settings change β†’ settings saved
+
+Conversation starts β†’ conversation created
+ β”œβ”€ Finishes OK β†’ conversation finished
+ β”œβ”€ Errors β†’ conversation errored (+ credit limit reached if budget)
+ β”œβ”€ Stopped β†’ conversation finished
+ └─ Deleted β†’ conversation deleted
+
+Credit purchase β†’ credit purchased
+Team invite β†’ team members invited
+Trajectory export β†’ trajectory downloaded
+Org switch β†’ person properties updated (no event)
+```
+
+---
+
+## Dashboards (Staging Project)
+
+All dashboards below are tagged `analytics-overhaul` in the **Staging** PostHog project (ID 163845). They were created on 2026-03-05/06.
+
+### [Conversion Funnel](https://us.posthog.com/project/163845/dashboard/1334830)
+
+4-step ordered funnel with 30-day conversion window.
+
+| Step | Event |
+|---|---|
+| 1 | user signed up |
+| 2 | conversation created |
+| 3 | conversation finished |
+| 4 | credit purchased |
+
+### [User Retention](https://us.posthog.com/project/163845/dashboard/1334831)
+
+Weekly trends comparing new signups to returning users who create conversations. Note: this is a trends approximation (signups vs conversation DAU), not a true cohort retention chart.
+
+| Insight | Type | Events |
+|---|---|---|
+| Weekly Retention: Signup to Conversation | Trends (weekly) | `user signed up` (total), `conversation created` (DAU) |
+
+### [Credit Usage](https://us.posthog.com/project/163845/dashboard/1334832)
+
+| Insight | Type | Breakdown |
+|---|---|---|
+| Credit Purchased by Org | Trends (weekly) | `credit purchased` by `org_id` |
+| Credit Limit Reached by Org | Trends (weekly) | `credit limit reached` by `org_id` |
+| Avg Credit Balance After Purchase | Trends (weekly) | avg `credit_balance_after` on `credit purchased` |
+
+### [Churn Signals](https://us.posthog.com/project/163845/dashboard/1334833)
+
+| Insight | Type | Description |
+|---|---|---|
+| Churn Signal: Credit Limit Without Purchase | HogQL table | Users who hit credit limit in last 90 days with no subsequent purchase |
+
+### [Usage Patterns](https://us.posthog.com/project/163845/dashboard/1334834)
+
+| Insight | Type | Breakdown |
+|---|---|---|
+| Conversations by Model | Trends (weekly) | `conversation finished` by `llm_model` |
+| Conversations by Trigger | Trends (weekly) | `conversation finished` by `trigger` |
+| Avg Cost per Conversation | Trends (weekly) | avg `accumulated_cost_usd` on `conversation finished` |
+
+### [Product Quality](https://us.posthog.com/project/163845/dashboard/1334835)
+
+| Insight | Type | Breakdown |
+|---|---|---|
+| Success Rate by Terminal State | Trends (weekly) | `conversation finished` by `terminal_state` |
+| Error Rate by Model | Trends (weekly) | `conversation errored` by `llm_model` |
+
+### [Frontend Health](https://us.posthog.com/project/163845/dashboard/1337892)
+
+| Insight | Type | Description |
+|---|---|---|
+| Web Vitals -- LCP | Trends (daily, 30d) | Avg Largest Contentful Paint |
+| Web Vitals -- FCP | Trends (daily, 30d) | Avg First Contentful Paint |
+| Web Vitals -- INP | Trends (daily, 30d) | Avg Interaction to Next Paint |
+| Web Vitals -- CLS | Trends (daily, 30d) | Avg Cumulative Layout Shift |
+| JS Error Rate | Trends (daily, 30d) | Total `$exception` events per day |
+| Top JS Errors | Table (30d) | `$exception` broken down by `$exception_type` |
+
+---
+
+## Consent & Privacy
+
+- All backend events are gated on `user_consents_to_analytics`. No server-side data is sent when consent is absent.
+- Frontend consent is synced: `posthog.opt_in_capturing()` / `posthog.opt_out_capturing()` mirrors the backend setting.
+- OSS deployments send frontend-only automatic instrumentation (web vitals, errors, pageviews) to a shared PostHog project. No backend business events are sent.
+- Feature/staging environments are isolated β€” distinct IDs are prefixed with `FEATURE_` so test traffic never pollutes production data.
diff --git a/openhands/analytics/__init__.py b/openhands/analytics/__init__.py
new file mode 100644
index 0000000000..b7e0f45ca6
--- /dev/null
+++ b/openhands/analytics/__init__.py
@@ -0,0 +1,63 @@
+"""OpenHands analytics package.
+
+Provides a module-level singleton pattern for the AnalyticsService.
+
+Usage::
+
+ from openhands.analytics import init_analytics_service, get_analytics_service
+
+ # At application startup:
+ init_analytics_service(api_key=..., host=..., app_mode=..., is_feature_env=...)
+
+ # At call sites:
+ svc = get_analytics_service()
+ if svc:
+ svc.capture(...)
+"""
+
+from openhands.analytics.analytics_context import (
+ AnalyticsContext,
+ resolve_analytics_context,
+)
+from openhands.analytics.analytics_service import AnalyticsService
+from openhands.server.types import AppMode
+
+_analytics_service: AnalyticsService | None = None
+
+
+def init_analytics_service(
+ api_key: str,
+ host: str,
+ app_mode: AppMode,
+ is_feature_env: bool,
+) -> AnalyticsService:
+ """Create and store the module-level AnalyticsService singleton.
+
+ Returns the newly created instance. Subsequent calls to
+ :func:`get_analytics_service` will return the same object.
+ """
+ global _analytics_service
+ _analytics_service = AnalyticsService(
+ api_key=api_key,
+ host=host,
+ app_mode=app_mode,
+ is_feature_env=is_feature_env,
+ )
+ return _analytics_service
+
+
+def get_analytics_service() -> AnalyticsService | None:
+ """Return the module-level AnalyticsService singleton.
+
+ Returns ``None`` if :func:`init_analytics_service` has not been called yet.
+ """
+ return _analytics_service
+
+
+__all__ = [
+ 'AnalyticsContext',
+ 'AnalyticsService',
+ 'get_analytics_service',
+ 'init_analytics_service',
+ 'resolve_analytics_context',
+]
diff --git a/openhands/analytics/analytics_constants.py b/openhands/analytics/analytics_constants.py
new file mode 100644
index 0000000000..1dfb15a4cc
--- /dev/null
+++ b/openhands/analytics/analytics_constants.py
@@ -0,0 +1,23 @@
+"""Event name constants for PostHog analytics.
+
+Naming convention: PostHog recommended object-action, lowercase with spaces.
+"""
+
+# Phase 1 events
+USER_LOGGED_IN = 'user logged in'
+
+# Phase 2 events
+USER_SIGNED_UP = 'user signed up'
+CONVERSATION_CREATED = 'conversation created'
+CONVERSATION_FINISHED = 'conversation finished'
+CONVERSATION_ERRORED = 'conversation errored'
+CONVERSATION_DELETED = 'conversation deleted'
+CREDIT_PURCHASED = 'credit purchased'
+CREDIT_LIMIT_REACHED = 'credit limit reached'
+
+# Phase 4 events
+GIT_PROVIDER_CONNECTED = 'git provider connected'
+ONBOARDING_COMPLETED = 'onboarding completed'
+SETTINGS_SAVED = 'settings saved'
+TRAJECTORY_DOWNLOADED = 'trajectory downloaded'
+TEAM_MEMBERS_INVITED = 'team members invited'
diff --git a/openhands/analytics/analytics_context.py b/openhands/analytics/analytics_context.py
new file mode 100644
index 0000000000..af8495c4e2
--- /dev/null
+++ b/openhands/analytics/analytics_context.py
@@ -0,0 +1,98 @@
+"""AnalyticsContext: resolution helper for analytics call sites.
+
+Provides a dataclass that bundles user_id, consent status, org_id, and the
+full user object into a single value. The async ``resolve_analytics_context`` factory
+performs user lookup with full error isolation so callers never need
+try/except around user resolution.
+
+User lookup is performed via the AnalyticsUserProvider abstraction, which follows
+the get_impl() pattern used throughout OpenHands. Enterprise deployments provide
+their own implementation (e.g., SaasAnalyticsUserProvider) that queries the actual
+user store, while the default implementation returns None for local/OSS mode.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from openhands.analytics.user_base import UserBase
+from openhands.analytics.user_provider import AnalyticsUserProvider
+from openhands.app_server.utils.import_utils import get_impl
+from openhands.app_server.utils.logger import openhands_logger as logger
+
+# Sentinel reused by resolve_analytics_context for the safe-default path.
+_SAFE_DEFAULT_KWARGS: dict[str, Any] = {
+ 'consented': False,
+ 'org_id': None,
+ 'user': None,
+}
+
+
+@dataclass
+class AnalyticsContext:
+ """Resolved analytics context for a single user.
+
+ Attributes:
+ user_id: Raw user ID string (always set).
+ consented: Whether the user opted in to analytics. ``False`` is the
+ safe default (None / missing / error all map to False).
+ org_id: String org_id derived from ``user.current_org_id``, or
+ ``None`` when unavailable.
+ user: The UserBase instance, or ``None`` when lookup failed.
+ """
+
+ user_id: str
+ consented: bool
+ org_id: str | None
+ user: UserBase | None
+
+
+def _get_user_provider() -> AnalyticsUserProvider:
+ """Get the configured AnalyticsUserProvider implementation.
+
+ Uses get_impl() to load the implementation class specified in
+ server_config.analytics_user_provider_class. Defaults to
+ DefaultAnalyticsUserProvider if not configured.
+ """
+ from openhands.app_server.shared import server_config
+
+ impl_class = get_impl(
+ AnalyticsUserProvider, server_config.analytics_user_provider_class
+ )
+ return impl_class()
+
+
+async def resolve_analytics_context(user_id: str) -> AnalyticsContext:
+ """Resolve a user_id into a fully-populated :class:`AnalyticsContext`.
+
+ Performs user lookup via the configured AnalyticsUserProvider, extracts
+ consent and org_id, and wraps everything in try/except so no exception
+ ever leaks to the caller.
+
+ Returns a safe default (consented=False, org_id=None, user=None) when the
+ user is not found or any error occurs.
+ """
+ try:
+ provider = _get_user_provider()
+ user = await provider.get_user_by_id(user_id)
+
+ if user is None:
+ return AnalyticsContext(user_id=user_id, **_SAFE_DEFAULT_KWARGS)
+
+ # None = undecided = not consented (same logic as auth.py)
+ consented = user.user_consents_to_analytics is True
+ org_id = str(user.current_org_id) if user.current_org_id else None
+
+ return AnalyticsContext(
+ user_id=user_id,
+ consented=consented,
+ org_id=org_id,
+ user=user,
+ )
+ except Exception:
+ logger.warning(
+ 'resolve_analytics_context failed for user_id=%s, returning safe default',
+ user_id,
+ )
+ return AnalyticsContext(user_id=user_id, **_SAFE_DEFAULT_KWARGS)
diff --git a/openhands/analytics/analytics_service.py b/openhands/analytics/analytics_service.py
new file mode 100644
index 0000000000..25cba9c659
--- /dev/null
+++ b/openhands/analytics/analytics_service.py
@@ -0,0 +1,571 @@
+"""Core analytics service for OpenHands.
+
+Provides a thin wrapper around the PostHog SDK with:
+- Consent gate: all calls are no-ops when consented=False
+- OSS/SaaS dual-mode: $process_person_profile is set to False in OSS mode;
+ set_person_properties and group_identify are SaaS-only
+- Common properties: app_mode, is_feature_env added to every event
+- Feature-env distinct_id prefix: FEATURE_ prefix for staging/feature envs
+- SDK error isolation: all exceptions are caught and logged, never raised
+
+This module must NOT import from enterprise/. It receives all configuration
+via constructor args.
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from posthog import Posthog
+
+from openhands.analytics.analytics_constants import (
+ CONVERSATION_CREATED,
+ CONVERSATION_DELETED,
+ CONVERSATION_ERRORED,
+ CONVERSATION_FINISHED,
+ CREDIT_LIMIT_REACHED,
+ CREDIT_PURCHASED,
+ GIT_PROVIDER_CONNECTED,
+ ONBOARDING_COMPLETED,
+ SETTINGS_SAVED,
+ TEAM_MEMBERS_INVITED,
+ TRAJECTORY_DOWNLOADED,
+ USER_LOGGED_IN,
+ USER_SIGNED_UP,
+)
+from openhands.analytics.analytics_context import AnalyticsContext
+from openhands.app_server.utils.logger import openhands_logger as logger
+from openhands.server.types import AppMode
+
+
+class AnalyticsService:
+ """Server-side analytics service backed by PostHog.
+
+ Args:
+ api_key: PostHog project API key. Pass an empty string to disable.
+ host: PostHog ingest host URL.
+ app_mode: AppMode.OPENHANDS (OSS) or AppMode.SAAS.
+ is_feature_env: True when running in a feature/staging environment.
+ """
+
+ def __init__(
+ self,
+ api_key: str,
+ host: str,
+ app_mode: AppMode,
+ is_feature_env: bool,
+ ) -> None:
+ self._app_mode = app_mode
+ self._is_feature_env = is_feature_env
+ self._client: Posthog = Posthog(
+ project_api_key=api_key,
+ host=host,
+ disabled=not api_key,
+ )
+
+ # ------------------------------------------------------------------
+ # Public API
+ # ------------------------------------------------------------------
+
+ def capture(
+ self,
+ ctx: AnalyticsContext,
+ event: str,
+ properties: dict[str, Any] | None = None,
+ session_id: str | None = None,
+ ) -> None:
+ """Capture a server-side event.
+
+ Consent gate: returns immediately when ctx.consented=False.
+ Common properties (app_mode, is_feature_env, and optionally org_id /
+ $session_id / $process_person_profile) are merged with caller-provided
+ properties before forwarding to PostHog.
+ """
+ if not ctx.consented:
+ return
+
+ merged = self._common_properties(org_id=ctx.org_id, session_id=session_id)
+ if properties:
+ merged.update(properties)
+
+ try:
+ self._client.capture(
+ distinct_id=self._distinct_id(ctx.user_id),
+ event=event,
+ properties=merged,
+ )
+ except Exception:
+ logger.exception('AnalyticsService.capture failed for event=%s', event)
+
+ def set_person_properties(
+ self,
+ ctx: AnalyticsContext,
+ properties: dict[str, Any],
+ ) -> None:
+ """Set person properties in PostHog (SaaS-only).
+
+ No-op in OSS mode or when ctx.consented=False.
+ """
+ if not ctx.consented:
+ return
+ if self._app_mode != AppMode.SAAS:
+ return
+
+ try:
+ self._client.set(
+ distinct_id=self._distinct_id(ctx.user_id),
+ properties=properties,
+ )
+ except Exception:
+ logger.exception('AnalyticsService.set_person_properties failed')
+
+ def group_identify(
+ self,
+ ctx: AnalyticsContext,
+ group_type: str,
+ group_key: str,
+ properties: dict[str, Any],
+ ) -> None:
+ """Associate a group with properties (SaaS-only).
+
+ No-op in OSS mode or when ctx.consented=False.
+ """
+ if not ctx.consented:
+ return
+ if self._app_mode != AppMode.SAAS:
+ return
+
+ try:
+ self._client.group_identify(
+ group_type=group_type,
+ group_key=group_key,
+ properties=properties,
+ distinct_id=self._distinct_id(ctx.user_id),
+ )
+ except Exception:
+ logger.exception('AnalyticsService.group_identify failed')
+
+ # ------------------------------------------------------------------
+ # Typed event methods
+ # ------------------------------------------------------------------
+
+ def track_user_signed_up(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ email_domain: str | None = None,
+ invitation_source: str = 'self_signup',
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'user signed up' event.
+
+ Fired when a new user completes registration.
+ """
+ self.capture(
+ ctx=ctx,
+ event=USER_SIGNED_UP,
+ properties={
+ 'email_domain': email_domain,
+ 'invitation_source': invitation_source,
+ },
+ session_id=session_id,
+ )
+
+ def track_user_logged_in(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ idp: str,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'user logged in' event.
+
+ Fired when an existing user authenticates.
+ """
+ self.capture(
+ ctx=ctx,
+ event=USER_LOGGED_IN,
+ properties={
+ 'idp': idp,
+ },
+ session_id=session_id,
+ )
+
+ def track_conversation_created(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ conversation_id: str,
+ trigger: str | None = None,
+ llm_model: str | None = None,
+ agent_type: str = 'default',
+ has_repository: bool = False,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'conversation created' event.
+
+ Fired when a new conversation is started.
+ """
+ self.capture(
+ ctx=ctx,
+ event=CONVERSATION_CREATED,
+ properties={
+ 'conversation_id': conversation_id,
+ 'trigger': trigger,
+ 'llm_model': llm_model,
+ 'agent_type': agent_type,
+ 'has_repository': has_repository,
+ },
+ session_id=session_id,
+ )
+
+ def track_conversation_finished(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ conversation_id: str,
+ terminal_state: str,
+ turn_count: int | None = None,
+ accumulated_cost_usd: float | None = None,
+ prompt_tokens: int | None = None,
+ completion_tokens: int | None = None,
+ llm_model: str | None = None,
+ trigger: str | None = None,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'conversation finished' event.
+
+ Fired when a conversation reaches a terminal state.
+ """
+ self.capture(
+ ctx=ctx,
+ event=CONVERSATION_FINISHED,
+ properties={
+ 'conversation_id': conversation_id,
+ 'terminal_state': terminal_state,
+ 'turn_count': turn_count,
+ 'accumulated_cost_usd': accumulated_cost_usd,
+ 'prompt_tokens': prompt_tokens,
+ 'completion_tokens': completion_tokens,
+ 'llm_model': llm_model,
+ 'trigger': trigger,
+ },
+ session_id=session_id,
+ )
+
+ def track_conversation_errored(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ conversation_id: str,
+ error_type: str,
+ error_message: str | None = None,
+ llm_model: str | None = None,
+ turn_count: int | None = None,
+ terminal_state: str,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'conversation errored' event.
+
+ Fired when a conversation ends in an error state.
+ """
+ self.capture(
+ ctx=ctx,
+ event=CONVERSATION_ERRORED,
+ properties={
+ 'conversation_id': conversation_id,
+ 'error_type': error_type,
+ 'error_message': error_message,
+ 'llm_model': llm_model,
+ 'turn_count': turn_count,
+ 'terminal_state': terminal_state,
+ },
+ session_id=session_id,
+ )
+
+ def track_conversation_deleted(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ conversation_id: str,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'conversation deleted' event.
+
+ Fired when a user deletes a conversation.
+ """
+ self.capture(
+ ctx=ctx,
+ event=CONVERSATION_DELETED,
+ properties={
+ 'conversation_id': conversation_id,
+ },
+ session_id=session_id,
+ )
+
+ def track_credit_purchased(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ amount_usd: float,
+ credit_balance_before: float | None = None,
+ credit_balance_after: float | None = None,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'credit purchased' event.
+
+ Fired when a user completes a credit purchase.
+ """
+ self.capture(
+ ctx=ctx,
+ event=CREDIT_PURCHASED,
+ properties={
+ 'amount_usd': amount_usd,
+ 'credit_balance_before': credit_balance_before,
+ 'credit_balance_after': credit_balance_after,
+ },
+ session_id=session_id,
+ )
+
+ def track_credit_limit_reached(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ conversation_id: str,
+ credit_balance: float | None = None,
+ llm_model: str | None = None,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'credit limit reached' event.
+
+ Fired when a conversation is blocked by insufficient credits.
+ """
+ self.capture(
+ ctx=ctx,
+ event=CREDIT_LIMIT_REACHED,
+ properties={
+ 'conversation_id': conversation_id,
+ 'credit_balance': credit_balance,
+ 'llm_model': llm_model,
+ },
+ session_id=session_id,
+ )
+
+ def track_git_provider_connected(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ provider_type: str,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'git provider connected' event.
+
+ Fired when a user connects a git provider (GitHub, GitLab, etc.).
+ """
+ self.capture(
+ ctx=ctx,
+ event=GIT_PROVIDER_CONNECTED,
+ properties={
+ 'provider_type': provider_type,
+ },
+ session_id=session_id,
+ )
+
+ def track_onboarding_completed(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ selections: dict[str, str | list[str]] | None = None,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'onboarding completed' event.
+
+ Fired when a user finishes the onboarding flow.
+
+ Args:
+ selections: Dynamic key-value pairs from the onboarding form.
+ Keys are question IDs (e.g., 'role', 'org_size', 'use_case',
+ 'org_name', 'org_domain'). Values are the selected option IDs
+ or arrays for multi-select questions.
+ """
+ self.capture(
+ ctx=ctx,
+ event=ONBOARDING_COMPLETED,
+ properties=selections or {},
+ session_id=session_id,
+ )
+
+ def track_settings_saved(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ settings_changed: list[str] | None = None,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'settings saved' event.
+
+ Fired when a user saves their settings.
+ """
+ self.capture(
+ ctx=ctx,
+ event=SETTINGS_SAVED,
+ properties={
+ 'settings_changed': settings_changed,
+ },
+ session_id=session_id,
+ )
+
+ def track_trajectory_downloaded(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ conversation_id: str,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'trajectory downloaded' event.
+
+ Fired when a user downloads a conversation trajectory.
+ """
+ self.capture(
+ ctx=ctx,
+ event=TRAJECTORY_DOWNLOADED,
+ properties={
+ 'conversation_id': conversation_id,
+ },
+ session_id=session_id,
+ )
+
+ def track_team_members_invited(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ invited_count: int,
+ successful_count: int,
+ failed_count: int,
+ role: str,
+ session_id: str | None = None,
+ ) -> None:
+ """Track 'team members invited' event.
+
+ Fired when a user invites team members to their organization.
+ """
+ self.capture(
+ ctx=ctx,
+ event=TEAM_MEMBERS_INVITED,
+ properties={
+ 'invited_count': invited_count,
+ 'successful_count': successful_count,
+ 'failed_count': failed_count,
+ 'role': role,
+ },
+ session_id=session_id,
+ )
+
+ def identify_user(
+ self,
+ ctx: AnalyticsContext,
+ *,
+ email: str | None = None,
+ org_name: str | None = None,
+ idp: str | None = None,
+ orgs: list[dict[str, Any]] | None = None,
+ ) -> None:
+ """Identify a user and their org memberships in PostHog.
+
+ Consolidates the duplicated ``set_person_properties`` +
+ ``group_identify`` pattern from auth.py and oauth_device.py into
+ a single call.
+
+ Consent gate: returns immediately when ``ctx.consented=False``.
+ SaaS gate: returns immediately in OSS mode (person profiles are
+ SaaS-only).
+
+ Args:
+ ctx: Analytics context with user_id, org_id, and consent.
+ email: User email address.
+ org_name: Current org display name.
+ idp: Identity provider (e.g. ``"github"``, ``"google"``).
+ orgs: List of org dicts with keys ``id``, ``name``,
+ ``member_count`` for group_identify calls.
+ """
+ if not ctx.consented:
+ return
+ if self._app_mode != AppMode.SAAS:
+ return
+
+ try:
+ # Person properties
+ self.set_person_properties(
+ ctx=ctx,
+ properties={
+ 'email': email,
+ 'org_id': ctx.org_id,
+ 'org_name': org_name,
+ 'plan_tier': None,
+ 'idp': idp,
+ 'last_login_at': datetime.now(timezone.utc).isoformat(),
+ },
+ )
+
+ # Group identify for each org membership
+ if orgs:
+ for org in orgs:
+ self.group_identify(
+ ctx=ctx,
+ group_type='org',
+ group_key=org['id'],
+ properties={
+ 'org_name': org.get('name'),
+ 'plan_tier': None,
+ 'created_at': None,
+ 'member_count': org.get('member_count'),
+ },
+ )
+ except Exception:
+ logger.exception('AnalyticsService.identify_user failed')
+
+ def shutdown(self) -> None:
+ """Flush and shut down the PostHog client.
+
+ Safe to call multiple times. SDK errors are logged, not raised.
+ """
+ try:
+ self._client.shutdown()
+ except Exception:
+ logger.exception('AnalyticsService.shutdown failed')
+
+ # ------------------------------------------------------------------
+ # Private helpers
+ # ------------------------------------------------------------------
+
+ def _distinct_id(self, user_id: str) -> str:
+ """Return the PostHog distinct_id for the given user.
+
+ In feature/staging environments, prefixes with 'FEATURE_' to keep
+ test traffic separate from production profiles.
+ """
+ if self._is_feature_env:
+ return f'FEATURE_{user_id}'
+ return user_id
+
+ def _common_properties(
+ self,
+ org_id: str | None = None,
+ session_id: str | None = None,
+ ) -> dict[str, Any]:
+ """Build the base property dict included on every event."""
+ props: dict[str, Any] = {
+ 'app_mode': self._app_mode.value,
+ 'is_feature_env': self._is_feature_env,
+ }
+
+ if org_id is not None:
+ props['org_id'] = org_id
+
+ if session_id is not None:
+ props['$session_id'] = session_id
+
+ # PostHog person profiles are not useful in OSS mode (no user accounts)
+ if self._app_mode != AppMode.SAAS:
+ props['$process_person_profile'] = False
+
+ return props
diff --git a/openhands/analytics/oss_install_id.py b/openhands/analytics/oss_install_id.py
new file mode 100644
index 0000000000..ff529be62f
--- /dev/null
+++ b/openhands/analytics/oss_install_id.py
@@ -0,0 +1,39 @@
+"""OSS install ID utility.
+
+Provides a stable distinct_id for OSS installations by persisting a UUID
+to a file in the persistence directory.
+"""
+
+import uuid
+from pathlib import Path
+
+
+def get_or_create_install_id(persistence_dir: Path) -> str:
+ """Return a stable install UUID for an OSS installation.
+
+ On first call, generates a new UUID4, writes it to
+ ``{persistence_dir}/analytics_id.txt``, and returns it.
+ On subsequent calls, reads and returns the stored UUID.
+
+ On any IOError (e.g., read-only filesystem), returns an ephemeral UUID
+ without crashing β€” the caller still gets a usable ID.
+ """
+ id_file = persistence_dir / 'analytics_id.txt'
+
+ try:
+ if id_file.exists():
+ stored = id_file.read_text().strip()
+ if stored:
+ return stored
+ except OSError:
+ pass
+
+ new_id = str(uuid.uuid4())
+
+ try:
+ id_file.write_text(new_id)
+ except OSError:
+ # File system is not writable β€” return ephemeral UUID
+ pass
+
+ return new_id
diff --git a/openhands/analytics/user_base.py b/openhands/analytics/user_base.py
new file mode 100644
index 0000000000..4b1fb7f8e2
--- /dev/null
+++ b/openhands/analytics/user_base.py
@@ -0,0 +1,39 @@
+"""Protocol for User models across OSS and Enterprise.
+
+This module provides a Protocol that defines the minimal interface required
+for analytics user lookup. Any object with matching attributes satisfies
+the protocol β€” no inheritance required (structural typing).
+
+Uses Any types for compatibility with SQLAlchemy's Mapped descriptors,
+which mypy sees as Mapped[T] rather than T without the SQLAlchemy mypy plugin.
+The actual expected types are documented in the docstring.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class UserBase(Protocol):
+ """Protocol defining the user interface for analytics.
+
+ This protocol defines the minimal set of attributes required for analytics
+ functionality. Any object with these attributes satisfies the protocol,
+ including SQLAlchemy models and mock objects in tests.
+
+ All attributes use ``Any`` type for compatibility with SQLAlchemy Mapped
+ descriptors. The expected runtime types are:
+
+ Attributes:
+ id: UUID | str - User's unique identifier.
+ user_consents_to_analytics: bool | None - Whether user consented to
+ analytics, or None if undecided (treated as False).
+ current_org_id: UUID | str | None - Organization ID, or None.
+ accepted_tos: datetime | None - When user accepted terms of service.
+ """
+
+ id: Any
+ user_consents_to_analytics: Any
+ current_org_id: Any
+ accepted_tos: Any
diff --git a/openhands/analytics/user_provider.py b/openhands/analytics/user_provider.py
new file mode 100644
index 0000000000..76b4bba054
--- /dev/null
+++ b/openhands/analytics/user_provider.py
@@ -0,0 +1,54 @@
+"""Abstract base class for analytics user lookup.
+
+This module provides an extension point for user lookup in analytics contexts.
+The default implementation returns None, which results in safe defaults being
+used. Enterprise deployments can provide their own implementation that queries
+the actual user store.
+
+The implementation class is configured via server_config.analytics_user_provider_class
+and loaded via get_impl() at runtime.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from openhands.analytics.user_base import UserBase
+
+
+class AnalyticsUserProvider(ABC):
+ """Abstract base class for looking up users for analytics purposes.
+
+ This is an extension point that allows enterprise deployments to provide
+ user lookup functionality without the open-source codebase depending on
+ enterprise modules.
+
+ The default implementation (DefaultAnalyticsUserProvider) returns None,
+ which causes resolve_analytics_context to use safe defaults.
+ """
+
+ @abstractmethod
+ async def get_user_by_id(self, user_id: str) -> UserBase | None:
+ """Look up a user by their ID.
+
+ Args:
+ user_id: The user's unique identifier.
+
+ Returns:
+ A UserBase instance with `user_consents_to_analytics` and
+ `current_org_id` attributes, or None if the user cannot be found
+ or user lookup is not available.
+ """
+
+
+class DefaultAnalyticsUserProvider(AnalyticsUserProvider):
+ """Default implementation that returns None for all lookups.
+
+ This is used in open-source/local deployments where no user store is
+ available. All analytics calls will use safe defaults (consented=False,
+ org_id=None, user=None).
+ """
+
+ async def get_user_by_id(self, user_id: str) -> UserBase | None:
+ """Return None since no user store is available in local mode."""
+ return None
diff --git a/openhands/app_server/app_conversation/app_conversation_router.py b/openhands/app_server/app_conversation/app_conversation_router.py
index 3777c56f24..c6d8529286 100644
--- a/openhands/app_server/app_conversation/app_conversation_router.py
+++ b/openhands/app_server/app_conversation/app_conversation_router.py
@@ -16,6 +16,7 @@ from fastapi.responses import JSONResponse, StreamingResponse
from sqlalchemy.ext.asyncio import AsyncSession
from openhands.agent_server.models import Success
+from openhands.analytics import get_analytics_service, resolve_analytics_context
from openhands.app_server.app_conversation.app_conversation_info_service import (
AppConversationInfoService,
)
@@ -352,6 +353,7 @@ async def batch_get_app_conversations(
async def start_app_conversation(
request: Request,
start_request: AppConversationStartRequest,
+ user_context: UserContext = user_context_dependency,
db_session: AsyncSession = db_session_dependency,
httpx_client: httpx.AsyncClient = httpx_client_dependency,
app_conversation_service: AppConversationService = (
@@ -366,6 +368,29 @@ async def start_app_conversation(
"""Start an app conversation start task and return it."""
async_iter = app_conversation_service.start_app_conversation(start_request)
result = await anext(async_iter)
+
+ # Analytics: conversation created (V1)
+ try:
+ analytics = get_analytics_service()
+ if analytics:
+ user_id = await user_context.get_user_id()
+ if user_id:
+ ctx = await resolve_analytics_context(user_id)
+ analytics.track_conversation_created(
+ ctx=ctx,
+ conversation_id=str(result.app_conversation_id)
+ if result.app_conversation_id
+ else result.id,
+ trigger=start_request.trigger.value
+ if start_request.trigger
+ else None,
+ llm_model=None, # Not available at start time
+ agent_type='default',
+ has_repository=start_request.selected_repository is not None,
+ )
+ except Exception:
+ logger.exception('analytics:conversation_created:failed')
+
asyncio.create_task(_consume_remaining(async_iter, db_session, httpx_client))
return result
except Exception:
@@ -631,6 +656,20 @@ async def delete_app_conversation(
if not deleted:
raise HTTPException(status.HTTP_404_NOT_FOUND, 'Failed to delete conversation')
+ # Analytics: conversation deleted (V1)
+ try:
+ analytics = get_analytics_service()
+ if analytics and app_conversation_info.created_by_user_id:
+ ctx = await resolve_analytics_context(
+ app_conversation_info.created_by_user_id
+ )
+ analytics.track_conversation_deleted(
+ ctx=ctx,
+ conversation_id=conversation_id,
+ )
+ except Exception:
+ logger.exception('analytics:conversation_deleted:failed')
+
# Commit the deletion
await db_session.commit()
@@ -1094,6 +1133,7 @@ async def export_conversation(
app_conversation_service: AppConversationService = (
app_conversation_service_dependency
),
+ user_context: UserContext = user_context_dependency,
):
"""Download a conversation trajectory as a zip file.
@@ -1111,6 +1151,29 @@ async def export_conversation(
conversation_id
)
+ # Analytics: track trajectory download
+ try:
+ analytics = get_analytics_service()
+ user_id = await user_context.get_user_id()
+ if analytics and user_id:
+ from openhands.analytics.analytics_context import AnalyticsContext
+
+ user_info = await user_context.get_user_info()
+ ctx = AnalyticsContext(
+ user_id=user_id,
+ consented=user_info.user_consents_to_analytics
+ if user_info and user_info.user_consents_to_analytics is not None
+ else False,
+ org_id=None,
+ user=None,
+ )
+ analytics.track_trajectory_downloaded(
+ ctx=ctx,
+ conversation_id=str(conversation_id),
+ )
+ except Exception:
+ logger.exception('analytics:trajectory_downloaded:failed')
+
# Return as a downloadable zip file
return Response(
content=zip_content,
diff --git a/openhands/app_server/config.py b/openhands/app_server/config.py
index 2cb7abdcdf..e2e5ac1e2d 100644
--- a/openhands/app_server/config.py
+++ b/openhands/app_server/config.py
@@ -171,10 +171,14 @@ def resolve_provider_llm_base_url(
def _get_default_lifespan():
- # Check legacy parameters for saas mode. If we are in SAAS mode do not apply
- # OpenHands alembic migrations
+ # Check legacy parameters for saas mode. If we are in SAAS mode use
+ # SaasAppLifespanService to initialize PostHog analytics
if 'saas' in (os.getenv('OPENHANDS_CONFIG_CLS') or '').lower():
- return None
+ from server.app_lifespan.saas_app_lifespan_service import (
+ SaasAppLifespanService,
+ )
+
+ return SaasAppLifespanService()
return OssAppLifespanService()
diff --git a/openhands/app_server/event_callback/webhook_router.py b/openhands/app_server/event_callback/webhook_router.py
index d32e1466fe..7b856d331a 100644
--- a/openhands/app_server/event_callback/webhook_router.py
+++ b/openhands/app_server/event_callback/webhook_router.py
@@ -13,6 +13,7 @@ from pydantic import SecretStr
from openhands import tools # type: ignore[attr-defined]
from openhands.agent_server.models import ConversationInfo, Success
+from openhands.analytics import get_analytics_service, resolve_analytics_context
from openhands.app_server.app_conversation.app_conversation_info_service import (
AppConversationInfoService,
)
@@ -60,6 +61,29 @@ app_mode = get_global_config().app_mode
_logger = logging.getLogger(__name__)
+def _classify_error_type(error_message: str | None) -> str:
+ """Classify conversation error into broad categories for dashboard filtering.
+
+ Categories: budget_exceeded, model_error, runtime_error, timeout, user_cancelled, unknown.
+ Uses best-effort string matching per CONTEXT.md decision.
+ """
+ if not error_message:
+ return 'unknown'
+ msg_lower = error_message.lower()
+ if 'budget' in msg_lower or 'budgetexceeded' in msg_lower:
+ return 'budget_exceeded'
+ if 'timeout' in msg_lower or 'timed out' in msg_lower:
+ return 'timeout'
+ if 'cancel' in msg_lower:
+ return 'user_cancelled'
+ if any(
+ kw in msg_lower
+ for kw in ('model', 'llm', 'api key', 'rate limit', 'authentication')
+ ):
+ return 'model_error'
+ return 'runtime_error'
+
+
def merge_conversation_tags(
existing_tags: dict[str, str] | None,
incoming_tags: dict[str, str] | None,
@@ -78,6 +102,86 @@ def merge_conversation_tags(
return {**existing, **incoming}
+async def _track_conversation_terminal(
+ conversation_id: UUID,
+ app_conversation_info: AppConversationInfo,
+ events: list[Event],
+ exec_status: ConversationExecutionStatus,
+) -> None:
+ """Track analytics for terminal conversation states.
+
+ Handles BIZZ-03 (credit limit), BIZZ-05 (finished), and BIZZ-06 (errored) events.
+ """
+ analytics = get_analytics_service()
+ if not analytics or not app_conversation_info.created_by_user_id:
+ return
+
+ ctx = await resolve_analytics_context(app_conversation_info.created_by_user_id)
+
+ # Extract metrics
+ metrics = app_conversation_info.metrics
+ accumulated_cost = metrics.accumulated_cost if metrics else None
+ prompt_tokens = (
+ metrics.accumulated_token_usage.prompt_tokens
+ if metrics and metrics.accumulated_token_usage
+ else None
+ )
+ completion_tokens = (
+ metrics.accumulated_token_usage.completion_tokens
+ if metrics and metrics.accumulated_token_usage
+ else None
+ )
+
+ is_error = exec_status in (
+ ConversationExecutionStatus.ERROR,
+ ConversationExecutionStatus.STUCK,
+ )
+
+ if is_error:
+ # Find last error message
+ error_message = None
+ for ev in events:
+ if isinstance(ev, ConversationStateUpdateEvent) and ev.key == 'last_error':
+ error_message = str(ev.value)[:500] if ev.value else None
+
+ error_type = _classify_error_type(error_message)
+
+ # BIZZ-06: conversation errored
+ analytics.track_conversation_errored(
+ ctx=ctx,
+ conversation_id=str(conversation_id),
+ error_type=error_type,
+ error_message=error_message,
+ llm_model=app_conversation_info.llm_model,
+ turn_count=None,
+ terminal_state=exec_status.value,
+ )
+
+ # BIZZ-03: credit limit reached
+ if error_type == 'budget_exceeded':
+ analytics.track_credit_limit_reached(
+ ctx=ctx,
+ conversation_id=str(conversation_id),
+ llm_model=app_conversation_info.llm_model,
+ )
+ return
+
+ # BIZZ-05: conversation finished
+ analytics.track_conversation_finished(
+ ctx=ctx,
+ conversation_id=str(conversation_id),
+ terminal_state=exec_status.value,
+ turn_count=None,
+ accumulated_cost_usd=accumulated_cost,
+ prompt_tokens=prompt_tokens,
+ completion_tokens=completion_tokens,
+ llm_model=app_conversation_info.llm_model,
+ trigger=app_conversation_info.trigger.value
+ if app_conversation_info.trigger
+ else None,
+ )
+
+
def detect_automation_trigger(
current_trigger: ConversationTrigger | None,
merged_tags: dict[str, str],
@@ -262,6 +366,23 @@ async def on_conversation_update(
)
)
+ # Analytics: conversation created
+ analytics = get_analytics_service()
+ if analytics and sandbox_info.created_by_user_id:
+ ctx = await resolve_analytics_context(sandbox_info.created_by_user_id)
+ analytics.track_conversation_created(
+ ctx=ctx,
+ conversation_id=str(conversation_info.id),
+ trigger=existing.trigger.value if existing.trigger else None,
+ llm_model=(
+ conversation_info.agent.llm.model
+ if conversation_info.agent and conversation_info.agent.llm
+ else None
+ ),
+ agent_type='default',
+ has_repository=existing.selected_repository is not None,
+ )
+
return Success()
@@ -287,6 +408,21 @@ async def on_event(
event, conversation_id
)
+ # Analytics: conversation terminal state detection
+ for event in events:
+ if not isinstance(event, ConversationStateUpdateEvent):
+ continue
+ if event.key != 'execution_status':
+ continue
+ try:
+ exec_status = ConversationExecutionStatus(event.value)
+ if exec_status.is_terminal():
+ await _track_conversation_terminal(
+ conversation_id, app_conversation_info, events, exec_status
+ )
+ except Exception:
+ _logger.exception('analytics:conversation_terminal:failed')
+
asyncio.create_task(
_run_callbacks_in_bg_and_close(
conversation_id, app_conversation_info.created_by_user_id, events
diff --git a/openhands/app_server/sandbox/sandbox_router.py b/openhands/app_server/sandbox/sandbox_router.py
index b2f0747b97..7ad0fcd0d5 100644
--- a/openhands/app_server/sandbox/sandbox_router.py
+++ b/openhands/app_server/sandbox/sandbox_router.py
@@ -7,7 +7,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response,
from fastapi.security import APIKeyHeader
from openhands.agent_server.models import Success
-from openhands.app_server.config import depends_sandbox_service
+from openhands.app_server.config import depends_sandbox_service, depends_user_context
from openhands.app_server.sandbox.sandbox_models import (
SandboxInfo,
SandboxPage,
@@ -19,6 +19,7 @@ from openhands.app_server.sandbox.sandbox_service import (
)
from openhands.app_server.sandbox.session_auth import validate_session_key
from openhands.app_server.user.auth_user_context import AuthUserContext
+from openhands.app_server.user.user_context import UserContext
from openhands.app_server.user_auth.user_auth import (
get_for_user as get_user_auth_for_user,
)
@@ -32,6 +33,7 @@ router = APIRouter(
prefix='/sandboxes', tags=['Sandbox'], dependencies=get_dependencies()
)
sandbox_service_dependency = depends_sandbox_service()
+user_context_dependency = depends_user_context()
# Read methods
@@ -93,11 +95,13 @@ async def pause_sandbox(
@router.post('/{sandbox_id}/resume', responses={404: {'description': 'Item not found'}})
async def resume_sandbox(
sandbox_id: str,
+ user_context: UserContext = user_context_dependency,
sandbox_service: SandboxService = sandbox_service_dependency,
) -> Success:
exists = await sandbox_service.resume_sandbox(sandbox_id)
if not exists:
raise HTTPException(status.HTTP_404_NOT_FOUND)
+
return Success()
diff --git a/openhands/app_server/secrets/secrets_router.py b/openhands/app_server/secrets/secrets_router.py
index 5e5da9e182..d3e561b14e 100644
--- a/openhands/app_server/secrets/secrets_router.py
+++ b/openhands/app_server/secrets/secrets_router.py
@@ -26,6 +26,7 @@ from openhands.app_server.user_auth import (
get_provider_tokens,
get_secrets,
get_secrets_store,
+ get_user_id,
)
from openhands.app_server.utils.dependencies import get_dependencies
from openhands.app_server.utils.models import EditResponse
@@ -96,6 +97,7 @@ async def store_provider_tokens(
provider_info: POSTProviderModel,
secrets_store: SecretsStore = Depends(get_secrets_store),
provider_tokens: PROVIDER_TOKEN_TYPE | None = Depends(get_provider_tokens),
+ user_id: str | None = Depends(get_user_id),
) -> EditResponse:
"""Store git provider tokens.
@@ -131,6 +133,20 @@ async def store_provider_tokens(
)
await secrets_store.store(updated_secrets)
+ # ACTV-02: git provider connected analytics
+ from openhands.analytics import get_analytics_service, resolve_analytics_context
+
+ analytics = get_analytics_service()
+ if analytics and user_id and provider_info.provider_tokens:
+ ctx = await resolve_analytics_context(user_id)
+ for provider_type, token_value in provider_info.provider_tokens.items():
+ # Only fire for providers with actual token, not host-only updates
+ if token_value.token:
+ analytics.track_git_provider_connected(
+ ctx=ctx,
+ provider_type=provider_type.value,
+ )
+
return EditResponse(
message='Git providers stored',
)
diff --git a/openhands/app_server/server_config/server_config.py b/openhands/app_server/server_config/server_config.py
index 71108daa10..52b0d13bf7 100644
--- a/openhands/app_server/server_config/server_config.py
+++ b/openhands/app_server/server_config/server_config.py
@@ -23,6 +23,7 @@ class ServerConfig(ServerConfigInterface):
user_auth_class: str = (
'openhands.app_server.user_auth.default_user_auth.DefaultUserAuth'
)
+ analytics_user_provider_class: str | None = None
enable_v1: bool = os.getenv('ENABLE_V1') != '0'
def verify_config(self):
diff --git a/openhands/app_server/settings/settings_router.py b/openhands/app_server/settings/settings_router.py
index 61ebb4907d..1c3d3a8371 100644
--- a/openhands/app_server/settings/settings_router.py
+++ b/openhands/app_server/settings/settings_router.py
@@ -12,6 +12,7 @@ from fastapi import APIRouter, Body, Depends, HTTPException, Path, status
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field
+from openhands.analytics import get_analytics_service
from openhands.app_server.integrations.provider import (
PROVIDER_TOKEN_TYPE,
ProviderType,
@@ -196,6 +197,7 @@ async def load_settings(
async def store_settings(
payload: dict[str, Any],
settings_store: SettingsStore = Depends(get_user_settings_store),
+ user_id: str | None = Depends(get_user_id),
) -> JSONResponse:
"""Store user settings.
@@ -238,6 +240,28 @@ async def store_settings(
settings.disabled_skills = existing_settings.disabled_skills
await settings_store.store(settings)
+
+ # Analytics: track settings saved
+ try:
+ analytics = get_analytics_service()
+ if analytics and user_id:
+ from openhands.analytics.analytics_context import AnalyticsContext
+
+ ctx = AnalyticsContext(
+ user_id=user_id,
+ consented=settings.user_consents_to_analytics is True,
+ org_id=None,
+ user=None,
+ )
+
+ settings_changed = list(payload.keys())
+ analytics.track_settings_saved(
+ ctx=ctx,
+ settings_changed=settings_changed,
+ )
+ except Exception:
+ logger.exception('analytics:settings_saved:failed')
+
return JSONResponse(
status_code=status.HTTP_200_OK,
content={'message': 'Settings stored'},
diff --git a/tests/unit/app_server/analytics/__init__.py b/tests/unit/app_server/analytics/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/tests/unit/test_analytics_context.py b/tests/unit/test_analytics_context.py
new file mode 100644
index 0000000000..0e1df8971d
--- /dev/null
+++ b/tests/unit/test_analytics_context.py
@@ -0,0 +1,194 @@
+"""Tests for AnalyticsContext dataclass and resolve_analytics_context factory."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openhands.analytics.analytics_context import (
+ AnalyticsContext,
+ resolve_analytics_context,
+)
+from openhands.analytics.user_provider import (
+ AnalyticsUserProvider,
+ DefaultAnalyticsUserProvider,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class MockAnalyticsUserProvider(AnalyticsUserProvider):
+ """Mock provider for testing that returns a configurable user."""
+
+ def __init__(self, user=None, raise_exception=None):
+ self._user = user
+ self._raise_exception = raise_exception
+
+ async def get_user_by_id(self, user_id: str):
+ if self._raise_exception:
+ raise self._raise_exception
+ return self._user
+
+
+def _patch_user_provider(provider: AnalyticsUserProvider):
+ """Create a patch context that makes _get_user_provider return the given provider."""
+ return patch(
+ 'openhands.analytics.analytics_context._get_user_provider',
+ return_value=provider,
+ )
+
+
+# ---------------------------------------------------------------------------
+# AnalyticsUserProvider tests
+# ---------------------------------------------------------------------------
+
+
+class TestAnalyticsUserProvider:
+ """Tests for AnalyticsUserProvider base class and default implementation."""
+
+ @pytest.mark.asyncio
+ async def test_default_provider_returns_none(self):
+ """DefaultAnalyticsUserProvider.get_user_by_id returns None for any user_id."""
+ provider = DefaultAnalyticsUserProvider()
+ result = await provider.get_user_by_id('any-user-id')
+ assert result is None
+
+
+# ---------------------------------------------------------------------------
+# AnalyticsContext dataclass tests
+# ---------------------------------------------------------------------------
+
+
+class TestAnalyticsContext:
+ """Tests for AnalyticsContext dataclass construction and field storage."""
+
+ def test_context_stores_all_fields_correctly(self):
+ """AnalyticsContext constructed with explicit values stores user_id, consented, org_id, user fields correctly."""
+ mock_user = MagicMock()
+ ctx = AnalyticsContext(
+ user_id='user-123',
+ consented=True,
+ org_id='org-456',
+ user=mock_user,
+ )
+ assert ctx.user_id == 'user-123'
+ assert ctx.consented is True
+ assert ctx.org_id == 'org-456'
+ assert ctx.user is mock_user
+
+ def test_context_default_safe_values(self):
+ """AnalyticsContext can be created with safe defaults (consented=False, org_id=None, user=None)."""
+ ctx = AnalyticsContext(
+ user_id='user-123',
+ consented=False,
+ org_id=None,
+ user=None,
+ )
+ assert ctx.user_id == 'user-123'
+ assert ctx.consented is False
+ assert ctx.org_id is None
+ assert ctx.user is None
+
+
+# ---------------------------------------------------------------------------
+# resolve_analytics_context factory tests
+# ---------------------------------------------------------------------------
+
+
+class TestResolveContext:
+ """Tests for resolve_analytics_context async factory function."""
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_with_valid_user(self):
+ """resolve_analytics_context with valid user_id returns AnalyticsContext with consented from user, org_id from user."""
+ mock_user = MagicMock()
+ mock_user.user_consents_to_analytics = True
+ mock_user.current_org_id = 'org-abc-123'
+
+ provider = MockAnalyticsUserProvider(user=mock_user)
+ with _patch_user_provider(provider):
+ ctx = await resolve_analytics_context('user-42')
+
+ assert ctx.user_id == 'user-42'
+ assert ctx.consented is True
+ assert ctx.org_id == 'org-abc-123'
+ assert ctx.user is mock_user
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_consent_none_means_false(self):
+ """resolve_analytics_context with user.user_consents_to_analytics=None returns consented=False."""
+ mock_user = MagicMock()
+ mock_user.user_consents_to_analytics = None
+ mock_user.current_org_id = 'org-1'
+
+ provider = MockAnalyticsUserProvider(user=mock_user)
+ with _patch_user_provider(provider):
+ ctx = await resolve_analytics_context('user-42')
+
+ assert ctx.consented is False
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_org_id_none(self):
+ """resolve_analytics_context with user.current_org_id=None returns org_id=None."""
+ mock_user = MagicMock()
+ mock_user.user_consents_to_analytics = True
+ mock_user.current_org_id = None
+
+ provider = MockAnalyticsUserProvider(user=mock_user)
+ with _patch_user_provider(provider):
+ ctx = await resolve_analytics_context('user-42')
+
+ assert ctx.org_id is None
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_user_not_found(self):
+ """resolve_analytics_context when provider returns None returns safe default."""
+ provider = MockAnalyticsUserProvider(user=None)
+ with _patch_user_provider(provider):
+ ctx = await resolve_analytics_context('nonexistent-user')
+
+ assert ctx.user_id == 'nonexistent-user'
+ assert ctx.consented is False
+ assert ctx.org_id is None
+ assert ctx.user is None
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_provider_raises_exception(self):
+ """resolve_analytics_context when provider raises Exception returns safe default (no exception leaks)."""
+ provider = MockAnalyticsUserProvider(
+ raise_exception=RuntimeError('DB connection failed')
+ )
+ with _patch_user_provider(provider):
+ ctx = await resolve_analytics_context('user-42')
+
+ assert ctx.user_id == 'user-42'
+ assert ctx.consented is False
+ assert ctx.org_id is None
+ assert ctx.user is None
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_logs_warning_on_failure(self):
+ """resolve_analytics_context logs a warning when user lookup fails."""
+ provider = MockAnalyticsUserProvider(raise_exception=RuntimeError('DB error'))
+ with (
+ _patch_user_provider(provider),
+ patch('openhands.analytics.analytics_context.logger') as mock_logger,
+ ):
+ await resolve_analytics_context('user-42')
+
+ mock_logger.warning.assert_called_once()
+ call_args = mock_logger.warning.call_args
+ assert 'user-42' in str(call_args)
+
+ @pytest.mark.asyncio
+ async def test_resolve_analytics_context_with_default_provider(self):
+ """resolve_analytics_context with DefaultAnalyticsUserProvider returns safe defaults."""
+ provider = DefaultAnalyticsUserProvider()
+ with _patch_user_provider(provider):
+ ctx = await resolve_analytics_context('user-42')
+
+ assert ctx.user_id == 'user-42'
+ assert ctx.consented is False
+ assert ctx.org_id is None
+ assert ctx.user is None
diff --git a/tests/unit/test_analytics_service.py b/tests/unit/test_analytics_service.py
new file mode 100644
index 0000000000..b0c82e24a9
--- /dev/null
+++ b/tests/unit/test_analytics_service.py
@@ -0,0 +1,874 @@
+"""Tests for the AnalyticsService and related utilities."""
+
+import uuid
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from openhands.analytics import (
+ AnalyticsService,
+ get_analytics_service,
+ init_analytics_service,
+)
+from openhands.analytics.analytics_constants import (
+ CONVERSATION_CREATED,
+ CONVERSATION_DELETED,
+ CONVERSATION_ERRORED,
+ CONVERSATION_FINISHED,
+ CREDIT_LIMIT_REACHED,
+ CREDIT_PURCHASED,
+ GIT_PROVIDER_CONNECTED,
+ ONBOARDING_COMPLETED,
+ SETTINGS_SAVED,
+ TEAM_MEMBERS_INVITED,
+ TRAJECTORY_DOWNLOADED,
+ USER_LOGGED_IN,
+ USER_SIGNED_UP,
+)
+from openhands.analytics.analytics_context import AnalyticsContext
+from openhands.analytics.analytics_service import AnalyticsService as DirectService
+from openhands.analytics.oss_install_id import get_or_create_install_id
+from openhands.server.types import AppMode
+
+
+def make_ctx(
+ user_id: str = 'user-1',
+ consented: bool = True,
+ org_id: str | None = None,
+) -> AnalyticsContext:
+ """Helper to create an AnalyticsContext for tests."""
+ return AnalyticsContext(
+ user_id=user_id,
+ consented=consented,
+ org_id=org_id,
+ user=None,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
[email protected](autouse=True)
+def reset_singleton():
+ """Reset the module-level singleton before each test."""
+ import openhands.analytics as analytics_module
+
+ original = analytics_module._analytics_service
+ analytics_module._analytics_service = None
+ yield
+ analytics_module._analytics_service = original
+
+
+def mock_posthog():
+ """Patch posthog.Posthog and return the mock instance."""
+ with patch(
+ 'openhands.analytics.analytics_service.Posthog', autospec=True
+ ) as MockClass:
+ mock_client = MagicMock()
+ MockClass.return_value = mock_client
+ yield MockClass, mock_client
+
+
+def oss_service(mock_posthog):
+ """AnalyticsService in OSS mode."""
+ MockClass, mock_client = mock_posthog
+ service = DirectService(
+ api_key='test-key',
+ host='https://posthog.example.com',
+ app_mode=AppMode.OPENHANDS,
+ is_feature_env=False,
+ )
+ return service, mock_client
+
+
+def saas_service(mock_posthog):
+ """AnalyticsService in SaaS mode."""
+ MockClass, mock_client = mock_posthog
+ service = DirectService(
+ api_key='test-key',
+ host='https://posthog.example.com',
+ app_mode=AppMode.SAAS,
+ is_feature_env=False,
+ )
+ return service, mock_client
+
+
+def feature_env_service(mock_posthog):
+ """AnalyticsService in feature-env mode (OSS)."""
+ MockClass, mock_client = mock_posthog
+ service = DirectService(
+ api_key='test-key',
+ host='https://posthog.example.com',
+ app_mode=AppMode.OPENHANDS,
+ is_feature_env=True,
+ )
+ return service, mock_client
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton tests
+# ---------------------------------------------------------------------------
+
+
+class TestSingleton:
+ def test_get_analytics_service_returns_none_before_init(self):
+ """get_analytics_service() returns None before init_analytics_service() is called."""
+ assert get_analytics_service() is None
+
+ def test_init_analytics_service_returns_instance(self, mock_posthog):
+ """init_analytics_service() returns an AnalyticsService instance."""
+ service = init_analytics_service(
+ api_key='key',
+ host='https://posthog.example.com',
+ app_mode=AppMode.SAAS,
+ is_feature_env=False,
+ )
+ assert isinstance(service, AnalyticsService)
+
+ def test_get_analytics_service_returns_instance_after_init(self, mock_posthog):
+ """get_analytics_service() returns the initialized instance."""
+ init_analytics_service(
+ api_key='key',
+ host='https://posthog.example.com',
+ app_mode=AppMode.SAAS,
+ is_feature_env=False,
+ )
+ result = get_analytics_service()
+ assert isinstance(result, AnalyticsService)
+
+ def test_init_analytics_service_stores_singleton(self, mock_posthog):
+ """Calling init twice returns the same object from get_analytics_service."""
+ svc1 = init_analytics_service(
+ api_key='key',
+ host='https://posthog.example.com',
+ app_mode=AppMode.SAAS,
+ is_feature_env=False,
+ )
+ svc2 = get_analytics_service()
+ assert svc1 is svc2
+
+
+# ---------------------------------------------------------------------------
+# Consent gate tests
+# ---------------------------------------------------------------------------
+
+
+class TestConsentGate:
+ def test_capture_with_consented_false_makes_zero_posthog_calls(self, oss_service):
+ """capture() with consented=False produces zero PostHog client calls."""
+ service, mock_client = oss_service
+ ctx = make_ctx(user_id='user123', consented=False)
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ )
+ mock_client.capture.assert_not_called()
+
+ def test_capture_with_consented_true_makes_posthog_call(self, oss_service):
+ """capture() with consented=True calls the PostHog client."""
+ service, mock_client = oss_service
+ ctx = make_ctx(user_id='user123', consented=True)
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ )
+ mock_client.capture.assert_called_once()
+
+ def test_set_person_properties_with_consented_false_is_noop(self, saas_service):
+ """set_person_properties() with consented=False does not call SDK."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123', consented=False)
+ service.set_person_properties(
+ ctx=ctx,
+ properties={'name': 'Alice'},
+ )
+ mock_client.set.assert_not_called()
+
+ def test_group_identify_with_consented_false_is_noop(self, saas_service):
+ """group_identify() with consented=False does not call SDK."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123', consented=False)
+ service.group_identify(
+ ctx=ctx,
+ group_type='org',
+ group_key='org123',
+ properties={'name': 'Acme'},
+ )
+ mock_client.group_identify.assert_not_called()
+
+
+# ---------------------------------------------------------------------------
+# OSS vs SaaS mode tests
+# ---------------------------------------------------------------------------
+
+
+class TestOssSaasMode:
+ def test_capture_oss_mode_includes_process_person_profile_false(self, oss_service):
+ """In OSS mode, captured events include '$process_person_profile': False."""
+ service, mock_client = oss_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ )
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert props.get('$process_person_profile') is False
+
+ def test_capture_saas_mode_does_not_include_process_person_profile(
+ self, saas_service
+ ):
+ """In SaaS mode, captured events do NOT include '$process_person_profile'."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ )
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert '$process_person_profile' not in props
+
+ def test_set_person_properties_oss_mode_is_noop(self, oss_service):
+ """set_person_properties() in OSS mode does not call SDK."""
+ service, mock_client = oss_service
+ ctx = make_ctx(user_id='user123')
+ service.set_person_properties(
+ ctx=ctx,
+ properties={'name': 'Alice'},
+ )
+ mock_client.set.assert_not_called()
+
+ def test_set_person_properties_saas_mode_calls_sdk(self, saas_service):
+ """set_person_properties() in SaaS mode calls SDK when consented."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.set_person_properties(
+ ctx=ctx,
+ properties={'name': 'Alice'},
+ )
+ mock_client.set.assert_called_once()
+
+ def test_group_identify_oss_mode_is_noop(self, oss_service):
+ """group_identify() in OSS mode does not call SDK."""
+ service, mock_client = oss_service
+ ctx = make_ctx(user_id='user123')
+ service.group_identify(
+ ctx=ctx,
+ group_type='org',
+ group_key='org123',
+ properties={'name': 'Acme'},
+ )
+ mock_client.group_identify.assert_not_called()
+
+ def test_group_identify_saas_mode_calls_sdk(self, saas_service):
+ """group_identify() in SaaS mode calls SDK when consented."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.group_identify(
+ ctx=ctx,
+ group_type='org',
+ group_key='org123',
+ properties={'name': 'Acme'},
+ )
+ mock_client.group_identify.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# Common properties tests
+# ---------------------------------------------------------------------------
+
+
+class TestCommonProperties:
+ def test_capture_always_includes_app_mode(self, saas_service):
+ """Every captured event includes app_mode in properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(ctx=ctx, event='test event')
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert 'app_mode' in props
+ assert props['app_mode'] == AppMode.SAAS.value
+
+ def test_capture_always_includes_is_feature_env(self, saas_service):
+ """Every captured event includes is_feature_env in properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(ctx=ctx, event='test event')
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert 'is_feature_env' in props
+ assert props['is_feature_env'] is False
+
+ def test_capture_includes_org_id_when_provided(self, saas_service):
+ """capture() includes org_id when provided."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123', org_id='org-abc')
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ )
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert props.get('org_id') == 'org-abc'
+
+ def test_capture_omits_org_id_when_not_provided(self, saas_service):
+ """capture() omits org_id when not provided."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(ctx=ctx, event='test event')
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert 'org_id' not in props
+
+ def test_capture_includes_session_id_when_provided(self, saas_service):
+ """capture() includes $session_id when session_id provided."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ session_id='sess-xyz',
+ )
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert props.get('$session_id') == 'sess-xyz'
+
+ def test_capture_omits_session_id_when_not_provided(self, saas_service):
+ """capture() omits $session_id when not provided."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(ctx=ctx, event='test event')
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert '$session_id' not in props
+
+ def test_capture_merges_caller_properties(self, saas_service):
+ """capture() merges caller-provided properties with common ones."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ properties={'custom_prop': 'custom_val'},
+ )
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs.get('properties', {})
+ assert props.get('custom_prop') == 'custom_val'
+ assert 'app_mode' in props # common props still present
+
+
+# ---------------------------------------------------------------------------
+# distinct_id / feature-env tests
+# ---------------------------------------------------------------------------
+
+
+class TestDistinctId:
+ def test_distinct_id_normal_mode_returns_raw_user_id(self, saas_service):
+ """_distinct_id() returns raw user_id when is_feature_env=False."""
+ service, _ = saas_service
+ assert service._distinct_id('user123') == 'user123'
+
+ def test_distinct_id_feature_env_returns_prefixed_user_id(
+ self, feature_env_service
+ ):
+ """_distinct_id() returns 'FEATURE_{user_id}' when is_feature_env=True."""
+ service, _ = feature_env_service
+ assert service._distinct_id('user123') == 'FEATURE_user123'
+
+ def test_capture_uses_distinct_id_helper(self, feature_env_service):
+ """capture() passes the prefixed distinct_id to the PostHog client."""
+ service, mock_client = feature_env_service
+ ctx = make_ctx(user_id='user123')
+ service.capture(
+ ctx=ctx,
+ event='test event',
+ )
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs.get('distinct_id') == 'FEATURE_user123'
+
+
+# ---------------------------------------------------------------------------
+# Shutdown tests
+# ---------------------------------------------------------------------------
+
+
+class TestShutdown:
+ def test_shutdown_calls_client_shutdown(self, saas_service):
+ """shutdown() calls client.shutdown() without raising."""
+ service, mock_client = saas_service
+ service.shutdown()
+ mock_client.shutdown.assert_called_once()
+
+ def test_shutdown_logs_errors_without_raising(self, saas_service):
+ """shutdown() catches SDK errors and does not propagate them."""
+ service, mock_client = saas_service
+ mock_client.shutdown.side_effect = RuntimeError('SDK error')
+ # Should not raise
+ service.shutdown()
+
+
+# ---------------------------------------------------------------------------
+# SDK error handling tests
+# ---------------------------------------------------------------------------
+
+
+class TestErrorHandling:
+ def test_capture_logs_sdk_errors_without_raising(self, saas_service):
+ """capture() catches SDK errors and does not raise to caller."""
+ service, mock_client = saas_service
+ mock_client.capture.side_effect = RuntimeError('Network error')
+ ctx = make_ctx(user_id='user123')
+ # Should not raise
+ service.capture(ctx=ctx, event='test event')
+
+
+# ---------------------------------------------------------------------------
+# Event constants tests
+# ---------------------------------------------------------------------------
+
+
+class TestEventConstants:
+ def test_event_constants_are_lowercase_strings_with_spaces(self):
+ """Event constants follow PostHog naming convention (lowercase, spaces)."""
+ for const in [
+ USER_LOGGED_IN,
+ USER_SIGNED_UP,
+ CONVERSATION_CREATED,
+ CONVERSATION_FINISHED,
+ CONVERSATION_ERRORED,
+ CREDIT_PURCHASED,
+ CREDIT_LIMIT_REACHED,
+ GIT_PROVIDER_CONNECTED,
+ ONBOARDING_COMPLETED,
+ ]:
+ assert isinstance(const, str)
+ assert const == const.lower(), f'{const!r} is not lowercase'
+ assert ' ' in const, f'{const!r} does not contain spaces'
+
+ def test_user_logged_in_constant_value(self):
+ """USER_LOGGED_IN has the correct value."""
+ assert USER_LOGGED_IN == 'user logged in'
+
+ def test_user_signed_up_constant_value(self):
+ """USER_SIGNED_UP has the correct value."""
+ assert USER_SIGNED_UP == 'user signed up'
+
+
+# ---------------------------------------------------------------------------
+# OSS install ID tests
+# ---------------------------------------------------------------------------
+
+
+class TestOssInstallId:
+ def test_get_or_create_install_id_creates_file_on_first_call(self, tmp_path):
+ """get_or_create_install_id() creates the analytics_id.txt file on first call."""
+ result = get_or_create_install_id(tmp_path)
+ assert (tmp_path / 'analytics_id.txt').exists()
+ assert result is not None
+
+ def test_get_or_create_install_id_returns_valid_uuid(self, tmp_path):
+ """get_or_create_install_id() returns a valid UUID string."""
+ result = get_or_create_install_id(tmp_path)
+ parsed = uuid.UUID(result) # raises if invalid
+ assert str(parsed) == result
+
+ def test_get_or_create_install_id_returns_same_uuid_on_second_call(self, tmp_path):
+ """get_or_create_install_id() returns the same UUID on subsequent calls."""
+ first = get_or_create_install_id(tmp_path)
+ second = get_or_create_install_id(tmp_path)
+ assert first == second
+
+ def test_get_or_create_install_id_returns_uuid_on_file_write_failure(
+ self, tmp_path
+ ):
+ """get_or_create_install_id() returns an ephemeral UUID when file write fails."""
+ read_only_dir = tmp_path / 'readonly'
+ read_only_dir.mkdir()
+ read_only_dir.chmod(0o444) # read-only
+
+ try:
+ result = get_or_create_install_id(read_only_dir)
+ # Should still return a valid UUID, not crash
+ parsed = uuid.UUID(result)
+ assert str(parsed) == result
+ finally:
+ read_only_dir.chmod(0o755) # restore for cleanup
+
+
+# ---------------------------------------------------------------------------
+# identify_user tests
+# ---------------------------------------------------------------------------
+
+
+class TestIdentifyUser:
+ """Tests for the identify_user method on AnalyticsService."""
+
+ def test_identify_user_consent_false_is_noop(self, saas_service):
+ """identify_user with consented=False is a complete no-op."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1', consented=False, org_id='org-1')
+ service.identify_user(
+ ctx=ctx,
+ )
+ mock_client.set.assert_not_called()
+ mock_client.group_identify.assert_not_called()
+
+ def test_identify_user_oss_mode_is_noop(self, oss_service):
+ """identify_user in OSS mode is a complete no-op."""
+ service, mock_client = oss_service
+ ctx = make_ctx(user_id='user-1', org_id='org-1')
+ service.identify_user(
+ ctx=ctx,
+ )
+ mock_client.set.assert_not_called()
+ mock_client.group_identify.assert_not_called()
+
+ def test_identify_user_saas_sets_person_properties(self, saas_service):
+ """identify_user in SaaS mode with consent calls set_person_properties with expected fields."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1', org_id='org-42')
+ service.identify_user(
+ ctx=ctx,
+ org_name='Acme Corp',
+ idp='github',
+ )
+ mock_client.set.assert_called_once()
+ _, kwargs = mock_client.set.call_args
+ props = kwargs.get('properties', {})
+ assert props['email'] == '[email protected]'
+ assert props['org_id'] == 'org-42'
+ assert props['org_name'] == 'Acme Corp'
+ assert props['idp'] == 'github'
+ assert 'last_login_at' in props
+ assert 'plan_tier' in props
+
+ def test_identify_user_saas_with_orgs_calls_group_identify(self, saas_service):
+ """identify_user in SaaS mode with orgs calls group_identify for each org."""
+ service, mock_client = saas_service
+ orgs = [
+ {'id': 'org-1', 'name': 'Org One', 'member_count': 5},
+ {'id': 'org-2', 'name': 'Org Two', 'member_count': 10},
+ ]
+ ctx = make_ctx(user_id='user-1')
+ service.identify_user(
+ ctx=ctx,
+ orgs=orgs,
+ )
+ assert mock_client.group_identify.call_count == 2
+
+ def test_identify_user_with_user_none_skips_all(self, saas_service):
+ """identify_user with no email/org/orgs still calls set_person_properties (with None values)."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.identify_user(
+ ctx=ctx,
+ )
+ # set_person_properties is still called (with None fields)
+ mock_client.set.assert_called_once()
+ # but group_identify is NOT called since no orgs provided
+ mock_client.group_identify.assert_not_called()
+
+ def test_identify_user_catches_exception(self, saas_service):
+ """identify_user catches any exception internally and does not raise."""
+ service, mock_client = saas_service
+ mock_client.set.side_effect = RuntimeError('PostHog SDK error')
+ ctx = make_ctx(user_id='user-1')
+ # Should not raise
+ service.identify_user(
+ ctx=ctx,
+ )
+
+ def test_identify_user_org_with_no_name(self, saas_service):
+ """identify_user with org that has no name handles it gracefully."""
+ service, mock_client = saas_service
+ orgs = [
+ {'id': 'org-1', 'name': None, 'member_count': 3},
+ ]
+ ctx = make_ctx(user_id='user-1')
+ service.identify_user(
+ ctx=ctx,
+ orgs=orgs,
+ )
+ assert mock_client.group_identify.call_count == 1
+ _, kwargs = mock_client.group_identify.call_args
+ props = kwargs.get('properties', {})
+ assert props.get('org_name') is None
+
+
+# ---------------------------------------------------------------------------
+# Typed event methods tests
+# ---------------------------------------------------------------------------
+
+
+class TestTypedEventMethods:
+ """Tests for the 15 typed event methods on AnalyticsService."""
+
+ def test_track_user_signed_up(self, saas_service):
+ """track_user_signed_up calls capture with USER_SIGNED_UP and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_user_signed_up(
+ ctx=ctx,
+ email_domain='example.com',
+ invitation_source='invite_link',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == USER_SIGNED_UP
+ props = kwargs['properties']
+ assert props['email_domain'] == 'example.com'
+ assert props['invitation_source'] == 'invite_link'
+
+ def test_track_user_logged_in(self, saas_service):
+ """track_user_logged_in calls capture with USER_LOGGED_IN and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_user_logged_in(
+ ctx=ctx,
+ idp='google',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == USER_LOGGED_IN
+ props = kwargs['properties']
+ assert props['idp'] == 'google'
+
+ def test_track_conversation_created(self, saas_service):
+ """track_conversation_created calls capture with CONVERSATION_CREATED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_conversation_created(
+ ctx=ctx,
+ conversation_id='conv-abc',
+ trigger='ui',
+ llm_model='gpt-4',
+ agent_type='CodeActAgent',
+ has_repository=True,
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == CONVERSATION_CREATED
+ props = kwargs['properties']
+ assert props['conversation_id'] == 'conv-abc'
+ assert props['trigger'] == 'ui'
+ assert props['llm_model'] == 'gpt-4'
+ assert props['agent_type'] == 'CodeActAgent'
+ assert props['has_repository'] is True
+
+ def test_track_conversation_finished(self, saas_service):
+ """track_conversation_finished calls capture with CONVERSATION_FINISHED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_conversation_finished(
+ ctx=ctx,
+ conversation_id='conv-abc',
+ terminal_state='completed',
+ turn_count=5,
+ accumulated_cost_usd=0.15,
+ prompt_tokens=1000,
+ completion_tokens=500,
+ llm_model='gpt-4',
+ trigger='ui',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == CONVERSATION_FINISHED
+ props = kwargs['properties']
+ assert props['conversation_id'] == 'conv-abc'
+ assert props['terminal_state'] == 'completed'
+ assert props['turn_count'] == 5
+ assert props['accumulated_cost_usd'] == 0.15
+ assert props['prompt_tokens'] == 1000
+ assert props['completion_tokens'] == 500
+ assert props['llm_model'] == 'gpt-4'
+ assert props['trigger'] == 'ui'
+
+ def test_track_conversation_errored(self, saas_service):
+ """track_conversation_errored calls capture with CONVERSATION_ERRORED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_conversation_errored(
+ ctx=ctx,
+ conversation_id='conv-abc',
+ error_type='LLMError',
+ error_message='Rate limit exceeded',
+ llm_model='gpt-4',
+ turn_count=3,
+ terminal_state='error',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == CONVERSATION_ERRORED
+ props = kwargs['properties']
+ assert props['conversation_id'] == 'conv-abc'
+ assert props['error_type'] == 'LLMError'
+ assert props['error_message'] == 'Rate limit exceeded'
+ assert props['llm_model'] == 'gpt-4'
+ assert props['turn_count'] == 3
+ assert props['terminal_state'] == 'error'
+
+ def test_track_credit_purchased(self, saas_service):
+ """track_credit_purchased calls capture with CREDIT_PURCHASED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_credit_purchased(
+ ctx=ctx,
+ amount_usd=10.0,
+ credit_balance_before=5.0,
+ credit_balance_after=15.0,
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == CREDIT_PURCHASED
+ props = kwargs['properties']
+ assert props['amount_usd'] == 10.0
+ assert props['credit_balance_before'] == 5.0
+ assert props['credit_balance_after'] == 15.0
+
+ def test_track_credit_limit_reached(self, saas_service):
+ """track_credit_limit_reached calls capture with CREDIT_LIMIT_REACHED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_credit_limit_reached(
+ ctx=ctx,
+ conversation_id='conv-abc',
+ credit_balance=0.0,
+ llm_model='gpt-4',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == CREDIT_LIMIT_REACHED
+ props = kwargs['properties']
+ assert props['conversation_id'] == 'conv-abc'
+ assert props['credit_balance'] == 0.0
+ assert props['llm_model'] == 'gpt-4'
+
+ def test_track_git_provider_connected(self, saas_service):
+ """track_git_provider_connected calls capture with GIT_PROVIDER_CONNECTED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_git_provider_connected(
+ ctx=ctx,
+ provider_type='github',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == GIT_PROVIDER_CONNECTED
+ props = kwargs['properties']
+ assert props['provider_type'] == 'github'
+
+ def test_track_onboarding_completed(self, saas_service):
+ """track_onboarding_completed calls capture with ONBOARDING_COMPLETED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_onboarding_completed(
+ ctx=ctx,
+ selections={
+ 'role': 'developer',
+ 'org_size': '11-50',
+ 'use_case': 'code_review',
+ },
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == ONBOARDING_COMPLETED
+ props = kwargs['properties']
+ assert props['role'] == 'developer'
+ assert props['org_size'] == '11-50'
+ assert props['use_case'] == 'code_review'
+
+ def test_track_conversation_deleted(self, saas_service):
+ """track_conversation_deleted calls capture with CONVERSATION_DELETED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_conversation_deleted(
+ ctx=ctx,
+ conversation_id='conv-xyz',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == CONVERSATION_DELETED
+ props = kwargs['properties']
+ assert props['conversation_id'] == 'conv-xyz'
+
+ def test_track_settings_saved(self, saas_service):
+ """track_settings_saved calls capture with SETTINGS_SAVED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_settings_saved(
+ ctx=ctx,
+ settings_changed=['llm_model', 'agent_type'],
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == SETTINGS_SAVED
+ props = kwargs['properties']
+ assert props['settings_changed'] == ['llm_model', 'agent_type']
+
+ def test_track_trajectory_downloaded(self, saas_service):
+ """track_trajectory_downloaded calls capture with TRAJECTORY_DOWNLOADED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1')
+ service.track_trajectory_downloaded(
+ ctx=ctx,
+ conversation_id='conv-download-123',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == TRAJECTORY_DOWNLOADED
+ props = kwargs['properties']
+ assert props['conversation_id'] == 'conv-download-123'
+
+ def test_track_team_members_invited(self, saas_service):
+ """track_team_members_invited calls capture with TEAM_MEMBERS_INVITED and correct properties."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1', org_id='org-123')
+ service.track_team_members_invited(
+ ctx=ctx,
+ invited_count=5,
+ successful_count=4,
+ failed_count=1,
+ role='member',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ assert kwargs['event'] == TEAM_MEMBERS_INVITED
+ props = kwargs['properties']
+ assert props['invited_count'] == 5
+ assert props['successful_count'] == 4
+ assert props['failed_count'] == 1
+ assert props['role'] == 'member'
+
+ def test_typed_method_consent_false_is_noop(self, saas_service):
+ """A typed method with consented=False results in no capture call."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1', consented=False)
+ service.track_user_logged_in(
+ ctx=ctx,
+ idp='github',
+ )
+ mock_client.capture.assert_not_called()
+
+ def test_typed_method_passes_org_id(self, saas_service):
+ """A typed method passes org_id through to self.capture."""
+ service, mock_client = saas_service
+ ctx = make_ctx(user_id='user-1', org_id='org-99')
+ service.track_user_logged_in(
+ ctx=ctx,
+ idp='github',
+ )
+ mock_client.capture.assert_called_once()
+ _, kwargs = mock_client.capture.call_args
+ props = kwargs['properties']
+ assert props.get('org_id') == 'org-99'
diff --git a/tests/unit/test_analytics_user_base.py b/tests/unit/test_analytics_user_base.py
new file mode 100644
index 0000000000..803861ef6b
--- /dev/null
+++ b/tests/unit/test_analytics_user_base.py
@@ -0,0 +1,149 @@
+"""Tests for UserBase Protocol structural typing compatibility."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+from unittest.mock import MagicMock
+from uuid import UUID, uuid4
+
+from openhands.analytics.user_base import UserBase
+
+
+class TestUserBaseProtocol:
+ """Tests verifying UserBase Protocol works with various implementations.
+
+ UserBase uses Any types for SQLAlchemy compatibility, but these tests
+ verify the Protocol's structural typing works correctly at runtime.
+ """
+
+ def test_protocol_with_uuid_types(self):
+ """UserBase Protocol accepts a class using UUID for id and current_org_id."""
+
+ @dataclass
+ class UserWithUUID:
+ id: UUID
+ user_consents_to_analytics: bool | None
+ current_org_id: UUID | None
+ accepted_tos: datetime | None
+
+ user = UserWithUUID(
+ id=uuid4(),
+ user_consents_to_analytics=True,
+ current_org_id=uuid4(),
+ accepted_tos=datetime.now(),
+ )
+
+ assert isinstance(user, UserBase)
+ assert user.user_consents_to_analytics is True
+
+ def test_protocol_with_str_types(self):
+ """UserBase Protocol accepts a class using str for id and current_org_id."""
+
+ @dataclass
+ class UserWithStr:
+ id: str
+ user_consents_to_analytics: bool | None
+ current_org_id: str | None
+ accepted_tos: datetime | None
+
+ user = UserWithStr(
+ id='user-123',
+ user_consents_to_analytics=False,
+ current_org_id='org-456',
+ accepted_tos=None,
+ )
+
+ assert isinstance(user, UserBase)
+ assert user.user_consents_to_analytics is False
+ assert user.accepted_tos is None
+
+ def test_protocol_with_none_values(self):
+ """UserBase Protocol accepts None for nullable fields."""
+
+ @dataclass
+ class UserWithNones:
+ id: str
+ user_consents_to_analytics: bool | None
+ current_org_id: str | None
+ accepted_tos: datetime | None
+
+ user = UserWithNones(
+ id='user-789',
+ user_consents_to_analytics=None,
+ current_org_id=None,
+ accepted_tos=None,
+ )
+
+ assert isinstance(user, UserBase)
+ assert user.user_consents_to_analytics is None
+ assert user.current_org_id is None
+
+ def test_protocol_with_extra_attributes(self):
+ """UserBase Protocol accepts classes with additional attributes."""
+
+ @dataclass
+ class UserWithExtras:
+ id: UUID
+ user_consents_to_analytics: bool | None
+ current_org_id: UUID | None
+ accepted_tos: datetime | None
+ email: str # Extra attribute
+ role: str # Extra attribute
+
+ user = UserWithExtras(
+ id=uuid4(),
+ user_consents_to_analytics=True,
+ current_org_id=uuid4(),
+ accepted_tos=datetime.now(),
+ role='admin',
+ )
+
+ assert isinstance(user, UserBase)
+
+ def test_protocol_rejects_missing_attributes(self):
+ """UserBase Protocol rejects classes missing required attributes."""
+
+ @dataclass
+ class IncompleteUser:
+ id: str
+ user_consents_to_analytics: bool | None
+ # Missing: current_org_id, accepted_tos
+
+ user = IncompleteUser(
+ id='user-incomplete',
+ user_consents_to_analytics=True,
+ )
+
+ assert not isinstance(user, UserBase)
+
+ def test_protocol_with_mock_object(self):
+ """UserBase Protocol works with mock objects (as used in tests)."""
+ mock_user = MagicMock()
+ mock_user.id = uuid4()
+ mock_user.user_consents_to_analytics = True
+ mock_user.current_org_id = 'org-mock'
+ mock_user.accepted_tos = datetime.now()
+
+ # MagicMock has all attributes, so it satisfies the protocol
+ assert isinstance(mock_user, UserBase)
+ assert mock_user.user_consents_to_analytics is True
+
+ def test_protocol_with_any_typed_class(self):
+ """UserBase Protocol works with Any-typed attributes (SQLAlchemy compatibility)."""
+
+ @dataclass
+ class UserWithAny:
+ id: Any
+ user_consents_to_analytics: Any
+ current_org_id: Any
+ accepted_tos: Any
+
+ user = UserWithAny(
+ id=uuid4(),
+ user_consents_to_analytics=True,
+ current_org_id='org-any',
+ accepted_tos=datetime.now(),
+ )
+
+ assert isinstance(user, UserBase)