agentic-dev/packages/core-analytics/AGENTS.md

@repo/core-analytics

Optional core package providing a vendor-neutral product analytics interface. Scaffold via pnpm turbo gen core-package analytics.

Structure

src/
  analytics.interface.ts   # IAnalytics — track, identify, pageView, flush
  noop-analytics.ts        # NoopAnalytics (default no-op implementation)
  index.ts                 # Barrel export

Design

IAnalytics exposes four methods:

• track(event, attributes?) — record a named event with optional attributes
• identify(user) — associate subsequent events with a user
• pageView(path, attributes?) — record a page-view event
• flush() — drain any in-flight queued events (returns Promise<void>)

The interface is vendor-neutral: no third-party analytics SDK is bundled. Feature packages depend on IAnalytics only; concrete implementations (e.g. a PostHog or Segment adapter) are wired at DI bind time in bind-production.

NoopAnalytics is the default implementation — all methods are no-ops and flush() resolves immediately via Promise.resolve(). Use it in dev-seed bindings and unit tests.

See docs/architecture/agent-first-workflow-and-conformance.md for the dependency-injection conventions.