🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Retention (#75)
Bill Yangc453578c4ff5
diff --git a/client/src/api/analytics/useGetRetention.ts b/client/src/api/analytics/useGetRetention.tsnew file mode 100644index 000000000..3036f5404--- /dev/null+++ b/client/src/api/analytics/useGetRetention.ts@@ -0,0 +1,30 @@+import { useQuery } from "@tanstack/react-query";+import { BACKEND_URL } from "../../lib/const";+import { useStore } from "../../lib/store";+import { authedFetch } from "../utils";++// Define the interface for processed retention data+export interface ProcessedRetentionData {+ cohorts: Record<string, { size: number; percentages: (number | null)[] }>;+ maxPeriods: number;+ mode: "day" | "week";+ range: number;+}++export type RetentionMode = "day" | "week";++export function useGetRetention(+ mode: RetentionMode = "week",+ range: number = 90+) {+ const { site } = useStore();+ return useQuery<ProcessedRetentionData>({+ queryKey: ["retention", site, mode, range],+ queryFn: () =>+ authedFetch(+ `${BACKEND_URL}/retention/${site}?mode=${mode}&range=${range}`+ )+ .then((res) => res.json())+ .then((data) => data.data),+ });+}diff --git a/client/src/app/[site]/Header/Header.tsx b/client/src/app/[site]/Header/Header.tsxindex e4f504644..5ce2da126 100644--- a/client/src/app/[site]/Header/Header.tsx+++ b/client/src/app/[site]/Header/Header.tsx@@ -65,6 +65,12 @@ export function Header() {href={getTabPath("realtime")}icon={<Radio size={20} />}/>+ <TabButton+ label="Retention"+ active={isActiveTab("retention")}+ href={getTabPath("retention")}+ icon={<ChartBarDecreasing size={20} />}+ /><TabButtonlabel="Reports"active={isActiveTab("reports")}diff --git a/client/src/app/[site]/retention/RetentionChart.tsx b/client/src/app/[site]/retention/RetentionChart.tsxnew file mode 100644index 000000000..d74be483d--- /dev/null+++ b/client/src/app/[site]/retention/RetentionChart.tsx@@ -0,0 +1,259 @@+"use client";++import { nivoTheme } from "@/lib/nivo";+import {+ ProcessedRetentionData,+ RetentionMode,+} from "../../../api/analytics/useGetRetention";+import { ResponsiveLine } from "@nivo/line";+import { useMemo } from "react";+import { Skeleton } from "../../../components/ui/skeleton";+import { DateTime } from "luxon";++interface RetentionChartProps {+ data: ProcessedRetentionData | undefined;+ isLoading: boolean;+ mode: RetentionMode;+}++// Vibrant color palette for different cohorts using Tailwind CSS HSL variables+const cohortColors = [+ "hsl(var(--accent-500))", // Primary accent color+ "hsl(var(--green-500))", // Green+ "hsl(var(--red-500))", // Red+ "hsl(var(--blue-500))", // Blue+ "hsl(var(--orange-500))", // Orange+ "hsl(var(--purple-500))", // Purple+ "hsl(var(--teal-500))", // Teal+ "hsl(var(--amber-500))", // Amber+ "hsl(var(--slate-600))", // Slate+ "hsl(var(--red-600))", // Darker red+ "hsl(var(--green-600))", // Darker green+ "hsl(var(--blue-600))", // Darker blue+ "hsl(var(--purple-600))", // Darker purple+ "hsl(var(--teal-600))", // Darker teal+];++// Loading skeleton+const RetentionChartSkeleton = () => (+ <div className="h-[400px] flex items-center justify-center">+ <div className="w-full space-y-3">+ <Skeleton className="h-[300px] w-full bg-neutral-900 rounded-md animate-pulse" />+ <div className="flex items-center justify-between px-6">+ {Array.from({ length: 6 }).map((_, i) => (+ <Skeleton+ key={i}+ className="h-4 w-12 bg-neutral-700/50 animate-pulse"+ style={{+ animationDelay: `${i * 100}ms`,+ opacity: 0.3 + i * 0.1,+ }}+ />+ ))}+ </div>+ </div>+ </div>+);++export function RetentionChart({ data, isLoading, mode }: RetentionChartProps) {+ // Get cohort keys once for both chart data and tooltip+ const cohortKeys = useMemo(() => {+ if (!data || !data.cohorts) return [];+ return Object.keys(data.cohorts)+ .sort((a, b) => b.localeCompare(a))+ .slice(0, 12); // Limit to 12 most recent cohorts for better readability+ }, [data]);++ // Process data for the chart - organize by cohort+ const chartData = useMemo(() => {+ if (!data || !data.cohorts || cohortKeys.length === 0) {+ return [];+ }++ // Format each cohort as a series (line)+ return cohortKeys.map((cohortKey, index) => {+ const cohortData = data.cohorts[cohortKey];++ // Format the date label based on mode+ let formattedDate: string;+ if (mode === "day") {+ formattedDate = DateTime.fromISO(cohortKey).toFormat("MMM dd");+ } else {+ // For weekly mode+ const startDate = DateTime.fromISO(cohortKey);+ const endDate = startDate.plus({ days: 6 });++ // If same month, don't repeat month+ if (startDate.month === endDate.month) {+ formattedDate = `${startDate.toFormat("MMM dd")}-${endDate.toFormat(+ "dd"+ )}`;+ } else {+ formattedDate = `${startDate.toFormat("MMM dd")}-${endDate.toFormat(+ "MMM dd"+ )}`;+ }+ }++ // Create data points for each period+ const points = cohortData.percentages.map((percentage, periodIndex) => ({+ x: periodIndex,+ y: percentage ?? null,+ }));++ return {+ id: formattedDate,+ data: points.filter((point) => point.y !== null), // Remove null points+ color: cohortColors[index % cohortColors.length],+ };+ });+ }, [data, mode, cohortKeys]);++ if (isLoading) {+ return <RetentionChartSkeleton />;+ }++ if (!data || chartData.length === 0) {+ return (+ <div className="h-[400px] flex items-center justify-center">+ <div className="text-neutral-400 text-sm">+ No retention data available+ </div>+ </div>+ );+ }++ // Calculate max Y value with a little headroom+ const maxY = Math.min(+ 100,+ Math.max(+ ...chartData.flatMap((series) =>+ series.data.map((d) => (typeof d.y === "number" ? d.y : 0))+ )+ ) * 1.1+ );++ return (+ <div className="h-[400px]">+ <ResponsiveLine+ data={chartData}+ theme={nivoTheme}+ margin={{ top: 20, right: 100, bottom: 30, left: 40 }}+ xScale={{+ type: "linear",+ min: 0,+ max: "auto",+ }}+ yScale={{+ type: "linear",+ min: 0,+ max: maxY,+ stacked: false,+ }}+ curve="linear"+ axisBottom={{+ tickSize: 5,+ tickPadding: 5,+ tickRotation: 0,+ tickValues: chartData.length,+ format: (value) => `${value}`,+ }}+ axisLeft={{+ tickSize: 5,+ tickPadding: 5,+ tickRotation: 0,+ format: (value) => `${value}%`,+ }}+ enableGridX={true}+ gridXValues={Array.from({ length: data.maxPeriods + 1 }, (_, i) => i)}+ colors={{ datum: "color" }}+ useMesh={true}+ pointSize={0}+ legends={[+ {+ anchor: "right",+ direction: "column",+ justify: false,+ translateX: 120,+ translateY: 0,+ itemsSpacing: 5,+ itemDirection: "left-to-right",+ itemWidth: 100,+ itemHeight: 20,+ itemOpacity: 0.85,+ symbolSize: 12,+ symbolShape: "circle",+ symbolBorderColor: "rgba(0, 0, 0, .5)",+ effects: [+ {+ on: "hover",+ style: {+ itemBackground: "rgba(0, 0, 0, .1)",+ itemOpacity: 1,+ },+ },+ ],+ itemTextColor: "hsl(var(--neutral-200))",+ },+ ]}+ tooltip={({ point }) => {+ const value = point.data.y as number | null;+ const xValue = point.data.x as number;++ // Find the original cohort date by matching the formatted label+ const cohortEntry = chartData.find(+ (series) => series.id === point.serieId+ );+ const cohortIndex = cohortEntry ? chartData.indexOf(cohortEntry) : -1;+ const originalCohortKey =+ cohortIndex >= 0 && cohortKeys && cohortKeys[cohortIndex];++ // Format full date for tooltip+ let cohortDateDisplay = point.serieId;+ if (originalCohortKey) {+ if (mode === "day") {+ cohortDateDisplay =+ DateTime.fromISO(originalCohortKey).toFormat("MMM dd, yyyy");+ } else {+ const startDate = DateTime.fromISO(originalCohortKey);+ const endDate = startDate.plus({ days: 6 });++ if (startDate.month === endDate.month) {+ cohortDateDisplay = `${startDate.toFormat(+ "MMM dd"+ )} - ${endDate.toFormat("dd, yyyy")}`;+ } else if (startDate.year === endDate.year) {+ cohortDateDisplay = `${startDate.toFormat(+ "MMM dd"+ )} - ${endDate.toFormat("MMM dd, yyyy")}`;+ } else {+ cohortDateDisplay = `${startDate.toFormat(+ "MMM dd, yyyy"+ )} - ${endDate.toFormat("MMM dd, yyyy")}`;+ }+ }+ }++ return (+ <div className="text-sm bg-neutral-850 p-2 rounded-md border border-neutral-800 shadow-md">+ <div+ className="font-medium mb-1"+ style={{ color: point.serieColor }}+ >+ Cohort: {cohortDateDisplay}+ </div>+ <div className="flex justify-between w-48 text-neutral-200">+ <span>+ {mode === "day" ? "Day" : "Week"} {xValue}+ </span>+ <span className="font-medium">+ {value !== null ? `${value.toFixed(1)}%` : "-"}+ </span>+ </div>+ </div>+ );+ }}+ />+ </div>+ );+}diff --git a/client/src/app/[site]/retention/page.tsx b/client/src/app/[site]/retention/page.tsxnew file mode 100644index 000000000..863e8d174--- /dev/null+++ b/client/src/app/[site]/retention/page.tsx@@ -0,0 +1,400 @@+"use client";++import {+ useGetRetention,+ RetentionMode,+} from "../../../api/analytics/useGetRetention";+import { DateTime } from "luxon"; // Import Luxon for date formatting+import { Fragment, useMemo, useState } from "react";+import {+ Card,+ CardContent,+ CardHeader,+ CardTitle,+} from "../../../components/ui/card";+import { Tabs, TabsList, TabsTrigger } from "../../../components/ui/tabs";+import {+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+} from "../../../components/ui/select";+import { Label } from "../../../components/ui/label";+import {+ Tooltip,+ TooltipContent,+ TooltipProvider,+ TooltipTrigger,+} from "../../../components/ui/tooltip";+import { HelpCircle } from "lucide-react";+import { Skeleton } from "../../../components/ui/skeleton";+import { RetentionChart } from "./RetentionChart";++// Available time range options (in days)+const RANGE_OPTIONS = [+ { value: "7", label: "7 days" },+ { value: "14", label: "14 days" },+ { value: "30", label: "30 days" },+ { value: "60", label: "60 days" },+ { value: "90", label: "90 days" },+ { value: "180", label: "6 months" },+ { value: "365", label: "1 year" },+];++// Default number of periods and cohorts for skeleton+const DEFAULT_SKELETON_PERIODS = 6;+const DEFAULT_SKELETON_COHORTS = 8;++// Dynamic color function that creates a smooth gradient based on retention percentage+const getRetentionColor = (+ percentage: number | null+): { backgroundColor: string; textColor: string } => {+ if (percentage === null || isNaN(percentage)) {+ return {+ backgroundColor: "hsl(var(--neutral-900))",+ textColor: "transparent",+ };+ }++ if (percentage === 0) {+ return {+ backgroundColor: "hsl(var(--neutral-850))",+ textColor: "var(--text-dark, #262626)",+ };+ }++ // Use a consistent blue hue+ const hue = 210; // Fixed blue hue++ // Use a consistent saturation+ const saturation = 80; // Fixed high saturation++ // Only vary the lightness based on retention percentage+ // High retention = darker (lower lightness), low retention = lighter+ // Scale from 85% (low retention) to 30% (high retention)+ const lightness = Math.max(30, Math.min(85, 85 - percentage * 0.55));++ // Determine text color (white for dark backgrounds, dark for light backgrounds)+ const textColor = lightness < 50 ? "white" : "var(--text-dark, #262626)";++ return {+ backgroundColor: `hsl(${hue}, ${saturation}%, ${lightness}%)`,+ textColor,+ };+};++// Loading skeleton for the retention grid+const RetentionGridSkeleton = () => {+ const periodHeaders = Array.from(+ { length: DEFAULT_SKELETON_PERIODS + 1 },+ (_, i) => (i === 0 ? "Cohort" : `Week ${i - 1}`)+ );++ return (+ <div className="overflow-x-auto">+ <div+ className="inline-grid gap-px bg-neutral-900 border border-neutral-800 rounded-lg shadow-lg"+ style={{+ gridTemplateColumns: `minmax(120px, auto) repeat(${DEFAULT_SKELETON_PERIODS}, minmax(90px, auto))`,+ }}+ >+ {/* Header Row */}+ {periodHeaders.map((header, i) => (+ <div+ key={`header-${i}`}+ className={`p-3 font-semibold bg-neutral-900 text-center border-b border-neutral-700 ${+ i === 0 ? "sticky left-0 z-10 border-r" : ""+ }`}+ >+ <Skeleton className="h-4 w-16 mx-auto bg-neutral-700/50 animate-pulse" />+ </div>+ ))}++ {/* Data Rows */}+ {Array.from({ length: DEFAULT_SKELETON_COHORTS }).map((_, rowIndex) => (+ <Fragment key={`row-${rowIndex}`}>+ {/* Cohort Info Cell */}+ <div className="p-3 bg-neutral-900 text-sm sticky left-0 z-10 border-r border-neutral-700">+ <Skeleton className="h-4 w-24 mb-2 bg-neutral-700/50 animate-pulse" />+ <Skeleton className="h-3 w-16 bg-neutral-700/50 animate-pulse" />+ </div>+ {/* Retention Cells */}+ {Array.from({ length: DEFAULT_SKELETON_PERIODS }).map(+ (_, cellIndex) => (+ <div+ key={`cell-${rowIndex}-${cellIndex}`}+ className="m-[2px] p-3 flex items-center justify-center bg-neutral-800 rounded-md"+ >+ <Skeleton+ className={`h-4 w-10 bg-neutral-700/50 animate-pulse`}+ style={{+ animationDelay: `${+ (rowIndex * DEFAULT_SKELETON_PERIODS + cellIndex) * 50+ }ms`,+ }}+ />+ </div>+ )+ )}+ </Fragment>+ ))}+ </div>+ </div>+ );+};++export default function RetentionPage() {+ // State for the retention mode (day or week)+ const [mode, setMode] = useState<RetentionMode>("week");+ // State for the data time range (days)+ const [timeRange, setTimeRange] = useState<number>(90);++ // Use the updated hook without the limit parameter+ const { data, isLoading, isError } = useGetRetention(mode, timeRange);++ // Get sorted cohort keys (oldest first)+ const cohortKeys = useMemo(+ () =>+ data?.cohorts+ ? Object.keys(data.cohorts).sort((a, b) => a.localeCompare(b))+ : [],+ [data?.cohorts]+ );++ // Function to format date based on mode+ const formatDate = (dateStr: string) => {+ if (mode === "day") {+ return DateTime.fromISO(dateStr).toFormat("MMM dd, yyyy");+ } else {+ // For weekly mode, show start and end dates of the week+ const startDate = DateTime.fromISO(dateStr);+ const endDate = startDate.plus({ days: 6 }); // End of week (7 days total)++ // If same month, don't repeat month name+ if (startDate.month === endDate.month) {+ return `${startDate.toFormat("MMM dd")} - ${endDate.toFormat(+ "dd, yyyy"+ )}`;+ } else if (startDate.year === endDate.year) {+ // Different months, same year+ return `${startDate.toFormat("MMM dd")} - ${endDate.toFormat(+ "MMM dd, yyyy"+ )}`;+ } else {+ // Different years+ return `${startDate.toFormat("MMM dd, yyyy")} - ${endDate.toFormat(+ "MMM dd, yyyy"+ )}`;+ }+ }+ };++ // Labels for column headers based on mode+ const getPeriodLabel = (index: number) => {+ return mode === "day" ? `Day ${index}` : `Week ${index}`;+ };++ const handleModeChange = (newMode: string) => {+ setMode(newMode as RetentionMode);+ };++ const handleRangeChange = (value: string) => {+ setTimeRange(parseInt(value));+ };++ // Common filters for both views+ const FilterControls = () => (+ <div className="flex items-center gap-4 flex-wrap justify-end">+ <div className="flex items-center gap-2">+ <Label htmlFor="time-range" className="text-sm whitespace-nowrap">+ Time Range:+ <TooltipProvider>+ <Tooltip>+ <TooltipTrigger asChild>+ <HelpCircle className="h-3.5 w-3.5 ml-1 inline-block text-neutral-400" />+ </TooltipTrigger>+ <TooltipContent>+ <p className="w-[200px] text-xs">+ Amount of historical data to include in the retention+ calculation. All available periods within this timeframe will+ be shown.+ </p>+ </TooltipContent>+ </Tooltip>+ </TooltipProvider>+ </Label>+ <Select+ value={timeRange.toString()}+ onValueChange={handleRangeChange}+ disabled={isLoading}+ >+ <SelectTrigger id="time-range" className="w-28" size="sm">+ <SelectValue placeholder="90 days" />+ </SelectTrigger>+ <SelectContent size="sm">+ {RANGE_OPTIONS.map((option) => (+ <SelectItem key={option.value} value={option.value}>+ {option.label}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </div>+ <Tabs value={mode} onValueChange={handleModeChange}>+ <TabsList>+ <TabsTrigger value="day" disabled={isLoading}>+ Daily+ </TabsTrigger>+ <TabsTrigger value="week" disabled={isLoading}>+ Weekly+ </TabsTrigger>+ </TabsList>+ </Tabs>+ </div>+ );++ // Render error state+ if (isError) {+ return (+ <div className="pt-4">+ <Card>+ <CardHeader>+ <CardTitle>User Retention</CardTitle>+ </CardHeader>+ <CardContent>+ <div className="p-8 text-center">+ <div className="text-red-500 mb-2 font-medium">+ Error loading retention data+ </div>+ <p className="text-neutral-500 text-sm">+ There was a problem fetching the retention data. Please try+ again later.+ </p>+ </div>+ </CardContent>+ </Card>+ </div>+ );+ }++ // Render empty state+ if (data && (!data.cohorts || cohortKeys.length === 0)) {+ return (+ <div className="pt-4">+ <Card>+ <CardHeader>+ <CardTitle>User Retention</CardTitle>+ </CardHeader>+ <CardContent>+ <div className="p-8 text-center">+ <div className="text-neutral-300 mb-2 font-medium">+ No retention data available+ </div>+ <p className="text-neutral-500 text-sm">+ Try selecting a different time range or make sure you have+ tracking data in the system.+ </p>+ </div>+ </CardContent>+ </Card>+ </div>+ );+ }++ const periodHeaders =+ !isLoading && data+ ? Array.from({ length: data.maxPeriods + 1 }, (_, i) => getPeriodLabel(i))+ : [];++ return (+ <div className="pt-4">+ {/* Single Card containing both chart and grid */}+ <Card>+ <CardHeader className="flex flex-row items-center justify-between pb-2">+ <CardTitle>User Retention</CardTitle>+ <FilterControls />+ </CardHeader>+ <CardContent className="space-y-6">+ {/* Retention Chart */}+ {isLoading ? (+ <div className="h-[400px]">+ <div className="w-full h-full space-y-3">+ <Skeleton className="h-[350px] w-full bg-neutral-900 rounded-md animate-pulse" />+ </div>+ </div>+ ) : data ? (+ <RetentionChart data={data} isLoading={false} mode={mode} />+ ) : null}++ <div>+ {isLoading ? (+ <RetentionGridSkeleton />+ ) : data ? (+ <div className="overflow-x-auto">+ <div+ className="inline-grid gap-px bg-neutral-900 rounded-lg shadow-lg"+ style={{+ gridTemplateColumns: `minmax(120px, auto) repeat(${+ data.maxPeriods + 1+ }, minmax(90px, auto))`,+ }}+ >+ {/* Header Row */}+ <div className="p-2 text-sm font-semibold bg-neutral-900 text-neutral-100 text-center sticky left-0 z-10 border-b border-r border-neutral-700">+ Cohort+ </div>+ {periodHeaders.map((header) => (+ <div+ key={header}+ className="p-2 text-sm bg-neutral-900 text-neutral-100 text-center border-b border-neutral-700"+ >+ {header}+ </div>+ ))}++ {/* Data Rows */}+ {cohortKeys.map((cohortPeriod) => (+ <Fragment key={cohortPeriod}>+ {/* Cohort Info Cell */}+ <div className="p-3 bg-neutral-900 text-sm sticky left-0 z-10 border-r border-neutral-800">+ <div className="font-medium whitespace-nowrap text-neutral-100">+ {formatDate(cohortPeriod)}+ </div>+ <div className="text-xs text-neutral-300 mt-1 whitespace-nowrap">+ {data.cohorts[cohortPeriod].size.toLocaleString()}{" "}+ users+ </div>+ </div>+ {/* Retention Cells */}+ {data.cohorts[cohortPeriod].percentages.map(+ (percentage: number | null, index: number) => {+ const { backgroundColor, textColor } =+ getRetentionColor(percentage);+ return (+ <div+ key={`${cohortPeriod}-period-${index}`}+ className="m-[2px] p-3 text-center flex items-center justify-center font-medium transition-colors duration-150 bg-neutral-900 rounded-md"+ style={{+ backgroundColor,+ color: textColor,+ }}+ >+ {percentage !== null+ ? `${percentage.toFixed(1)}%`+ : "-"}+ </div>+ );+ }+ )}+ </Fragment>+ ))}+ </div>+ </div>+ ) : null}+ </div>+ </CardContent>+ </Card>+ </div>+ );+}diff --git a/server/src/api/getOverviewBucketed.ts b/server/src/api/getOverviewBucketed.tsindex 9e87dbeaa..fa46e300c 100644--- a/server/src/api/getOverviewBucketed.ts+++ b/server/src/api/getOverviewBucketed.ts@@ -208,8 +208,6 @@ export async function getOverviewBucketed(pastMinutes,});- console.info(query);-try {const result = await clickhouse.query({query,diff --git a/server/src/api/getRetention.ts b/server/src/api/getRetention.tsnew file mode 100644index 000000000..323ebd2fb--- /dev/null+++ b/server/src/api/getRetention.ts@@ -0,0 +1,170 @@+import { FastifyReply, FastifyRequest } from "fastify";+import clickhouse from "../db/clickhouse/clickhouse.js";+import { getUserHasAccessToSite } from "../lib/auth-utils.js";+import { processResults } from "./utils.js";++// Define the expected shape of a single data row from the query+interface RetentionDataRow {+ cohort_period: string;+ period_difference: number;+ cohort_size: number;+ retained_users: number;+ retention_percentage: number;+}++// Processed data structure for the frontend+interface ProcessedRetentionData {+ cohorts: Record<string, { size: number; percentages: (number | null)[] }>;+ maxPeriods: number;+ mode: "day" | "week";+ range: number;+}++export const getRetention = async (+ req: FastifyRequest<{+ Params: { site: string };+ Querystring: { mode?: string; range?: string };+ }>,+ res: FastifyReply+) => {+ const { site } = req.params;+ const { mode = "week", range = "90" } = req.query; // Default to weekly mode and 90 days range++ // Validate mode parameter+ const retentionMode = mode === "day" ? "day" : "week";++ // Validate range parameter (between 7-365 days)+ const timeRange = Math.min(365, Math.max(7, parseInt(range) || 90));++ const userHasAccessToSite = await getUserHasAccessToSite(req, site);+ if (!userHasAccessToSite) {+ return res.status(403).send({ error: "Forbidden" });+ }++ // Build the appropriate SQL based on the retention mode+ const periodFunction = retentionMode === "day" ? "toDate" : "toStartOfWeek";+ const periodDiffFunc = retentionMode === "day" ? "day" : "week";++ const query = await clickhouse.query({+ query: `+WITH UserFirstPeriod AS (+ SELECT+ user_id,+ ${periodFunction}(min(timestamp)${+ retentionMode === "week" ? ", 1" : ""+ }) AS cohort_period+ FROM pageviews+ WHERE site_id = {siteId:UInt16}+ -- Use the configurable time range+ AND timestamp >= addDays(today(), -{timeRange:UInt16})+ GROUP BY user_id+),+PeriodActivity AS (+ SELECT DISTINCT+ user_id,+ ${periodFunction}(timestamp${+ retentionMode === "week" ? ", 1" : ""+ }) AS activity_period+ FROM pageviews+ WHERE site_id = {siteId:UInt16}+ -- Match the date range filter+ AND timestamp >= addDays(today(), -{timeRange:UInt16})+),+CohortRetention AS (+ SELECT+ ufp.cohort_period,+ dateDiff('${periodDiffFunc}', ufp.cohort_period, pa.activity_period) AS period_difference,+ count(DISTINCT pa.user_id) AS retained_users+ FROM UserFirstPeriod ufp+ JOIN PeriodActivity pa ON ufp.user_id = pa.user_id+ WHERE pa.activity_period >= ufp.cohort_period+ GROUP BY+ ufp.cohort_period,+ period_difference+),+CohortSize AS (+ SELECT+ cohort_period,+ count(DISTINCT user_id) AS total_users+ FROM UserFirstPeriod+ GROUP BY cohort_period+)+SELECT+ cr.cohort_period,+ cr.period_difference,+ cs.total_users AS cohort_size,+ cr.retained_users,+ round(cr.retained_users * 100.0 / cs.total_users, 2) AS retention_percentage+FROM CohortRetention cr+JOIN CohortSize cs ON cr.cohort_period = cs.cohort_period+ORDER BY+ cr.cohort_period DESC,+ cr.period_difference ASC;+ `,+ format: "JSONEachRow",+ query_params: {+ siteId: Number(site),+ timeRange: timeRange,+ },+ });++ const results = await processResults<RetentionDataRow>(query);++ // Process data into a grid-friendly format+ const processedData: ProcessedRetentionData = {+ ...processRetentionData(results),+ mode: retentionMode as "day" | "week",+ range: timeRange,+ };++ return res.send({ data: processedData });+};++// Process raw retention data into a grid-friendly format+function processRetentionData(+ rawData: RetentionDataRow[]+): Omit<ProcessedRetentionData, "mode" | "range"> {+ if (!rawData || rawData.length === 0) {+ return { cohorts: {}, maxPeriods: 0 };+ }++ const processedCohorts: Record<+ string,+ { size: number; percentages: (number | null)[] }+ > = {};+ let maxPeriodDiff = 0;++ rawData.forEach((row) => {+ if (!processedCohorts[row.cohort_period]) {+ processedCohorts[row.cohort_period] = {+ size: row.cohort_size,+ percentages: [],+ };+ }+ // Ensure array is long enough, filling gaps with null+ while (+ processedCohorts[row.cohort_period].percentages.length <=+ row.period_difference+ ) {+ processedCohorts[row.cohort_period].percentages.push(null);+ }+ processedCohorts[row.cohort_period].percentages[row.period_difference] =+ row.retention_percentage;++ if (row.period_difference > maxPeriodDiff) {+ maxPeriodDiff = row.period_difference;+ }+ });++ // Ensure all percentage arrays have the same length for grid alignment+ const finalMaxPeriods = Math.max(maxPeriodDiff, 0);++ Object.values(processedCohorts).forEach((cohort) => {+ // Ensure all cohorts have the same number of periods+ while (cohort.percentages.length <= finalMaxPeriods) {+ cohort.percentages.push(null);+ }+ });++ return { cohorts: processedCohorts, maxPeriods: finalMaxPeriods };+}diff --git a/server/src/index.ts b/server/src/index.tsindex ff2ead02e..54d04fb82 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -33,6 +33,7 @@ import { initializeCronJobs } from "./cron/index.js";import { getUserSubscription } from "./api/user/getUserSubscription.js";import { getUserInfo } from "./api/getUserInfo.js";import { getLiveSessionLocations } from "./api/getLiveSessionLocations.js";+import { getRetention } from "./api/getRetention.js";const __filename = fileURLToPath(import.meta.url);const __dirname = dirname(__filename);@@ -127,6 +128,7 @@ server.get("/live-user-count/:site", getLiveUsercount);server.get("/overview", getOverview);server.get("/overview-bucketed", getOverviewBucketed);server.get("/single-col", getSingleCol);+server.get("/retention/:site", getRetention);server.get("/site-has-data/:site", getSiteHasData);server.get("/sessions", getSessions);server.get("/session/:sessionId", getSession);