Skip to content

[codex] Add analytics overview filters #1496

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mantrakp04 wants to merge 7 commits into
base: dev
Choose a base branch
from
Open

[codex] Add analytics overview filters #1496

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ba947ec
Add analytics overview filters
mantrakp04 May 27, 2026
f087ab9
Merge branch 'dev' into codex/analytics-overview-filters
mantrakp04 May 27, 2026
3e99ccc
Export tooltip portal
mantrakp04 May 27, 2026
3f03d94
Refactor globe controls and enhance tooltip descriptions
mantrakp04 May 27, 2026
174f3a4
Update dependencies and enhance chart animations
mantrakp04 May 27, 2026
322c785
Refactor user-agent classification and enhance analytics overview fil…
mantrakp04 May 27, 2026
a1fff45
Merge branch 'dev' into codex/analytics-overview-filters
mantrakp04 May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 31 additions & 13 deletions apps/backend/src/app/api/latest/analytics/events/batch/route.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,7 @@ export const POST = createSmartRouteHandler({
inserted: yupNumber().defined(),
}).defined(),
}),
async handler({ auth, body }) {
async handler({ auth, body }, fullReq) {
if (!auth.tenancy.config.apps.installed["analytics"]?.enabled) {
throw new KnownErrors.AnalyticsNotEnabled();
}
Expand Down Expand Up @@ -134,18 +134,36 @@ export const POST = createSmartRouteHandler({

const clickhouseClient = getClickhouseAdminClient();

const rows = body.events.map((event) => ({
event_type: event.event_type,
event_at: new Date(event.event_at_ms),
data: stripLoneSurrogates(event.data),
project_id: projectId,
branch_id: branchId,
user_id: userId,
team_id: null,
refresh_token_id: refreshTokenId,
session_replay_id: recentSession?.id ?? null,
session_replay_segment_id: body.session_replay_segment_id,
}));
// Server-side fallback: stamp the request's User-Agent into the event data
// blob when the client didn't already include one. This lets the analytics
// overview aggregate device/browser/OS breakdowns even for older clients.
const headerUserAgent = (() => {
const raw = fullReq.headers["user-agent"];
if (Array.isArray(raw)) return raw[0] ?? null;
return (raw as string | undefined) ?? null;
})();

const rows = body.events.map((event) => {
const baseData = (typeof event.data === "object" && !Array.isArray(event.data))
Copy link
Copy Markdown

@cubic-dev-ai cubic-dev-ai Bot May 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: When event.data is null, typeof null === "object" is true in JavaScript, so baseData will be null. The subsequent baseData.user_agent access will throw a TypeError. Add a null check to the condition.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At apps/backend/src/app/api/latest/analytics/events/batch/route.tsx, line 147:

<comment>When `event.data` is `null`, `typeof null === "object"` is `true` in JavaScript, so `baseData` will be `null`. The subsequent `baseData.user_agent` access will throw a `TypeError`. Add a null check to the condition.</comment>

<file context>
@@ -134,18 +134,36 @@ export const POST = createSmartRouteHandler({
+    })();
+
+    const rows = body.events.map((event) => {
+      const baseData = (typeof event.data === "object" && !Array.isArray(event.data))
+        ? (event.data as Record<string, unknown>)
+        : {};
</file context>
Suggested change
const baseData = (typeof event.data === "object" && !Array.isArray(event.data))
const baseData = (event.data != null && typeof event.data === "object" && !Array.isArray(event.data))
Fix with Cubic

? (event.data as Record<string, unknown>)
: {};
Comment on lines +137 to +149
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

FILE="apps/backend/src/app/api/latest/analytics/events/batch/route.tsx"

# Show the relevant region with line numbers
sed -n '110,190p' "$FILE"

# Also show the surrounding validation/error handling in the handler for context
rg -n "throw new|StatusError|StackAssertionError|BadRequest|analytics event data|Invalid" "$FILE" || true

# Show imports to confirm which error types/utilities are available in this file
sed -n '1,120p' "$FILE"

Repository: hexclave/stack-auth

Length of output: 8501

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Find where createSmartRouteHandler is implemented
rg -n "function createSmartRouteHandler|createSmartRouteHandler\s*=" -S "apps/backend/src" || true

# If found, display relevant error-handling sections
# (limit output by focusing on common catch blocks)
FILE=$(rg -l "createSmartRouteHandler" apps/backend/src | head -n 20 | tail -n 1)
echo "Last matching file: $FILE"
if [ -f "$FILE" ]; then
  rg -n "catch\s*\(|StatusError|StackAssertionError|BadRequest|500" "$FILE" || true
  sed -n '1,200p' "$FILE" | cat
fi

# Also scan for this handler file references to StatusError vs unhandled errors
rg -n "StackAssertionError" apps/backend/src/app/api/latest/analytics/events/batch/route.tsx || true

Repository: hexclave/stack-auth

Length of output: 6250

🏁 Script executed:

#!/bin/bash
set -euo pipefail

ROUTE="apps/backend/src/app/api/latest/analytics/events/batch/route.tsx"
SMART="apps/backend/src/route-handlers/smart-route-handler.tsx"

echo "=== route.tsx (analytics batch) lines 120-190 ==="
sed -n '120,190p' "$ROUTE"

echo
echo "=== smart-route-handler.tsx: show error handling region ==="
# Print around likely catch blocks / error serialization
rg -n "catch\s*\(|StatusError|StackAssertionError|HexclaveAssertionError|serialize|toResponse|response" "$SMART" | head -n 50
# Also dump a window around the first substantial match near line ~216
sed -n '180,320p' "$SMART"

Repository: hexclave/stack-auth

Length of output: 10436

🏁 Script executed:

#!/bin/bash
set -euo pipefail

SMART="apps/backend/src/route-handlers/smart-route-handler.tsx"

echo "=== smart-route-handler.tsx: catchError + handleApiRequest region ==="
# show from around class InternalServerError through catchError and createResponse usage
sed -n '1,120p' "$SMART"

echo
echo "=== smart-route-handler.tsx: handleApiRequest/catch path ==="
# locate handleApiRequest implementation region if present in this file
rg -n "function handleApiRequest|handleApiRequest\s*\(" "$SMART"
# print around last match
MATCH_LINE=$(rg -n "handleApiRequest\s*\(" "$SMART" | head -n 1 | cut -d: -f1 || true)
if [ -n "${MATCH_LINE:-}" ]; then
  START=$((MATCH_LINE-60))
  END=$((MATCH_LINE+120))
  sed -n "${START},${END}p" "$SMART"
fi

echo
echo "=== smart-route-handler.tsx: createResponse / errorToNiceString usage ==="
rg -n "createResponse|errorToNiceString|toResponse|InternalServerError|captureError|catchError" "$SMART"
sed -n '120,220p' "$SMART"

Repository: hexclave/stack-auth

Length of output: 20725

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the remainder of the analytics batch route for any other assumptions about event.data
ROUTE="apps/backend/src/app/api/latest/analytics/events/batch/route.tsx"
echo "=== Full event mapping usages in ${ROUTE} ==="
rg -n "event\.data|user_agent|mergedData|baseData" "$ROUTE"

echo
echo "=== Event schema section (request validation) ==="
# print around where yupObject defines events/data
rg -n "events:|yupMixed|event_type|event_at_ms|data:" "$ROUTE"
sed -n '60,120p' "$ROUTE"

echo
echo "=== Search other analytics endpoints for similar event.data handling ==="
# locate other analytics event batch routes
rg -n "analytics/events/batch|analytics_internal\.events|event_type:|yupMixed\(\)\.defined\(\)" apps/backend/src/app/api/latest/analytics -S || true

# If there are other routes with similar map/normalization, inspect them
MATCHES=$(rg -l "analytics_internal\.events|yupMixed\(\)\.defined\(\)" apps/backend/src/app/api/latest/analytics -S || true)
echo
echo "Matched files:"
echo "$MATCHES" | sed 's/^/ - /'
if [ -n "${MATCHES:-}" ]; then
  for f in $(echo "$MATCHES" | head -n 5); do
    echo
    echo "---- ${f} (context around normalization) ----"
    rg -n "map\\(\\(event\\)|event\\.data|user_agent|mergedData|baseData|stripLoneSurrogates" "$f" || true
    sed -n '1,220p' "$f" | head -n 60 || true
  done
fi

Repository: hexclave/stack-auth

Length of output: 7351

Remove as casts and fail fast on non-object event.data in analytics batch ingestion

  • headerUserAgent uses (raw as string | undefined), and event.data is cast to Record<string, unknown> via as and then silently coerced to {} when it’s not an object. This hides malformed client payloads (the request schema uses yupMixed() for data) and can skew analytics.
  • Replace both casts with type guards and return StatusError.BadRequest when event.data isn’t a plain object.
Proposed fix 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
     const headerUserAgent = (() => {
       const raw = fullReq.headers["user-agent"];
       if (Array.isArray(raw)) return raw[0] ?? null;
-      return (raw as string | undefined) ?? null;
+      return typeof raw === "string" ? raw : null;
     })();
 
     const rows = body.events.map((event) => {
-      const baseData = (typeof event.data === "object" && !Array.isArray(event.data))
-        ? (event.data as Record<string, unknown>)
-        : {};
+      if (!isRecord(event.data)) {
+        throw new StatusError(StatusError.BadRequest, "Invalid analytics event data payload");
+      }
+      const baseData = event.data;
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/backend/src/app/api/latest/analytics/events/batch/route.tsx` around
lines 137 - 149, The code currently uses unsafe `as` casts in headerUserAgent
and when coercing event.data; replace those casts with proper type guards:
implement headerUserAgent by checking if fullReq.headers["user-agent"] is an
array (take index 0 if so) or a string (use it directly) and otherwise treat as
null, and validate each event's data with a plain-object guard (typeof
event.data === "object" && event.data !== null && !Array.isArray(event.data));
if an event.data fails this check, short-circuit the request and return
StatusError.BadRequest (from StatusError) instead of silently coercing to {} —
update the rows generation (the variable rows and the event handling logic) to
assume a validated plain object after this guard.

const existingUa = baseData.user_agent;
const mergedData = (existingUa == null || existingUa === "")
? { ...baseData, user_agent: headerUserAgent }
: baseData;
return ({
event_type: event.event_type,
event_at: new Date(event.event_at_ms),
data: stripLoneSurrogates(mergedData),
project_id: projectId,
branch_id: branchId,
user_id: userId,
team_id: null,
refresh_token_id: refreshTokenId,
session_replay_id: recentSession?.id ?? null,
session_replay_segment_id: body.session_replay_segment_id,
});
});

await clickhouseClient.insert({
table: "analytics_internal.events",
Expand Down
45 changes: 44 additions & 1 deletion apps/backend/src/app/api/latest/internal/metrics/route.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
import { describe, expect, it } from "vitest";
import { getMetricsWindowBounds, isMetricsRevenueInvoiceStatus } from "./route";
import {
buildAnalyticsOverviewUserAgentFilterFragmentsForTest,
getMetricsWindowBounds,
isMetricsRevenueInvoiceStatus,
normalizeAnalyticsOverviewFilters,
} from "./route";

describe("internal metrics helpers", () => {
it("only counts paid and succeeded invoices as revenue", () => {
Expand All @@ -17,4 +22,42 @@ describe("internal metrics helpers", () => {
expect(since.toISOString()).toBe("2026-03-14T00:00:00.000Z");
expect(untilExclusive.toISOString()).toBe("2026-04-14T00:00:00.000Z");
});

it("normalizes analytics overview filters before adding them to ClickHouse params", () => {
expect(normalizeAnalyticsOverviewFilters({
country_code: " us ",
referrer: " https://example.com ",
browser: "",
os: " macOS ",
device: " Desktop ",
})).toMatchInlineSnapshot(`
{
"browser": undefined,
"country_code": "US",
"device": "Desktop",
"os": "macOS",
"referrer": "https://example.com",
}
`);
});

it("builds deterministic user-agent filter fragments without a raw user-agent allowlist", () => {
expect(buildAnalyticsOverviewUserAgentFilterFragmentsForTest({
browser: "Chrome",
os: "macOS",
device: "Desktop",
})).toMatchInlineSnapshot(`
{
"hasBrowserFilter": true,
"hasDeviceFilter": true,
"hasOsFilter": true,
"params": {
"browserFilter": "Chrome",
"deviceFilter": "Desktop",
"osFilter": "macOS",
},
"usesRawUserAgentAllowlist": false,
}
`);
});
});
Loading
Loading