Overview

analytics provides product event capture, storage, and viewing for SAF applications — browser event logging, server-side typed analytics helpers, and development admin routes/pages. In development events land in an in-memory ring buffer; production swaps in vendor integrations (e.g. PostHog) via the same service abstraction.

Like errors, this suite spans client and server. It is separate from node-metrics (Prometheus/process metrics) and node-log (Winston operational logs).

What this suite provides

• analytics-spec — OpenAPI contracts for recording and listing product events
• analytics-service — AnalyticsService abstraction, typed event helpers, in-memory implementation for tests
• analytics-http — in-memory event buffer and dev Express router (createDevAnalyticsRouter)
• analytics-sdk — TanStack Query client for recording and listing events
• analytics-vue — client event logger and admin Events page

Integration

Client SPAs call analytics-sdk / analytics-vue to POST product events to /product-events/record. Server code uses analytics-service (typed makeTypedAnalytics) and can call recordProductEvent with source: "server" in development.

SafContext fields (auth, routing metadata) feed analytics attribution; runWithActingUser attributes anonymous operations (webhooks, jobs) to the owning user for event context.

When the repo follows base/service/http, the HTTP app mounts createDevAnalyticsRouter() alongside node-log, node-metrics, and errors dev tooling. The admin SPA lists buffered events since process start.

Vendor implementations

Production backends implement AnalyticsService in vendor packages:

• @saflib/vendors-posthog — PostHog for server-side events
• @saflib/vendors-posthog-client — PostHog browser init, feature flags, and client events

Development uses the in-memory buffer; call configureAnalytics() at startup in production.