πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
Add analytics query hooks and refactor existing hooks for improved data fetching
Bill Yang62abed1e1bcb
diff --git a/CONTEXT.md b/CONTEXT.mdnew file mode 100644index 000000000..995d160f4--- /dev/null+++ b/CONTEXT.md@@ -0,0 +1,13 @@+# Rybbit++Domain language for Rybbit's analytics product, documentation, and public tools.++## Language++**Public Website Target**:+A caller-supplied HTTP or HTTPS location that resolves only to public network addresses and can be inspected by Rybbit's free analytics tools.+_Avoid_: External URL, safe URL, validated URL++**Website Inspection**:+An operation that evaluates a Public Website Target using bounded direct acquisition or a remote evaluator.+_Avoid_: URL scan, website fetchdiff --git a/client/CLAUDE.md b/client/CLAUDE.mdindex b68f4c84d..6d396eb9e 100644--- a/client/CLAUDE.md+++ b/client/CLAUDE.md@@ -94,7 +94,9 @@ export function useGetSomething(siteId?: string) {- Converts array params to JSON strings- Extracts and throws backend errors from `response.data.error`-**`buildApiParams(time, timezone, filters?)`** returns `CommonApiParams` with `.toQueryParams()` / `.toBucketedQueryParams()` helpers for converting the time store state into API-ready parameters.+**`buildApiParams(time, { filters? })`** (`api/utils.ts`) returns a plain `CommonApiParams` object; the free functions `toQueryParams` / `toBucketedQueryParams` / `toMetricQueryParams` (`api/analytics/endpoints/types.ts`) convert it to snake_case wire params inside endpoint functions.++**`useAnalyticsQuery` / `useAnalyticsInfiniteQuery`** (`api/analytics/useAnalyticsQuery.ts`) β the standard way to build analytics hooks. Reads site/time/filters/timezone from the store once, derives the wire params, and builds the queryKey from the same params object so key and request cannot drift. Handles the same-site placeholder policy, `staleTime`, and `enabled: !!site`. Per-endpoint hooks only declare their key prefix, endpoint-specific `extraParams`, and fetcher. Never hand-assemble a queryKey listing store inputs in an analytics hook.## State Managementdiff --git a/client/src/api/CLAUDE.md b/client/src/api/CLAUDE.mdindex c5e141148..172778b9b 100644--- a/client/src/api/CLAUDE.md+++ b/client/src/api/CLAUDE.md@@ -69,6 +69,21 @@ Wrapper around axios that:Converts a `Time` object to `CommonApiParams` for analytics endpoints.+### `useAnalyticsQuery` / `useAnalyticsInfiniteQuery` (`analytics/useAnalyticsQuery.ts`)++The standard base for analytics query hooks. Reads the store context (site,+time, previousTime, filters, timezone) once, derives the wire params, and+builds the queryKey from the same params object β key and request cannot+drift. Owns the same-site placeholder policy, `staleTime: 60_000`, and+`enabled: !!site`. A per-endpoint hook declares only:++- `key` β the historical key prefix (mutations invalidate by it)+- `extraParams` β endpoint params beyond time/filters (also keyed automatically)+- `keyExtras` β only for values that select the fetcher itself (e.g. `lite`)+- `fetch` β the endpoint function, plus any response reshaping++Do not hand-assemble queryKeys that list store inputs in analytics hooks.+## Conventions- **Naming**: Endpoint functions use `fetch*`, `create*`, `update*`, `delete*` prefixesdiff --git a/client/src/api/analytics/hooks/bots/useGetBotDimension.ts b/client/src/api/analytics/hooks/bots/useGetBotDimension.tsindex bbeafa611..a042ff84c 100644--- a/client/src/api/analytics/hooks/bots/useGetBotDimension.ts+++ b/client/src/api/analytics/hooks/bots/useGetBotDimension.ts@@ -1,8 +1,12 @@-import { useQuery } from "@tanstack/react-query";import { useBotsStore } from "../../../../app/[site]/bots/botsStore";import { useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { type BotDimensionKey, fetchBotDimension } from "../../endpoints";+import {+ type BotDimensionKey,+ type BotDimensionParams,+ fetchBotDimension,+ type PaginatedBotDimensionResponse,+} from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";import { BOT_AVAILABLE_FILTERS } from "./constants";export function useGetBotDimension({@@ -16,21 +20,17 @@ export function useGetBotDimension({limit?: number;page?: number;}) {- const { time, filters, timezone } = useStore();+ const { filters } = useStore();const { selectedLayer } = useBotsStore();const botFilters = filters.filter(filter => BOT_AVAILABLE_FILTERS.includes(filter.parameter));- const params = buildApiParams(time, { filters: botFilters });- return useQuery({- queryKey: ["bot-dimension", time, site, dimension, limit, page, botFilters, selectedLayer, timezone],- queryFn: () =>- fetchBotDimension(site!, { ...params, dimension, limit, page, layer: selectedLayer }).then(data => ({ data })),- staleTime: 60_000,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const [, , prevSite] = query.queryKey;- return prevSite === site ? query.state.data : undefined;- },- enabled: !!site,+ return useAnalyticsQuery<{ data: PaginatedBotDimensionResponse }, BotDimensionParams>({+ key: "bot-dimension",+ site,+ // Only bot-relevant filters go on the wire; when none apply, send no filters.+ useFilters: botFilters.length > 0,+ customFilters: botFilters,+ extraParams: { dimension, limit, page, layer: selectedLayer },+ fetch: (site, params) => fetchBotDimension(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/bots/useGetBotOverview.ts b/client/src/api/analytics/hooks/bots/useGetBotOverview.tsindex b74769b2e..8ec71acff 100644--- a/client/src/api/analytics/hooks/bots/useGetBotOverview.ts+++ b/client/src/api/analytics/hooks/bots/useGetBotOverview.ts@@ -1,25 +1,21 @@-import { useQuery } from "@tanstack/react-query";-import { useStore } from "../../../../lib/store";import { useBotsStore } from "../../../../app/[site]/bots/botsStore";-import { buildApiParams } from "../../../utils";-import { fetchBotOverview } from "../../endpoints";+import { useStore } from "../../../../lib/store";+import { type BotOverviewParams, fetchBotOverview, type GetBotOverviewResponse } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";import { BOT_AVAILABLE_FILTERS } from "./constants";export function useGetBotOverview({ site }: { site?: number | string }) {- const { time, filters, timezone } = useStore();+ const { filters } = useStore();const { selectedLayer } = useBotsStore();const botFilters = filters.filter(filter => BOT_AVAILABLE_FILTERS.includes(filter.parameter));- const params = buildApiParams(time, { filters: botFilters });- return useQuery({- queryKey: ["bot-overview", time, site, botFilters, selectedLayer, timezone],- queryFn: () => fetchBotOverview(site!, { ...params, layer: selectedLayer }).then(data => ({ data })),- staleTime: 60_000,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const [, , prevSite] = query.queryKey;- return prevSite === site ? query.state.data : undefined;- },- enabled: !!site,+ return useAnalyticsQuery<{ data: GetBotOverviewResponse }, BotOverviewParams>({+ key: "bot-overview",+ site,+ // Only bot-relevant filters go on the wire; when none apply, send no filters.+ useFilters: botFilters.length > 0,+ customFilters: botFilters,+ extraParams: { layer: selectedLayer },+ fetch: (site, params) => fetchBotOverview(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/bots/useGetBotTimeSeries.ts b/client/src/api/analytics/hooks/bots/useGetBotTimeSeries.tsindex 13ee9a239..30c830f8b 100644--- a/client/src/api/analytics/hooks/bots/useGetBotTimeSeries.ts+++ b/client/src/api/analytics/hooks/bots/useGetBotTimeSeries.ts@@ -1,10 +1,10 @@import { TimeBucket } from "@rybbit/shared";-import { UseQueryOptions, UseQueryResult, useQuery } from "@tanstack/react-query";+import { UseQueryOptions, UseQueryResult } from "@tanstack/react-query";import { useBotsStore } from "../../../../app/[site]/bots/botsStore";import { useStore } from "../../../../lib/store";import { APIResponse } from "../../../types";-import { buildApiParams } from "../../../utils";-import { fetchBotTimeSeries, GetBotTimeSeriesResponse } from "../../endpoints";+import { type BotTimeSeriesParams, fetchBotTimeSeries, GetBotTimeSeriesResponse } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";import { BOT_AVAILABLE_FILTERS } from "./constants";export function useGetBotTimeSeries({@@ -16,23 +16,19 @@ export function useGetBotTimeSeries({bucket?: TimeBucket;props?: Partial<UseQueryOptions<APIResponse<GetBotTimeSeriesResponse>>>;}): UseQueryResult<APIResponse<GetBotTimeSeriesResponse>> {- const { time, filters, bucket: storeBucket, timezone } = useStore();+ const { filters, bucket: storeBucket } = useStore();const { selectedLayer } = useBotsStore();const bucketToUse = bucket || storeBucket;const botFilters = filters.filter(filter => BOT_AVAILABLE_FILTERS.includes(filter.parameter));- const params = buildApiParams(time, { filters: botFilters });- return useQuery({- queryKey: ["bot-time-series", time, bucketToUse, site, botFilters, selectedLayer, timezone],- queryFn: () =>- fetchBotTimeSeries(site, { ...params, bucket: bucketToUse, layer: selectedLayer }).then(data => ({ data })),- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const [, , , prevSite] = query.queryKey as [string, any, TimeBucket, string | number];- return prevSite === site ? query.state.data : undefined;- },- staleTime: 60_000,- enabled: !!site,- ...props,+ return useAnalyticsQuery<APIResponse<GetBotTimeSeriesResponse>, BotTimeSeriesParams>({+ key: "bot-time-series",+ site,+ // Only bot-relevant filters go on the wire; when none apply, send no filters.+ useFilters: botFilters.length > 0,+ customFilters: botFilters,+ extraParams: { bucket: bucketToUse, layer: selectedLayer },+ props,+ fetch: (site, params) => fetchBotTimeSeries(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/errors/useGetErrorBucketed.ts b/client/src/api/analytics/hooks/errors/useGetErrorBucketed.tsindex a0a085d13..891d06b3d 100644--- a/client/src/api/analytics/hooks/errors/useGetErrorBucketed.ts+++ b/client/src/api/analytics/hooks/errors/useGetErrorBucketed.ts@@ -1,7 +1,7 @@import { useStore } from "@/lib/store";-import { useQuery, UseQueryResult } from "@tanstack/react-query";-import { buildApiParams } from "../../../utils";-import { fetchErrorBucketed, GetErrorBucketedResponse } from "../../endpoints";+import { UseQueryResult } from "@tanstack/react-query";+import { ErrorBucketedParams, fetchErrorBucketed, GetErrorBucketedResponse } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";type UseGetErrorBucketedOptions = {errorMessage: string;@@ -10,20 +10,13 @@ type UseGetErrorBucketedOptions = {export function useGetErrorBucketed({errorMessage,}: UseGetErrorBucketedOptions): UseQueryResult<GetErrorBucketedResponse> {- const { time, site, filters, bucket, timezone } = useStore();+ const { bucket } = useStore();- const params = buildApiParams(time, { filters });-- return useQuery({- queryKey: ["error-bucketed", time, site, filters, bucket, errorMessage, timezone],- queryFn: () => {- return fetchErrorBucketed(site, {- ...params,- errorMessage,- bucket,- });- },- enabled: !!errorMessage && !!site,+ return useAnalyticsQuery<GetErrorBucketedResponse, ErrorBucketedParams>({+ key: "error-bucketed",+ extraParams: { errorMessage, bucket },+ enabled: !!errorMessage,staleTime: Infinity,+ fetch: (site, params) => fetchErrorBucketed(site, params),});}diff --git a/client/src/api/analytics/hooks/errors/useGetErrorNames.ts b/client/src/api/analytics/hooks/errors/useGetErrorNames.tsindex cddb6cc0a..6d0504afe 100644--- a/client/src/api/analytics/hooks/errors/useGetErrorNames.ts+++ b/client/src/api/analytics/hooks/errors/useGetErrorNames.ts@@ -1,7 +1,6 @@-import { useStore } from "@/lib/store";-import { useQuery, UseQueryResult } from "@tanstack/react-query";-import { buildApiParams } from "../../../utils";-import { fetchErrorNames, ErrorNamesPaginatedResponse } from "../../endpoints";+import { UseQueryResult } from "@tanstack/react-query";+import { ErrorNamesParams, ErrorNamesPaginatedResponse, fetchErrorNames } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";type UseGetErrorNamesOptions = {limit?: number;@@ -15,19 +14,12 @@ export function useGetErrorNamesPaginated({page = 1,useFilters = true,}: UseGetErrorNamesOptions): UseQueryResult<{ data: ErrorNamesPaginatedResponse }> {- const { time, site, filters, timezone } = useStore();-- return useQuery({- queryKey: ["error-names", time, site, filters, limit, page, useFilters, timezone],- queryFn: async () => {- const data = await fetchErrorNames(site, {- ...buildApiParams(time, { filters: useFilters ? filters : undefined }),- limit,- page,- });- return { data };- },+ return useAnalyticsQuery<{ data: ErrorNamesPaginatedResponse }, ErrorNamesParams>({+ key: "error-names",+ useFilters,+ extraParams: { limit, page },staleTime: Infinity,+ fetch: (site, params) => fetchErrorNames(site, params).then(data => ({ data })),});}@@ -36,17 +28,11 @@ export function useGetErrorNames({limit = 10,useFilters = true,}: Omit<UseGetErrorNamesOptions, "page">): UseQueryResult<{ data: ErrorNamesPaginatedResponse }> {- const { time, site, filters, timezone } = useStore();-- return useQuery({- queryKey: ["error-names", time, site, filters, limit, timezone],- queryFn: async () => {- const data = await fetchErrorNames(site, {- ...buildApiParams(time, { filters: useFilters ? filters : undefined }),- limit,- });- return { data };- },+ return useAnalyticsQuery<{ data: ErrorNamesPaginatedResponse }, ErrorNamesParams>({+ key: "error-names",+ useFilters,+ extraParams: { limit },staleTime: Infinity,+ fetch: (site, params) => fetchErrorNames(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/events/useGetAutocaptureEvents.ts b/client/src/api/analytics/hooks/events/useGetAutocaptureEvents.tsindex 429c39907..5ae8e4e79 100644--- a/client/src/api/analytics/hooks/events/useGetAutocaptureEvents.ts+++ b/client/src/api/analytics/hooks/events/useGetAutocaptureEvents.ts@@ -1,21 +1,19 @@-import { useQuery } from "@tanstack/react-query";import { AutocaptureTargetType } from "../../../../lib/events";import { EVENT_FILTERS } from "../../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchAutocaptureEvents } from "../../endpoints";+import { getFilteredFilters } from "../../../../lib/store";+import { type AutocaptureEvent, fetchAutocaptureEvents } from "../../endpoints";+import { CommonApiParams } from "../../endpoints/types";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetAutocaptureEvents(type: AutocaptureTargetType) {- const { site, time, timezone } = useStore();-const filteredFilters = getFilteredFilters(EVENT_FILTERS);- const params = buildApiParams(time, {- filters: filteredFilters.length > 0 ? filteredFilters : undefined,- });- return useQuery({- queryKey: ["autocapture-events", site, type, time, filteredFilters, timezone],- enabled: !!site,- queryFn: () => fetchAutocaptureEvents(site, { ...params, type }),+ return useAnalyticsQuery<AutocaptureEvent[], CommonApiParams & { type: string }>({+ key: "autocapture-events",+ // Only event-relevant filters go on the wire; when none apply, send no filters.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { type },+ fetch: (site, params) => fetchAutocaptureEvents(site, params),});}diff --git a/client/src/api/analytics/hooks/events/useGetEventBucketed.ts b/client/src/api/analytics/hooks/events/useGetEventBucketed.tsindex 4bd154207..10d30bd25 100644--- a/client/src/api/analytics/hooks/events/useGetEventBucketed.ts+++ b/client/src/api/analytics/hooks/events/useGetEventBucketed.ts@@ -1,25 +1,18 @@-import { useQuery } from "@tanstack/react-query";import { EVENT_FILTERS } from "../../../../lib/filterGroups";import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchEventBucketed } from "../../endpoints";+import { type EventBucketedParams, type EventBucketedPoint, fetchEventBucketed } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetEventBucketed({ limit = 5 }: { limit?: number } = {}) {- const { site, time, bucket, timezone } = useStore();-+ const { bucket } = useStore();const filteredFilters = getFilteredFilters(EVENT_FILTERS);- const params = buildApiParams(time, {- filters: filteredFilters.length > 0 ? filteredFilters : undefined,- });- return useQuery({- queryKey: ["event-bucketed", site, time, bucket, filteredFilters, limit, timezone],- enabled: !!site,- queryFn: () =>- fetchEventBucketed(site, {- ...params,- bucket,- limit,- }),+ return useAnalyticsQuery<EventBucketedPoint[], EventBucketedParams>({+ key: "event-bucketed",+ // Only event-relevant filters go on the wire; when none apply, send no filters.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { bucket, limit },+ fetch: (site, params) => fetchEventBucketed(site, params),});}diff --git a/client/src/api/analytics/hooks/events/useGetEventNames.ts b/client/src/api/analytics/hooks/events/useGetEventNames.tsindex 929bd72ec..8c94eff5e 100644--- a/client/src/api/analytics/hooks/events/useGetEventNames.ts+++ b/client/src/api/analytics/hooks/events/useGetEventNames.ts@@ -1,20 +1,16 @@-import { useQuery } from "@tanstack/react-query";import { EVENT_FILTERS } from "../../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";+import { getFilteredFilters } from "../../../../lib/store";import { fetchEventNames } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetEventNames() {- const { site, time, timezone } = useStore();-const filteredFilters = getFilteredFilters(EVENT_FILTERS);- const params = buildApiParams(time, {- filters: filteredFilters.length > 0 ? filteredFilters : undefined,- });- return useQuery({- queryKey: ["event-names", site, time, filteredFilters, timezone],- enabled: !!site,- queryFn: () => fetchEventNames(site, params),+ return useAnalyticsQuery({+ key: "event-names",+ // Only event-relevant filters go on the wire; when none apply, send no filters.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ fetch: (site, params) => fetchEventNames(site, params),});}diff --git a/client/src/api/analytics/hooks/events/useGetOutboundLinks.ts b/client/src/api/analytics/hooks/events/useGetOutboundLinks.tsindex 3ffa0855a..3594a12f9 100644--- a/client/src/api/analytics/hooks/events/useGetOutboundLinks.ts+++ b/client/src/api/analytics/hooks/events/useGetOutboundLinks.ts@@ -1,20 +1,16 @@-import { useQuery } from "@tanstack/react-query";import { EVENT_FILTERS } from "../../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";+import { getFilteredFilters } from "../../../../lib/store";import { fetchOutboundLinks } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetOutboundLinks() {- const { site, time, timezone } = useStore();-const filteredFilters = getFilteredFilters(EVENT_FILTERS);- const params = buildApiParams(time, {- filters: filteredFilters.length > 0 ? filteredFilters : undefined,- });- return useQuery({- queryKey: ["outbound-links", site, time, filteredFilters, timezone],- enabled: !!site,- queryFn: () => fetchOutboundLinks(site, params),+ return useAnalyticsQuery({+ key: "outbound-links",+ // Only event-relevant filters go on the wire; when none apply, send no filters.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ fetch: (site, params) => fetchOutboundLinks(site, params),});}diff --git a/client/src/api/analytics/hooks/events/useGetSiteEventCount.ts b/client/src/api/analytics/hooks/events/useGetSiteEventCount.tsindex ac862e79f..264a75651 100644--- a/client/src/api/analytics/hooks/events/useGetSiteEventCount.ts+++ b/client/src/api/analytics/hooks/events/useGetSiteEventCount.ts@@ -1,24 +1,18 @@-import { useQuery } from "@tanstack/react-query";import { EVENT_FILTERS } from "../../../../lib/filterGroups";import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchSiteEventCount } from "../../endpoints";+import { fetchSiteEventCount, type SiteEventCountParams, type SiteEventCountPoint } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetSiteEventCount() {- const { site, time, bucket, timezone } = useStore();-+ const { bucket } = useStore();const filteredFilters = getFilteredFilters(EVENT_FILTERS);- const params = buildApiParams(time, {- filters: filteredFilters.length > 0 ? filteredFilters : undefined,- });- return useQuery({- queryKey: ["site-event-count", site, time, bucket, filteredFilters, timezone],- enabled: !!site,- queryFn: () =>- fetchSiteEventCount(site, {- ...params,- bucket,- }),+ return useAnalyticsQuery<SiteEventCountPoint[], SiteEventCountParams>({+ key: "site-event-count",+ // Only event-relevant filters go on the wire; when none apply, send no filters.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { bucket },+ fetch: (site, params) => fetchSiteEventCount(site, params),});}diff --git a/client/src/api/analytics/hooks/funnels/useGetFunnel.ts b/client/src/api/analytics/hooks/funnels/useGetFunnel.tsindex 1ba5aedaa..3f5143ee2 100644--- a/client/src/api/analytics/hooks/funnels/useGetFunnel.ts+++ b/client/src/api/analytics/hooks/funnels/useGetFunnel.ts@@ -1,39 +1,34 @@-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";+import { useMutation, useQueryClient } from "@tanstack/react-query";import { useDebounce } from "@uidotdev/usehooks";import { FUNNEL_PAGE_FILTERS } from "../../../../lib/filterGroups";import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { analyzeFunnel, FunnelRequest, FunnelResponse, saveFunnel, SaveFunnelRequest } from "../../endpoints";+import {+ analyzeFunnel,+ AnalyzeFunnelParams,+ FunnelRequest,+ FunnelResponse,+ saveFunnel,+ SaveFunnelRequest,+} from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";/*** Hook for analyzing conversion funnels through a series of steps*/export function useGetFunnel(config?: FunnelRequest, debounce?: boolean) {- const { site, time, timezone } = useStore();-const debouncedConfig = useDebounce(config, 500);- const filteredFilters = getFilteredFilters(FUNNEL_PAGE_FILTERS);- const params = buildApiParams(time, { filters: filteredFilters });-const configToUse = debounce ? debouncedConfig : config;+ // Only the funnel page's filter parameters apply; an empty subset means no+ // filters at all (not the store's full filter list).+ const filteredFilters = getFilteredFilters(FUNNEL_PAGE_FILTERS);- return useQuery<FunnelResponse[], Error>({- queryKey: ["funnel", site, time, filteredFilters, configToUse?.steps, timezone],- queryFn: async () => {- if (!configToUse) {- throw new Error("Funnel configuration is required");- }-- return analyzeFunnel(site, {- ...params,- steps: configToUse.steps,- name: configToUse.name,- });- },- // Keep showing the previous result while a changed configuration refetches,- // so the live preview updates in place instead of flashing a loader- placeholderData: previousData => previousData,- enabled: !!site && !!configToUse,+ return useAnalyticsQuery<FunnelResponse[], AnalyzeFunnelParams>({+ key: "funnel",+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { steps: configToUse?.steps ?? [], name: configToUse?.name },+ enabled: !!configToUse,+ fetch: (site, params) => analyzeFunnel(site, params),});}diff --git a/client/src/api/analytics/hooks/funnels/useGetFunnelStepSessions.ts b/client/src/api/analytics/hooks/funnels/useGetFunnelStepSessions.tsindex f5934077e..e1fa0cef9 100644--- a/client/src/api/analytics/hooks/funnels/useGetFunnelStepSessions.ts+++ b/client/src/api/analytics/hooks/funnels/useGetFunnelStepSessions.ts@@ -1,9 +1,13 @@-import { useQuery } from "@tanstack/react-query";import { Time } from "../../../../components/DateSelector/types";import { FUNNEL_PAGE_FILTERS } from "../../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchFunnelStepSessions, FunnelStep } from "../../endpoints";+import { getFilteredFilters } from "../../../../lib/store";+import {+ fetchFunnelStepSessions,+ FunnelStep,+ FunnelStepSessionsParams,+ GetSessionsResponse,+} from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetFunnelStepSessions({steps,@@ -24,22 +28,18 @@ export function useGetFunnelStepSessions({limit?: number;enabled?: boolean;}) {- const { timezone } = useStore();+ // Only the funnel page's filter parameters apply; an empty subset means no+ // filters at all (not the store's full filter list).const filteredFilters = getFilteredFilters(FUNNEL_PAGE_FILTERS);- const params = buildApiParams(time, { filters: filteredFilters });- return useQuery({- queryKey: ["funnel-step-sessions", steps, stepNumber, siteId, time, mode, page, limit, filteredFilters, timezone],- queryFn: async () => {- return fetchFunnelStepSessions(siteId, {- ...params,- steps,- stepNumber,- mode,- page,- limit,- });- },- enabled: !!siteId && !!steps && steps.length >= 2 && enabled,+ return useAnalyticsQuery<{ data: GetSessionsResponse }, FunnelStepSessionsParams>({+ key: "funnel-step-sessions",+ site: siteId,+ overrideTime: time,+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { steps, stepNumber, mode, page, limit },+ enabled: !!steps && steps.length >= 2 && enabled,+ fetch: (site, params) => fetchFunnelStepSessions(site, params),});}diff --git a/client/src/api/analytics/hooks/goals/useGetGoalSessions.ts b/client/src/api/analytics/hooks/goals/useGetGoalSessions.tsindex 9fe29399e..d96d23c5d 100644--- a/client/src/api/analytics/hooks/goals/useGetGoalSessions.ts+++ b/client/src/api/analytics/hooks/goals/useGetGoalSessions.ts@@ -1,8 +1,6 @@-import { useQuery } from "@tanstack/react-query";import { Time } from "../../../../components/DateSelector/types";-import { useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchGoalSessions } from "../../endpoints";+import { fetchGoalSessions, GetSessionsResponse, GoalSessionsParams } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetGoalSessions({goalId,@@ -19,19 +17,13 @@ export function useGetGoalSessions({limit?: number;enabled?: boolean;}) {- const { timezone } = useStore();- const params = buildApiParams(time);-- return useQuery({- queryKey: ["goal-sessions", goalId, siteId, time, page, limit, timezone],- queryFn: async () => {- return fetchGoalSessions(siteId, {- ...params,- goalId,- page,- limit,- });- },- enabled: !!siteId && !!goalId && enabled,+ return useAnalyticsQuery<{ data: GetSessionsResponse }, GoalSessionsParams>({+ key: "goal-sessions",+ site: siteId,+ overrideTime: time,+ useFilters: false,+ extraParams: { goalId, page, limit },+ enabled: !!goalId && enabled,+ fetch: (site, params) => fetchGoalSessions(site, params),});}diff --git a/client/src/api/analytics/hooks/goals/useGetGoalTimeSeries.ts b/client/src/api/analytics/hooks/goals/useGetGoalTimeSeries.tsindex 2b4d66c3d..2f8113d49 100644--- a/client/src/api/analytics/hooks/goals/useGetGoalTimeSeries.ts+++ b/client/src/api/analytics/hooks/goals/useGetGoalTimeSeries.ts@@ -1,25 +1,22 @@-import { useQuery } from "@tanstack/react-query";import { TimeBucket } from "@rybbit/shared";import { GOALS_PAGE_FILTERS } from "../../../../lib/filterGroups";import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchGoalTimeSeries } from "../../endpoints";+import { fetchGoalTimeSeries, GoalTimeSeriesParams, GoalTimeSeriesPoint } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetGoalTimeSeries({ goalIds, bucket }: { goalIds: number[]; bucket?: TimeBucket }) {- const { site, time, bucket: storeBucket, timezone } = useStore();- const filteredFilters = getFilteredFilters(GOALS_PAGE_FILTERS);+ const { bucket: storeBucket } = useStore();const bucketToUse = bucket || storeBucket;- const params = buildApiParams(time, { filters: filteredFilters });+ // Only the goals page's filter parameters apply; an empty subset means no+ // filters at all (not the store's full filter list).+ const filteredFilters = getFilteredFilters(GOALS_PAGE_FILTERS);- return useQuery({- queryKey: ["goal-time-series", site, time, bucketToUse, filteredFilters, goalIds, timezone],- queryFn: async () => {- return fetchGoalTimeSeries(site, {- ...params,- bucket: bucketToUse,- goalIds,- });- },- enabled: !!site && goalIds.length > 0,+ return useAnalyticsQuery<GoalTimeSeriesPoint[], GoalTimeSeriesParams>({+ key: "goal-time-series",+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { bucket: bucketToUse, goalIds },+ enabled: goalIds.length > 0,+ fetch: (site, params) => fetchGoalTimeSeries(site, params),});}diff --git a/client/src/api/analytics/hooks/goals/useGetGoals.ts b/client/src/api/analytics/hooks/goals/useGetGoals.tsindex afe2b4b56..2f521787f 100644--- a/client/src/api/analytics/hooks/goals/useGetGoals.ts+++ b/client/src/api/analytics/hooks/goals/useGetGoals.ts@@ -1,8 +1,7 @@-import { useQuery } from "@tanstack/react-query";import { GOALS_PAGE_FILTERS } from "../../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchGoals } from "../../endpoints";+import { getFilteredFilters } from "../../../../lib/store";+import { fetchGoals, GoalsParams, GoalsResponse } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";export function useGetGoals({page = 1,@@ -15,22 +14,15 @@ export function useGetGoals({sort?: "goalId" | "name" | "goalType" | "createdAt";order?: "asc" | "desc";}) {- const { site, time, timezone } = useStore();+ // Only the goals page's filter parameters apply; an empty subset means no+ // filters at all (not the store's full filter list).const filteredFilters = getFilteredFilters(GOALS_PAGE_FILTERS);- const params = buildApiParams(time, { filters: filteredFilters });-- return useQuery({- queryKey: ["goals", site, time, filteredFilters, page, pageSize, sort, order, timezone],- queryFn: async () => {- return fetchGoals(site, {- ...params,- page,- pageSize,- sort,- order,- });- },- enabled: !!site,+ return useAnalyticsQuery<GoalsResponse, GoalsParams>({+ key: "goals",+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { page, pageSize, sort, order },+ fetch: (site, params) => fetchGoals(site, params),});}diff --git a/client/src/api/analytics/hooks/performance/useGetPerformanceByDimension.ts b/client/src/api/analytics/hooks/performance/useGetPerformanceByDimension.tsindex f44243803..367ee4ad7 100644--- a/client/src/api/analytics/hooks/performance/useGetPerformanceByDimension.ts+++ b/client/src/api/analytics/hooks/performance/useGetPerformanceByDimension.ts@@ -1,9 +1,13 @@import { Filter } from "@rybbit/shared";-import { useQuery, UseQueryResult } from "@tanstack/react-query";+import { UseQueryResult } from "@tanstack/react-query";import { usePerformanceStore } from "../../../../app/[site]/performance/performanceStore";-import { useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchPerformanceByDimension, PaginatedPerformanceResponse, PerformanceByDimensionItem } from "../../endpoints";+import {+ fetchPerformanceByDimension,+ PaginatedPerformanceResponse,+ PerformanceByDimensionItem,+ PerformanceByDimensionParams,+} from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";// Keep the old type for backward compatibilityexport type PerformanceByPathItem = PerformanceByDimensionItem & {@@ -31,49 +35,15 @@ export function useGetPerformanceByDimension({sortBy,sortOrder,}: UseGetPerformanceByDimensionOptions): UseQueryResult<PaginatedPerformanceResponse> {- const { time, filters, timezone } = useStore();const { selectedPercentile } = usePerformanceStore();- const combinedFilters = useFilters ? [...filters, ...additionalFilters] : undefined;- const params = buildApiParams(time, { filters: combinedFilters });-- return useQuery({- queryKey: [- "performance-by-dimension",- dimension,- time,- site,- filters,- selectedPercentile,- limit,- page,- additionalFilters,- sortBy,- sortOrder,- timezone,- ],- queryFn: () => {- return fetchPerformanceByDimension(site, {- ...params,- dimension,- limit,- page,- percentile: selectedPercentile,- sortBy,- sortOrder,- });- },+ return useAnalyticsQuery<PaginatedPerformanceResponse, PerformanceByDimensionParams>({+ key: "performance-by-dimension",+ site,+ useFilters,+ additionalFilters,+ extraParams: { dimension, limit, page, percentile: selectedPercentile, sortBy, sortOrder },staleTime: Infinity,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const prevQueryKey = query.queryKey;- const [, , , prevSite] = prevQueryKey;-- if (prevSite === site) {- return query.state.data;- }- return undefined;- },- enabled: !!site,+ fetch: (site, params) => fetchPerformanceByDimension(site, params),});}diff --git a/client/src/api/analytics/hooks/performance/useGetPerformanceOverview.ts b/client/src/api/analytics/hooks/performance/useGetPerformanceOverview.tsindex bb55c6edb..85d100b0d 100644--- a/client/src/api/analytics/hooks/performance/useGetPerformanceOverview.ts+++ b/client/src/api/analytics/hooks/performance/useGetPerformanceOverview.ts@@ -1,36 +1,18 @@-import { useQuery } from "@tanstack/react-query";import { usePerformanceStore } from "../../../../app/[site]/performance/performanceStore";-import { useStore } from "../../../../lib/store";-import { buildApiParams } from "../../../utils";-import { fetchPerformanceOverview } from "../../endpoints";+import { fetchPerformanceOverview, GetPerformanceOverviewResponse, PerformanceOverviewParams } from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";type PeriodTime = "current" | "previous";export function useGetPerformanceOverview({ periodTime, site }: { periodTime?: PeriodTime; site?: number | string }) {- const { time, previousTime, filters, timezone } = useStore();const { selectedPercentile } = usePerformanceStore();- const timeToUse = periodTime === "previous" ? previousTime : time;- const params = buildApiParams(timeToUse, { filters });-- return useQuery({- queryKey: ["performance-overview", timeToUse, site, filters, selectedPercentile, timezone],- queryFn: () => {- return fetchPerformanceOverview(site!, {- ...params,- percentile: selectedPercentile,- }).then(data => ({ data }));- },+ return useAnalyticsQuery<{ data: GetPerformanceOverviewResponse }, PerformanceOverviewParams>({+ key: "performance-overview",+ site,+ periodTime,+ extraParams: { percentile: selectedPercentile },staleTime: Infinity,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const prevQueryKey = query.queryKey as [string, string, string];- const [, , prevSite] = prevQueryKey;-- if (prevSite === site) {- return query.state.data;- }- return undefined;- },+ fetch: (site, params) => fetchPerformanceOverview(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/performance/useGetPerformanceTimeSeries.ts b/client/src/api/analytics/hooks/performance/useGetPerformanceTimeSeries.tsindex 157a6fc5c..70a716e0d 100644--- a/client/src/api/analytics/hooks/performance/useGetPerformanceTimeSeries.ts+++ b/client/src/api/analytics/hooks/performance/useGetPerformanceTimeSeries.ts@@ -1,10 +1,13 @@import { Filter, TimeBucket } from "@rybbit/shared";-import { useQuery, UseQueryOptions, UseQueryResult } from "@tanstack/react-query";-import { usePerformanceStore } from "../../../../app/[site]/performance/performanceStore";+import { UseQueryOptions, UseQueryResult } from "@tanstack/react-query";import { useStore } from "../../../../lib/store";import { APIResponse } from "../../../types";-import { buildApiParams } from "../../../utils";-import { fetchPerformanceTimeSeries, GetPerformanceTimeSeriesResponse } from "../../endpoints";+import {+ fetchPerformanceTimeSeries,+ GetPerformanceTimeSeriesResponse,+ PerformanceTimeSeriesParams,+} from "../../endpoints";+import { useAnalyticsQuery } from "../../useAnalyticsQuery";type PeriodTime = "current" | "previous";@@ -21,30 +24,17 @@ export function useGetPerformanceTimeSeries({dynamicFilters?: Filter[];props?: Partial<UseQueryOptions<APIResponse<GetPerformanceTimeSeriesResponse>>>;}): UseQueryResult<APIResponse<GetPerformanceTimeSeriesResponse>> {- const { time, previousTime, filters: globalFilters, bucket: storeBucket, timezone } = useStore();- const { selectedPerformanceMetric } = usePerformanceStore();-- const timeToUse = periodTime === "previous" ? previousTime : time;+ const { bucket: storeBucket } = useStore();const bucketToUse = bucket || storeBucket;- const combinedFilters = [...globalFilters, ...dynamicFilters];-- const params = buildApiParams(timeToUse, { filters: combinedFilters });-- return useQuery({- queryKey: ["performance-time-series", timeToUse, bucketToUse, site, combinedFilters, selectedPerformanceMetric, timezone],- queryFn: () => {- return fetchPerformanceTimeSeries(site, { ...params, bucket: bucketToUse }).then(data => ({ data }));- },- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const [, , , prevSite] = query.queryKey as [string, any, TimeBucket, string | number, Filter[], string];- if (prevSite === site) {- return query.state.data;- }- return undefined;- },+ return useAnalyticsQuery<APIResponse<GetPerformanceTimeSeriesResponse>, PerformanceTimeSeriesParams>({+ key: "performance-time-series",+ site,+ periodTime,+ additionalFilters: dynamicFilters,+ extraParams: { bucket: bucketToUse },staleTime: Infinity,- ...props,+ props,+ fetch: (site, params) => fetchPerformanceTimeSeries(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/useDashboardCard.ts b/client/src/api/analytics/hooks/useDashboardCard.tsindex a245b2dd0..2b7101c17 100644--- a/client/src/api/analytics/hooks/useDashboardCard.ts+++ b/client/src/api/analytics/hooks/useDashboardCard.ts@@ -1,7 +1,7 @@-import { useQuery } from "@tanstack/react-query";import { useStore } from "../../../lib/store";-import { buildApiParams } from "../../utils";-import { runDashboardCard } from "../endpoints/dashboards";+import { RunCustomQueryResponse } from "../endpoints/customQuery";+import { runDashboardCard, RunDashboardCardBody } from "../endpoints/dashboards";+import { useAnalyticsQuery } from "../useAnalyticsQuery";/*** Executes a dashboard card's SQL against the time-aware run-card endpoint.@@ -17,14 +17,15 @@ export function useDashboardCard(sql: string,enabled = true) {- const time = useStore(state => state.time);const bucket = useStore(state => state.bucket);- const apiParams = buildApiParams(time);- return useQuery({- queryKey: ["dashboard-card", siteId, cardId, sql, apiParams, bucket],- queryFn: () => runDashboardCard(siteId!, { query: sql, bucket, ...apiParams }),+ return useAnalyticsQuery<RunCustomQueryResponse, RunDashboardCardBody>({+ key: ["dashboard-card", cardId],+ site: siteId,+ useFilters: false,+ extraParams: { query: sql, bucket },enabled: enabled && !!siteId && !!sql.trim(),- retry: false,+ props: { retry: false },+ fetch: (site, params) => runDashboardCard(site, params),});}diff --git a/client/src/api/analytics/hooks/useGetJourneys.ts b/client/src/api/analytics/hooks/useGetJourneys.tsindex b8ed98d34..b14e834e4 100644--- a/client/src/api/analytics/hooks/useGetJourneys.ts+++ b/client/src/api/analytics/hooks/useGetJourneys.ts@@ -1,10 +1,9 @@import { Filter } from "@rybbit/shared";-import { useQuery } from "@tanstack/react-query";import { Time } from "../../../components/DateSelector/types";import { JOURNEY_PAGE_FILTERS } from "../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../lib/store";-import { buildApiParams } from "../../utils";-import { fetchJourneys, Journey, JourneysResponse } from "../endpoints";+import { getFilteredFilters } from "../../../lib/store";+import { fetchJourneys, JourneysParams as JourneysApiParams, JourneysResponse } from "../endpoints";+import { useAnalyticsQuery } from "../useAnalyticsQuery";export interface JourneyParams {siteId?: number;@@ -18,21 +17,19 @@ export interface JourneyParams {}export const useJourneys = ({ siteId, steps = 3, time, limit = 100, stepFilters, additionalFilters }: JourneyParams) => {- const { timezone } = useStore();const filteredFilters = getFilteredFilters(JOURNEY_PAGE_FILTERS);const combinedFilters = additionalFilters?.length ? [...filteredFilters, ...additionalFilters] : filteredFilters;- const params = buildApiParams(time, { filters: combinedFilters });- return useQuery<JourneysResponse>({- queryKey: ["journeys", siteId, steps, time, limit, combinedFilters, stepFilters, timezone],- queryFn: () =>- fetchJourneys(siteId!, {- ...params,- steps,- limit,- stepFilters,- }),- enabled: !!siteId,- placeholderData: previousData => previousData,+ return useAnalyticsQuery<JourneysResponse, JourneysApiParams>({+ key: "journeys",+ site: siteId,+ overrideTime: time,+ // customFilters fall back to the store filters when empty; disable filters+ // entirely instead so an empty page-filter set stays unfiltered.+ useFilters: combinedFilters.length > 0,+ customFilters: combinedFilters,+ extraParams: { steps, limit, stepFilters },+ enabled: siteId !== undefined,+ fetch: (site, params) => fetchJourneys(site, params),});};diff --git a/client/src/api/analytics/hooks/useGetMetric.ts b/client/src/api/analytics/hooks/useGetMetric.tsindex 64b0e59ee..702e98d54 100644--- a/client/src/api/analytics/hooks/useGetMetric.ts+++ b/client/src/api/analytics/hooks/useGetMetric.ts@@ -1,16 +1,10 @@import { Filter, FilterParameter } from "@rybbit/shared";-import {- InfiniteData,- useInfiniteQuery,- UseInfiniteQueryResult,- useQuery,- UseQueryResult,-} from "@tanstack/react-query";-import { useStore } from "../../../lib/store";-import { APIResponse } from "../../types";-import { buildApiParams } from "../../utils";+import { InfiniteData, UseInfiniteQueryResult, UseQueryResult } from "@tanstack/react-query";import { Time } from "../../../components/DateSelector/types";+import { APIResponse } from "../../types";import { fetchMetric, fetchMetricLite, MetricResponse } from "../endpoints";+import { MetricParams } from "../endpoints/types";+import { useAnalyticsQuery, useAnalyticsInfiniteQuery } from "../useAnalyticsQuery";type PeriodTime = "current" | "previous";@@ -25,45 +19,13 @@ export function useMetric({periodTime?: PeriodTime;useFilters?: boolean;}): UseQueryResult<APIResponse<MetricResponse[]>> {- const { time, previousTime, site, filters, timezone } = useStore();- const timeToUse = periodTime === "previous" ? previousTime : time;-- // For "previous" periods in past-minutes mode, we need to modify the time object- // to use doubled duration for the start and the original start as the end- const timeForQuery: Time =- timeToUse.mode === "past-minutes" && periodTime === "previous"- ? {- ...timeToUse,- pastMinutesStart: timeToUse.pastMinutesStart * 2,- pastMinutesEnd: timeToUse.pastMinutesStart,- }- : timeToUse;-- const params = buildApiParams(timeForQuery, { filters: useFilters ? filters : undefined });- const queryKey = [parameter, timeForQuery, site, filters, limit, useFilters, timezone];-- return useQuery({- queryKey,- queryFn: async () => {- const result = await fetchMetric(site, {- ...params,- parameter,- limit,- });- return { data: result.data };- },- staleTime: 60_000,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const prevQueryKey = query.queryKey as [string, string, string];- const [, , prevSite] = prevQueryKey;-- if (prevSite === site) {- return query.state.data;- }- return undefined;- },- enabled: !!site,+ return useAnalyticsQuery<APIResponse<MetricResponse[]>, MetricParams>({+ key: parameter,+ periodTime,+ doublePastMinutesForPrevious: true,+ useFilters,+ extraParams: { parameter, limit },+ fetch: (site, params) => fetchMetric(site, params).then(result => ({ data: result.data })),});}@@ -92,41 +54,17 @@ export function usePaginatedMetric({customTime?: Time;lite?: boolean;}): UseQueryResult<PaginatedResponse> {- const { time, site, filters, timezone } = useStore();- const timeToUse = customTime ?? time;// Lite endpoints forward filters too β the server falls back to raw events// when a filter is active. `lite` only selects the fetcher, not the filters.- const combinedFilters = useFilters- ? customFilters.length > 0- ? customFilters- : [...filters, ...additionalFilters]- : undefined;-- const params = buildApiParams(timeToUse, { filters: combinedFilters });-- return useQuery({- queryKey: [parameter, customTime, time, site, filters, limit, page, additionalFilters, customFilters, timezone, lite],- queryFn: async () => {- const fetcher = lite ? fetchMetricLite : fetchMetric;- return fetcher(site, {- ...params,- parameter,- limit,- page,- });- },- staleTime: 60_000,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const prevQueryKey = query.queryKey;- const [, , prevSite] = prevQueryKey;-- if (prevSite === site) {- return query.state.data;- }- return undefined;- },- enabled: !!site,+ return useAnalyticsQuery<PaginatedResponse, MetricParams>({+ key: parameter,+ overrideTime: customTime,+ useFilters,+ additionalFilters,+ customFilters,+ extraParams: { parameter, limit, page },+ keyExtras: [lite],+ fetch: (site, params) => (lite ? fetchMetricLite : fetchMetric)(site, params),});}@@ -147,53 +85,16 @@ export function useInfiniteMetric({customTime?: Time;lite?: boolean;}): UseInfiniteQueryResult<InfiniteData<PaginatedResponse>> {- const { time, site, filters, timezone } = useStore();- const timeToUse = customTime ?? time;// Lite endpoints forward filters too β the server falls back to raw events// when a filter is active. `lite` only selects the fetcher, not the filters.- const combinedFilters = useFilters- ? customFilters.length > 0- ? customFilters- : [...filters, ...additionalFilters]- : undefined;- const params = buildApiParams(timeToUse, { filters: combinedFilters });-- return useInfiniteQuery({- queryKey: [- parameter,- customTime,- time,- site,- filters,- limit,- additionalFilters,- customFilters,- "infinite-metric",- timezone,- lite,- ],- queryFn: async ({ pageParam = 1 }) => {- const fetcher = lite ? fetchMetricLite : fetchMetric;- return fetcher(site, {- ...params,- parameter,- limit,- page: pageParam,- });- },- initialPageParam: 1,- getNextPageParam: (lastPage, allPages) => {- // If we've fetched all items, don't get next page- const totalItems = lastPage.totalCount;- const fetchedItemCount = allPages.reduce((acc, page) => acc + page.data.length, 0);-- if (fetchedItemCount >= totalItems) {- return undefined;- }-- return allPages.length + 1;- },- staleTime: 60_000,- enabled: !!site,+ return useAnalyticsInfiniteQuery<PaginatedResponse, MetricParams>({+ key: parameter,+ overrideTime: customTime,+ useFilters,+ additionalFilters,+ customFilters,+ extraParams: { parameter, limit },+ keyExtras: [lite],+ fetchPage: (site, params, page) => (lite ? fetchMetricLite : fetchMetric)(site, { ...params, page }),});}diff --git a/client/src/api/analytics/hooks/useGetOverview.ts b/client/src/api/analytics/hooks/useGetOverview.tsindex b59a03e3c..df31aeccb 100644--- a/client/src/api/analytics/hooks/useGetOverview.ts+++ b/client/src/api/analytics/hooks/useGetOverview.ts@@ -1,8 +1,6 @@-import { useQuery } from "@tanstack/react-query";import { Time } from "../../../components/DateSelector/types";-import { useStore } from "../../../lib/store";-import { buildApiParams } from "../../utils";import { fetchOverview, fetchOverviewLite } from "../endpoints";+import { useAnalyticsQuery } from "../useAnalyticsQuery";type PeriodTime = "current" | "previous";@@ -16,32 +14,13 @@ type UseGetOverviewOptions = {};export function useGetOverview({ periodTime, site, overrideTime, useFilters = true, lite = false }: UseGetOverviewOptions) {- const { time, previousTime, filters, timezone } = useStore();-- // Use overrideTime if provided, otherwise use store time- const baseTime = overrideTime || time;- const timeToUse = periodTime === "previous" ? previousTime : baseTime;-- const params = buildApiParams(timeToUse, { filters: useFilters ? filters : undefined });- const queryKey = ["overview", timeToUse, site, filters, useFilters, timezone, lite];-- return useQuery({- queryKey,- queryFn: () => {- const fetcher = lite ? fetchOverviewLite : fetchOverview;- return fetcher(site!, params).then(data => ({ data }));- },- staleTime: 60_000,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const prevQueryKey = query.queryKey;- const [, , prevSite] = prevQueryKey;-- if (prevSite === site) {- return query.state.data;- }- return undefined;- },- enabled: !!site,+ return useAnalyticsQuery({+ key: "overview",+ site,+ periodTime,+ overrideTime,+ useFilters,+ keyExtras: [lite],+ fetch: (site, params) => (lite ? fetchOverviewLite : fetchOverview)(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/useGetOverviewBucketed.ts b/client/src/api/analytics/hooks/useGetOverviewBucketed.tsindex db03fa8c2..7b3fd5eea 100644--- a/client/src/api/analytics/hooks/useGetOverviewBucketed.ts+++ b/client/src/api/analytics/hooks/useGetOverviewBucketed.ts@@ -1,10 +1,10 @@import { Filter, TimeBucket } from "@rybbit/shared";-import { UseQueryOptions, UseQueryResult, useQuery } from "@tanstack/react-query";+import { UseQueryOptions, UseQueryResult } from "@tanstack/react-query";import { Time } from "../../../components/DateSelector/types";-import { useStore } from "../../../lib/store";import { APIResponse } from "../../types";-import { buildApiParams } from "../../utils";import { fetchOverviewBucketed, fetchOverviewBucketedLite, GetOverviewBucketedResponse } from "../endpoints";+import { BucketedParams } from "../endpoints/types";+import { useAnalyticsQuery } from "../useAnalyticsQuery";type PeriodTime = "current" | "previous";@@ -25,56 +25,22 @@ export function useGetOverviewBucketed({dynamicFilters?: Filter[];refetchInterval?: number;overrideTime?: Time;- props?: Partial<UseQueryOptions<APIResponse<GetOverviewBucketedResponse>>>;+ props?: Partial<UseQueryOptions<APIResponse<GetOverviewBucketedResponse>, Error>>;useFilters?: boolean;// Read the MV-backed lite endpoint instead of the raw-events one.lite?: boolean;}): UseQueryResult<APIResponse<GetOverviewBucketedResponse>> {- const { time, previousTime, filters: globalFilters, timezone } = useStore();-- // Use overrideTime if provided, otherwise use store time- const baseTime = overrideTime || time;- const timeToUse = periodTime === "previous" ? previousTime : baseTime;- const combinedFilters = useFilters ? [...globalFilters, ...dynamicFilters] : undefined;-- // Generate appropriate query key based on whether we're using past minutes or regular time- const queryKey =- timeToUse.mode === "past-minutes"- ? [- "overview-bucketed-past-minutes",- timeToUse.pastMinutesStart,- timeToUse.pastMinutesEnd,- site,- bucket,- combinedFilters,- useFilters,- timezone,- lite,- ]- : ["overview-bucketed", timeToUse, bucket, site, combinedFilters, useFilters, timezone, lite];-- const params = buildApiParams(timeToUse, { filters: combinedFilters });-- return useQuery({- queryKey,- queryFn: () => {- const fetcher = lite ? fetchOverviewBucketedLite : fetchOverviewBucketed;- return fetcher(site, { ...params, bucket }).then(data => ({ data }));- },+ return useAnalyticsQuery<APIResponse<GetOverviewBucketedResponse>, BucketedParams>({+ key: "overview-bucketed",+ site,+ periodTime,+ overrideTime,+ useFilters,+ additionalFilters: dynamicFilters,+ extraParams: { bucket },+ keyExtras: [lite],refetchInterval,- placeholderData: (_, query: any) => {- if (!query?.queryKey) return undefined;- const queryKeyArray = query.queryKey as any[];-- // Find site in query key (position varies based on query type)- const siteIndex = queryKeyArray.findIndex(item => item === site);- if (siteIndex !== -1) {- return query.state.data;- }- return undefined;- },- staleTime: 60_000,- enabled: !!site,- ...props,+ props,+ fetch: (site, params) => (lite ? fetchOverviewBucketedLite : fetchOverviewBucketed)(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/useGetPageTitles.ts b/client/src/api/analytics/hooks/useGetPageTitles.tsindex d42e5a558..289d02b78 100644--- a/client/src/api/analytics/hooks/useGetPageTitles.ts+++ b/client/src/api/analytics/hooks/useGetPageTitles.ts@@ -1,7 +1,6 @@-import { useStore } from "@/lib/store";-import { useQuery, UseQueryResult } from "@tanstack/react-query";-import { buildApiParams } from "../../utils";-import { fetchPageTitles, PageTitlesPaginatedResponse } from "../endpoints";+import { UseQueryResult } from "@tanstack/react-query";+import { fetchPageTitles, PageTitlesParams, PageTitlesPaginatedResponse } from "../endpoints";+import { useAnalyticsQuery } from "../useAnalyticsQuery";type PeriodTime = "current" | "previous";@@ -19,22 +18,12 @@ export function useGetPageTitlesPaginated({useFilters = true,periodTime = "current",}: UseGetPageTitlesOptions): UseQueryResult<{ data: PageTitlesPaginatedResponse }> {- const { time, previousTime, site, filters, timezone } = useStore();-- const timeToUse = periodTime === "previous" ? previousTime : time;- const params = buildApiParams(timeToUse, { filters: useFilters ? filters : undefined });-- return useQuery({- queryKey: ["page-titles", timeToUse, site, filters, limit, page, useFilters, timezone, periodTime],- queryFn: async () => {- const data = await fetchPageTitles(site, {- ...params,- limit,- page,- });- return { data };- },+ return useAnalyticsQuery<{ data: PageTitlesPaginatedResponse }, PageTitlesParams>({+ key: "page-titles",+ periodTime,+ useFilters,+ extraParams: { limit, page },staleTime: Infinity,- enabled: !!site,+ fetch: (site, params) => fetchPageTitles(site, params).then(data => ({ data })),});}diff --git a/client/src/api/analytics/hooks/useGetSessionLocations.ts b/client/src/api/analytics/hooks/useGetSessionLocations.tsindex 2c13dac1f..2c09b0b93 100644--- a/client/src/api/analytics/hooks/useGetSessionLocations.ts+++ b/client/src/api/analytics/hooks/useGetSessionLocations.ts@@ -1,10 +1,9 @@-import { useQuery } from "@tanstack/react-query";import { useStore } from "../../../lib/store";-import { buildApiParams } from "../../utils";import { fetchSessionLocations, LiveSessionLocation } from "../endpoints";+import { useAnalyticsQuery } from "../useAnalyticsQuery";export function useGetSessionLocations() {- const { time, site, filters, timezone } = useStore();+ const { filters } = useStore();// Filter out location-related filters to avoid circular dependenciesconst locationExcludedFilters = filters.filter(@@ -16,13 +15,12 @@ export function useGetSessionLocations() {f.parameter !== "region");- const params = buildApiParams(time, { filters: locationExcludedFilters });-- return useQuery<LiveSessionLocation[]>({- queryKey: ["session-locations", site, time, locationExcludedFilters, timezone],- queryFn: () => {- return fetchSessionLocations(site, params);- },- enabled: !!site,+ return useAnalyticsQuery<LiveSessionLocation[]>({+ key: "session-locations",+ // customFilters fall back to the store filters when empty; disable filters+ // entirely instead so the excluded location filters stay excluded.+ useFilters: locationExcludedFilters.length > 0,+ customFilters: locationExcludedFilters,+ fetch: (site, params) => fetchSessionLocations(site, params),});}diff --git a/client/src/api/analytics/hooks/useGetUserSessions.ts b/client/src/api/analytics/hooks/useGetUserSessions.tsindex 93cc1d9e7..a656abdce 100644--- a/client/src/api/analytics/hooks/useGetUserSessions.ts+++ b/client/src/api/analytics/hooks/useGetUserSessions.ts@@ -8,9 +8,11 @@ import {fetchUserSessionCount,GetSessionsResponse,SessionPageviewsAndEvents,+ SessionsParams,UserSessionCountResponse,} from "../endpoints";import { Time } from "../../../components/DateSelector/types";+import { useAnalyticsQuery } from "../useAnalyticsQuery";export function useGetSessions({userId,@@ -31,29 +33,18 @@ export function useGetSessions({minEvents?: number;minDuration?: number;}) {- const { time, site, timezone } = useStore();-const filteredFilters = getFilteredFilters(SESSION_PAGE_FILTERS);- const params = buildApiParams(timeOverride || time, { filters: filteredFilters });-- return useQuery<{ data: GetSessionsResponse }>({- queryKey: ["sessions", timeOverride || time, site, filteredFilters, userId, page, limit, identifiedOnly, timezone, minPageviews, minEvents, minDuration],- queryFn: () => {- return fetchSessions(site, {- ...params,- page,- limit,- userId,- identifiedOnly,- minPageviews,- minEvents,- minDuration,- });- },+ return useAnalyticsQuery<{ data: GetSessionsResponse }, SessionsParams>({+ key: "sessions",+ overrideTime: timeOverride,+ // customFilters fall back to the store filters when empty; disable filters+ // entirely instead so an empty page-filter set stays unfiltered.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: { page, limit, userId, identifiedOnly, minPageviews, minEvents, minDuration },staleTime: Infinity,- // Wait for the store to hydrate; an empty site produces a malformed URL- enabled: !!site,+ fetch: (site, params) => fetchSessions(site, params),});}diff --git a/client/src/api/analytics/hooks/useGetUsers.ts b/client/src/api/analytics/hooks/useGetUsers.tsindex 61094bb32..e991c3321 100644--- a/client/src/api/analytics/hooks/useGetUsers.ts+++ b/client/src/api/analytics/hooks/useGetUsers.ts@@ -1,10 +1,9 @@import { Filter } from "@rybbit/shared";-import { useQuery } from "@tanstack/react-query";-import { getFilteredFilters, useStore } from "../../../lib/store";+import { getFilteredFilters } from "../../../lib/store";import { USER_PAGE_FILTERS } from "../../../lib/filterGroups";import { APIResponse } from "../../types";-import { buildApiParams } from "../../utils";-import { fetchUsers, UsersResponse } from "../endpoints";+import { fetchUsers, UsersParams, UsersResponse } from "../endpoints";+import { useAnalyticsQuery } from "../useAnalyticsQuery";export interface GetUsersOptions {page: number;@@ -18,31 +17,37 @@ export interface GetUsersOptions {}export function useGetUsers(options: GetUsersOptions) {- const { time, site, timezone } = useStore();-const { page, pageSize, sortBy, sortOrder, identifiedOnly = false, search, searchField } = options;const filteredFilters = getFilteredFilters(USER_PAGE_FILTERS);- const params = buildApiParams(time, { filters: filteredFilters });- return useQuery<+ return useAnalyticsQuery<APIResponse<UsersResponse[]> & {totalCount: number;page: number;pageSize: number;- }+ },+ UsersParams>({- queryKey: ["users", site, time, page, pageSize, sortBy, sortOrder, filteredFilters, identifiedOnly, search, searchField, timezone],- queryFn: async () => {- const result = await fetchUsers(site, {- ...params,- page,- pageSize,- sortBy,- sortOrder: sortOrder as "asc" | "desc",- identifiedOnly,- search,- searchField,- });+ key: "users",+ // customFilters fall back to the store filters when empty; disable filters+ // entirely instead so an empty page-filter set stays unfiltered.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,+ extraParams: {+ page,+ pageSize,+ sortBy,+ sortOrder: sortOrder as "asc" | "desc",+ identifiedOnly,+ search,+ searchField,+ },+ // Use default staleTime (0) for real-time data+ staleTime: 0,+ // Enable refetching when the window regains focus+ props: { refetchOnWindowFocus: true },+ fetch: async (site, params) => {+ const result = await fetchUsers(site, params);return {data: result.data as UsersResponse[],totalCount: result.totalCount,@@ -50,10 +55,5 @@ export function useGetUsers(options: GetUsersOptions) {pageSize: result.pageSize,};},- // Use default staleTime (0) for real-time data- staleTime: 0,- // Enable refetching when the window regains focus- refetchOnWindowFocus: true,- enabled: !!site,});}diff --git a/client/src/api/analytics/hooks/userGetInfo.ts b/client/src/api/analytics/hooks/userGetInfo.tsindex 67887d06a..3cc92b87f 100644--- a/client/src/api/analytics/hooks/userGetInfo.ts+++ b/client/src/api/analytics/hooks/userGetInfo.ts@@ -1,17 +1,20 @@-import { useQuery } from "@tanstack/react-query";import { USER_DETAIL_PAGE_FILTERS } from "../../../lib/filterGroups";-import { getFilteredFilters, useStore } from "../../../lib/store";-import { buildApiParams } from "../../utils";+import { getFilteredFilters } from "../../../lib/store";import { fetchUserInfo, UserInfo } from "../endpoints";+import { useAnalyticsQuery } from "../useAnalyticsQuery";export function useUserInfo(siteId: number, userId: string) {- const { time, timezone } = useStore();const filteredFilters = getFilteredFilters(USER_DETAIL_PAGE_FILTERS);- const params = buildApiParams(time, { filters: filteredFilters });- return useQuery<UserInfo>({- queryKey: ["user-info", userId, siteId, time, filteredFilters, timezone],- queryFn: () => fetchUserInfo(siteId, userId, params),+ return useAnalyticsQuery<UserInfo>({+ // userId must stay at index 1 β useDeleteUser removes ["user-info", userId].+ key: ["user-info", userId],+ site: siteId,+ // customFilters fall back to the store filters when empty; disable filters+ // entirely instead so an empty page-filter set stays unfiltered.+ useFilters: filteredFilters.length > 0,+ customFilters: filteredFilters,enabled: !!siteId && !!userId,+ fetch: (site, params) => fetchUserInfo(site, userId, params),});}diff --git a/client/src/api/analytics/useAnalyticsQuery.ts b/client/src/api/analytics/useAnalyticsQuery.tsnew file mode 100644index 000000000..564f579f3--- /dev/null+++ b/client/src/api/analytics/useAnalyticsQuery.ts@@ -0,0 +1,147 @@+import { Filter } from "@rybbit/shared";+import {+ InfiniteData,+ useInfiniteQuery,+ UseInfiniteQueryResult,+ useQuery,+ UseQueryOptions,+ UseQueryResult,+} from "@tanstack/react-query";+import { Time } from "../../components/DateSelector/types";+import { useStore } from "../../lib/store";+import { buildApiParams } from "../utils";+import { CommonApiParams } from "./endpoints/types";++type PeriodTime = "current" | "previous";++export interface AnalyticsContextOptions {+ // Override the store's current site (e.g. multi-site overview cards).+ site?: number | string;+ periodTime?: PeriodTime;+ // Query a specific time range instead of the store's; ignored when+ // periodTime is "previous" (the store's comparison period wins).+ overrideTime?: Time;+ // Previous period in past-minutes mode means [2x .. 1x] minutes ago.+ doublePastMinutesForPrevious?: boolean;+ useFilters?: boolean;+ // Appended to the store filters.+ additionalFilters?: Filter[];+ // Replace the store filters entirely (when non-empty).+ customFilters?: Filter[];+}++/**+ * Resolves the analytics request context (site, time period, filters) from the+ * store once and derives the wire params from it. The queryKey is built from+ * the same params object that is sent to the endpoint, so it is in sync with+ * the request by construction β a hook can no longer forget to list an input+ * and silently serve stale data.+ */+function useAnalyticsParams(options: AnalyticsContextOptions & { extraParams?: Record<string, unknown> }) {+ const { time, previousTime, site: storeSite, filters } = useStore();+ const site = options.site ?? storeSite;++ const baseTime = options.overrideTime ?? time;+ let timeToUse = options.periodTime === "previous" ? previousTime : baseTime;++ if (options.doublePastMinutesForPrevious && options.periodTime === "previous" && timeToUse.mode === "past-minutes") {+ timeToUse = {+ ...timeToUse,+ pastMinutesStart: timeToUse.pastMinutesStart * 2,+ pastMinutesEnd: timeToUse.pastMinutesStart,+ };+ }++ const useFilters = options.useFilters ?? true;+ const combinedFilters = !useFilters+ ? undefined+ : options.customFilters?.length+ ? options.customFilters+ : options.additionalFilters?.length+ ? [...filters, ...options.additionalFilters]+ : filters;++ const params = { ...buildApiParams(timeToUse, { filters: combinedFilters }), ...options.extraParams };+ return { site, params };+}++export interface AnalyticsQueryOptions<TData, TParams extends CommonApiParams = CommonApiParams>+ extends AnalyticsContextOptions {+ // First element(s) of the queryKey. Keep the historical name β mutations+ // invalidate by this prefix (e.g. ["users"], ["user-info", userId]).+ key: string | readonly unknown[];+ fetch: (site: number | string, params: TParams) => Promise<TData>;+ // Endpoint params beyond the shared time/filter context (bucket, parameter,+ // limit, page, ...). Spread into the wire params AND the queryKey.+ extraParams?: Omit<TParams, keyof CommonApiParams>;+ // ONLY for values that change the fetcher itself rather than its params+ // (e.g. the `lite` flag). Everything else is already in the key via params.+ keyExtras?: readonly unknown[];+ staleTime?: number;+ refetchInterval?: number;+ enabled?: boolean;+ // Same-site placeholder policy: keep showing the previous result while a+ // changed key (time/filter tweak) refetches. Site changes still hard-reset.+ placeholder?: boolean;+ props?: Partial<UseQueryOptions<TData, Error>>;+}++const buildQueryKey = (+ key: string | readonly unknown[],+ site: number | string | undefined,+ params: unknown,+ keyExtras?: readonly unknown[]+) => [...(Array.isArray(key) ? key : [key]), site, params, ...(keyExtras ?? [])];++export function useAnalyticsQuery<TData, TParams extends CommonApiParams = CommonApiParams>(+ options: AnalyticsQueryOptions<TData, TParams>+): UseQueryResult<TData> {+ const { site, params } = useAnalyticsParams(options);+ const queryKey = buildQueryKey(options.key, site, params, options.keyExtras);++ return useQuery<TData, Error>({+ queryKey,+ queryFn: () => options.fetch(site!, params as TParams),+ staleTime: options.staleTime ?? 60_000,+ refetchInterval: options.refetchInterval,+ placeholderData:+ (options.placeholder ?? true)+ ? (previousData, previousQuery) =>+ site !== undefined && previousQuery?.queryKey?.includes(site) ? previousData : undefined+ : undefined,+ enabled: (options.enabled ?? true) && !!site,+ ...options.props,+ });+}++export interface AnalyticsInfiniteQueryOptions<+ TPage extends { data: unknown[]; totalCount: number },+ TParams extends CommonApiParams = CommonApiParams,+> extends AnalyticsContextOptions {+ key: string | readonly unknown[];+ fetchPage: (site: number | string, params: TParams, page: number) => Promise<TPage>;+ extraParams?: Omit<TParams, keyof CommonApiParams>;+ keyExtras?: readonly unknown[];+ staleTime?: number;+ enabled?: boolean;+}++export function useAnalyticsInfiniteQuery<+ TPage extends { data: unknown[]; totalCount: number },+ TParams extends CommonApiParams = CommonApiParams,+>(options: AnalyticsInfiniteQueryOptions<TPage, TParams>): UseInfiniteQueryResult<InfiniteData<TPage>> {+ const { site, params } = useAnalyticsParams(options);+ const queryKey = [...buildQueryKey(options.key, site, params, options.keyExtras), "infinite"];++ return useInfiniteQuery({+ queryKey,+ queryFn: ({ pageParam }) => options.fetchPage(site!, params as TParams, pageParam as number),+ initialPageParam: 1,+ getNextPageParam: (lastPage, allPages) => {+ const fetchedItemCount = allPages.reduce((acc, page) => acc + page.data.length, 0);+ return fetchedItemCount >= lastPage.totalCount ? undefined : allPages.length + 1;+ },+ staleTime: options.staleTime ?? 60_000,+ enabled: (options.enabled ?? true) && !!site,+ });+}diff --git a/server/src/api/analytics/bots/utils.ts b/server/src/api/analytics/bots/utils.tsindex 2d382229b..d98062b48 100644--- a/server/src/api/analytics/bots/utils.ts+++ b/server/src/api/analytics/bots/utils.ts@@ -1,9 +1,14 @@import { FilterParams } from "@rybbit/shared";import SqlString from "sqlstring";-import { FilterParameter, FilterType, TimeBucket } from "../types.js";-import { validateFilters, validateTimeStatementFillParams } from "../utils/query-validation.js";+import { FilterParameter, TimeBucket } from "../types.js";+import { getFilterStatement, getSqlParam } from "../utils/getFilterStatement.js";+import { validateTimeStatementFillParams } from "../utils/query-validation.js";import { bucketIntervalMap, normalizeDatetimeForClickhouse, TimeBucketToFn } from "../utils/utils.js";+// Condition rendering is shared with the events surface; re-exported here for+// existing importers and tests.+export { buildStringFilterCondition } from "../utils/getFilterStatement.js";+export const BOT_LAYER_COLUMNS = {ua_pattern: "detected_ua_pattern",header_heuristics: "detected_header_heuristics",@@ -61,141 +66,25 @@ export function getBotLayerStatement(layer?: string | null) {return column ? `AND ${column}` : "";}-const filterTypeToOperator = (type: FilterType) => {- switch (type) {- case "equals":- return "=";- case "not_equals":- return "!=";- case "contains":- case "starts_with":- case "ends_with":- return "LIKE";- case "not_contains":- return "NOT LIKE";- case "greater_than":- return ">";- case "less_than":- return "<";- case "greater_than_or_equal":- return ">=";- case "less_than_or_equal":- return "<=";- case "regex":- case "not_regex":- case "is_null":- case "is_not_null":- return null;- }-};--const escapeLikePattern = (value: string): string => value.replace(/[\\%_]/g, "\\$&");--const wrapLikeValue = (type: FilterType, value: string | number): string => {- const v = String(value);- if (type === "contains" || type === "not_contains") return `%${escapeLikePattern(v)}%`;- if (type === "starts_with") return `${escapeLikePattern(v)}%`;- if (type === "ends_with") return `%${escapeLikePattern(v)}`;- return v;-};+// Dimension keys that only exist on bot_events; everything else shares the+// events-surface column expressions from getSqlParam.+const BOT_ONLY_DIMENSIONS = new Set<BotDimensionKey>(["asn_org", "bot_category", "matched_ua_pattern"]);export const getBotSqlParam = (parameter: BotDimensionKey) => {- if (parameter === "referrer") {- return "domainWithoutWWW(referrer)";- }- if (parameter === "dimensions") {- return "concat(toString(screen_width), 'x', toString(screen_height))";- }- if (parameter === "city") {- return "concat(toString(region), '-', toString(city))";- }- if (parameter === "browser_version") {- return "concat(toString(browser), ' ', toString(browser_version))";- }- if (parameter === "operating_system_version") {- return `CASE- WHEN concat(toString(operating_system), ' ', toString(operating_system_version)) = 'Windows 10'- THEN 'Windows 10/11'- ELSE concat(toString(operating_system), ' ', toString(operating_system_version))- END`;- }- return parameter;-};--export const buildStringFilterCondition = (expression: string, filterType: FilterType, values: (string | number)[]) => {- if (filterType === "is_null") {- return `(${expression} IS NULL OR ${expression} = '')`;- }- if (filterType === "is_not_null") {- return `(${expression} IS NOT NULL AND ${expression} != '')`;+ if (BOT_ONLY_DIMENSIONS.has(parameter)) {+ return parameter;}-- if (filterType === "regex" || filterType === "not_regex") {- const pattern = String(values[0] ?? "");- if (!pattern) {- throw new Error("Regex pattern cannot be empty");- }- try {- new RegExp(pattern);- } catch (e) {- throw new Error(`Invalid regex pattern: ${e instanceof Error ? e.message : "Unknown error"}`);- }- if (pattern.length > 500) {- throw new Error("Regex pattern too long (max 500 characters)");- }- const matchExpr = `match(${expression}, ${SqlString.escape(pattern)})`;- return filterType === "regex" ? matchExpr : `NOT ${matchExpr}`;- }-- const op = filterTypeToOperator(filterType);- const joiner = filterType === "not_equals" || filterType === "not_contains" ? " AND " : " OR ";- const conditions = values.map(value => `${expression} ${op} ${SqlString.escape(wrapLikeValue(filterType, value))}`);- return conditions.length === 1 ? conditions[0] : `(${conditions.join(joiner)})`;+ return getSqlParam(parameter as FilterParameter);};+// bot_events is a flat table: no session-level subqueries, no+// identified_user_id column, and only a subset of the filterable parameters.export function getBotFilterStatement(filters?: string) {- if (!filters) {- return "";- }-- const filtersArray = validateFilters(filters).filter(filter => BOT_FILTER_PARAMETERS.has(filter.parameter));- if (filtersArray.length === 0) {- return "";- }-- const conditions = filtersArray.map(filter => {- const expression = getBotSqlParam(filter.parameter);- if (filter.type === "is_null" || filter.type === "is_not_null") {- return buildStringFilterCondition(expression, filter.type, filter.value);- }-- if (- filter.type === "greater_than" ||- filter.type === "less_than" ||- filter.type === "greater_than_or_equal" ||- filter.type === "less_than_or_equal"- ) {- const numericValue = Number(filter.value[0]);- if (isNaN(numericValue)) {- throw new Error(`Invalid numeric value for ${filter.type} filter: ${filter.value[0]}`);- }- return `${expression} ${filterTypeToOperator(filter.type)} ${numericValue}`;- }-- if (filter.parameter === "lat" || filter.parameter === "lon") {- const tolerance = 0.001;- const rangeConditions = filter.value.map(value => {- const targetValue = Number(value);- return `(${filter.parameter} >= ${targetValue - tolerance} AND ${filter.parameter} <= ${targetValue + tolerance})`;- });- const rangeCondition = rangeConditions.length === 1 ? rangeConditions[0] : `(${rangeConditions.join(" OR ")})`;- return filter.type === "not_equals" ? `NOT ${rangeCondition}` : rangeCondition;- }-- return buildStringFilterCondition(expression, filter.type, filter.value);+ return getFilterStatement(filters || "", undefined, undefined, {+ sessionLevelParams: [],+ parameterAllowlist: BOT_FILTER_PARAMETERS,+ dualUserIdColumns: false,});-- return `AND ${conditions.join(" AND ")}`;}export function getBotTimeStatementFill(params: FilterParams, bucket: TimeBucket) {diff --git a/server/src/api/analytics/lite/utils.ts b/server/src/api/analytics/lite/utils.tsindex 903b354b7..863e4d815 100644--- a/server/src/api/analytics/lite/utils.ts+++ b/server/src/api/analytics/lite/utils.ts@@ -2,6 +2,7 @@ import { FilterParams } from "@rybbit/shared";import SqlString from "sqlstring";import { FilterType, TimeBucket } from "../types.js";import { TimeBucketToFn, bucketIntervalMap } from "../utils/utils.js";+import { buildStringFilterCondition, wrapLikeValue } from "../utils/getFilterStatement.js";import { validateFilters, validateTimeStatementParams } from "../utils/query-validation.js";// Lite endpoints back the simplified high-traffic dashboard. They read from@@ -45,27 +46,20 @@ const LITE_SESSION_FILTER_COLUMNS: Record<string, string> = {hostname: "hostname",};-const LITE_FILTER_OPERATORS: Record<string, string> = {- equals: "=",- not_equals: "!=",- contains: "LIKE",- not_contains: "NOT LIKE",- starts_with: "LIKE",- ends_with: "LIKE",-};--// Escape LIKE pattern metacharacters in user-supplied values so they match-// literally. Only the % wildcards that wrapLiteLikeValue itself adds around-// the value remain functional.-const escapeLikePattern = (value: string): string => value.replace(/[\\%_]/g, "\\$&");--export function wrapLiteLikeValue(type: FilterType, value: string | number): string {- const v = String(value);- if (type === "contains" || type === "not_contains") return `%${escapeLikePattern(v)}%`;- if (type === "starts_with") return `${escapeLikePattern(v)}%`;- if (type === "ends_with") return `%${escapeLikePattern(v)}`;- return v;-}+// The session rollup can only serve simple string operators; anything else+// (regex, numeric comparisons, lat/lon) forces the raw-events fallback.+const LITE_SUPPORTED_FILTER_TYPES = new Set<FilterType>([+ "equals",+ "not_equals",+ "contains",+ "not_contains",+ "starts_with",+ "ends_with",+]);++// LIKE-value wrapping is shared with the events surface; re-exported under the+// historical lite name for existing importers and tests.+export const wrapLiteLikeValue = wrapLikeValue;// Build a WHERE-clause fragment (prefixed " AND ") against sessions_mv_target// columns. Returns `supported: false` when any filter targets a column or type@@ -82,25 +76,16 @@ export function getLiteSessionFilter(filters: string | undefined): { supported:const column = LITE_SESSION_FILTER_COLUMNS[filter.parameter];if (!column) return { supported: false, sql: "" };- if (filter.type === "is_null") {- conditions.push(`(${column} IS NULL OR ${column} = '')`);- continue;- }- if (filter.type === "is_not_null") {- conditions.push(`(${column} IS NOT NULL AND ${column} != '')`);+ if (filter.type === "is_null" || filter.type === "is_not_null") {+ conditions.push(buildStringFilterCondition(column, filter.type, filter.value));continue;}- const op = LITE_FILTER_OPERATORS[filter.type];- if (!op || filter.value.length === 0) return { supported: false, sql: "" };+ if (!LITE_SUPPORTED_FILTER_TYPES.has(filter.type) || filter.value.length === 0) {+ return { supported: false, sql: "" };+ }- const parts = filter.value.map(- value => `${column} ${op} ${SqlString.escape(wrapLiteLikeValue(filter.type, value))}`- );- // Negative filters must AND-join across values (NOT IN semantics): OR-joining- // negations is a tautology β (x != 'a' OR x != 'b') matches every row.- const joiner = filter.type === "not_equals" || filter.type === "not_contains" ? " AND " : " OR ";- conditions.push(parts.length === 1 ? parts[0] : `(${parts.join(joiner)})`);+ conditions.push(buildStringFilterCondition(column, filter.type, filter.value));}return { supported: true, sql: conditions.length ? `AND ${conditions.join(" AND ")}` : "" };diff --git a/server/src/api/analytics/utils/getFilterStatement.ts b/server/src/api/analytics/utils/getFilterStatement.tsindex 6c1efe90e..7ddd71540 100644--- a/server/src/api/analytics/utils/getFilterStatement.ts+++ b/server/src/api/analytics/utils/getFilterStatement.ts@@ -17,6 +17,17 @@ export interface FilterStatementOptions {// output); the mapping is applied where column identifiers are produced, so// user-supplied filter values are never rewritten.fieldMappings?: Record<string, string>;++ // When set, filters on parameters outside this list are silently dropped.+ // Used by surfaces (e.g. bot_events) whose table carries only a subset of+ // the filterable columns.+ parameterAllowlist?: ReadonlySet<FilterParameter>;++ // user_id filters normally match user_id OR identified_user_id, because URLs+ // may carry either the device fingerprint or the custom identified ID.+ // Surfaces whose table has no identified_user_id column (bot_events) set+ // this to false to treat user_id as a plain column. Default: true.+ dualUserIdColumns?: boolean;}const DEFAULT_SESSION_LEVEL_PARAMS: FilterParameter[] = ["event_name", "channel"];@@ -54,7 +65,7 @@ const filterTypeToOperator = (type: FilterType) => {// value remain functional.const escapeLikePattern = (value: string): string => value.replace(/[\\%_]/g, "\\$&");-const wrapLikeValue = (type: FilterType, value: string | number): string => {+export const wrapLikeValue = (type: FilterType, value: string | number): string => {const v = String(value);if (type === "contains" || type === "not_contains") return `%${escapeLikePattern(v)}%`;if (type === "starts_with") return `${escapeLikePattern(v)}%`;@@ -62,6 +73,58 @@ const wrapLikeValue = (type: FilterType, value: string | number): string => {return v;};+// Renders one filter condition against a column expression: null checks,+// validated regex matches, and (NOT) LIKE / comparison operators with+// NOT-IN-style AND-joining for negative filters. Shared by every filterβSQL+// surface (events, bots, lite) so escaping and joiner semantics can only be+// fixed in one place.+export const buildStringFilterCondition = (+ expression: string,+ filterType: FilterType,+ values: (string | number)[]+): string => {+ if (filterType === "is_null") {+ return `(${expression} IS NULL OR ${expression} = '')`;+ }+ if (filterType === "is_not_null") {+ return `(${expression} IS NOT NULL AND ${expression} != '')`;+ }++ if (filterType === "regex" || filterType === "not_regex") {+ const pattern = String(values[0] ?? "");++ if (!pattern) {+ throw new Error("Regex pattern cannot be empty");+ }++ try {+ new RegExp(pattern);+ } catch (e) {+ throw new Error(`Invalid regex pattern: ${e instanceof Error ? e.message : "Unknown error"}`);+ }++ if (pattern.length > 500) {+ throw new Error("Regex pattern too long (max 500 characters)");+ }++ const matchExpr = `match(${expression}, ${SqlString.escape(pattern)})`;+ return filterType === "regex" ? matchExpr : `NOT ${matchExpr}`;+ }++ const op = filterTypeToOperator(filterType);+ // Negative filters must AND-join across values (NOT IN semantics): OR-joining+ // negations is a tautology β (x != 'a' OR x != 'b') matches every row.+ const joiner = filterType === "not_equals" || filterType === "not_contains" ? " AND " : " OR ";+ const condition =+ values.length === 1+ ? `${expression} ${op} ${SqlString.escape(wrapLikeValue(filterType, values[0]))}`+ : `(${values+ .map(value => `${expression} ${op} ${SqlString.escape(wrapLikeValue(filterType, value))}`)+ .join(joiner)})`;++ return condition;+};+export const getSqlParam = (parameter: FilterParameter) => {if (parameter.startsWith("feature_flag:")) {const key = parameter.substring("feature_flag:".length);@@ -121,7 +184,8 @@ export function getFilterStatement(}// Sanitize inputs with Zod- const filtersArray = validateFilters(filters);+ const allowlist = options?.parameterAllowlist;+ const filtersArray = validateFilters(filters).filter(filter => !allowlist || allowlist.has(filter.parameter));if (filtersArray.length === 0) {return "";@@ -138,67 +202,18 @@ export function getFilterStatement(// Strip leading "AND " from timeStatement since we'll be constructing WHERE clausesconst timeFilter = timeStatement ? timeStatement.replace(/^AND\s+/i, "").trim() : "";- const buildStringFilterCondition = (- expression: string,- filterType: FilterType,- values: (string | number)[],- _legacyWildcardPrefix?: string- ): string => {- if (filterType === "is_null") {- return `(${expression} IS NULL OR ${expression} = '')`;- }- if (filterType === "is_not_null") {- return `(${expression} IS NOT NULL AND ${expression} != '')`;- }-- if (filterType === "regex" || filterType === "not_regex") {- const pattern = String(values[0] ?? "");-- if (!pattern) {- throw new Error("Regex pattern cannot be empty");- }-- try {- new RegExp(pattern);- } catch (e) {- throw new Error(`Invalid regex pattern: ${e instanceof Error ? e.message : "Unknown error"}`);- }-- if (pattern.length > 500) {- throw new Error("Regex pattern too long (max 500 characters)");- }-- const matchExpr = `match(${expression}, ${SqlString.escape(pattern)})`;- return filterType === "regex" ? matchExpr : `NOT ${matchExpr}`;- }-- const op = filterTypeToOperator(filterType);- // Negative filters must AND-join across values (NOT IN semantics): OR-joining- // negations is a tautology β (x != 'a' OR x != 'b') matches every row.- const joiner = filterType === "not_equals" || filterType === "not_contains" ? " AND " : " OR ";- const condition =- values.length === 1- ? `${expression} ${op} ${SqlString.escape(wrapLikeValue(filterType, values[0]))}`- : `(${values- .map(value => `${expression} ${op} ${SqlString.escape(wrapLikeValue(filterType, value))}`)- .join(joiner)})`;-- return condition;- };-// Helper to build session-level subquery for a parameterconst buildSessionLevelSubquery = (param: FilterParameter,filterType: FilterType,- values: (string | number)[],- wildcardPrefix: string+ values: (string | number)[]): string => {const whereClause = [siteIdFilter, timeFilter].filter(Boolean).join(" AND ");// getSqlParam keeps transformed params (city, browser_version, ...) correct// inside the subquery. fieldMappings deliberately do NOT apply here: the// subquery selects from the raw events table, where the caller's CTE// aliases don't exist.- const condition = buildStringFilterCondition(getSqlParam(param), filterType, values, wildcardPrefix);+ const condition = buildStringFilterCondition(getSqlParam(param), filterType, values);const finalWhere = whereClause ? `WHERE ${whereClause} AND ${condition}` : `WHERE ${condition}`;@@ -209,14 +224,10 @@ export function getFilterStatement()`;};- const buildSessionChannelSubquery = (- filterType: FilterType,- values: (string | number)[],- wildcardPrefix: string- ): string => {+ const buildSessionChannelSubquery = (filterType: FilterType, values: (string | number)[]): string => {const whereClause = [siteIdFilter, timeFilter].filter(Boolean).join(" AND ");const whereStatement = whereClause ? `WHERE ${whereClause}` : "";- const condition = buildStringFilterCondition("session_channel", filterType, values, wildcardPrefix);+ const condition = buildStringFilterCondition("session_channel", filterType, values);return `session_id IN (SELECT session_id@@ -236,7 +247,6 @@ export function getFilterStatement("AND " +filtersArray.map(filter => {- const x = filter.type === "contains" || filter.type === "not_contains" ? "%" : "";const isNumericParam = filter.parameter === "lat" || filter.parameter === "lon";const isNullCheck = filter.type === "is_null" || filter.type === "is_not_null";@@ -244,10 +254,10 @@ export function getFilterStatement(// Most parameters match sessions containing an event; channel uses the session's first attributed value.if (sessionLevelParams.includes(filter.parameter)) {if (filter.parameter === "channel") {- return buildSessionChannelSubquery(filter.type, filter.value, x);+ return buildSessionChannelSubquery(filter.type, filter.value);}- return buildSessionLevelSubquery(filter.parameter, filter.type, filter.value, x);+ return buildSessionLevelSubquery(filter.parameter, filter.type, filter.value);}if (filter.parameter === "entry_page") {@@ -291,7 +301,7 @@ export function getFilterStatement(// Special handling for user_id to also check identified_user_id// This is needed because URLs may contain either the device fingerprint (user_id)// or the custom identified user ID (identified_user_id)- if (filter.parameter === "user_id") {+ if (filter.parameter === "user_id" && (options?.dualUserIdColumns ?? true)) {if (filter.type === "is_null") {return `((user_id IS NULL OR user_id = '') AND (identified_user_id IS NULL OR identified_user_id = ''))`;}@@ -327,7 +337,7 @@ export function getFilterStatement(}if (filter.type === "regex" || filter.type === "not_regex") {- return buildStringFilterCondition(mapField(getSqlParam(filter.parameter)), filter.type, filter.value, x);+ return buildStringFilterCondition(mapField(getSqlParam(filter.parameter)), filter.type, filter.value);}// Handle numeric comparison filters (>, <, >=, <=)