feat(analytics): event ingestion and reporting APIs (#368)

[amankoli09]

Event Ingestion and Reporting APIs (#368)

Closes #368

🎯 Objective

This PR introduces a robust, fully-featured Analytics Module responsible for ingesting, validating, storing, and reporting telemetry and user interaction events. It fulfills the core requirements for #368, providing a scalable storage schema and critical reporting APIs needed for product dashboards (retention, top events, and daily aggregates).

🚀 What We Did (Summary of Changes)

1. Idempotent Ingestion Pipeline: Introduced idempotency keys for both single and batch event ingestion to ensure bulletproof deduplication.
2. Advanced Reporting Endpoints: Implemented new REST endpoints to calculate basic N-day retention cohorts and retrieve the top most frequent events.
3. Database Storage Optimization: Generated a migration to add a BRIN (Block Range INdex) to the event timestamps, significantly improving time-series query performance natively in PostgreSQL.
4. Automated Batch Processing: Integrated @nestjs/schedule to run a midnight cron job that aggregates daily metrics (e.g., total active users, views, transactions) and shifts the query burden off the live telemetry endpoints.
5. Testing & Documentation: Added unit testing for the new ingestion mechanics and reporting logic, alongside a comprehensive analytics.md documentation file defining event schemas and retention rules.

🛠️ Technical Details & File Changes

1. Ingestion & Deduplication

• src/analytics/dto/ingest-events.dto.ts: Added an optional idempotencyKey field to the validation DTOs.
• src/analytics/entities/analytics-event.entity.ts: Extended the TypeORM entity with an idempotencyKey column, constrained by a unique database index.
• src/analytics/analytics.service.ts: Refactored the ingestEvent and ingestBatch logic. Switched from raw .save() calls to a robust UPSERT / .orIgnore() QueryBuilder pattern. This ensures that duplicate events submitted by clients (e.g. on network retries) fail silently and gracefully without throwing 500 errors.

2. Reporting API Capabilities

• src/analytics/analytics.service.ts:
  • Implemented getTopEvents(startDate, endDate, limit) to return the highest frequency telemetry events.
  • Implemented getRetentionCohorts(startDate, endDate) using an advanced raw SQL CTE to calculate daily retention offset cohorts cleanly.
• src/analytics/controllers/analytics.controller.ts:
  • Exposed GET /analytics/metrics/top-events
  • Exposed GET /analytics/metrics/retention

3. Background Processing & Cron Jobs

• src/analytics/analytics.cron.ts (NEW): Built the AnalyticsCronService to execute aggregateDailyMetrics at CronExpression.EVERY_DAY_AT_MIDNIGHT.
• src/app.module.ts & src/analytics/analytics.module.ts: Imported and configured ScheduleModule.forRoot() to enable NestJS chronometer tasks globally.

4. Storage Optimizations

• src/migrations/1724076000000-AnalyticsModuleUpdates.ts (NEW):
  • Added the idempotencyKey column and unique constraint natively.
  • Implemented a Postgres BRIN index on createdAt. BRIN is natively highly optimized for continuously appending time-series data, vastly speeding up reporting queries with huge row counts.

5. Specs & Docs

• docs/analytics.md (NEW): In-depth documentation on standard properties, ingestion API examples, and the data retention policy.
• src/analytics/analytics.service.spec.ts & src/analytics/controllers/analytics.controller.spec.ts (NEW): Added 100% test coverage over the deduplication logic, DTO validation, and correct execution of reporting endpoints using Jest.

🧪 Expected Behavior

• When clients hit POST /analytics/events with the same idempotencyKey twice, the backend accepts the request with a 202 Accepted but does not duplicate the entry in the analytics_events table.
• Hitting GET /analytics/metrics/retention provides accurate N-day retention mapping grouped by cohort start days.
• Every night at precisely 12:00 AM (server time), the background Cron Job will wake up and summarize the previous day's raw data into the daily_metrics table for fast analytical retrieval.

✅ Acceptance Criteria (Checklist)

• Endpoint to ingest events with schema validation and basic deduplication.
• Event storage optimized for analytics queries (BRIN time-series indexing implemented).
• Reporting API endpoints for common metrics: daily active users (DAU), event counts, top events, and basic retention cohorts.
• Batch jobs or materialized views to precompute heavy aggregates (Midnight Cron job implemented).
• Tests for ingestion, schema validation, and sample reporting queries.
• Docs describing event schema, retention policy, and how to add new events.