Skip to content

🐸 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.md
new file mode 100644
index 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 fetch
diff --git a/client/CLAUDE.md b/client/CLAUDE.md
index 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 Management
diff --git a/client/src/api/CLAUDE.md b/client/src/api/CLAUDE.md
index 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*` prefixes
diff --git a/client/src/api/analytics/hooks/bots/useGetBotDimension.ts b/client/src/api/analytics/hooks/bots/useGetBotDimension.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 compatibility
export 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 dependencies
const 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 clauses
const 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 parameter
const 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 (>, <, >=, <=)