OpenSpec Change: enterprise-api-plugin-analytics

Change ID: enterprise-api-plugin-analytics
Package: @suaveplan/api-plugin-analytics
Category: api/data
Target path: api/data/api-plugin-analytics
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-analytics.md

Summary

Deliver @suaveplan/api-plugin-analytics on the genesis branch from scratch at enterprise quality. Product-analytics plugin for @suaveplan/api. Genesis rebuild fixes all identified gaps: replaces the in-memory ring buffer with a pluggable StorageAdapter (in-memory for dev, SurrealDB for production), adds HTTP routes (POST /track, POST /track/batch, POST /query/aggregate, POST /query/funnel, POST /query/cohort, DELETE /analytics/purge), proper EventMap declaration via src/events.ts module augmentation (dropping as Parameters<...> cast), per-event-type schema validation via @suaveplan/schema-registry, PII masking via @suaveplan/data-masking, and batch idempotency via @suaveplan/idempotency.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB adapter
`@suaveplan/events` (`workspace:^`)	Typed event bus
`@suaveplan/schema-registry` (`workspace:^`)	Event schema versioning
`@suaveplan/data-masking` (`workspace:^`)	PII masking on ingestion
`@suaveplan/idempotency` (`workspace:^`)	Batch ingestion dedup
`@suaveplan/error` (`workspace:^`)	`AnalyticsError` hierarchy
`@suaveplan/rate-limiter` (`workspace:^`)	Ingestion rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface (preserves + extends existing)

function createAnalyticsPlugin(config?: AnalyticsConfig): PluginDescriptor

// Services (preserved)
class AnalyticsService      // track, aggregate, clear — now backed by StorageAdapter
class FunnelAnalyzer        // funnel conversion rates
class CohortAnalyzer        // cohort retention

// Types (preserved)
AnalyticsEvent, TrackEventInput, TimeGranularity, TimeSeriesPoint
AggregationQuery, AggregationResult
FunnelQuery, FunnelStep, FunnelStepResult, FunnelResult
CohortQuery, CohortRow, CohortResult, AnalyticsEventMap

// New
interface StorageAdapter { track, query, purge, getStats }
dateToPeriodKey (preserved)

Error codes (new)

type AnalyticsErrorCode =
  | "ANALYTICS_INVALID_EVENT"
  | "ANALYTICS_STORAGE_ERROR"
  | "ANALYTICS_SCHEMA_MISMATCH"
  | "ANALYTICS_QUERY_INVALID"

File layout

api/data/api-plugin-analytics/
  package.json  tsconfig.json  vitest.config.ts
  src/
    index.ts  events.ts  types.ts  errors/
    adapters/storage.port.ts  adapters/memory-storage.ts  adapters/surreal-storage.ts
    analytics/analytics.ts  cohort/cohort.ts  funnel/funnel.ts
    routes/track/  routes/query/  routes/admin/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/events, @suaveplan/schema-registry, @suaveplan/data-masking, @suaveplan/idempotency.

3.3 KiB Raw Permalink Blame History