suaveplan/openspec/changes/enterprise-api-plugin-analytics/tasks.md

Tasks: enterprise-api-plugin-analytics

Change ID: enterprise-api-plugin-analytics Package: @suaveplan/api-plugin-analytics Target path: api/data/api-plugin-analytics Prerequisite packages on Verdaccio: @suaveplan/api, @suaveplan/api-shared, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/events, @suaveplan/schema-registry, @suaveplan/data-masking, @suaveplan/idempotency, @suaveplan/rate-limiter, @suaveplan/error

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold + types + errors + events

• Create api/data/api-plugin-analytics/; package.json v0.0.0; standard tooling.
• src/types.ts — preserve all existing types; add StorageAdapter interface, AnalyticsConfig (Zod), AnalyticsErrorCode.
• src/errors/ — 4-code union + metadata + registration. Test + doc.
• src/events.ts — AnalyticsEventMap module augmentation (analytics:initialized, analytics:event:tracked); NO as Parameters<...> casts.

---

2. Storage adapters

• src/adapters/storage.port.ts — StorageAdapter interface: track(event), query(params), purge(filter), getStats().
• src/adapters/memory-storage.ts — bounded ring buffer (preserved from main). .test.ts + .md.
• src/adapters/surreal-storage.ts — SurrealDB-backed adapter. .test.ts + .md.

---

3. Core services (preserve existing, add adapter injection)

• AnalyticsService: inject StorageAdapter; track applies PII masking + schema validation before storage. Preserve aggregate, clear, dateToPeriodKey.
• FunnelAnalyzer: preserve existing implementation. .test.ts + .md.
• CohortAnalyzer: preserve existing implementation. .test.ts + .md.

---

4. Routes

• POST /analytics/track — requireAuth; single event; rate-limited.
• POST /analytics/track/batch — requireAuth; idempotency key; rate-limited.
• POST /analytics/query/aggregate — requireAuth.
• POST /analytics/query/funnel — requireAuth.
• POST /analytics/query/cohort — requireAuth.
• DELETE /analytics/purge — requireAuth + requireRole("ADMIN").
• GET /analytics/stats — requireAuth + requireRole("ADMIN").
• Route .test.ts + .md.

---

5. Plugin factory + integration tests + publish

• createAnalyticsPlugin(config?): enabledByDefault: true, dependencies: ["database"].
• Default to SurrealStorageAdapter; fall back to MemoryStorageAdapter when no DB plugin available.
• Integration: track events → aggregate → funnel → cohort → purge (real SurrealDB).
• bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-analytics — green; 100% coverage.
• bun scripts/publish.ts --package @suaveplan/api-plugin-analytics.
• Archive → openspec/archive/2026-04-24-enterprise-api-plugin-analytics/.