The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
import {
DATE_RANGE_INTERVAL_PRESETS,
EVENT_TYPES,
OLD_ANALYTICS_ENDPOINTS,
OLD_TO_NEW_ANALYTICS_ENDPOINTS,
VALID_ANALYTICS_ENDPOINTS,
} from "@/lib/analytics/constants";
import { sanitizeTimezone } from "@/lib/analytics/utils/sanitize-timezone";
import {
DEFAULT_PAGINATION_LIMIT,
DUB_FOUNDING_DATE,
capitalize,
formatDate,
parseFilterValue,
} from "@dub/utils";
import * as z from "zod/v4";
import { booleanQuerySchema, getPaginationQuerySchema } from "./misc";
import { parseDateSchema } from "./utils";
const analyticsEvents = z
.enum([...EVENT_TYPES, "composite"], {
error: "Invalid event type. Valid event types are: clicks, leads, sales",
})
.default("clicks")
.meta({
description:
"The type of event to retrieve analytics for. Defaults to `clicks`.",
example: "leads",
});
const analyticsGroupBy = z
.enum(VALID_ANALYTICS_ENDPOINTS, {
error: `Invalid type value. Valid values are: ${VALID_ANALYTICS_ENDPOINTS.filter((v) => v !== "trigger").join(", ")}.`,
})
.default("count")
.describe(
"The parameter to group the analytics data points by. Defaults to `count` if undefined.",
);
const oldAnalyticsEndpoints = z
.enum(OLD_ANALYTICS_ENDPOINTS, {
error: `Invalid type value. Valid values are: ${OLD_ANALYTICS_ENDPOINTS.join(", ")}`,
})
.transform((v) => OLD_TO_NEW_ANALYTICS_ENDPOINTS[v] || v);
// For backwards compatibility
export const analyticsPathParamsSchema = z.object({
eventType: analyticsEvents
.removeDefault()
.or(oldAnalyticsEndpoints)
.optional(),
endpoint: oldAnalyticsEndpoints.optional(),
});
// Query schema for GET /analytics and GET /events endpoints
export const analyticsQuerySchema = z.object({
event: analyticsEvents,
groupBy: analyticsGroupBy,
domain: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The domain to filter analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `dub.co`, `dub.co,google.com`, `-spam.com`.",
)
.meta({ example: "dub.co" }),
key: z
.string()
.optional()
.describe(
"The slug of the short link to retrieve analytics for. Must be used along with the corresponding `domain` of the short link to fetch analytics for a specific short link.",
),
linkId: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The unique ID of the link to retrieve analytics for." +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `link_123`, `link_123,link_456`, `-link_789`.",
),
externalId: z
.string()
.optional()
.describe(
"The ID of the link in the your database. Must be prefixed with 'ext_' when passed as a query parameter.",
),
tenantId: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The ID of the tenant that created the link inside your system. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `tenant_123`, `tenant_123,tenant_456`, `-tenant_789`.",
),
tagId: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The tag ID to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `tag_123`, `tag_123,tag_456`, `-tag_789`.",
),
folderId: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The folder ID to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `folder_123`, `folder_123,folder_456`, `-folder_789`. " +
"If not provided, return analytics for all links.",
),
customerId: z
.string()
.optional()
.describe("The ID of the customer to retrieve analytics for."),
interval: z
.enum(DATE_RANGE_INTERVAL_PRESETS)
.optional()
.describe(
"The interval to retrieve analytics for. If undefined, defaults to 24h.",
),
start: parseDateSchema
.refine((value: Date) => value >= DUB_FOUNDING_DATE, {
message: `The start date cannot be earlier than ${formatDate(DUB_FOUNDING_DATE)}.`,
})
.optional()
.describe(
"The start date and time when to retrieve analytics from. If set, takes precedence over `interval`.",
),
end: parseDateSchema
.optional()
.describe(
"The end date and time when to retrieve analytics from. If not provided, defaults to the current date. If set along with `start`, takes precedence over `interval`.",
),
timezone: z
.string()
.optional()
.overwrite((v) => (v === undefined ? undefined : sanitizeTimezone(v)))
.describe(
"The IANA time zone code for aligning timeseries granularity (e.g. America/New_York). Defaults to UTC.",
)
.meta({ example: "America/New_York", default: "UTC" }),
// more filter facets
country: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The country to retrieve analytics for. Must be passed as a 2-letter ISO 3166-1 country code (see https://d.to/geo). " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `US`, `US,BR,FR`, `-US`.",
),
city: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The city to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `New York`, `New York,London`, `-New York`.",
),
region: z
.string()
.optional()
.describe(
"The ISO 3166-2 region code to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `NY`, `NY,CA`, `-NY`.",
),
continent: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The continent to retrieve analytics for. Valid values: AF, AN, AS, EU, NA, OC, SA. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `NA`, `NA,EU`, `-AS`.",
),
device: z
.string()
.optional()
.transform((v) => {
if (!v) return undefined;
// Capitalize each value
const parsed = parseFilterValue(v);
if (!parsed) return undefined;
return {
...parsed,
values: parsed.values
.map((val) => capitalize(val))
.filter(Boolean) as string[],
};
})
.describe(
"The device to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `Desktop`, `Mobile,Tablet`, `-Mobile`.",
),
browser: z
.string()
.optional()
.transform((v) => {
if (!v) return undefined;
const parsed = parseFilterValue(v);
if (!parsed) return undefined;
return {
...parsed,
values: parsed.values
.map((val) => capitalize(val))
.filter(Boolean) as string[],
};
})
.describe(
"The browser to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `Chrome`, `Chrome,Firefox,Safari`, `-IE`.",
),
os: z
.string()
.optional()
.transform((v) => {
if (!v) return undefined;
const parsed = parseFilterValue(v);
if (!parsed) return undefined;
return {
...parsed,
values: parsed.values
.map((val) => (val === "iOS" ? "iOS" : capitalize(val)))
.filter(Boolean) as string[],
};
})
.describe(
"The OS to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `Windows`, `Mac,Windows,Linux`, `-Windows`.",
),
trigger: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The trigger to retrieve analytics for. Valid values: qr, link, pageview. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `qr`, `qr,link`, `-qr`. " +
"If undefined, returns all trigger types.",
),
eventName: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The conversion event name to retrieve analytics for. Only available for lead and sale events. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `Sign up`, `Sign up,Purchase`, `-Sign up`.",
),
referer: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The referer hostname to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `google.com`, `google.com,twitter.com`, `-facebook.com`.",
),
refererUrl: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The full referer URL to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `https://google.com`, `https://google.com,https://twitter.com`, `-https://spam.com`.",
),
url: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The destination URL to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `https://example.com`, `https://example.com,https://other.com`, `-https://spam.com`.",
),
utm_source: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The UTM source to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `google`, `google,twitter`, `-spam`.",
),
utm_medium: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The UTM medium to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `cpc`, `cpc,social`, `-email`.",
),
utm_campaign: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The UTM campaign to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`). " +
"Examples: `summer_sale`, `summer_sale,winter_sale`, `-old_campaign`.",
),
utm_term: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The UTM term to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).",
),
utm_content: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"The UTM content to retrieve analytics for. " +
"Supports advanced filtering: single value, multiple values (comma-separated), or exclusion (prefix with `-`).",
),
root: booleanQuerySchema
.optional()
.describe(
"Filter for root domains. If true, filter for domains only. If false, filter for links only. If undefined, return both.",
),
saleType: z
.enum(["new", "recurring"])
.optional()
.describe(
"Filter sales by type: 'new' for first-time purchases, 'recurring' for repeat purchases. If undefined, returns both.",
),
query: z
.string()
.max(10000)
.optional()
.describe(
"Search the events by a custom metadata value. Only available for lead and sale events. " +
"Examples: `metadata['key']:'value'`",
),
// deprecated fields
tagIds: z
.string()
.optional()
.transform(parseFilterValue)
.describe(
"Deprecated: Use `tagId` instead. The tag IDs to retrieve analytics for.",
)
.meta({ deprecated: true }),
qr: booleanQuerySchema
.optional()
.describe(
"Deprecated: Use the `trigger` field instead. Filter for QR code scans. If true, filter for QR codes only. If false, filter for links only. If undefined, return both.",
)
.meta({ deprecated: true }),
});
/**
* Parse analytics/events query parameters with backward compatibility
* Converts deprecated multiple value fields (tagIds) to singular fields (tagId)
*/
export function parseAnalyticsQuery(searchParams: Record<string, string>) {
const data = analyticsQuerySchema.parse(searchParams);
if (data.tagIds && !data.tagId) {
data.tagId = data.tagIds;
}
return data;
}
export function parseEventsQuery(searchParams: Record<string, string>) {
const data = eventsQuerySchema.parse(searchParams);
if (data.tagIds && !data.tagId) {
data.tagId = data.tagIds;
}
return data;
}
// Analytics filter params for Tinybird endpoints
export const analyticsFilterTB = z.object({
eventType: analyticsEvents,
workspaceId: z.string().optional(),
groupBy: analyticsGroupBy,
domain: z
.union([z.string(), z.array(z.string())])
.transform((v) => (Array.isArray(v) ? v : v.split(",")))
.optional()
.describe("The domain(s) to retrieve analytics for."),
domainOperator: z.enum(["IN", "NOT IN"]).optional(),
linkId: z
.union([z.string(), z.array(z.string())])
.transform((v) => (Array.isArray(v) ? v : v.split(",")))
.optional()
.describe(
"The link IDs to retrieve analytics for (with operator support).",
),
linkIdOperator: z.enum(["IN", "NOT IN"]).optional(),
tenantId: z
.union([z.string(), z.array(z.string())])
.transform((v) => (Array.isArray(v) ? v : v.split(",")))
.optional()
.describe(
"The tenant ID(s) to retrieve analytics for (with operator support).",
),
tenantIdOperator: z.enum(["IN", "NOT IN"]).optional(),
tagId: z
.union([z.string(), z.array(z.string())])
.transform((v) => (Array.isArray(v) ? v : v.split(",")))
.optional()
.describe(
"The tag ID(s) to retrieve analytics for (with operator support).",
),
tagIdOperator: z.enum(["IN", "NOT IN"]).optional(),
folderId: z
.union([z.string(), z.array(z.string())])
.transform((v) => (Array.isArray(v) ? v : v.split(",")))
.optional()
.describe(
"The folder ID(s) to retrieve analytics for (with operator support).",
),
folderIdOperator: z.enum(["IN", "NOT IN"]).optional(),
customerId: z.string().optional(),
start: z.string(),
end: z.string(),
granularity: z.enum(["minute", "hour", "day", "month"]).optional(),
timezone: z.string().optional(),
// Region is a special case - it's the subdivision part of a region code
region: z.string().optional(),
root: z
.union([z.string(), z.boolean()])
.transform((v) => {
if (typeof v === "boolean") return v;
return v === "true" || v === "1" || v === "yes";
})
.optional()
.describe(
"Filter for root domain links. True = root only, false = links only. Single value (no operator).",
),
saleType: z
.enum(["new", "recurring"])
.optional()
.describe(
"Filter sales by type: 'new' or 'recurring'. Single value only (no operator).",
),
// All dimensional filters now go through the JSON filters parameter
filters: z
.string()
.optional()
.describe("JSON array of advanced filters with operators (IN, NOT IN)."),
});
export const eventsFilterTB = analyticsFilterTB
.omit({ granularity: true, timezone: true })
.and(
z.object({
offset: z.coerce.number().default(0),
limit: z.coerce.number().default(DEFAULT_PAGINATION_LIMIT),
order: z.enum(["asc", "desc"]).default("desc"),
sortBy: z.enum(["timestamp"]).default("timestamp"),
}),
);
const sortOrder = z
.enum(["asc", "desc"])
.default("desc")
.optional()
.describe("The sort order. The default is `desc`.");
const eventsPaginationQuerySchema = getPaginationQuerySchema({
pageSize: DEFAULT_PAGINATION_LIMIT,
maxPageSize: 1000,
});
export const eventsQuerySchema = analyticsQuerySchema
.omit({ groupBy: true })
.extend({
event: z
.enum(EVENT_TYPES)
.default("clicks")
.describe(
"The type of event to retrieve analytics for. Defaults to 'clicks'.",
),
page: eventsPaginationQuerySchema.page.default(1),
limit: eventsPaginationQuerySchema.pageSize,
sortOrder,
sortBy: z
.enum(["timestamp"])
.optional()
.default("timestamp")
.describe("The field to sort the events by. The default is `timestamp`."),
order: sortOrder
.describe("DEPRECATED. Use `sortOrder` instead.")
.meta({ deprecated: true }),
});