Fas 1a: analytics tracker, ingestion endpoint, admin dashboards

apps/admin/src/App.tsx

@@ -8,6 +8,7 @@ import { ModerationPage } from "./pages/Moderation.js";
 import { FlagsPage } from "./pages/Flags.js";
 import { SubscriptionsPage } from "./pages/Subscriptions.js";
 import { AuditLogsPage } from "./pages/AuditLogs.js";
+import { AnalyticsPage } from "./pages/Analytics.js";
 
 export function App() {
   const [authed, setAuthed] = useState(hasToken());
@@ -28,6 +29,7 @@ export function App() {
         <NavLink to="/flags">Feature flags</NavLink>
         <NavLink to="/subscriptions">Prenumerationer</NavLink>
         <NavLink to="/audit">Audit logs</NavLink>
+        <NavLink to="/analytics">Analytics</NavLink>
         <button
           onClick={() => {
             setToken(null);
@@ -45,6 +47,7 @@ export function App() {
           <Route path="/flags" element={<FlagsPage />} />
           <Route path="/subscriptions" element={<SubscriptionsPage />} />
           <Route path="/audit" element={<AuditLogsPage />} />
+          <Route path="/analytics" element={<AnalyticsPage />} />
           <Route path="*" element={<Navigate to="/" replace />} />
         </Routes>
       </main>

apps/admin/src/pages/Analytics.tsx

@@ -0,0 +1,210 @@
+import { useEffect, useMemo, useState } from "react";
+import { api } from "../api.js";
+
+interface FunnelDef {
+  name: string;
+  steps: string[];
+}
+interface FunnelResult {
+  name: string;
+  startDate: string;
+  endDate: string;
+  steps: Array<{ step: number; event: string; count: number }>;
+  conversionFromFirst: Array<{ step: number; event: string; rate: number }>;
+}
+interface RetentionResult {
+  cohorts: Record<
+    string,
+    { cohortSize: number; retention: Array<{ day: number; active: number; rate: number }> }
+  >;
+}
+interface EventCountsResult {
+  counts: Array<{
+    date: string;
+    event_name: string;
+    total: number;
+    unique_sessions: number;
+    unique_users: number;
+  }>;
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+function weekAgo() {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() - 7);
+  return d.toISOString().slice(0, 10);
+}
+
+export function AnalyticsPage() {
+  const [funnels, setFunnels] = useState<FunnelDef[]>([]);
+  const [funnelName, setFunnelName] = useState<string>("");
+  const [funnelStart, setFunnelStart] = useState<string>(weekAgo());
+  const [funnelEnd, setFunnelEnd] = useState<string>(today());
+  const [funnelResult, setFunnelResult] = useState<FunnelResult | null>(null);
+
+  const [retStart, setRetStart] = useState<string>(weekAgo());
+  const [retEnd, setRetEnd] = useState<string>(today());
+  const [retention, setRetention] = useState<RetentionResult | null>(null);
+
+  const [countsStart, setCountsStart] = useState<string>(weekAgo());
+  const [countsEnd, setCountsEnd] = useState<string>(today());
+  const [counts, setCounts] = useState<EventCountsResult | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    api<{ funnels: FunnelDef[] }>("/admin/v1/analytics/funnels")
+      .then((res) => {
+        setFunnels(res.funnels);
+        if (res.funnels[0]) setFunnelName(res.funnels[0].name);
+      })
+      .catch((e) => setError(String(e.message)));
+  }, []);
+
+  const loadFunnel = () => {
+    if (!funnelName) return;
+    api<FunnelResult>(
+      `/admin/v1/analytics/funnels/${encodeURIComponent(funnelName)}?startDate=${funnelStart}&endDate=${funnelEnd}`,
+    )
+      .then(setFunnelResult)
+      .catch((e) => setError(String(e.message)));
+  };
+
+  const loadRetention = () => {
+    api<RetentionResult>(
+      `/admin/v1/analytics/retention?startDate=${retStart}&endDate=${retEnd}`,
+    )
+      .then(setRetention)
+      .catch((e) => setError(String(e.message)));
+  };
+
+  const loadCounts = () => {
+    api<EventCountsResult>(
+      `/admin/v1/analytics/event-counts?startDate=${countsStart}&endDate=${countsEnd}`,
+    )
+      .then(setCounts)
+      .catch((e) => setError(String(e.message)));
+  };
+
+  const countsByEvent = useMemo(() => {
+    if (!counts) return [];
+    const grouped = new Map<string, { dates: string[]; totals: number[] }>();
+    for (const row of counts.counts) {
+      const existing = grouped.get(row.event_name);
+      if (!existing) {
+        grouped.set(row.event_name, { dates: [row.date], totals: [Number(row.total)] });
+      } else {
+        existing.dates.push(row.date);
+        existing.totals.push(Number(row.total));
+      }
+    }
+    return Array.from(grouped.entries()).map(([event, data]) => ({ event, ...data }));
+  }, [counts]);
+
+  return (
+    <div>
+      <h2>Analytics</h2>
+      {error && <div className="error-text">{error}</div>}
+
+      <div className="panel">
+        <h3>Funnels</h3>
+        <div className="form-row">
+          <select value={funnelName} onChange={(e) => setFunnelName(e.target.value)}>
+            {funnels.map((f) => (
+              <option key={f.name} value={f.name}>
+                {f.name}
+              </option>
+            ))}
+          </select>
+          <input type="date" value={funnelStart} onChange={(e) => setFunnelStart(e.target.value)} />
+          <input type="date" value={funnelEnd} onChange={(e) => setFunnelEnd(e.target.value)} />
+          <button onClick={loadFunnel}>Beräkna</button>
+        </div>
+        {funnelResult && (
+          <table>
+            <thead>
+              <tr>
+                <th>Steg</th>
+                <th>Event</th>
+                <th>Antal</th>
+                <th>Konvertering från första</th>
+              </tr>
+            </thead>
+            <tbody>
+              {funnelResult.steps.map((s, i) => (
+                <tr key={s.step}>
+                  <td>{s.step}</td>
+                  <td>{s.event}</td>
+                  <td>{s.count}</td>
+                  <td>{(funnelResult.conversionFromFirst[i]?.rate ?? 0 * 100).toFixed(1)}%</td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+
+      <div className="panel">
+        <h3>Retention</h3>
+        <div className="form-row">
+          <input type="date" value={retStart} onChange={(e) => setRetStart(e.target.value)} />
+          <input type="date" value={retEnd} onChange={(e) => setRetEnd(e.target.value)} />
+          <button onClick={loadRetention}>Ladda</button>
+        </div>
+        {retention && (
+          <table>
+            <thead>
+              <tr>
+                <th>Kohort</th>
+                <th>Storlek</th>
+                {Array.from({ length: 8 }, (_, i) => (
+                  <th key={i}>Dag {i}</th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {Object.entries(retention.cohorts).map(([date, cohort]) => (
+                <tr key={date}>
+                  <td>{date}</td>
+                  <td>{cohort.cohortSize}</td>
+                  {cohort.retention.slice(0, 8).map((r) => (
+                    <td key={r.day}>{(r.rate * 100).toFixed(0)}%</td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+
+      <div className="panel">
+        <h3>Eventvolymer</h3>
+        <div className="form-row">
+          <input type="date" value={countsStart} onChange={(e) => setCountsStart(e.target.value)} />
+          <input type="date" value={countsEnd} onChange={(e) => setCountsEnd(e.target.value)} />
+          <button onClick={loadCounts}>Ladda</button>
+        </div>
+        {countsByEvent.map(({ event, dates, totals }) => (
+          <div key={event} style={{ marginTop: "1rem" }}>
+            <strong>{event}</strong>
+            <div
+              style={{
+                display: "grid",
+                gridTemplateColumns: "repeat(auto-fill, minmax(120px, 1fr))",
+                gap: "0.5rem",
+              }}
+            >
+              {dates.map((d, i) => (
+                <div key={d} className="stat" style={{ padding: "0.5rem" }}>
+                  <div className="value">{totals[i]}</div>
+                  <div className="label">{d.slice(5)}</div>
+                </div>
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

apps/api/src/routes/admin-analytics.ts

@@ -0,0 +1,211 @@
+import type { FastifyInstance } from "fastify";
+import { sql } from "drizzle-orm";
+import { z } from "zod";
+import { FUNNELS } from "@app/shared-types";
+import { errors } from "../lib/errors.js";
+
+/**
+ * Admin analytics dashboards: funnels and retention (spec §8.2).
+ * Queries run against product_analytics_events; no materialized aggregates
+ * required for beta volumes.
+ */
+export async function adminAnalyticsRoutes(app: FastifyInstance) {
+  const admin = { preHandler: [app.requireAdmin] };
+
+  /** List available funnels. */
+  app.get("/admin/v1/analytics/funnels", admin, async () => {
+    return {
+      funnels: Object.entries(FUNNELS).map(([name, steps]) => ({ name, steps })),
+    };
+  });
+
+  /** Compute a funnel between two UTC dates (YYYY-MM-DD). */
+  app.get("/admin/v1/analytics/funnels/:name", admin, async (req) => {
+    const params = z.object({ name: z.enum(Object.keys(FUNNELS) as [string, ...string[]]) }).parse(req.params);
+    const query = z
+      .object({
+        startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+      })
+      .parse(req.query);
+
+    const steps = FUNNELS[params.name as keyof typeof FUNNELS];
+    const start = new Date(query.startDate);
+    const end = new Date(query.endDate);
+    end.setUTCDate(end.getUTCDate() + 1);
+
+    // Build a CTE chain: each step selects distinct users who completed the
+    // current event after the previous step's timestamp.
+    const ctes: string[] = [];
+    const selects: string[] = [];
+    for (let i = 0; i < steps.length; i++) {
+      const prev = i > 0 ? `step${i - 1}` : null;
+      const cteName = `step${i}`;
+      const event = steps[i]!;
+      if (i === 0) {
+        ctes.push(
+          `${cteName} AS (\n` +
+            `  SELECT DISTINCT user_id, household_id\n` +
+            `  FROM product_analytics_events\n` +
+            `  WHERE event_name = ${sqlParam(event)}\n` +
+            `    AND occurred_at >= ${sqlParam(start.toISOString())}\n` +
+            `    AND occurred_at < ${sqlParam(end.toISOString())}\n` +
+            `)`,
+        );
+      } else {
+        ctes.push(
+          `${cteName} AS (\n` +
+            `  SELECT DISTINCT ${prev!}.user_id, ${prev!}.household_id\n` +
+            `  FROM ${prev!}\n` +
+            `  INNER JOIN product_analytics_events e ON e.user_id = ${prev!}.user_id\n` +
+            `  WHERE e.event_name = ${sqlParam(event)}\n` +
+            `    AND e.occurred_at >= ${sqlParam(start.toISOString())}\n` +
+            `    AND e.occurred_at < ${sqlParam(end.toISOString())}\n` +
+            `)`,
+        );
+      }
+      selects.push(`(SELECT count(*) FROM ${cteName}) AS step${i}`);
+    }
+
+    const querySql = `WITH ${ctes.join(", ")} SELECT ${selects.join(", ")}`;
+    const result = await app.db.execute(sql.raw(querySql));
+    const row = (Array.isArray(result) ? result[0] : (result.rows[0] ?? {})) as Record<string, number>;
+
+    const stepCounts = steps.map((event, i) => ({
+      step: i + 1,
+      event,
+      count: Number(row[`step${i}`] ?? 0),
+    }));
+
+    return {
+      name: params.name,
+      startDate: query.startDate,
+      endDate: query.endDate,
+      steps: stepCounts,
+      conversionFromFirst: stepCounts.map((s, i) => ({
+        step: s.step,
+        event: s.event,
+        rate: i === 0 ? 1 : stepCounts[0]?.count ? s.count / stepCounts[0].count : 0,
+      })),
+    };
+  });
+
+  /** Retention cohorts. Cohort = users with account_created on a given UTC day.
+   *  Returns active users per cohort day for 0..30 days after creation.
+   */
+  app.get("/admin/v1/analytics/retention", admin, async (req) => {
+    const query = z
+      .object({
+        startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+      })
+      .parse(req.query);
+
+    const endDate = query.endDate ?? new Date().toISOString().slice(0, 10);
+    const cohortStart = new Date(query.startDate);
+    const cohortEnd = new Date(endDate);
+    cohortEnd.setUTCDate(cohortEnd.getUTCDate() + 1);
+
+    const raw = `
+      WITH cohort AS (
+        SELECT DISTINCT user_id,
+               (occurred_at AT TIME ZONE 'UTC')::date AS cohort_date
+        FROM product_analytics_events
+        WHERE event_name = 'account_created'
+          AND occurred_at >= ${sqlParam(cohortStart.toISOString())}
+          AND occurred_at < ${sqlParam(cohortEnd.toISOString())}
+      ),
+      activity AS (
+        SELECT user_id,
+               (occurred_at AT TIME ZONE 'UTC')::date AS active_date
+        FROM product_analytics_events
+        WHERE occurred_at >= ${sqlParam(cohortStart.toISOString())}
+      ),
+      sizes AS (
+        SELECT cohort_date, count(DISTINCT user_id) AS cohort_size
+        FROM cohort
+        GROUP BY cohort_date
+      )
+      SELECT s.cohort_date,
+             d.day,
+             s.cohort_size,
+             count(DISTINCT a.user_id) AS active_users
+      FROM sizes s
+      CROSS JOIN generate_series(0, 30) AS d(day)
+      LEFT JOIN cohort c ON c.cohort_date = s.cohort_date
+      LEFT JOIN activity a
+        ON a.user_id = c.user_id
+       AND a.active_date = s.cohort_date + d.day
+      GROUP BY s.cohort_date, d.day, s.cohort_size
+      ORDER BY s.cohort_date, d.day
+    `;
+
+    const result = await app.db.execute(sql.raw(raw));
+    const rows = Array.isArray(result) ? result : result.rows;
+
+    const cohorts: Record<
+      string,
+      { cohortSize: number; retention: Array<{ day: number; active: number; rate: number }> }
+    > = {};
+    for (const r of rows as Array<{ cohort_date: string; day: number; cohort_size: number; active_users: number }>) {
+      const key = String(r.cohort_date).slice(0, 10);
+      if (!cohorts[key]) {
+        cohorts[key] = { cohortSize: Number(r.cohort_size), retention: [] };
+      }
+      const size = Number(r.cohort_size);
+      cohorts[key].retention.push({
+        day: Number(r.day),
+        active: Number(r.active_users),
+        rate: size > 0 ? Number(r.active_users) / size : 0,
+      });
+    }
+
+    return { cohorts };
+  });
+
+  /** Daily event counts for trend charts. */
+  app.get("/admin/v1/analytics/event-counts", admin, async (req) => {
+    const query = z
+      .object({
+        startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        eventName: z.string().max(64).optional(),
+      })
+      .parse(req.query);
+
+    const start = new Date(query.startDate);
+    const end = new Date(query.endDate);
+    end.setUTCDate(end.getUTCDate() + 1);
+
+    let filter = "";
+    if (query.eventName) {
+      filter = `AND event_name = ${sqlParam(query.eventName)}`;
+    }
+
+    const raw = `
+      SELECT (occurred_at AT TIME ZONE 'UTC')::date AS date,
+             event_name,
+             count(*) AS total,
+             count(DISTINCT session_id) AS unique_sessions,
+             count(DISTINCT user_id) AS unique_users
+      FROM product_analytics_events
+      WHERE occurred_at >= ${sqlParam(start.toISOString())}
+        AND occurred_at < ${sqlParam(end.toISOString())}
+        ${filter}
+      GROUP BY date, event_name
+      ORDER BY date, event_name
+    `;
+
+    const result = await app.db.execute(sql.raw(raw));
+    const rows = Array.isArray(result) ? result : result.rows;
+    return { counts: rows };
+  });
+}
+
+/** Escape a string/date parameter for raw SQL by wrapping it in single quotes.
+ *  This is intentionally local-only SQL; dates and enums are validated above.
+ */
+function sqlParam(value: string | number): string {
+  if (typeof value === "number") return String(value);
+  return `'${String(value).replace(/'/g, "''")}'`;
+}

apps/api/src/routes/analytics.ts

@@ -0,0 +1,93 @@
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import { isAnalyticsOptedIn, schema } from "@app/database";
+import {
+  analyticsBatchInputSchema,
+  MAX_ANALYTICS_BATCH_SIZE,
+  validateAnalyticsPropertySize,
+} from "@app/validation";
+import { parse, errors } from "../lib/errors.js";
+import { audit } from "../lib/helpers.js";
+
+/** Max events per batch is also the per-minute rate-limit budget for this endpoint. */
+const ANALYTICS_RATE_LIMIT_MAX = MAX_ANALYTICS_BATCH_SIZE;
+
+/**
+ * Product analytics ingestion (spec §8.2).
+ * Accepts both authenticated and anonymous events. Anonymous events must have
+ * anonymousId and can be backfilled to userId later when the user logs in.
+ */
+export async function analyticsRoutes(app: FastifyInstance) {
+  app.post(
+    "/v1/analytics/events",
+    {
+      config: {
+        rateLimit: {
+          max: ANALYTICS_RATE_LIMIT_MAX,
+          timeWindow: "1 minute",
+          keyGenerator: (req) => `analytics:${req.ip}:${(req as unknown as { userId?: string }).userId ?? "anon"}`,
+        },
+      },
+    },
+    async (req, reply) => {
+      const input = parse(analyticsBatchInputSchema, req.body, "analytics batch");
+      validateAnalyticsPropertySize(input.events);
+
+      let userId: string | undefined;
+      try {
+        const payload = await req.jwtVerify<{ sub: string; role: string; type: string }>();
+        if (payload.type === "access" && payload.sub) {
+          userId = payload.sub;
+        }
+      } catch {
+        // Anonymous event – fine as long as the batch carries anonymousId.
+      }
+      const isAuthenticated = !!userId;
+
+      if (isAuthenticated && userId) {
+        const optedIn = await isAnalyticsOptedIn(app.db, userId);
+        if (!optedIn) {
+          throw errors.forbidden("Analytics collection disabled by user consent.");
+        }
+      }
+
+      const now = new Date();
+      const rows = input.events.map((event, index) => {
+        const occurredAt = event.occurredAt ? new Date(event.occurredAt) : now;
+        if (Number.isNaN(occurredAt.getTime())) {
+          throw errors.badRequest(`Invalid occurredAt for event ${index}`);
+        }
+        return {
+          occurredAt,
+          receivedAt: now,
+          eventName: event.name,
+          anonymousId: event.anonymousId ?? null,
+          sessionId: event.sessionId ?? null,
+          userId: isAuthenticated ? userId : null,
+          householdId: event.householdId ?? null,
+          appVersion: event.appVersion ?? null,
+          platform: event.platform ?? null,
+          locale: event.locale ?? null,
+          experimentVariant: event.experimentVariant ?? null,
+          properties: event.properties ?? {},
+        };
+      });
+
+      // Single insert for the whole batch. On conflict is impossible because
+      // events are insert-only with random UUIDs.
+      const result = await app.db.insert(schema.productAnalyticsEvents).values(rows);
+      const accepted = result.rowCount ?? rows.length;
+
+      if (isAuthenticated) {
+        await audit(app.db, {
+          actorUserId: userId,
+          action: "analytics.ingest",
+          targetType: "analytics_batch",
+          targetId: String(accepted),
+          ip: req.ip,
+        });
+      }
+
+      return reply.code(202).send({ accepted, rejected: 0 });
+    },
+  );
+}

apps/api/src/server.ts

@@ -21,6 +21,8 @@ import { budgetRoutes } from "./routes/budget.js";
 import { subscriptionRoutes } from "./routes/subscriptions.js";
 import { communityRoutes } from "./routes/community.js";
 import { adminRoutes } from "./routes/admin.js";
+import { adminAnalyticsRoutes } from "./routes/admin-analytics.js";
+import { analyticsRoutes } from "./routes/analytics.js";
 
 declare module "fastify" {
   interface FastifyInstance {
@@ -80,6 +82,8 @@ export async function buildServer(config: AppConfig) {
   await app.register(subscriptionRoutes);
   await app.register(communityRoutes);
   await app.register(adminRoutes);
+  await app.register(adminAnalyticsRoutes);
+  await app.register(analyticsRoutes);
 
   return app;
 }

apps/mobile/package.json

@@ -11,6 +11,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@app/analytics": "workspace:*",
     "@app/shared-types": "workspace:*",
     "@react-native-async-storage/async-storage": "^3.1.1",
     "@tanstack/query-async-storage-persister": "^5.90.0",

packages/analytics/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@app/analytics",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Product analytics tracker (spec §8.2) – React Native batch sender + typed builders.",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@app/shared-types": "workspace:*"
+  }
+}

packages/analytics/src/builders.ts

@@ -0,0 +1,90 @@
+/**
+ * Typed event builders for the product analytics taxonomy.
+ * Each builder returns a plain AnalyticsEvent ready for batching.
+ */
+import type { ProductAnalyticsEventName } from "@app/shared-types";
+import type { AnalyticsEvent } from "./types.js";
+
+function builder(name: ProductAnalyticsEventName) {
+  return (props?: {
+    occurredAt?: string;
+    anonymousId?: string;
+    sessionId?: string;
+    householdId?: string;
+    appVersion?: string;
+    platform?: "ios" | "android" | "web";
+    locale?: string;
+    experimentVariant?: string;
+    properties?: Record<string, unknown>;
+  }): AnalyticsEvent => ({ name, ...props });
+}
+
+// Acquisition & onboarding
+export const appInstalled = builder("app_installed");
+export const appFirstOpen = builder("app_first_open");
+export const onboardingStarted = builder("onboarding_started");
+export const onboardingStepCompleted = builder("onboarding_step_completed");
+export const onboardingSkipped = builder("onboarding_skipped");
+export const accountCreated = builder("account_created");
+export const householdCreated = builder("household_created");
+export const householdJoined = builder("household_joined");
+export const allergySetupCompleted = builder("allergy_setup_completed");
+export const cameraPermissionResult = builder("camera_permission_result");
+export const notificationPermissionResult = builder("notification_permission_result");
+
+// Inventory
+export const scanStarted = builder("scan_started");
+export const scanUploaded = builder("scan_uploaded");
+export const scanProcessingCompleted = builder("scan_processing_completed");
+export const scanProcessingFailed = builder("scan_processing_failed");
+export const scanReviewOpened = builder("scan_review_opened");
+export const scanItemConfirmed = builder("scan_item_confirmed");
+export const scanItemCorrected = builder("scan_item_corrected");
+export const scanItemRemoved = builder("scan_item_removed");
+export const scanCompleted = builder("scan_completed");
+export const inventoryItemAdded = builder("inventory_item_added");
+export const inventoryItemConsumed = builder("inventory_item_consumed");
+export const inventoryItemDiscarded = builder("inventory_item_discarded");
+export const inventoryReconciliationStarted = builder("inventory_reconciliation_started");
+export const inventoryReconciliationCompleted = builder("inventory_reconciliation_completed");
+export const inventoryConflictCreated = builder("inventory_conflict_created");
+export const inventoryConflictResolved = builder("inventory_conflict_resolved");
+
+// Recipes & cooking
+export const recommendationsViewed = builder("recommendations_viewed");
+export const recommendationOpened = builder("recommendation_opened");
+export const recipeSaved = builder("recipe_saved");
+export const cookingSessionStarted = builder("cooking_session_started");
+export const cookingSessionCompleted = builder("cooking_session_completed");
+export const cookingSessionCancelled = builder("cooking_session_cancelled");
+export const leftoversCreated = builder("leftovers_created");
+export const substitutionConfirmed = builder("substitution_confirmed");
+
+// Shopping
+export const shoppingItemAdded = builder("shopping_item_added");
+export const shoppingItemChecked = builder("shopping_item_checked");
+export const shoppingListShared = builder("shopping_list_shared");
+export const receiptScanned = builder("receipt_scanned");
+export const purchaseImported = builder("purchase_imported");
+
+// Household
+export const householdInviteSent = builder("household_invite_sent");
+export const householdInviteAccepted = builder("household_invite_accepted");
+export const secondMemberFirstAction = builder("second_member_first_action");
+
+// Subscription
+export const paywallViewed = builder("paywall_viewed");
+export const trialStarted = builder("trial_started");
+export const trialCancelled = builder("trial_cancelled");
+export const subscriptionStarted = builder("subscription_started");
+export const subscriptionRenewed = builder("subscription_renewed");
+export const subscriptionGracePeriod = builder("subscription_grace_period");
+export const subscriptionCancelled = builder("subscription_cancelled");
+export const subscriptionExpired = builder("subscription_expired");
+export const entitlementRestored = builder("entitlement_restored");
+
+// Feedback
+export const feedbackSubmitted = builder("feedback_submitted");
+export const incorrectInventoryReported = builder("incorrect_inventory_reported");
+export const badRecommendationReported = builder("bad_recommendation_reported");
+export const supportContactStarted = builder("support_contact_started");

packages/analytics/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./builders.js";
+export * from "./tracker.js";

packages/analytics/src/tracker.ts

@@ -0,0 +1,111 @@
+/**
+ * React Native analytics tracker: small in-memory queue + periodic flush.
+ * No PII is stored locally beyond anonymous/session ids.
+ */
+import type { AnalyticsBatchResult, AnalyticsEvent, TrackerConfig } from "./types.js";
+
+export type SendBatch = (events: AnalyticsEvent[]) => Promise<AnalyticsBatchResult>;
+
+export interface Tracker {
+  track: (event: AnalyticsEvent) => void;
+  flush: () => Promise<AnalyticsBatchResult>;
+  setSessionId: (sessionId: string) => void;
+  setAuthToken: (token: string | undefined) => void;
+  setAnonymousId: (anonymousId: string) => void;
+  destroy: () => void;
+}
+
+/**
+ * Create a tracker that batches events in memory and flushes periodically.
+ * In a React Native app the storage adapter (AsyncStorage) should persist
+ * anonymousId; this tracker intentionally keeps no durable local state.
+ */
+export function createTracker(config: TrackerConfig, send: SendBatch): Tracker {
+  const maxBatchSize = config.maxBatchSize ?? 20;
+  const flushIntervalMs = config.flushIntervalMs ?? 10_000;
+  let queue: AnalyticsEvent[] = [];
+  let sessionId = config.sessionId ?? "";
+  let authToken = config.authToken ?? "";
+  let anonymousId = config.anonymousId ?? "";
+
+  function enrich(event: AnalyticsEvent): AnalyticsEvent {
+    return {
+      ...event,
+      anonymousId: event.anonymousId ?? anonymousId,
+      sessionId: event.sessionId ?? sessionId,
+      appVersion: event.appVersion ?? config.appVersion,
+      platform: event.platform ?? config.platform,
+      locale: event.locale ?? config.locale,
+      occurredAt: event.occurredAt ?? new Date().toISOString(),
+    };
+  }
+
+  async function flush(): Promise<AnalyticsBatchResult> {
+    if (queue.length === 0) return { accepted: 0 };
+    const batch = queue.slice(0, maxBatchSize);
+    queue = queue.slice(maxBatchSize);
+    try {
+      const result = await send(batch);
+      if (result.rejected && result.rejected > 0) {
+        // Put rejected events back at the front of the queue only if the
+        // server asked us to retry (e.g. rate limit). For validation errors
+        // we drop them to avoid an infinite retry loop.
+        const retryable = batch.filter((_, i) =>
+          result.errors?.some((e) => e.index === i && e.message.toLowerCase().includes("rate limit")),
+        );
+        queue = [...retryable, ...queue];
+      }
+      return result;
+    } catch (err) {
+      // Network failure: keep events for next flush.
+      queue = [...batch, ...queue];
+      return { accepted: 0, rejected: batch.length, errors: [{ index: 0, message: String(err) }] };
+    }
+  }
+
+  const timer = flushIntervalMs > 0 ? setInterval(() => void flush(), flushIntervalMs) : null;
+
+  return {
+    track(event: AnalyticsEvent) {
+      queue.push(enrich(event));
+      if (queue.length >= maxBatchSize) {
+        void flush();
+      }
+    },
+    flush,
+    setSessionId(next) {
+      sessionId = next;
+    },
+    setAuthToken(next) {
+      authToken = next ?? "";
+    },
+    setAnonymousId(next) {
+      anonymousId = next;
+    },
+    destroy() {
+      if (timer) clearInterval(timer);
+    },
+  };
+}
+
+/**
+ * Default HTTP sender for the batch endpoint.
+ * This function has no React Native dependencies and can be used anywhere.
+ */
+export function createHttpSend(config: { apiBaseUrl: string; authToken?: string }): SendBatch {
+  return async (events) => {
+    const res = await fetch(`${config.apiBaseUrl.replace(/\/$/, "")}/v1/analytics/events`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(config.authToken ? { Authorization: `Bearer ${config.authToken}` } : {}),
+      },
+      body: JSON.stringify({ events }),
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "unknown error");
+      throw new Error(`Analytics API ${res.status}: ${text}`);
+    }
+    return (await res.json().catch(() => ({ accepted: events.length }))) as AnalyticsBatchResult;
+  };
+}

packages/analytics/src/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Product analytics tracker types (spec §8.2).
+ * Events are plain JSON objects validated against the shared taxonomy.
+ */
+import type { ProductAnalyticsEventName } from "@app/shared-types";
+
+export interface AnalyticsEvent {
+  name: ProductAnalyticsEventName;
+  /** ISO 8601 timestamp. Defaults to now if omitted. */
+  occurredAt?: string;
+  /** UUID or device-stable pseudonymous id. */
+  anonymousId?: string;
+  /** Session id, rotated periodically. */
+  sessionId?: string;
+  /** Active household when event was produced. */
+  householdId?: string;
+  appVersion?: string;
+  platform?: "ios" | "android" | "web";
+  locale?: string;
+  experimentVariant?: string;
+  /** Structured, safe properties only (no PII, no free text). */
+  properties?: Record<string, unknown>;
+}
+
+export interface AnalyticsBatchPayload {
+  events: AnalyticsEvent[];
+}
+
+export interface AnalyticsBatchResult {
+  accepted: number;
+  rejected?: number;
+  errors?: Array<{ index: number; message: string }>;
+}
+
+export interface TrackerConfig {
+  apiBaseUrl: string;
+  /** Auth token; events sent before login are anonymous. */
+  authToken?: string;
+  /** Anonymous id persisted for this install. */
+  anonymousId: string;
+  /** Current session id. */
+  sessionId?: string;
+  appVersion: string;
+  platform: "ios" | "android" | "web";
+  locale: string;
+  /** Max events per batch. */
+  maxBatchSize?: number;
+  /** Flush interval in ms. */
+  flushIntervalMs?: number;
+}

packages/analytics/test/tracker.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Unit tests for the analytics tracker.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { createTracker, appFirstOpen, scanStarted } from "@app/analytics";
+import type { AnalyticsBatchResult, AnalyticsEvent, SendBatch } from "@app/analytics";
+
+describe("createTracker", () => {
+  it("enriches events with default context and flushes immediately when batch is full", async () => {
+    const sent: AnalyticsEvent[][] = [];
+    const send: SendBatch = vi.fn(async (events) => {
+      sent.push(events);
+      return { accepted: events.length } satisfies AnalyticsBatchResult;
+    });
+
+    const tracker = createTracker(
+      {
+        apiBaseUrl: "http://localhost:4000",
+        anonymousId: "anon-1",
+        sessionId: "session-1",
+        appVersion: "1.0.0",
+        platform: "ios",
+        locale: "sv-SE",
+        maxBatchSize: 2,
+        flushIntervalMs: 0,
+      },
+      send,
+    );
+
+    tracker.track(appFirstOpen());
+    tracker.track(scanStarted({ properties: { source: "camera" } }));
+    await tracker.flush();
+
+    expect(sent).toHaveLength(1);
+    const firstBatch = sent[0]!;
+    expect(firstBatch).toHaveLength(2);
+    expect(firstBatch[0]).toBeDefined();
+    expect(firstBatch[0]!.name).toBe("app_first_open");
+    expect(firstBatch[0]!.anonymousId).toBe("anon-1");
+    expect(firstBatch[0]!.sessionId).toBe("session-1");
+    expect(firstBatch[0]!.appVersion).toBe("1.0.0");
+    expect(firstBatch[0]!.platform).toBe("ios");
+    expect(firstBatch[0]!.locale).toBe("sv-SE");
+    expect(firstBatch[0]!.occurredAt).toBeDefined();
+    expect(firstBatch[1]).toBeDefined();
+    expect(firstBatch[1]!.name).toBe("scan_started");
+    expect(firstBatch[1]!.properties).toEqual({ source: "camera" });
+
+    tracker.destroy();
+  });
+
+  it("requeues events when send fails", async () => {
+    let calls = 0;
+    const send: SendBatch = vi.fn(async () => {
+      calls++;
+      if (calls === 1) throw new Error("network");
+      return { accepted: 1 };
+    });
+
+    const tracker = createTracker(
+      {
+        apiBaseUrl: "http://localhost:4000",
+        anonymousId: "anon-2",
+        appVersion: "1.0.0",
+        platform: "android",
+        locale: "en-US",
+        maxBatchSize: 1,
+        flushIntervalMs: 0,
+      },
+      send,
+    );
+
+    tracker.track(appFirstOpen());
+    const first = await tracker.flush();
+    expect(first.accepted).toBe(0);
+
+    const second = await tracker.flush();
+    expect(second.accepted).toBe(1);
+    expect(send).toHaveBeenCalledTimes(2);
+
+    tracker.destroy();
+  });
+
+  it("drops validation-rejected events instead of retrying forever", async () => {
+    const send: SendBatch = vi.fn(async () => ({
+      accepted: 0,
+      rejected: 1,
+      errors: [{ index: 0, message: "validation error, do not retry" }],
+    }));
+
+    const tracker = createTracker(
+      {
+        apiBaseUrl: "http://localhost:4000",
+        anonymousId: "anon-3",
+        appVersion: "1.0.0",
+        platform: "web",
+        locale: "sv-SE",
+        maxBatchSize: 100,
+        flushIntervalMs: 0,
+      },
+      send,
+    );
+
+    tracker.track(appFirstOpen());
+    const result = await tracker.flush();
+    expect(result.rejected).toBe(1);
+
+    // Queue should be empty; second flush returns zero.
+    const second = await tracker.flush();
+    expect(second.accepted).toBe(0);
+    expect(send).toHaveBeenCalledTimes(1);
+
+    tracker.destroy();
+  });
+});

packages/analytics/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "lib": ["ES2023", "DOM"]
+  },
+  "include": ["src/**/*", "test/**/*"]
+}

packages/validation/src/analytics.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { PRODUCT_ANALYTICS_EVENT_NAMES } from "@app/shared-types";
+
+export const MAX_ANALYTICS_BATCH_SIZE = 50;
+export const MAX_ANALYTICS_PROPERTY_SIZE = 8 * 1024; // 8 KiB per event properties JSON
+
+const eventNameSchema = z.enum(PRODUCT_ANALYTICS_EVENT_NAMES);
+
+const analyticsEventSchema = z.object({
+  name: eventNameSchema,
+  occurredAt: z.string().refine((v) => !Number.isNaN(Date.parse(v))).optional(),
+  anonymousId: z.string().max(64).optional(),
+  sessionId: z.string().max(64).optional(),
+  householdId: z.string().uuid().optional(),
+  appVersion: z.string().max(32).optional(),
+  platform: z.enum(["ios", "android", "web"]).optional(),
+  locale: z.string().max(16).optional(),
+  experimentVariant: z.string().max(128).optional(),
+  properties: z.record(z.string(), z.unknown()).default({}),
+});
+
+export const analyticsBatchInputSchema = z.object({
+  events: z
+    .array(analyticsEventSchema)
+    .min(1, "At least one event is required")
+    .max(MAX_ANALYTICS_BATCH_SIZE, `Max ${MAX_ANALYTICS_BATCH_SIZE} events per batch`),
+});
+
+export type AnalyticsBatchInput = z.infer<typeof analyticsBatchInputSchema>;
+
+/**
+ * Validate that the JSON-stringified properties of each event fit within the
+ * per-event byte budget. Call this after zod parsing.
+ */
+export function validateAnalyticsPropertySize(events: AnalyticsBatchInput["events"]): void {
+  for (let i = 0; i < events.length; i++) {
+    const size = new Blob([JSON.stringify(events[i]?.properties ?? {})]).size;
+    if (size > MAX_ANALYTICS_PROPERTY_SIZE) {
+      throw new Error(
+        `Event ${i} properties exceed ${MAX_ANALYTICS_PROPERTY_SIZE} bytes (${size})`,
+      );
+    }
+  }
+}

packages/validation/src/index.ts

@@ -12,3 +12,4 @@ export * from "./recommendations.js";
 export * from "./memory.js";
 export * from "./subscriptions.js";
 export * from "./locale.js";
+export * from "./analytics.js";