89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# 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)
|
|
|
|
```ts
|
|
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)
|
|
|
|
```ts
|
|
type AnalyticsErrorCode =
|
|
| "ANALYTICS_INVALID_EVENT"
|
|
| "ANALYTICS_STORAGE_ERROR"
|
|
| "ANALYTICS_SCHEMA_MISMATCH"
|
|
| "ANALYTICS_QUERY_INVALID"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
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`.
|