{/* Hero — Figma node 802:2027. Full-bleed palm/gradient photo card:
diff --git a/src/server/runtime/blob-storage.server.ts b/src/server/runtime/blob-storage.server.ts
index ab4f4a7af..564da32b3 100644
--- a/src/server/runtime/blob-storage.server.ts
+++ b/src/server/runtime/blob-storage.server.ts
@@ -189,7 +189,7 @@ function getCacheRequest(name: BlobStorageName, key: string) {
return new Request(url)
}
-function getDefaultRuntimeCache() {
+export function getDefaultRuntimeCache() {
if (!isIsolateRuntime() || typeof caches === 'undefined') {
return undefined
}
diff --git a/src/utils/analytics/live-dashboard.ts b/src/utils/analytics/live-dashboard.ts
index 0564407a5..fc5e8671e 100644
--- a/src/utils/analytics/live-dashboard.ts
+++ b/src/utils/analytics/live-dashboard.ts
@@ -109,3 +109,183 @@ export function companyBreakdown(
},
]
}
+
+export type LiveOverview = Awaited<
+ ReturnType
+>
+export type CompanyFacet = 'library' | 'industry' | 'size' | 'stage' | 'status'
+export type CompanyFilters = {
+ search: string
+ library: string[]
+ industry: string[]
+ size: string[]
+ stage: string[]
+ status: string[]
+ minViews: string
+ minActions: string
+ showRecent: boolean
+ identifiedOnly: boolean
+}
+export const emptyCompanyFilters: CompanyFilters = {
+ search: '',
+ library: [],
+ industry: [],
+ size: [],
+ stage: [],
+ status: [],
+ minViews: '',
+ minActions: '',
+ showRecent: false,
+ identifiedOnly: false,
+}
+
+export function employeeLowerBound(value: string | null | undefined) {
+ const match = value?.match(/(\d[\d,]*(?:\.\d+)?)\s*([km])?/i)
+ if (!match) return undefined
+ return (
+ Number(match[1].replaceAll(',', '')) *
+ (match[2]?.toLowerCase() === 'm'
+ ? 1_000_000
+ : match[2]?.toLowerCase() === 'k'
+ ? 1000
+ : 1)
+ )
+}
+export function companySizeBucket(value: string | null | undefined) {
+ const count = employeeLowerBound(value)
+ return count === undefined
+ ? 'Unspecified'
+ : count < 250
+ ? '1-249'
+ : count < 1000
+ ? '250-999'
+ : count < 10_000
+ ? '1K-9,999'
+ : '10K+'
+}
+export function buildCompanyGridRows(
+ data: LiveOverview,
+ history: import('./scarf-history').ScarfHistory | undefined,
+) {
+ const reports = new Map(
+ history?.companies.map((company) => [company.domain, company]),
+ )
+ return data.companies.map((company) => {
+ const report = reports.get(company.id)
+ return {
+ ...company,
+ name:
+ company.company?.name ||
+ report?.name ||
+ company.id ||
+ 'Unmatched traffic',
+ libraries: [...new Set(company.pages.map(pageLibrary))],
+ active: company.activeSessions > 0,
+ status:
+ company.visibleTabs > 0
+ ? 'Active'
+ : company.activeTabs > 0
+ ? 'Background'
+ : 'Left',
+ industry: company.company?.industry || 'Unspecified',
+ sizeBucket: companySizeBucket(company.company?.company_size),
+ employeeMin: employeeLowerBound(company.company?.company_size),
+ history: report,
+ }
+ })
+}
+export type CompanyGridRow = ReturnType[number]
+export function companyFacetValues(row: CompanyGridRow, facet: CompanyFacet) {
+ return facet === 'status'
+ ? [row.status]
+ : facet === 'library'
+ ? row.libraries
+ : facet === 'industry'
+ ? [row.industry]
+ : facet === 'size'
+ ? [row.sizeBucket]
+ : [row.history?.stage || 'Unspecified']
+}
+export function filterCompanyRows(
+ rows: CompanyGridRow[],
+ filters: CompanyFilters,
+ omit?: CompanyFacet,
+) {
+ const facets: CompanyFacet[] = [
+ 'library',
+ 'industry',
+ 'size',
+ 'stage',
+ 'status',
+ ]
+ const search = filters.search.trim().toLowerCase()
+ return rows.filter(
+ (row) =>
+ (filters.showRecent || row.active) &&
+ (!filters.identifiedOnly || Boolean(row.id)) &&
+ (!search ||
+ `${row.name} ${row.id} ${row.industry} ${row.libraries.join(' ')} ${row.pages.join(' ')}`
+ .toLowerCase()
+ .includes(search)) &&
+ (!filters.minViews ||
+ (row.history?.views !== undefined &&
+ row.history.views >= Number(filters.minViews))) &&
+ (!filters.minActions || row.actions >= Number(filters.minActions)) &&
+ facets.every(
+ (facet) =>
+ omit === facet ||
+ !filters[facet].length ||
+ filters[facet].some((value) =>
+ companyFacetValues(row, facet).includes(value),
+ ),
+ ),
+ )
+}
+export function companyFacetCounts(
+ rows: CompanyGridRow[],
+ facet: CompanyFacet,
+ activeOnly = true,
+) {
+ const counts = new Map()
+ for (const row of rows) {
+ if (!row.id || (activeOnly && !row.active)) continue
+ for (const value of companyFacetValues(row, facet))
+ counts.set(value, (counts.get(value) ?? 0) + 1)
+ }
+ return [...counts]
+ .map(([name, value]) => ({ name, value, values: [name] }))
+ .sort((a, b) =>
+ facet === 'size'
+ ? ['1-249', '250-999', '1K-9,999', '10K+', 'Unspecified'].indexOf(
+ a.name,
+ ) -
+ ['1-249', '250-999', '1K-9,999', '10K+', 'Unspecified'].indexOf(
+ b.name,
+ )
+ : b.value - a.value || a.name.localeCompare(b.name),
+ )
+}
+export function companyWidgetItems(
+ items: ReturnType,
+) {
+ return items.length <= 6
+ ? items
+ : [
+ ...items.slice(0, 5),
+ {
+ name: 'Other',
+ value: items.slice(5).reduce((count, item) => count + item.value, 0),
+ values: items.slice(5).flatMap((item) => item.values),
+ },
+ ]
+}
+export function companyGrowth(row: CompanyGridRow) {
+ const current = row.history?.views
+ const previous = row.history?.previousViews
+ return current === undefined || previous === undefined || previous === 0
+ ? undefined
+ : ((current - previous) / previous) * 100
+}
+export function csvSafeText(value: string) {
+ return /^\s*[=+\-@]|^[\t\r\n]/.test(value) ? `'${value}` : value
+}
diff --git a/src/utils/analytics/live.functions.ts b/src/utils/analytics/live.functions.ts
index a3d95eba7..b4ec11e01 100644
--- a/src/utils/analytics/live.functions.ts
+++ b/src/utils/analytics/live.functions.ts
@@ -1,5 +1,9 @@
+import { z } from 'zod'
+import { historyDaysSchema } from './scarf-history'
+import { loadScarfHistory } from './scarf-history.server'
+import { requireAdmin } from '~/utils/roles.server'
import { createServerFn } from '@tanstack/react-start'
-import { listLiveVisitors } from './live.server'
+import { listLiveVisitors, listLiveCompanyOverview } from './live.server'
import { getLiveConfig } from './scarf-lookup.server'
export const getLiveVisitors = createServerFn({ method: 'GET' }).handler(
@@ -9,3 +13,23 @@ export const getLiveVisitors = createServerFn({ method: 'GET' }).handler(
export const getLiveVisitorsEnabled = createServerFn({ method: 'GET' }).handler(
async () => (await getLiveConfig()).enabled,
)
+
+export const getLiveCompanyOverview = createServerFn({ method: 'GET' }).handler(
+ async () => listLiveCompanyOverview(),
+)
+export const getLiveCompanySessions = createServerFn({ method: 'GET' })
+ .validator(
+ z.object({
+ domain: z
+ .string()
+ .max(253)
+ .regex(/^(?:[a-z0-9.-]+)?$/),
+ }),
+ )
+ .handler(async ({ data }) => listLiveVisitors(data.domain))
+export const getScarfCompanyHistory = createServerFn({ method: 'GET' })
+ .validator(z.object({ days: historyDaysSchema }))
+ .handler(async ({ data }) => {
+ await requireAdmin()
+ return loadScarfHistory(data.days)
+ })
diff --git a/src/utils/analytics/live.server.ts b/src/utils/analytics/live.server.ts
index 0bd95c553..879b93999 100644
--- a/src/utils/analytics/live.server.ts
+++ b/src/utils/analytics/live.server.ts
@@ -1,3 +1,4 @@
+import { z } from 'zod'
import { and, desc, eq, gt, lt, sql } from 'drizzle-orm'
import { isIP } from 'node:net'
import { db } from '~/db/client'
@@ -10,6 +11,7 @@ import {
import { getLiveConfig, lookupScarfCompany } from './scarf-lookup.server'
import {
isLivePage,
+ liveCompanySchema,
livePublicPagePattern,
liveForbiddenPagePattern,
liveEventSchema,
@@ -172,7 +174,7 @@ export async function recordLiveEvent(
}
}
-export async function listLiveVisitors() {
+export async function listLiveVisitors(domain?: string) {
await requireAdmin()
const config = await getLiveConfig()
const now = Date.now()
@@ -203,6 +205,9 @@ export async function listLiveVisitors() {
and(
gt(liveTabs.lastSeen, new Date(now - 5 * 60_000)),
gt(liveSessions.createdAt, new Date(now - LIVE_RETENTION_MS)),
+ domain === undefined
+ ? undefined
+ : sql`coalesce(lower(${liveSessions.company}->>'domain'), '') = ${domain}`,
sql`length(${liveTabs.page}) <= 400`,
sql`${liveTabs.page} ~ ${livePublicPagePattern.source}`,
sql`${liveTabs.page} !~ ${liveForbiddenPagePattern.source}`,
@@ -234,3 +239,69 @@ export async function pruneLiveVisitors(now = Date.now()) {
.delete(liveSessions)
.where(lt(liveSessions.createdAt, new Date(now - LIVE_RETENTION_MS)))
}
+
+export const liveCompanyOverviewRowSchema = z.object({
+ id: z.string(),
+ company: liveCompanySchema.nullable(),
+ activeSessions: z.coerce.number().int().nonnegative(),
+ activeTabs: z.coerce.number().int().nonnegative(),
+ visibleTabs: z.coerce.number().int().nonnegative(),
+ recentSessions: z.coerce.number().int().nonnegative(),
+ pages: z.array(z.string()),
+ actions: z.coerce.number().int().nonnegative(),
+ recentViews: z.coerce.number().int().nonnegative(),
+ lastSeen: z.coerce.date(),
+})
+
+export function liveCompanyOverviewSql(now: number) {
+ const activeSince = new Date(now - LIVE_TIMEOUT_MS).toISOString()
+ const recentSince = new Date(now - 5 * 60_000).toISOString()
+ const retainedSince = new Date(now - LIVE_RETENTION_MS).toISOString()
+ return sql`
+ WITH eligible AS (
+ SELECT s.id AS session_id, s.company, t.page, t.visible, t.last_seen, t.activity,
+ (t.left_at IS NULL AND t.last_seen > ${activeSince}::timestamptz) AS active
+ FROM live_tabs t JOIN live_sessions s ON s.id = t.session_id
+ WHERE t.last_seen > ${recentSince}::timestamptz AND s.created_at > ${retainedSince}::timestamptz
+ AND length(t.page) <= 400 AND t.page ~ ${livePublicPagePattern.source}
+ AND t.page !~ ${liveForbiddenPagePattern.source}
+ )
+ SELECT coalesce(lower(e.company->>'domain'), '') AS id,
+ max(e.company::text)::jsonb AS company,
+ count(DISTINCT e.session_id) FILTER (WHERE e.active) AS "activeSessions",
+ count(*) FILTER (WHERE e.active) AS "activeTabs",
+ count(*) FILTER (WHERE e.active AND e.visible) AS "visibleTabs",
+ count(DISTINCT e.session_id) AS "recentSessions",
+ coalesce(jsonb_agg(DISTINCT e.page ORDER BY e.page) FILTER (WHERE e.active), '[]'::jsonb) AS pages,
+ coalesce(sum(a.actions), 0) AS actions, coalesce(sum(a.views), 0) AS "recentViews",
+ max(e.last_seen) AS "lastSeen"
+ FROM eligible e
+ CROSS JOIN LATERAL (
+ SELECT count(*) FILTER (WHERE event->>'action' <> 'page_view') AS actions,
+ count(*) FILTER (WHERE event->>'action' = 'page_view') AS views
+ FROM jsonb_array_elements(e.activity) event
+ WHERE event->>'at' >= ${recentSince}
+ AND length(event->>'page') <= 400 AND event->>'page' ~ ${livePublicPagePattern.source}
+ AND event->>'page' !~ ${liveForbiddenPagePattern.source}
+ ) a
+ GROUP BY coalesce(lower(e.company->>'domain'), '')
+ ORDER BY id
+ `
+}
+
+export async function listLiveCompanyOverview() {
+ await requireAdmin()
+ const config = await getLiveConfig()
+ const now = Date.now()
+ const companies = config.enabled
+ ? z
+ .array(liveCompanyOverviewRowSchema)
+ .parse(await db.execute(liveCompanyOverviewSql(now)))
+ : []
+ return {
+ enabled: config.enabled,
+ lookupConfigured: Boolean(config.key),
+ now: new Date(now).toISOString(),
+ companies,
+ }
+}
diff --git a/src/utils/analytics/scarf-history.server.ts b/src/utils/analytics/scarf-history.server.ts
new file mode 100644
index 000000000..3d18d9919
--- /dev/null
+++ b/src/utils/analytics/scarf-history.server.ts
@@ -0,0 +1,191 @@
+import { libraries } from '~/libraries/libraries'
+import { getHostRuntimeEnv } from '~/server/runtime/host.server'
+import { getDefaultRuntimeCache } from '~/server/runtime/blob-storage.server'
+import { homepageScarfPixel, productScarfPixels } from './scarf-pixels'
+import {
+ companyHistoryFromReports,
+ historyWindow,
+ scarfAggregationRowSchema,
+ type ScarfAggregationRow,
+ scarfHistorySchema,
+ type ScarfHistory,
+} from './scarf-history'
+
+// This is the event-only /site-events route verified in Scarf's package settings.
+const siteTelemetryPackage = 'b942b596-f90d-4072-a763-86fb5fbe5852'
+const sitePixels = [
+ ...new Set([
+ homepageScarfPixel,
+ ...productScarfPixels.map((pixel) => pixel.id),
+ ...libraries.flatMap((library) =>
+ library.scarfId ? [library.scarfId] : [],
+ ),
+ ]),
+]
+
+export function scarfReportUrl(
+ start: string,
+ end: string,
+ source: 'views' | 'events',
+) {
+ const url = new URL(
+ 'https://api.scarf.sh/v3/insights/TanStack/aggregations/export',
+ )
+ for (const [key, value] of Object.entries({
+ start_date: start,
+ end_date: end,
+ rollup: 'total',
+ breakdown: 'by-company',
+ format: 'ndjson',
+ group_by_artifact: 'false',
+ group_by_artifact_type: 'false',
+ include_low_confidence: 'false',
+ }))
+ url.searchParams.set(key, value)
+ url.searchParams.set(
+ 'package_id',
+ source === 'events' ? siteTelemetryPackage : 'none',
+ )
+ if (source === 'views')
+ for (const id of sitePixels)
+ url.searchParams.append('tracking_pixel_id', id)
+ else url.searchParams.set('tracking_pixel_id', 'none')
+ return url
+}
+
+class ScarfReportError extends Error {
+ constructor(readonly detail: string) {
+ super(detail)
+ }
+}
+
+async function report(
+ start: string,
+ end: string,
+ source: 'views' | 'events',
+ token: string,
+) {
+ const response = await fetch(scarfReportUrl(start, end, source), {
+ headers: {
+ Authorization: `Bearer ${token}`,
+ Accept: 'application/x-ndjson',
+ },
+ signal: AbortSignal.timeout(30_000),
+ })
+ if (!response.ok) {
+ await response.body?.cancel()
+ throw new ScarfReportError(`HTTP ${response.status}`)
+ }
+ const rows: ScarfAggregationRow[] = []
+ const reader = response.body?.getReader()
+ if (!reader) throw new ScarfReportError('empty response')
+ const decoder = new TextDecoder()
+ let buffer = ''
+ let bytes = 0
+ const addRow = (line: string) => {
+ if (!line.trim()) return
+ if (rows.length >= 50_000)
+ throw new ScarfReportError('export too large; choose a shorter window')
+ rows.push(scarfAggregationRowSchema.parse(JSON.parse(line)))
+ }
+ try {
+ while (true) {
+ const chunk = await reader.read()
+ if (chunk.done) break
+ bytes += chunk.value.byteLength
+ if (bytes > 100 * 1024 * 1024)
+ throw new ScarfReportError('export too large; choose a shorter window')
+ buffer += decoder.decode(chunk.value, { stream: true })
+ let end = buffer.indexOf('\n')
+ while (end !== -1) {
+ addRow(buffer.slice(0, end))
+ buffer = buffer.slice(end + 1)
+ end = buffer.indexOf('\n')
+ }
+ if (buffer.length > 64_000)
+ throw new ScarfReportError('invalid export row')
+ }
+ buffer += decoder.decode()
+ addRow(buffer)
+ return rows
+ } catch (error) {
+ await reader.cancel()
+ throw error
+ } finally {
+ reader.releaseLock()
+ }
+}
+
+export async function loadScarfHistory(
+ days: ScarfHistory['days'],
+): Promise {
+ const window = historyWindow(days)
+ const base = {
+ days,
+ start: window.start,
+ end: window.end,
+ fetchedAt: new Date().toISOString(),
+ companies: [],
+ issues: [],
+ }
+ const host = await getHostRuntimeEnv()
+ const token =
+ host?.ANALYTICS_SCARF_API_TOKEN ?? process.env.ANALYTICS_SCARF_API_TOKEN
+ if (typeof token !== 'string' || !token)
+ return { ...base, status: 'unconfigured' }
+ const cache = getDefaultRuntimeCache()
+ const cacheKey = new Request(
+ `https://scarf-reporting.tanstack.internal/site-history/v1/${days}/${window.end}`,
+ )
+ const cached = await cache?.match(cacheKey).catch(() => undefined)
+ if (cached) {
+ const parsed = scarfHistorySchema.safeParse(await cached.json())
+ if (parsed.success) return parsed.data
+ }
+ const results = await Promise.allSettled([
+ report(window.start, window.end, 'views', token),
+ report(window.previousStart, window.start, 'views', token),
+ report(window.start, window.end, 'events', token),
+ ])
+ const data = results.map((result) =>
+ result.status === 'fulfilled' ? result.value : undefined,
+ )
+ const issues = results.flatMap((result, index) =>
+ result.status === 'fulfilled'
+ ? []
+ : [
+ `${['Site pixel views', 'Previous period', 'Site events'][index]} unavailable${result.reason instanceof ScarfReportError ? ` (${result.reason.detail})` : ' (unexpected response or timeout)'}. Check Scarf reporting access or try again later.`,
+ ],
+ )
+ let companies: ScarfHistory['companies'] = []
+ try {
+ companies = companyHistoryFromReports(data[0], data[1], data[2])
+ } catch {
+ issues.push(
+ 'Scarf returned inconsistent company totals. History is unavailable.',
+ )
+ }
+ const history: ScarfHistory = {
+ ...base,
+ companies,
+ issues,
+ status: issues.length
+ ? companies.length
+ ? 'partial'
+ : 'unavailable'
+ : 'ready',
+ }
+ // Cache aggregate company metrics only, never credentials or source-level data.
+ await cache
+ ?.put(
+ cacheKey,
+ new Response(JSON.stringify(history), {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'Cache-Control': `max-age=${history.status === 'ready' ? 900 : 60}`,
+ },
+ }),
+ )
+ .catch(() => undefined)
+ return history
+}
diff --git a/src/utils/analytics/scarf-history.ts b/src/utils/analytics/scarf-history.ts
new file mode 100644
index 000000000..eb3ebdb23
--- /dev/null
+++ b/src/utils/analytics/scarf-history.ts
@@ -0,0 +1,96 @@
+import { z } from 'zod'
+
+export const historyDaysSchema = z.union([
+ z.literal(7),
+ z.literal(30),
+ z.literal(90),
+ z.literal(365),
+])
+export const scarfCompanyHistorySchema = z.object({
+ domain: z.string(),
+ name: z.string().nullable(),
+ views: z.number().nonnegative().optional(),
+ previousViews: z.number().nonnegative().optional(),
+ siteEvents: z.number().nonnegative().optional(),
+ origins: z.number().nonnegative().optional(),
+ endpoints: z.number().nonnegative().optional(),
+ stage: z.string().nullable(),
+ lastSeen: z.string().nullable(),
+})
+export type ScarfCompanyHistory = z.infer
+export const scarfHistorySchema = z.object({
+ status: z.enum(['ready', 'partial', 'unconfigured', 'unavailable']),
+ days: historyDaysSchema,
+ start: z.string(),
+ end: z.string(),
+ fetchedAt: z.string(),
+ companies: z.array(scarfCompanyHistorySchema),
+ issues: z.array(z.string()),
+})
+export type ScarfHistory = z.infer
+export function historyWindow(days: number, now = new Date()) {
+ const end = new Date(
+ Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1),
+ )
+ const start = new Date(end.getTime() - days * 86_400_000)
+ const previousStart = new Date(start.getTime() - days * 86_400_000)
+ return {
+ start: start.toISOString().slice(0, 10),
+ end: end.toISOString().slice(0, 10),
+ previousStart: previousStart.toISOString().slice(0, 10),
+ }
+}
+export const scarfAggregationRowSchema = z.object({
+ company_domain: z.string().nullable(),
+ company_name: z.string().nullable(),
+ total: z.number().int().nonnegative(),
+ unique_origins: z.number().int().nonnegative(),
+ unique_endpoints: z.number().int().nonnegative(),
+ company_funnel_stage: z.string().nullable(),
+ last_seen: z.string(),
+})
+export type ScarfAggregationRow = z.infer
+export const scarfAggregationSchema = z.object({
+ data: z.array(scarfAggregationRowSchema).max(50_000),
+})
+
+export function companyHistoryFromReports(
+ views: z.infer['data'] | undefined,
+ previous: z.infer['data'] | undefined,
+ events: z.infer['data'] | undefined,
+) {
+ const companies = new Map()
+ const reports: {
+ kind: 'views' | 'previousViews' | 'siteEvents'
+ rows: typeof views
+ }[] = [
+ { kind: 'views', rows: views },
+ { kind: 'previousViews', rows: previous },
+ { kind: 'siteEvents', rows: events },
+ ]
+ for (const { kind, rows } of reports) {
+ const seen = new Set()
+ for (const row of rows ?? []) {
+ const domain = row.company_domain?.trim().toLowerCase()
+ if (!domain) continue
+ if (seen.has(domain))
+ throw new Error('Scarf returned duplicate company totals')
+ seen.add(domain)
+ const company = companies.get(domain) ?? {
+ domain,
+ name: row.company_name,
+ stage: null,
+ lastSeen: null,
+ }
+ company[kind] = row.total
+ if (kind === 'views') {
+ company.origins = row.unique_origins
+ company.endpoints = row.unique_endpoints
+ company.stage = row.company_funnel_stage
+ company.lastSeen = row.last_seen
+ }
+ companies.set(domain, company)
+ }
+ }
+ return [...companies.values()]
+}
diff --git a/src/utils/analytics/scarf-pixels.ts b/src/utils/analytics/scarf-pixels.ts
new file mode 100644
index 000000000..74580fce3
--- /dev/null
+++ b/src/utils/analytics/scarf-pixels.ts
@@ -0,0 +1,7 @@
+export const homepageScarfPixel = 'b7a8c111-2305-4d95-a02a-d84c5bfb82ae'
+export const productScarfPixels = [
+ { path: '/application-starter', id: 'ed471ec3-aa08-430f-8481-258b3a1f94dc' },
+ { path: '/builder', id: 'aa4dcee9-86a2-49b4-9981-40c97cc1f55b' },
+ { path: '/stats/npm', id: 'e729f879-e127-48e1-be19-c68f6786c9e8' },
+ { path: '/intent/registry', id: '811c34af-38bd-4f06-9762-3f58dea0650a' },
+]
diff --git a/tests/live-company-tools.test.ts b/tests/live-company-tools.test.ts
new file mode 100644
index 000000000..29df4b3e8
--- /dev/null
+++ b/tests/live-company-tools.test.ts
@@ -0,0 +1,256 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+ buildCompanyGridRows,
+ filterCompanyRows,
+ emptyCompanyFilters,
+ employeeLowerBound,
+ companyFacetCounts,
+ companyWidgetItems,
+ companyGrowth,
+ csvSafeText,
+ type LiveOverview,
+} from '../src/utils/analytics/live-dashboard.ts'
+import {
+ companyHistoryFromReports,
+ historyWindow,
+ type ScarfHistory,
+} from '../src/utils/analytics/scarf-history.ts'
+
+const data: LiveOverview = {
+ enabled: true,
+ lookupConfigured: true,
+ now: '2026-10-29T17:00:00Z',
+ companies: [
+ {
+ id: 'acme.example',
+ company: {
+ name: 'Acme',
+ domain: 'acme.example',
+ industry: 'Software',
+ company_size: '1,000 - 4,999',
+ linkedin_url: null,
+ },
+ activeSessions: 3,
+ activeTabs: 5,
+ visibleTabs: 2,
+ recentSessions: 4,
+ pages: ['/query/latest', '/router/latest'],
+ actions: 9,
+ recentViews: 12,
+ lastSeen: new Date('2026-10-29T17:00:00Z'),
+ },
+ {
+ id: 'other.example',
+ company: {
+ name: 'Other',
+ domain: 'other.example',
+ industry: 'Retail',
+ company_size: '100K+',
+ linkedin_url: null,
+ },
+ activeSessions: 1,
+ activeTabs: 1,
+ visibleTabs: 1,
+ recentSessions: 1,
+ pages: ['/query/latest'],
+ actions: 1,
+ recentViews: 2,
+ lastSeen: new Date('2026-10-29T17:00:00Z'),
+ },
+ {
+ id: '',
+ company: null,
+ activeSessions: 10,
+ activeTabs: 10,
+ visibleTabs: 2,
+ recentSessions: 10,
+ pages: ['/form/latest'],
+ actions: 100,
+ recentViews: 100,
+ lastSeen: new Date('2026-10-29T17:00:00Z'),
+ },
+ ],
+}
+const history: ScarfHistory = {
+ status: 'ready',
+ days: 30,
+ start: '2026-09-30',
+ end: '2026-10-30',
+ fetchedAt: data.now,
+ issues: [],
+ companies: [
+ {
+ domain: 'acme.example',
+ name: 'Acme',
+ views: 500,
+ previousViews: 250,
+ siteEvents: 2000,
+ origins: 12,
+ endpoints: 18,
+ stage: 'ongoing-usage',
+ lastSeen: data.now,
+ },
+ ],
+}
+
+test('facets use OR within a dimension and AND across dimensions', () => {
+ const rows = buildCompanyGridRows(data, history)
+ assert.deepEqual(
+ filterCompanyRows(rows, {
+ ...emptyCompanyFilters,
+ library: ['Query', 'Form'],
+ industry: ['Software'],
+ }).map((row) => row.id),
+ ['acme.example'],
+ )
+ assert.deepEqual(
+ filterCompanyRows(rows, {
+ ...emptyCompanyFilters,
+ minViews: '100',
+ minActions: '5',
+ }).map((row) => row.id),
+ ['acme.example'],
+ )
+ assert.equal(
+ filterCompanyRows(rows, { ...emptyCompanyFilters, identifiedOnly: true })
+ .length,
+ 2,
+ )
+})
+test('facet counts exclude unmatched traffic and count each company once per library', () => {
+ const rows = buildCompanyGridRows(data, history)
+ assert.deepEqual(
+ companyFacetCounts(rows, 'library').map((item) => [item.name, item.value]),
+ [
+ ['Query', 2],
+ ['Router', 1],
+ ],
+ )
+ assert.equal(
+ companyFacetCounts(
+ filterCompanyRows(
+ rows,
+ { ...emptyCompanyFilters, industry: ['Software'] },
+ 'industry',
+ ),
+ 'industry',
+ ).length,
+ 2,
+ )
+})
+test('Other retains the actual facet values so a click can filter the grouped categories', () => {
+ const items = Array.from({ length: 8 }, (_, index) => ({
+ name: `Industry ${index}`,
+ value: 8 - index,
+ values: [`Industry ${index}`],
+ }))
+ const other = companyWidgetItems(items).at(-1)
+ assert.deepEqual(other, {
+ name: 'Other',
+ value: 6,
+ values: ['Industry 5', 'Industry 6', 'Industry 7'],
+ })
+})
+test('size sorting handles provider range variants, K suffixes, and unknown values', () => {
+ assert.equal(employeeLowerBound('1,000 - 4,999'), 1000)
+ assert.equal(employeeLowerBound('5K-10K'), 5000)
+ assert.equal(employeeLowerBound('100K+'), 100000)
+ assert.equal(employeeLowerBound(null), undefined)
+})
+test('missing historical metrics stay unknown, zero stays zero, and change uses equal windows', () => {
+ const rows = buildCompanyGridRows(data, history)
+ assert.equal(companyGrowth(rows[0]), 100)
+ assert.equal(rows[1].history, undefined)
+ assert.equal(companyGrowth(rows[1]), undefined)
+ assert.deepEqual(historyWindow(30, new Date('2026-10-29T17:00:00Z')), {
+ start: '2026-09-30',
+ end: '2026-10-30',
+ previousStart: '2026-08-31',
+ })
+})
+test('report joins keep site pixel views separate from telemetry events and do not invent missing values', () => {
+ const report = {
+ company_domain: 'ACME.EXAMPLE',
+ company_name: 'Acme',
+ total: 12,
+ unique_origins: 2,
+ unique_endpoints: 3,
+ company_funnel_stage: null,
+ last_seen: data.now,
+ }
+ const rows = companyHistoryFromReports([report], undefined, [
+ { ...report, total: 90 },
+ ])
+ assert.equal(rows[0].views, 12)
+ assert.equal(rows[0].siteEvents, 90)
+ assert.equal(rows[0].previousViews, undefined)
+ assert.throws(
+ () => companyHistoryFromReports([report, report], undefined, undefined),
+ /duplicate/,
+ )
+})
+test('CSV text neutralizes spreadsheet formulas while preserving numeric values at their source', () => {
+ assert.equal(csvSafeText('=SUM(1,2)'), "'=SUM(1,2)")
+ assert.equal(csvSafeText(' +1'), "' +1")
+ assert.equal(csvSafeText('Acme'), 'Acme')
+})
+
+test('company status prefers any visible tab and filters background companies without counting them twice', () => {
+ const rows = buildCompanyGridRows(
+ {
+ ...data,
+ companies: data.companies.map((company, index) =>
+ index === 1
+ ? { ...company, visibleTabs: 0 }
+ : index === 2
+ ? { ...company, activeTabs: 0, activeSessions: 0, visibleTabs: 0 }
+ : company,
+ ),
+ },
+ history,
+ )
+ assert.deepEqual(
+ rows.map((row) => row.status),
+ ['Active', 'Background', 'Left'],
+ )
+ assert.deepEqual(
+ companyFacetCounts(rows, 'status').map(({ name, value }) => ({
+ name,
+ value,
+ })),
+ [
+ { name: 'Active', value: 1 },
+ { name: 'Background', value: 1 },
+ ],
+ )
+ assert.deepEqual(
+ filterCompanyRows(rows, {
+ ...emptyCompanyFilters,
+ status: ['Background'],
+ library: ['Query'],
+ industry: ['Retail'],
+ }).map((row) => row.id),
+ ['other.example'],
+ )
+ assert.deepEqual(
+ filterCompanyRows(rows, {
+ ...emptyCompanyFilters,
+ status: ['Active', 'Background'],
+ }).map((row) => row.id),
+ ['acme.example', 'other.example'],
+ )
+ assert.equal(
+ filterCompanyRows(rows, { ...emptyCompanyFilters, status: ['Left'] })
+ .length,
+ 0,
+ )
+ assert.equal(
+ filterCompanyRows(rows, {
+ ...emptyCompanyFilters,
+ status: ['Left'],
+ showRecent: true,
+ }).length,
+ 1,
+ )
+})
diff --git a/tests/scarf-history.test.ts b/tests/scarf-history.test.ts
new file mode 100644
index 000000000..617218222
--- /dev/null
+++ b/tests/scarf-history.test.ts
@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import {
+ loadScarfHistory,
+ scarfReportUrl,
+} from '../src/utils/analytics/scarf-history.server.ts'
+
+test('site reports select only the website pixels or its dedicated telemetry package', () => {
+ const views = scarfReportUrl('2026-09-30', '2026-10-30', 'views')
+ assert.equal(views.pathname, '/v3/insights/TanStack/aggregations/export')
+ assert.equal(views.searchParams.get('package_id'), 'none')
+ assert.ok(
+ views.searchParams
+ .getAll('tracking_pixel_id')
+ .includes('b7a8c111-2305-4d95-a02a-d84c5bfb82ae'),
+ )
+ assert.equal(views.searchParams.get('group_by_artifact'), 'false')
+ assert.equal(views.searchParams.get('group_by_artifact_type'), 'false')
+ const events = scarfReportUrl('2026-09-30', '2026-10-30', 'events')
+ assert.equal(
+ events.searchParams.get('package_id'),
+ 'b942b596-f90d-4072-a763-86fb5fbe5852',
+ )
+ assert.equal(events.searchParams.get('tracking_pixel_id'), 'none')
+})
+test('unavailable reporting access does not pretend the company has zero history', async (t) => {
+ const previous = process.env.ANALYTICS_SCARF_API_TOKEN
+ process.env.ANALYTICS_SCARF_API_TOKEN = 'test-token'
+ t.after(() => {
+ if (previous === undefined) delete process.env.ANALYTICS_SCARF_API_TOKEN
+ else process.env.ANALYTICS_SCARF_API_TOKEN = previous
+ })
+ t.mock.method(
+ globalThis,
+ 'fetch',
+ async () => new Response(null, { status: 403 }),
+ )
+ const result = await loadScarfHistory(30)
+ assert.equal(result.status, 'unavailable')
+ assert.deepEqual(result.companies, [])
+ assert.equal(result.issues.length, 3)
+})
+
+test('streamed history keeps aggregate views separate and strips source identifiers', async (t) => {
+ const previous = process.env.ANALYTICS_SCARF_API_TOKEN
+ process.env.ANALYTICS_SCARF_API_TOKEN = 'test-token'
+ t.after(() => {
+ if (previous === undefined) delete process.env.ANALYTICS_SCARF_API_TOKEN
+ else process.env.ANALYTICS_SCARF_API_TOKEN = previous
+ })
+ const { historyWindow } =
+ await import('../src/utils/analytics/scarf-history.ts')
+ const window = historyWindow(30)
+ t.mock.method(
+ globalThis,
+ 'fetch',
+ async (input: RequestInfo | URL, init?: RequestInit) => {
+ const url = new URL(input instanceof Request ? input.url : String(input))
+ assert.equal(
+ new Headers(init?.headers).get('Authorization'),
+ 'Bearer test-token',
+ )
+ assert.equal(url.searchParams.get('format'), 'ndjson')
+ const total =
+ url.searchParams.get('package_id') !== 'none'
+ ? 90
+ : url.searchParams.get('start_date') === window.start
+ ? 12
+ : 6
+ const row = {
+ company_domain: 'example.com',
+ company_name: 'Example',
+ total,
+ unique_origins: 2,
+ unique_endpoints: 3,
+ company_funnel_stage: 'ongoing-usage',
+ last_seen: new Date().toISOString(),
+ origin_id: 'source-id-must-not-be-returned',
+ }
+ return new Response(JSON.stringify(row), {
+ headers: { 'Content-Type': 'application/x-ndjson' },
+ })
+ },
+ )
+ const result = await loadScarfHistory(30)
+ assert.equal(result.status, 'ready')
+ assert.equal(result.companies[0].views, 12)
+ assert.equal(result.companies[0].previousViews, 6)
+ assert.equal(result.companies[0].siteEvents, 90)
+ assert.equal(
+ JSON.stringify(result).includes('source-id-must-not-be-returned'),
+ false,
+ )
+ assert.equal(JSON.stringify(result).includes('test-token'), false)
+})