Skip to content

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

Worktree backend tier1 tests (#1053)

Goldflag738d570e8ef5
diff --git a/server/src/api/analytics/bots/utils.test.ts b/server/src/api/analytics/bots/utils.test.ts
new file mode 100644
index 000000000..08605b789
--- /dev/null
+++ b/server/src/api/analytics/bots/utils.test.ts
@@ -0,0 +1,380 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../../db/postgres/postgres.js", () => ({
+ db: {},
+ sql: {},
+}));
+
+import { TimeBucket } from "../types.js";
+import {
+ buildStringFilterCondition,
+ getBotFilterStatement,
+ getBotLayerStatement,
+ getBotSqlParam,
+ getBotTimeStatementFill,
+} from "./utils.js";
+
+const normalize = (sql: string) => sql.replace(/\s+/g, " ").trim();
+
+type FillParams = Parameters<typeof getBotTimeStatementFill>[0];
+const fillParams = (p: Record<string, unknown>) => p as unknown as FillParams;
+
+describe("getBotLayerStatement", () => {
+ it("should return empty string for undefined layer", () => {
+ expect(getBotLayerStatement(undefined)).toBe("");
+ });
+
+ it("should return empty string for null layer", () => {
+ expect(getBotLayerStatement(null)).toBe("");
+ });
+
+ it("should return empty string for empty string layer", () => {
+ expect(getBotLayerStatement("")).toBe("");
+ });
+
+ it("should map each known layer to its detection column", () => {
+ expect(getBotLayerStatement("ua_pattern")).toBe("AND detected_ua_pattern");
+ expect(getBotLayerStatement("header_heuristics")).toBe("AND detected_header_heuristics");
+ expect(getBotLayerStatement("client_signals")).toBe("AND detected_client_signals");
+ expect(getBotLayerStatement("bot_asn")).toBe("AND detected_bot_asn");
+ expect(getBotLayerStatement("rate_anomaly")).toBe("AND detected_rate_anomaly");
+ });
+
+ it("silently returns empty string for an unmapped layer string", () => {
+ // Pinned behavior: an unknown layer is a silent no-op β€” the caller gets no
+ // filter and no error, so a typo'd layer returns unfiltered data.
+ expect(getBotLayerStatement("nonsense_layer")).toBe("");
+ expect(getBotLayerStatement("ua_pattern; DROP TABLE events")).toBe("");
+ });
+});
+
+describe("getBotSqlParam", () => {
+ it("should use domainWithoutWWW for referrer", () => {
+ expect(getBotSqlParam("referrer")).toBe("domainWithoutWWW(referrer)");
+ });
+
+ it("should use concat for dimensions", () => {
+ expect(getBotSqlParam("dimensions")).toBe("concat(toString(screen_width), 'x', toString(screen_height))");
+ });
+
+ it("should use region-city concat for city", () => {
+ expect(getBotSqlParam("city")).toBe("concat(toString(region), '-', toString(city))");
+ });
+
+ it("should use browser concat for browser_version", () => {
+ expect(getBotSqlParam("browser_version")).toBe("concat(toString(browser), ' ', toString(browser_version))");
+ });
+
+ it("should use CASE expression for operating_system_version", () => {
+ const result = getBotSqlParam("operating_system_version");
+ expect(result).toContain("CASE");
+ expect(result).toContain("Windows 10/11");
+ });
+
+ it("should pass through standard and bot-specific parameters", () => {
+ expect(getBotSqlParam("browser")).toBe("browser");
+ expect(getBotSqlParam("pathname")).toBe("pathname");
+ expect(getBotSqlParam("asn_org")).toBe("asn_org");
+ expect(getBotSqlParam("bot_category")).toBe("bot_category");
+ expect(getBotSqlParam("matched_ua_pattern")).toBe("matched_ua_pattern");
+ });
+});
+
+describe("buildStringFilterCondition", () => {
+ it("should build is_null condition", () => {
+ expect(buildStringFilterCondition("browser", "is_null", [])).toBe("(browser IS NULL OR browser = '')");
+ });
+
+ it("should build is_not_null condition", () => {
+ expect(buildStringFilterCondition("browser", "is_not_null", [])).toBe("(browser IS NOT NULL AND browser != '')");
+ });
+
+ it("should build single-value equals condition", () => {
+ expect(buildStringFilterCondition("browser", "equals", ["Chrome"])).toBe("browser = 'Chrome'");
+ });
+
+ it("should OR-join multi-value contains conditions", () => {
+ expect(buildStringFilterCondition("pathname", "contains", ["/blog", "/docs"])).toBe(
+ "(pathname LIKE '%/blog%' OR pathname LIKE '%/docs%')"
+ );
+ });
+
+ it("should AND-join multi-value not_contains conditions", () => {
+ expect(buildStringFilterCondition("pathname", "not_contains", ["/admin", "/debug"])).toBe(
+ "(pathname NOT LIKE '%/admin%' AND pathname NOT LIKE '%/debug%')"
+ );
+ });
+
+ it("should build regex condition with match()", () => {
+ expect(buildStringFilterCondition("pathname", "regex", ["^/blog/.*"])).toBe("match(pathname, '^/blog/.*')");
+ });
+
+ it("should build not_regex condition with NOT match()", () => {
+ expect(buildStringFilterCondition("pathname", "not_regex", ["^/admin/.*"])).toBe(
+ "NOT match(pathname, '^/admin/.*')"
+ );
+ });
+
+ it("should throw for empty regex pattern", () => {
+ expect(() => buildStringFilterCondition("pathname", "regex", [""])).toThrow("Regex pattern cannot be empty");
+ });
+
+ it("wraps invalid regex errors with the same message as the main filter builder", () => {
+ expect(() => buildStringFilterCondition("pathname", "regex", ["[invalid"])).toThrow("Invalid regex pattern");
+ });
+
+ it("should throw for regex pattern exceeding max length", () => {
+ const longPattern = "a".repeat(501);
+ expect(() => buildStringFilterCondition("pathname", "regex", [longPattern])).toThrow("Regex pattern too long");
+ });
+});
+
+describe("getBotFilterStatement", () => {
+ describe("Empty and invalid inputs", () => {
+ it("should return empty string when filters are undefined", () => {
+ expect(getBotFilterStatement()).toBe("");
+ });
+
+ it("should return empty string for empty string", () => {
+ expect(getBotFilterStatement("")).toBe("");
+ });
+
+ it("should return empty string for empty array", () => {
+ expect(getBotFilterStatement("[]")).toBe("");
+ });
+
+ it("should throw for invalid JSON", () => {
+ expect(() => getBotFilterStatement("invalid json")).toThrow("Invalid JSON format");
+ });
+ });
+
+ describe("Parameter allowlist", () => {
+ it("silently drops filters whose parameter is not in BOT_FILTER_PARAMETERS", () => {
+ // Pinned behavior: unsupported parameters are filtered out without error,
+ // so a caller filtering by event_name gets unfiltered data back.
+ const filters = JSON.stringify([{ parameter: "event_name", type: "equals", value: ["click"] }]);
+ expect(getBotFilterStatement(filters)).toBe("");
+ });
+
+ it("silently drops channel, utm and entry/exit page filters", () => {
+ const filters = JSON.stringify([
+ { parameter: "channel", type: "equals", value: ["Organic Search"] },
+ { parameter: "utm_source", type: "equals", value: ["google"] },
+ { parameter: "entry_page", type: "equals", value: ["/home"] },
+ { parameter: "exit_page", type: "equals", value: ["/bye"] },
+ ]);
+ expect(getBotFilterStatement(filters)).toBe("");
+ });
+
+ it("keeps supported parameters while dropping unsupported ones", () => {
+ const filters = JSON.stringify([
+ { parameter: "event_name", type: "equals", value: ["click"] },
+ { parameter: "browser", type: "equals", value: ["Chrome"] },
+ ]);
+ expect(getBotFilterStatement(filters)).toBe("AND browser = 'Chrome'");
+ });
+ });
+
+ describe("Operator cases mirrored from the main filter builder", () => {
+ it("should handle single value equals filter", () => {
+ const filters = JSON.stringify([{ parameter: "browser", type: "equals", value: ["Chrome"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND browser = 'Chrome'");
+ });
+
+ it("should OR-join multiple equals values", () => {
+ const filters = JSON.stringify([{ parameter: "browser", type: "equals", value: ["Chrome", "Firefox"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND (browser = 'Chrome' OR browser = 'Firefox')");
+ });
+
+ it("should AND-join multiple not_equals values (NOT IN semantics)", () => {
+ const filters = JSON.stringify([{ parameter: "browser", type: "not_equals", value: ["Chrome", "Firefox"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND (browser != 'Chrome' AND browser != 'Firefox')");
+ });
+
+ it("should handle contains with % wrapping", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "contains", value: ["/blog"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND pathname LIKE '%/blog%'");
+ });
+
+ it("should handle not_contains", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "not_contains", value: ["/admin"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND pathname NOT LIKE '%/admin%'");
+ });
+
+ it("should handle starts_with, escaping user wildcards like the main builder", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "starts_with", value: ["50%"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND pathname LIKE '50\\\\%%'");
+ });
+
+ it("should handle ends_with", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "ends_with", value: ["/checkout"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND pathname LIKE '%/checkout'");
+ });
+
+ it("should handle is_null", () => {
+ const filters = JSON.stringify([{ parameter: "browser", type: "is_null", value: [] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND (browser IS NULL OR browser = '')");
+ });
+
+ it("should handle is_not_null", () => {
+ const filters = JSON.stringify([{ parameter: "country", type: "is_not_null", value: [] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND (country IS NOT NULL AND country != '')");
+ });
+
+ it("should handle regex filters", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "regex", value: ["^/blog/.*"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND match(pathname, '^/blog/.*')");
+ });
+
+ it("should handle not_regex filters", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "not_regex", value: ["^/admin/.*"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND NOT match(pathname, '^/admin/.*')");
+ });
+
+ it("should handle greater_than_or_equal", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "greater_than_or_equal", value: ["40.5"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND lat >= 40.5");
+ });
+
+ it("should handle less_than_or_equal", () => {
+ const filters = JSON.stringify([{ parameter: "lon", type: "less_than_or_equal", value: ["-70.25"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND lon <= -70.25");
+ });
+
+ it("should throw for invalid numeric values", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "greater_than", value: ["not-a-number"] }]);
+ expect(() => getBotFilterStatement(filters)).toThrow("Invalid numeric value");
+ });
+
+ it("should handle lat equals with tolerance", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "equals", value: ["40.7128"] }]);
+ const result = getBotFilterStatement(filters);
+ expect(result).toContain("lat >= 40.7118");
+ expect(result).toContain("lat <= 40.7138");
+ });
+
+ it("should negate the lat/lon range for not_equals", () => {
+ const filters = JSON.stringify([{ parameter: "lon", type: "not_equals", value: ["-74.006"] }]);
+ const result = getBotFilterStatement(filters);
+ expect(result).toContain("NOT (lon >= -74.007 AND lon <= -74.005)");
+ });
+
+ it("should escape single quotes in values", () => {
+ const filters = JSON.stringify([
+ { parameter: "browser", type: "equals", value: ["Chrome'; DROP TABLE users;--"] },
+ ]);
+ expect(getBotFilterStatement(filters)).toBe("AND browser = 'Chrome\\'; DROP TABLE users;--'");
+ });
+
+ it("should join multiple filters with AND", () => {
+ const filters = JSON.stringify([
+ { parameter: "browser", type: "equals", value: ["Chrome"] },
+ { parameter: "country", type: "not_equals", value: ["CN"] },
+ ]);
+ expect(getBotFilterStatement(filters)).toBe("AND browser = 'Chrome' AND country != 'CN'");
+ });
+
+ it("does NOT check identified_user_id for user_id filters, unlike the main builder", () => {
+ // Structural divergence, not fixable drift: the bot_events ClickHouse
+ // table (src/db/clickhouse/clickhouse.ts) has a user_id column but no
+ // identified_user_id column β€” bots are never identified β€” so the main
+ // builder's user_id -> identified_user_id expansion cannot apply here.
+ const filters = JSON.stringify([{ parameter: "user_id", type: "equals", value: ["user123"] }]);
+ expect(getBotFilterStatement(filters)).toBe("AND user_id = 'user123'");
+ });
+
+ it("should apply expression transforms for referrer and city", () => {
+ const filters = JSON.stringify([
+ { parameter: "referrer", type: "equals", value: ["google.com"] },
+ { parameter: "city", type: "equals", value: ["CA-San Francisco"] },
+ ]);
+ const result = getBotFilterStatement(filters);
+ expect(result).toContain("domainWithoutWWW(referrer) = 'google.com'");
+ expect(result).toContain("concat(toString(region), '-', toString(city)) = 'CA-San Francisco'");
+ });
+ });
+});
+
+describe("getBotTimeStatementFill", () => {
+ describe("date range mode", () => {
+ it("should build a timezone-aware WITH FILL clause from start_date and end_date", () => {
+ const result = getBotTimeStatementFill(
+ fillParams({ start_date: "2024-01-01", end_date: "2024-01-31", time_zone: "America/New_York" }),
+ "day"
+ );
+ expect(normalize(result)).toBe(
+ "WITH FILL FROM toTimeZone( toDateTime(toStartOfDay(toDateTime('2024-01-01', 'America/New_York'))), 'UTC' ) " +
+ "TO if( toDate('2024-01-31') = toDate(now(), 'America/New_York'), toTimeZone(now(), 'UTC'), " +
+ "toTimeZone( toDateTime(toStartOfDay(toDateTime('2024-01-31', 'America/New_York'))) + INTERVAL 1 DAY, 'UTC' ) ) " +
+ "STEP INTERVAL 1 DAY"
+ );
+ });
+
+ it("should default a missing time_zone to UTC", () => {
+ const result = getBotTimeStatementFill(fillParams({ start_date: "2024-01-01", end_date: "2024-01-31" }), "day");
+ expect(result).toContain("toDateTime('2024-01-01', 'UTC')");
+ });
+ });
+
+ describe("datetime range mode", () => {
+ it("should build a WITH FILL clause from start_datetime and end_datetime", () => {
+ const result = getBotTimeStatementFill(
+ fillParams({
+ start_datetime: "2024-01-01 05:30:00",
+ end_datetime: "2024-01-02 06:45:00",
+ time_zone: "UTC",
+ }),
+ "hour"
+ );
+ expect(normalize(result)).toBe(
+ "WITH FILL FROM toTimeZone( toDateTime(toStartOfHour(toTimeZone(toDateTime('2024-01-01 05:30:00', 'UTC'), 'UTC'))), 'UTC' ) " +
+ "TO toTimeZone( toDateTime(toStartOfHour(toTimeZone(toDateTime('2024-01-02 06:45:00', 'UTC'), 'UTC'))), 'UTC' ) " +
+ "STEP INTERVAL 1 HOUR"
+ );
+ });
+ });
+
+ describe("past minutes mode", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("should build a WITH FILL clause from past_minutes_start/end relative to now", () => {
+ const result = getBotTimeStatementFill(fillParams({ past_minutes_start: 120, past_minutes_end: 60 }), "hour");
+ expect(normalize(result)).toBe(
+ "WITH FILL FROM toStartOfHour(toDateTime('2024-06-15 10:00:00')) " +
+ "TO toStartOfHour(toDateTime('2024-06-15 11:00:00')) + INTERVAL 1 HOUR " +
+ "STEP INTERVAL 1 HOUR"
+ );
+ });
+
+ it("should use MINUTE-based interval for minute buckets", () => {
+ const result = getBotTimeStatementFill(
+ fillParams({ past_minutes_start: 30, past_minutes_end: 0 }),
+ "five_minutes"
+ );
+ expect(result).toContain("+ INTERVAL 1 MINUTE");
+ expect(result).toContain("STEP INTERVAL 5 MINUTES");
+ });
+ });
+
+ describe("validation", () => {
+ it("should throw for an invalid bucket", () => {
+ expect(() =>
+ getBotTimeStatementFill(
+ fillParams({ start_date: "2024-01-01", end_date: "2024-01-31", time_zone: "UTC" }),
+ "decade" as TimeBucket
+ )
+ ).toThrow();
+ });
+
+ it("should throw when no time range params are provided", () => {
+ expect(() => getBotTimeStatementFill(fillParams({}), "day")).toThrow();
+ });
+ });
+});
diff --git a/server/src/api/analytics/bots/utils.ts b/server/src/api/analytics/bots/utils.ts
index 9a2215b9e..2d382229b 100644
--- a/server/src/api/analytics/bots/utils.ts
+++ b/server/src/api/analytics/bots/utils.ts
@@ -89,11 +89,13 @@ const filterTypeToOperator = (type: FilterType) => {
}
};
+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 `%${v}%`;
- if (type === "starts_with") return `${v}%`;
- if (type === "ends_with") return `%${v}`;
+ 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;
};
@@ -120,7 +122,7 @@ export const getBotSqlParam = (parameter: BotDimensionKey) => {
return parameter;
};
-const buildStringFilterCondition = (expression: string, filterType: FilterType, values: (string | number)[]) => {
+export const buildStringFilterCondition = (expression: string, filterType: FilterType, values: (string | number)[]) => {
if (filterType === "is_null") {
return `(${expression} IS NULL OR ${expression} = '')`;
}
@@ -133,7 +135,11 @@ const buildStringFilterCondition = (expression: string, filterType: FilterType,
if (!pattern) {
throw new Error("Regex pattern cannot be empty");
}
- new RegExp(pattern);
+ 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)");
}
diff --git a/server/src/api/analytics/lite/utils.test.ts b/server/src/api/analytics/lite/utils.test.ts
new file mode 100644
index 000000000..3d3fbf2d2
--- /dev/null
+++ b/server/src/api/analytics/lite/utils.test.ts
@@ -0,0 +1,355 @@
+import { FilterParams } from "@rybbit/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TimeBucket } from "../types.js";
+import {
+ getLiteFillClause,
+ getLiteSessionFilter,
+ getLiteTimeStatement,
+ hasLiteFilters,
+ liteBucket,
+ wrapLiteLikeValue,
+} from "./utils.js";
+
+vi.mock("../../../db/postgres/postgres.js", () => ({
+ db: {},
+ sql: {},
+}));
+
+const normalize = (sql: string) => sql.replace(/\s+/g, " ").trim();
+
+const filtersOf = (filters: object[]) => JSON.stringify(filters);
+
+const params = (overrides: Partial<FilterParams>) => overrides as FilterParams;
+
+describe("getLiteSessionFilter", () => {
+ describe("empty inputs", () => {
+ it("should support undefined filters with empty sql", () => {
+ expect(getLiteSessionFilter(undefined)).toEqual({ supported: true, sql: "" });
+ });
+
+ it("should support an empty filter array with empty sql", () => {
+ expect(getLiteSessionFilter("[]")).toEqual({ supported: true, sql: "" });
+ });
+
+ it("should throw for invalid JSON", () => {
+ expect(() => getLiteSessionFilter("not json")).toThrow("Invalid JSON format");
+ });
+ });
+
+ describe("supported vs unsupported columns", () => {
+ it("should support every sessions_mv column", () => {
+ for (const parameter of ["country", "region", "device_type", "browser", "operating_system", "hostname"]) {
+ const result = getLiteSessionFilter(filtersOf([{ parameter, type: "equals", value: ["x"] }]));
+ expect(result).toEqual({ supported: true, sql: `AND ${parameter} = 'x'` });
+ }
+ });
+
+ it("should fall back for columns not on the session rollup", () => {
+ for (const parameter of ["pathname", "page_title", "referrer", "channel", "entry_page", "utm_source"]) {
+ const result = getLiteSessionFilter(filtersOf([{ parameter, type: "equals", value: ["x"] }]));
+ expect(result).toEqual({ supported: false, sql: "" });
+ }
+ });
+
+ it("should fall back when any one filter is unsupported", () => {
+ const result = getLiteSessionFilter(
+ filtersOf([
+ { parameter: "country", type: "equals", value: ["US"] },
+ { parameter: "pathname", type: "equals", value: ["/home"] },
+ ])
+ );
+ expect(result).toEqual({ supported: false, sql: "" });
+ });
+
+ it("should fall back for operators outside the lite map", () => {
+ for (const type of ["regex", "not_regex", "greater_than", "less_than"]) {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type, value: ["US"] }]));
+ expect(result).toEqual({ supported: false, sql: "" });
+ }
+ });
+
+ it("should fall back for an empty value array", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type: "equals", value: [] }]));
+ expect(result).toEqual({ supported: false, sql: "" });
+ });
+ });
+
+ describe("operators", () => {
+ it("should handle equals", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type: "equals", value: ["US"] }]));
+ expect(result).toEqual({ supported: true, sql: "AND country = 'US'" });
+ });
+
+ it("should handle not_equals", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type: "not_equals", value: ["US"] }]));
+ expect(result).toEqual({ supported: true, sql: "AND country != 'US'" });
+ });
+
+ it("should handle contains", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "browser", type: "contains", value: ["Chr"] }]));
+ expect(result).toEqual({ supported: true, sql: "AND browser LIKE '%Chr%'" });
+ });
+
+ it("should handle not_contains", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "browser", type: "not_contains", value: ["bot"] }]));
+ expect(result).toEqual({ supported: true, sql: "AND browser NOT LIKE '%bot%'" });
+ });
+
+ it("should handle starts_with", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "hostname", type: "starts_with", value: ["app."] }]));
+ expect(result).toEqual({ supported: true, sql: "AND hostname LIKE 'app.%'" });
+ });
+
+ it("should handle ends_with", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "hostname", type: "ends_with", value: [".dev"] }]));
+ expect(result).toEqual({ supported: true, sql: "AND hostname LIKE '%.dev'" });
+ });
+
+ it("should handle is_null as NULL-or-empty", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "region", type: "is_null", value: [] }]));
+ expect(result).toEqual({ supported: true, sql: "AND (region IS NULL OR region = '')" });
+ });
+
+ it("should handle is_not_null as not-NULL-and-not-empty", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "region", type: "is_not_null", value: [] }]));
+ expect(result).toEqual({ supported: true, sql: "AND (region IS NOT NULL AND region != '')" });
+ });
+ });
+
+ describe("multi-value joining", () => {
+ it("should OR-join positive filters", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type: "equals", value: ["US", "DE"] }]));
+ expect(result).toEqual({ supported: true, sql: "AND (country = 'US' OR country = 'DE')" });
+ });
+
+ it("should AND-join not_equals values to avoid the OR tautology", () => {
+ const result = getLiteSessionFilter(
+ filtersOf([{ parameter: "country", type: "not_equals", value: ["US", "DE"] }])
+ );
+ expect(result).toEqual({ supported: true, sql: "AND (country != 'US' AND country != 'DE')" });
+ });
+
+ it("should AND-join not_contains values", () => {
+ const result = getLiteSessionFilter(
+ filtersOf([{ parameter: "browser", type: "not_contains", value: ["bot", "spider"] }])
+ );
+ expect(result).toEqual({
+ supported: true,
+ sql: "AND (browser NOT LIKE '%bot%' AND browser NOT LIKE '%spider%')",
+ });
+ });
+
+ it("should not parenthesize single values", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type: "equals", value: ["US"] }]));
+ expect(result.sql).toBe("AND country = 'US'");
+ });
+
+ it("should AND-join separate filters", () => {
+ const result = getLiteSessionFilter(
+ filtersOf([
+ { parameter: "country", type: "equals", value: ["US"] },
+ { parameter: "device_type", type: "equals", value: ["Desktop"] },
+ ])
+ );
+ expect(result).toEqual({ supported: true, sql: "AND country = 'US' AND device_type = 'Desktop'" });
+ });
+ });
+
+ describe("value escaping", () => {
+ it("should escape single quotes", () => {
+ const result = getLiteSessionFilter(
+ filtersOf([{ parameter: "country", type: "equals", value: ["US'; DROP TABLE events;--"] }])
+ );
+ expect(result.sql).toBe("AND country = 'US\\'; DROP TABLE events;--'");
+ });
+
+ it("should escape quotes inside LIKE wildcards", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "browser", type: "contains", value: ["O'Brien"] }]));
+ expect(result.sql).toBe("AND browser LIKE '%O\\'Brien%'");
+ });
+
+ it("should stringify numeric values", () => {
+ const result = getLiteSessionFilter(filtersOf([{ parameter: "country", type: "equals", value: [42] }]));
+ expect(result.sql).toBe("AND country = '42'");
+ });
+ });
+});
+
+describe("getLiteTimeStatement", () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("should build a timezone-aware day range against the given column", () => {
+ const result = getLiteTimeStatement(
+ { start_date: "2024-01-01", end_date: "2024-01-31", time_zone: "America/New_York" },
+ "event_hour"
+ );
+
+ expect(normalize(result)).toBe(
+ normalize(`AND event_hour >= toTimeZone(
+ toStartOfDay(toDateTime('2024-01-01', 'America/New_York')),
+ 'UTC'
+ )
+ AND event_hour < if(
+ toDate('2024-01-31') = toDate(now(), 'America/New_York'),
+ toTimeZone(now(), 'UTC'),
+ toTimeZone(
+ toStartOfDay(toDateTime('2024-01-31', 'America/New_York')) + INTERVAL 1 DAY,
+ 'UTC'
+ )
+ )`)
+ );
+ });
+
+ it("should default a missing time_zone to UTC", () => {
+ const result = getLiteTimeStatement(params({ start_date: "2024-01-01", end_date: "2024-01-31" }), "event_hour");
+ expect(result).toContain("toDateTime('2024-01-01', 'UTC')");
+ expect(result).not.toBe("");
+ });
+
+ it("should compute exact timestamps for past minutes", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+
+ const result = getLiteTimeStatement(params({ past_minutes_start: 120, past_minutes_end: 0 }), "start_time");
+
+ expect(result).toBe(
+ "AND start_time > toDateTime('2024-06-15 10:00:00') AND start_time <= toDateTime('2024-06-15 12:00:00')"
+ );
+ });
+
+ it("should return empty string with no time params", () => {
+ expect(getLiteTimeStatement(params({}), "event_hour")).toBe("");
+ });
+
+ it("should return empty string when only one date bound is provided", () => {
+ expect(getLiteTimeStatement(params({ start_date: "2024-01-01" }), "event_hour")).toBe("");
+ });
+});
+
+describe("getLiteFillClause", () => {
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("should build a date-range fill clause with the bucket fn and interval", () => {
+ const result = getLiteFillClause(
+ params({ start_date: "2024-01-01", end_date: "2024-01-31", time_zone: "UTC" }),
+ "day"
+ );
+
+ expect(normalize(result)).toBe(
+ normalize(`WITH FILL FROM toTimeZone(
+ toDateTime(toStartOfDay(toDateTime('2024-01-01', 'UTC'))),
+ 'UTC'
+ )
+ TO if(
+ toDate('2024-01-31') = toDate(now(), 'UTC'),
+ toTimeZone(now(), 'UTC'),
+ toTimeZone(
+ toDateTime(toStartOfDay(toDateTime('2024-01-31', 'UTC'))) + INTERVAL 1 DAY,
+ 'UTC'
+ )
+ ) STEP INTERVAL 1 DAY`)
+ );
+ });
+
+ it("should default a missing time_zone to UTC", () => {
+ const result = getLiteFillClause(params({ start_date: "2024-01-01", end_date: "2024-01-31" }), "hour");
+ expect(result).toContain("toDateTime('2024-01-01', 'UTC')");
+ expect(result).toContain("toStartOfHour");
+ expect(result).toContain("STEP INTERVAL 1 HOUR");
+ });
+
+ it("should build a past-minutes fill clause with exact timestamps", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+
+ const result = getLiteFillClause(params({ past_minutes_start: 120, past_minutes_end: 0 }), "hour");
+
+ expect(normalize(result)).toBe(
+ normalize(`WITH FILL FROM toStartOfHour(toDateTime('2024-06-15 10:00:00'))
+ TO toStartOfHour(toDateTime('2024-06-15 12:00:00')) + INTERVAL 1 HOUR
+ STEP INTERVAL 1 HOUR`)
+ );
+ });
+
+ it("should return empty string with no time params", () => {
+ expect(getLiteFillClause(params({}), "hour")).toBe("");
+ });
+});
+
+describe("liteBucket", () => {
+ it("should default undefined to hour", () => {
+ expect(liteBucket(undefined)).toBe("hour");
+ });
+
+ it("should promote sub-hour buckets to hour", () => {
+ for (const bucket of ["minute", "five_minutes", "ten_minutes", "fifteen_minutes"] as TimeBucket[]) {
+ expect(liteBucket(bucket)).toBe("hour");
+ }
+ });
+
+ it("should pass hour and coarser buckets through", () => {
+ for (const bucket of ["hour", "day", "week", "month", "year"] as TimeBucket[]) {
+ expect(liteBucket(bucket)).toBe(bucket);
+ }
+ });
+});
+
+describe("wrapLiteLikeValue", () => {
+ it("should wrap contains and not_contains with both wildcards", () => {
+ expect(wrapLiteLikeValue("contains", "blog")).toBe("%blog%");
+ expect(wrapLiteLikeValue("not_contains", "blog")).toBe("%blog%");
+ });
+
+ it("should append a wildcard for starts_with", () => {
+ expect(wrapLiteLikeValue("starts_with", "app.")).toBe("app.%");
+ });
+
+ it("should prepend a wildcard for ends_with", () => {
+ expect(wrapLiteLikeValue("ends_with", ".dev")).toBe("%.dev");
+ });
+
+ it("should pass other types through unwrapped", () => {
+ expect(wrapLiteLikeValue("equals", "US")).toBe("US");
+ expect(wrapLiteLikeValue("not_equals", "US")).toBe("US");
+ });
+
+ it("should stringify numbers", () => {
+ expect(wrapLiteLikeValue("contains", 42)).toBe("%42%");
+ });
+
+ it("should escape % and _ in user values so they match literally", () => {
+ expect(wrapLiteLikeValue("contains", "50%")).toBe("%50\\%%");
+ expect(wrapLiteLikeValue("starts_with", "a_b")).toBe("a\\_b%");
+ });
+
+ it("should escape backslashes in user values", () => {
+ expect(wrapLiteLikeValue("ends_with", "C:\\temp")).toBe("%C:\\\\temp");
+ });
+
+ it("should not escape values for non-LIKE types", () => {
+ expect(wrapLiteLikeValue("equals", "50%")).toBe("50%");
+ });
+});
+
+describe("hasLiteFilters", () => {
+ it("should return false for undefined or empty string", () => {
+ expect(hasLiteFilters(undefined)).toBe(false);
+ expect(hasLiteFilters("")).toBe(false);
+ });
+
+ it("should return false for an empty filter array", () => {
+ expect(hasLiteFilters("[]")).toBe(false);
+ });
+
+ it("should return true when at least one valid filter is present", () => {
+ expect(hasLiteFilters(filtersOf([{ parameter: "country", type: "equals", value: ["US"] }]))).toBe(true);
+ });
+
+ it("should throw for invalid JSON", () => {
+ expect(() => hasLiteFilters("not json")).toThrow("Invalid JSON format");
+ });
+});
diff --git a/server/src/api/analytics/lite/utils.ts b/server/src/api/analytics/lite/utils.ts
index d77c3ad65..903b354b7 100644
--- a/server/src/api/analytics/lite/utils.ts
+++ b/server/src/api/analytics/lite/utils.ts
@@ -1,6 +1,6 @@
import { FilterParams } from "@rybbit/shared";
import SqlString from "sqlstring";
-import { TimeBucket } from "../types.js";
+import { FilterType, TimeBucket } from "../types.js";
import { TimeBucketToFn, bucketIntervalMap } from "../utils/utils.js";
import { validateFilters, validateTimeStatementParams } from "../utils/query-validation.js";
@@ -54,11 +54,16 @@ const LITE_FILTER_OPERATORS: Record<string, string> = {
ends_with: "LIKE",
};
-function wrapLiteLikeValue(type: string, value: string | number): string {
+// 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 `%${v}%`;
- if (type === "starts_with") return `${v}%`;
- if (type === "ends_with") return `%${v}`;
+ 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;
}
@@ -168,10 +173,7 @@ export function liteBucket(bucket: TimeBucket | undefined): TimeBucket {
return bucket;
}
-export function getLiteFillClause(
- params: FilterParams,
- bucket: TimeBucket
-): string {
+export function getLiteFillClause(params: FilterParams, bucket: TimeBucket): string {
const { start_date, end_date, past_minutes_start, past_minutes_end } = params;
const time_zone = params.time_zone || "UTC";
const fn = TimeBucketToFn[bucket];
diff --git a/server/src/api/analytics/utils/customQueryValidation.internals.test.ts b/server/src/api/analytics/utils/customQueryValidation.internals.test.ts
new file mode 100644
index 000000000..1b1f0fdfd
--- /dev/null
+++ b/server/src/api/analytics/utils/customQueryValidation.internals.test.ts
@@ -0,0 +1,280 @@
+import { describe, expect, it } from "vitest";
+import {
+ collectInTableReferences,
+ collectTableReferences,
+ getCteNames,
+ hasQuotedIdentifierSyntax,
+ normalizeCustomQuery,
+ stripSqlLiteralsAndComments,
+} from "./customQueryValidation.js";
+
+// These cover the UNTESTED internals of customQueryValidation.ts. The public
+// validateScopedQuery is exercised separately in customQueryValidation.test.ts.
+
+// =============================================================================
+// stripSqlLiteralsAndComments
+// =============================================================================
+
+describe("stripSqlLiteralsAndComments", () => {
+ // The function blanks out literal/comment content while PRESERVING string
+ // length and newline positions, so later regex offsets still line up. Every
+ // assertion below relies on that length invariant.
+ it("preserves overall length (blanks in place, never deletes)", () => {
+ const inputs = [
+ "SELECT 'abc' FROM t",
+ "SELECT 1 -- comment\nFROM t",
+ "SELECT /* c */ 1 FROM t",
+ 'SELECT "col" FROM t',
+ ];
+ for (const input of inputs) {
+ expect(stripSqlLiteralsAndComments(input)).toHaveLength(input.length);
+ }
+ });
+
+ describe("string literals", () => {
+ it("blanks a simple single-quoted literal but keeps surrounding SQL", () => {
+ expect(stripSqlLiteralsAndComments("SELECT 'abc' FROM t")).toBe("SELECT FROM t");
+ });
+
+ it("handles a doubled-quote escape ('') inside a literal without ending early", () => {
+ // "'it''s'" is one literal; the whole thing becomes blanks.
+ expect(stripSqlLiteralsAndComments("SELECT 'it''s' FROM t")).toBe("SELECT FROM t");
+ });
+
+ it("handles a backslash escape inside a literal", () => {
+ // \' does not terminate the string; the closing ' does.
+ expect(stripSqlLiteralsAndComments("SELECT 'a\\'b' FROM t")).toBe("SELECT FROM t");
+ });
+
+ it("preserves newlines inside a literal (position alignment)", () => {
+ expect(stripSqlLiteralsAndComments("SELECT 'a\nb' FROM t")).toBe("SELECT \n FROM t");
+ });
+
+ it("blanks an unterminated string literal to end of input", () => {
+ expect(stripSqlLiteralsAndComments("SELECT 'abc")).toBe("SELECT ");
+ });
+ });
+
+ describe("line comments (--)", () => {
+ it("blanks a -- comment but keeps the terminating newline and following SQL", () => {
+ expect(stripSqlLiteralsAndComments("SELECT 1 -- FROM secret\nFROM t")).toBe(
+ "SELECT 1 \nFROM t"
+ );
+ });
+ });
+
+ describe("block comments (/* */)", () => {
+ it("blanks a /* */ block comment", () => {
+ expect(stripSqlLiteralsAndComments("SELECT /* FROM secret */ 1 FROM t")).toBe(
+ "SELECT 1 FROM t"
+ );
+ });
+
+ it("blanks an unterminated block comment to end of input", () => {
+ expect(stripSqlLiteralsAndComments("SELECT 1 /* FROM secret")).toBe("SELECT 1 ");
+ });
+
+ it("does not treat nested /* as re-opening β€” first */ ends the comment", () => {
+ // The comment ends at the first */; the trailing "*/" becomes live SQL.
+ const out = stripSqlLiteralsAndComments("SELECT 1 /* a /* b */ x */ FROM t");
+ expect(out).toHaveLength("SELECT 1 /* a /* b */ x */ FROM t".length);
+ // The "x */" after the first close is NOT stripped.
+ expect(out).toContain("x */ FROM t");
+ });
+ });
+
+ describe("quoted identifiers", () => {
+ it("blanks a double-quoted identifier", () => {
+ expect(stripSqlLiteralsAndComments('SELECT "col" FROM t')).toBe("SELECT FROM t");
+ });
+
+ it("blanks a backtick-quoted identifier", () => {
+ expect(stripSqlLiteralsAndComments("SELECT `col` FROM t")).toBe("SELECT FROM t");
+ });
+ });
+
+ describe("adversarial: hidden table names must NOT survive stripping", () => {
+ it("a table name inside a string literal is correctly ignored", () => {
+ // `'FROM events'` is data, not a clause; only the real FROM scoped_events remains.
+ const out = stripSqlLiteralsAndComments("SELECT 'FROM events' FROM scoped_events");
+ expect(out).toBe("SELECT FROM scoped_events");
+ expect(collectTableReferences(out)).toEqual(["scoped_events"]);
+ });
+
+ it("a table name inside a block comment is correctly ignored", () => {
+ const out = stripSqlLiteralsAndComments("SELECT 1 /* , events */ FROM scoped_events");
+ expect(collectTableReferences(out)).toEqual(["scoped_events"]);
+ });
+
+ it("a literal containing /* does not confuse the tokenizer into comment mode", () => {
+ // The `/*` lives inside a string, so it stays a string; nothing leaks out.
+ const out = stripSqlLiteralsAndComments("SELECT '/* not a comment */' FROM t");
+ expect(out).toBe("SELECT FROM t");
+ expect(out).toContain("FROM t");
+ });
+
+ it("a -- inside a string literal does not start a comment", () => {
+ const out = stripSqlLiteralsAndComments("SELECT '-- x' AS c FROM scoped_events");
+ expect(out).toContain("AS c FROM scoped_events");
+ });
+ });
+});
+
+// =============================================================================
+// getCteNames
+// =============================================================================
+
+describe("getCteNames", () => {
+ it("collects a single WITH ... AS ( name", () => {
+ expect([...getCteNames("WITH foo AS (SELECT 1)")]).toEqual(["foo"]);
+ });
+
+ it("collects comma-separated CTE names", () => {
+ expect([...getCteNames("WITH foo AS (SELECT 1), bar AS (SELECT 2)")]).toEqual(["foo", "bar"]);
+ });
+
+ it("is case-insensitive on keywords and lowercases the captured name", () => {
+ expect([...getCteNames("with FOO as (select 1)")]).toEqual(["foo"]);
+ expect([...getCteNames("WITH Bar AS (SELECT 1)")]).toEqual(["bar"]);
+ });
+
+ it("tolerates missing whitespace before the opening paren", () => {
+ expect([...getCteNames("with foo as(select 1)")]).toEqual(["foo"]);
+ });
+
+ it("returns an empty set when AS is not followed by a paren (not a CTE)", () => {
+ expect([...getCteNames("WITH foo AS SELECT 1")]).toEqual([]);
+ expect([...getCteNames("SELECT x AS foo FROM scoped_events")]).toEqual([]);
+ });
+
+ it("deduplicates repeated names", () => {
+ expect([...getCteNames("WITH foo AS (SELECT 1), foo AS (SELECT 2)")]).toEqual(["foo"]);
+ });
+});
+
+// =============================================================================
+// collectTableReferences
+// =============================================================================
+
+describe("collectTableReferences", () => {
+ it("collects the table after FROM and after JOIN", () => {
+ expect(collectTableReferences("SELECT * FROM a JOIN b ON 1=1")).toEqual(["a", "b"]);
+ });
+
+ it("collects every entry of a comma-separated FROM list", () => {
+ expect(collectTableReferences("SELECT * FROM a, b, c WHERE x")).toEqual(["a", "b", "c"]);
+ });
+
+ it("stops the FROM list at a clause terminator (WHERE/GROUP/ORDER/etc.)", () => {
+ // The comma after WHERE belongs to another clause, not the table list.
+ expect(collectTableReferences("SELECT * FROM a WHERE x IN (1, 2)")).toEqual(["a"]);
+ expect(collectTableReferences("SELECT * FROM a GROUP BY x, y")).toEqual(["a"]);
+ expect(collectTableReferences("SELECT * FROM a ORDER BY x, y")).toEqual(["a"]);
+ });
+
+ it("descends into a subquery's inner FROM rather than naming the subquery", () => {
+ expect(collectTableReferences("SELECT * FROM (SELECT * FROM inner) x")).toEqual(["inner"]);
+ });
+
+ it("skips ARRAY JOIN (array expression, not a table)", () => {
+ expect(collectTableReferences("SELECT k FROM t ARRAY JOIN mapKeys(m) AS k")).toEqual(["t"]);
+ expect(collectTableReferences("SELECT k FROM t LEFT ARRAY JOIN mapKeys(m) AS k")).toEqual(["t"]);
+ });
+
+ it("does not treat commas inside SELECT lists or function args as table entries", () => {
+ expect(collectTableReferences("SELECT count(*), uniq(x) FROM t GROUP BY p")).toEqual(["t"]);
+ });
+
+ it("captures a dotted (db-qualified) table name whole", () => {
+ expect(collectTableReferences("SELECT * FROM system.tables")).toEqual(["system.tables"]);
+ });
+});
+
+// =============================================================================
+// collectInTableReferences
+// =============================================================================
+
+describe("collectInTableReferences", () => {
+ it("collects the operand of `expr IN table`", () => {
+ expect(collectInTableReferences("WHERE x IN events")).toEqual(["events"]);
+ });
+
+ it("handles NOT IN and GLOBAL IN / GLOBAL NOT IN", () => {
+ expect(collectInTableReferences("WHERE x NOT IN events")).toEqual(["events"]);
+ expect(collectInTableReferences("WHERE x GLOBAL IN events")).toEqual(["events"]);
+ expect(collectInTableReferences("WHERE x GLOBAL NOT IN events")).toEqual(["events"]);
+ });
+
+ it("is case-insensitive", () => {
+ expect(collectInTableReferences("WHERE x in events")).toEqual(["events"]);
+ });
+
+ it("ignores `IN (...)` value lists and `IN function(...)` calls", () => {
+ // A following "(" marks a value expression, not the IN-table shorthand.
+ expect(collectInTableReferences("WHERE x IN (1, 2, 3)")).toEqual([]);
+ expect(collectInTableReferences("WHERE x IN tuple('a', 'b')")).toEqual([]);
+ });
+
+ it("collects multiple IN-table references in one query", () => {
+ expect(collectInTableReferences("WHERE a IN t1 AND b IN t2")).toEqual(["t1", "t2"]);
+ });
+});
+
+// =============================================================================
+// hasQuotedIdentifierSyntax
+// =============================================================================
+
+describe("hasQuotedIdentifierSyntax", () => {
+ it("detects a double-quoted identifier", () => {
+ expect(hasQuotedIdentifierSyntax('SELECT "x" FROM t')).toBe(true);
+ });
+
+ it("detects a backtick-quoted identifier", () => {
+ expect(hasQuotedIdentifierSyntax("SELECT `x` FROM t")).toBe(true);
+ });
+
+ it("does NOT flag a double quote or backtick that lives inside a string literal", () => {
+ expect(hasQuotedIdentifierSyntax("SELECT 'has \" quote'")).toBe(false);
+ expect(hasQuotedIdentifierSyntax("SELECT 'has ` tick'")).toBe(false);
+ });
+
+ it("does NOT flag a double quote inside a line or block comment", () => {
+ expect(hasQuotedIdentifierSyntax("SELECT 1 -- a \" b\nFROM t")).toBe(false);
+ expect(hasQuotedIdentifierSyntax('SELECT 1 /* a " b */ FROM t')).toBe(false);
+ });
+
+ it("respects doubled-quote and backslash escapes when tracking string state", () => {
+ // The '' keeps us inside the string, so the later " is still inside it.
+ expect(hasQuotedIdentifierSyntax(`SELECT 'it''s a \" test'`)).toBe(false);
+ expect(hasQuotedIdentifierSyntax(`SELECT 'a\\' \" b'`)).toBe(false);
+ });
+
+ it("returns false for a clean query with no quoting", () => {
+ expect(hasQuotedIdentifierSyntax("SELECT count(*) FROM scoped_events")).toBe(false);
+ });
+});
+
+// =============================================================================
+// normalizeCustomQuery
+// =============================================================================
+
+describe("normalizeCustomQuery", () => {
+ it("trims surrounding whitespace", () => {
+ expect(normalizeCustomQuery(" SELECT 1 ")).toBe("SELECT 1");
+ });
+
+ it("strips one or more trailing semicolons", () => {
+ expect(normalizeCustomQuery("SELECT 1;")).toBe("SELECT 1");
+ expect(normalizeCustomQuery("SELECT 1;;;")).toBe("SELECT 1");
+ });
+
+ it("strips trailing semicolons after trailing whitespace", () => {
+ expect(normalizeCustomQuery(" SELECT 1 ;; ")).toBe("SELECT 1");
+ });
+
+ it("leaves a mid-query semicolon in place (only anchored trailing ones are removed)", () => {
+ // The regex is anchored to end-of-string, so an interior ; survives β€” which
+ // is how validateScopedQuery can later detect multi-statement input.
+ expect(normalizeCustomQuery("SELECT 1; SELECT 2")).toBe("SELECT 1; SELECT 2");
+ });
+});
diff --git a/server/src/api/analytics/utils/customQueryValidation.ts b/server/src/api/analytics/utils/customQueryValidation.ts
index 665a68715..5ac5f2feb 100644
--- a/server/src/api/analytics/utils/customQueryValidation.ts
+++ b/server/src/api/analytics/utils/customQueryValidation.ts
@@ -79,7 +79,7 @@ const blockedFunctions = [
const quotedIdentifierError = "Quoted identifiers are not allowed in custom analytics queries";
-function hasQuotedIdentifierSyntax(query: string) {
+export function hasQuotedIdentifierSyntax(query: string) {
let index = 0;
let state: "normal" | "single" | "line-comment" | "block-comment" = "normal";
@@ -125,7 +125,7 @@ function hasQuotedIdentifierSyntax(query: string) {
return false;
}
-function stripSqlLiteralsAndComments(query: string) {
+export function stripSqlLiteralsAndComments(query: string) {
let result = "";
let index = 0;
let state: "normal" | "single" | "double" | "backtick" | "line-comment" | "block-comment" = "normal";
@@ -210,7 +210,7 @@ export function normalizeCustomQuery(query: string) {
return query.trim().replace(/;+$/g, "").trim();
}
-function getCteNames(query: string) {
+export function getCteNames(query: string) {
const cteNames = new Set<string>();
const ctePattern = /(?:\bWITH|,)\s*([a-zA-Z_][a-zA-Z0-9_]*)\s+AS\s*\(/gi;
let match: RegExpExecArray | null;
@@ -269,7 +269,7 @@ function skipWhitespace(query: string, index: number): number {
// each FROM/JOIN and every comma-separated entry in a FROM list (`FROM a, b`), which
// a FROM/JOIN-keyword-only scan would miss. Subquery references (`FROM ( SELECT … )`)
// are skipped here β€” their inner FROM/JOIN clauses are reached by this same scan.
-function collectTableReferences(query: string): string[] {
+export function collectTableReferences(query: string): string[] {
const references: string[] = [];
const length = query.length;
@@ -336,7 +336,7 @@ function collectTableReferences(query: string): string[] {
return references;
}
-function collectInTableReferences(query: string): string[] {
+export function collectInTableReferences(query: string): string[] {
const references: string[] = [];
const inPattern = /\b(?:GLOBAL\s+)?(?:NOT\s+)?IN\b/gi;
let match: RegExpExecArray | null;
diff --git a/server/src/api/analytics/utils/getFilterStatement.test.ts b/server/src/api/analytics/utils/getFilterStatement.test.ts
index 7301c50fa..4b5875686 100644
--- a/server/src/api/analytics/utils/getFilterStatement.test.ts
+++ b/server/src/api/analytics/utils/getFilterStatement.test.ts
@@ -417,4 +417,241 @@ describe("getFilterStatement", () => {
expect(result.match(/AND/g)?.length).toBe(3);
});
});
+
+ describe("Null check filters on standard parameters", () => {
+ it("should handle is_null on a standard column", () => {
+ const filters = JSON.stringify([{ parameter: "browser", type: "is_null", value: [] }]);
+ const result = getFilterStatement(filters);
+ expect(result).toBe("AND (browser IS NULL OR browser = '')");
+ });
+
+ it("should handle is_not_null on a standard column", () => {
+ const filters = JSON.stringify([{ parameter: "country", type: "is_not_null", value: [] }]);
+ const result = getFilterStatement(filters);
+ expect(result).toBe("AND (country IS NOT NULL AND country != '')");
+ });
+
+ it("should apply is_null to transformed expressions", () => {
+ const filters = JSON.stringify([{ parameter: "utm_source", type: "is_null", value: [] }]);
+ const result = getFilterStatement(filters);
+ expect(result).toBe("AND (url_parameters['utm_source'] IS NULL OR url_parameters['utm_source'] = '')");
+ });
+
+ it("should handle is_not_null inside a session-level subquery", () => {
+ const filters = JSON.stringify([{ parameter: "event_name", type: "is_not_null", value: [] }]);
+ const result = getFilterStatement(filters);
+ expect(result).toContain("session_id IN");
+ expect(result).toContain("(event_name IS NOT NULL AND event_name != '')");
+ });
+ });
+
+ describe("Starts with and ends with filters", () => {
+ it("should append % for starts_with", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "starts_with", value: ["/blog"] }]);
+ expect(getFilterStatement(filters)).toBe("AND pathname LIKE '/blog%'");
+ });
+
+ it("should prepend % for ends_with", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "ends_with", value: ["/checkout"] }]);
+ expect(getFilterStatement(filters)).toBe("AND pathname LIKE '%/checkout'");
+ });
+
+ it("should OR-join multiple starts_with values", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "starts_with", value: ["/blog", "/docs"] }]);
+ expect(getFilterStatement(filters)).toBe("AND (pathname LIKE '/blog%' OR pathname LIKE '/docs%')");
+ });
+
+ it("escapes % in user values so they match literally", () => {
+ // A literal "%" in the value is escaped to \% in the LIKE pattern, so
+ // starts_with "50%" only matches strings starting with the literal "50%".
+ const filters = JSON.stringify([{ parameter: "pathname", type: "starts_with", value: ["50%"] }]);
+ expect(getFilterStatement(filters)).toBe("AND pathname LIKE '50\\\\%%'");
+ });
+
+ it("escapes _ in user values so it matches literally", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "ends_with", value: ["a_b"] }]);
+ expect(getFilterStatement(filters)).toBe("AND pathname LIKE '%a\\\\_b'");
+ });
+
+ it("escapes backslashes in user values before LIKE wrapping", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "starts_with", value: ["C:\\temp"] }]);
+ // The value's backslash is LIKE-escaped to \\, then SqlString doubles
+ // each backslash in the string literal.
+ expect(getFilterStatement(filters)).toBe("AND pathname LIKE 'C:\\\\\\\\temp%'");
+ });
+ });
+
+ describe("Greater/less than or equal filters", () => {
+ it("should handle greater_than_or_equal", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "greater_than_or_equal", value: ["40.5"] }]);
+ expect(getFilterStatement(filters)).toBe("AND lat >= 40.5");
+ });
+
+ it("should handle less_than_or_equal", () => {
+ const filters = JSON.stringify([{ parameter: "lon", type: "less_than_or_equal", value: ["-70.25"] }]);
+ expect(getFilterStatement(filters)).toBe("AND lon <= -70.25");
+ });
+
+ it("should only use the first value for numeric comparisons", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "greater_than_or_equal", value: ["10", "20"] }]);
+ expect(getFilterStatement(filters)).toBe("AND lat >= 10");
+ });
+
+ it("should coerce numeric comparisons on non-numeric parameters", () => {
+ // Pinned behavior: any parameter accepts numeric comparison types; the
+ // value is coerced with Number() and inlined unquoted.
+ const filters = JSON.stringify([{ parameter: "pathname", type: "greater_than_or_equal", value: ["10"] }]);
+ expect(getFilterStatement(filters)).toBe("AND pathname >= 10");
+ });
+
+ it("should throw for non-numeric value with greater_than_or_equal", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "greater_than_or_equal", value: ["abc"] }]);
+ expect(() => getFilterStatement(filters)).toThrow("Invalid numeric value");
+ });
+ });
+
+ describe("Multi-value wildcard filters", () => {
+ it("should OR-join multiple contains values with % wrapping", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "contains", value: ["/blog", "/docs"] }]);
+ expect(getFilterStatement(filters)).toBe("AND (pathname LIKE '%/blog%' OR pathname LIKE '%/docs%')");
+ });
+
+ it("should AND-join multiple not_contains values", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "not_contains", value: ["/admin", "/internal"] }]);
+ expect(getFilterStatement(filters)).toBe(
+ "AND (pathname NOT LIKE '%/admin%' AND pathname NOT LIKE '%/internal%')"
+ );
+ });
+
+ it("escapes % and _ in multi-value contains so they match literally", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "contains", value: ["100%", "a_b"] }]);
+ expect(getFilterStatement(filters)).toBe("AND (pathname LIKE '%100\\\\%%' OR pathname LIKE '%a\\\\_b%')");
+ });
+
+ it("should OR-join multiple contains values on transformed params", () => {
+ const filters = JSON.stringify([{ parameter: "utm_source", type: "contains", value: ["google", "bing"] }]);
+ expect(getFilterStatement(filters)).toBe(
+ "AND (url_parameters['utm_source'] LIKE '%google%' OR url_parameters['utm_source'] LIKE '%bing%')"
+ );
+ });
+ });
+
+ describe("Generic session-level subqueries via sessionLevelParams", () => {
+ const normalize = (sql: string) => sql.replace(/\s+/g, " ").trim();
+
+ it("should route arbitrary params to a session-level subquery when configured", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "equals", value: ["/pricing"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, { sessionLevelParams: ["pathname"] });
+ expect(normalize(result)).toBe(
+ "AND session_id IN ( SELECT DISTINCT session_id FROM events WHERE pathname = '/pricing' )"
+ );
+ });
+
+ it("should include siteId and time filter in the generic session subquery", () => {
+ const filters = JSON.stringify([{ parameter: "hostname", type: "equals", value: ["app.example.com"] }]);
+ const result = getFilterStatement(filters, 42, "AND timestamp > now() - INTERVAL 1 DAY", {
+ sessionLevelParams: ["hostname"],
+ });
+ expect(normalize(result)).toBe(
+ "AND session_id IN ( SELECT DISTINCT session_id FROM events WHERE site_id = 42 AND timestamp > now() - INTERVAL 1 DAY AND hostname = 'app.example.com' )"
+ );
+ });
+
+ it("should handle negated filters inside the session subquery", () => {
+ // Note the semantics: this selects sessions containing at least one event
+ // whose hostname differs, not sessions with no matching event.
+ const filters = JSON.stringify([{ parameter: "hostname", type: "not_equals", value: ["bad.example.com"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, { sessionLevelParams: ["hostname"] });
+ expect(normalize(result)).toBe(
+ "AND session_id IN ( SELECT DISTINCT session_id FROM events WHERE hostname != 'bad.example.com' )"
+ );
+ });
+
+ it("should AND-join multi-value not_contains inside the session subquery", () => {
+ const filters = JSON.stringify([{ parameter: "pathname", type: "not_contains", value: ["/admin", "/debug"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, { sessionLevelParams: ["pathname"] });
+ expect(normalize(result)).toBe(
+ "AND session_id IN ( SELECT DISTINCT session_id FROM events WHERE (pathname NOT LIKE '%/admin%' AND pathname NOT LIKE '%/debug%') )"
+ );
+ });
+
+ it("applies getSqlParam transforms inside generic session subqueries", () => {
+ // Transformed params like city keep their concat() expression when
+ // routed session-level.
+ const filters = JSON.stringify([{ parameter: "city", type: "equals", value: ["CA-San Francisco"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, { sessionLevelParams: ["city"] });
+ expect(normalize(result)).toBe(
+ "AND session_id IN ( SELECT DISTINCT session_id FROM events WHERE concat(toString(region), '-', toString(city)) = 'CA-San Francisco' )"
+ );
+ });
+ });
+
+ describe("fieldMappings option", () => {
+ it("should rewrite mapped expressions to CTE column names", () => {
+ const filters = JSON.stringify([{ parameter: "utm_source", type: "equals", value: ["google"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, {
+ fieldMappings: { "url_parameters['utm_source']": "utm_source" },
+ });
+ expect(result).toBe("AND utm_source = 'google'");
+ });
+
+ it("should apply multiple mappings", () => {
+ const filters = JSON.stringify([
+ { parameter: "utm_source", type: "equals", value: ["google"] },
+ { parameter: "utm_medium", type: "contains", value: ["cpc"] },
+ ]);
+ const result = getFilterStatement(filters, undefined, undefined, {
+ fieldMappings: {
+ "url_parameters['utm_source']": "utm_source",
+ "url_parameters['utm_medium']": "utm_medium",
+ },
+ });
+ expect(result).toBe("AND utm_source = 'google' AND utm_medium LIKE '%cpc%'");
+ });
+
+ it("does not rewrite mapping tokens inside user-supplied string literals", () => {
+ // Mappings are applied where column identifiers are emitted, never as a
+ // rewrite over the finished SQL, so a filter VALUE that happens to equal
+ // a mapped token is left untouched.
+ const filters = JSON.stringify([
+ { parameter: "pathname", type: "equals", value: ["/pricing"] },
+ { parameter: "page_title", type: "equals", value: ["pathname"] },
+ ]);
+ const result = getFilterStatement(filters, undefined, undefined, {
+ fieldMappings: { pathname: "page_path" },
+ });
+ expect(result).toBe("AND page_path = '/pricing' AND page_title = 'pathname'");
+ });
+
+ it("should apply mappings to the lat/lon tolerance branch", () => {
+ const filters = JSON.stringify([{ parameter: "lat", type: "equals", value: ["40.7128"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, {
+ fieldMappings: { lat: "latitude" },
+ });
+ expect(result).toContain("latitude >= 40.7118");
+ expect(result).toContain("latitude <= 40.7138");
+ expect(result).not.toContain("(lat >=");
+ });
+
+ it("should apply mappings to negated multi-value lat/lon filters", () => {
+ const filters = JSON.stringify([{ parameter: "lon", type: "not_equals", value: ["-74.006", "-73.5"] }]);
+ const result = getFilterStatement(filters, undefined, undefined, {
+ fieldMappings: { lon: "longitude" },
+ });
+ expect(result).toContain("NOT ((longitude >= -74.007 AND longitude <= -74.005)");
+ expect(result).toContain("(longitude >= -73.501 AND longitude <= -73.499)");
+ });
+
+ it("does not rewrite quote-containing mapping tokens inside values", () => {
+ // Values containing a production-shaped mapping token
+ // (url_parameters['x']) also survive intact.
+ const filters = JSON.stringify([
+ { parameter: "page_title", type: "equals", value: ["url_parameters['utm_source']"] },
+ ]);
+ const result = getFilterStatement(filters, undefined, undefined, {
+ fieldMappings: { "url_parameters['utm_source']": "utm_source" },
+ });
+ expect(result).toBe("AND page_title = 'url_parameters[\\'utm_source\\']'");
+ });
+ });
});
diff --git a/server/src/api/analytics/utils/getFilterStatement.ts b/server/src/api/analytics/utils/getFilterStatement.ts
index f0172b81d..6c1efe90e 100644
--- a/server/src/api/analytics/utils/getFilterStatement.ts
+++ b/server/src/api/analytics/utils/getFilterStatement.ts
@@ -13,6 +13,9 @@ export interface FilterStatementOptions {
// Field name mappings for CTEs that extract fields to different column names
// e.g., { "url_parameters['utm_source']": "utm_source" }
+ // Keys must exactly match the emitted column expression (the getSqlParam
+ // output); the mapping is applied where column identifiers are produced, so
+ // user-supplied filter values are never rewritten.
fieldMappings?: Record<string, string>;
}
@@ -46,11 +49,16 @@ const filterTypeToOperator = (type: FilterType) => {
}
};
+// Escape LIKE pattern metacharacters in user-supplied values so they match
+// literally. Only the % wildcards that wrapLikeValue itself adds around the
+// value remain functional.
+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 `%${v}%`;
- if (type === "starts_with") return `${v}%`;
- if (type === "ends_with") return `%${v}`;
+ 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;
};
@@ -120,6 +128,12 @@ export function getFilterStatement(
}
const sessionLevelParams = options?.sessionLevelParams ?? DEFAULT_SESSION_LEVEL_PARAMS;
+
+ // Map an emitted column expression to its CTE alias, if the caller provided
+ // one. Applied at column-identifier emission time β€” never as a rewrite over
+ // finished SQL β€” so user-supplied values can't be affected.
+ const mapField = (expression: string): string => options?.fieldMappings?.[expression] ?? expression;
+
const siteIdFilter = siteId ? `site_id = ${siteId}` : "";
// Strip leading "AND " from timeStatement since we'll be constructing WHERE clauses
const timeFilter = timeStatement ? timeStatement.replace(/^AND\s+/i, "").trim() : "";
@@ -180,7 +194,11 @@ export function getFilterStatement(
wildcardPrefix: string
): string => {
const whereClause = [siteIdFilter, timeFilter].filter(Boolean).join(" AND ");
- const condition = buildStringFilterCondition(param, filterType, values, wildcardPrefix);
+ // 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 finalWhere = whereClause ? `WHERE ${whereClause} AND ${condition}` : `WHERE ${condition}`;
@@ -214,7 +232,7 @@ export function getFilterStatement(
)`;
};
- let result =
+ const result =
"AND " +
filtersArray
.map(filter => {
@@ -305,11 +323,11 @@ export function getFilterStatement(
}
if (isNullCheck) {
- return buildStringFilterCondition(getSqlParam(filter.parameter), filter.type, filter.value);
+ return buildStringFilterCondition(mapField(getSqlParam(filter.parameter)), filter.type, filter.value);
}
if (filter.type === "regex" || filter.type === "not_regex") {
- return buildStringFilterCondition(getSqlParam(filter.parameter), filter.type, filter.value, x);
+ return buildStringFilterCondition(mapField(getSqlParam(filter.parameter)), filter.type, filter.value, x);
}
// Handle numeric comparison filters (>, <, >=, <=)
@@ -323,19 +341,20 @@ export function getFilterStatement(
if (isNaN(numericValue)) {
throw new Error(`Invalid numeric value for ${filter.type} filter: ${filter.value[0]}`);
}
- return `${getSqlParam(filter.parameter)} ${filterTypeToOperator(filter.type)} ${numericValue}`;
+ return `${mapField(getSqlParam(filter.parameter))} ${filterTypeToOperator(filter.type)} ${numericValue}`;
}
if (filter.type === "starts_with" || filter.type === "ends_with") {
- return buildStringFilterCondition(getSqlParam(filter.parameter), filter.type, filter.value);
+ return buildStringFilterCondition(mapField(getSqlParam(filter.parameter)), filter.type, filter.value);
}
// Special handling for lat/lon with tolerance (only for equals/not_equals)
if (filter.parameter === "lat" || filter.parameter === "lon") {
const tolerance = 0.001;
+ const column = mapField(getSqlParam(filter.parameter));
const rangeConditions = filter.value.map(value => {
const targetValue = Number(value);
- return `(${filter.parameter} >= ${targetValue - tolerance} AND ${filter.parameter} <= ${targetValue + tolerance})`;
+ return `(${column} >= ${targetValue - tolerance} AND ${column} <= ${targetValue + tolerance})`;
});
const rangeCondition =
rangeConditions.length === 1 ? rangeConditions[0] : `(${rangeConditions.join(" OR ")})`;
@@ -343,30 +362,23 @@ export function getFilterStatement(
}
if (filter.value.length === 1) {
- const value = isNumericParam ? filter.value[0] : SqlString.escape(x + filter.value[0] + x);
- return `${getSqlParam(filter.parameter)} ${filterTypeToOperator(filter.type)} ${value}`;
+ const value = isNumericParam
+ ? filter.value[0]
+ : SqlString.escape(wrapLikeValue(filter.type, filter.value[0]));
+ return `${mapField(getSqlParam(filter.parameter))} ${filterTypeToOperator(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 ";
const valuesWithOperator = filter.value.map(value => {
- const escapedValue = isNumericParam ? value : SqlString.escape(x + value + x);
- return `${getSqlParam(filter.parameter)} ${filterTypeToOperator(filter.type)} ${escapedValue}`;
+ const escapedValue = isNumericParam ? value : SqlString.escape(wrapLikeValue(filter.type, value));
+ return `${mapField(getSqlParam(filter.parameter))} ${filterTypeToOperator(filter.type)} ${escapedValue}`;
});
return `(${valuesWithOperator.join(joiner)})`;
})
.join(" AND ");
- // Apply field mappings if provided (for CTEs that extract fields to different column names)
- if (options?.fieldMappings) {
- for (const [from, to] of Object.entries(options.fieldMappings)) {
- // Escape special regex characters in the 'from' string
- const escapedFrom = from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
- result = result.replace(new RegExp(escapedFrom, "g"), to);
- }
- }
-
return result;
}
diff --git a/server/src/api/analytics/utils/query-validation.test.ts b/server/src/api/analytics/utils/query-validation.test.ts
new file mode 100644
index 000000000..d3b54336e
--- /dev/null
+++ b/server/src/api/analytics/utils/query-validation.test.ts
@@ -0,0 +1,423 @@
+import { describe, expect, it } from "vitest";
+import {
+ filterParamSchema,
+ validateFilters,
+ validateHttpTimeParams,
+ validateTimeStatementFillParams,
+ validateTimeStatementParams,
+} from "./query-validation.js";
+
+// =============================================================================
+// validateHttpTimeParams
+// =============================================================================
+
+describe("validateHttpTimeParams", () => {
+ it("returns null when no time params are present (all-time mode)", () => {
+ expect(validateHttpTimeParams({})).toBeNull();
+ expect(validateHttpTimeParams({ site: "1", filters: "[]" })).toBeNull();
+ });
+
+ it("returns null for non-object queries (treated as empty)", () => {
+ expect(validateHttpTimeParams(undefined)).toBeNull();
+ expect(validateHttpTimeParams(null)).toBeNull();
+ expect(validateHttpTimeParams("start_date=2025-01-01")).toBeNull();
+ });
+
+ it("treats empty-string params as absent (dashboard sends start_date=&end_date=)", () => {
+ expect(validateHttpTimeParams({ start_date: "", end_date: "" })).toBeNull();
+ expect(
+ validateHttpTimeParams({
+ start_date: "",
+ end_date: "",
+ time_zone: "",
+ start_datetime: "",
+ end_datetime: "",
+ past_minutes_start: "",
+ past_minutes_end: "",
+ })
+ ).toBeNull();
+ });
+
+ it("errors when an empty string unpairs a real value", () => {
+ // start_date="" is stripped as absent, so end_date is now unpaired
+ expect(validateHttpTimeParams({ start_date: "", end_date: "2025-01-31" })).toBe(
+ "start_date and end_date must be provided together"
+ );
+ });
+
+ describe("date range params", () => {
+ it("accepts a valid start_date/end_date pair with time_zone", () => {
+ expect(
+ validateHttpTimeParams({ start_date: "2025-01-01", end_date: "2025-01-31", time_zone: "America/New_York" })
+ ).toBeNull();
+ });
+
+ it("errors on an unpaired start_date or end_date", () => {
+ expect(validateHttpTimeParams({ start_date: "2025-01-01" })).toBe(
+ "start_date and end_date must be provided together"
+ );
+ expect(validateHttpTimeParams({ end_date: "2025-01-31" })).toBe(
+ "start_date and end_date must be provided together"
+ );
+ });
+
+ it("errors on a malformed date format", () => {
+ expect(validateHttpTimeParams({ start_date: "01/01/2025", end_date: "2025-01-31" })).toBe(
+ "Invalid start_date format. Use YYYY-MM-DD"
+ );
+ expect(validateHttpTimeParams({ start_date: "2025-01-01", end_date: "2025-1-31" })).toBe(
+ "Invalid end_date format. Use YYYY-MM-DD"
+ );
+ });
+
+ it("errors on a well-formatted but impossible date", () => {
+ // Matches the regex but Date.parse yields NaN
+ expect(validateHttpTimeParams({ start_date: "2025-13-45", end_date: "2025-01-31" })).toBe(
+ "Invalid start_date value"
+ );
+ });
+ });
+
+ describe("time_zone", () => {
+ it("accepts a valid IANA time zone on its own", () => {
+ expect(validateHttpTimeParams({ time_zone: "Asia/Tokyo" })).toBeNull();
+ expect(validateHttpTimeParams({ time_zone: "UTC" })).toBeNull();
+ });
+
+ it("rejects an invalid time zone", () => {
+ expect(validateHttpTimeParams({ time_zone: "Not/AZone" })).toBe("Invalid time_zone");
+ });
+ });
+
+ describe("datetime range params", () => {
+ it("accepts space- and T-separated datetimes, with or without zone suffix", () => {
+ expect(
+ validateHttpTimeParams({ start_datetime: "2025-01-01 00:00:00", end_datetime: "2025-01-02 00:00:00" })
+ ).toBeNull();
+ expect(
+ validateHttpTimeParams({ start_datetime: "2025-01-01T00:00:00Z", end_datetime: "2025-01-02T00:00:00Z" })
+ ).toBeNull();
+ expect(
+ validateHttpTimeParams({
+ start_datetime: "2025-01-01T00:00:00+05:00",
+ end_datetime: "2025-01-02T00:00:00+0500",
+ })
+ ).toBeNull();
+ });
+
+ it("errors on an unpaired datetime", () => {
+ expect(validateHttpTimeParams({ start_datetime: "2025-01-01 00:00:00" })).toBe(
+ "start_datetime and end_datetime must be provided together"
+ );
+ });
+
+ it("errors on a malformed datetime", () => {
+ expect(validateHttpTimeParams({ start_datetime: "2025-01-01", end_datetime: "2025-01-02 00:00:00" })).toBe(
+ "Invalid start_datetime format. Use YYYY-MM-DD HH:mm:ss"
+ );
+ });
+
+ it("requires start_datetime strictly before end_datetime", () => {
+ expect(
+ validateHttpTimeParams({ start_datetime: "2025-01-02 00:00:00", end_datetime: "2025-01-01 00:00:00" })
+ ).toBe("start_datetime must be before end_datetime");
+ // Equal timestamps are also rejected
+ expect(
+ validateHttpTimeParams({ start_datetime: "2025-01-01 00:00:00", end_datetime: "2025-01-01 00:00:00" })
+ ).toBe("start_datetime must be before end_datetime");
+ });
+ });
+
+ describe("past minutes params", () => {
+ it("accepts start > end (start = older, end = newer), as strings or numbers", () => {
+ expect(validateHttpTimeParams({ past_minutes_start: "60", past_minutes_end: "0" })).toBeNull();
+ expect(validateHttpTimeParams({ past_minutes_start: 1440, past_minutes_end: 30 })).toBeNull();
+ });
+
+ it("errors on an unpaired past_minutes param", () => {
+ expect(validateHttpTimeParams({ past_minutes_start: "60" })).toBe(
+ "past_minutes_start and past_minutes_end must be provided together"
+ );
+ expect(validateHttpTimeParams({ past_minutes_end: "0" })).toBe(
+ "past_minutes_start and past_minutes_end must be provided together"
+ );
+ });
+
+ it("errors when start is not strictly greater than end", () => {
+ const message = "past_minutes_start must be greater than past_minutes_end (start = older, end = newer)";
+ expect(validateHttpTimeParams({ past_minutes_start: "30", past_minutes_end: "60" })).toBe(message);
+ expect(validateHttpTimeParams({ past_minutes_start: "60", past_minutes_end: "60" })).toBe(message);
+ });
+
+ it("errors on negative or non-numeric values", () => {
+ // A negative end still satisfies the ordering refine, so only the
+ // non-negative message fires here.
+ expect(validateHttpTimeParams({ past_minutes_start: "60", past_minutes_end: "-5" })).toBe(
+ "past_minutes values must be non-negative numbers"
+ );
+ // A negative/NaN start also fails the ordering refine, so both fire.
+ expect(validateHttpTimeParams({ past_minutes_start: "-5", past_minutes_end: "0" })).toContain(
+ "past_minutes values must be non-negative numbers"
+ );
+ expect(validateHttpTimeParams({ past_minutes_start: "abc", past_minutes_end: "0" })).toContain(
+ "past_minutes values must be non-negative numbers"
+ );
+ });
+ });
+
+ it("joins multiple issues with a semicolon", () => {
+ const result = validateHttpTimeParams({ start_date: "bogus", past_minutes_start: "60" });
+ // "bogus" fails both the regex check and the Date.parse refine, so the
+ // format and value messages both appear.
+ expect(result).toBe(
+ "Invalid start_date format. Use YYYY-MM-DD; " +
+ "Invalid start_date value; " +
+ "start_date and end_date must be provided together; " +
+ "past_minutes_start and past_minutes_end must be provided together"
+ );
+ });
+});
+
+// =============================================================================
+// validateTimeStatementParams
+// =============================================================================
+
+describe("validateTimeStatementParams", () => {
+ const ALL_UNDEFINED = { date: undefined, dateTimeRange: undefined, pastMinutesRange: undefined };
+
+ it("accepts a valid date object", () => {
+ const params = { date: { start_date: "2025-01-01", end_date: "2025-01-31", time_zone: "UTC" } };
+ expect(validateTimeStatementParams(params)).toEqual(params);
+ });
+
+ it("accepts a valid dateTimeRange", () => {
+ const params = { dateTimeRange: { start_datetime: "2025-01-01 00:00:00", end_datetime: "2025-01-02 00:00:00" } };
+ expect(validateTimeStatementParams(params)).toEqual(params);
+ });
+
+ it("accepts a valid pastMinutesRange where start is older (greater) than end", () => {
+ const params = { pastMinutesRange: { start: 60, end: 0 } };
+ expect(validateTimeStatementParams(params)).toEqual(params);
+ });
+
+ // PINNED BEHAVIOR: timeStatementParamsSchema ends in .catch({...}), so ANY
+ // invalid input β€” malformed dates, bad timezones, reversed ranges, even
+ // complete garbage β€” is silently swallowed and replaced with all-undefined
+ // fields instead of throwing. Callers (getTimeStatement) treat all-undefined
+ // as "no time filter", so invalid input degrades to an all-time query rather
+ // than an error. Tests below pin this so a future change is deliberate.
+ describe("silently swallows invalid input to all-undefined (.catch)", () => {
+ it("empty object (nothing provided) does not throw", () => {
+ expect(validateTimeStatementParams({})).toEqual(ALL_UNDEFINED);
+ });
+
+ it("non-object garbage does not throw", () => {
+ expect(validateTimeStatementParams(null)).toEqual(ALL_UNDEFINED);
+ expect(validateTimeStatementParams("garbage")).toEqual(ALL_UNDEFINED);
+ expect(validateTimeStatementParams(42)).toEqual(ALL_UNDEFINED);
+ });
+
+ it("invalid time zone is swallowed", () => {
+ expect(
+ validateTimeStatementParams({
+ date: { start_date: "2025-01-01", end_date: "2025-01-31", time_zone: "Not/AZone" },
+ })
+ ).toEqual(ALL_UNDEFINED);
+ });
+
+ it("date object missing required time_zone is swallowed", () => {
+ expect(
+ validateTimeStatementParams({ date: { start_date: "2025-01-01", end_date: "2025-01-31" } })
+ ).toEqual(ALL_UNDEFINED);
+ });
+
+ it("malformed date strings are swallowed", () => {
+ expect(
+ validateTimeStatementParams({ date: { start_date: "01/01/2025", end_date: "2025-01-31", time_zone: "UTC" } })
+ ).toEqual(ALL_UNDEFINED);
+ });
+
+ it("reversed or equal dateTimeRange is swallowed", () => {
+ expect(
+ validateTimeStatementParams({
+ dateTimeRange: { start_datetime: "2025-01-02 00:00:00", end_datetime: "2025-01-01 00:00:00" },
+ })
+ ).toEqual(ALL_UNDEFINED);
+ });
+
+ it("pastMinutesRange with start <= end (wrong ordering) is swallowed", () => {
+ expect(validateTimeStatementParams({ pastMinutesRange: { start: 0, end: 60 } })).toEqual(ALL_UNDEFINED);
+ expect(validateTimeStatementParams({ pastMinutesRange: { start: 60, end: 60 } })).toEqual(ALL_UNDEFINED);
+ });
+
+ it("negative pastMinutesRange values are swallowed", () => {
+ expect(validateTimeStatementParams({ pastMinutesRange: { start: -10, end: -20 } })).toEqual(ALL_UNDEFINED);
+ });
+ });
+});
+
+// =============================================================================
+// validateTimeStatementFillParams (bucket enum + fill params schema)
+// =============================================================================
+
+describe("validateTimeStatementFillParams", () => {
+ // Cast: validateTimeStatementFillParams is typed for full FilterParams, but
+ // the schema only reads the time-related fields, so partial objects are fine.
+ const validDateParams = { start_date: "2025-01-01", end_date: "2025-01-31", time_zone: "UTC" } as never;
+
+ describe("bucket enum", () => {
+ it.each(["minute", "five_minutes", "ten_minutes", "fifteen_minutes", "hour", "day", "week", "month", "year"])(
+ "accepts bucket %s",
+ bucket => {
+ const result = validateTimeStatementFillParams(validDateParams, bucket);
+ expect(result.bucket).toBe(bucket);
+ }
+ );
+
+ it("rejects unknown bucket values", () => {
+ expect(() => validateTimeStatementFillParams(validDateParams, "quarter")).toThrow();
+ expect(() => validateTimeStatementFillParams(validDateParams, undefined)).toThrow();
+ });
+ });
+
+ it("defaults a missing time_zone to UTC instead of dropping the range", () => {
+ const result = validateTimeStatementFillParams(
+ { start_date: "2025-01-01", end_date: "2025-01-31" } as never,
+ "day"
+ );
+ expect(result.params.time_zone).toBe("UTC");
+ expect(result.params.start_date).toBe("2025-01-01");
+ });
+
+ it("coerces string past_minutes params to numbers", () => {
+ const result = validateTimeStatementFillParams(
+ { past_minutes_start: "60", past_minutes_end: "0" } as never,
+ "minute"
+ );
+ expect(result.params.past_minutes_start).toBe(60);
+ expect(result.params.past_minutes_end).toBe(0);
+ });
+
+ it("throws when past_minutes_start is not greater than past_minutes_end", () => {
+ expect(() =>
+ validateTimeStatementFillParams({ past_minutes_start: "0", past_minutes_end: "60" } as never, "minute")
+ ).toThrow(/greater than/);
+ });
+
+ it("throws when no complete time param group is provided", () => {
+ expect(() => validateTimeStatementFillParams({} as never, "day")).toThrow(/must be provided/);
+ // start_date alone (no end_date) is not a complete group
+ expect(() => validateTimeStatementFillParams({ start_date: "2025-01-01" } as never, "day")).toThrow(
+ /must be provided/
+ );
+ });
+
+ it("silently turns a non-numeric past_minutes string into undefined, then fails the group check", () => {
+ // PINNED: the transform maps NaN to undefined rather than erroring, so the
+ // failure surfaces as the "must be provided" refinement, not a type error.
+ expect(() =>
+ validateTimeStatementFillParams({ past_minutes_start: "abc", past_minutes_end: "0" } as never, "minute")
+ ).toThrow(/must be provided/);
+ });
+});
+
+// =============================================================================
+// validateFilters
+// =============================================================================
+
+describe("validateFilters", () => {
+ it("parses a valid filters array", () => {
+ const filters = [{ parameter: "browser", type: "equals", value: ["Chrome"] }];
+ expect(validateFilters(JSON.stringify(filters))).toEqual(filters);
+ });
+
+ it("accepts an empty array", () => {
+ expect(validateFilters("[]")).toEqual([]);
+ });
+
+ it("accepts mixed string and number values", () => {
+ const filters = [{ parameter: "lat", type: "greater_than", value: [45.5, "46"] }];
+ expect(validateFilters(JSON.stringify(filters))).toEqual(filters);
+ });
+
+ it("throws 'Invalid JSON format' on malformed JSON", () => {
+ expect(() => validateFilters("not json")).toThrow("Invalid JSON format");
+ expect(() => validateFilters("[{")).toThrow("Invalid JSON format");
+ });
+
+ it("throws when the JSON is not an array", () => {
+ expect(() => validateFilters('{"parameter":"browser","type":"equals","value":["x"]}')).toThrow();
+ });
+
+ it("throws on an unknown filter parameter", () => {
+ expect(() =>
+ validateFilters(JSON.stringify([{ parameter: "password", type: "equals", value: ["x"] }]))
+ ).toThrow();
+ });
+
+ it("throws on an unknown filter type", () => {
+ expect(() => validateFilters(JSON.stringify([{ parameter: "browser", type: "like", value: ["x"] }]))).toThrow();
+ });
+
+ it("throws when value is not an array of strings/numbers", () => {
+ expect(() => validateFilters(JSON.stringify([{ parameter: "browser", type: "equals", value: "Chrome" }]))).toThrow();
+ expect(() =>
+ validateFilters(JSON.stringify([{ parameter: "browser", type: "equals", value: [true] }]))
+ ).toThrow();
+ });
+
+ it("accepts feature_flag filter parameters", () => {
+ const filters = [{ parameter: "feature_flag:new_checkout", type: "equals", value: ["true"] }];
+ expect(validateFilters(JSON.stringify(filters))).toEqual(filters);
+ });
+});
+
+// =============================================================================
+// filterParamSchema (feature_flag regex + union)
+// =============================================================================
+
+describe("filterParamSchema", () => {
+ it("accepts base filter parameters", () => {
+ expect(filterParamSchema.safeParse("browser").success).toBe(true);
+ expect(filterParamSchema.safeParse("pathname").success).toBe(true);
+ expect(filterParamSchema.safeParse("utm_source").success).toBe(true);
+ expect(filterParamSchema.safeParse("tag").success).toBe(true);
+ });
+
+ it("rejects strings outside the base enum", () => {
+ expect(filterParamSchema.safeParse("screen_class").success).toBe(false);
+ expect(filterParamSchema.safeParse("").success).toBe(false);
+ expect(filterParamSchema.safeParse("BROWSER").success).toBe(false);
+ });
+
+ it("rejects url_param: parameters (handled elsewhere, not part of this schema)", () => {
+ expect(filterParamSchema.safeParse("url_param:campaign_id").success).toBe(false);
+ });
+
+ describe("feature_flag: regex", () => {
+ it("accepts flag keys starting with a letter, using the allowed charset", () => {
+ expect(filterParamSchema.safeParse("feature_flag:new_checkout").success).toBe(true);
+ expect(filterParamSchema.safeParse("feature_flag:A").success).toBe(true);
+ expect(filterParamSchema.safeParse("feature_flag:my.flag:v2-x_1").success).toBe(true);
+ });
+
+ it("accepts a flag key of exactly 100 characters", () => {
+ expect(filterParamSchema.safeParse(`feature_flag:a${"b".repeat(99)}`).success).toBe(true);
+ });
+
+ it("rejects a flag key longer than 100 characters", () => {
+ expect(filterParamSchema.safeParse(`feature_flag:a${"b".repeat(100)}`).success).toBe(false);
+ });
+
+ it("rejects an empty flag key", () => {
+ expect(filterParamSchema.safeParse("feature_flag:").success).toBe(false);
+ });
+
+ it("rejects flag keys starting with a digit or containing invalid characters", () => {
+ expect(filterParamSchema.safeParse("feature_flag:1abc").success).toBe(false);
+ expect(filterParamSchema.safeParse("feature_flag:has space").success).toBe(false);
+ expect(filterParamSchema.safeParse("feature_flag:x'; DROP").success).toBe(false);
+ expect(filterParamSchema.safeParse("feature_flag:flag\n").success).toBe(false);
+ });
+ });
+});
diff --git a/server/src/api/analytics/utils/utils.test.ts b/server/src/api/analytics/utils/utils.test.ts
new file mode 100644
index 000000000..e8608ae8b
--- /dev/null
+++ b/server/src/api/analytics/utils/utils.test.ts
@@ -0,0 +1,328 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { getTimeStatement, normalizeDatetimeForClickhouse, patternToRegex, processResults } from "./utils.js";
+
+vi.mock("../../../db/postgres/postgres.js", () => ({
+ db: {},
+ sql: {},
+}));
+
+const normalize = (sql: string) => sql.replace(/\s+/g, " ").trim();
+
+type TimeParams = Parameters<typeof getTimeStatement>[0];
+const getTime = (params: Partial<TimeParams>) => getTimeStatement(params as TimeParams);
+
+const makeResultSet = <T>(rows: T[]) => ({ json: async () => rows }) as unknown as Parameters<typeof processResults>[0];
+
+describe("getTimeStatement", () => {
+ describe("date range", () => {
+ it("should build a timezone-aware day range from start_date and end_date", () => {
+ const result = getTime({
+ start_date: "2024-01-01",
+ end_date: "2024-01-31",
+ time_zone: "America/New_York",
+ });
+
+ expect(normalize(result)).toBe(
+ normalize(`AND timestamp >= toTimeZone(
+ toStartOfDay(toDateTime('2024-01-01', 'America/New_York')),
+ 'UTC'
+ )
+ AND timestamp < if(
+ toDate('2024-01-31') = toDate(now(), 'America/New_York'),
+ toTimeZone(now(), 'UTC'),
+ toTimeZone(
+ toStartOfDay(toDateTime('2024-01-31', 'America/New_York')) + INTERVAL 1 DAY,
+ 'UTC'
+ )
+ )`)
+ );
+ });
+
+ it("should default a missing time_zone to UTC instead of dropping the range", () => {
+ const result = getTime({ start_date: "2024-01-01", end_date: "2024-01-31" });
+
+ expect(result).toContain("toDateTime('2024-01-01', 'UTC')");
+ expect(result).toContain("toDateTime('2024-01-31', 'UTC')");
+ expect(result).not.toBe("");
+ });
+
+ it("should defer the 'today' decision to ClickHouse via if(toDate(end) = toDate(now))", () => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+
+ const result = getTime({
+ start_date: "2024-06-15",
+ end_date: "2024-06-15",
+ time_zone: "UTC",
+ });
+
+ expect(normalize(result)).toContain("toDate('2024-06-15') = toDate(now(), 'UTC')");
+ expect(normalize(result)).toContain("toTimeZone(now(), 'UTC')");
+
+ vi.useRealTimers();
+ });
+
+ it("should take precedence over datetime range and past minutes", () => {
+ const result = getTime({
+ start_date: "2024-01-01",
+ end_date: "2024-01-31",
+ time_zone: "UTC",
+ start_datetime: "2024-02-01 00:00:00",
+ end_datetime: "2024-02-02 00:00:00",
+ past_minutes_start: 60,
+ past_minutes_end: 0,
+ });
+
+ expect(result).toContain("toStartOfDay(toDateTime('2024-01-01', 'UTC'))");
+ expect(result).not.toContain("2024-02-01");
+ });
+
+ it("should return empty string for an invalid date format", () => {
+ expect(getTime({ start_date: "01/01/2024", end_date: "2024-01-31", time_zone: "UTC" })).toBe("");
+ });
+
+ // Potential footgun: an invalid time zone silently degrades to all-time
+ // (empty statement) rather than throwing; callers validate upstream.
+ it("should return empty string for an invalid time zone", () => {
+ expect(getTime({ start_date: "2024-01-01", end_date: "2024-01-31", time_zone: "Not/AZone" })).toBe("");
+ });
+ });
+
+ describe("datetime range", () => {
+ it("should build a UTC datetime range", () => {
+ const result = getTime({
+ start_datetime: "2024-01-01 00:00:00",
+ end_datetime: "2024-01-02 12:30:00",
+ });
+
+ expect(normalize(result)).toBe(
+ "AND timestamp >= toDateTime('2024-01-01 00:00:00', 'UTC') AND timestamp < toDateTime('2024-01-02 12:30:00', 'UTC')"
+ );
+ });
+
+ it("should normalize offset datetimes to UTC", () => {
+ const result = getTime({
+ start_datetime: "2024-01-01T05:00:00+02:00",
+ end_datetime: "2024-01-02T05:00:00+02:00",
+ });
+
+ expect(normalize(result)).toBe(
+ "AND timestamp >= toDateTime('2024-01-01 03:00:00', 'UTC') AND timestamp < toDateTime('2024-01-02 03:00:00', 'UTC')"
+ );
+ });
+
+ it("should return empty string when start_datetime is not before end_datetime", () => {
+ expect(getTime({ start_datetime: "2024-01-02 00:00:00", end_datetime: "2024-01-01 00:00:00" })).toBe("");
+ expect(getTime({ start_datetime: "2024-01-01 00:00:00", end_datetime: "2024-01-01 00:00:00" })).toBe("");
+ });
+ });
+
+ describe("past minutes range", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it("should compute exact UTC timestamps from past minutes", () => {
+ const result = getTime({ past_minutes_start: 60, past_minutes_end: 0 });
+
+ expect(result).toBe(
+ "AND timestamp > toDateTime('2024-06-15 11:00:00') AND timestamp <= toDateTime('2024-06-15 12:00:00')"
+ );
+ });
+
+ it("should accept numeric strings for past minutes", () => {
+ const result = getTime({
+ past_minutes_start: "30" as unknown as number,
+ past_minutes_end: "0" as unknown as number,
+ });
+
+ expect(result).toBe(
+ "AND timestamp > toDateTime('2024-06-15 11:30:00') AND timestamp <= toDateTime('2024-06-15 12:00:00')"
+ );
+ });
+
+ it("should return empty string when start is not greater than end", () => {
+ expect(getTime({ past_minutes_start: 0, past_minutes_end: 60 })).toBe("");
+ expect(getTime({ past_minutes_start: 30, past_minutes_end: 30 })).toBe("");
+ });
+
+ it("should ignore an unpaired past_minutes param", () => {
+ expect(getTime({ past_minutes_start: 60 })).toBe("");
+ });
+ });
+
+ describe("empty params", () => {
+ it("should return empty string when no time params are provided", () => {
+ expect(getTime({})).toBe("");
+ });
+
+ it("should return empty string when only one date bound is provided", () => {
+ expect(getTime({ start_date: "2024-01-01", time_zone: "UTC" })).toBe("");
+ expect(getTime({ end_date: "2024-01-31", time_zone: "UTC" })).toBe("");
+ });
+ });
+});
+
+describe("normalizeDatetimeForClickhouse", () => {
+ it("should strip the Z suffix from ISO UTC datetimes", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15T10:30:00Z")).toBe("2024-01-15 10:30:00");
+ });
+
+ it("should convert positive offsets to UTC", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15T10:30:00+02:00")).toBe("2024-01-15 08:30:00");
+ });
+
+ it("should convert negative offsets to UTC", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15T10:30:00-05:00")).toBe("2024-01-15 15:30:00");
+ });
+
+ it("should treat zoneless datetimes as UTC", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15T10:30:00")).toBe("2024-01-15 10:30:00");
+ });
+
+ it("should accept space-separated datetimes without a zone", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15 10:30:00")).toBe("2024-01-15 10:30:00");
+ });
+
+ it("should accept space-separated datetimes with an offset", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15 10:30:00+02:00")).toBe("2024-01-15 08:30:00");
+ });
+
+ it("should expand date-only input to midnight UTC", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15")).toBe("2024-01-15 00:00:00");
+ });
+
+ it("should truncate milliseconds", () => {
+ expect(normalizeDatetimeForClickhouse("2024-01-15T10:30:00.999Z")).toBe("2024-01-15 10:30:00");
+ });
+
+ // Unparseable input reaches toISOString() on an Invalid Date and throws;
+ // callers only pass values already validated by the datetime regex.
+ it("should throw on unparseable input", () => {
+ expect(() => normalizeDatetimeForClickhouse("not-a-date")).toThrow(RangeError);
+ });
+});
+
+describe("patternToRegex", () => {
+ it("should convert a single * to a one-segment matcher", () => {
+ expect(patternToRegex("/blog/*")).toBe("^/blog/[^/]+$");
+ });
+
+ it("should convert ** to a multi-segment matcher", () => {
+ expect(patternToRegex("/blog/**")).toBe("^/blog/.*$");
+ });
+
+ it("should handle ** in the middle of a pattern", () => {
+ expect(patternToRegex("/docs/**/intro")).toBe("^/docs/.*/intro$");
+ });
+
+ it("should handle bare wildcards", () => {
+ expect(patternToRegex("*")).toBe("^[^/]+$");
+ expect(patternToRegex("**")).toBe("^.*$");
+ });
+
+ it("should escape regex metacharacters", () => {
+ expect(patternToRegex("/path.html")).toBe("^/path\\.html$");
+ expect(patternToRegex("/a+b?c")).toBe("^/a\\+b\\?c$");
+ expect(patternToRegex("/(x)|[y]")).toBe("^/\\(x\\)\\|\\[y\\]$");
+ expect(patternToRegex("/p{1}^$")).toBe("^/p\\{1\\}\\^\\$$");
+ expect(patternToRegex("/back\\slash")).toBe("^/back\\\\slash$");
+ });
+
+ it("should not treat a literal {{DOUBLE_STAR}} in the input as the internal marker", () => {
+ // Braces are escaped before the marker substitution, so the marker regex
+ // cannot match user input containing the literal token.
+ expect(patternToRegex("/{{DOUBLE_STAR}}")).toBe("^/\\{\\{DOUBLE_STAR\\}\\}$");
+ });
+
+ it("should treat *** as ** followed by *", () => {
+ expect(patternToRegex("/a/***")).toBe("^/a/.*[^/]+$");
+ });
+
+ it("should anchor patterns without wildcards", () => {
+ expect(patternToRegex("/pricing")).toBe("^/pricing$");
+ });
+});
+
+describe("processResults", () => {
+ it("should coerce numeric strings to numbers", async () => {
+ const rows = await processResults<Record<string, unknown>>(
+ makeResultSet([{ count: "123", ratio: "45.6", negative: "-7" }])
+ );
+
+ expect(rows).toEqual([{ count: 123, ratio: 45.6, negative: -7 }]);
+ });
+
+ it("should leave existing numbers untouched", async () => {
+ const rows = await processResults<Record<string, unknown>>(makeResultSet([{ count: 42 }]));
+
+ expect(rows).toEqual([{ count: 42 }]);
+ });
+
+ it("should not coerce ID-like fields even when numeric", async () => {
+ const rows = await processResults<Record<string, unknown>>(
+ makeResultSet([
+ {
+ session_id: "12345",
+ user_id: "67890",
+ identified_user_id: "111",
+ effective_user_id: "222",
+ site_id: "999",
+ },
+ ])
+ );
+
+ expect(rows).toEqual([
+ {
+ session_id: "12345",
+ user_id: "67890",
+ identified_user_id: "111",
+ effective_user_id: "222",
+ site_id: 999,
+ },
+ ]);
+ });
+
+ it("should leave booleans, empty strings, null, and undefined untouched", async () => {
+ const rows = await processResults<Record<string, unknown>>(
+ makeResultSet([{ flagOn: true, flagOff: false, empty: "", missing: null, gone: undefined }])
+ );
+
+ expect(rows).toEqual([{ flagOn: true, flagOff: false, empty: "", missing: null, gone: undefined }]);
+ });
+
+ it("should not coerce non-numeric strings", async () => {
+ const rows = await processResults<Record<string, unknown>>(
+ makeResultSet([{ browser: "Chrome", date: "2024-01-01", version: "1.2.3", word: "true" }])
+ );
+
+ expect(rows).toEqual([{ browser: "Chrome", date: "2024-01-01", version: "1.2.3", word: "true" }]);
+ });
+
+ // Number(" ") === 0, and only the exact empty string is excluded, so
+ // whitespace-only strings collapse to 0. Pinning current behavior.
+ it("should coerce whitespace-only strings to 0", async () => {
+ const rows = await processResults<Record<string, unknown>>(makeResultSet([{ blank: " " }]));
+
+ expect(rows).toEqual([{ blank: 0 }]);
+ });
+
+ it("should process every row independently", async () => {
+ const rows = await processResults<Record<string, unknown>>(
+ makeResultSet([
+ { pathname: "/a", visitors: "10" },
+ { pathname: "/b", visitors: "20" },
+ ])
+ );
+
+ expect(rows).toEqual([
+ { pathname: "/a", visitors: 10 },
+ { pathname: "/b", visitors: 20 },
+ ]);
+ });
+});
diff --git a/server/src/api/as/webhook.test.ts b/server/src/api/as/webhook.test.ts
new file mode 100644
index 000000000..24be47c09
--- /dev/null
+++ b/server/src/api/as/webhook.test.ts
@@ -0,0 +1,405 @@
+import { PgDialect } from "drizzle-orm/pg-core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ execute: vi.fn(),
+ loggerInfo: vi.fn(),
+ loggerWarn: vi.fn(),
+ loggerError: vi.fn(),
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: { execute: mocks.execute },
+}));
+
+vi.mock("../../lib/const.js", () => ({
+ IS_CLOUD: true,
+}));
+
+vi.mock("../../lib/logger/logger.js", () => ({
+ logger: {
+ info: mocks.loggerInfo,
+ warn: mocks.loggerWarn,
+ error: mocks.loggerError,
+ },
+}));
+
+import { handleAppSumoWebhook } from "./webhook.js";
+
+const dialect = new PgDialect();
+
+// Renders the drizzle sql`` object passed to db.execute on the nth call into
+// { sql, params } so we can assert the intended statement and bind values.
+function executedQuery(n: number) {
+ return dialect.sqlToQuery(mocks.execute.mock.calls[n][0]);
+}
+
+function createRequest(body: Record<string, unknown>) {
+ return { body } as any;
+}
+
+function createReply() {
+ const reply: any = { statusCode: 200 };
+ reply.status = vi.fn((code: number) => {
+ reply.statusCode = code;
+ return reply;
+ });
+ reply.send = vi.fn((payload: unknown) => {
+ reply.payload = payload;
+ return reply;
+ });
+ return reply;
+}
+
+async function invoke(body: Record<string, unknown>) {
+ const reply = createReply();
+ await handleAppSumoWebhook(createRequest(body), reply);
+ return reply;
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ process.env.APPSUMO_CLIENT_ID = "as_client_id";
+ process.env.APPSUMO_CLIENT_SECRET = "as_client_secret";
+ mocks.execute.mockResolvedValue([]);
+});
+
+describe("handleAppSumoWebhook β€” availability gate", () => {
+ it("returns 503 without touching the db when AppSumo credentials are not configured", async () => {
+ delete process.env.APPSUMO_CLIENT_ID;
+
+ const reply = await invoke({ event: "purchase", license_key: "lic_1" });
+
+ expect(reply.statusCode).toBe(503);
+ expect(reply.payload).toEqual({ error: "AppSumo integration is not available" });
+ expect(mocks.execute).not.toHaveBeenCalled();
+ });
+});
+
+describe("handleAppSumoWebhook β€” test webhooks", () => {
+ it.each([
+ ["test flag", { test: true, event: "purchase", license_key: "lic_1" }],
+ ["test event", { event: "test", license_key: "lic_1" }],
+ ])("acknowledges a %s payload without any db access", async (_label, body) => {
+ const reply = await invoke(body);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({ event: "test", success: true });
+ expect(mocks.execute).not.toHaveBeenCalled();
+ });
+});
+
+describe("handleAppSumoWebhook β€” payload validation", () => {
+ // PINNED: validation failures are still acknowledged with HTTP 200 (with
+ // success: false in the body) rather than a 4xx β€” the handler always acks.
+ it("rejects a payload with a missing license_key before any db write", async () => {
+ const reply = await invoke({ event: "purchase" });
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({
+ event: "purchase",
+ success: false,
+ error: "Missing license_key in webhook payload",
+ });
+ expect(mocks.execute).not.toHaveBeenCalled();
+ });
+
+ it("rejects a payload with a missing event before any db write", async () => {
+ const reply = await invoke({ license_key: "lic_1" });
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({
+ event: "unknown",
+ success: false,
+ error: "Missing event in webhook payload",
+ });
+ expect(mocks.execute).not.toHaveBeenCalled();
+ });
+
+ it("rejects an unknown event type before any db write", async () => {
+ const reply = await invoke({ event: "refund", license_key: "lic_1" });
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({
+ event: "refund",
+ success: false,
+ error: "Invalid event type: refund",
+ });
+ expect(mocks.execute).not.toHaveBeenCalled();
+ });
+});
+
+describe("handleAppSumoWebhook β€” audit trail", () => {
+ it("logs every valid webhook to appsumo.webhook_events with the full payload", async () => {
+ const body = { event: "deactivate", license_key: "lic_audit" };
+ await invoke(body);
+
+ const audit = executedQuery(0);
+ expect(audit.sql).toContain("INSERT INTO appsumo.webhook_events");
+ expect(audit.params).toEqual(["lic_audit", "deactivate", JSON.stringify(body)]);
+ });
+
+ it("acks with 200 + success:false when the db throws mid-processing", async () => {
+ // PINNED: db failures are swallowed and acknowledged (200) so AppSumo will
+ // not retry β€” the event is effectively lost apart from the error log.
+ mocks.execute.mockRejectedValueOnce(new Error("connection refused"));
+
+ const reply = await invoke({ event: "deactivate", license_key: "lic_err" });
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({
+ event: "deactivate",
+ success: false,
+ error: "connection refused",
+ });
+ });
+});
+
+describe("handleAppSumoWebhook β€” purchase", () => {
+ it("creates a pending placeholder license for a new license_key", async () => {
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([]) // existence check: not found
+ .mockResolvedValueOnce([]); // insert
+
+ const reply = await invoke({
+ event: "purchase",
+ license_key: "lic_new",
+ tier: 3,
+ parent_license_key: "lic_parent",
+ });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(3);
+
+ const existence = executedQuery(1);
+ expect(existence.sql).toContain("SELECT id FROM appsumo.licenses");
+ expect(existence.params).toEqual(["lic_new"]);
+
+ const insert = executedQuery(2);
+ expect(insert.sql).toContain("INSERT INTO appsumo.licenses");
+ expect(insert.sql).toContain("'pending'");
+ expect(insert.sql).toContain("ON CONFLICT (license_key) DO NOTHING");
+ expect(insert.params).toEqual(["lic_new", "3", "lic_parent"]);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({ event: "purchase", success: true });
+ });
+
+ it("skips the insert when the license already exists", async () => {
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([{ id: 7 }]); // existence check: found
+
+ const reply = await invoke({ event: "purchase", license_key: "lic_dup", tier: 2 });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(2);
+ expect(reply.payload).toEqual({ event: "purchase", success: true });
+ });
+});
+
+describe("handleAppSumoWebhook β€” activate", () => {
+ it("marks the license active with the given tier", async () => {
+ await invoke({ event: "activate", license_key: "lic_act", tier: "2" });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(2);
+ const update = executedQuery(1);
+ expect(update.sql).toContain("UPDATE appsumo.licenses");
+ expect(update.sql).toContain("status = 'active'");
+ expect(update.params).toEqual(["2", "lic_act"]);
+ });
+
+ // PINNED current behavior of `tier?.toString() || "1"` β€” a suspected weakness:
+ // - missing/null/"" tier silently defaults to tier "1"
+ // - numeric 0 does NOT default: (0).toString() === "0" is a truthy string, so
+ // a `tier: 0` payload writes the (presumably invalid) tier "0" to the db.
+ // The defaulting also means a malformed upgrade payload can silently demote a
+ // license to tier 1.
+ it.each([
+ ["missing", undefined, "1"],
+ ["null", null, "1"],
+ ["empty string", "", "1"],
+ ["numeric zero", 0, "0"],
+ ])("tier defaulting: %s tier is written as %s", async (_label, tier, expected) => {
+ await invoke({ event: "activate", license_key: "lic_tier", tier: tier as any });
+
+ const update = executedQuery(1);
+ expect(update.params).toEqual([expected, "lic_tier"]);
+ });
+});
+
+describe("handleAppSumoWebhook β€” upgrade", () => {
+ it("transfers the org from the previous license, activates the new key, deactivates the old", async () => {
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([{ organization_id: "org_1" }]) // old license lookup
+ .mockResolvedValueOnce([]) // insert new active license
+ .mockResolvedValueOnce([]); // deactivate old license
+
+ const reply = await invoke({ event: "upgrade", license_key: "lic_new", prev_license_key: "lic_old", tier: 4 });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(4);
+
+ const lookup = executedQuery(1);
+ expect(lookup.sql).toContain("SELECT organization_id FROM appsumo.licenses");
+ expect(lookup.params).toEqual(["lic_old"]);
+
+ const insert = executedQuery(2);
+ expect(insert.sql).toContain("INSERT INTO appsumo.licenses");
+ expect(insert.sql).toContain("'active'");
+ expect(insert.sql).toContain("ON CONFLICT (license_key) DO UPDATE");
+ // [org, new key, tier, org (conflict set), tier (conflict set)]
+ expect(insert.params).toEqual(["org_1", "lic_new", "4", "org_1", "4"]);
+
+ const deactivate = executedQuery(3);
+ expect(deactivate.sql).toContain("status = 'inactive'");
+ expect(deactivate.params).toEqual(["lic_old"]);
+
+ expect(reply.payload).toEqual({ event: "upgrade", success: true });
+ });
+
+ it("creates a pending license when the previous license has no organization yet", async () => {
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([{ organization_id: null }]) // old license, unlinked
+ .mockResolvedValueOnce([]) // insert pending license
+ .mockResolvedValueOnce([]); // deactivate old license
+
+ await invoke({ event: "upgrade", license_key: "lic_new", prev_license_key: "lic_old", tier: 2 });
+
+ const insert = executedQuery(2);
+ expect(insert.sql).toContain("'pending'");
+ expect(insert.params).toEqual(["lic_new", "2", "2"]);
+
+ const deactivate = executedQuery(3);
+ expect(deactivate.params).toEqual(["lic_old"]);
+ });
+
+ it("PINNED: missing prev_license_key is silently ignored after the audit log, still acked as success", async () => {
+ const reply = await invoke({ event: "upgrade", license_key: "lic_new", tier: 4 });
+
+ // Only the audit-trail insert ran β€” no license was created or mutated,
+ // yet AppSumo is told the upgrade succeeded.
+ expect(mocks.execute).toHaveBeenCalledTimes(1);
+ expect(executedQuery(0).sql).toContain("INSERT INTO appsumo.webhook_events");
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({ event: "upgrade", success: true });
+ });
+
+ it("PINNED (suspected bug): unknown prev_license_key falls back to ANY license with an org and transfers that org", async () => {
+ // If the previous license is not found, the handler grabs the most
+ // recently updated license belonging to ANY organization and attaches the
+ // new license to it. On this public, unauthenticated endpoint that means a
+ // fabricated upgrade payload with an unknown prev_license_key can mint an
+ // active license attached to another customer's organization.
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([]) // old license lookup: not found
+ .mockResolvedValueOnce([{ organization_id: "org_someone_else" }]) // fallback lookup
+ .mockResolvedValueOnce([]) // insert new active license
+ .mockResolvedValueOnce([]); // deactivate (nonexistent) old license
+
+ const reply = await invoke({
+ event: "upgrade",
+ license_key: "lic_forged",
+ prev_license_key: "lic_unknown",
+ tier: 5,
+ });
+
+ const fallback = executedQuery(2);
+ expect(fallback.sql).toContain("WHERE organization_id IS NOT NULL");
+ expect(fallback.sql).toContain("ORDER BY updated_at DESC");
+
+ const insert = executedQuery(3);
+ expect(insert.sql).toContain("'active'");
+ expect(insert.params).toEqual(["org_someone_else", "lic_forged", "5", "org_someone_else", "5"]);
+
+ expect(reply.payload).toEqual({ event: "upgrade", success: true });
+ });
+
+ it("gives up when neither the previous license nor any fallback license exists", async () => {
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([]) // old license lookup: not found
+ .mockResolvedValueOnce([]); // fallback lookup: nothing
+
+ const reply = await invoke({ event: "upgrade", license_key: "lic_new", prev_license_key: "lic_gone", tier: 2 });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(3);
+ // Still acked as success despite doing nothing.
+ expect(reply.payload).toEqual({ event: "upgrade", success: true });
+ });
+});
+
+describe("handleAppSumoWebhook β€” downgrade", () => {
+ it("transfers the org to the new lower-tier license and deactivates the old one", async () => {
+ mocks.execute
+ .mockResolvedValueOnce([]) // audit insert
+ .mockResolvedValueOnce([{ organization_id: "org_1" }]) // old license lookup
+ .mockResolvedValueOnce([]) // insert new active license
+ .mockResolvedValueOnce([]); // deactivate old license
+
+ const reply = await invoke({ event: "downgrade", license_key: "lic_down", prev_license_key: "lic_old", tier: 1 });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(4);
+
+ const insert = executedQuery(2);
+ expect(insert.sql).toContain("'active'");
+ expect(insert.params).toEqual(["org_1", "lic_down", "1", "org_1", "1"]);
+
+ const deactivate = executedQuery(3);
+ expect(deactivate.sql).toContain("status = 'inactive'");
+ expect(deactivate.params).toEqual(["lic_old"]);
+
+ expect(reply.payload).toEqual({ event: "downgrade", success: true });
+ });
+
+ it("PINNED: missing prev_license_key on downgrade is also silently ignored but acked as success", async () => {
+ const reply = await invoke({ event: "downgrade", license_key: "lic_down", tier: 1 });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(1); // audit insert only
+ expect(reply.payload).toEqual({ event: "downgrade", success: true });
+ });
+});
+
+describe("handleAppSumoWebhook β€” deactivate", () => {
+ it("marks the license inactive on refund/cancel", async () => {
+ await invoke({ event: "deactivate", license_key: "lic_refund", license_status: "active" });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(2);
+ const update = executedQuery(1);
+ expect(update.sql).toContain("UPDATE appsumo.licenses");
+ expect(update.sql).toContain("status = 'inactive'");
+ expect(update.params).toEqual(["lic_refund"]);
+ });
+
+ it.each(["Upgraded by customer", "Downgraded by customer"])(
+ "skips deactivation when the reason is %s (handled by the upgrade/downgrade event)",
+ async reason => {
+ const reply = await invoke({ event: "deactivate", license_key: "lic_skip", extra: { reason } });
+
+ // Only the audit-trail insert; the license row was not touched.
+ expect(mocks.execute).toHaveBeenCalledTimes(1);
+ expect(reply.payload).toEqual({ event: "deactivate", success: true });
+ }
+ );
+});
+
+describe("handleAppSumoWebhook β€” migrate", () => {
+ it("re-points the add-on at its new parent license and updates the tier", async () => {
+ await invoke({ event: "migrate", license_key: "lic_addon", tier: 2, parent_license_key: "lic_new_parent" });
+
+ expect(mocks.execute).toHaveBeenCalledTimes(2);
+ const update = executedQuery(1);
+ expect(update.sql).toContain("UPDATE appsumo.licenses");
+ expect(update.sql).toContain("parent_license_key");
+ expect(update.params).toEqual(["2", "lic_new_parent", "lic_addon"]);
+ });
+
+ it("nulls the parent when parent_license_key is missing", async () => {
+ await invoke({ event: "migrate", license_key: "lic_addon" });
+
+ const update = executedQuery(1);
+ // Tier also defaults to "1" here (same pinned defaulting as activate).
+ expect(update.params).toEqual(["1", null, "lic_addon"]);
+ });
+});
diff --git a/server/src/api/gsc/utils.ts b/server/src/api/gsc/utils.ts
index 16832305e..90497f3d5 100644
--- a/server/src/api/gsc/utils.ts
+++ b/server/src/api/gsc/utils.ts
@@ -89,10 +89,10 @@ export async function refreshGSCToken(siteId: number): Promise<string | null> {
const now = new Date();
const fiveMinutesFromNow = new Date(now.getTime() + 5 * 60 * 1000);
- // if (expiresAt > fiveMinutesFromNow) {
- // // Token is still valid
- // return connection.accessToken;
- // }
+ if (expiresAt > fiveMinutesFromNow) {
+ // Token is still valid
+ return connection.accessToken;
+ }
// Token is expired or about to expire, refresh it
const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
diff --git a/server/src/api/sites/addSite.test.ts b/server/src/api/sites/addSite.test.ts
new file mode 100644
index 000000000..5d9084459
--- /dev/null
+++ b/server/src/api/sites/addSite.test.ts
@@ -0,0 +1,310 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = vi.hoisted(() => ({
+ isCloud: true,
+ existingSiteCount: 0,
+ insertedValues: [] as Record<string, unknown>[],
+}));
+
+const mocks = vi.hoisted(() => ({
+ getSubscriptionInner: vi.fn(),
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: {
+ select: vi.fn(() => ({
+ from: () => ({
+ where: async () => Array.from({ length: state.existingSiteCount }, (_, i) => ({ siteId: i + 1 })),
+ }),
+ })),
+ insert: vi.fn(() => ({
+ values: (values: Record<string, unknown>) => ({
+ returning: async () => {
+ state.insertedValues.push(values);
+ return [{ siteId: 1, ...values }];
+ },
+ }),
+ })),
+ },
+}));
+
+vi.mock("../../lib/const.js", async importOriginal => {
+ const actual = await importOriginal<typeof import("../../lib/const.js")>();
+ return {
+ ...actual,
+ get IS_CLOUD() {
+ return state.isCloud;
+ },
+ };
+});
+
+vi.mock("../stripe/getSubscription.js", () => ({
+ getSubscriptionInner: mocks.getSubscriptionInner,
+}));
+
+import { addSite } from "./addSite.js";
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function makeRequest(body: Record<string, unknown>, organizationId = "org_1") {
+ return {
+ params: { organizationId },
+ body: { domain: "example.com", name: "Example", ...body },
+ user: { id: "u_1" },
+ } as any;
+}
+
+/** Shape returned by getSubscriptionInner β€” only the fields addSite reads. */
+function subscription(overrides: Partial<{ planName: string; status: string; siteLimit: number | null }> = {}) {
+ return { planName: "basic-100k", status: "active", siteLimit: 1, ...overrides };
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ state.isCloud = true;
+ state.existingSiteCount = 0;
+ state.insertedValues.length = 0;
+ mocks.getSubscriptionInner.mockResolvedValue(subscription());
+});
+
+describe("addSite β€” cloud pro-feature gating (session replay)", () => {
+ it("rejects session replay on a non-pro plan and inserts nothing", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ planName: "basic-100k", status: "active" }));
+ const reply = replyStub();
+
+ await addSite(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Session replay requires a Pro subscription");
+ expect(state.insertedValues).toHaveLength(0);
+ });
+
+ it("returns 404 before any feature gating when the org does not exist", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(null);
+ const reply = replyStub();
+
+ await addSite(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("Organization not found");
+ expect(state.insertedValues).toHaveLength(0);
+ });
+
+ it("allows session replay on a pro plan", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ planName: "pro-1m", siteLimit: null }));
+ const reply = replyStub();
+
+ await addSite(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues).toHaveLength(1);
+ expect(state.insertedValues[0].sessionReplay).toBe(true);
+ });
+});
+
+describe("addSite β€” cloud standard-feature gating (active subscription required)", () => {
+ it("rejects standard features for a free-tier org and names each requested feature", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ planName: "free", status: "free", siteLimit: 1 }));
+ const reply = replyStub();
+
+ await addSite(makeRequest({ webVitals: true, trackErrors: true }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("The following features require an active subscription: webVitals, trackErrors");
+ expect(state.insertedValues).toHaveLength(0);
+ });
+
+ it("allows standard features on a trialing subscription (trialing counts as paying)", async () => {
+ // A pro trial gets standard features, consistent with session replay also being
+ // granted during trial.
+ mocks.getSubscriptionInner.mockResolvedValue(
+ subscription({ planName: "pro-1m", status: "trialing", siteLimit: null })
+ );
+ const reply = replyStub();
+
+ await addSite(makeRequest({ trackCopy: true, trackFormInteractions: true }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues[0]).toMatchObject({ trackCopy: true, trackFormInteractions: true });
+ });
+
+ it("allows standard features on any active subscription", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ planName: "standard-250k", siteLimit: 5 }));
+ const reply = replyStub();
+
+ await addSite(makeRequest({ webVitals: true, trackButtonClicks: true }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues[0]).toMatchObject({ webVitals: true, trackButtonClicks: true });
+ });
+
+ it("does not gate a plain site (no premium features) on subscription status", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ planName: "free", status: "free", siteLimit: 1 }));
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues).toHaveLength(1);
+ });
+});
+
+describe("addSite β€” cloud site-limit enforcement", () => {
+ it("rejects when the org is at its site limit and inserts nothing", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ siteLimit: 2 }));
+ state.existingSiteCount = 2;
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe(
+ "You have reached the limit of 2 websites for your plan. Please upgrade to add more."
+ );
+ expect(state.insertedValues).toHaveLength(0);
+ });
+
+ it("uses the singular form for a limit of 1", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ siteLimit: 1 }));
+ state.existingSiteCount = 1;
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toContain("limit of 1 website for your plan");
+ });
+
+ it("allows adding a site while under the limit", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ siteLimit: 2 }));
+ state.existingSiteCount = 1;
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues).toHaveLength(1);
+ });
+
+ it("treats a null siteLimit as unlimited", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue(subscription({ planName: "pro-1m", siteLimit: null }));
+ state.existingSiteCount = 500;
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(201);
+ });
+
+ it("returns 404 and inserts nothing when the organization does not exist", async () => {
+ // getSubscriptionInner returns null only when the organization row is missing;
+ // a missing org gets no site at all, regardless of existing site count.
+ mocks.getSubscriptionInner.mockResolvedValue(null);
+ for (const existingSiteCount of [0, 500]) {
+ state.existingSiteCount = existingSiteCount;
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("Organization not found");
+ }
+ expect(state.insertedValues).toHaveLength(0);
+ });
+});
+
+describe("addSite β€” self-hosted (IS_CLOUD=false) bypasses all gating", () => {
+ beforeEach(() => {
+ state.isCloud = false;
+ });
+
+ it("allows session replay and standard features without any subscription check", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ sessionReplay: true, webVitals: true, trackErrors: true }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(mocks.getSubscriptionInner).not.toHaveBeenCalled();
+ expect(state.insertedValues[0]).toMatchObject({ sessionReplay: true, webVitals: true, trackErrors: true });
+ });
+
+ it("enforces no site limit", async () => {
+ state.existingSiteCount = 500;
+ const reply = replyStub();
+
+ await addSite(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(201);
+ });
+});
+
+describe("addSite β€” domain validation", () => {
+ it("rejects an invalid web domain before any subscription check", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ domain: "not_a_domain" }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Invalid domain format");
+ expect(mocks.getSubscriptionInner).not.toHaveBeenCalled();
+ expect(state.insertedValues).toHaveLength(0);
+ });
+
+ it("strips protocol and trailing slashes before validating and storing", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ domain: "https://sub.example.com//" }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues[0].domain).toBe("sub.example.com");
+ });
+
+ it("stores web sites with a null type", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ type: "web" }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues[0].type).toBeNull();
+ });
+
+ it("accepts a bundle identifier for mobile sites", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ type: "mobile", domain: "com.example.app" }), reply);
+
+ expect(reply.statusCode).toBe(201);
+ expect(state.insertedValues[0]).toMatchObject({ type: "mobile", domain: "com.example.app" });
+ });
+
+ it("rejects an invalid mobile app identifier", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ type: "mobile", domain: "..bad identifier!" }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Invalid app identifier");
+ expect(state.insertedValues).toHaveLength(0);
+ });
+
+ it("rejects session replay and web vitals for mobile sites", async () => {
+ const reply = replyStub();
+
+ await addSite(makeRequest({ type: "mobile", domain: "com.example.app", sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Session replay and Web Vitals are only available for web sites");
+ expect(state.insertedValues).toHaveLength(0);
+ });
+});
diff --git a/server/src/api/sites/addSite.ts b/server/src/api/sites/addSite.ts
index 4e6bfda00..aaac2e7e5 100644
--- a/server/src/api/sites/addSite.ts
+++ b/server/src/api/sites/addSite.ts
@@ -90,7 +90,13 @@ export async function addSite(
if (IS_CLOUD) {
const subscription = await getSubscriptionInner(organizationId);
- if (sessionReplay && !subscription?.planName.includes("pro")) {
+ // getSubscriptionInner returns null only when the organization row doesn't exist.
+ // Middleware makes this near-unreachable, but a missing org gets no site at all.
+ if (!subscription) {
+ return reply.status(404).send({ error: "Organization not found" });
+ }
+
+ if (sessionReplay && !subscription.planName.includes("pro")) {
return reply.status(403).send({
error: "Session replay requires a Pro subscription",
});
@@ -98,14 +104,18 @@ export async function addSite(
const standardFeatures = { webVitals, trackErrors, trackButtonClicks, trackCopy, trackFormInteractions };
const requestedStandard = Object.entries(standardFeatures).filter(([, v]) => v);
- if (requestedStandard.length > 0 && subscription?.status !== "active") {
+ // Trialing counts as paying: a pro trial gets standard features, consistent with
+ // session replay being granted during trial above.
+ const hasActiveSubscription = subscription?.status === "active" || subscription?.status === "trialing";
+ if (requestedStandard.length > 0 && !hasActiveSubscription) {
return reply.status(403).send({
error: `The following features require an active subscription: ${requestedStandard.map(([k]) => k).join(", ")}`,
});
}
- // Enforce site limit
- const siteLimit = subscription?.siteLimit ?? null;
+ // Enforce site limit. A null siteLimit means unlimited; the missing-org case
+ // already returned 404 above.
+ const siteLimit = subscription.siteLimit ?? null;
if (siteLimit !== null) {
const existingSites = await db
.select({ siteId: sites.siteId })
diff --git a/server/src/api/sites/moveSite.test.ts b/server/src/api/sites/moveSite.test.ts
new file mode 100644
index 000000000..ce6161114
--- /dev/null
+++ b/server/src/api/sites/moveSite.test.ts
@@ -0,0 +1,267 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = vi.hoisted(() => ({
+ isCloud: true,
+ site: null as Record<string, unknown> | null,
+ targetOrg: null as Record<string, unknown> | null,
+ targetMembership: null as { role: string } | null,
+ targetOrgSiteCount: 0,
+}));
+
+const mocks = vi.hoisted(() => ({
+ getSubscriptionInner: vi.fn(),
+ applySiteMove: vi.fn(async () => {}),
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: {
+ query: {
+ sites: { findFirst: vi.fn(async () => state.site) },
+ organization: { findFirst: vi.fn(async () => state.targetOrg) },
+ member: { findFirst: vi.fn(async () => state.targetMembership) },
+ },
+ // Only used to count the target organization's existing sites.
+ select: vi.fn(() => ({
+ from: () => ({
+ where: async () => Array.from({ length: state.targetOrgSiteCount }, (_, i) => ({ siteId: i + 100 })),
+ }),
+ })),
+ },
+}));
+
+vi.mock("../../lib/const.js", async importOriginal => {
+ const actual = await importOriginal<typeof import("../../lib/const.js")>();
+ return {
+ ...actual,
+ get IS_CLOUD() {
+ return state.isCloud;
+ },
+ };
+});
+
+vi.mock("../stripe/getSubscription.js", () => ({
+ getSubscriptionInner: mocks.getSubscriptionInner,
+}));
+
+vi.mock("./applySiteMove.js", () => ({
+ applySiteMove: mocks.applySiteMove,
+}));
+
+import { moveSite } from "./moveSite.js";
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+// null means "explicitly absent" (anonymous caller / missing body field).
+function makeRequest({
+ siteId = "1",
+ organizationId = "org_target",
+ userId = "u_caller",
+}: { siteId?: string; organizationId?: unknown; userId?: string | null } = {}) {
+ return {
+ params: { siteId },
+ body: organizationId === null ? {} : { organizationId },
+ user: userId === null ? undefined : { id: userId },
+ } as any;
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ state.isCloud = true;
+ state.site = { siteId: 1, organizationId: "org_source", domain: "example.com" };
+ state.targetOrg = { id: "org_target", name: "Target Org" };
+ state.targetMembership = { role: "admin" };
+ state.targetOrgSiteCount = 0;
+ mocks.getSubscriptionInner.mockResolvedValue({ planName: "pro-1m", status: "active", siteLimit: null });
+});
+
+// The adminSite middleware only vouches for the SOURCE site's organization. The
+// handler's inline membership check on the TARGET organization is the sole gate
+// preventing anyone from moving a site into an org they don't control.
+describe("moveSite β€” target-organization authorization (sole gate)", () => {
+ it("moves the site when the caller is an admin of the target org", async () => {
+ state.targetMembership = { role: "admin" };
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body).toEqual({ success: true, organizationId: "org_target" });
+ expect(mocks.applySiteMove).toHaveBeenCalledWith(1, "org_source", "org_target");
+ });
+
+ it("moves the site when the caller is an owner of the target org", async () => {
+ state.targetMembership = { role: "owner" };
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.applySiteMove).toHaveBeenCalledTimes(1);
+ });
+
+ it("rejects a plain member of the target org and writes no ownership change", async () => {
+ state.targetMembership = { role: "member" };
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("You must be an admin or owner of the target organization");
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("rejects a caller with no membership in the target org and writes no ownership change", async () => {
+ state.targetMembership = null;
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("You are not a member of the target organization");
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("rejects an unauthenticated request", async () => {
+ const reply = replyStub();
+
+ await moveSite(makeRequest({ userId: null }), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+});
+
+describe("moveSite β€” target-organization site limit (cloud)", () => {
+ it("rejects the move when the target org is at its site limit", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue({ planName: "standard-250k", status: "active", siteLimit: 5 });
+ state.targetOrgSiteCount = 5;
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe(
+ "The target organization has reached its limit of 5 websites. Please upgrade it to add more."
+ );
+ expect(mocks.getSubscriptionInner).toHaveBeenCalledWith("org_target");
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("allows the move while the target org is under its limit", async () => {
+ mocks.getSubscriptionInner.mockResolvedValue({ planName: "standard-250k", status: "active", siteLimit: 5 });
+ state.targetOrgSiteCount = 4;
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.applySiteMove).toHaveBeenCalledTimes(1);
+ });
+
+ it("treats a null siteLimit as unlimited", async () => {
+ state.targetOrgSiteCount = 500;
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(200);
+ });
+
+ it("skips the subscription check entirely when self-hosted", async () => {
+ state.isCloud = false;
+ state.targetOrgSiteCount = 500;
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.getSubscriptionInner).not.toHaveBeenCalled();
+ expect(mocks.applySiteMove).toHaveBeenCalledWith(1, "org_source", "org_target");
+ });
+});
+
+describe("moveSite β€” request and target validation", () => {
+ it("rejects a move into the site's current organization", async () => {
+ state.site = { siteId: 1, organizationId: "org_target", domain: "example.com" };
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Site is already in this organization");
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("gives a non-member the same 403 whether or not the target org exists (no existence oracle)", async () => {
+ state.targetMembership = null;
+
+ state.targetOrg = { id: "org_target", name: "Target Org" };
+ const existingOrgReply = replyStub();
+ await moveSite(makeRequest(), existingOrgReply);
+
+ state.targetOrg = null;
+ const missingOrgReply = replyStub();
+ await moveSite(makeRequest(), missingOrgReply);
+
+ expect(existingOrgReply.statusCode).toBe(403);
+ expect(missingOrgReply.statusCode).toBe(403);
+ expect(missingOrgReply.body).toEqual(existingOrgReply.body);
+ expect(missingOrgReply.body.error).toBe("You are not a member of the target organization");
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("returns 404 for a missing target org only after the membership check passes", async () => {
+ // Only reachable with a (stale) admin membership row for the missing org, so the
+ // 404 cannot be used by outsiders to probe org IDs.
+ state.targetOrg = null;
+ state.targetMembership = { role: "admin" };
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("Target organization not found");
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("returns 404 when the site does not exist", async () => {
+ state.site = null;
+ const reply = replyStub();
+
+ await moveSite(makeRequest(), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("Site not found");
+ });
+
+ it("rejects non-positive or non-numeric site ids", async () => {
+ for (const siteId of ["abc", "-1", "0"]) {
+ const reply = replyStub();
+ await moveSite(makeRequest({ siteId }), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Invalid site ID");
+ }
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+
+ it("rejects a missing or empty target organizationId", async () => {
+ for (const organizationId of [null, ""]) {
+ const reply = replyStub();
+ await moveSite(makeRequest({ organizationId }), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Invalid request data");
+ }
+ expect(mocks.applySiteMove).not.toHaveBeenCalled();
+ });
+});
diff --git a/server/src/api/sites/moveSite.ts b/server/src/api/sites/moveSite.ts
index 0ef06a140..a79eae456 100644
--- a/server/src/api/sites/moveSite.ts
+++ b/server/src/api/sites/moveSite.ts
@@ -49,15 +49,9 @@ export async function moveSite(
return reply.status(400).send({ error: "Site is already in this organization" });
}
- // Target organization must exist.
- const targetOrg = await db.query.organization.findFirst({
- where: eq(organization.id, targetOrganizationId),
- });
- if (!targetOrg) {
- return reply.status(404).send({ error: "Target organization not found" });
- }
-
- // Caller must be an admin/owner of the target organization.
+ // Caller must be an admin/owner of the target organization. This runs BEFORE the
+ // org-existence check so a caller without target-org access gets the same 403
+ // whether or not the org exists β€” no org-ID existence oracle.
const targetMembership = await db.query.member.findFirst({
where: and(eq(member.userId, userId), eq(member.organizationId, targetOrganizationId)),
});
@@ -68,6 +62,16 @@ export async function moveSite(
return reply.status(403).send({ error: "You must be an admin or owner of the target organization" });
}
+ // Target organization must exist. Only reachable by target-org admins/owners
+ // (a membership row for a nonexistent org shouldn't exist, but guard against
+ // stale rows) so the 404 can't be used to probe org IDs.
+ const targetOrg = await db.query.organization.findFirst({
+ where: eq(organization.id, targetOrganizationId),
+ });
+ if (!targetOrg) {
+ return reply.status(404).send({ error: "Target organization not found" });
+ }
+
// Enforce the target organization's site limit on cloud.
if (IS_CLOUD) {
const subscription = await getSubscriptionInner(targetOrganizationId);
diff --git a/server/src/api/sites/updateSiteConfig.test.ts b/server/src/api/sites/updateSiteConfig.test.ts
new file mode 100644
index 000000000..f324eb4f2
--- /dev/null
+++ b/server/src/api/sites/updateSiteConfig.test.ts
@@ -0,0 +1,307 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AppSumoSubscriptionInfo, StripeSubscriptionInfo } from "../../lib/subscriptionUtils.js";
+
+const state = vi.hoisted(() => ({
+ isCloud: true,
+ site: null as Record<string, unknown> | null,
+ orgRow: null as { stripeCustomerId: string | null } | null,
+ updates: [] as Record<string, unknown>[],
+}));
+
+const mocks = vi.hoisted(() => ({
+ getBestSubscription: vi.fn(),
+ updateConfig: vi.fn(async () => {}),
+ getConfig: vi.fn(async () => ({ siteId: 1 })),
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: {
+ query: {
+ sites: {
+ findFirst: vi.fn(async () => state.site),
+ },
+ },
+ // Only used for the organization stripeCustomerId lookup in the replay gate.
+ select: vi.fn(() => ({
+ from: () => ({
+ where: () => ({
+ limit: async () => (state.orgRow ? [state.orgRow] : []),
+ }),
+ }),
+ })),
+ update: vi.fn(() => ({
+ set: (data: Record<string, unknown>) => ({
+ where: async () => {
+ state.updates.push(data);
+ },
+ }),
+ })),
+ },
+}));
+
+vi.mock("../../lib/const.js", async importOriginal => {
+ const actual = await importOriginal<typeof import("../../lib/const.js")>();
+ return {
+ ...actual,
+ get IS_CLOUD() {
+ return state.isCloud;
+ },
+ };
+});
+
+vi.mock("../../lib/siteConfig.js", () => ({
+ siteConfig: { updateConfig: mocks.updateConfig, getConfig: mocks.getConfig },
+}));
+
+// Keep the real subscriptionIncludesReplay so the test exercises the actual
+// entitlement rules; only the subscription lookup itself is stubbed.
+vi.mock("../../lib/subscriptionUtils.js", async importOriginal => {
+ const actual = await importOriginal<typeof import("../../lib/subscriptionUtils.js")>();
+ return { ...actual, getBestSubscription: mocks.getBestSubscription };
+});
+
+import { updateSiteConfig } from "./updateSiteConfig.js";
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function makeRequest(body: Record<string, unknown>, siteId = "1") {
+ return { params: { siteId }, body } as any;
+}
+
+function makeSite(overrides: Record<string, unknown> = {}) {
+ return {
+ siteId: 1,
+ id: "abcdef123456",
+ type: null,
+ domain: "example.com",
+ organizationId: "org_1",
+ sessionReplay: false,
+ ...overrides,
+ };
+}
+
+function stripeSubscription(planName: string, overrides: Partial<StripeSubscriptionInfo> = {}): StripeSubscriptionInfo {
+ return {
+ source: "stripe",
+ subscriptionId: "sub_1",
+ priceId: "price_1",
+ planName,
+ eventLimit: 100_000,
+ replayLimit: 0,
+ periodStart: "2026-07-01",
+ currentPeriodEnd: new Date("2026-08-01T00:00:00Z"),
+ status: "active",
+ interval: "month",
+ cancelAtPeriodEnd: false,
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ ...overrides,
+ };
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ state.isCloud = true;
+ state.site = makeSite();
+ state.orgRow = { stripeCustomerId: "cus_1" };
+ state.updates.length = 0;
+ mocks.getBestSubscription.mockResolvedValue(stripeSubscription("basic-100k"));
+});
+
+describe("updateSiteConfig β€” session replay pro gating (the only subscription-gated field)", () => {
+ it("rejects enabling session replay on a non-pro plan and writes nothing", async () => {
+ mocks.getBestSubscription.mockResolvedValue(stripeSubscription("basic-100k", { replayLimit: 2500 }));
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Session replay requires a Pro plan");
+ expect(state.updates).toHaveLength(0);
+ expect(mocks.updateConfig).not.toHaveBeenCalled();
+ expect(mocks.getBestSubscription).toHaveBeenCalledWith("org_1", "cus_1");
+ });
+
+ it("allows enabling session replay on a pro plan", async () => {
+ mocks.getBestSubscription.mockResolvedValue(stripeSubscription("pro-1m", { replayLimit: 10_000 }));
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body.success).toBe(true);
+ expect(state.updates[0]).toMatchObject({ sessionReplay: true });
+ expect(mocks.updateConfig).toHaveBeenCalledWith(1, expect.objectContaining({ sessionReplay: true }));
+ });
+
+ it("rejects enabling session replay during a large (>=500k events) pro trial", async () => {
+ mocks.getBestSubscription.mockResolvedValue(
+ stripeSubscription("pro-1m", { status: "trialing", eventLimit: 500_000, replayLimit: 10_000 })
+ );
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(state.updates).toHaveLength(0);
+ });
+
+ it("allows enabling session replay on an AppSumo tier with a replay entitlement", async () => {
+ const appsumo: AppSumoSubscriptionInfo = {
+ source: "appsumo",
+ tier: "4",
+ eventLimit: 1_000_000,
+ replayLimit: 5_000,
+ periodStart: "2026-07-01",
+ planName: "appsumo-4",
+ status: "active",
+ interval: "lifetime",
+ cancelAtPeriodEnd: false,
+ };
+ mocks.getBestSubscription.mockResolvedValue(appsumo);
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(state.updates[0]).toMatchObject({ sessionReplay: true });
+ });
+
+ it("always allows turning session replay off, without a subscription lookup", async () => {
+ state.site = makeSite({ sessionReplay: true });
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: false }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(state.updates[0]).toMatchObject({ sessionReplay: false });
+ expect(mocks.getBestSubscription).not.toHaveBeenCalled();
+ });
+
+ it("rejects enabling session replay on a cloud site with no organization", async () => {
+ // Pinning actual behavior: when site.organizationId is null, includesReplay stays
+ // false and the request is rejected β€” an orphan site can never enable replay on cloud.
+ state.site = makeSite({ organizationId: null });
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(mocks.getBestSubscription).not.toHaveBeenCalled();
+ expect(state.updates).toHaveLength(0);
+ });
+});
+
+describe("updateSiteConfig β€” self-hosted (IS_CLOUD=false) bypass", () => {
+ it("allows enabling session replay without any subscription lookup", async () => {
+ state.isCloud = false;
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.getBestSubscription).not.toHaveBeenCalled();
+ expect(state.updates[0]).toMatchObject({ sessionReplay: true });
+ });
+});
+
+describe("updateSiteConfig β€” non-gated fields update without subscription checks", () => {
+ it("updates settings and analytics toggles on a non-pro cloud plan", async () => {
+ const reply = replyStub();
+
+ await updateSiteConfig(
+ makeRequest({
+ name: "Renamed",
+ public: true,
+ blockBots: false,
+ webVitals: true,
+ trackErrors: true,
+ excludedCountries: ["US", "GB"],
+ tags: ["prod"],
+ }),
+ reply
+ );
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.getBestSubscription).not.toHaveBeenCalled();
+ expect(state.updates[0]).toMatchObject({
+ name: "Renamed",
+ public: true,
+ blockBots: false,
+ webVitals: true,
+ trackErrors: true,
+ excludedCountries: ["US", "GB"],
+ tags: ["prod"],
+ });
+ expect(mocks.updateConfig).toHaveBeenCalledWith(1, state.updates[0]);
+ });
+
+ it("cleans and stores an updated domain", async () => {
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ domain: "https://new.example.com/" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(state.updates[0]).toMatchObject({ domain: "new.example.com" });
+ });
+
+ it("rejects invalid excluded IP patterns", async () => {
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ excludedIPs: ["999.999.0.1"] }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Invalid IP patterns");
+ expect(state.updates).toHaveLength(0);
+ });
+});
+
+describe("updateSiteConfig β€” request validation", () => {
+ it("rejects a non-numeric site id", async () => {
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ name: "x" }, "abc"), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Invalid site ID");
+ });
+
+ it("returns 404 for an unknown site", async () => {
+ state.site = null;
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ name: "x" }), reply);
+
+ expect(reply.statusCode).toBe(404);
+ });
+
+ it("rejects enabling session replay on a mobile site before the pro gate", async () => {
+ state.site = makeSite({ type: "mobile", domain: "com.example.app" });
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({ sessionReplay: true }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Session replay and Web Vitals are only available for web sites");
+ expect(mocks.getBestSubscription).not.toHaveBeenCalled();
+ });
+
+ it("rejects an empty update", async () => {
+ const reply = replyStub();
+
+ await updateSiteConfig(makeRequest({}), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("No fields to update");
+ });
+});
diff --git a/server/src/api/stripe/createCheckoutSession.test.ts b/server/src/api/stripe/createCheckoutSession.test.ts
new file mode 100644
index 000000000..7994aa005
--- /dev/null
+++ b/server/src/api/stripe/createCheckoutSession.test.ts
@@ -0,0 +1,197 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ customersCreate: vi.fn(),
+ checkoutSessionsCreate: vi.fn(),
+}));
+
+vi.mock("../../lib/stripe.js", () => ({
+ stripe: {
+ customers: { create: mocks.customersCreate },
+ checkout: { sessions: { create: mocks.checkoutSessionsCreate } },
+ },
+}));
+
+// Real Drizzle queries against PGlite so the inline membership check β€” the SOLE
+// authorization gate on this route β€” is exercised for real.
+vi.mock("../../db/postgres/postgres.js", async () => {
+ const { PGlite } = await import("@electric-sql/pglite");
+ const { drizzle } = await import("drizzle-orm/pglite");
+ const schema = await import("../../db/postgres/schema.js");
+ const client = new PGlite();
+ const db = drizzle(client, { schema });
+ return { db, sql: client };
+});
+
+import { sql } from "../../db/postgres/postgres.js";
+import { createCheckoutSession } from "./createCheckoutSession.js";
+
+const DDL = `
+CREATE TABLE "organization" ("id" text PRIMARY KEY, "name" text NOT NULL, "slug" text, "createdAt" timestamp DEFAULT now(), "stripeCustomerId" text);
+CREATE TABLE "user" ("id" text PRIMARY KEY, "name" text, "email" text, "createdAt" timestamp DEFAULT now());
+CREATE TABLE "member" ("id" text PRIMARY KEY, "organizationId" text NOT NULL, "userId" text NOT NULL, "role" text NOT NULL, "createdAt" timestamp DEFAULT now());
+`;
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function requestStub(userId: string | undefined, body: Record<string, unknown>) {
+ return { user: userId ? { id: userId } : undefined, body } as any;
+}
+
+async function orgCustomerId(orgId: string): Promise<string | null> {
+ const result = await (sql as any).query(`SELECT "stripeCustomerId" FROM "organization" WHERE "id" = $1`, [orgId]);
+ return result.rows[0]?.stripeCustomerId ?? null;
+}
+
+const validBody = { priceId: "price_pro", returnUrl: "https://app.rybbit.io/billing", organizationId: "org_1" };
+
+beforeAll(async () => {
+ await (sql as any).exec(DDL);
+});
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ await (sql as any).exec(`TRUNCATE "organization", "user", "member"`);
+ await (sql as any).exec(`
+ INSERT INTO "organization" ("id","name","slug","stripeCustomerId") VALUES
+ ('org_1','Acme','acme','cus_1'),
+ ('org_2','Rival','rival','cus_2');
+ INSERT INTO "user" ("id","name","email") VALUES
+ ('u_owner','Owner','[email protected]'),
+ ('u_member','Member','[email protected]'),
+ ('u_outsider','Outsider','[email protected]');
+ INSERT INTO "member" ("id","organizationId","userId","role") VALUES
+ ('m_owner','org_1','u_owner','owner'),
+ ('m_member','org_1','u_member','member'),
+ ('m_outsider','org_2','u_outsider','owner');
+ `);
+ mocks.customersCreate.mockResolvedValue({ id: "cus_new" });
+ mocks.checkoutSessionsCreate.mockResolvedValue({ client_secret: "cs_secret_123" });
+});
+
+describe("createCheckoutSession β€” authorization", () => {
+ it("creates a checkout session for the org owner with metadata.organizationId from the authorized org", async () => {
+ const reply = replyStub();
+
+ await createCheckoutSession(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body).toEqual({ clientSecret: "cs_secret_123" });
+ // metadata.organizationId is what the webhook later trusts β€” it must be the org
+ // the membership check authorized, not anything attacker-controlled.
+ expect(mocks.checkoutSessionsCreate).toHaveBeenCalledWith(
+ expect.objectContaining({
+ mode: "subscription",
+ ui_mode: "embedded",
+ customer: "cus_1",
+ line_items: [{ price: "price_pro", quantity: 1 }],
+ return_url: "https://app.rybbit.io/billing",
+ metadata: { organizationId: "org_1" },
+ subscription_data: { trial_period_days: 7 },
+ })
+ );
+ // Org already had a Stripe customer β€” no new customer, no DB write.
+ expect(mocks.customersCreate).not.toHaveBeenCalled();
+ expect(await orgCustomerId("org_1")).toBe("cus_1");
+ });
+
+ it("rejects a non-owner member with 403 and creates nothing", async () => {
+ const reply = replyStub();
+
+ await createCheckoutSession(requestStub("u_member", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can manage billing");
+ expect(mocks.customersCreate).not.toHaveBeenCalled();
+ expect(mocks.checkoutSessionsCreate).not.toHaveBeenCalled();
+ });
+
+ it("rejects a user with no membership in the target org (cross-org attempt)", async () => {
+ const reply = replyStub();
+
+ // u_outsider owns org_2 but must not be able to start checkout for org_1.
+ await createCheckoutSession(requestStub("u_outsider", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(mocks.customersCreate).not.toHaveBeenCalled();
+ expect(mocks.checkoutSessionsCreate).not.toHaveBeenCalled();
+ expect(await orgCustomerId("org_1")).toBe("cus_1");
+ });
+
+ it("returns 401 when there is no authenticated user", async () => {
+ const reply = replyStub();
+
+ await createCheckoutSession(requestStub(undefined, validBody), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expect(mocks.checkoutSessionsCreate).not.toHaveBeenCalled();
+ });
+
+ it("returns 400 when priceId, returnUrl or organizationId is missing", async () => {
+ for (const omit of ["priceId", "returnUrl", "organizationId"] as const) {
+ const body: Record<string, unknown> = { ...validBody };
+ delete body[omit];
+ const reply = replyStub();
+ await createCheckoutSession(requestStub("u_owner", body), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Missing required parameters");
+ }
+ expect(mocks.checkoutSessionsCreate).not.toHaveBeenCalled();
+ });
+});
+
+describe("createCheckoutSession β€” customer creation and referral wiring", () => {
+ it("creates a Stripe customer and persists it when the org has none", async () => {
+ await (sql as any).exec(`UPDATE "organization" SET "stripeCustomerId" = NULL WHERE "id" = 'org_1'`);
+ const reply = replyStub();
+
+ await createCheckoutSession(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.customersCreate).toHaveBeenCalledWith({
+ email: "[email protected]",
+ name: "Acme",
+ metadata: { organizationId: "org_1", createdByUserId: "u_owner" },
+ });
+ expect(await orgCustomerId("org_1")).toBe("cus_new");
+ expect(mocks.checkoutSessionsCreate).toHaveBeenCalledWith(expect.objectContaining({ customer: "cus_new" }));
+ });
+
+ it("threads the referral through customer metadata and client_reference_id", async () => {
+ await (sql as any).exec(`UPDATE "organization" SET "stripeCustomerId" = NULL WHERE "id" = 'org_1'`);
+ const reply = replyStub();
+
+ await createCheckoutSession(requestStub("u_owner", { ...validBody, referral: "ref_abc" }), reply);
+
+ expect(mocks.customersCreate).toHaveBeenCalledWith(
+ expect.objectContaining({ metadata: expect.objectContaining({ referral: "ref_abc" }) })
+ );
+ expect(mocks.checkoutSessionsCreate).toHaveBeenCalledWith(
+ expect.objectContaining({ client_reference_id: "ref_abc" })
+ );
+ });
+
+ it("returns 404 when the organization does not exist", async () => {
+ // Membership row without a matching organization row.
+ await (sql as any).exec(
+ `INSERT INTO "member" ("id","organizationId","userId","role") VALUES ('m_ghost','org_ghost','u_owner','owner')`
+ );
+ const reply = replyStub();
+
+ await createCheckoutSession(requestStub("u_owner", { ...validBody, organizationId: "org_ghost" }), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(mocks.checkoutSessionsCreate).not.toHaveBeenCalled();
+ });
+});
diff --git a/server/src/api/stripe/createPortalSession.test.ts b/server/src/api/stripe/createPortalSession.test.ts
new file mode 100644
index 000000000..2ca6fa8a0
--- /dev/null
+++ b/server/src/api/stripe/createPortalSession.test.ts
@@ -0,0 +1,218 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ subscriptionsList: vi.fn(),
+ portalSessionsCreate: vi.fn(),
+}));
+
+vi.mock("../../lib/stripe.js", () => ({
+ stripe: {
+ subscriptions: { list: mocks.subscriptionsList },
+ billingPortal: { sessions: { create: mocks.portalSessionsCreate } },
+ },
+}));
+
+// Real Drizzle queries against PGlite so the inline membership check β€” the SOLE
+// authorization gate on this route β€” is exercised for real.
+vi.mock("../../db/postgres/postgres.js", async () => {
+ const { PGlite } = await import("@electric-sql/pglite");
+ const { drizzle } = await import("drizzle-orm/pglite");
+ const schema = await import("../../db/postgres/schema.js");
+ const client = new PGlite();
+ const db = drizzle(client, { schema });
+ return { db, sql: client };
+});
+
+import { sql } from "../../db/postgres/postgres.js";
+import { createPortalSession } from "./createPortalSession.js";
+
+const DDL = `
+CREATE TABLE "organization" ("id" text PRIMARY KEY, "name" text NOT NULL, "slug" text, "createdAt" timestamp DEFAULT now(), "stripeCustomerId" text);
+CREATE TABLE "member" ("id" text PRIMARY KEY, "organizationId" text NOT NULL, "userId" text NOT NULL, "role" text NOT NULL, "createdAt" timestamp DEFAULT now());
+`;
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function requestStub(userId: string | undefined, body: Record<string, unknown>) {
+ return { user: userId ? { id: userId } : undefined, body } as any;
+}
+
+const validBody = { returnUrl: "https://app.rybbit.io/settings/billing", organizationId: "org_1" };
+
+beforeAll(async () => {
+ await (sql as any).exec(DDL);
+});
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ await (sql as any).exec(`TRUNCATE "organization", "member"`);
+ await (sql as any).exec(`
+ INSERT INTO "organization" ("id","name","slug","stripeCustomerId") VALUES
+ ('org_1','Acme','acme','cus_1'),
+ ('org_2','Rival','rival','cus_2');
+ INSERT INTO "member" ("id","organizationId","userId","role") VALUES
+ ('m_owner','org_1','u_owner','owner'),
+ ('m_member','org_1','u_member','member'),
+ ('m_outsider','org_2','u_outsider','owner');
+ `);
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "active" ? { data: [{ id: "sub_1", cancel_at_period_end: false }] } : { data: [] }
+ );
+ mocks.portalSessionsCreate.mockResolvedValue({ url: "https://billing.stripe.com/session/xyz" });
+});
+
+describe("createPortalSession β€” authorization", () => {
+ it("creates a plain portal session for the org owner with the requested return URL", async () => {
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body).toEqual({ portalUrl: "https://billing.stripe.com/session/xyz" });
+ expect(mocks.portalSessionsCreate).toHaveBeenCalledWith({
+ customer: "cus_1",
+ return_url: "https://app.rybbit.io/settings/billing",
+ });
+ });
+
+ it("rejects a non-owner member with 403 and never opens a portal", async () => {
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_member", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can manage billing");
+ expect(mocks.portalSessionsCreate).not.toHaveBeenCalled();
+ expect(mocks.subscriptionsList).not.toHaveBeenCalled();
+ });
+
+ it("rejects a user with no membership in the target org (cross-org attempt)", async () => {
+ const reply = replyStub();
+
+ // u_outsider owns org_2 but must not reach org_1's billing portal (cus_1).
+ await createPortalSession(requestStub("u_outsider", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(mocks.portalSessionsCreate).not.toHaveBeenCalled();
+ });
+
+ it("returns 401 when there is no authenticated user", async () => {
+ const reply = replyStub();
+
+ await createPortalSession(requestStub(undefined, validBody), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expect(mocks.portalSessionsCreate).not.toHaveBeenCalled();
+ });
+
+ it("returns 400 when returnUrl or organizationId is missing", async () => {
+ for (const body of [{ organizationId: "org_1" }, { returnUrl: "https://x.dev" }, {}]) {
+ const reply = replyStub();
+ await createPortalSession(requestStub("u_owner", body), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Missing required parameters");
+ }
+ expect(mocks.portalSessionsCreate).not.toHaveBeenCalled();
+ });
+
+ it("returns 404 when the org has no Stripe customer ID", async () => {
+ await (sql as any).exec(`UPDATE "organization" SET "stripeCustomerId" = NULL WHERE "id" = 'org_1'`);
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(mocks.portalSessionsCreate).not.toHaveBeenCalled();
+ });
+});
+
+describe("createPortalSession β€” flow types", () => {
+ it("targets the active subscription for the subscription_update flow", async () => {
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", { ...validBody, flowType: "subscription_update" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.portalSessionsCreate).toHaveBeenCalledWith({
+ customer: "cus_1",
+ return_url: validBody.returnUrl,
+ flow_data: { type: "subscription_update", subscription_update: { subscription: "sub_1" } },
+ });
+ });
+
+ it("falls back to the trialing subscription when no active one exists", async () => {
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "trialing" ? { data: [{ id: "sub_trial", cancel_at_period_end: false }] } : { data: [] }
+ );
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", { ...validBody, flowType: "subscription_update" }), reply);
+
+ expect(mocks.portalSessionsCreate).toHaveBeenCalledWith(
+ expect.objectContaining({
+ flow_data: { type: "subscription_update", subscription_update: { subscription: "sub_trial" } },
+ })
+ );
+ });
+
+ it("returns 404 for subscription_update when no subscription exists at all", async () => {
+ mocks.subscriptionsList.mockResolvedValue({ data: [] });
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", { ...validBody, flowType: "subscription_update" }), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("No active subscription found");
+ expect(mocks.portalSessionsCreate).not.toHaveBeenCalled();
+ });
+
+ it("attaches the subscription_cancel flow for a subscription not yet set to cancel", async () => {
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", { ...validBody, flowType: "subscription_cancel" }), reply);
+
+ expect(mocks.portalSessionsCreate).toHaveBeenCalledWith(
+ expect.objectContaining({
+ flow_data: { type: "subscription_cancel", subscription_cancel: { subscription: "sub_1" } },
+ })
+ );
+ });
+
+ it("opens the plain portal when the subscription is already set to cancel at period end", async () => {
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "active" ? { data: [{ id: "sub_1", cancel_at_period_end: true }] } : { data: [] }
+ );
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", { ...validBody, flowType: "subscription_cancel" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ // No flow_data β€” Stripe rejects a cancel flow for an already-cancelling subscription.
+ expect(mocks.portalSessionsCreate).toHaveBeenCalledWith({
+ customer: "cus_1",
+ return_url: validBody.returnUrl,
+ });
+ });
+
+ it("attaches the payment_method_update flow without needing a subscription lookup", async () => {
+ const reply = replyStub();
+
+ await createPortalSession(requestStub("u_owner", { ...validBody, flowType: "payment_method_update" }), reply);
+
+ expect(mocks.subscriptionsList).not.toHaveBeenCalled();
+ expect(mocks.portalSessionsCreate).toHaveBeenCalledWith(
+ expect.objectContaining({ flow_data: { type: "payment_method_update" } })
+ );
+ });
+});
diff --git a/server/src/api/stripe/getInvoices.test.ts b/server/src/api/stripe/getInvoices.test.ts
new file mode 100644
index 000000000..c55bfecf2
--- /dev/null
+++ b/server/src/api/stripe/getInvoices.test.ts
@@ -0,0 +1,174 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ invoicesList: vi.fn(),
+}));
+
+vi.mock("../../lib/stripe.js", () => ({
+ stripe: {
+ invoices: { list: mocks.invoicesList },
+ },
+}));
+
+// Real Drizzle queries against PGlite so the inline membership check β€” the SOLE
+// authorization gate on this route β€” is exercised for real.
+vi.mock("../../db/postgres/postgres.js", async () => {
+ const { PGlite } = await import("@electric-sql/pglite");
+ const { drizzle } = await import("drizzle-orm/pglite");
+ const schema = await import("../../db/postgres/schema.js");
+ const client = new PGlite();
+ const db = drizzle(client, { schema });
+ return { db, sql: client };
+});
+
+import { sql } from "../../db/postgres/postgres.js";
+import { getInvoices } from "./getInvoices.js";
+
+const DDL = `
+CREATE TABLE "organization" ("id" text PRIMARY KEY, "name" text NOT NULL, "slug" text, "createdAt" timestamp DEFAULT now(), "stripeCustomerId" text);
+CREATE TABLE "member" ("id" text PRIMARY KEY, "organizationId" text NOT NULL, "userId" text NOT NULL, "role" text NOT NULL, "createdAt" timestamp DEFAULT now());
+`;
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function requestStub(userId: string | undefined, query: Record<string, unknown>) {
+ return { user: userId ? { id: userId } : undefined, query } as any;
+}
+
+const fakeInvoice = {
+ id: "in_1",
+ number: "ACME-0001",
+ status: "paid",
+ amount_due: 4900,
+ amount_paid: 4900,
+ currency: "usd",
+ created: 1751000000,
+ period_start: 1751000000,
+ period_end: 1753600000,
+ hosted_invoice_url: "https://invoice.stripe.com/i/in_1",
+ invoice_pdf: "https://invoice.stripe.com/i/in_1/pdf",
+ // Extra Stripe fields that must NOT leak through the mapping:
+ customer: "cus_1",
+ default_payment_method: "pm_secret",
+};
+
+beforeAll(async () => {
+ await (sql as any).exec(DDL);
+});
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ await (sql as any).exec(`TRUNCATE "organization", "member"`);
+ await (sql as any).exec(`
+ INSERT INTO "organization" ("id","name","slug","stripeCustomerId") VALUES
+ ('org_1','Acme','acme','cus_1'),
+ ('org_2','Rival','rival','cus_2');
+ INSERT INTO "member" ("id","organizationId","userId","role") VALUES
+ ('m_owner','org_1','u_owner','owner'),
+ ('m_member','org_1','u_member','member'),
+ ('m_outsider','org_2','u_outsider','owner');
+ `);
+ mocks.invoicesList.mockResolvedValue({ data: [fakeInvoice] });
+});
+
+const expectedMappedInvoice = {
+ id: "in_1",
+ number: "ACME-0001",
+ status: "paid",
+ amountDue: 4900,
+ amountPaid: 4900,
+ currency: "usd",
+ created: 1751000000,
+ periodStart: 1751000000,
+ periodEnd: 1753600000,
+ hostedInvoiceUrl: "https://invoice.stripe.com/i/in_1",
+ invoicePdf: "https://invoice.stripe.com/i/in_1/pdf",
+};
+
+describe("getInvoices β€” authorization", () => {
+ it("returns mapped invoices for the org owner", async () => {
+ const reply = replyStub();
+
+ await getInvoices(requestStub("u_owner", { organizationId: "org_1" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.invoicesList).toHaveBeenCalledWith({ customer: "cus_1", limit: 100 });
+ expect(reply.body).toEqual([expectedMappedInvoice]);
+ });
+
+ it("rejects a non-owner member with 403 and never calls Stripe", async () => {
+ // Invoices carry unauthenticated Stripe hosted/PDF URLs, so this read is
+ // owner-only like the other five billing routes.
+ const reply = replyStub();
+
+ await getInvoices(requestStub("u_member", { organizationId: "org_1" }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can manage billing");
+ expect(mocks.invoicesList).not.toHaveBeenCalled();
+ });
+
+ it("rejects a user with no membership in the target org (cross-org attempt)", async () => {
+ const reply = replyStub();
+
+ // u_outsider owns org_2 but must not read org_1's invoices.
+ await getInvoices(requestStub("u_outsider", { organizationId: "org_1" }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can manage billing");
+ expect(mocks.invoicesList).not.toHaveBeenCalled();
+ });
+
+ it("returns 401 when there is no authenticated user", async () => {
+ const reply = replyStub();
+
+ await getInvoices(requestStub(undefined, { organizationId: "org_1" }), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expect(mocks.invoicesList).not.toHaveBeenCalled();
+ });
+
+ it("returns 400 when organizationId is missing", async () => {
+ const reply = replyStub();
+
+ await getInvoices(requestStub("u_owner", {}), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Organization ID is required");
+ expect(mocks.invoicesList).not.toHaveBeenCalled();
+ });
+});
+
+describe("getInvoices β€” Stripe customer handling", () => {
+ it("returns an empty list without calling Stripe when the org has no customer ID", async () => {
+ await (sql as any).exec(`UPDATE "organization" SET "stripeCustomerId" = NULL WHERE "id" = 'org_1'`);
+ const reply = replyStub();
+
+ await getInvoices(requestStub("u_owner", { organizationId: "org_1" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body).toEqual([]);
+ expect(mocks.invoicesList).not.toHaveBeenCalled();
+ });
+
+ it("returns 500 when the Stripe API fails", async () => {
+ mocks.invoicesList.mockRejectedValue(new Error("stripe down"));
+ const reply = replyStub();
+
+ await getInvoices(requestStub("u_owner", { organizationId: "org_1" }), reply);
+
+ expect(reply.statusCode).toBe(500);
+ expect(reply.body.error).toBe("Failed to fetch invoices");
+ });
+});
diff --git a/server/src/api/stripe/getInvoices.ts b/server/src/api/stripe/getInvoices.ts
index f3a73f7af..cf2a34f9f 100644
--- a/server/src/api/stripe/getInvoices.ts
+++ b/server/src/api/stripe/getInvoices.ts
@@ -27,18 +27,18 @@ export async function getInvoices(
return reply.status(500).send({ error: "Stripe is not configured" });
}
- // Verify user is a member of this organization
- const memberResult = await db
- .select({ role: member.role })
- .from(member)
- .where(and(eq(member.userId, userId), eq(member.organizationId, organizationId)))
- .limit(1);
+ try {
+ // Verify user has permission to manage billing for this organization
+ const memberResult = await db
+ .select({ role: member.role })
+ .from(member)
+ .where(and(eq(member.userId, userId), eq(member.organizationId, organizationId)))
+ .limit(1);
- if (!memberResult.length) {
- return reply.status(403).send({ error: "You do not have access to this organization" });
- }
+ if (!memberResult.length || memberResult[0].role !== "owner") {
+ return reply.status(403).send({ error: "Only organization owners can manage billing" });
+ }
- try {
// Get the organization's Stripe customer ID
const orgResult = await db
.select({ stripeCustomerId: organization.stripeCustomerId })
@@ -56,7 +56,7 @@ export async function getInvoices(
limit: 100,
});
- const formatted = invoices.data.map((invoice) => ({
+ const formatted = invoices.data.map(invoice => ({
id: invoice.id,
number: invoice.number,
status: invoice.status,
diff --git a/server/src/api/stripe/getSubscription.test.ts b/server/src/api/stripe/getSubscription.test.ts
new file mode 100644
index 000000000..1dc6f3659
--- /dev/null
+++ b/server/src/api/stripe/getSubscription.test.ts
@@ -0,0 +1,210 @@
+import { DateTime } from "luxon";
+import { describe, expect, it, vi } from "vitest";
+import type {
+ AppSumoSubscriptionInfo,
+ CustomPlanSubscriptionInfo,
+ FreeSubscriptionInfo,
+ OverrideSubscriptionInfo,
+ StripeSubscriptionInfo,
+} from "../../lib/subscriptionUtils.js";
+import { computeLimits } from "./getSubscription.js";
+
+// getSubscription.ts imports the DB pool and subscription utils (which pull in the
+// Stripe client) at module load time. Mock both so importing computeLimits is
+// side-effect free.
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: {},
+}));
+
+vi.mock("../../lib/subscriptionUtils.js", () => ({
+ getBestSubscription: vi.fn(),
+}));
+
+const START_OF_MONTH = "2026-07-01";
+
+function stripeSubscription(planName: string, overrides: Partial<StripeSubscriptionInfo> = {}): StripeSubscriptionInfo {
+ return {
+ source: "stripe",
+ subscriptionId: "sub_123",
+ priceId: "price_123",
+ planName,
+ eventLimit: 100_000,
+ replayLimit: 0,
+ periodStart: START_OF_MONTH,
+ currentPeriodEnd: new Date("2026-08-01T00:00:00Z"),
+ status: "active",
+ interval: "month",
+ cancelAtPeriodEnd: false,
+ createdAt: new Date("2026-01-01T00:00:00Z"),
+ ...overrides,
+ };
+}
+
+function appsumoSubscription(tier: string): AppSumoSubscriptionInfo {
+ return {
+ source: "appsumo",
+ tier,
+ eventLimit: 20_000,
+ replayLimit: 0,
+ periodStart: START_OF_MONTH,
+ planName: `appsumo-${tier}`,
+ status: "active",
+ interval: "lifetime",
+ cancelAtPeriodEnd: false,
+ };
+}
+
+function overrideSubscription(planName: string): OverrideSubscriptionInfo {
+ return {
+ source: "override",
+ planName,
+ eventLimit: 100_000,
+ replayLimit: 0,
+ periodStart: START_OF_MONTH,
+ status: "active",
+ interval: "month",
+ cancelAtPeriodEnd: false,
+ };
+}
+
+function customSubscription(memberLimit: number | null, siteLimit: number | null): CustomPlanSubscriptionInfo {
+ return {
+ source: "custom",
+ planName: "custom",
+ eventLimit: 1_000_000,
+ memberLimit,
+ siteLimit,
+ periodStart: START_OF_MONTH,
+ status: "active",
+ interval: "lifetime",
+ cancelAtPeriodEnd: false,
+ };
+}
+
+function freeSubscription(): FreeSubscriptionInfo {
+ return {
+ source: "free",
+ eventLimit: 3_000,
+ periodStart: START_OF_MONTH,
+ planName: "free",
+ status: "free",
+ };
+}
+
+// The legacy cutoff is parsed with DateTime.fromFormat("2025-06-27", "yyyy-MM-dd"),
+// i.e. local midnight β€” compute the same instant here so the boundary tests are
+// timezone independent.
+const legacyCutoff = DateTime.fromFormat("2025-06-27", "yyyy-MM-dd");
+
+describe("computeLimits", () => {
+ describe("custom plans", () => {
+ it("returns the plan's own limits verbatim", () => {
+ expect(computeLimits(customSubscription(7, 12))).toEqual({ memberLimit: 7, siteLimit: 12 });
+ });
+
+ it("passes through null (unlimited) limits", () => {
+ expect(computeLimits(customSubscription(null, null))).toEqual({ memberLimit: null, siteLimit: null });
+ expect(computeLimits(customSubscription(5, null))).toEqual({ memberLimit: 5, siteLimit: null });
+ });
+ });
+
+ describe("pro plans", () => {
+ it("gives unlimited members and sites", () => {
+ expect(computeLimits(stripeSubscription("pro100k"))).toEqual({ memberLimit: null, siteLimit: null });
+ expect(computeLimits(stripeSubscription("pro1m-annual"))).toEqual({ memberLimit: null, siteLimit: null });
+ });
+
+ it("also applies to override plans containing 'pro'", () => {
+ expect(computeLimits(overrideSubscription("pro250k"))).toEqual({ memberLimit: null, siteLimit: null });
+ });
+ });
+
+ describe("standard plans", () => {
+ it("applies the standard tier limits when no Stripe creation date is known", () => {
+ expect(computeLimits(stripeSubscription("standard100k"))).toEqual({ memberLimit: 3, siteLimit: 5 });
+ });
+
+ it("gives unlimited sites to legacy subscriptions created before 2025-06-27", () => {
+ const justBeforeCutoff = new Date(legacyCutoff.toMillis() - 1);
+ expect(computeLimits(stripeSubscription("standard100k"), justBeforeCutoff)).toEqual({
+ memberLimit: 3,
+ siteLimit: null,
+ });
+ });
+
+ it("applies the site limit to subscriptions created exactly at the 2025-06-27 boundary", () => {
+ expect(computeLimits(stripeSubscription("standard100k"), legacyCutoff.toJSDate())).toEqual({
+ memberLimit: 3,
+ siteLimit: 5,
+ });
+ });
+
+ it("applies the site limit to subscriptions created after the boundary", () => {
+ const afterCutoff = legacyCutoff.plus({ days: 1 }).toJSDate();
+ expect(computeLimits(stripeSubscription("standard100k"), afterCutoff)).toEqual({
+ memberLimit: 3,
+ siteLimit: 5,
+ });
+ });
+ });
+
+ describe("basic plans", () => {
+ it("applies the basic tier limits", () => {
+ expect(computeLimits(stripeSubscription("basic100k"))).toEqual({ memberLimit: 1, siteLimit: 1 });
+ });
+ });
+
+ describe("appsumo tiers", () => {
+ it("maps tiers 1-5 to their configured limits", () => {
+ expect(computeLimits(appsumoSubscription("1"))).toEqual({ memberLimit: 1, siteLimit: 3 });
+ expect(computeLimits(appsumoSubscription("2"))).toEqual({ memberLimit: 3, siteLimit: 10 });
+ expect(computeLimits(appsumoSubscription("3"))).toEqual({ memberLimit: 10, siteLimit: 25 });
+ expect(computeLimits(appsumoSubscription("4"))).toEqual({ memberLimit: 25, siteLimit: 50 });
+ expect(computeLimits(appsumoSubscription("5"))).toEqual({ memberLimit: 50, siteLimit: 100 });
+ });
+
+ it("gives tiers 6 and 7 unlimited members and sites", () => {
+ expect(computeLimits(appsumoSubscription("6"))).toEqual({ memberLimit: null, siteLimit: null });
+ expect(computeLimits(appsumoSubscription("7"))).toEqual({ memberLimit: null, siteLimit: null });
+ });
+
+ it("does not match tiers outside 1-7, falling through to the free limits", () => {
+ // Pinned current behavior: "appsumo-0" / "appsumo-8" fail the ^appsumo-([1-7])$
+ // regex, and since the source is "appsumo" (not "override") they fall all the
+ // way through to the free-tier limits.
+ expect(computeLimits(appsumoSubscription("0"))).toEqual({ memberLimit: 1, siteLimit: 1 });
+ expect(computeLimits(appsumoSubscription("8"))).toEqual({ memberLimit: 1, siteLimit: 1 });
+ });
+
+ it("matches appsumo tiers on override plans too", () => {
+ expect(computeLimits(overrideSubscription("appsumo-3"))).toEqual({ memberLimit: 10, siteLimit: 25 });
+ });
+ });
+
+ describe("override plans", () => {
+ it("defaults unknown override plan names to unlimited", () => {
+ expect(computeLimits(overrideSubscription("enterprise-special"))).toEqual({
+ memberLimit: null,
+ siteLimit: null,
+ });
+ });
+ });
+
+ describe("free tier and unknown plans", () => {
+ it("applies the free tier limits", () => {
+ expect(computeLimits(freeSubscription())).toEqual({ memberLimit: 1, siteLimit: 1 });
+ });
+
+ it("treats unrecognized stripe plan names as free tier", () => {
+ // Pinned current behavior: a Stripe plan whose name matches no known tier
+ // (e.g. "Unknown Plan" from an unmapped price ID) gets the free-tier limits.
+ expect(computeLimits(stripeSubscription("Unknown Plan"))).toEqual({ memberLimit: 1, siteLimit: 1 });
+ });
+
+ it("matches plan names case-sensitively", () => {
+ // Pinned current behavior: planName.includes("pro") is case sensitive, so a
+ // capitalized name falls through to the free-tier limits.
+ expect(computeLimits(stripeSubscription("Pro100k"))).toEqual({ memberLimit: 1, siteLimit: 1 });
+ });
+ });
+});
diff --git a/server/src/api/stripe/getSubscription.ts b/server/src/api/stripe/getSubscription.ts
index 411bfee58..fe2642de2 100644
--- a/server/src/api/stripe/getSubscription.ts
+++ b/server/src/api/stripe/getSubscription.ts
@@ -28,7 +28,7 @@ function getStartOfNextMonth() {
* Computes memberLimit and siteLimit from a subscription.
* null = unlimited.
*/
-function computeLimits(
+export function computeLimits(
subscription: SubscriptionInfo,
stripeCreatedAt?: Date
): { memberLimit: number | null; siteLimit: number | null } {
diff --git a/server/src/api/stripe/previewSubscriptionUpdate.test.ts b/server/src/api/stripe/previewSubscriptionUpdate.test.ts
new file mode 100644
index 000000000..e51afc388
--- /dev/null
+++ b/server/src/api/stripe/previewSubscriptionUpdate.test.ts
@@ -0,0 +1,214 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ subscriptionsList: vi.fn(),
+ pricesRetrieve: vi.fn(),
+ invoicesCreatePreview: vi.fn(),
+}));
+
+vi.mock("../../lib/stripe.js", () => ({
+ stripe: {
+ subscriptions: { list: mocks.subscriptionsList },
+ prices: { retrieve: mocks.pricesRetrieve },
+ invoices: { createPreview: mocks.invoicesCreatePreview },
+ },
+}));
+
+// Real Drizzle queries against PGlite so the inline membership check β€” the SOLE
+// authorization gate on this route β€” is exercised for real.
+vi.mock("../../db/postgres/postgres.js", async () => {
+ const { PGlite } = await import("@electric-sql/pglite");
+ const { drizzle } = await import("drizzle-orm/pglite");
+ const schema = await import("../../db/postgres/schema.js");
+ const client = new PGlite();
+ const db = drizzle(client, { schema });
+ return { db, sql: client };
+});
+
+import { sql } from "../../db/postgres/postgres.js";
+import { previewSubscriptionUpdate } from "./previewSubscriptionUpdate.js";
+
+const DDL = `
+CREATE TABLE "organization" ("id" text PRIMARY KEY, "name" text NOT NULL, "slug" text, "createdAt" timestamp DEFAULT now(), "stripeCustomerId" text);
+CREATE TABLE "member" ("id" text PRIMARY KEY, "organizationId" text NOT NULL, "userId" text NOT NULL, "role" text NOT NULL, "createdAt" timestamp DEFAULT now());
+`;
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function requestStub(userId: string | undefined, body: Record<string, unknown>) {
+ return { user: userId ? { id: userId } : undefined, body } as any;
+}
+
+const PERIOD_END = 1760000000;
+
+function fakeSubscription(status: "active" | "trialing") {
+ return {
+ id: "sub_1",
+ status,
+ items: { data: [{ id: "si_1", price: { id: "price_old" }, current_period_end: PERIOD_END }] },
+ };
+}
+
+const validBody = { organizationId: "org_1", newPriceId: "price_new" };
+
+beforeAll(async () => {
+ await (sql as any).exec(DDL);
+});
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ await (sql as any).exec(`TRUNCATE "organization", "member"`);
+ await (sql as any).exec(`
+ INSERT INTO "organization" ("id","name","slug","stripeCustomerId") VALUES
+ ('org_1','Acme','acme','cus_1'),
+ ('org_2','Rival','rival','cus_2');
+ INSERT INTO "member" ("id","organizationId","userId","role") VALUES
+ ('m_owner','org_1','u_owner','owner'),
+ ('m_member','org_1','u_member','member'),
+ ('m_outsider','org_2','u_outsider','owner');
+ `);
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "active" ? { data: [fakeSubscription("active")] } : { data: [] }
+ );
+ mocks.pricesRetrieve.mockImplementation(async (priceId: string) => ({
+ id: priceId,
+ unit_amount: priceId === "price_new" ? 4900 : 1900,
+ recurring: { interval: "month" },
+ }));
+ mocks.invoicesCreatePreview.mockResolvedValue({
+ amount_due: 2500,
+ lines: {
+ data: [
+ { amount: -1000, parent: { subscription_item_details: { proration: true } } },
+ { amount: 3500, parent: { subscription_item_details: { proration: true } } },
+ { amount: 4900, parent: { subscription_item_details: { proration: false } } },
+ ],
+ },
+ });
+});
+
+describe("previewSubscriptionUpdate β€” authorization", () => {
+ it("returns a proration preview for the org owner", async () => {
+ const reply = replyStub();
+
+ await previewSubscriptionUpdate(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.invoicesCreatePreview).toHaveBeenCalledWith({
+ customer: "cus_1",
+ subscription: "sub_1",
+ subscription_details: {
+ items: [{ id: "si_1", price: "price_new" }],
+ proration_behavior: "always_invoice",
+ },
+ });
+ expect(reply.body).toEqual({
+ success: true,
+ preview: {
+ isTrialing: false,
+ currentPlan: { priceId: "price_old", amount: 1900, interval: "month" },
+ newPlan: { priceId: "price_new", amount: 4900, interval: "month" },
+ proration: {
+ // Only lines flagged proration:true count; amounts convert cents to dollars.
+ credit: 10,
+ charge: 35,
+ immediatePayment: 25,
+ nextBillingDate: new Date(PERIOD_END * 1000).toISOString(),
+ },
+ },
+ });
+ });
+
+ it("rejects a non-owner member with 403 and calls no Stripe API", async () => {
+ const reply = replyStub();
+
+ await previewSubscriptionUpdate(requestStub("u_member", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can manage billing");
+ expect(mocks.subscriptionsList).not.toHaveBeenCalled();
+ expect(mocks.invoicesCreatePreview).not.toHaveBeenCalled();
+ });
+
+ it("rejects a user with no membership in the target org (cross-org attempt)", async () => {
+ const reply = replyStub();
+
+ // u_outsider owns org_2 but must not preview org_1's billing.
+ await previewSubscriptionUpdate(requestStub("u_outsider", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(mocks.invoicesCreatePreview).not.toHaveBeenCalled();
+ });
+
+ it("returns 401 when there is no authenticated user", async () => {
+ const reply = replyStub();
+
+ await previewSubscriptionUpdate(requestStub(undefined, validBody), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expect(mocks.invoicesCreatePreview).not.toHaveBeenCalled();
+ });
+
+ it("returns 400 when organizationId or newPriceId is missing", async () => {
+ for (const body of [{ newPriceId: "price_new" }, { organizationId: "org_1" }, {}]) {
+ const reply = replyStub();
+ await previewSubscriptionUpdate(requestStub("u_owner", body), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Missing required parameters");
+ }
+ expect(mocks.invoicesCreatePreview).not.toHaveBeenCalled();
+ });
+});
+
+describe("previewSubscriptionUpdate β€” branches", () => {
+ it("returns a zero-proration preview for trialing subscriptions without hitting the invoice API", async () => {
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "trialing" ? { data: [fakeSubscription("trialing")] } : { data: [] }
+ );
+ const reply = replyStub();
+
+ await previewSubscriptionUpdate(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.invoicesCreatePreview).not.toHaveBeenCalled();
+ expect(reply.body.preview.isTrialing).toBe(true);
+ expect(reply.body.preview.proration).toEqual({
+ credit: 0,
+ charge: 0,
+ immediatePayment: 0,
+ nextBillingDate: new Date(PERIOD_END * 1000).toISOString(),
+ });
+ });
+
+ it("returns 404 when the org has no Stripe customer ID", async () => {
+ await (sql as any).exec(`UPDATE "organization" SET "stripeCustomerId" = NULL WHERE "id" = 'org_1'`);
+ const reply = replyStub();
+
+ await previewSubscriptionUpdate(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(mocks.subscriptionsList).not.toHaveBeenCalled();
+ });
+
+ it("returns 404 when no active or trialing subscription exists", async () => {
+ mocks.subscriptionsList.mockResolvedValue({ data: [] });
+ const reply = replyStub();
+
+ await previewSubscriptionUpdate(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("No active subscription found");
+ expect(mocks.invoicesCreatePreview).not.toHaveBeenCalled();
+ });
+});
diff --git a/server/src/api/stripe/submitCancellationFeedback.test.ts b/server/src/api/stripe/submitCancellationFeedback.test.ts
new file mode 100644
index 000000000..4df084342
--- /dev/null
+++ b/server/src/api/stripe/submitCancellationFeedback.test.ts
@@ -0,0 +1,162 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Real Drizzle queries against PGlite so the inline membership check β€” the SOLE
+// authorization gate on this route β€” and the feedback insert are exercised for real.
+vi.mock("../../db/postgres/postgres.js", async () => {
+ const { PGlite } = await import("@electric-sql/pglite");
+ const { drizzle } = await import("drizzle-orm/pglite");
+ const schema = await import("../../db/postgres/schema.js");
+ const client = new PGlite();
+ const db = drizzle(client, { schema });
+ return { db, sql: client };
+});
+
+import { sql } from "../../db/postgres/postgres.js";
+import { submitCancellationFeedback } from "./submitCancellationFeedback.js";
+
+const DDL = `
+CREATE TABLE "member" ("id" text PRIMARY KEY, "organizationId" text NOT NULL, "userId" text NOT NULL, "role" text NOT NULL, "createdAt" timestamp DEFAULT now());
+CREATE TABLE "cancellation_feedback" (
+ "id" serial PRIMARY KEY,
+ "organization_id" text NOT NULL,
+ "user_id" text NOT NULL,
+ "reason" text NOT NULL,
+ "reason_details" text,
+ "retention_offer_shown" text,
+ "retention_offer_accepted" boolean DEFAULT false,
+ "outcome" text NOT NULL,
+ "plan_name_at_cancellation" text,
+ "monthly_event_count_at_cancellation" integer,
+ "created_at" timestamp DEFAULT now() NOT NULL
+);
+`;
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function requestStub(userId: string | undefined, body: Record<string, unknown>) {
+ return { user: userId ? { id: userId } : undefined, body } as any;
+}
+
+async function feedbackRows(): Promise<any[]> {
+ const result = await (sql as any).query(`SELECT * FROM "cancellation_feedback"`);
+ return result.rows;
+}
+
+const validBody = { organizationId: "org_1", reason: "too_expensive", outcome: "cancelled" };
+
+beforeAll(async () => {
+ await (sql as any).exec(DDL);
+});
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ await (sql as any).exec(`TRUNCATE "member", "cancellation_feedback"`);
+ await (sql as any).exec(`
+ INSERT INTO "member" ("id","organizationId","userId","role") VALUES
+ ('m_owner','org_1','u_owner','owner'),
+ ('m_member','org_1','u_member','member'),
+ ('m_outsider','org_2','u_outsider','owner');
+ `);
+});
+
+describe("submitCancellationFeedback β€” authorization", () => {
+ it("persists feedback for the org owner with the full payload", async () => {
+ const reply = replyStub();
+
+ await submitCancellationFeedback(
+ requestStub("u_owner", {
+ ...validBody,
+ reasonDetails: "Migrating to self-hosted",
+ retentionOfferShown: "discount_50",
+ retentionOfferAccepted: true,
+ planNameAtCancellation: "pro100k",
+ monthlyEventCountAtCancellation: 42000,
+ }),
+ reply
+ );
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body).toEqual({ success: true });
+ const rows = await feedbackRows();
+ expect(rows).toHaveLength(1);
+ expect(rows[0]).toMatchObject({
+ organization_id: "org_1",
+ user_id: "u_owner",
+ reason: "too_expensive",
+ reason_details: "Migrating to self-hosted",
+ retention_offer_shown: "discount_50",
+ retention_offer_accepted: true,
+ outcome: "cancelled",
+ plan_name_at_cancellation: "pro100k",
+ monthly_event_count_at_cancellation: 42000,
+ });
+ });
+
+ it("defaults optional fields to null/false when omitted", async () => {
+ const reply = replyStub();
+
+ await submitCancellationFeedback(requestStub("u_owner", validBody), reply);
+
+ expect(reply.statusCode).toBe(200);
+ const rows = await feedbackRows();
+ expect(rows[0]).toMatchObject({
+ reason_details: null,
+ retention_offer_shown: null,
+ retention_offer_accepted: false,
+ plan_name_at_cancellation: null,
+ monthly_event_count_at_cancellation: null,
+ });
+ });
+
+ it("rejects a non-owner member with 403 and writes nothing", async () => {
+ const reply = replyStub();
+
+ await submitCancellationFeedback(requestStub("u_member", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can submit cancellation feedback");
+ expect(await feedbackRows()).toHaveLength(0);
+ });
+
+ it("rejects a user with no membership in the target org (cross-org attempt)", async () => {
+ const reply = replyStub();
+
+ // u_outsider owns org_2 but must not write feedback rows attributed to org_1.
+ await submitCancellationFeedback(requestStub("u_outsider", validBody), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(await feedbackRows()).toHaveLength(0);
+ });
+
+ it("returns 401 when there is no authenticated user", async () => {
+ const reply = replyStub();
+
+ await submitCancellationFeedback(requestStub(undefined, validBody), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expect(await feedbackRows()).toHaveLength(0);
+ });
+
+ it("returns 400 when organizationId, reason or outcome is missing", async () => {
+ for (const omit of ["organizationId", "reason", "outcome"] as const) {
+ const body: Record<string, unknown> = { ...validBody };
+ delete body[omit];
+ const reply = replyStub();
+ await submitCancellationFeedback(requestStub("u_owner", body), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Missing required parameters");
+ }
+ expect(await feedbackRows()).toHaveLength(0);
+ });
+});
diff --git a/server/src/api/stripe/updateSubscription.test.ts b/server/src/api/stripe/updateSubscription.test.ts
new file mode 100644
index 000000000..c4c8c6e5c
--- /dev/null
+++ b/server/src/api/stripe/updateSubscription.test.ts
@@ -0,0 +1,240 @@
+import Stripe from "stripe";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+ subscriptionsList: vi.fn(),
+ subscriptionsUpdate: vi.fn(),
+ subscriptionsRetrieve: vi.fn(),
+ pricesRetrieve: vi.fn(),
+ invalidateStripeSubscriptionCache: vi.fn(),
+}));
+
+vi.mock("../../lib/stripe.js", () => ({
+ stripe: {
+ subscriptions: {
+ list: mocks.subscriptionsList,
+ update: mocks.subscriptionsUpdate,
+ retrieve: mocks.subscriptionsRetrieve,
+ },
+ prices: { retrieve: mocks.pricesRetrieve },
+ },
+}));
+
+vi.mock("../../lib/subscriptionUtils.js", () => ({
+ invalidateStripeSubscriptionCache: mocks.invalidateStripeSubscriptionCache,
+}));
+
+// Real Drizzle queries against PGlite so the inline membership check β€” the SOLE
+// authorization gate on this route β€” is exercised for real.
+vi.mock("../../db/postgres/postgres.js", async () => {
+ const { PGlite } = await import("@electric-sql/pglite");
+ const { drizzle } = await import("drizzle-orm/pglite");
+ const schema = await import("../../db/postgres/schema.js");
+ const client = new PGlite();
+ const db = drizzle(client, { schema });
+ return { db, sql: client };
+});
+
+import { sql } from "../../db/postgres/postgres.js";
+import { updateSubscription } from "./updateSubscription.js";
+
+const DDL = `
+CREATE TABLE "organization" ("id" text PRIMARY KEY, "name" text NOT NULL, "slug" text, "createdAt" timestamp DEFAULT now(), "stripeCustomerId" text);
+CREATE TABLE "member" ("id" text PRIMARY KEY, "organizationId" text NOT NULL, "userId" text NOT NULL, "role" text NOT NULL, "createdAt" timestamp DEFAULT now());
+`;
+
+function replyStub() {
+ const reply: any = { statusCode: 200 };
+ reply.status = (code: number) => {
+ reply.statusCode = code;
+ return reply;
+ };
+ reply.send = (body: unknown) => {
+ reply.body = body;
+ return reply;
+ };
+ return reply;
+}
+
+function requestStub(userId: string | undefined, body: Record<string, unknown>) {
+ return { user: userId ? { id: userId } : undefined, body } as any;
+}
+
+function fakeSubscription(status: "active" | "trialing", overrides: Record<string, unknown> = {}) {
+ return {
+ id: "sub_1",
+ status,
+ trial_end: null,
+ items: { data: [{ id: "si_1", price: { id: "price_old" }, current_period_end: 1760000000 }] },
+ ...overrides,
+ };
+}
+
+function expectNoStripeMutation() {
+ expect(mocks.subscriptionsUpdate).not.toHaveBeenCalled();
+ expect(mocks.invalidateStripeSubscriptionCache).not.toHaveBeenCalled();
+}
+
+beforeAll(async () => {
+ await (sql as any).exec(DDL);
+});
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ await (sql as any).exec(`TRUNCATE "organization", "member"`);
+ await (sql as any).exec(`
+ INSERT INTO "organization" ("id","name","slug","stripeCustomerId") VALUES
+ ('org_1','Acme','acme','cus_1'),
+ ('org_2','Rival','rival','cus_2');
+ INSERT INTO "member" ("id","organizationId","userId","role") VALUES
+ ('m_owner','org_1','u_owner','owner'),
+ ('m_member','org_1','u_member','member'),
+ ('m_outsider','org_2','u_outsider','owner');
+ `);
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "active" ? { data: [fakeSubscription("active")] } : { data: [] }
+ );
+ mocks.subscriptionsUpdate.mockResolvedValue({ id: "sub_1" });
+ mocks.subscriptionsRetrieve.mockResolvedValue({
+ id: "sub_1",
+ status: "active",
+ items: { data: [{ current_period_end: 1760000000 }] },
+ });
+ mocks.pricesRetrieve.mockResolvedValue({ id: "price_new" });
+});
+
+describe("updateSubscription β€” authorization", () => {
+ it("lets the org owner change the plan and invoices the proration", async () => {
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_owner", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.body).toEqual({
+ success: true,
+ subscription: {
+ id: "sub_1",
+ status: "active",
+ currentPeriodEnd: new Date(1760000000 * 1000).toISOString(),
+ },
+ });
+ expect(mocks.subscriptionsList).toHaveBeenCalledWith({ customer: "cus_1", status: "active", limit: 1 });
+ expect(mocks.subscriptionsUpdate).toHaveBeenCalledWith("sub_1", {
+ items: [{ id: "si_1", price: "price_new" }],
+ proration_behavior: "always_invoice",
+ });
+ expect(mocks.invalidateStripeSubscriptionCache).toHaveBeenCalledWith("cus_1");
+ });
+
+ it("rejects a non-owner member with 403 and touches nothing in Stripe", async () => {
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_member", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(reply.body.error).toBe("Only organization owners can manage billing");
+ expect(mocks.subscriptionsList).not.toHaveBeenCalled();
+ expectNoStripeMutation();
+ });
+
+ it("rejects a user with no membership in the target org (cross-org attempt)", async () => {
+ const reply = replyStub();
+
+ // u_outsider owns org_2 but has no row in org_1 β€” owning some org must not help.
+ await updateSubscription(requestStub("u_outsider", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(403);
+ expect(mocks.subscriptionsList).not.toHaveBeenCalled();
+ expectNoStripeMutation();
+ });
+
+ it("returns 401 when there is no authenticated user", async () => {
+ const reply = replyStub();
+
+ await updateSubscription(requestStub(undefined, { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(401);
+ expectNoStripeMutation();
+ });
+
+ it("returns 400 when organizationId or newPriceId is missing", async () => {
+ for (const body of [{ newPriceId: "price_new" }, { organizationId: "org_1" }, {}]) {
+ const reply = replyStub();
+ await updateSubscription(requestStub("u_owner", body), reply);
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toContain("Missing required parameters");
+ }
+ expectNoStripeMutation();
+ });
+});
+
+describe("updateSubscription β€” plan-change branches", () => {
+ it("preserves the trial when swapping plans on a trialing subscription", async () => {
+ mocks.subscriptionsList.mockImplementation(async ({ status }: any) =>
+ status === "trialing" ? { data: [fakeSubscription("trialing", { trial_end: 1765000000 })] } : { data: [] }
+ );
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_owner", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(200);
+ expect(mocks.subscriptionsUpdate).toHaveBeenCalledWith("sub_1", {
+ items: [{ id: "si_1", price: "price_new" }],
+ proration_behavior: "none",
+ trial_end: 1765000000,
+ });
+ });
+
+ it("returns 400 when Stripe reports the price does not exist, without updating the subscription", async () => {
+ mocks.pricesRetrieve.mockRejectedValue(
+ new Stripe.errors.StripeInvalidRequestError({
+ type: "invalid_request_error",
+ code: "resource_missing",
+ param: "price",
+ message: "No such price: 'price_bogus'",
+ } as any)
+ );
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_owner", { organizationId: "org_1", newPriceId: "price_bogus" }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.body.error).toBe("Invalid price ID");
+ expectNoStripeMutation();
+ });
+
+ it("returns 500 for a transient Stripe failure during price validation, without updating the subscription", async () => {
+ // An outage/rate-limit style failure must not be misreported as a bad price ID.
+ mocks.pricesRetrieve.mockRejectedValue(
+ new Stripe.errors.StripeAPIError({ type: "api_error", message: "Stripe is temporarily unavailable" } as any)
+ );
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_owner", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(500);
+ expect(reply.body.error).toBe("Failed to update subscription");
+ expectNoStripeMutation();
+ });
+
+ it("returns 404 when the org has no Stripe customer ID", async () => {
+ await (sql as any).exec(`UPDATE "organization" SET "stripeCustomerId" = NULL WHERE "id" = 'org_1'`);
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_owner", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expectNoStripeMutation();
+ });
+
+ it("returns 404 when no active or trialing subscription exists", async () => {
+ mocks.subscriptionsList.mockResolvedValue({ data: [] });
+ const reply = replyStub();
+
+ await updateSubscription(requestStub("u_owner", { organizationId: "org_1", newPriceId: "price_new" }), reply);
+
+ expect(reply.statusCode).toBe(404);
+ expect(reply.body.error).toBe("No active subscription found");
+ expectNoStripeMutation();
+ });
+});
diff --git a/server/src/api/stripe/updateSubscription.ts b/server/src/api/stripe/updateSubscription.ts
index 292cdcae4..f00de8b91 100644
--- a/server/src/api/stripe/updateSubscription.ts
+++ b/server/src/api/stripe/updateSubscription.ts
@@ -72,11 +72,16 @@ export async function updateSubscription(
}
const subscriptionItem = subscription.items.data[0];
- // 4. Validate the new price exists
+ // 4. Validate the new price exists. Only Stripe's missing-resource error means the
+ // price ID is invalid; anything else (outage, rate limit, network) falls through to
+ // the 500 path below without mutating the subscription.
try {
await (stripe as Stripe).prices.retrieve(newPriceId);
} catch (error) {
- return reply.status(400).send({ error: "Invalid price ID" });
+ if (error instanceof Stripe.errors.StripeInvalidRequestError && error.code === "resource_missing") {
+ return reply.status(400).send({ error: "Invalid price ID" });
+ }
+ throw error;
}
// 5. Update the subscription with the new price
diff --git a/server/src/api/stripe/webhook.test.ts b/server/src/api/stripe/webhook.test.ts
new file mode 100644
index 000000000..12e6d3eae
--- /dev/null
+++ b/server/src/api/stripe/webhook.test.ts
@@ -0,0 +1,341 @@
+import type { SQL } from "drizzle-orm";
+import { PgDialect } from "drizzle-orm/pg-core";
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => {
+ // The handler captures STRIPE_WEBHOOK_SECRET at module load time, so it has
+ // to exist before ./webhook.js is imported (vi.hoisted runs before imports).
+ // Capture whatever was there so afterAll can restore it.
+ const previousWebhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
+ process.env.STRIPE_WEBHOOK_SECRET = "whsec_test_secret";
+
+ const selectLimit = vi.fn(async (): Promise<{ id: string }[]> => []);
+ const selectWhere = vi.fn((_where: unknown) => ({ limit: selectLimit }));
+ const selectFrom = vi.fn(() => ({ where: selectWhere }));
+ const select = vi.fn(() => ({ from: selectFrom }));
+
+ const updateWhere = vi.fn(async (_where: unknown) => undefined);
+ const updateSet = vi.fn(() => ({ where: updateWhere }));
+ const update = vi.fn(() => ({ set: updateSet }));
+
+ return {
+ previousWebhookSecret,
+ constructEvent: vi.fn(),
+ invalidateStripeSubscriptionCache: vi.fn(),
+ select,
+ selectWhere,
+ selectLimit,
+ update,
+ updateSet,
+ updateWhere,
+ };
+});
+
+vi.mock("../../lib/stripe.js", () => ({
+ stripe: { webhooks: { constructEvent: mocks.constructEvent } },
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: { select: mocks.select, update: mocks.update },
+}));
+
+vi.mock("../../lib/subscriptionUtils.js", () => ({
+ invalidateStripeSubscriptionCache: mocks.invalidateStripeSubscriptionCache,
+}));
+
+import { handleWebhook } from "./webhook.js";
+
+const dialect = new PgDialect();
+
+const SIGNATURE = "t=1700000000,v1=deadbeef";
+
+type RequestOverrides = {
+ rawBody?: string | Buffer | null;
+ headers?: Record<string, string | undefined>;
+ parsedBody?: unknown;
+};
+
+function createRequest(overrides: RequestOverrides = {}) {
+ const rawBody = "rawBody" in overrides ? overrides.rawBody : '{"id":"evt_raw"}';
+ return {
+ headers: overrides.headers ?? { "stripe-signature": SIGNATURE },
+ body: overrides.parsedBody,
+ raw: rawBody === null ? {} : { body: rawBody },
+ } as any;
+}
+
+function createReply() {
+ const reply: any = { statusCode: 200 };
+ reply.status = vi.fn((code: number) => {
+ reply.statusCode = code;
+ return reply;
+ });
+ reply.send = vi.fn((payload: unknown) => {
+ reply.payload = payload;
+ return reply;
+ });
+ return reply;
+}
+
+function stripeEvent(type: string, object: Record<string, unknown>) {
+ return { type, data: { object } } as any;
+}
+
+function expectNoDbWrites() {
+ expect(mocks.select).not.toHaveBeenCalled();
+ expect(mocks.update).not.toHaveBeenCalled();
+ expect(mocks.updateSet).not.toHaveBeenCalled();
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ mocks.selectLimit.mockResolvedValue([]);
+ mocks.updateWhere.mockResolvedValue(undefined);
+});
+
+afterAll(() => {
+ // Restore whatever STRIPE_WEBHOOK_SECRET held before this suite mutated it.
+ if (mocks.previousWebhookSecret === undefined) {
+ delete process.env.STRIPE_WEBHOOK_SECRET;
+ } else {
+ process.env.STRIPE_WEBHOOK_SECRET = mocks.previousWebhookSecret;
+ }
+});
+
+describe("handleWebhook β€” signature verification", () => {
+ it("rejects a request with a missing stripe-signature header and writes nothing", async () => {
+ // The handler forwards the (undefined) header to constructEvent, which the
+ // real Stripe SDK rejects β€” simulate that.
+ mocks.constructEvent.mockImplementation((_body: unknown, sig: unknown) => {
+ if (!sig) throw new Error("No stripe-signature header value was provided.");
+ return stripeEvent("noop", {});
+ });
+
+ const reply = createReply();
+ await handleWebhook(createRequest({ headers: {} }), reply);
+
+ expect(mocks.constructEvent).toHaveBeenCalledWith('{"id":"evt_raw"}', undefined, "whsec_test_secret");
+ expect(reply.statusCode).toBe(400);
+ expect(reply.payload).toContain("Webhook Error");
+ expectNoDbWrites();
+ expect(mocks.invalidateStripeSubscriptionCache).not.toHaveBeenCalled();
+ });
+
+ it("returns 400 on an invalid signature and performs NO db write for a forged event", async () => {
+ mocks.constructEvent.mockImplementation(() => {
+ throw new Error("Signature verification failed");
+ });
+
+ const reply = createReply();
+ await handleWebhook(
+ createRequest({
+ rawBody: JSON.stringify({
+ type: "checkout.session.completed",
+ data: {
+ object: {
+ mode: "subscription",
+ customer: "cus_forged",
+ metadata: { organizationId: "victim_org" },
+ },
+ },
+ }),
+ }),
+ reply
+ );
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.payload).toContain("Webhook Error: Signature verification failed");
+ // CRITICAL: a forged event must never touch the database or the cache.
+ expectNoDbWrites();
+ expect(mocks.invalidateStripeSubscriptionCache).not.toHaveBeenCalled();
+ });
+
+ it("passes the RAW body (not the parsed JSON body) to constructEvent", async () => {
+ // Security invariant: signature verification must run over the exact bytes
+ // Stripe signed. Using the parsed/re-serialized body would break (or worse,
+ // bypass) verification.
+ const rawBody = '{"id": "evt_1", "type": "some.event"}';
+ mocks.constructEvent.mockReturnValue(stripeEvent("some.event", {}));
+
+ const reply = createReply();
+ await handleWebhook(createRequest({ rawBody, parsedBody: { id: "evt_1", type: "tampered.event" } }), reply);
+
+ expect(mocks.constructEvent).toHaveBeenCalledTimes(1);
+ expect(mocks.constructEvent).toHaveBeenCalledWith(rawBody, SIGNATURE, "whsec_test_secret");
+ const [firstArg] = mocks.constructEvent.mock.calls[0];
+ expect(typeof firstArg).toBe("string");
+ expect(firstArg).not.toEqual({ id: "evt_1", type: "tampered.event" });
+ });
+
+ it("returns 400 without calling constructEvent when no raw body is available", async () => {
+ const reply = createReply();
+ await handleWebhook(createRequest({ rawBody: null }), reply);
+
+ expect(reply.statusCode).toBe(400);
+ expect(reply.payload).toBe("Webhook error: No raw body available");
+ expect(mocks.constructEvent).not.toHaveBeenCalled();
+ expectNoDbWrites();
+ });
+});
+
+describe("handleWebhook β€” checkout.session.completed", () => {
+ it("writes the stripe customer id onto the org from session.metadata.organizationId", async () => {
+ mocks.constructEvent.mockReturnValue(
+ stripeEvent("checkout.session.completed", {
+ id: "cs_1",
+ mode: "subscription",
+ customer: "cus_123",
+ metadata: { organizationId: "org_1" },
+ })
+ );
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expect(mocks.invalidateStripeSubscriptionCache).toHaveBeenCalledWith("cus_123");
+
+ // Looked up by stripeCustomerId first (idempotency check).
+ const lookupWhere = dialect.sqlToQuery(mocks.selectWhere.mock.calls[0][0] as SQL);
+ expect(lookupWhere.params).toEqual(["cus_123"]);
+
+ // Then wrote the customer id onto the org named in the session metadata.
+ expect(mocks.updateSet).toHaveBeenCalledWith({ stripeCustomerId: "cus_123" });
+ const updateWhere = dialect.sqlToQuery(mocks.updateWhere.mock.calls[0][0] as SQL);
+ expect(updateWhere.params).toEqual(["org_1"]);
+
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({ received: true });
+ });
+
+ it("does not overwrite when an org already has this stripe customer id", async () => {
+ mocks.selectLimit.mockResolvedValue([{ id: "org_existing" }]);
+ mocks.constructEvent.mockReturnValue(
+ stripeEvent("checkout.session.completed", {
+ id: "cs_2",
+ mode: "subscription",
+ customer: "cus_123",
+ metadata: { organizationId: "org_1" },
+ })
+ );
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expect(mocks.select).toHaveBeenCalledTimes(1);
+ expect(mocks.update).not.toHaveBeenCalled();
+ expect(reply.payload).toEqual({ received: true });
+ });
+
+ it("returns 500 (retriable) when the idempotency lookup fails, so Stripe retries", async () => {
+ mocks.selectLimit.mockRejectedValue(new Error("db down"));
+ mocks.constructEvent.mockReturnValue(
+ stripeEvent("checkout.session.completed", {
+ id: "cs_err_read",
+ mode: "subscription",
+ customer: "cus_123",
+ metadata: { organizationId: "org_1" },
+ })
+ );
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expect(reply.statusCode).toBe(500);
+ expect(reply.payload).toEqual({ error: "Failed to link organization to Stripe customer." });
+ expect(mocks.update).not.toHaveBeenCalled();
+ });
+
+ it("returns 500 (retriable) when writing the customer id fails, so Stripe retries", async () => {
+ mocks.updateWhere.mockRejectedValue(new Error("write failed"));
+ mocks.constructEvent.mockReturnValue(
+ stripeEvent("checkout.session.completed", {
+ id: "cs_err_write",
+ mode: "subscription",
+ customer: "cus_123",
+ metadata: { organizationId: "org_1" },
+ })
+ );
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expect(reply.statusCode).toBe(500);
+ expect(reply.payload).toEqual({ error: "Failed to link organization to Stripe customer." });
+ });
+
+ // Non-retriable: a Stripe retry would redeliver the same metadata-less
+ // session, so the handler acks with 200 instead of asking for a retry.
+ it.each([
+ ["missing metadata", undefined],
+ ["missing organizationId", {}],
+ ["empty organizationId", { organizationId: "" }],
+ ])("skips the db entirely but still invalidates the cache when %s", async (_label, metadata) => {
+ mocks.constructEvent.mockReturnValue(
+ stripeEvent("checkout.session.completed", {
+ id: "cs_3",
+ mode: "subscription",
+ customer: "cus_123",
+ metadata,
+ })
+ );
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expectNoDbWrites();
+ // The cache invalidation happens before the metadata check.
+ expect(mocks.invalidateStripeSubscriptionCache).toHaveBeenCalledWith("cus_123");
+ // Still acknowledged to Stripe.
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({ received: true });
+ });
+
+ it("ignores non-subscription checkout sessions", async () => {
+ mocks.constructEvent.mockReturnValue(
+ stripeEvent("checkout.session.completed", {
+ id: "cs_4",
+ mode: "payment",
+ customer: "cus_123",
+ metadata: { organizationId: "org_1" },
+ })
+ );
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expectNoDbWrites();
+ expect(mocks.invalidateStripeSubscriptionCache).not.toHaveBeenCalled();
+ expect(reply.payload).toEqual({ received: true });
+ });
+});
+
+describe("handleWebhook β€” subscription lifecycle events", () => {
+ it.each(["customer.subscription.updated", "customer.subscription.deleted"])(
+ "invalidates the subscription cache for the event's customer on %s",
+ async eventType => {
+ mocks.constructEvent.mockReturnValue(stripeEvent(eventType, { id: "sub_1", customer: "cus_lifecycle" }));
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expect(mocks.invalidateStripeSubscriptionCache).toHaveBeenCalledTimes(1);
+ expect(mocks.invalidateStripeSubscriptionCache).toHaveBeenCalledWith("cus_lifecycle");
+ expectNoDbWrites();
+ expect(reply.payload).toEqual({ received: true });
+ }
+ );
+});
+
+describe("handleWebhook β€” unhandled event types", () => {
+ it("acknowledges unhandled events without side effects", async () => {
+ mocks.constructEvent.mockReturnValue(stripeEvent("invoice.paid", { id: "in_1", customer: "cus_1" }));
+
+ const reply = createReply();
+ await handleWebhook(createRequest(), reply);
+
+ expectNoDbWrites();
+ expect(mocks.invalidateStripeSubscriptionCache).not.toHaveBeenCalled();
+ expect(reply.statusCode).toBe(200);
+ expect(reply.payload).toEqual({ received: true });
+ });
+});
diff --git a/server/src/api/stripe/webhook.ts b/server/src/api/stripe/webhook.ts
index 1f7f9dc3f..b16eae40b 100644
--- a/server/src/api/stripe/webhook.ts
+++ b/server/src/api/stripe/webhook.ts
@@ -69,9 +69,15 @@ export async function handleWebhook(request: FastifyRequest, reply: FastifyReply
}
} catch (dbError: any) {
console.error(`Database error updating organization with Stripe customer ID: ${dbError.message}`);
- // Decide if you should still return 200 to Stripe or signal an error
+ // Retriable failure: the org is still not linked to its Stripe customer.
+ // Return a 5xx so Stripe retries the webhook; acking here would drop the
+ // event permanently and leave the organization unlinked forever.
+ return reply.status(500).send({ error: "Failed to link organization to Stripe customer." });
}
} else {
+ // Non-retriable: the checkout session itself lacks organizationId metadata,
+ // so a Stripe retry would deliver the exact same payload. Ack with 200 and
+ // log β€” retrying can never fix this.
console.error(
`Missing required metadata in checkout session ${session.id}. Customer ID: ${stripeCustomerId}, Organization ID: ${organizationId}`
);
@@ -82,6 +88,8 @@ export async function handleWebhook(request: FastifyRequest, reply: FastifyReply
// Subscription changes made outside updateSubscription (e.g. via the Stripe billing
// portal) only reach us through these events β€” drop the cached lookup so the change
// is reflected on the next read instead of waiting out the full TTL.
+ // Note: invalidateStripeSubscriptionCache is a synchronous in-process Map delete β€”
+ // it cannot fail, so there is no swallowed-error path here to convert to a 5xx.
case "customer.subscription.updated":
case "customer.subscription.deleted":
const changedSubscription = event.data.object as Stripe.Subscription;
diff --git a/server/src/services/import/importQuotaTracker.test.ts b/server/src/services/import/importQuotaTracker.test.ts
new file mode 100644
index 000000000..bc766cac9
--- /dev/null
+++ b/server/src/services/import/importQuotaTracker.test.ts
@@ -0,0 +1,238 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { ImportQuotaTracker } from "./importQuotaTracker.js";
+import { db } from "../../db/postgres/postgres.js";
+import { getBestSubscription } from "../../lib/subscriptionUtils.js";
+
+vi.mock("../../db/clickhouse/clickhouse.js", () => ({
+ clickhouse: { query: vi.fn() },
+}));
+
+vi.mock("../../db/postgres/postgres.js", () => ({
+ db: { select: vi.fn() },
+}));
+
+vi.mock("../../lib/subscriptionUtils.js", () => ({
+ getBestSubscription: vi.fn(),
+}));
+
+vi.mock("../../lib/const.js", () => ({
+ IS_CLOUD: true,
+}));
+
+vi.mock("../../api/analytics/utils/utils.js", () => ({
+ processResults: vi.fn(),
+}));
+
+// The constructor is private; tests build trackers directly with injected state
+// instead of going through the DB/ClickHouse-backed static create().
+function makeTracker(usage: Record<string, number>, limit: number, oldestAllowedMonth: string): ImportQuotaTracker {
+ return new (ImportQuotaTracker as any)(new Map(Object.entries(usage)), limit, oldestAllowedMonth);
+}
+
+// Drizzle query builders are thenable; create() awaits `.limit(1)` for the org
+// row and `.where(...)` for the site rows, so every link resolves to `rows`.
+function chainResolving(rows: unknown) {
+ const chain: any = {
+ from: () => chain,
+ where: () => chain,
+ limit: () => chain,
+ then: (resolve: any, reject: any) => Promise.resolve(rows).then(resolve, reject),
+ };
+ return chain;
+}
+
+function mockDbForCreate() {
+ vi.mocked(db.select as any)
+ .mockReturnValueOnce(chainResolving([{ stripeCustomerId: "cus_123" }]))
+ .mockReturnValueOnce(chainResolving([])); // no sites -> ClickHouse never queried
+}
+
+describe("ImportQuotaTracker", () => {
+ beforeEach(() => {
+ vi.useFakeTimers();
+ // Current month is 2024-06.
+ vi.setSystemTime(new Date("2024-06-15T12:00:00Z"));
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ vi.clearAllMocks();
+ });
+
+ describe("canImportBatch", () => {
+ it("should allow all timestamps when under the monthly limit", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ const result = tracker.canImportBatch(["2024-06-01 00:00:00", "2024-06-10 08:15:30", "2024-06-14 23:59:59"]);
+ expect(result).toEqual([0, 1, 2]);
+ });
+
+ it("should return an empty array for an empty batch", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ expect(tracker.canImportBatch([])).toEqual([]);
+ });
+
+ it("should account for existing usage in a month", () => {
+ const tracker = makeTracker({ "202405": 3 }, 5, "202312");
+ const result = tracker.canImportBatch([
+ "2024-05-01 10:00:00",
+ "2024-05-02 10:00:00",
+ "2024-05-03 10:00:00",
+ "2024-05-04 10:00:00",
+ ]);
+ // Only 2 slots remain in May (3 used out of 5).
+ expect(result).toEqual([0, 1]);
+ });
+
+ it("should track quota per month independently in a batch spanning months", () => {
+ const tracker = makeTracker({}, 2, "202312");
+ const result = tracker.canImportBatch([
+ "2024-05-01 10:00:00",
+ "2024-06-01 10:00:00",
+ "2024-05-02 10:00:00",
+ "2024-06-02 10:00:00",
+ "2024-05-03 10:00:00", // 3rd May event exceeds May's limit
+ ]);
+ expect(result).toEqual([0, 1, 2, 3]);
+ });
+
+ it("should reject events for a month exactly at the limit", () => {
+ const tracker = makeTracker({ "202406": 5 }, 5, "202312");
+ expect(tracker.canImportBatch(["2024-06-01 10:00:00"])).toEqual([]);
+ });
+
+ it("should allow exactly one more event when one below the limit", () => {
+ const tracker = makeTracker({ "202406": 4 }, 5, "202312");
+ expect(tracker.canImportBatch(["2024-06-01 10:00:00", "2024-06-02 10:00:00"])).toEqual([0]);
+ });
+
+ it("should accumulate increments across successive calls", () => {
+ const tracker = makeTracker({}, 3, "202312");
+ expect(tracker.canImportBatch(["2024-06-01 10:00:00", "2024-06-02 10:00:00"])).toEqual([0, 1]);
+ expect(tracker.canImportBatch(["2024-06-03 10:00:00", "2024-06-04 10:00:00"])).toEqual([0]);
+ expect(tracker.canImportBatch(["2024-06-05 10:00:00"])).toEqual([]);
+ });
+
+ it("should reject future timestamps", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ expect(tracker.canImportBatch(["2024-06-15 12:00:01", "2025-01-01 00:00:00"])).toEqual([]);
+ });
+
+ it("should allow a timestamp exactly at the current time", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ // dt > now is false when equal, so it is not treated as future.
+ expect(tracker.canImportBatch(["2024-06-15 12:00:00"])).toEqual([0]);
+ });
+
+ it("should reject timestamps older than the allowed window", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ expect(tracker.canImportBatch(["2023-11-30 23:59:59", "2020-01-01 00:00:00"])).toEqual([]);
+ });
+
+ it("should allow timestamps exactly in the oldest allowed month", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ // "202312" < "202312" is false, so the boundary month is allowed.
+ expect(tracker.canImportBatch(["2023-12-01 00:00:00"])).toEqual([0]);
+ });
+
+ it("should reject invalid timestamp strings", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ expect(
+ tracker.canImportBatch([
+ "not-a-date",
+ "2024-06-15T10:00:00", // ISO "T" separator does not match the expected format
+ "",
+ "2024-13-01 10:00:00", // invalid month
+ ])
+ ).toEqual([]);
+ });
+
+ it("should not consume quota for rejected timestamps", () => {
+ const tracker = makeTracker({}, 1, "202312");
+ const result = tracker.canImportBatch([
+ "2025-01-01 00:00:00", // future, rejected
+ "bad-timestamp", // invalid, rejected
+ "2024-06-01 10:00:00", // valid, takes the single slot
+ ]);
+ expect(result).toEqual([2]);
+ });
+
+ it("should keep valid events interleaved with rejected ones", () => {
+ const tracker = makeTracker({}, 10, "202312");
+ const result = tracker.canImportBatch(["2024-06-01 10:00:00", "garbage", "2024-06-02 10:00:00"]);
+ expect(result).toEqual([0, 2]);
+ });
+
+ it("should still reject malformed and future timestamps when the limit is Infinity", () => {
+ const tracker = makeTracker({}, Infinity, "190001");
+ // Self-hosted: quota accounting is disabled, but timestamp validation
+ // applies exactly like the cloud path.
+ expect(tracker.canImportBatch(["not-a-date", "2099-01-01 00:00:00", "2024-06-01 10:00:00"])).toEqual([2]);
+ });
+
+ it("should ignore the historical window when the limit is Infinity", () => {
+ // The window is tier/quota-derived, so it is disabled for self-hosted
+ // even if oldestAllowedMonth would otherwise reject the timestamp.
+ const tracker = makeTracker({}, Infinity, "202401");
+ expect(tracker.canImportBatch(["2020-01-01 00:00:00"])).toEqual([0]);
+ });
+ });
+
+ describe("getHistoricalWindowMonths (via create)", () => {
+ async function createTrackerForSubscription(subscription: Record<string, unknown>) {
+ mockDbForCreate();
+ vi.mocked(getBestSubscription).mockResolvedValueOnce(subscription as any);
+ return ImportQuotaTracker.create("org-1");
+ }
+
+ it("should allow 6 months of history for the free tier", async () => {
+ const tracker = await createTrackerForSubscription({
+ source: "free",
+ eventLimit: 10000,
+ });
+ // 2024-06 minus 6 months, start of month.
+ expect(tracker.getOldestAllowedMonth()).toBe("202312");
+ });
+
+ it("should allow 24 months of history for appsumo", async () => {
+ const tracker = await createTrackerForSubscription({
+ source: "appsumo",
+ planName: "appsumo-tier2",
+ eventLimit: 100000,
+ });
+ expect(tracker.getOldestAllowedMonth()).toBe("202206");
+ });
+
+ it("should allow 60 months of history for stripe pro plans", async () => {
+ const tracker = await createTrackerForSubscription({
+ source: "stripe",
+ planName: "pro100k",
+ eventLimit: 100000,
+ });
+ expect(tracker.getOldestAllowedMonth()).toBe("201906");
+ });
+
+ it("should allow 24 months of history for non-pro stripe plans", async () => {
+ const tracker = await createTrackerForSubscription({
+ source: "stripe",
+ planName: "standard100k",
+ eventLimit: 100000,
+ });
+ expect(tracker.getOldestAllowedMonth()).toBe("202206");
+ });
+
+ it("should use the subscription event limit as the monthly limit", async () => {
+ const tracker = await createTrackerForSubscription({
+ source: "free",
+ eventLimit: 2,
+ });
+ expect(tracker.canImportBatch(["2024-06-01 10:00:00", "2024-06-02 10:00:00", "2024-06-03 10:00:00"])).toEqual([
+ 0, 1,
+ ]);
+ });
+
+ it("should throw when the organization is not found", async () => {
+ vi.mocked(db.select as any).mockReturnValueOnce(chainResolving([]));
+ await expect(ImportQuotaTracker.create("missing-org")).rejects.toThrow("Organization missing-org not found");
+ });
+ });
+});
diff --git a/server/src/services/import/importQuotaTracker.ts b/server/src/services/import/importQuotaTracker.ts
index ea715c9ba..a508b43da 100644
--- a/server/src/services/import/importQuotaTracker.ts
+++ b/server/src/services/import/importQuotaTracker.ts
@@ -160,13 +160,10 @@ export class ImportQuotaTracker {
* @returns Array of indices indicating which events can be imported
*/
canImportBatch(timestamps: string[]): number[] {
- if (this.monthlyLimit === Infinity) {
- return timestamps.map((_, i) => i);
- }
-
const allowedIndices: number[] = [];
const monthlyIncrements = new Map<string, number>();
const now = DateTime.utc();
+ const unlimited = this.monthlyLimit === Infinity;
for (let i = 0; i < timestamps.length; i++) {
const timestamp = timestamps[i];
@@ -176,6 +173,13 @@ export class ImportQuotaTracker {
continue;
}
+ if (unlimited) {
+ // Self-hosted: no quota accounting and no tier-based historical window,
+ // but malformed and future timestamps are still rejected.
+ allowedIndices.push(i);
+ continue;
+ }
+
const month = dt.toFormat("yyyyMM");
if (month < this.oldestAllowedMonth) {
continue;
diff --git a/server/src/services/import/mappers/simpleAnalytics.test.ts b/server/src/services/import/mappers/simpleAnalytics.test.ts
new file mode 100644
index 000000000..80f0383bd
--- /dev/null
+++ b/server/src/services/import/mappers/simpleAnalytics.test.ts
@@ -0,0 +1,266 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { Settings } from "luxon";
+import { SimpleAnalyticsImportMapper } from "./simpleAnalytics.js";
+
+// Valid RFC4122 v4 UUIDs (variant nibble 8/9) β€” zod v3's .uuid() is lax, but
+// stricter validators must still accept the happy-path fixtures.
+const TEST_SESSION_ID = "9e3779b1-3c6e-4362-8a4f-81b88c81f013";
+const TEST_UUID = "12345678-90ab-4def-9234-567890abcdef";
+
+const CHROME_WINDOWS_UA =
+ "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36";
+const IPHONE_UA =
+ "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1";
+
+function makeEvent(overrides: Record<string, string> = {}) {
+ return {
+ added_iso: "2024-06-15T14:30:00Z",
+ country_code: "US",
+ datapoint: "pageview",
+ document_referrer: "https://google.com/search",
+ hostname: "example.com",
+ lang_language: "en",
+ lang_region: "us",
+ path: "/blog/post-1",
+ query: "utm_source=google",
+ screen_height: "1080",
+ screen_width: "1920",
+ session_id: TEST_SESSION_ID,
+ user_agent: CHROME_WINDOWS_UA,
+ uuid: TEST_UUID,
+ ...overrides,
+ };
+}
+
+describe("SimpleAnalyticsImportMapper", () => {
+ // The mapper reformats added_iso via DateTime.fromISO, which uses the system
+ // zone; pin it to UTC so the expected timestamps are deterministic.
+ let previousZone: typeof Settings.defaultZone;
+
+ beforeAll(() => {
+ previousZone = Settings.defaultZone;
+ Settings.defaultZone = "utc";
+ });
+
+ afterAll(() => {
+ Settings.defaultZone = previousZone;
+ });
+
+ describe("transform", () => {
+ it("should transform a valid pageview event", () => {
+ const events = [makeEvent()];
+ const result = SimpleAnalyticsImportMapper.transform(events, 1, "import-1");
+
+ expect(result).toHaveLength(1);
+ expect(result[0]).toMatchObject({
+ site_id: 1,
+ timestamp: "2024-06-15 14:30:00",
+ session_id: TEST_SESSION_ID,
+ user_id: TEST_UUID,
+ hostname: "example.com",
+ pathname: "/blog/post-1",
+ querystring: "?utm_source=google",
+ url_parameters: { utm_source: "google" },
+ page_title: "",
+ referrer: "https://google.com/search",
+ browser: "Chrome",
+ browser_version: "125",
+ operating_system: "Windows",
+ operating_system_version: "10",
+ language: "en-US",
+ country: "US",
+ region: "",
+ city: "",
+ lat: 0,
+ lon: 0,
+ screen_width: 1920,
+ screen_height: 1080,
+ device_type: "Desktop",
+ type: "pageview",
+ event_name: "",
+ props: {},
+ import_id: "import-1",
+ });
+ expect(result[0].channel).toBeTruthy();
+ });
+
+ it("should transform a non-pageview datapoint into a custom event", () => {
+ const events = [makeEvent({ datapoint: "signup_click" })];
+ const result = SimpleAnalyticsImportMapper.transform(events, 2, "import-2");
+
+ expect(result).toHaveLength(1);
+ expect(result[0].type).toBe("custom_event");
+ expect(result[0].event_name).toBe("signup_click");
+ });
+
+ describe("timestamp reformatting", () => {
+ it("should reformat the ISO timestamp to ClickHouse format", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ added_iso: "2023-01-05T09:07:03Z" })],
+ 1,
+ "i"
+ );
+ expect(result[0].timestamp).toBe("2023-01-05 09:07:03");
+ });
+
+ it("should drop fractional seconds", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ added_iso: "2024-06-15T14:30:00.123Z" })],
+ 1,
+ "i"
+ );
+ expect(result).toHaveLength(1);
+ expect(result[0].timestamp).toBe("2024-06-15 14:30:00");
+ });
+
+ it("should drop rows with non-ISO timestamps", () => {
+ for (const added_iso of [
+ "2024-06-15 14:30:00", // space separator
+ "2024-06-15T14:30:00", // missing Z
+ "2024-06-15T14:30:00+02:00", // offsets rejected by z.string().datetime()
+ "not-a-date",
+ "",
+ ]) {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ added_iso })], 1, "i");
+ expect(result).toHaveLength(0);
+ }
+ });
+ });
+
+ describe("user agent parsing", () => {
+ it("should classify an iPhone user agent as Mobile on iOS", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ user_agent: IPHONE_UA, screen_width: "390", screen_height: "844" })],
+ 1,
+ "i"
+ );
+ expect(result).toHaveLength(1);
+ expect(result[0].operating_system).toBe("iOS");
+ expect(result[0].device_type).toBe("Mobile");
+ });
+
+ it("should fall back to screen dimensions when the user agent is empty", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ user_agent: "" })], 1, "i");
+ expect(result).toHaveLength(1);
+ expect(result[0].browser).toBe("");
+ expect(result[0].browser_version).toBe("");
+ expect(result[0].operating_system).toBe("");
+ expect(result[0].operating_system_version).toBe("");
+ // 1920x1080 screen -> larger dimension > 1024 -> Desktop
+ expect(result[0].device_type).toBe("Desktop");
+ });
+ });
+
+ describe("language handling", () => {
+ it("should combine language and uppercased region", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ lang_language: "pt", lang_region: "br" })],
+ 1,
+ "i"
+ );
+ expect(result[0].language).toBe("pt-BR");
+ });
+
+ it("should use the bare language when the region is empty", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ lang_language: "de", lang_region: "" })],
+ 1,
+ "i"
+ );
+ expect(result[0].language).toBe("de");
+ });
+ });
+
+ describe("querystring handling", () => {
+ it("should prefix a non-empty query with ?", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ query: "a=1&b=2" })], 1, "i");
+ expect(result[0].querystring).toBe("?a=1&b=2");
+ expect(result[0].url_parameters).toEqual({ a: "1", b: "2" });
+ });
+
+ it("should leave an empty query empty", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ query: "" })], 1, "i");
+ expect(result[0].querystring).toBe("");
+ expect(result[0].url_parameters).toEqual({});
+ });
+ });
+
+ describe("referrer handling", () => {
+ it("should clear self-referrers", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ document_referrer: "https://example.com/previous" })],
+ 1,
+ "i"
+ );
+ expect(result[0].referrer).toBe("");
+ });
+
+ it("should keep external referrers", () => {
+ const result = SimpleAnalyticsImportMapper.transform(
+ [makeEvent({ document_referrer: "https://news.ycombinator.com/item" })],
+ 1,
+ "i"
+ );
+ expect(result[0].referrer).toBe("https://news.ycombinator.com/item");
+ });
+
+ it("should leave an empty referrer empty", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ document_referrer: "" })], 1, "i");
+ expect(result[0].referrer).toBe("");
+ });
+ });
+
+ describe("schema edge cases", () => {
+ it("should drop rows with non-numeric screen dimensions", () => {
+ const invalidScreens: Array<Record<string, string>> = [
+ { screen_width: "abc" },
+ { screen_width: "" },
+ { screen_height: "1080.5" },
+ { screen_height: "" },
+ ];
+ for (const overrides of invalidScreens) {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent(overrides)], 1, "i");
+ expect(result).toHaveLength(0);
+ }
+ });
+
+ it("should drop rows with an invalid country code", () => {
+ for (const country_code of ["USA", "us", "1A"]) {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ country_code })], 1, "i");
+ expect(result).toHaveLength(0);
+ }
+ });
+
+ it("should allow an empty country code", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ country_code: "" })], 1, "i");
+ expect(result).toHaveLength(1);
+ expect(result[0].country).toBe("");
+ });
+
+ it("should drop rows with an invalid session uuid", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ session_id: "not-a-uuid" })], 1, "i");
+ expect(result).toHaveLength(0);
+ });
+
+ it("should drop rows with an invalid user uuid", () => {
+ const result = SimpleAnalyticsImportMapper.transform([makeEvent({ uuid: "not-a-uuid" })], 1, "i");
+ expect(result).toHaveLength(0);
+ });
+ });
+
+ it("should keep valid rows when mixed with invalid ones", () => {
+ const events = [
+ makeEvent({ path: "/valid" }),
+ makeEvent({ added_iso: "bad" }),
+ makeEvent({ path: "/also-valid" }),
+ ];
+ const result = SimpleAnalyticsImportMapper.transform(events, 1, "i");
+ expect(result).toHaveLength(2);
+ expect(result.map(e => e.pathname)).toEqual(["/valid", "/also-valid"]);
+ });
+
+ it("should return empty array for empty input", () => {
+ expect(SimpleAnalyticsImportMapper.transform([], 1, "i")).toHaveLength(0);
+ });
+ });
+});
diff --git a/server/src/services/import/mappers/umami.test.ts b/server/src/services/import/mappers/umami.test.ts
new file mode 100644
index 000000000..696c1b520
--- /dev/null
+++ b/server/src/services/import/mappers/umami.test.ts
@@ -0,0 +1,287 @@
+import { describe, it, expect } from "vitest";
+import { UmamiImportMapper } from "./umami.js";
+
+// Valid RFC4122 v4 UUID (variant nibble 8) β€” zod v3's .uuid() is lax, but
+// stricter validators must still accept the happy-path fixtures.
+const TEST_SESSION_ID = "9e3779b1-3c6e-4362-8a4f-81b88c81f013";
+
+function makeEvent(overrides: Record<string, string> = {}) {
+ return {
+ session_id: TEST_SESSION_ID,
+ hostname: "example.com",
+ browser: "chrome",
+ os: "Windows 10",
+ device: "desktop",
+ screen: "1920x1080",
+ language: "en-US",
+ country: "US",
+ region: "US-CA",
+ city: "San Francisco",
+ url_path: "/blog/post-1",
+ url_query: "utm_source=google",
+ referrer_path: "/search",
+ referrer_domain: "google.com",
+ page_title: "Post 1",
+ event_type: "1",
+ event_name: "",
+ distinct_id: "visitor-1",
+ created_at: "2024-06-15 14:30:00",
+ ...overrides,
+ };
+}
+
+describe("UmamiImportMapper", () => {
+ describe("transform", () => {
+ it("should transform a valid pageview event", () => {
+ const events = [makeEvent()];
+ const result = UmamiImportMapper.transform(events, 1, "import-1");
+
+ expect(result).toHaveLength(1);
+ expect(result[0]).toMatchObject({
+ site_id: 1,
+ timestamp: "2024-06-15 14:30:00",
+ session_id: TEST_SESSION_ID,
+ user_id: "visitor-1",
+ hostname: "example.com",
+ pathname: "/blog/post-1",
+ querystring: "?utm_source=google",
+ url_parameters: { utm_source: "google" },
+ page_title: "Post 1",
+ referrer: "https://google.com/search",
+ browser: "Chrome",
+ browser_version: "",
+ operating_system: "Windows",
+ operating_system_version: "10",
+ language: "en-US",
+ country: "US",
+ region: "US-CA",
+ city: "San Francisco",
+ lat: 0,
+ lon: 0,
+ screen_width: 1920,
+ screen_height: 1080,
+ device_type: "Desktop",
+ type: "pageview",
+ event_name: "",
+ props: {},
+ import_id: "import-1",
+ });
+ expect(result[0].channel).toBeTruthy();
+ });
+
+ it("should transform a custom event", () => {
+ const events = [makeEvent({ event_type: "2", event_name: "SignUp" })];
+ const result = UmamiImportMapper.transform(events, 2, "import-2");
+
+ expect(result).toHaveLength(1);
+ expect(result[0].type).toBe("custom_event");
+ expect(result[0].event_name).toBe("SignUp");
+ });
+
+ it("should clear the event name for pageviews", () => {
+ const events = [makeEvent({ event_type: "1", event_name: "ShouldBeDropped" })];
+ const result = UmamiImportMapper.transform(events, 1, "import-1");
+ expect(result).toHaveLength(1);
+ expect(result[0].event_name).toBe("");
+ });
+
+ describe("browser/os/device normalization", () => {
+ it("should map known browser keys case-insensitively", () => {
+ const cases: Array<[string, string]> = [
+ ["chrome", "Chrome"],
+ ["Chrome", "Chrome"],
+ ["crios", "Mobile Chrome"],
+ ["edge-chromium", "Edge"],
+ ["ios", "Mobile Safari"],
+ ["samsung", "Samsung Internet"],
+ ];
+ for (const [input, expected] of cases) {
+ const result = UmamiImportMapper.transform([makeEvent({ browser: input })], 1, "i");
+ expect(result[0].browser).toBe(expected);
+ }
+ });
+
+ it("should pass through unknown browsers unchanged", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ browser: "brave" })], 1, "i");
+ expect(result[0].browser).toBe("brave");
+ });
+
+ it("should map known operating systems", () => {
+ const cases: Array<[string, string]> = [
+ ["Windows 10", "Windows"],
+ ["Mac OS", "macOS"],
+ ["iOS", "iOS"],
+ ["Android OS", "Android"],
+ ["Linux", "Linux"],
+ ["Chrome OS", "Chrome OS"],
+ ];
+ for (const [input, expected] of cases) {
+ const result = UmamiImportMapper.transform([makeEvent({ os: input })], 1, "i");
+ expect(result[0].operating_system).toBe(expected);
+ }
+ });
+
+ it("should map device types to Desktop/Mobile", () => {
+ const cases: Array<[string, string]> = [
+ ["desktop", "Desktop"],
+ ["laptop", "Desktop"],
+ ["mobile", "Mobile"],
+ ["tablet", "Mobile"],
+ ];
+ for (const [input, expected] of cases) {
+ const result = UmamiImportMapper.transform([makeEvent({ device: input })], 1, "i");
+ expect(result[0].device_type).toBe(expected);
+ }
+ });
+ });
+
+ describe("operating_system_version derivation", () => {
+ // Regression test: deriveOsVersion must match case-insensitively like the
+ // os map does β€” raw umami exports vary in casing.
+ it("should derive version 10 from any casing of Windows 10", () => {
+ for (const os of ["Windows 10", "windows 10", "WINDOWS 10"]) {
+ const result = UmamiImportMapper.transform([makeEvent({ os })], 1, "i");
+ expect(result).toHaveLength(1);
+ expect(result[0].operating_system_version).toBe("10");
+ expect(result[0].operating_system).toBe("Windows");
+ }
+ });
+
+ it("should derive version 7 from any casing of Windows 7", () => {
+ for (const os of ["Windows 7", "windows 7", "wInDoWs 7"]) {
+ const result = UmamiImportMapper.transform([makeEvent({ os })], 1, "i");
+ expect(result).toHaveLength(1);
+ expect(result[0].operating_system_version).toBe("7");
+ }
+ });
+
+ it("should derive an empty version for all other operating systems", () => {
+ for (const os of ["Mac OS", "Linux", "Android OS", "Windows Server 2003", "iOS"]) {
+ const result = UmamiImportMapper.transform([makeEvent({ os })], 1, "i");
+ expect(result[0].operating_system_version).toBe("");
+ }
+ });
+ });
+
+ describe("screen parsing", () => {
+ it("should split screen into width and height", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ screen: "390x844" })], 1, "i");
+ expect(result[0].screen_width).toBe(390);
+ expect(result[0].screen_height).toBe(844);
+ });
+
+ it("should default to 0x0 for an empty screen", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ screen: "" })], 1, "i");
+ expect(result[0].screen_width).toBe(0);
+ expect(result[0].screen_height).toBe(0);
+ });
+ });
+
+ describe("querystring handling", () => {
+ it("should prefix a non-empty url_query with ?", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ url_query: "a=1&b=2" })], 1, "i");
+ expect(result[0].querystring).toBe("?a=1&b=2");
+ expect(result[0].url_parameters).toEqual({ a: "1", b: "2" });
+ });
+
+ it("should leave an empty url_query empty", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ url_query: "" })], 1, "i");
+ expect(result[0].querystring).toBe("");
+ expect(result[0].url_parameters).toEqual({});
+ });
+ });
+
+ describe("referrer handling", () => {
+ it("should prefix the referrer domain with https:// and append the path", () => {
+ const result = UmamiImportMapper.transform(
+ [makeEvent({ referrer_domain: "news.ycombinator.com", referrer_path: "/item" })],
+ 1,
+ "i"
+ );
+ expect(result[0].referrer).toBe("https://news.ycombinator.com/item");
+ });
+
+ it("should clear self-referrers", () => {
+ const result = UmamiImportMapper.transform(
+ [makeEvent({ referrer_domain: "example.com", referrer_path: "/previous" })],
+ 1,
+ "i"
+ );
+ expect(result[0].referrer).toBe("");
+ });
+
+ it("should clear self-referrers when the hostname has a www prefix", () => {
+ const result = UmamiImportMapper.transform(
+ [
+ makeEvent({
+ hostname: "www.example.com",
+ referrer_domain: "example.com",
+ referrer_path: "/previous",
+ }),
+ ],
+ 1,
+ "i"
+ );
+ expect(result[0].referrer).toBe("");
+ });
+
+ it("should leave the referrer empty when domain and path are empty", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ referrer_domain: "", referrer_path: "" })], 1, "i");
+ expect(result[0].referrer).toBe("");
+ });
+ });
+
+ describe("invalid rows", () => {
+ it("should drop rows with an invalid session uuid", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ session_id: "not-a-uuid" })], 1, "i");
+ expect(result).toHaveLength(0);
+ });
+
+ it("should drop rows with an invalid country code", () => {
+ for (const country of ["USA", "us", "1A"]) {
+ const result = UmamiImportMapper.transform([makeEvent({ country })], 1, "i");
+ expect(result).toHaveLength(0);
+ }
+ });
+
+ it("should allow an empty country code", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ country: "" })], 1, "i");
+ expect(result).toHaveLength(1);
+ expect(result[0].country).toBe("");
+ });
+
+ it("should drop rows with an invalid timestamp format", () => {
+ for (const created_at of [
+ "2024-06-15T14:30:00", // ISO "T" separator
+ "2024-13-01 10:00:00", // invalid month
+ "2024-06-15 24:30:00", // invalid hour
+ "not-a-date",
+ "",
+ ]) {
+ const result = UmamiImportMapper.transform([makeEvent({ created_at })], 1, "i");
+ expect(result).toHaveLength(0);
+ }
+ });
+
+ it("should drop rows with a malformed screen value", () => {
+ const result = UmamiImportMapper.transform([makeEvent({ screen: "1920*1080" })], 1, "i");
+ expect(result).toHaveLength(0);
+ });
+
+ it("should keep valid rows when mixed with invalid ones", () => {
+ const events = [
+ makeEvent({ url_path: "/valid" }),
+ makeEvent({ session_id: "bad" }),
+ makeEvent({ url_path: "/also-valid" }),
+ ];
+ const result = UmamiImportMapper.transform(events, 1, "i");
+ expect(result).toHaveLength(2);
+ expect(result.map(e => e.pathname)).toEqual(["/valid", "/also-valid"]);
+ });
+ });
+
+ it("should return empty array for empty input", () => {
+ expect(UmamiImportMapper.transform([], 1, "i")).toHaveLength(0);
+ });
+ });
+});
diff --git a/server/src/services/import/mappers/umami.ts b/server/src/services/import/mappers/umami.ts
index 5e2f81d8a..10114fd35 100644
--- a/server/src/services/import/mappers/umami.ts
+++ b/server/src/services/import/mappers/umami.ts
@@ -109,6 +109,12 @@ export class UmamiImportMapper {
static readonly umamiEventKeyOnlySchema = deriveKeyOnlySchema(UmamiImportMapper.umamiEventSchema);
+ // Match case-insensitively like osMap does β€” raw umami exports vary in casing.
+ private static deriveOsVersion(rawOs: string): string {
+ const key = rawOs.toLowerCase();
+ return key === "windows 10" ? "10" : key === "windows 7" ? "7" : "";
+ }
+
static transform(events: UmamiEvent[], site: number, importId: string): RybbitEvent[] {
return events.reduce<RybbitEvent[]>((acc, event) => {
const parsed = UmamiImportMapper.umamiEventSchema.safeParse(event);
@@ -138,7 +144,7 @@ export class UmamiImportMapper {
browser: data.browser,
browser_version: "",
operating_system: data.os,
- operating_system_version: event.os === "Windows 10" ? "10" : event.os === "Windows 7" ? "7" : "",
+ operating_system_version: UmamiImportMapper.deriveOsVersion(event.os),
language: data.language,
country: data.country,
region: data.region,
diff --git a/server/src/services/uptime/validationEngine.test.ts b/server/src/services/uptime/validationEngine.test.ts
new file mode 100644
index 000000000..131d7e1cc
--- /dev/null
+++ b/server/src/services/uptime/validationEngine.test.ts
@@ -0,0 +1,281 @@
+import { describe, expect, it } from "vitest";
+import { applyValidationRules } from "./validationEngine.js";
+import { HttpCheckResult, ValidationRule } from "./types.js";
+
+function createResult(overrides: Partial<HttpCheckResult> = {}): HttpCheckResult {
+ return {
+ status: "success",
+ statusCode: 200,
+ responseTimeMs: 150,
+ timing: {},
+ headers: {},
+ bodySizeBytes: 1024,
+ validationErrors: [],
+ ...overrides,
+ };
+}
+
+describe("applyValidationRules", () => {
+ it("returns no errors for an empty rule list", () => {
+ expect(applyValidationRules(createResult(), [])).toEqual([]);
+ });
+
+ describe("status_code", () => {
+ it("passes and fails 'equals'", () => {
+ const rule: ValidationRule = { type: "status_code", operator: "equals", value: 200 };
+ expect(applyValidationRules(createResult({ statusCode: 200 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ statusCode: 500 }), [rule])).toEqual([
+ "Status code 500 does not equal 200",
+ ]);
+ });
+
+ it("passes and fails 'not_equals'", () => {
+ const rule: ValidationRule = { type: "status_code", operator: "not_equals", value: 500 };
+ expect(applyValidationRules(createResult({ statusCode: 200 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ statusCode: 500 }), [rule])).toEqual(["Status code 500 equals 500"]);
+ });
+
+ it("passes and fails 'in' with an array value", () => {
+ const rule: ValidationRule = { type: "status_code", operator: "in", value: [200, 201, 204] };
+ expect(applyValidationRules(createResult({ statusCode: 204 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ statusCode: 404 }), [rule])).toEqual([
+ "Status code 404 is not in [200, 201, 204]",
+ ]);
+ });
+
+ it("passes and fails 'not_in' with an array value", () => {
+ const rule: ValidationRule = { type: "status_code", operator: "not_in", value: [500, 502, 503] };
+ expect(applyValidationRules(createResult({ statusCode: 200 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ statusCode: 502 }), [rule])).toEqual([
+ "Status code 502 is in [500, 502, 503]",
+ ]);
+ });
+
+ it("fails explicitly when the status code is falsy", () => {
+ // Fail-closed: a missing status code (connection-level failure) or a literal 0
+ // means no response was received, so a status_code rule must fail explicitly
+ // rather than silently pass.
+ const rule: ValidationRule = { type: "status_code", operator: "equals", value: 200 };
+ expect(applyValidationRules(createResult({ statusCode: undefined }), [rule])).toEqual([
+ "No status code available to validate",
+ ]);
+ expect(applyValidationRules(createResult({ statusCode: 0 }), [rule])).toEqual([
+ "No status code available to validate",
+ ]);
+ });
+
+ it("fails 'in' and 'not_in' when the value is not an array", () => {
+ // Fail-closed: a scalar operand on in/not_in is a misconfigured rule and must
+ // surface as a validation failure instead of silently passing.
+ expect(
+ applyValidationRules(createResult({ statusCode: 404 }), [{ type: "status_code", operator: "in", value: 200 }])
+ ).toEqual(['Validation rule misconfigured: "in" operator requires an array value']);
+ expect(
+ applyValidationRules(createResult({ statusCode: 500 }), [
+ { type: "status_code", operator: "not_in", value: 500 },
+ ])
+ ).toEqual(['Validation rule misconfigured: "not_in" operator requires an array value']);
+ });
+ });
+
+ describe("response_time", () => {
+ it("'less_than' fails exactly at the threshold and passes just below", () => {
+ const rule: ValidationRule = { type: "response_time", operator: "less_than", value: 500 };
+ expect(applyValidationRules(createResult({ responseTimeMs: 499 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ responseTimeMs: 500 }), [rule])).toEqual([
+ "Response time 500ms is not less than 500ms",
+ ]);
+ expect(applyValidationRules(createResult({ responseTimeMs: 501 }), [rule])).toEqual([
+ "Response time 501ms is not less than 500ms",
+ ]);
+ });
+
+ it("'greater_than' fails exactly at the threshold and passes just above", () => {
+ const rule: ValidationRule = { type: "response_time", operator: "greater_than", value: 100 };
+ expect(applyValidationRules(createResult({ responseTimeMs: 101 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ responseTimeMs: 100 }), [rule])).toEqual([
+ "Response time 100ms is not greater than 100ms",
+ ]);
+ expect(applyValidationRules(createResult({ responseTimeMs: 99 }), [rule])).toEqual([
+ "Response time 99ms is not greater than 100ms",
+ ]);
+ });
+ });
+
+ describe("response_size", () => {
+ it("'less_than' fails exactly at the threshold and passes just below", () => {
+ const rule: ValidationRule = { type: "response_size", operator: "less_than", value: 2048 };
+ expect(applyValidationRules(createResult({ bodySizeBytes: 2047 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ bodySizeBytes: 2048 }), [rule])).toEqual([
+ "Response size 2048 bytes is not less than 2048 bytes",
+ ]);
+ });
+
+ it("'greater_than' fails exactly at the threshold and passes just above", () => {
+ const rule: ValidationRule = { type: "response_size", operator: "greater_than", value: 100 };
+ expect(applyValidationRules(createResult({ bodySizeBytes: 101 }), [rule])).toEqual([]);
+ expect(applyValidationRules(createResult({ bodySizeBytes: 100 }), [rule])).toEqual([
+ "Response size 100 bytes is not greater than 100 bytes",
+ ]);
+ });
+ });
+
+ describe("response_body_contains", () => {
+ it("passes when the body contains the value and fails when it does not", () => {
+ const rule: ValidationRule = { type: "response_body_contains", value: "OK" };
+ expect(applyValidationRules(createResult(), [rule], "status: OK")).toEqual([]);
+ expect(applyValidationRules(createResult(), [rule], "status: down")).toEqual([
+ 'Response body does not contain "OK"',
+ ]);
+ });
+
+ it("is case sensitive by default and case insensitive when caseSensitive is false", () => {
+ expect(applyValidationRules(createResult(), [{ type: "response_body_contains", value: "OK" }], "ok")).toEqual([
+ 'Response body does not contain "OK"',
+ ]);
+ expect(
+ applyValidationRules(
+ createResult(),
+ [{ type: "response_body_contains", value: "OK", caseSensitive: false }],
+ "ok"
+ )
+ ).toEqual([]);
+ });
+
+ it("fails with a dedicated error when the body is empty", () => {
+ const rule: ValidationRule = { type: "response_body_contains", value: "OK" };
+ expect(applyValidationRules(createResult(), [rule], undefined)).toEqual(["Response body is empty"]);
+ expect(applyValidationRules(createResult(), [rule], "")).toEqual(["Response body is empty"]);
+ });
+ });
+
+ describe("response_body_not_contains", () => {
+ it("passes when absent and fails when present", () => {
+ const rule: ValidationRule = { type: "response_body_not_contains", value: "error" };
+ expect(applyValidationRules(createResult(), [rule], "all good")).toEqual([]);
+ expect(applyValidationRules(createResult(), [rule], "fatal error occurred")).toEqual([
+ 'Response body contains "error"',
+ ]);
+ });
+
+ it("passes when the body is empty", () => {
+ const rule: ValidationRule = { type: "response_body_not_contains", value: "error" };
+ expect(applyValidationRules(createResult(), [rule], undefined)).toEqual([]);
+ });
+
+ it("respects caseSensitive: false", () => {
+ expect(
+ applyValidationRules(
+ createResult(),
+ [{ type: "response_body_not_contains", value: "ERROR", caseSensitive: false }],
+ "an error occurred"
+ )
+ ).toEqual(['Response body contains "ERROR"']);
+ });
+ });
+
+ describe("header_exists", () => {
+ it("matches header names case-insensitively", () => {
+ const result = createResult({ headers: { "Content-Type": "application/json" } });
+ expect(applyValidationRules(result, [{ type: "header_exists", header: "content-type" }])).toEqual([]);
+ expect(applyValidationRules(result, [{ type: "header_exists", header: "CONTENT-TYPE" }])).toEqual([]);
+ });
+
+ it("fails when the header is missing", () => {
+ const result = createResult({ headers: { "Content-Type": "application/json" } });
+ expect(applyValidationRules(result, [{ type: "header_exists", header: "X-Request-Id" }])).toEqual([
+ 'Header "X-Request-Id" does not exist',
+ ]);
+ });
+
+ it("fails when no header name is specified", () => {
+ expect(applyValidationRules(createResult(), [{ type: "header_exists" }])).toEqual(["Header name not specified"]);
+ });
+ });
+
+ describe("header_value", () => {
+ const result = createResult({ headers: { "Content-Type": "Application/JSON" } });
+
+ it("matches header names case-insensitively but values case-sensitively for 'equals'", () => {
+ expect(
+ applyValidationRules(result, [
+ { type: "header_value", header: "content-type", operator: "equals", value: "Application/JSON" },
+ ])
+ ).toEqual([]);
+ expect(
+ applyValidationRules(result, [
+ { type: "header_value", header: "content-type", operator: "equals", value: "application/json" },
+ ])
+ ).toEqual(['Header "content-type" value "Application/JSON" does not equal "application/json"']);
+ });
+
+ it("supports 'contains' on the header value, case-sensitively", () => {
+ expect(
+ applyValidationRules(result, [
+ { type: "header_value", header: "Content-Type", operator: "contains", value: "JSON" },
+ ])
+ ).toEqual([]);
+ expect(
+ applyValidationRules(result, [
+ { type: "header_value", header: "Content-Type", operator: "contains", value: "json" },
+ ])
+ ).toEqual(['Header "Content-Type" value "Application/JSON" does not contain "json"']);
+ });
+
+ it("fails when the header is missing or unnamed", () => {
+ expect(
+ applyValidationRules(result, [{ type: "header_value", header: "X-Missing", operator: "equals", value: "x" }])
+ ).toEqual(['Header "X-Missing" does not exist']);
+ expect(applyValidationRules(result, [{ type: "header_value", operator: "equals", value: "x" }])).toEqual([
+ "Header name not specified",
+ ]);
+ });
+ });
+
+ describe("rule combination and error handling", () => {
+ it("evaluates every rule and collects all failures in rule order", () => {
+ const rules: ValidationRule[] = [
+ { type: "status_code", operator: "equals", value: 200 },
+ { type: "response_time", operator: "less_than", value: 100 },
+ { type: "response_body_contains", value: "healthy" },
+ ];
+ const result = createResult({ statusCode: 503, responseTimeMs: 250 });
+
+ // All rules run: a failure does not short-circuit the remaining rules.
+ expect(applyValidationRules(result, rules, "service degraded")).toEqual([
+ "Status code 503 does not equal 200",
+ "Response time 250ms is not less than 100ms",
+ 'Response body does not contain "healthy"',
+ ]);
+ });
+
+ it("only reports the rules that fail", () => {
+ const rules: ValidationRule[] = [
+ { type: "status_code", operator: "equals", value: 200 },
+ { type: "response_body_contains", value: "down" },
+ ];
+ expect(applyValidationRules(createResult(), rules, "system is down")).toEqual([]);
+ });
+
+ it("reports unknown rule types as errors", () => {
+ expect(applyValidationRules(createResult(), [{ type: "certificate" as ValidationRule["type"] }])).toEqual([
+ "Unknown validation rule type: certificate",
+ ]);
+ });
+
+ it("converts a thrown validator error into a validation error instead of aborting", () => {
+ // headers is typed as Record<string, string>, but a malformed result at runtime
+ // (headers undefined) makes Object.keys throw; the engine catches it and keeps
+ // evaluating the remaining rules.
+ const broken = createResult({ headers: undefined as unknown as Record<string, string>, statusCode: 500 });
+ const errors = applyValidationRules(broken, [
+ { type: "header_exists", header: "Content-Type" },
+ { type: "status_code", operator: "equals", value: 200 },
+ ]);
+
+ expect(errors).toHaveLength(2);
+ expect(errors[0]).toMatch(/^Validation rule error: /);
+ expect(errors[1]).toBe("Status code 500 does not equal 200");
+ });
+ });
+});
diff --git a/server/src/services/uptime/validationEngine.ts b/server/src/services/uptime/validationEngine.ts
index 5b0b68c5a..2a62657cc 100644
--- a/server/src/services/uptime/validationEngine.ts
+++ b/server/src/services/uptime/validationEngine.ts
@@ -24,7 +24,9 @@ export function applyValidationRules(
function validateRule(result: HttpCheckResult, rule: ValidationRule, responseBody?: string): string | null {
switch (rule.type) {
case "status_code":
- if (!result.statusCode) return null;
+ // Fail closed: a missing status code means the check never got a response,
+ // so a status_code expectation cannot be considered satisfied.
+ if (!result.statusCode) return "No status code available to validate";
return validateStatusCode(result.statusCode, rule);
case "response_time":
@@ -69,13 +71,21 @@ function validateStatusCode(statusCode: number, rule: ValidationRule): string |
break;
case "in":
- if (Array.isArray(value) && !value.includes(statusCode)) {
+ // Fail closed: a non-array operand is a misconfigured rule, not a pass.
+ if (!Array.isArray(value)) {
+ return `Validation rule misconfigured: "in" operator requires an array value`;
+ }
+ if (!value.includes(statusCode)) {
return `Status code ${statusCode} is not in [${value.join(", ")}]`;
}
break;
case "not_in":
- if (Array.isArray(value) && value.includes(statusCode)) {
+ // Fail closed: a non-array operand is a misconfigured rule, not a pass.
+ if (!Array.isArray(value)) {
+ return `Validation rule misconfigured: "not_in" operator requires an array value`;
+ }
+ if (value.includes(statusCode)) {
return `Status code ${statusCode} is in [${value.join(", ")}]`;
}
break;