Sven (AAMOS AI)
247 lines
8.5 KiB
TypeScript
247 lines
8.5 KiB
TypeScript
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 };
|
|
});
|
|
|
|
/** Household activation metrics (Fas 1b). */
|
|
app.get("/admin/v1/analytics/activation", admin, async () => {
|
|
const result = await app.db.execute(sql`
|
|
SELECT
|
|
COUNT(*) FILTER (WHERE first_scan_completed_at IS NOT NULL) AS scanned,
|
|
COUNT(*) FILTER (WHERE activated_at IS NOT NULL) AS activated,
|
|
COUNT(*) FILTER (WHERE value_confirmed_at IS NOT NULL) AS value_confirmed,
|
|
COUNT(*) AS total
|
|
FROM households
|
|
`);
|
|
const rows = Array.isArray(result) ? result : result.rows;
|
|
const r = rows[0] as Record<string, number>;
|
|
return {
|
|
totalHouseholds: Number(r.total ?? 0),
|
|
scanned: Number(r.scanned ?? 0),
|
|
activated: Number(r.activated ?? 0),
|
|
valueConfirmed: Number(r.value_confirmed ?? 0),
|
|
activationRate: r.total ? Number(r.activated) / Number(r.total) : 0,
|
|
valueConfirmationRate: r.total ? Number(r.value_confirmed) / Number(r.total) : 0,
|
|
};
|
|
});
|
|
}
|
|
|
|
/** 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, "''")}'`;
|
|
}
|