feat(visitor-analytics): add analytics API and OpenAPI contract #621

Context

Issue #620 collects visitor telemetry. This issue exposes tenant-scoped visitor analytics through authenticated APIs for admin dashboards and external clients.

AWCMS-Mini APIs must keep the existing patterns: bearer session, tenant context, ABAC default-deny, consistent response helper, OpenAPI updates, keyset pagination for large lists, and safe error handling.

Objective

Add visitor analytics REST endpoints and OpenAPI contract for realtime presence, summary statistics, sessions, events, pages, devices, locations, security view, settings, and retention purge.

Scope

Add API routes under:

/api/v1/analytics

Suggested endpoints:

GET /api/v1/analytics/realtime
GET /api/v1/analytics/summary?range=24h|7d|30d|12m
GET /api/v1/analytics/sessions
GET /api/v1/analytics/events
GET /api/v1/analytics/pages
GET /api/v1/analytics/devices
GET /api/v1/analytics/locations
GET /api/v1/analytics/security
GET /api/v1/analytics/settings
PATCH /api/v1/analytics/settings
POST /api/v1/analytics/retention/purge

Recommended realtime response shape:

{
  "onlineHumanCount": 0,
  "onlineAdminCount": 0,
  "onlinePublicCount": 0,
  "onlineApiCount": 0,
  "onlineWindowSeconds": 300,
  "lastUpdatedAt": "2026-07-09T00:00:00.000Z"
}

Recommended summary response shape:

{
  "range": "7d",
  "humanUniqueVisitors": 0,
  "humanPageviews": 0,
  "botPageviews": 0,
  "adminUniqueUsers": 0,
  "publicUniqueVisitors": 0,
  "topPaths": [],
  "topBrowsers": [],
  "topDevices": [],
  "topCountries": []
}

Authorization requirements:

• Aggregate dashboard/realtime: visitor_analytics.dashboard.read or visitor_analytics.realtime.read as appropriate.
• Sessions list: visitor_analytics.sessions.read.
• Events list: visitor_analytics.events.read.
• Raw IP/user-agent/login detail: visitor_analytics.raw_detail.read.
• Settings read/update: visitor_analytics.settings.read / visitor_analytics.settings.update.
• Retention purge: visitor_analytics.retention.purge.

Pagination:

• sessions and events must use keyset pagination.
• Return nextCursor consistently with existing AWCMS-Mini pagination style.

Out of scope

• Admin UI.
• Middleware collector changes.
• Rollup job implementation, except reading existing rollups if already available.
• Online geolocation enrichment.
• CSV/export unless it is implemented as a separate follow-up.

Acceptance criteria

• All endpoints require bearer session and tenant context.
• All endpoints enforce ABAC default-deny.
• Access denied returns 403 ACCESS_DENIED, not empty analytics data.
• Raw detail fields are omitted unless caller has visitor_analytics.raw_detail.read.
• sessions and events support keyset pagination.
• range=24h|7d|30d|12m is validated strictly.
• Invalid filters return 400 VALIDATION_ERROR.
• PATCH /analytics/settings rejects secret-shaped keys/values using existing redaction/sensitive-data helpers where appropriate.
• POST /analytics/retention/purge requires Idempotency-Key and records an audit event.
• OpenAPI spec is updated with schemas, auth, errors, and pagination.
• bun run api:spec:check passes.
• API tests cover allow/deny, raw detail gating, validation, pagination, and purge idempotency.
• bun run check passes.

Security and privacy notes

• Aggregate endpoints must not accidentally leak raw IP, raw user-agent, login identifiers, cookies, tokens, or query-string secrets.
• Settings mutation is a high-risk admin operation and must be audited.
• Retention purge is destructive and must be idempotent + audited.
• Do not use analytics permissions as a substitute for tenant isolation or RLS.

Dependencies

Depends on #617, #618, and #620. Uses helper behavior from #619.