Fas 1a: analytics tracker, ingestion endpoint, admin dashboards
This commit is contained in:
Sven (AAMOS AI)
@@ -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>
|
||||
|
||||
@@ -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>
|
||||
);
|
||||
}
|
||||
@@ -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, "''")}'`;
|
||||
}
|
||||
@@ -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 });
|
||||
},
|
||||
);
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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:*"
|
||||
}
|
||||
}
|
||||
@@ -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");
|
||||
@@ -0,0 +1,3 @@
|
||||
export * from "./types.js";
|
||||
export * from "./builders.js";
|
||||
export * from "./tracker.js";
|
||||
@@ -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;
|
||||
};
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"extends": "../../tsconfig.base.json",
|
||||
"compilerOptions": {
|
||||
"outDir": "./dist",
|
||||
"rootDir": ".",
|
||||
"lib": ["ES2023", "DOM"]
|
||||
},
|
||||
"include": ["src/**/*", "test/**/*"]
|
||||
}
|
||||
@@ -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})`,
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -12,3 +12,4 @@ export * from "./recommendations.js";
|
||||
export * from "./memory.js";
|
||||
export * from "./subscriptions.js";
|
||||
export * from "./locale.js";
|
||||
export * from "./analytics.js";
|
||||
|
||||
Generated
+3582
-6450
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user