🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
import { ALL_CLIENT_BOT_SIGNAL_BITS, MAX_CLIENT_BOT_SCORE } from "@rybbit/shared";
import { z } from "zod";
/**
* Cut a string to `maxLength` UTF-16 units without splitting a surrogate pair:
* half an emoji serializes to an escape ClickHouse refuses, losing the row.
*/
export function truncateString(value: string, maxLength: number): string {
if (value.length <= maxLength) return value;
const lastCode = value.charCodeAt(maxLength - 1);
return value.slice(0, lastCode >= 0xd800 && lastCode <= 0xdbff ? maxLength - 1 : maxLength);
}
// The page's own URL, title and referrer are cut to length rather than
// rejected. They come from whatever page the visitor is on, not from the
// integration, and a 400 dropped every event on a page whose title or URL ran
// long — whichever client (tracker, SDK, older cached script) sent it.
const truncatedString = (maxLength: number) => z.string().transform(value => truncateString(value, maxLength));
// The path and query string, though, are cut only after Site Exclusions have
// matched them whole (truncateUrlForStorage): cut first, `?padding=…&preview=1`
// lost the very parameter a "preview" exclusion names. The validation bound
// keeps that matching cheap and sits far past any real page's URL.
const MAX_URL_PART_LENGTH = 2048;
const MAX_RAW_URL_PART_LENGTH = 16 * 1024;
// Shared fields for all event types
const baseEventFields = {
site_id: z.string().min(1),
hostname: z.string().max(253).optional(),
pathname: z.string().max(MAX_RAW_URL_PART_LENGTH).optional(),
querystring: z.string().max(MAX_RAW_URL_PART_LENGTH).optional(),
screenWidth: z.number().int().nonnegative().optional(),
screenHeight: z.number().int().nonnegative().optional(),
language: z.string().max(35).optional(),
page_title: truncatedString(512).optional(),
referrer: truncatedString(2048).optional(),
anonymous_id: z.string().min(1).max(255).optional(),
user_id: z.string().max(255).optional(),
tag: z.string().max(256).optional(),
feature_flags: z.record(z.string().max(100), z.string().max(2048)).optional(),
visitor_id: z.string().min(1).max(64).optional(),
ip_address: z.string().ip().optional(),
user_agent: z.string().max(512).optional(),
// Bounds come from the Bot Signal contract, so appending a signal bit widens
// the accepted mask with it. Hard-coding the bound is how the 12th bit
// (squareScreen = 2048) came to fail validation and drop the whole event.
_bs: z.number().int().min(0).max(MAX_CLIENT_BOT_SCORE).optional(),
_bsm: z.number().int().min(0).max(ALL_CLIENT_BOT_SIGNAL_BITS).optional(),
};
// Default event_name and properties used by pageview and performance
const defaultEventProps = {
event_name: z.string().max(256).optional(),
properties: z.string().max(2048).optional(),
};
// Reusable JSON validation refine
const jsonStringRefine = (message: string) =>
z
.string()
.max(2048)
.refine(
val => {
try {
JSON.parse(val);
return true;
} catch {
return false;
}
},
{ message }
)
.optional();
// Define Zod schema for validation
export const trackingPayloadSchema = z.discriminatedUnion("type", [
z
.object({
type: z.literal("pageview"),
...baseEventFields,
...defaultEventProps,
})
.strict(),
z
.object({
type: z.literal("custom_event"),
...baseEventFields,
event_name: z.string().min(1).max(256),
properties: jsonStringRefine("Properties must be a valid JSON string"),
})
.strict(),
z
.object({
type: z.literal("performance"),
...baseEventFields,
...defaultEventProps,
// Performance metrics (can be null if not collected)
lcp: z.number().min(0).nullable().optional(),
cls: z.number().min(0).nullable().optional(),
inp: z.number().min(0).nullable().optional(),
fcp: z.number().min(0).nullable().optional(),
ttfb: z.number().min(0).nullable().optional(),
})
.strict(),
z
.object({
type: z.literal("outbound"),
...baseEventFields,
event_name: z.string().max(256).optional(),
properties: z
.string()
.max(2048)
.refine(
val => {
try {
const parsed = JSON.parse(val);
if (typeof parsed.url !== "string" || parsed.url.length === 0) return false;
if (parsed.text && typeof parsed.text !== "string") return false;
if (parsed.target && typeof parsed.target !== "string") return false;
try {
new URL(parsed.url);
} catch {
return false;
}
return true;
} catch {
return false;
}
},
{
message: "Properties must be valid JSON with outbound link fields (url required, text and target optional)",
}
),
})
.strict(),
z
.object({
type: z.literal("error"),
...baseEventFields,
event_name: z.string().min(1).max(256), // Error type (TypeError, ReferenceError, etc.)
properties: z
.string()
.max(4096) // Larger limit for error details
.refine(
val => {
try {
const parsed = JSON.parse(val);
if (typeof parsed.message !== "string") return false;
if (parsed.stack && typeof parsed.stack !== "string") return false;
if (parsed.fileName && typeof parsed.fileName !== "string") return false;
if (parsed.lineNumber && typeof parsed.lineNumber !== "number") return false;
if (parsed.columnNumber && typeof parsed.columnNumber !== "number") return false;
// Apply truncation limits
if (parsed.message && parsed.message.length > 500) {
parsed.message = parsed.message.substring(0, 500);
}
if (parsed.stack && parsed.stack.length > 2000) {
parsed.stack = parsed.stack.substring(0, 2000);
}
return true;
} catch {
return false;
}
},
{
message:
"Properties must be valid JSON with error fields (message, stack, fileName, lineNumber, columnNumber)",
}
),
})
.strict(),
z
.object({
type: z.literal("button_click"),
...baseEventFields,
event_name: z.string().max(256).optional(),
properties: jsonStringRefine("Properties must be valid JSON"),
})
.strict(),
z
.object({
type: z.literal("copy"),
...baseEventFields,
event_name: z.string().max(256).optional(),
properties: z
.string()
.max(2048)
.refine(
val => {
try {
const parsed = JSON.parse(val);
if (typeof parsed.sourceElement !== "string") return false;
if (parsed.text !== undefined && typeof parsed.text !== "string") return false;
if (parsed.textLength !== undefined && (typeof parsed.textLength !== "number" || parsed.textLength < 0))
return false;
return true;
} catch {
return false;
}
},
{
message:
"Properties must be valid JSON with copy fields (sourceElement required, text and textLength optional)",
}
),
})
.strict(),
z
.object({
type: z.literal("form_submit"),
...baseEventFields,
event_name: z.string().max(256).optional(),
properties: z
.string()
.max(2048)
.refine(
val => {
try {
const parsed = JSON.parse(val);
if (typeof parsed.formId !== "string") return false;
if (typeof parsed.formName !== "string") return false;
if (typeof parsed.formAction !== "string") return false;
if (typeof parsed.method !== "string") return false;
if (typeof parsed.fieldCount !== "number" || parsed.fieldCount < 0) return false;
return true;
} catch {
return false;
}
},
{
message:
"Properties must be valid JSON with form_submit fields (formId, formName, formAction, method, fieldCount required)",
}
),
})
.strict(),
z
.object({
type: z.literal("input_change"),
...baseEventFields,
event_name: z.string().max(256).optional(),
properties: z
.string()
.max(2048)
.refine(
val => {
try {
const parsed = JSON.parse(val);
if (typeof parsed.element !== "string") return false;
if (typeof parsed.inputName !== "string") return false;
return true;
} catch {
return false;
}
},
{
message: "Properties must be valid JSON with input_change fields (element, inputName required)",
}
),
})
.strict(),
]);
/** The event body after validation — the only shape ingestion ever sees. */
export type ValidatedTrackingPayload = z.infer<typeof trackingPayloadSchema>;
/** The payload with its path and query string cut to what the events table keeps. */
export function truncateUrlForStorage(payload: ValidatedTrackingPayload): ValidatedTrackingPayload {
const { pathname, querystring } = payload;
if ((pathname?.length ?? 0) <= MAX_URL_PART_LENGTH && (querystring?.length ?? 0) <= MAX_URL_PART_LENGTH) {
return payload;
}
return {
...payload,
pathname: pathname && truncateString(pathname, MAX_URL_PART_LENGTH),
querystring: querystring && truncateString(querystring, MAX_URL_PART_LENGTH),
};
}