suaveplan/openspec/archive/2026-05-25-enterprise-analytics-browser/tasks.md

Tasks: enterprise-analytics-browser

Change ID: enterprise-analytics-browser Package: @suaveplan/analytics-browser Target path: packages/observability/monitor/analytics-browser

---

0. Pre-flight

• 0.1 git worktree list + git status per worktree.
• 0.2 Worktree HEAD fast-forwarded to b22864397b… (genesis baseline).
• 0.3 Confirmed package set in MANIFEST.md (regenerated post-merge).

1. Scaffold

• Create directory tree per design.md.
• package.json v0.1.0, "browser" field, "sideEffects": false, subpath exports.
• tsconfig.lib.json, vite.config.ts, vitest.config.ts (happy-dom, pool: forks, istanbul 100/100/100/100).

2. Error codes (src/error-codes/)

• error-codes.ts — ANALYTICS_BROWSER_CODES (8) + AnalyticsBrowserError.
• error-codes.test.ts, error-codes.md, index.ts.

3. Types (src/types/)

• analytics.types.ts — AnalyticsEvent, TrackerOptions, Transport, AnalyticsEventMap, StorageBackend, SessionInfo, SessionOptions, BatchTransportOptions, BeaconTransportOptions, ScrubRule, ScrubStrategy, ConsentPolicy, Sampler, DropReason.
• analytics.types.md.

4. Constants (src/constants/)

• DEFAULT_TRACKER_OPTIONS, DEFAULT_BATCH_OPTIONS, DEFAULT_BEACON_OPTIONS, DEFAULT_SESSION_TIMEOUT_MS.

5. ID generator (src/internal/id/)

• id.ts — generateId() using crypto.getRandomValues.
• id.test.ts, id.md, index.ts.

6. Schema (src/schema/)

• analytics-event-schema.ts — AnalyticsEventSchema + validateAnalyticsEvent.
• analytics-event-schema.test.ts, analytics-event-schema.md, index.ts.

7. Consent (src/consent/)

• consent.ts — ConsentPolicy, AllowAllPolicy, DoNotTrackPolicy.
• consent.test.ts, consent.md, index.ts.

8. PII (src/pii/)

• pii.ts — scrubPII with redact / hash / drop strategies (dotted paths).
• pii.test.ts, pii.md, index.ts.

9. Sampling (src/sampling/)

• sampling.ts — Sampler, HeadSampler with per-event overrides.
• sampling.test.ts, sampling.md, index.ts.

10. Storage backends (src/storage/)

• storage.ts — StorageBackend interface, MemoryStorageBackend, WebStorageBackend (maxBytes + QUEUE_FULL).
• storage.test.ts, storage.md, index.ts.

11. Session (src/session/)

• session.ts — SessionManager (id / pageviews / duration / referrer / inactivity / renew / end).
• session.test.ts, session.md, index.ts.

12. Transports (src/transport/)

• batch.ts — BatchTransport (AbortController + timeoutMs + exponential backoff + 4xx short-circuit).
• beacon.ts — BeaconTransport (sendBeacon + fetch keepalive fallback).
• batch.test.ts, batch.md, beacon.test.ts, beacon.md, index.ts.

13. Tracker (src/tracker/)

• tracker.ts — AnalyticsTracker consuming EventBus<AnalyticsEventMap>; consent → sampling → PII → enqueue + storage round-trip; auto-flush via injectable TimersLike; restore(); identify; setProperties; setSessionId; flush(); shutdown().
• tracker.test.ts, tracker.md, index.ts.

14. Telemetry (src/telemetry/)

• telemetry.ts — eventsTrackedCounter, eventsFlushedCounter, eventsDroppedCounter, batchSizeHistogram, flushLatencyHistogram + record* helpers.
• telemetry.test.ts, telemetry.md, index.ts.

15. Barrel (src/index.ts)

• Explicit named re-exports — no export * per §6a.

16. Tests setup + integration

• tests/setup/polyfills.ts — web-crypto + OTel InMemoryMetricExporter.
• tests/integration.test.ts — tracker → batch transport → in-process endpoint; "no node: imports in src/".

17. Docs

• README.md — overview, subpath table, consent / PII / sampling / storage guides, migration notes from upstream EventEmitter → EventBus.

18. Verify

• bunx turbo lint typecheck test build --filter=@suaveplan/analytics-browser — green.
• bunx turbo test:coverage --filter=@suaveplan/analytics-browser — 100/100/100/100.
• bun scripts/folder-reorg/generate-manifest.ts (refresh MANIFEST.md).
• No @ts-expect-error, any, console.log, vi.mock, vi.stubGlobal in src/.

19. Fold + archive

• Fold specs/analytics-browser/spec.md into openspec/specs/analytics-browser/spec.md.
• Move folder to openspec/archive/2026-05-25-enterprise-analytics-browser/.

20. STATUS

• Flip @suaveplan/analytics-browser – → ✅ in STATUS.md; bump migrated count 283 → 284, pending 210 → 209.