Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Implement generic `FilterParams` type across analytics API endpoints to enhance type safety and maintainability. Updated multiple request interfaces to utilize the new `FilterParams` type, allowing for flexible extension of query parameters while ensuring backward compatibility. This change resolves TypeScript errors and streamlines the handling of filtering parameters throughout the codebase.

Bill Yang11b0c47db4da
diff --git a/memory-bank/decisionLog.md b/memory-bank/decisionLog.md
index 2e897d89a..9fd4fd7dd 100644
--- a/memory-bank/decisionLog.md
+++ b/memory-bank/decisionLog.md
@@ -128,3 +128,27 @@ User requested to add support for the past 24-hour mode to useGetPerformanceTime
- [`SiteCard.tsx`](client/src/components/SiteCard.tsx:1) - Replaced `useGetOverviewPastMinutes` with `useGetOverview`
- [`Overview.tsx`](client/src/app/[site]/main/components/MainSection/Overview.tsx:1) - Replaced both instances of `useGetOverviewPastMinutes` with `useGetOverview`
- **Impact**: Eliminated TypeScript errors and completed hook consolidation across the codebase
+
+[2025-06-09 17:59:00] - **Generic Interface Implementation: FilterParams Type Conversion**
+
+## Decision
+
+Converted the `FilterParams` interface into a generic type using intersection types to allow extending with additional properties.
+
+## Rationale
+
+User requested to make the existing `FilterParams` interface generic so it could be extended with additional properties like `FilterParams<{something: number}>`. The original interface-based approach with `extends` didn't properly merge the generic type parameter, causing TypeScript errors when trying to access properties from the generic type.
+
+## Implementation Details
+
+- Changed from `export interface FilterParams<T = {}> extends BaseParams {}` to `export type FilterParams<T = {}> = BaseParams & T`
+- Used intersection types (`&`) instead of interface extension to properly merge the base properties with the generic type parameter
+- Maintained `BaseParams` interface for the core filtering properties (startDate, endDate, timeZone, filters, pastMinutesStart, pastMinutesEnd)
+- Added `OverviewParams<T>` as an alias for backward compatibility
+- This allows proper type safety when using `FilterParams<{bucket: TimeBucket}>` where both base properties and the `bucket` property are accessible
+
+## Impact
+
+- Enables type-safe extension of filtering parameters across the analytics API
+- Maintains backward compatibility with existing code
+- Fixes TypeScript errors in files like [`getPerformanceTimeSeries.ts`](server/src/api/analytics/performance/getPerformanceTimeSeries.ts:187) that use extended filter parameters
diff --git a/server/src/api/analytics/events/getEventNames.ts b/server/src/api/analytics/events/getEventNames.ts
index 7cc806c60..889d6ae25 100644
--- a/server/src/api/analytics/events/getEventNames.ts
+++ b/server/src/api/analytics/events/getEventNames.ts
@@ -6,6 +6,7 @@ import {
getFilterStatement,
} from "../utils.js";
import { getUserHasAccessToSitePublic } from "../../../lib/auth-utils.js";
+import { FilterParams } from "@rybbit/shared";
export type GetEventNamesResponse = {
eventName: string;
@@ -16,14 +17,9 @@ export interface GetEventNamesRequest {
Params: {
site: string;
};
- Querystring: {
- startDate?: string;
- endDate?: string;
- timeZone: string;
- filters?: string;
- pastMinutesStart?: string;
- pastMinutesEnd?: string;
- };
+ Querystring: FilterParams<{
+ eventName: string;
+ }>;
}
export async function getEventNames(
diff --git a/server/src/api/analytics/events/getEventProperties.ts b/server/src/api/analytics/events/getEventProperties.ts
index 1aa7b2a55..5182d15ae 100644
--- a/server/src/api/analytics/events/getEventProperties.ts
+++ b/server/src/api/analytics/events/getEventProperties.ts
@@ -6,6 +6,7 @@ import {
getFilterStatement,
} from "../utils.js";
import { getUserHasAccessToSitePublic } from "../../../lib/auth-utils.js";
+import { FilterParams } from "@rybbit/shared";
export type GetEventPropertiesResponse = {
propertyKey: string;
@@ -17,15 +18,9 @@ export interface GetEventPropertiesRequest {
Params: {
site: string;
};
- Querystring: {
- startDate?: string;
- endDate?: string;
- timeZone: string;
+ Querystring: FilterParams<{
eventName: string;
- filters?: string;
- pastMinutesStart?: string;
- pastMinutesEnd?: string;
- };
+ }>;
}
export async function getEventProperties(
diff --git a/server/src/api/analytics/getOverview.ts b/server/src/api/analytics/getOverview.ts
index 4a28d5455..dd211395b 100644
--- a/server/src/api/analytics/getOverview.ts
+++ b/server/src/api/analytics/getOverview.ts
@@ -7,6 +7,7 @@ import {
} from "./utils.js";
import { getUserHasAccessToSitePublic } from "../../lib/auth-utils.js";
import { FilterParameter } from "./types.js";
+import { FilterParams } from "@rybbit/shared";
type GetOverviewResponse = {
sessions: number;
@@ -86,16 +87,7 @@ export interface OverviewRequest {
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- timeZone: string;
- filters: string;
- parameter: FilterParameter;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- limit?: number;
- };
+ Querystring: FilterParams;
}
export async function getOverview(
diff --git a/server/src/api/analytics/getOverviewBucketed.ts b/server/src/api/analytics/getOverviewBucketed.ts
index 61bb4b888..e7822d7d0 100644
--- a/server/src/api/analytics/getOverviewBucketed.ts
+++ b/server/src/api/analytics/getOverviewBucketed.ts
@@ -1,13 +1,14 @@
+import { FilterParams } from "@rybbit/shared";
import { FastifyReply, FastifyRequest } from "fastify";
+import SqlString from "sqlstring";
import clickhouse from "../../db/clickhouse/clickhouse.js";
+import { getUserHasAccessToSitePublic } from "../../lib/auth-utils.js";
+import { validateTimeStatementFillParams } from "./query-validation.js";
import {
getFilterStatement,
getTimeStatement,
processResults,
} from "./utils.js";
-import SqlString from "sqlstring";
-import { getUserHasAccessToSitePublic } from "../../lib/auth-utils.js";
-import { validateTimeStatementFillParams } from "./query-validation.js";
const TimeBucketToFn = {
minute: "toStartOfMinute",
@@ -217,15 +218,9 @@ export async function getOverviewBucketed(
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- timeZone: string;
+ Querystring: FilterParams<{
bucket: TimeBucket;
- filters: string;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- };
+ }>;
}>,
res: FastifyReply
) {
diff --git a/server/src/api/analytics/getPageTitles.ts b/server/src/api/analytics/getPageTitles.ts
index 986f162d0..60ae60a8a 100644
--- a/server/src/api/analytics/getPageTitles.ts
+++ b/server/src/api/analytics/getPageTitles.ts
@@ -6,21 +6,16 @@ import {
getTimeStatement,
processResults,
} from "./utils.js";
+import { FilterParams } from "@rybbit/shared";
interface GetPageTitlesRequest {
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- timeZone: string;
- filters: string;
+ Querystring: FilterParams<{
limit?: number;
page?: number;
- };
+ }>;
}
// This type represents a single item in the array
diff --git a/server/src/api/analytics/getSessions.ts b/server/src/api/analytics/getSessions.ts
index d7635c48d..4647b3083 100644
--- a/server/src/api/analytics/getSessions.ts
+++ b/server/src/api/analytics/getSessions.ts
@@ -6,6 +6,7 @@ import {
processResults,
} from "./utils.js";
import { getUserHasAccessToSitePublic } from "../../lib/auth-utils.js";
+import { FilterParams } from "@rybbit/shared";
export type GetSessionsResponse = {
session_id: string;
@@ -37,16 +38,10 @@ export interface GetSessionsRequest {
Params: {
site: string;
};
- Querystring: {
- startDate?: string;
- endDate?: string;
- timeZone: string;
- filters: string;
+ Querystring: FilterParams<{
page: number;
userId?: string;
- pastMinutesStart?: string;
- pastMinutesEnd?: string;
- };
+ }>;
}
export async function getSessions(
diff --git a/server/src/api/analytics/getSingleCol.ts b/server/src/api/analytics/getSingleCol.ts
index 5ad9461c9..7da60e64f 100644
--- a/server/src/api/analytics/getSingleCol.ts
+++ b/server/src/api/analytics/getSingleCol.ts
@@ -8,22 +8,17 @@ import {
getTimeStatement,
processResults,
} from "./utils.js";
+import { FilterParams } from "@rybbit/shared";
interface GetSingleColRequest {
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- timeZone: string;
- filters: string;
+ Querystring: FilterParams<{
parameter: FilterParameter;
limit?: number;
page?: number;
- };
+ }>;
}
type GetSingleColResponse = {
diff --git a/server/src/api/analytics/getUsers.ts b/server/src/api/analytics/getUsers.ts
index 7ebd09ca4..81d056220 100644
--- a/server/src/api/analytics/getUsers.ts
+++ b/server/src/api/analytics/getUsers.ts
@@ -6,6 +6,7 @@ import {
processResults,
} from "./utils.js";
import { getUserHasAccessToSitePublic } from "../../lib/auth-utils.js";
+import { FilterParams } from "@rybbit/shared";
export type GetUsersResponse = {
user_id: string;
@@ -27,18 +28,12 @@ export interface GetUsersRequest {
Params: {
site: string;
};
- Querystring: {
- startDate?: string;
- endDate?: string;
- timeZone: string;
- filters: string;
+ Querystring: FilterParams<{
page?: string;
pageSize?: string;
sortBy?: string;
sortOrder?: string;
- pastMinutesStart?: string;
- pastMinutesEnd?: string;
- };
+ }>;
}
export async function getUsers(
diff --git a/server/src/api/analytics/goals/getGoals.ts b/server/src/api/analytics/goals/getGoals.ts
index f94404636..0bbed1f6f 100644
--- a/server/src/api/analytics/goals/getGoals.ts
+++ b/server/src/api/analytics/goals/getGoals.ts
@@ -11,6 +11,7 @@ import {
patternToRegex,
} from "../utils.js";
import SqlString from "sqlstring";
+import { FilterParams } from "@rybbit/shared";
// Types for the response
interface GoalWithConversions {
@@ -39,18 +40,12 @@ export async function getGoals(
Params: {
site: string;
};
- Querystring: {
- startDate?: string;
- endDate?: string;
- timeZone: string;
- filters?: string;
+ Querystring: FilterParams<{
page?: string;
pageSize?: string;
sort?: string;
order?: "asc" | "desc";
- pastMinutesStart?: string;
- pastMinutesEnd?: string;
- };
+ }>;
}>,
reply: FastifyReply
) {
diff --git a/server/src/api/analytics/performance/getPerformanceByDimension.ts b/server/src/api/analytics/performance/getPerformanceByDimension.ts
index c38d1e5f6..3e0b516a2 100644
--- a/server/src/api/analytics/performance/getPerformanceByDimension.ts
+++ b/server/src/api/analytics/performance/getPerformanceByDimension.ts
@@ -6,24 +6,19 @@ import {
getTimeStatement,
processResults,
} from "../utils.js";
+import { FilterParams } from "@rybbit/shared";
interface GetPerformanceByDimensionRequest {
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- timeZone: string;
- filters: string;
+ Querystring: FilterParams<{
limit?: number;
page?: number;
sortBy?: string;
sortOrder?: "asc" | "desc";
dimension: string;
- };
+ }>;
}
// Generic type for performance by dimension
diff --git a/server/src/api/analytics/performance/getPerformanceOverview.ts b/server/src/api/analytics/performance/getPerformanceOverview.ts
index 80036ea6d..f9f15dfb2 100644
--- a/server/src/api/analytics/performance/getPerformanceOverview.ts
+++ b/server/src/api/analytics/performance/getPerformanceOverview.ts
@@ -7,6 +7,7 @@ import {
} from "../utils.js";
import { getUserHasAccessToSitePublic } from "../../../lib/auth-utils.js";
import { PerformanceOverviewMetrics } from "../types.js";
+import { FilterParams } from "@rybbit/shared";
const getQuery = ({
startDate,
@@ -61,14 +62,7 @@ export interface PerformanceOverviewRequest {
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- timeZone: string;
- filters: string;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- };
+ Querystring: FilterParams;
}
export async function getPerformanceOverview(
diff --git a/server/src/api/analytics/performance/getPerformanceTimeSeries.ts b/server/src/api/analytics/performance/getPerformanceTimeSeries.ts
index 8c5ecfa85..b3a926ae8 100644
--- a/server/src/api/analytics/performance/getPerformanceTimeSeries.ts
+++ b/server/src/api/analytics/performance/getPerformanceTimeSeries.ts
@@ -9,6 +9,7 @@ import SqlString from "sqlstring";
import { getUserHasAccessToSitePublic } from "../../../lib/auth-utils.js";
import { validateTimeStatementFillParams } from "../query-validation.js";
import { TimeBucket, PerformanceTimeSeriesPoint } from "../types.js";
+import { FilterParams } from "@rybbit/shared";
const TimeBucketToFn = {
minute: "toStartOfMinute",
@@ -132,7 +133,6 @@ const getQuery = ({
const filterStatement = getFilterStatement(filters);
const isAllTime = !startDate && !endDate && !pastMinutesRange;
- console.log(pastMinutesRange);
const timeParams = pastMinutesRange
? { pastMinutesRange }
@@ -184,15 +184,9 @@ export async function getPerformanceTimeSeries(
Params: {
site: string;
};
- Querystring: {
- startDate: string;
- endDate: string;
- timeZone: string;
+ Querystring: FilterParams<{
bucket: TimeBucket;
- filters: string;
- pastMinutesStart?: number;
- pastMinutesEnd?: number;
- };
+ }>;
}>,
res: FastifyReply
) {
diff --git a/shared/src/index.ts b/shared/src/index.ts
index 31c424999..f2c217795 100644
--- a/shared/src/index.ts
+++ b/shared/src/index.ts
@@ -1,8 +1,4 @@
export * from "./filters";
+export * from "./params";
export * from "./time";
export * from "./performance";
-// export * from "./goals";
-// export * from "./funnels";
-// export * from "./pagination";
-// export * from "./analytics";
-// export * from "./events";
diff --git a/shared/src/params.ts b/shared/src/params.ts
new file mode 100644
index 000000000..d8372d370
--- /dev/null
+++ b/shared/src/params.ts
@@ -0,0 +1,10 @@
+export interface BaseParams {
+ startDate: string;
+ endDate: string;
+ timeZone: string;
+ filters: string;
+ pastMinutesStart?: number;
+ pastMinutesEnd?: number;
+}
+
+export type FilterParams<T = {}> = BaseParams & T;