sentryagent-idp/openspec/changes/phase-6-market-expansion/specs/analytics-dashboard/spec.md

ADDED Requirements

Requirement: Analytics events are recorded for token issuances and agent activity

The system SHALL record an analytics event row in analytics_events for every OAuth2 token issuance and every agent registration, update, and deactivation, scoped to the tenant. Each row SHALL contain: tenant_id, date (UTC date), metric_type (e.g., token_issued, agent_registered), and count (aggregated daily).

Scenario: Token issuance recorded in analytics

• WHEN POST /oauth2/token succeeds for a tenant
• THEN the analytics_events table SHALL have a row incremented for metric_type=token_issued for that tenant on today's UTC date

Scenario: Agent registration recorded in analytics

• WHEN POST /api/agents succeeds
• THEN the analytics_events table SHALL have a row incremented for metric_type=agent_registered for the owning tenant on today's UTC date

Scenario: Analytics recording does not block the primary response

• WHEN the analytics write fails (e.g., DB timeout)
• THEN the primary API response SHALL still succeed and the error SHALL be logged

Requirement: Tenant can retrieve token issuance trend data

The system SHALL expose GET /api/analytics/tokens returning daily token issuance counts for the authenticated tenant over a configurable date range (default: last 30 days, max: 90 days). Response SHALL include an array of { date, count } objects sorted ascending by date.

Scenario: Successful token trend retrieval

• WHEN an authenticated tenant admin calls GET /api/analytics/tokens?days=30
• THEN the response SHALL be HTTP 200 with a JSON array of up to 30 { date, count } objects

Scenario: Date range exceeding maximum is rejected

• WHEN the request specifies days greater than 90
• THEN the response SHALL be HTTP 400 with an error indicating the maximum is 90 days

Scenario: Tenant sees only their own data

• WHEN tenant A retrieves analytics
• THEN the response SHALL contain only rows where tenant_id matches tenant A — no cross-tenant data leakage

Requirement: Tenant can retrieve agent activity heatmap data

The system SHALL expose GET /api/analytics/agents/activity returning per-agent event counts grouped by day-of-week and hour-of-day for the authenticated tenant (last 30 days). Response SHALL include an array of { agent_id, dow, hour, count } objects suitable for rendering a heatmap.

Scenario: Successful activity heatmap retrieval

• WHEN an authenticated tenant admin calls GET /api/analytics/agents/activity
• THEN the response SHALL be HTTP 200 with a JSON array of activity buckets

Scenario: Tenant with no agents returns empty array

• WHEN the tenant has no registered agents
• THEN the response SHALL be HTTP 200 with an empty array

Requirement: Tenant can retrieve a per-agent usage summary

The system SHALL expose GET /api/analytics/agents returning a list of agents with their total token issuances for the current billing period (current calendar month). Response SHALL include { agent_id, name, token_count } sorted descending by token_count.

Scenario: Successful per-agent summary

• WHEN an authenticated tenant admin calls GET /api/analytics/agents
• THEN the response SHALL be HTTP 200 with a sorted list of agent usage summaries

Scenario: Analytics endpoint requires authentication

• WHEN a request to any /api/analytics/* endpoint is made without a valid JWT
• THEN the response SHALL be HTTP 401

Requirement: Analytics data is accessible via the developer portal

The portal SHALL include an Analytics page at /analytics with:

• A line chart showing token issuance trend (last 30 days) rendered with recharts
• A heatmap chart showing agent activity by day/hour rendered with recharts
• A table listing per-agent usage for the current month

Scenario: Analytics page loads token trend chart

• WHEN a tenant admin navigates to /analytics in the portal
• THEN the page SHALL render a line chart with token issuance data from GET /api/analytics/tokens

Scenario: Analytics page is code-split (lazy loaded)

• WHEN the portal bundle is built
• THEN recharts and analytics page components SHALL be in a separate chunk (via next/dynamic) and NOT included in the main bundle