Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

ralph(M7-002): event + profile + group modules into core

ralphf1573b1acad4
diff --git a/apps/api/src/controllers/profile.controller.ts b/apps/api/src/controllers/profile.controller.ts
index f32adf635..cc97e4c69 100644
--- a/apps/api/src/controllers/profile.controller.ts
+++ b/apps/api/src/controllers/profile.controller.ts
@@ -1,11 +1,22 @@
-import { getGeoLocation, parseUserAgent } from '@openpanel/core';
-import { getProfileById, upsertProfile } from '@openpanel/db';
+import {
+ type AdjustProfilePropertyResult,
+ adjustProfileProperty,
+ getGeoLocation,
+ identifyProfile,
+ parseUserAgent,
+} from '@openpanel/core';
import type {
DeprecatedIncrementProfilePayload,
DeprecatedUpdateProfilePayload,
} from '@openpanel/validation';
import type { FastifyReply, FastifyRequest } from 'fastify';
-import { assocPath, pathOr } from 'ramda';
+
+// Dissolved into @openpanel/core's profile module (M7-002): the upsert and
+// the increment/decrement arithmetic moved to profile.service.ts's
+// `identifyProfile` / `adjustProfileProperty`. These controllers stay
+// (DELEGATE PATTERN) — they are the live Fastify handlers, thin wrappers
+// resolving `request.client` and translating the result into a Fastify
+// reply, same as import.controller.ts.
export async function updateProfile(
request: FastifyRequest<{
@@ -18,36 +29,30 @@ export async function updateProfile(
if (!projectId) {
return reply.status(400).send('No projectId');
}
- const ip = request.clientIp;
- const ua = request.headers['user-agent'];
- const uaInfo = parseUserAgent(ua, payload.properties);
- const geo = await getGeoLocation(ip);
+ const userAgent = parseUserAgent(
+ request.headers['user-agent'],
+ payload.properties
+ );
+ const geo = await getGeoLocation(request.clientIp);
- await upsertProfile({
- ...payload,
- id: payload.profileId,
- isExternal: true,
- projectId,
- properties: {
- ...(payload.properties ?? {}),
- country: geo.country,
- city: geo.city,
- region: geo.region,
- longitude: geo.longitude,
- latitude: geo.latitude,
- os: uaInfo.os,
- os_version: uaInfo.osVersion,
- browser: uaInfo.browser,
- browser_version: uaInfo.browserVersion,
- device: uaInfo.device,
- brand: uaInfo.brand,
- model: uaInfo.model,
- },
- });
+ await identifyProfile(projectId, payload, { geo, userAgent });
reply.status(202).send(payload.profileId);
}
+function sendAdjusted(
+ reply: FastifyReply,
+ result: AdjustProfilePropertyResult
+) {
+ if (result.status === 'not-found') {
+ return reply.status(404).send('Not found');
+ }
+ if (result.status === 'not-a-number') {
+ return reply.status(400).send('Not number');
+ }
+ return reply.status(202).send(result.profileId);
+}
+
export async function incrementProfileProperty(
request: FastifyRequest<{
Body: DeprecatedIncrementProfilePayload;
@@ -60,34 +65,12 @@ export async function incrementProfileProperty(
return reply.status(400).send('No projectId');
}
- const profile = await getProfileById(profileId, projectId);
- if (!profile) {
- return reply.status(404).send('Not found');
- }
-
- const parsed = Number.parseInt(
- pathOr<string>('0', property.split('.'), profile.properties),
- 10
- );
-
- if (Number.isNaN(parsed)) {
- return reply.status(400).send('Not number');
- }
-
- profile.properties = assocPath(
- property.split('.'),
- parsed + value,
- profile.properties
- );
-
- await upsertProfile({
- id: profile.id,
- projectId,
- properties: profile.properties,
- isExternal: true,
+ const result = await adjustProfileProperty(projectId, {
+ profileId,
+ property,
+ delta: value,
});
-
- reply.status(202).send(profile.id);
+ return sendAdjusted(reply, result);
}
export async function decrementProfileProperty(
@@ -102,32 +85,10 @@ export async function decrementProfileProperty(
return reply.status(400).send('No projectId');
}
- const profile = await getProfileById(profileId, projectId);
- if (!profile) {
- return reply.status(404).send('Not found');
- }
-
- const parsed = Number.parseInt(
- pathOr<string>('0', property.split('.'), profile.properties),
- 10
- );
-
- if (Number.isNaN(parsed)) {
- return reply.status(400).send('Not number');
- }
-
- profile.properties = assocPath(
- property.split('.'),
- parsed - value,
- profile.properties
- );
-
- await upsertProfile({
- id: profile.id,
- projectId,
- properties: profile.properties,
- isExternal: true,
+ const result = await adjustProfileProperty(projectId, {
+ profileId,
+ property,
+ delta: -value,
});
-
- reply.status(202).send(profile.id);
+ return sendAdjusted(reply, result);
}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index e8a95b01e..b886c06b2 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -302,6 +302,91 @@ export {
// module map: email owns "C"); @openpanel/constants keeps a re-export shim.
export type { EmailCategory } from './modules/email/email.constants';
export { emailCategories } from './modules/email/email.constants';
+// Dissolved from @openpanel/db's services/event.service.ts, profile.service.ts
+// and group.service.ts, plus the query/mutation bodies packages/trpc's
+// event/profile/group routers held inline and apps/api's profile controller
+// (M7-002, ADR-008's module map: event "R,S", profile "R,H,S", group
+// "R,S,C") — packages/trpc's routers, apps/api's export controller, is-bot
+// hook and profile controller, apps/worker's incoming-event job and the
+// assistant/mcp tools call these directly, the same way V1 reaches every
+// other dissolved service here. packages/db keeps re-export shims for all
+// three files (the buffers' row types and cohort.service's profileSearchSql
+// still resolve through them).
+export type {
+ EventListSelect,
+ GetEventListOptions,
+ IClickhouseBotEvent,
+ IClickhouseEvent,
+ IEventColumn,
+ IImportedEvent,
+ IServiceBotEvent,
+ IServiceCreateBotEventPayload,
+ IServiceCreateEventPayload,
+ IServiceCreateEventPayloadWithId,
+ IServiceEvent,
+ IServiceEventMinimal,
+ IServiceImportedEventPayload,
+ IServicePage,
+ QueryEventsInput,
+} from './modules/event/event.service';
+export {
+ createBotEvent,
+ createEvent,
+ EVENT_COLUMNS,
+ getBotEventsPage,
+ getConversionEventNames,
+ getConversionListPage,
+ getEventById,
+ getEventDetails,
+ getEventList,
+ getEventListPage,
+ getEventMetas,
+ getEventMetasCached,
+ getEventPropertyValuesCore,
+ getEvents,
+ getEventsCount,
+ getTopEventNames,
+ getTopOrigins,
+ getTopPages,
+ listEventNamesCore,
+ listEventPropertiesCore,
+ queryEventsCore,
+ transformEvent,
+ transformMinimalEvent,
+ transformSessionToEvent,
+ updateEventMeta,
+} from './modules/event/event.service';
+export type {
+ GetGroupListOptions,
+ GetGroupMemberProfilesOptions,
+ IServiceGroup,
+ IServiceGroupStats,
+ IServiceUpsertGroup,
+} from './modules/group/group.service';
+export {
+ createGroup,
+ deleteGroup,
+ findGroupsCore,
+ getGroupActivity,
+ getGroupById,
+ getGroupCore,
+ getGroupList,
+ getGroupListCount,
+ getGroupListPage,
+ getGroupMemberGrowth,
+ getGroupMemberProfiles,
+ getGroupMemberProfilesPage,
+ getGroupMetrics,
+ getGroupMostEvents,
+ getGroupPopularRoutes,
+ getGroupPropertyKeys,
+ getGroupStats,
+ getGroupsByIds,
+ getGroupTypes,
+ listGroupTypesCore,
+ updateGroup,
+ upsertGroup,
+} from './modules/group/group.service';
// Dissolved from @openpanel/db's src/gsc.ts + services/gsc.service.ts
// (M5-002) — apps/worker's gsc job file, apps/api's gsc OAuth callback
// controller and packages/trpc's gsc router call these directly, the same
@@ -460,6 +545,42 @@ export {
updateOrganization,
updateOrganizationMemberAccess,
} from './modules/organization/organization.service';
+export type {
+ AdjustProfilePropertyResult,
+ FindProfilesInput,
+ GetProfileListOptions,
+ IClickhouseProfile,
+ IdentifyProfileInput,
+ IProfileMetrics,
+ IServiceProfile,
+ IServiceUpsertProfile,
+ ProfileRequestContext,
+} from './modules/profile/profile.service';
+export {
+ adjustProfileProperty,
+ findProfilesCore,
+ getPowerUsers,
+ getProfileActivity,
+ getProfileById,
+ getProfileList,
+ getProfileListCount,
+ getProfileListPage,
+ getProfileMetrics,
+ getProfileMetricsCore,
+ getProfileMostEvents,
+ getProfilePopularRoutes,
+ getProfilePropertyKeys,
+ getProfilePropertyKeysCached,
+ getProfilePropertyNames,
+ getProfileSessionsCore,
+ getProfiles,
+ getProfilesCached,
+ getProfileValues,
+ getProfileWithEvents,
+ identifyProfile,
+ transformProfile,
+ upsertProfile,
+} from './modules/profile/profile.service';
// Dissolved from @openpanel/db's services/project.service.ts (M6-002) —
// packages/trpc's project router, apps/api's manage controller and several
// core modules' `src/access.ts` call these directly, the same way V1
diff --git a/packages/core/src/modules/cohort/cohort.jobs.test.ts b/packages/core/src/modules/cohort/cohort.jobs.test.ts
index 7f3af1b8b..bbd2fb0d2 100644
--- a/packages/core/src/modules/cohort/cohort.jobs.test.ts
+++ b/packages/core/src/modules/cohort/cohort.jobs.test.ts
@@ -39,6 +39,9 @@ function stubJobCtx(cohort: Partial<CohortService>, jobName = 'test'): JobCtx {
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
diff --git a/packages/core/src/modules/event/event.rpc.test.ts b/packages/core/src/modules/event/event.rpc.test.ts
new file mode 100644
index 000000000..e77c7f68a
--- /dev/null
+++ b/packages/core/src/modules/event/event.rpc.test.ts
@@ -0,0 +1,77 @@
+// Only the "is anyone logged in" boundary is exercised here — no database.
+// The access-check + query bodies ride on @openpanel/db (lazy-loaded, see
+// event.service.ts's header); wiring this router end-to-end against a real
+// ClickHouse is P6's (protectedProcedure) job — see event.rpc.ts's header.
+// Same shape as session.rpc.test.ts.
+
+import { expect, test } from 'bun:test';
+import { stubHttpCtx } from '../../../test/rpc-fixtures';
+import { makeTrpcContext } from '../../rpc/base';
+import type { CookieOptions } from '../../shared/cookie';
+import { eventRouter } from './event.rpc';
+
+const COOKIE_OPTIONS: CookieOptions = {
+ domain: '.openpanel.dev',
+ secure: true,
+ sameSite: 'lax',
+ httpOnly: true,
+ path: '/',
+};
+
+const EMPTY_SESSION = { session: null, user: null, userId: null };
+const PROJECT = { projectId: 'proj_1' };
+const REF = { id: 'evt_1', projectId: 'proj_1' };
+const WINDOW = { projectId: 'proj_1', range: '7d', interval: 'day' } as const;
+
+async function anonCaller() {
+ const { ctx } = stubHttpCtx({}, EMPTY_SESSION);
+ const trpcCtx = await makeTrpcContext(ctx, new Headers(), {
+ cookieOptions: COOKIE_OPTIONS,
+ });
+ return eventRouter.createCaller(trpcCtx);
+}
+
+const UNAUTHORIZED = { code: 'UNAUTHORIZED' };
+
+test('every query rejects an unauthenticated caller before touching a database', async () => {
+ const caller = await anonCaller();
+ await expect(caller.byId(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.details(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.events(PROJECT)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.conversionNames(PROJECT)).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(caller.conversions(PROJECT)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.pages(WINDOW)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.pagesTimeseries(WINDOW)).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(caller.previousPages(WINDOW)).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(
+ caller.pageTimeseries({ ...WINDOW, origin: 'https://a.io', path: '/' })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.origin(PROJECT)).rejects.toMatchObject(UNAUTHORIZED);
+});
+
+// V1 let anonymous callers in on the mere existence of a ShareOverview row;
+// ADR-011 §9 rules that a bug.
+test('bots rejects an unauthenticated caller (ADR-011: no anonymous share branch)', async () => {
+ const caller = await anonCaller();
+ await expect(caller.bots(PROJECT)).rejects.toMatchObject(UNAUTHORIZED);
+});
+
+test('updateEventMeta rejects an unauthenticated caller before touching Postgres', async () => {
+ const caller = await anonCaller();
+ await expect(
+ caller.updateEventMeta({ ...PROJECT, name: 'signup', conversion: true })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+});
+
+test('events rejects a malformed filter at the input boundary', async () => {
+ const caller = await anonCaller();
+ await expect(
+ caller.events({ ...PROJECT, filters: [{ bogus: true }] as never })
+ ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+});
diff --git a/packages/core/src/modules/event/event.rpc.ts b/packages/core/src/modules/event/event.rpc.ts
new file mode 100644
index 000000000..3de8312d9
--- /dev/null
+++ b/packages/core/src/modules/event/event.rpc.ts
@@ -0,0 +1,294 @@
+// Ported from packages/trpc/src/routers/event.ts (M7-002).
+//
+// Same arrangement as session.rpc.ts: V1's `protectedProcedure` stack lands
+// with auth (P6), so until then each procedure does its own "is anyone logged
+// in" + `requireProjectAccess` off the `projectId` input (`read` for queries,
+// `write` for `updateEventMeta`). packages/trpc's event router delegates its
+// handler bodies onto `./event.service` while keeping V1's own
+// `protectedProcedure` stack.
+//
+// `bots` was V1's only `publicProcedure` here (anonymous callers were let in
+// when a share-overview row existed); ADR-011 makes it protected.
+//
+// `pages` / `pagesTimeseries` / `previousPages` / `pageTimeseries` read from
+// `pagesService`, which the overview module owns (its own task) — the bodies
+// are ported verbatim and reach it lazily through `@openpanel/db`.
+
+import {
+ zChartEventFilter,
+ zRange,
+ zTimeInterval,
+} from '@openpanel/validation';
+import { z } from 'zod';
+import { createTRPCRouter, procedure } from '../../rpc/base';
+import { TRPCAccessError, TRPCNotFoundError } from '../../rpc/errors';
+import {
+ getBotEventsPage,
+ getConversionEventNames,
+ getConversionListPage,
+ getEventById,
+ getEventDetails,
+ getEventListPage,
+ getTopOrigins,
+ updateEventMeta,
+} from './event.service';
+
+const DEFAULT_BOTS_LIMIT = 8;
+
+const zEventRef = z.object({
+ id: z.string(),
+ projectId: z.string(),
+ createdAt: z.date().optional(),
+});
+
+const zChartWindow = z.object({
+ projectId: z.string(),
+ range: zRange,
+ interval: zTimeInterval,
+});
+
+function loadAccessChecks() {
+ return import('./src/access');
+}
+
+function loadPagesRuntime() {
+ return Promise.all([
+ import('@openpanel/db/src/services/organization.service'),
+ import('@openpanel/db/src/services/date.service'),
+ import('@openpanel/db/src/services/pages.service'),
+ ]).then(
+ ([
+ { getSettingsForProject },
+ { getChartStartEndDate },
+ { pagesService },
+ ]) => ({
+ getSettingsForProject,
+ getChartStartEndDate,
+ pagesService,
+ })
+ );
+}
+
+function requireLogin(userId: string | null | undefined): string {
+ if (!userId) {
+ throw new TRPCAccessError('Not authenticated');
+ }
+ return userId;
+}
+
+async function requireAccess(
+ userId: string,
+ projectId: string,
+ level: 'read' | 'write'
+) {
+ const { requireProjectAccess } = await loadAccessChecks();
+ await requireProjectAccess({ userId, projectId, level });
+}
+
+function formatClickhouseDateTime(date: Date): string {
+ return date.toISOString().slice(0, 19).replace('T', ' ');
+}
+
+export const eventRouter = createTRPCRouter({
+ updateEventMeta: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ name: z.string(),
+ icon: z.string().optional(),
+ color: z.string().optional(),
+ conversion: z.boolean().optional(),
+ })
+ )
+ .mutation(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'write');
+
+ return updateEventMeta(input);
+ }),
+
+ byId: procedure.input(zEventRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ const event = await getEventById(input);
+ if (!event) {
+ throw new TRPCNotFoundError('Event not found');
+ }
+ return event;
+ }),
+
+ details: procedure.input(zEventRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ const details = await getEventDetails(input);
+ if (!details) {
+ throw new TRPCNotFoundError('Event not found');
+ }
+ return details;
+ }),
+
+ events: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ profileId: z.string().nullish(),
+ sessionId: z.string().nullish(),
+ groupId: z.string().nullish(),
+ cohortId: z.string().nullish(),
+ cursor: z.string().nullish(),
+ filters: z.array(zChartEventFilter).default([]),
+ startDate: z.date().nullish(),
+ endDate: z.date().nullish(),
+ events: z.array(z.string()).nullish(),
+ columnVisibility: z.record(z.string(), z.boolean()).nullish(),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getEventListPage(input);
+ }),
+
+ conversionNames: procedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getConversionEventNames(input.projectId);
+ }),
+
+ conversions: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ cursor: z.string().nullish(),
+ startDate: z.date().nullish(),
+ endDate: z.date().nullish(),
+ events: z.array(z.string()).nullish(),
+ columnVisibility: z.record(z.string(), z.boolean()).nullish(),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getConversionListPage(input);
+ }),
+
+ bots: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ cursor: z.number().optional(),
+ limit: z.number().default(DEFAULT_BOTS_LIMIT),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getBotEventsPage(input);
+ }),
+
+ pages: procedure
+ .input(
+ zChartWindow.extend({
+ cursor: z.number().optional(),
+ take: z.number().min(1).optional(),
+ search: z.string().optional(),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ const { getSettingsForProject, getChartStartEndDate, pagesService } =
+ await loadPagesRuntime();
+ const { timezone } = await getSettingsForProject(input.projectId);
+ const { startDate, endDate } = getChartStartEndDate(input, timezone);
+ return pagesService.getTopPages({
+ projectId: input.projectId,
+ startDate,
+ endDate,
+ timezone,
+ search: input.search,
+ limit: input.take,
+ });
+ }),
+
+ pagesTimeseries: procedure
+ .input(zChartWindow)
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ const { getSettingsForProject, getChartStartEndDate, pagesService } =
+ await loadPagesRuntime();
+ const { timezone } = await getSettingsForProject(input.projectId);
+ const { startDate, endDate } = getChartStartEndDate(input, timezone);
+ return pagesService.getPageTimeseries({
+ projectId: input.projectId,
+ startDate,
+ endDate,
+ timezone,
+ interval: input.interval,
+ });
+ }),
+
+ previousPages: procedure.input(zChartWindow).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ const { getSettingsForProject, getChartStartEndDate, pagesService } =
+ await loadPagesRuntime();
+ const { timezone } = await getSettingsForProject(input.projectId);
+ const { startDate, endDate } = getChartStartEndDate(input, timezone);
+
+ const startMs = new Date(startDate).getTime();
+ const endMs = new Date(endDate).getTime();
+ const duration = endMs - startMs;
+ const previousEnd = new Date(startMs - 1);
+ const previousStart = new Date(previousEnd.getTime() - duration);
+
+ return pagesService.getTopPages({
+ projectId: input.projectId,
+ startDate: formatClickhouseDateTime(previousStart),
+ endDate: formatClickhouseDateTime(previousEnd),
+ timezone,
+ });
+ }),
+
+ pageTimeseries: procedure
+ .input(zChartWindow.extend({ origin: z.string(), path: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ const { getSettingsForProject, getChartStartEndDate, pagesService } =
+ await loadPagesRuntime();
+ const { timezone } = await getSettingsForProject(input.projectId);
+ const { startDate, endDate } = getChartStartEndDate(input, timezone);
+ return pagesService.getPageTimeseries({
+ projectId: input.projectId,
+ startDate,
+ endDate,
+ timezone,
+ interval: input.interval,
+ filterOrigin: input.origin,
+ filterPath: input.path,
+ });
+ }),
+
+ origin: procedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getTopOrigins(input.projectId);
+ }),
+});
diff --git a/packages/core/src/modules/event/event.service.ts b/packages/core/src/modules/event/event.service.ts
new file mode 100644
index 000000000..dd3d4eaac
--- /dev/null
+++ b/packages/core/src/modules/event/event.service.ts
@@ -0,0 +1,1322 @@
+// Ported from packages/db/src/services/event.service.ts and the query bodies
+// of packages/trpc/src/routers/event.ts (M7-002). The db file is now a
+// re-export shim over this one, so @openpanel/db importers (packages/trpc,
+// apps/api's export controller and bot hook, the buffers' types,
+// notification.service, the mcp/assistant tools) keep working while V1 runs
+// (DELEGATE PATTERN).
+//
+// Every query is a `sql` fragment (src/event.sql.ts), converted one at a time
+// with a result-set proof each, per ADR-013. The two filter compilers
+// (`getEventFiltersWhereClause`, `buildFilterWhere`) are NOT converted here —
+// they are shared and out of this task's scope; src/filter-clauses.ts is the
+// one bridge.
+//
+// Not ported: V1's `EventService.query` / `EventService.getList` (a clix
+// builder over events + profiles + sessions) — nothing in the repo calls
+// them; `eventService.getById` is `getEventById` below. `GetEventListOptions.
+// custom(sb)` — its only caller (event.conversions) is the typed
+// `conversionNames` option instead, since there is no builder to hand out.
+//
+// db/ch/buffer access is LAZY (`load*` below) for the reason
+// insight.service.ts's header gives: constructing @openpanel/db's clients at
+// import time spawns a pino-pretty worker per `bun test --isolate` file.
+
+import { DateTime, toDots } from '@openpanel/common';
+import type { SqlFragment } from '@openpanel/db/src/clickhouse/sql';
+import type { EventMeta, Prisma } from '@openpanel/db/src/prisma-client';
+import { cacheable } from '@openpanel/redis';
+import type { IChartEventFilter } from '@openpanel/validation';
+import { clone, mergeDeepRight, uniq } from 'ramda';
+import type { ServiceDeps } from '../../services';
+import {
+ getProfileById,
+ getProfilesCached,
+ type IServiceProfile,
+ type IServiceUpsertProfile,
+ upsertProfile,
+} from '../profile/profile.service';
+import type { IClickhouseSession } from '../session/session.service';
+import { convertClickhouseDateToJs, formatClickhouseDate } from './src/dates';
+import {
+ botEventsCountQuery,
+ botEventsQuery,
+ type EventFilterJoins,
+ type EventListColumn,
+ type EventListQuery,
+ type EventsCountQuery,
+ eventByIdQuery,
+ eventListQuery,
+ eventPropertiesQuery,
+ eventPropertyValuesQuery,
+ eventsCountQuery,
+ NO_FILTER_JOINS,
+ type QueryEventsEqualityColumn,
+ queryEventsQuery,
+ topEventNamesQuery,
+ topOriginsQuery,
+ topPagesQuery,
+} from './src/event.sql';
+import type { CompiledFilterClauses } from './src/filter-clauses';
+
+export {
+ EVENT_LIST_COLUMNS,
+ QUERY_EVENTS_EQUALITY_COLUMNS,
+} from './src/event.sql';
+
+const EVENT_METAS_CACHE_SECONDS = 60 * 5;
+const TOP_EVENT_NAMES_CACHE_SECONDS = 60 * 10;
+const EVENT_LIST_DEFAULT_LOOKBACK_DAYS = 0.5;
+const EVENT_LIST_MAX_LOOKBACK_DAYS_DEFAULT = 365 * 5;
+const EVENT_LIST_MAX_LOOKBACK_DAYS_ENV = 'EVENT_LIST_MAX_LOOKBACK_DAYS';
+const QUERY_EVENTS_DEFAULT_LIMIT = 20;
+const CLICKHOUSE_DATETIME_FORMAT = 'yyyy-MM-dd HH:mm:ss.SSS';
+const MASK_CHARACTER = '*';
+const MASK_VISIBLE_PREFIX = 4;
+const MASK_MIN_LENGTH_FOR_PREFIX = 8;
+const MASKABLE_CHARACTERS = /(\w)/g;
+const EVENTS_ALIAS = 'e';
+const PROFILE_FILTER_PREFIX = 'profile.';
+const GROUP_FILTER_PREFIX = 'group.';
+const LOCALHOST_ORIGIN_MARKER = 'localhost:';
+
+// clix always sent `session_timezone: 'UTC'`; the queries converted from clix
+// keep sending it so their result sets stay identical.
+const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;
+
+const QUERY_EVENTS_FILTER_TARGET = {
+ selfTable: 'events',
+ profileIdExpr: 'profile_id',
+ groupsExpr: 'groups',
+} as const;
+
+function loadChClient() {
+ return import('@openpanel/db/src/clickhouse/client');
+}
+
+function loadDb() {
+ return import('@openpanel/db/src/prisma-client').then((m) => m.db);
+}
+
+function loadBuffers() {
+ return import('@openpanel/db/src/buffers');
+}
+
+// Lazy for the same reason subscription.service.ts's is: core tests that
+// partially mock `@openpanel/redis` (no `getCache`) reach this module through
+// @openpanel/db's re-export shims and the core barrel.
+function loadCache() {
+ return import('@openpanel/redis').then((m) => m.getCache);
+}
+
+function loadEventFilterCompiler() {
+ return import('@openpanel/db/src/services/chart.service');
+}
+
+function loadFilterCompiler() {
+ return import('@openpanel/db/src/services/filter-where.service');
+}
+
+function loadLookback() {
+ return import('@openpanel/db/src/services/lookback');
+}
+
+// Lazy: session.service → session-end → this module is a static chain, and a
+// static edge back would be a plain import cycle evaluated in the wrong order.
+// Keep this the ONLY dynamic edge on that loop — a second one (e.g. session-end
+// lazily importing this module) panics rolldown when apps/worker bundles the
+// workspace (module_finalizers "no entry found for key").
+function loadSessionService() {
+ return import('../session/session.service');
+}
+
+function loadDateService() {
+ return import('@openpanel/db/src/services/date.service');
+}
+
+export type IImportedEvent = Omit<
+ IClickhouseEvent,
+ 'properties' | 'profile' | 'meta' | 'imported_at'
+> & {
+ properties: Record<string, unknown>;
+};
+
+export interface IServicePage {
+ path: string;
+ count: number;
+ project_id: string;
+ first_seen: string;
+ title: string;
+ origin: string;
+}
+
+export interface IClickhouseBotEvent {
+ id: string;
+ name: string;
+ type: string;
+ project_id: string;
+ path: string;
+ created_at: string;
+}
+
+export interface IServiceBotEvent {
+ id: string;
+ name: string;
+ type: string;
+ projectId: string;
+ path: string;
+ createdAt: Date;
+}
+
+export type IServiceCreateBotEventPayload = Omit<IServiceBotEvent, 'id'>;
+
+export interface IClickhouseEvent {
+ id: string;
+ name: string;
+ device_id: string;
+ profile_id: string;
+ project_id: string;
+ session_id: string;
+ path: string;
+ origin: string;
+ referrer: string;
+ referrer_name: string;
+ referrer_type: string;
+ duration: number;
+ properties: Record<string, string | number | boolean | undefined | null>;
+ created_at: string;
+ country: string;
+ city: string;
+ region: string;
+ longitude: number | null;
+ latitude: number | null;
+ os: string;
+ os_version: string;
+ browser: string;
+ browser_version: string;
+ device: string;
+ brand: string;
+ model: string;
+ imported_at: string | null;
+ // Ingestion (ClickHouse-insert) time. Set explicitly at insert time; the
+ // column DEFAULTs to created_at for rows that omit it. Used as the cursor for
+ // object-store exports. Optional here because most read queries don't select
+ // it.
+ inserted_at?: string;
+ sdk_name: string;
+ sdk_version: string;
+ revenue?: number;
+ groups: string[];
+
+ // They do not exist here. Just make ts happy for now
+ profile?: IServiceProfile;
+ meta?: EventMeta;
+}
+
+export interface IServiceEvent {
+ id: string;
+ name: string;
+ deviceId: string;
+ profileId: string;
+ projectId: string;
+ sessionId: string;
+ properties: Record<string, unknown> & {
+ hash?: string;
+ query?: Record<string, unknown>;
+ };
+ createdAt: Date;
+ country?: string | undefined;
+ city?: string | undefined;
+ region?: string | undefined;
+ longitude?: number | undefined | null;
+ latitude?: number | undefined | null;
+ os?: string | undefined;
+ osVersion?: string | undefined;
+ browser?: string | undefined;
+ browserVersion?: string | undefined;
+ device?: string | undefined;
+ brand?: string | undefined;
+ model?: string | undefined;
+ duration?: number;
+ path: string;
+ origin: string;
+ referrer: string | undefined;
+ referrerName: string | undefined;
+ referrerType: string | undefined;
+ importedAt: Date | undefined;
+ profile: IServiceProfile | undefined;
+ meta: EventMeta | undefined;
+ sdkName: string | undefined;
+ sdkVersion: string | undefined;
+ revenue?: number;
+ groups: string[];
+}
+
+export type IServiceCreateEventPayload = Omit<
+ IServiceEvent,
+ 'id' | 'importedAt' | 'profile' | 'meta'
+>;
+/**
+ * A create payload whose id was already minted upstream (the ingest producer).
+ * Reusing it means a redelivered Kafka message lands as an identical-id row.
+ */
+export type IServiceCreateEventPayloadWithId = IServiceCreateEventPayload & {
+ id?: string;
+};
+export type IServiceImportedEventPayload = Omit<
+ IServiceEvent,
+ 'profile' | 'meta'
+>;
+
+export interface IServiceEventMinimal {
+ id: string;
+ name: string;
+ projectId: string;
+ sessionId: string;
+ createdAt: Date;
+ country?: string | undefined;
+ longitude?: number | undefined | null;
+ latitude?: number | undefined | null;
+ os?: string | undefined;
+ browser?: string | undefined;
+ device?: string | undefined;
+ brand?: string | undefined;
+ duration?: number;
+ path: string;
+ origin: string;
+ referrer: string | undefined;
+ meta: EventMeta | undefined;
+ minimal: boolean;
+}
+
+type SelectHelper<T> = {
+ [K in keyof T]?: boolean;
+};
+
+export type EventListSelect = SelectHelper<IServiceEvent>;
+
+interface GetEventsOptions {
+ profile?: boolean;
+ meta?: boolean | Prisma.EventMetaSelect;
+}
+
+export function transformSessionToEvent(
+ session: IClickhouseSession
+): IServiceEvent {
+ return {
+ id: '', // Not used
+ name: 'screen_view',
+ sessionId: session.id,
+ profileId: session.profile_id,
+ path: session.exit_path,
+ origin: session.exit_origin,
+ createdAt: convertClickhouseDateToJs(session.ended_at),
+ referrer: session.referrer,
+ referrerName: session.referrer_name,
+ referrerType: session.referrer_type,
+ os: session.os,
+ osVersion: session.os_version,
+ browser: session.browser,
+ browserVersion: session.browser_version,
+ device: session.device,
+ brand: session.brand,
+ model: session.model,
+ country: session.country,
+ region: session.region,
+ city: session.city,
+ longitude: session.longitude,
+ latitude: session.latitude,
+ projectId: session.project_id,
+ deviceId: session.device_id,
+ duration: 0,
+ revenue: session.revenue,
+ properties: {
+ is_bounce: session.is_bounce,
+ __query: {
+ utm_medium: session.utm_medium,
+ utm_source: session.utm_source,
+ utm_campaign: session.utm_campaign,
+ utm_content: session.utm_content,
+ utm_term: session.utm_term,
+ },
+ },
+ profile: undefined,
+ meta: undefined,
+ importedAt: undefined,
+ sdkName: undefined,
+ sdkVersion: undefined,
+ groups: [],
+ };
+}
+
+export function transformEvent(event: IClickhouseEvent): IServiceEvent {
+ return {
+ id: event.id,
+ name: event.name,
+ deviceId: event.device_id,
+ profileId: event.profile_id,
+ projectId: event.project_id,
+ sessionId: event.session_id,
+ properties: event.properties,
+ createdAt: convertClickhouseDateToJs(event.created_at),
+ country: event.country,
+ city: event.city,
+ region: event.region,
+ longitude: event.longitude,
+ latitude: event.latitude,
+ os: event.os,
+ osVersion: event.os_version,
+ browser: event.browser,
+ browserVersion: event.browser_version,
+ device: event.device,
+ brand: event.brand,
+ model: event.model,
+ path: event.path,
+ origin: event.origin,
+ referrer: event.referrer,
+ referrerName: event.referrer_name,
+ referrerType: event.referrer_type,
+ meta: event.meta,
+ importedAt: event.imported_at ? new Date(event.imported_at) : undefined,
+ sdkName: event.sdk_name,
+ sdkVersion: event.sdk_version,
+ profile: event.profile,
+ revenue: event.revenue,
+ groups: event.groups ?? [],
+ };
+}
+
+function maskString(str: string, mask = MASK_CHARACTER) {
+ const allMasked = str.replace(MASKABLE_CHARACTERS, mask);
+ if (str.length < MASK_MIN_LENGTH_FOR_PREFIX) {
+ return allMasked;
+ }
+
+ return `${str.slice(0, MASK_VISIBLE_PREFIX)}${allMasked.slice(MASK_VISIBLE_PREFIX)}`;
+}
+
+export function transformMinimalEvent(
+ event: IServiceEvent
+): IServiceEventMinimal {
+ return {
+ id: event.id,
+ name: event.name,
+ projectId: event.projectId,
+ sessionId: event.sessionId,
+ createdAt: event.createdAt,
+ country: event.country,
+ longitude: event.longitude,
+ latitude: event.latitude,
+ os: event.os,
+ browser: event.browser,
+ device: event.device,
+ brand: event.brand,
+ duration: event.duration,
+ path: maskString(event.path),
+ origin: event.origin,
+ referrer: event.referrer,
+ meta: event.meta,
+ minimal: true,
+ };
+}
+
+export async function getEventMetas(projectId: string) {
+ const db = await loadDb();
+ return db.eventMeta.findMany({
+ where: {
+ projectId,
+ },
+ });
+}
+
+export const getEventMetasCached = cacheable(
+ getEventMetas,
+ EVENT_METAS_CACHE_SECONDS
+);
+
+function emptyProfile(profileId: string, projectId: string): IServiceProfile {
+ return {
+ id: profileId,
+ email: '',
+ avatar: '',
+ firstName: '',
+ lastName: '',
+ createdAt: new Date(),
+ lastSeenAt: new Date(),
+ projectId,
+ isExternal: false,
+ properties: {},
+ groups: [],
+ };
+}
+
+async function attachProfiles(events: IClickhouseEvent[], projectId: string) {
+ const ids = events
+ .filter((e) => e.device_id !== e.profile_id)
+ .map((e) => e.profile_id);
+ const profiles = await getProfilesCached(ids, projectId);
+
+ const map = new Map<string, IServiceProfile>();
+ for (const profile of profiles) {
+ map.set(profile.id, profile);
+ }
+
+ for (const event of events) {
+ event.profile =
+ map.get(event.profile_id) ?? emptyProfile(event.profile_id, projectId);
+ }
+}
+
+async function attachMetas(events: IClickhouseEvent[], projectId: string) {
+ const metas = await getEventMetasCached(projectId);
+ const map = new Map<string, EventMeta>();
+ for (const meta of metas) {
+ map.set(meta.name, meta);
+ }
+ for (const event of events) {
+ event.meta = map.get(event.name);
+ }
+}
+
+export async function getEvents(
+ query: SqlFragment,
+ options: GetEventsOptions = {}
+): Promise<IServiceEvent[]> {
+ const { chQuery } = await loadChClient();
+ const events = await chQuery<IClickhouseEvent>(query);
+ const projectId = events[0]?.project_id;
+ if (options.profile && projectId) {
+ await attachProfiles(events, projectId);
+ }
+ if (options.meta && projectId) {
+ await attachMetas(events, projectId);
+ }
+ return events.map(transformEvent);
+}
+
+/**
+ * Persist an event to ClickHouse (via the buffer) and upsert the profile
+ * on session boundaries.
+ *
+ * Does NOT touch the session-row buffer. Callers producing non-session_start
+ * / session_end events are responsible for calling `sessionBuffer.ingest()`
+ * before this. `incoming-event.ts` is the only such caller today; everywhere
+ * else (session_start, session_end) the session-row update is correctly a
+ * no-op anyway.
+ */
+export async function createEvent(payload: IServiceCreateEventPayloadWithId) {
+ if (!payload.profileId && payload.deviceId) {
+ payload.profileId = payload.deviceId;
+ }
+
+ const event: IClickhouseEvent = {
+ id: payload.id ?? crypto.randomUUID(),
+ name: payload.name,
+ device_id: payload.deviceId,
+ profile_id: payload.profileId ? String(payload.profileId) : '',
+ project_id: payload.projectId,
+ session_id: payload.sessionId,
+ properties: toDots(payload.properties),
+ path: payload.path ?? '',
+ origin: payload.origin ?? '',
+ created_at: DateTime.fromJSDate(payload.createdAt)
+ .setZone('UTC')
+ .toFormat(CLICKHOUSE_DATETIME_FORMAT),
+ country: payload.country ?? '',
+ city: payload.city ?? '',
+ region: payload.region ?? '',
+ longitude: payload.longitude ?? null,
+ latitude: payload.latitude ?? null,
+ os: payload.os ?? '',
+ os_version: payload.osVersion ?? '',
+ browser: payload.browser ?? '',
+ browser_version: payload.browserVersion ?? '',
+ device: payload.device ?? '',
+ brand: payload.brand ?? '',
+ model: payload.model ?? '',
+ duration: payload.duration ?? 0,
+ referrer: payload.referrer ?? '',
+ referrer_name: payload.referrerName ?? '',
+ referrer_type: payload.referrerType ?? '',
+ imported_at: null,
+ // Ingestion time, used as the export cursor. Stamped here rather than via the
+ // column DEFAULT so backdated events (server-side, offline, past timestamps)
+ // still get a real, monotonic-ish insert time instead of their event time.
+ inserted_at: DateTime.utc().toFormat(CLICKHOUSE_DATETIME_FORMAT),
+ sdk_name: payload.sdkName ?? '',
+ sdk_version: payload.sdkVersion ?? '',
+ revenue: payload.revenue,
+ groups: payload.groups ?? [],
+ };
+
+ const { eventBuffer } = await loadBuffers();
+ eventBuffer.add(event);
+
+ const promises: Promise<unknown>[] = [];
+
+ if (payload.profileId) {
+ const profile: IServiceUpsertProfile = {
+ id: String(payload.profileId),
+ isExternal: payload.profileId !== payload.deviceId,
+ projectId: payload.projectId,
+ properties: {
+ path: payload.path,
+ country: payload.country,
+ city: payload.city,
+ region: payload.region,
+ longitude: payload.longitude,
+ latitude: payload.latitude,
+ os: payload.os,
+ os_version: payload.osVersion,
+ browser: payload.browser,
+ browser_version: payload.browserVersion,
+ device: payload.device,
+ brand: payload.brand,
+ model: payload.model,
+ referrer: payload.referrer,
+ referrer_name: payload.referrerName,
+ referrer_type: payload.referrerType,
+ },
+ };
+
+ // Only upsert the profile on session boundaries.
+ // - session_start covers fresh activity.
+ // - session_end is synthesized server-side by the worker.
+ // Identified users' explicit profile writes (op.identify(), op.setProfile())
+ // go through the controller path and are not affected by this branch.
+ //
+ // `isFromEvent=true` activates profile-buffer's cache shortcut: if the
+ // profile is in the 1h Redis cache (i.e. recently flushed), the add is
+ // skipped. Trade-off: profile.last_seen_at granularity is capped at the
+ // cache TTL (~1h) rather than per-session. We accept this because
+ // (a) profile-buffer was the leading indicator in the 2026-05-20 buildup
+ // and was processing ~2 writes per session per anonymous user;
+ // (b) the bulk of those writes carried no new information (anonymous
+ // profile data is event-derived and stable across a session);
+ // (c) recency queries should derive from event timestamps, not from
+ // profile.last_seen_at.
+ if (payload.name === 'session_start' || payload.name === 'session_end') {
+ promises.push(upsertProfile(profile, true));
+ }
+ }
+
+ await Promise.all(promises);
+
+ return {
+ document: event,
+ };
+}
+
+export interface GetEventListOptions {
+ projectId: string;
+ profileId?: string;
+ sessionId?: string;
+ groupId?: string;
+ cohortId?: string;
+ take: number;
+ cursor?: number | Date;
+ events?: string[] | null;
+ filters?: IChartEventFilter[];
+ startDate?: Date;
+ endDate?: Date;
+ select?: EventListSelect;
+ /** `event.conversions`' extra `name IN (..)` narrowing. */
+ conversionNames?: string[];
+ dateIntervalInDays?: number;
+}
+
+/** V1's default projection, merged under whatever the caller asks for. */
+const DEFAULT_EVENT_LIST_SELECT: EventListSelect = {
+ id: true,
+ name: true,
+ deviceId: true,
+ profileId: true,
+ sessionId: true,
+ projectId: true,
+ createdAt: true,
+ path: true,
+ duration: true,
+ city: true,
+ country: true,
+ os: true,
+ browser: true,
+};
+
+// V1 emitted these in this order, `created_at` and `project_id` always first.
+const SELECT_TO_COLUMN: readonly [keyof EventListSelect, EventListColumn][] = [
+ ['id', 'id'],
+ ['name', 'name'],
+ ['deviceId', 'device_id'],
+ ['profileId', 'profile_id'],
+ ['sessionId', 'session_id'],
+ ['properties', 'properties'],
+ ['country', 'country'],
+ ['city', 'city'],
+ ['region', 'region'],
+ ['longitude', 'longitude'],
+ ['latitude', 'latitude'],
+ ['os', 'os'],
+ ['osVersion', 'os_version'],
+ ['browser', 'browser'],
+ ['browserVersion', 'browser_version'],
+ ['device', 'device'],
+ ['brand', 'brand'],
+ ['model', 'model'],
+ ['path', 'path'],
+ ['origin', 'origin'],
+ ['referrer', 'referrer'],
+ ['referrerName', 'referrer_name'],
+ ['referrerType', 'referrer_type'],
+ ['importedAt', 'imported_at'],
+ ['sdkName', 'sdk_name'],
+ ['sdkVersion', 'sdk_version'],
+ ['revenue', 'revenue'],
+ ['groups', 'groups'],
+];
+
+function eventListColumns(select: EventListSelect): EventListColumn[] {
+ const columns: EventListColumn[] = ['created_at', 'project_id'];
+ for (const [key, column] of SELECT_TO_COLUMN) {
+ if (select[key]) {
+ columns.push(column);
+ }
+ }
+ return columns;
+}
+
+/** Which joins the compiled `profile.*` / `group.*` filters will read from. */
+function eventFilterJoins(filters: IChartEventFilter[]): EventFilterJoins {
+ const profileColumns = uniq(
+ filters
+ .filter((f) => f.name.startsWith(PROFILE_FILTER_PREFIX))
+ .map((f) => f.name.replace(PROFILE_FILTER_PREFIX, '').split('.')[0])
+ .filter((column): column is string => column !== undefined)
+ );
+ const groups = filters.some((f) => f.name.startsWith(GROUP_FILTER_PREFIX));
+ return { profileColumns, groups };
+}
+
+async function compileEventFilters(
+ filters: IChartEventFilter[] | undefined,
+ projectId: string
+): Promise<{ filterClauses: CompiledFilterClauses; joins: EventFilterJoins }> {
+ if (!filters) {
+ return { filterClauses: {}, joins: NO_FILTER_JOINS };
+ }
+ const { getEventFiltersWhereClause } = await loadEventFilterCompiler();
+ return {
+ filterClauses: getEventFiltersWhereClause(filters, projectId, EVENTS_ALIAS),
+ joins: eventFilterJoins(filters),
+ };
+}
+
+/**
+ * V1 applied the lookback window for a Date cursor and for "no cursor and no
+ * date range" — where a numeric `cursor` of 0 counts as no cursor, so the
+ * first numeric page is windowed and later pages are not.
+ */
+function hasEventListLookback(options: GetEventListOptions): boolean {
+ const { cursor, startDate, endDate } = options;
+ return cursor instanceof Date || !(cursor || (startDate && endDate));
+}
+
+export async function getEventList(
+ options: GetEventListOptions
+): Promise<IServiceEvent[]> {
+ const {
+ cursor,
+ take,
+ projectId,
+ profileId,
+ sessionId,
+ groupId,
+ cohortId,
+ events,
+ filters,
+ startDate,
+ endDate,
+ conversionNames,
+ select: incomingSelect,
+ dateIntervalInDays = EVENT_LIST_DEFAULT_LOOKBACK_DAYS,
+ } = options;
+
+ const { resolveMaxLookbackDays } = await loadLookback();
+ // Deployment-tunable ceiling for the empty-result lookback (see lookback.ts).
+ const maxLookbackDays = resolveMaxLookbackDays(
+ EVENT_LIST_MAX_LOOKBACK_DAYS_ENV,
+ EVENT_LIST_MAX_LOOKBACK_DAYS_DEFAULT
+ );
+ const lookbackDays = Math.min(dateIntervalInDays, maxLookbackDays);
+ const hasLookback = hasEventListLookback(options);
+
+ const select = mergeDeepRight(
+ DEFAULT_EVENT_LIST_SELECT,
+ incomingSelect ?? {}
+ ) as EventListSelect;
+
+ const { filterClauses, joins } = await compileEventFilters(
+ filters,
+ projectId
+ );
+
+ const query: EventListQuery = {
+ projectId,
+ columns: eventListColumns(select),
+ take,
+ offset: typeof cursor === 'number' ? Math.max(0, cursor * take) : undefined,
+ cursor: cursor instanceof Date ? cursor : undefined,
+ lookbackDays: hasLookback ? lookbackDays : undefined,
+ profileId,
+ sessionId,
+ groupId,
+ cohortId,
+ startDate,
+ endDate,
+ events: events ?? undefined,
+ filterClauses,
+ joins,
+ conversionNames,
+ };
+
+ const data = await getEvents(eventListQuery(query), {
+ profile: select.profile ?? true,
+ meta: select.meta ?? true,
+ });
+
+ // If we dont get any events, try without the cursor window
+ if (data.length === 0 && hasLookback && lookbackDays < maxLookbackDays) {
+ return getEventList({
+ ...options,
+ dateIntervalInDays: dateIntervalInDays * 2,
+ });
+ }
+
+ return data;
+}
+
+export async function getEventsCount({
+ projectId,
+ profileId,
+ groupId,
+ cohortId,
+ events,
+ filters,
+ startDate,
+ endDate,
+}: Omit<GetEventListOptions, 'cursor' | 'take'>): Promise<number> {
+ const { filterClauses, joins } = await compileEventFilters(
+ filters,
+ projectId
+ );
+ const query: EventsCountQuery = {
+ projectId,
+ profileId,
+ groupId,
+ cohortId,
+ startDate,
+ endDate,
+ events: events ?? undefined,
+ filterClauses,
+ joins,
+ };
+ const { chQuery } = await loadChClient();
+ const res = await chQuery<{ count: number }>(eventsCountQuery(query));
+ return res[0]?.count ?? 0;
+}
+
+export async function createBotEvent({
+ name,
+ type,
+ projectId,
+ createdAt,
+ path,
+}: IServiceCreateBotEventPayload) {
+ const { botBuffer } = await loadBuffers();
+ return botBuffer.add({
+ id: crypto.randomUUID(),
+ name,
+ type,
+ project_id: projectId,
+ path,
+ created_at: formatClickhouseDate(createdAt),
+ });
+}
+
+export async function getConversionEventNames(projectId: string) {
+ const db = await loadDb();
+ return db.eventMeta.findMany({
+ where: {
+ projectId,
+ conversion: true,
+ },
+ });
+}
+
+export async function getTopPages({
+ projectId,
+ cursor,
+ take,
+ search,
+}: {
+ projectId: string;
+ cursor?: number;
+ take: number;
+ search?: string;
+}): Promise<IServicePage[]> {
+ const { chQuery } = await loadChClient();
+ return chQuery<IServicePage>(
+ topPagesQuery({
+ projectId,
+ take,
+ offset: Math.max(0, (cursor ?? 0) * take),
+ search,
+ })
+ );
+}
+
+/** V1's `eventService.getById`. */
+export async function getEventById({
+ projectId,
+ id,
+ createdAt,
+}: {
+ projectId: string;
+ id: string;
+ createdAt?: Date;
+}): Promise<IServiceEvent | null> {
+ const { chQuery } = await loadChClient();
+ const [rows, metas] = await Promise.all([
+ chQuery<IClickhouseEvent>(
+ eventByIdQuery({ projectId, id, createdAt }),
+ CLIX_SESSION_TIMEZONE
+ ),
+ getEventMetasCached(projectId),
+ ]);
+ const row = rows[0];
+ if (!row) {
+ return null;
+ }
+ const event = transformEvent(row);
+
+ if (event.profileId) {
+ const profile = await getProfileById(event.profileId, projectId);
+ if (profile) {
+ event.profile = profile;
+ }
+ }
+
+ event.meta = metas.find((meta) => meta.name === event.name);
+
+ return event;
+}
+
+export async function getTopEventNames(projectId: string): Promise<string[]> {
+ const getCache = await loadCache();
+ return getCache(
+ `mcp:event-names:${projectId}`,
+ TOP_EVENT_NAMES_CACHE_SECONDS,
+ async () => {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ name: string; count: number }>(
+ topEventNamesQuery(projectId),
+ CLIX_SESSION_TIMEZONE
+ );
+ return rows.map((r) => r.name);
+ }
+ );
+}
+
+export const listEventNamesCore = (projectId: string): Promise<string[]> =>
+ getTopEventNames(projectId);
+
+/**
+ * Top-level filterable columns on the `events` table. These apply to
+ * every event regardless of name and can be passed straight to
+ * `getEventFiltersWhereClause` as filter / breakdown `name` values.
+ *
+ * Kept as a whitelist because the filter builder splices `name` into
+ * SQL verbatim — only these are safe to expose through the AI /
+ * MCP discovery surface.
+ */
+export const EVENT_COLUMNS = [
+ 'path',
+ 'origin',
+ 'referrer',
+ 'referrer_name',
+ 'referrer_type',
+ 'duration',
+ 'country',
+ 'city',
+ 'region',
+ 'os',
+ 'os_version',
+ 'browser',
+ 'browser_version',
+ 'device',
+ 'brand',
+ 'model',
+ 'sdk_name',
+ 'sdk_version',
+ 'profile_id',
+ 'session_id',
+ 'device_id',
+ 'revenue',
+] as const;
+
+export type IEventColumn = (typeof EVENT_COLUMNS)[number];
+
+export async function listEventPropertiesCore(input: {
+ projectId: string;
+ eventName?: string;
+}): Promise<{
+ columns: readonly string[];
+ properties: Array<{ property_key: string; event_name: string }>;
+}> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ property_key: string; event_name: string }>(
+ eventPropertiesQuery(input),
+ CLIX_SESSION_TIMEZONE
+ );
+ return { columns: EVENT_COLUMNS, properties: rows };
+}
+
+export async function getEventPropertyValuesCore(input: {
+ projectId: string;
+ eventName: string;
+ propertyKey: string;
+}): Promise<{ event: string; property: string; values: string[] }> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ value: string }>(
+ eventPropertyValuesQuery(input),
+ CLIX_SESSION_TIMEZONE
+ );
+
+ return {
+ event: input.eventName,
+ property: input.propertyKey,
+ values: rows.map((r) => r.value),
+ };
+}
+
+export interface QueryEventsInput {
+ projectId: string;
+ startDate?: string;
+ endDate?: string;
+ eventNames?: string[];
+ path?: string;
+ country?: string;
+ city?: string;
+ device?: string;
+ browser?: string;
+ os?: string;
+ referrer?: string;
+ referrerName?: string;
+ referrerType?: string;
+ sessionId?: string;
+ profileId?: string;
+ profileIds?: string[];
+ properties?: Record<string, string>;
+ filters?: IChartEventFilter[];
+ limit?: number;
+}
+
+const QUERY_EVENTS_INPUT_TO_COLUMN: readonly [
+ keyof QueryEventsInput,
+ QueryEventsEqualityColumn,
+][] = [
+ ['path', 'path'],
+ ['referrer', 'referrer'],
+ ['referrerName', 'referrer_name'],
+ ['referrerType', 'referrer_type'],
+ ['device', 'device'],
+ ['country', 'country'],
+ ['city', 'city'],
+ ['os', 'os'],
+ ['browser', 'browser'],
+];
+
+function queryEventsEquals(
+ input: QueryEventsInput
+): Partial<Record<QueryEventsEqualityColumn, string>> {
+ const equals: Partial<Record<QueryEventsEqualityColumn, string>> = {};
+ for (const [key, column] of QUERY_EVENTS_INPUT_TO_COLUMN) {
+ const value = input[key];
+ if (typeof value === 'string' && value) {
+ equals[column] = value;
+ }
+ }
+ return equals;
+}
+
+// Skip the default 30-day date filter when sessionId is set — a session id
+// is unique and narrow enough to query directly. Without this, an older
+// session's events would be silently excluded. A caller that still passes
+// dates alongside a sessionId is honoured.
+async function queryEventsDateRange(
+ input: QueryEventsInput
+): Promise<{ start: string; end: string } | undefined> {
+ const wantsRange = !input.sessionId || input.startDate || input.endDate;
+ if (!wantsRange) {
+ return undefined;
+ }
+ const { resolveDateRange } = await loadDateService();
+ const { startDate, endDate } = resolveDateRange(
+ input.startDate,
+ input.endDate
+ );
+ return {
+ start: formatClickhouseDate(new Date(startDate)),
+ end: formatClickhouseDate(new Date(endDate)),
+ };
+}
+
+export async function queryEventsCore(
+ input: QueryEventsInput
+): Promise<IClickhouseEvent[]> {
+ let filterClauses: CompiledFilterClauses = {};
+ if (input.filters?.length) {
+ const { buildFilterWhere } = await loadFilterCompiler();
+ filterClauses = buildFilterWhere(
+ input.filters,
+ input.projectId,
+ QUERY_EVENTS_FILTER_TARGET
+ );
+ }
+ const { chQuery } = await loadChClient();
+ return chQuery<IClickhouseEvent>(
+ queryEventsQuery({
+ projectId: input.projectId,
+ sessionId: input.sessionId,
+ profileId: input.profileId,
+ profileIds: input.profileIds,
+ eventNames: input.eventNames,
+ equals: queryEventsEquals(input),
+ properties: input.properties,
+ dateRange: await queryEventsDateRange(input),
+ filterClauses,
+ limit: input.limit ?? QUERY_EVENTS_DEFAULT_LIMIT,
+ }),
+ CLIX_SESSION_TIMEZONE
+ );
+}
+
+// ---- packages/trpc/src/routers/event.ts bodies
+
+export interface UpdateEventMetaInput {
+ projectId: string;
+ name: string;
+ icon?: string;
+ color?: string;
+ conversion?: boolean;
+}
+
+export async function updateEventMeta({
+ projectId,
+ name,
+ icon,
+ color,
+ conversion,
+}: UpdateEventMetaInput) {
+ await getEventMetasCached.clear(projectId);
+ const db = await loadDb();
+ return db.eventMeta.upsert({
+ where: {
+ name_projectId: {
+ name,
+ projectId,
+ },
+ },
+ create: { projectId, name, icon, color, conversion },
+ update: { icon, color, conversion },
+ });
+}
+
+export async function getEventDetails(input: {
+ projectId: string;
+ id: string;
+ createdAt?: Date;
+}) {
+ const event = await getEventById(input);
+ if (!event) {
+ return null;
+ }
+ const { getSessionById } = await loadSessionService();
+ const session = event.sessionId
+ ? await getSessionById(event.sessionId, input.projectId).catch(
+ () => undefined
+ )
+ : undefined;
+ return { event, session };
+}
+
+export interface EventListPageInput {
+ projectId: string;
+ profileId?: string | null;
+ sessionId?: string | null;
+ groupId?: string | null;
+ cohortId?: string | null;
+ cursor?: string | null;
+ filters?: IChartEventFilter[];
+ startDate?: Date | null;
+ endDate?: Date | null;
+ events?: string[] | null;
+ columnVisibility?: Record<string, boolean> | null;
+}
+
+const EVENT_LIST_PAGE_TAKE = 50;
+
+function pageSelect(
+ columnVisibility: Record<string, boolean> | null | undefined
+): EventListSelect {
+ return {
+ ...columnVisibility,
+ city: columnVisibility?.country ?? true,
+ path: columnVisibility?.name ?? true,
+ duration: columnVisibility?.name ?? true,
+ projectId: false,
+ revenue: true,
+ };
+}
+
+// Hacky join to get profile for entire session
+// TODO: Replace this with a join on the session table
+function shareSessionProfiles(items: IServiceEvent[]) {
+ const map = new Map<string, IServiceProfile>(); // sessionId -> profile
+ for (const item of items) {
+ if (item.sessionId && item.profile?.isExternal === true) {
+ map.set(item.sessionId, item.profile);
+ }
+ }
+
+ for (const item of items) {
+ const profile = map.get(item.sessionId);
+ if (profile && (item.profile?.isExternal === false || !item.profile)) {
+ item.profile = clone(profile);
+ if (item?.profile?.firstName) {
+ item.profile.firstName = `* ${item.profile.firstName}`;
+ }
+ }
+ }
+}
+
+function toEventListPage(items: IServiceEvent[]) {
+ shareSessionProfiles(items);
+ const lastItem = items.at(-1);
+ return {
+ data: items,
+ meta: {
+ next:
+ items.length > 0 && lastItem ? lastItem.createdAt.toISOString() : null,
+ },
+ };
+}
+
+export async function getEventListPage({
+ columnVisibility,
+ ...input
+}: EventListPageInput) {
+ const items = await getEventList({
+ projectId: input.projectId,
+ filters: input.filters,
+ profileId: input.profileId ?? undefined,
+ sessionId: input.sessionId ?? undefined,
+ groupId: input.groupId ?? undefined,
+ cohortId: input.cohortId ?? undefined,
+ startDate: input.startDate ?? undefined,
+ endDate: input.endDate ?? undefined,
+ events: input.events ?? undefined,
+ take: EVENT_LIST_PAGE_TAKE,
+ cursor: input.cursor ? new Date(input.cursor) : undefined,
+ select: pageSelect(columnVisibility),
+ });
+ return toEventListPage(items);
+}
+
+export type ConversionListPageInput = Pick<
+ EventListPageInput,
+ | 'projectId'
+ | 'cursor'
+ | 'startDate'
+ | 'endDate'
+ | 'events'
+ | 'columnVisibility'
+>;
+
+export async function getConversionListPage({
+ columnVisibility,
+ ...input
+}: ConversionListPageInput) {
+ const conversions = await getConversionEventNames(input.projectId);
+ const filteredConversions = conversions.filter((event) => {
+ if (input.events && input.events.length > 0) {
+ return input.events.includes(event.name);
+ }
+ return true;
+ });
+
+ if (filteredConversions.length === 0) {
+ return { data: [], meta: { next: null } };
+ }
+
+ const items = await getEventList({
+ projectId: input.projectId,
+ startDate: input.startDate ?? undefined,
+ endDate: input.endDate ?? undefined,
+ events: input.events ?? undefined,
+ take: EVENT_LIST_PAGE_TAKE,
+ cursor: input.cursor ? new Date(input.cursor) : undefined,
+ select: pageSelect(columnVisibility),
+ conversionNames: filteredConversions.map((event) => event.name),
+ });
+ return toEventListPage(items);
+}
+
+export async function getBotEventsPage({
+ projectId,
+ cursor,
+ limit,
+}: {
+ projectId: string;
+ cursor?: number;
+ limit: number;
+}) {
+ const { chQuery } = await loadChClient();
+ const [events, counts] = await Promise.all([
+ chQuery<IClickhouseBotEvent>(
+ botEventsQuery({ projectId, limit, offset: (cursor ?? 0) * limit })
+ ),
+ chQuery<{ count: number }>(botEventsCountQuery(projectId)),
+ ]);
+
+ return {
+ data: events.map((item) => ({
+ ...item,
+ createdAt: convertClickhouseDateToJs(item.created_at),
+ })),
+ count: counts[0]?.count ?? 0,
+ };
+}
+
+export async function getTopOrigins(projectId: string) {
+ const { chQuery } = await loadChClient();
+ const res = await chQuery<{ origin: string; count: number }>(
+ topOriginsQuery(projectId)
+ );
+ return res.filter(
+ (item) => item.origin && !item.origin.includes(LOCALHOST_ORIGIN_MARKER)
+ );
+}
+
+export interface EventService {
+ getById(input: {
+ projectId: string;
+ id: string;
+ createdAt?: Date;
+ }): Promise<IServiceEvent | null>;
+ create(
+ payload: IServiceCreateEventPayloadWithId
+ ): Promise<{ document: IClickhouseEvent }>;
+}
+
+export function createEventService(_deps: ServiceDeps): EventService {
+ return { getById: getEventById, create: createEvent };
+}
diff --git a/packages/core/src/modules/event/src/access.ts b/packages/core/src/modules/event/src/access.ts
new file mode 100644
index 000000000..9b407436e
--- /dev/null
+++ b/packages/core/src/modules/event/src/access.ts
@@ -0,0 +1,22 @@
+// Binds core's shared/access.ts ladder to @openpanel/db's real lookups, for
+// this module's own router — the same binding packages/trpc/src/access.ts
+// does for V1, self-contained here because the general core -> db binding
+// itself moves with auth (P6), not this wave. Same shape as
+// session/src/access.ts.
+
+import {
+ canWriteProject,
+ getOrganizationAccess,
+ getProjectAccess,
+} from '@openpanel/db/src/services/access.service';
+import { getProjectById } from '@openpanel/db/src/services/project.service';
+import { createAccessChecks } from '../../../shared/access';
+
+const checks = createAccessChecks({
+ getProjectAccess,
+ canWriteProject,
+ getOrganizationAccess,
+ getProjectById,
+});
+
+export const requireProjectAccess = checks.requireProjectAccess;
diff --git a/packages/db/src/services/create-event-id.test.ts b/packages/core/src/modules/event/src/create-event-id.test.ts
similarity index 53%
rename from packages/db/src/services/create-event-id.test.ts
rename to packages/core/src/modules/event/src/create-event-id.test.ts
index 8b10aa425..3ef9bde34 100644
--- a/packages/db/src/services/create-event-id.test.ts
+++ b/packages/core/src/modules/event/src/create-event-id.test.ts
@@ -1,13 +1,28 @@
-import { describe, expect, it, vi } from 'vitest';
+// Ported from packages/db/src/services/create-event-id.test.ts (M7-002).
+// `createEvent` reaches the buffers lazily (`loadBuffers`), so the buffer
+// mock is installed before the subject is imported; spread-actual + snapshot
+// restore, same as realtime.service.test.ts.
-const add = vi.fn();
+import { afterAll, beforeAll, describe, expect, mock, test } from 'bun:test';
-vi.mock('../buffers', () => ({
+const add = mock((_event: { id: string }) => undefined);
+
+const actualBuffers = await import('@openpanel/db/src/buffers');
+const realBuffers = { ...actualBuffers };
+mock.module('@openpanel/db/src/buffers', () => ({
+ ...realBuffers,
eventBuffer: { add },
- botBuffer: { add: vi.fn() },
+ botBuffer: { add: mock(() => undefined) },
}));
-const { createEvent } = await import('./event.service');
+afterAll(() => {
+ mock.module('@openpanel/db/src/buffers', () => realBuffers);
+});
+
+let createEvent: typeof import('../event.service').createEvent;
+beforeAll(async () => {
+ ({ createEvent } = await import('../event.service'));
+});
const PRODUCED_EVENT_ID = '11111111-2222-4333-8444-555555555555';
const UUID_V4 =
@@ -45,7 +60,7 @@ const payload = {
};
describe('createEvent id', () => {
- it('uses the producer-minted id for the ClickHouse row', async () => {
+ test('uses the producer-minted id for the ClickHouse row', async () => {
add.mockClear();
const first = await createEvent({ ...payload, id: PRODUCED_EVENT_ID });
@@ -53,17 +68,18 @@ describe('createEvent id', () => {
const second = await createEvent({ ...payload, id: PRODUCED_EVENT_ID });
expect(add).toHaveBeenCalledTimes(2);
- expect(add.mock.calls[0]![0].id).toBe(PRODUCED_EVENT_ID);
- expect(add.mock.calls[1]![0].id).toBe(PRODUCED_EVENT_ID);
+ expect(add.mock.calls[0]?.[0].id).toBe(PRODUCED_EVENT_ID);
+ expect(add.mock.calls[1]?.[0].id).toBe(PRODUCED_EVENT_ID);
expect(first.document.id).toBe(second.document.id);
});
- it('falls back to a generated uuid when the payload carries no id', async () => {
+ test('falls back to a generated uuid when the payload carries no id', async () => {
add.mockClear();
await createEvent({ ...payload });
await createEvent({ ...payload });
+ expect(add).toHaveBeenCalledTimes(2);
const [firstId, secondId] = add.mock.calls.map(([event]) => event.id);
expect(firstId).toMatch(UUID_V4);
expect(secondId).toMatch(UUID_V4);
diff --git a/packages/core/src/modules/event/src/dates.ts b/packages/core/src/modules/event/src/dates.ts
new file mode 100644
index 000000000..bcfcf8cb5
--- /dev/null
+++ b/packages/core/src/modules/event/src/dates.ts
@@ -0,0 +1,18 @@
+// @openpanel/db's clickhouse/client.ts owns these, but importing it constructs
+// a client and a pino logger at import time (see insight.service.ts's header),
+// and the fragment builders here must stay pure and synchronous. Same choice
+// cohort.service.ts made for its table map.
+
+const CLICKHOUSE_DATE_SUFFIX = /(\.\d{3})?Z+$/;
+
+/** `YYYY-MM-DD HH:mm:ss` in UTC — what V1 sent as a date literal. */
+export function formatClickhouseDate(date: Date | string): string {
+ return new Date(date)
+ .toISOString()
+ .replace('T', ' ')
+ .replace(CLICKHOUSE_DATE_SUFFIX, '');
+}
+
+export function convertClickhouseDateToJs(date: string): Date {
+ return new Date(`${date.replace(' ', 'T')}Z`);
+}
diff --git a/packages/core/src/modules/event/src/event.sql.proof.md b/packages/core/src/modules/event/src/event.sql.proof.md
new file mode 100644
index 000000000..21b014d96
--- /dev/null
+++ b/packages/core/src/modules/event/src/event.sql.proof.md
@@ -0,0 +1,665 @@
+# event.sql.ts — V1 → V2 result-set proof (M7-002)
+
+Every query builder in `event.sql.ts` was executed twice against the same data — once as V1 (the `git HEAD` service/router code, `3300f2a0`) and once as V2 (core's service, which renders the builder) — through one patched ClickHouse client that captured each statement, its `query_params`, `clickhouse_settings`, wall time and the raw JSON response. The two responses were compared on `data` (every row, every column, as JSON) and `meta` (column names and types). Statements without an `ORDER BY` were compared as row sets, because ClickHouse's parallel aggregation returns them in a different order run to run — V1 against itself too.
+
+- **Date**: 2026-09-04. **Data**: local prod-copy `openpanel` (319,499,000 events, static), project `redcollege` unless noted; cases needing rows the prod-copy lacks (`cohort_members`, `events_bots` are empty there) also ran on the isolated `openpanel_test` database with 3,380 events copied from `redcollege` under project `m7-002-proof`, plus seeded cohort/bot rows (deleted afterwards).
+- **Machine**: single-node ClickHouse 26.1.3.52 on a 4-vCPU box — timings are directional only; production is 2 shards × 2 replicas (`docs/ENVIRONMENT.md`). `rows_read` differences on JOIN statements are ClickHouse's per-run accounting of the right-hand side, not a plan difference: the SQL text is identical up to `{pN:Type}` binding.
+- **Verdict**: 26 cases / 51 statements, all IDENTICAL. No conversion changed a result set.
+
+The harness was a throwaway script (it needed verbatim copies of the V1 sources next to V2); each statement below is complete and reproducible with `curl http://127.0.0.1:8123/?database=openpanel`, binding the V2 params as `param_pN=`.
+
+### eventListQuery — date cursor, default columns, no lookups
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 42.7 ms / 10.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 0.5 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} ORDER BY created_at DESC, id ASC LIMIT {p5:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":0.5,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":50}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 24575/24575; wall V1/V2 = 27.3 ms / 18.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} ORDER BY created_at DESC, id ASC LIMIT {p5:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":1,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":50}
+```
+
+### eventListQuery — numeric cursor page 2, every column, date range
+
+**statement** — IDENTICAL; rows V1/V2 = 20/20; rows_read V1/V2 = 73721/73721; wall V1/V2 = 23.2 ms / 21.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, properties, country, city, region, longitude, latitude, os, os_version, browser, browser_version, device, brand, model, path, origin, referrer, referrer_name, referrer_type, imported_at, sdk_name, sdk_version, revenue, groups FROM events e WHERE project_id = 'redcollege' AND toDate(created_at) BETWEEN toDate('2026-08-15 00:00:00') AND toDate('2026-08-20 23:59:59') ORDER BY created_at DESC, id ASC LIMIT 20 OFFSET 40
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, properties, country, city, region, longitude, latitude, os, os_version, browser, browser_version, device, brand, model, path, origin, referrer, referrer_name, referrer_type, imported_at, sdk_name, sdk_version, revenue, groups FROM events e WHERE project_id = {p1:String} AND toDate(created_at) BETWEEN toDate({p2:String}) AND toDate({p3:String}) ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64} OFFSET {p5:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"2026-08-15 00:00:00","p3":"2026-08-20 23:59:59","p4":20,"p5":40}
+```
+
+### eventListQuery — profile (identity stitching) + events + sessionId
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 122874/122874; wall V1/V2 = 31.2 ms / 20.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-26 00:00:00', 3) - INTERVAL 0.5 DAY AND created_at < '2026-08-26 00:00:00' AND project_id = 'redcollege' AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = 'redcollege' AND device_id != '' AND profile_id = '107145' group by did) AND profile_id = device_id) OR profile_id = '107145') AND session_id = '0kiE1SjOk6U6_WDCbuyLeQ' AND name IN ('screen_view','link_out') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = {p5:String} AND device_id != '' AND profile_id = {p6:String} group by did) AND profile_id = device_id) OR profile_id = {p7:String}) AND session_id = {p8:String} AND name IN {p9:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p10:UInt64}
+-- V2 params: {"p1":"2026-08-26 00:00:00","p2":0.5,"p3":"2026-08-26 00:00:00","p4":"redcollege","p5":"redcollege","p6":"107145","p7":"107145","p8":"0kiE1SjOk6U6_WDCbuyLeQ","p9":["screen_view","link_out"],"p10":50}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 163832/163832; wall V1/V2 = 22.5 ms / 27.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-26 00:00:00', 3) - INTERVAL 1 DAY AND created_at < '2026-08-26 00:00:00' AND project_id = 'redcollege' AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = 'redcollege' AND device_id != '' AND profile_id = '107145' group by did) AND profile_id = device_id) OR profile_id = '107145') AND session_id = '0kiE1SjOk6U6_WDCbuyLeQ' AND name IN ('screen_view','link_out') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = {p5:String} AND device_id != '' AND profile_id = {p6:String} group by did) AND profile_id = device_id) OR profile_id = {p7:String}) AND session_id = {p8:String} AND name IN {p9:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p10:UInt64}
+-- V2 params: {"p1":"2026-08-26 00:00:00","p2":1,"p3":"2026-08-26 00:00:00","p4":"redcollege","p5":"redcollege","p6":"107145","p7":"107145","p8":"0kiE1SjOk6U6_WDCbuyLeQ","p9":["screen_view","link_out"],"p10":50}
+```
+
+**statement 3** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 180215/180215; wall V1/V2 = 32.7 ms / 32.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-26 00:00:00', 3) - INTERVAL 2 DAY AND created_at < '2026-08-26 00:00:00' AND project_id = 'redcollege' AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = 'redcollege' AND device_id != '' AND profile_id = '107145' group by did) AND profile_id = device_id) OR profile_id = '107145') AND session_id = '0kiE1SjOk6U6_WDCbuyLeQ' AND name IN ('screen_view','link_out') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = {p5:String} AND device_id != '' AND profile_id = {p6:String} group by did) AND profile_id = device_id) OR profile_id = {p7:String}) AND session_id = {p8:String} AND name IN {p9:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p10:UInt64}
+-- V2 params: {"p1":"2026-08-26 00:00:00","p2":2,"p3":"2026-08-26 00:00:00","p4":"redcollege","p5":"redcollege","p6":"107145","p7":"107145","p8":"0kiE1SjOk6U6_WDCbuyLeQ","p9":["screen_view","link_out"],"p10":50}
+```
+
+### eventListQuery — groupId + profile.* filter (profile join)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 16.6 ms / 10.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = 'redcollege') as profile on profile.id = profile_id WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 0.5 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND has(groups, '395') AND profile.properties['cargo'] = 'Profesora' ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = {p1:String}) as profile on profile.id = profile_id WHERE created_at >= toDateTime64({p2:String}, 3) - INTERVAL {p3:Float64} DAY AND created_at < {p4:String} AND project_id = {p5:String} AND has(groups, {p6:String}) AND profile.properties['cargo'] = 'Profesora' ORDER BY created_at DESC, id ASC LIMIT {p7:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"2026-08-24 00:00:00","p3":0.5,"p4":"2026-08-24 00:00:00","p5":"redcollege","p6":"395","p7":50}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 130794/130794; wall V1/V2 = 71.3 ms / 52.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = 'redcollege') as profile on profile.id = profile_id WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND has(groups, '395') AND profile.properties['cargo'] = 'Profesora' ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = {p1:String}) as profile on profile.id = profile_id WHERE created_at >= toDateTime64({p2:String}, 3) - INTERVAL {p3:Float64} DAY AND created_at < {p4:String} AND project_id = {p5:String} AND has(groups, {p6:String}) AND profile.properties['cargo'] = 'Profesora' ORDER BY created_at DESC, id ASC LIMIT {p7:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"2026-08-24 00:00:00","p3":1,"p4":"2026-08-24 00:00:00","p5":"redcollege","p6":"395","p7":50}
+```
+
+### eventListQuery — groupId + group.* filter (group array join)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 3359/3359; wall V1/V2 = 10.3 ms / 12.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = 'redcollege') AS _g ON _g.id = _group_id WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 0.5 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND has(groups, '271') AND _g.type = 'establecimiento' ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = {p1:String}) AS _g ON _g.id = _group_id WHERE created_at >= toDateTime64({p2:String}, 3) - INTERVAL {p3:Float64} DAY AND created_at < {p4:String} AND project_id = {p5:String} AND has(groups, {p6:String}) AND _g.type = 'establecimiento' ORDER BY created_at DESC, id ASC LIMIT {p7:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"2026-08-24 00:00:00","p3":0.5,"p4":"2026-08-24 00:00:00","p5":"redcollege","p6":"271","p7":50}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 50/50; rows_read V1/V2 = 11551/11551; wall V1/V2 = 14.5 ms / 12.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = 'redcollege') AS _g ON _g.id = _group_id WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND has(groups, '271') AND _g.type = 'establecimiento' ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = {p1:String}) AS _g ON _g.id = _group_id WHERE created_at >= toDateTime64({p2:String}, 3) - INTERVAL {p3:Float64} DAY AND created_at < {p4:String} AND project_id = {p5:String} AND has(groups, {p6:String}) AND _g.type = 'establecimiento' ORDER BY created_at DESC, id ASC LIMIT {p7:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"2026-08-24 00:00:00","p3":1,"p4":"2026-08-24 00:00:00","p5":"redcollege","p6":"271","p7":50}
+```
+
+### eventListQuery — profile.* AND group.* filters together (V1 error parity)
+
+Both sides raise the same ClickHouse error (V1 has always failed this input; V2 must fail identically, not "fix" it):
+
+- **v1**: `JOIN ANY LEFT JOIN ... ON profile.id = profile_id ambiguous identifier 'id'. In scope SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events AS e ANY LEFT JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = 'redcollege'`
+- **v2**: `JOIN ANY LEFT JOIN ... ON profile.id = profile_id ambiguous identifier 'id'. In scope SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events AS e ANY LEFT JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = 'redcollege'`
+
+### eventListQuery — cohortId + conversions name list (event.conversions)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 15.6 ms / 10.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 0.5 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":0.5,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 16.1 ms / 9.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":1,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 3** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 14.6 ms / 10.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 2 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":2,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 4** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 15.3 ms / 11.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 4 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":4,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 5** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 16.7 ms / 14.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 8 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":8,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 6** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 15.6 ms / 13.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 16 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":16,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 7** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 14.0 ms / 15.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 32 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":32,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 8** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 15.1 ms / 14.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 64 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":64,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 9** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 18.3 ms / 14.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 128 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":128,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 10** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 12.3 ms / 14.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 256 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":256,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 11** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 13.0 ms / 14.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 512 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":512,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 12** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 14.6 ms / 14.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1024 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":1024,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 13** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 13.3 ms / 14.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1825 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":1825,"p3":"2026-08-24 00:00:00","p4":"redcollege","p5":"cohort-1","p6":"redcollege","p7":["link_out","banner_click"],"p8":50}
+```
+
+The prod-copy has no rows for this case (empty `cohort_members` / `events_bots`), so the same case also ran on the seeded `openpanel_test` copy:
+
+### eventListQuery — cohortId + conversions name list (event.conversions)
+
+_Database: `openpanel_test`._
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 3383/3383; wall V1/V2 = 50.5 ms / 8.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 0.5 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'm7-002-proof' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'm7-002-proof') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":0.5,"p3":"2026-08-24 00:00:00","p4":"m7-002-proof","p5":"cohort-1","p6":"m7-002-proof","p7":["link_out","banner_click"],"p8":50}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 3/3; rows_read V1/V2 = 6763/6763; wall V1/V2 = 9.9 ms / 8.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-08-24 00:00:00', 3) - INTERVAL 1 DAY AND created_at < '2026-08-24 00:00:00' AND project_id = 'm7-002-proof' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'm7-002-proof') AND name IN ('link_out','banner_click') ORDER BY created_at DESC, id ASC LIMIT 50
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p5:String} AND project_id = {p6:String}) AND name IN {p7:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p8:UInt64}
+-- V2 params: {"p1":"2026-08-24 00:00:00","p2":1,"p3":"2026-08-24 00:00:00","p4":"m7-002-proof","p5":"cohort-1","p6":"m7-002-proof","p7":["link_out","banner_click"],"p8":50}
+```
+
+### eventListQuery — no cursor, no range (lookback doubling until rows)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 6.5 ms / 6.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-09-04 06:37:07', 3) - INTERVAL 0.5 DAY AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 10
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String} ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"2026-09-04 06:37:07","p2":0.5,"p3":"redcollege","p4":10}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 1878/0; wall V1/V2 = 6.8 ms / 6.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-09-04 06:37:07', 3) - INTERVAL 1 DAY AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 10
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String} ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"2026-09-04 06:37:07","p2":1,"p3":"redcollege","p4":10}
+```
+
+**statement 3** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 7284/0; wall V1/V2 = 9.6 ms / 10.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-09-04 06:37:07', 3) - INTERVAL 2 DAY AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 10
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String} ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"2026-09-04 06:37:07","p2":2,"p3":"redcollege","p4":10}
+```
+
+**statement 4** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 7284/0; wall V1/V2 = 8.8 ms / 15.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-09-04 06:37:07', 3) - INTERVAL 4 DAY AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 10
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String} ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"2026-09-04 06:37:07","p2":4,"p3":"redcollege","p4":10}
+```
+
+**statement 5** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 7284/0; wall V1/V2 = 10.0 ms / 9.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-09-04 06:37:07', 3) - INTERVAL 8 DAY AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 10
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String} ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"2026-09-04 06:37:07","p2":8,"p3":"redcollege","p4":10}
+```
+
+**statement 6** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 113773/81914; wall V1/V2 = 17.3 ms / 18.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64('2026-09-04 06:37:07', 3) - INTERVAL 16 DAY AND project_id = 'redcollege' ORDER BY created_at DESC, id ASC LIMIT 10
+-- V2
+SELECT created_at, project_id, id, name, device_id, profile_id, session_id, country, city, os, browser, path FROM events e WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String} ORDER BY created_at DESC, id ASC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"2026-09-04 06:37:07","p2":16,"p3":"redcollege","p4":10}
+```
+
+### eventsCountQuery — plain project
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 65533/65533; wall V1/V2 = 10.8 ms / 9.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events e WHERE project_id = 'redcollege'
+-- V2
+SELECT count(*) as count FROM events e WHERE project_id = {p1:String}
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":126190}]`
+
+### eventsCountQuery — profileId + groupId + range + events + profile.* filter
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 155365/155365; wall V1/V2 = 61.1 ms / 40.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = 'redcollege') as profile on profile.id = profile_id WHERE project_id = 'redcollege' AND profile_id = '107145' AND has(groups, '271') AND toDate(created_at) BETWEEN toDate('2026-08-15 00:00:00') AND toDate('2026-08-20 23:59:59') AND name IN ('screen_view') AND profile.properties['cargo'] = 'Profesora'
+-- V2
+SELECT count(*) as count FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = {p1:String}) as profile on profile.id = profile_id WHERE project_id = {p2:String} AND profile_id = {p3:String} AND has(groups, {p4:String}) AND toDate(created_at) BETWEEN toDate({p5:String}) AND toDate({p6:String}) AND name IN {p7:Array(String)} AND profile.properties['cargo'] = 'Profesora'
+-- V2 params: {"p1":"redcollege","p2":"redcollege","p3":"107145","p4":"271","p5":"2026-08-15 00:00:00","p6":"2026-08-20 23:59:59","p7":["screen_view"]}
+```
+
+Result (first rows, identical on both sides): `[{"count":0}]`
+
+### eventsCountQuery — group.* filter (group array join)
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 159000/159000; wall V1/V2 = 11.6 ms / 12.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events e ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = 'redcollege') AS _g ON _g.id = _group_id WHERE project_id = 'redcollege' AND _g.type = 'establecimiento'
+-- V2
+SELECT count(*) as count FROM events e ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = {p1:String}) AS _g ON _g.id = _group_id WHERE project_id = {p2:String} AND _g.type = 'establecimiento'
+-- V2 params: {"p1":"redcollege","p2":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":100146}]`
+
+### eventsCountQuery — profile.* AND group.* filters together (V1 error parity)
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 281602/281602; wall V1/V2 = 67.1 ms / 56.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = 'redcollege') as profile on profile.id = profile_id ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = 'redcollege') AS _g ON _g.id = _group_id WHERE project_id = 'redcollege' AND profile.properties['cargo'] = 'Profesora' AND _g.type = 'establecimiento'
+-- V2
+SELECT count(*) as count FROM events e LEFT ANY JOIN (SELECT id, properties FROM profiles FINAL WHERE project_id = {p1:String}) as profile on profile.id = profile_id ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = {p2:String}) AS _g ON _g.id = _group_id WHERE project_id = {p3:String} AND profile.properties['cargo'] = 'Profesora' AND _g.type = 'establecimiento'
+-- V2 params: {"p1":"redcollege","p2":"redcollege","p3":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":6066}]`
+
+### eventsCountQuery — cohortId
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 0/0; wall V1/V2 = 9.6 ms / 9.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events e WHERE project_id = 'redcollege' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'redcollege')
+-- V2
+SELECT count(*) as count FROM events e WHERE project_id = {p1:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p2:String} AND project_id = {p3:String})
+-- V2 params: {"p1":"redcollege","p2":"cohort-1","p3":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":0}]`
+
+The prod-copy has no rows for this case (empty `cohort_members` / `events_bots`), so the same case also ran on the seeded `openpanel_test` copy:
+
+### eventsCountQuery — cohortId
+
+_Database: `openpanel_test`._
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 3383/3383; wall V1/V2 = 6.4 ms / 7.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events e WHERE project_id = 'm7-002-proof' AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = 'cohort-1' AND project_id = 'm7-002-proof')
+-- V2
+SELECT count(*) as count FROM events e WHERE project_id = {p1:String} AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p2:String} AND project_id = {p3:String})
+-- V2 params: {"p1":"m7-002-proof","p2":"cohort-1","p3":"m7-002-proof"}
+```
+
+Result (first rows, identical on both sides): `[{"count":2019}]`
+
+### topPagesQuery — page 2 with search
+
+**statement** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 179309/179309; wall V1/V2 = 33.4 ms / 36.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT path, count(*) as count, project_id, first_value(created_at) as first_seen, last_value(properties['__title']) as title, origin FROM events WHERE name = 'screen_view' AND project_id = 'redcollege' AND created_at > now() - INTERVAL 30 DAY AND path ILIKE '%libro%' GROUP BY path, project_id, origin ORDER BY count desc LIMIT 10 OFFSET 10
+-- V2
+SELECT path, count(*) as count, project_id, first_value(created_at) as first_seen, last_value(properties['__title']) as title, origin FROM events WHERE name = 'screen_view' AND project_id = {p1:String} AND created_at > now() - INTERVAL {p2:UInt64} DAY AND path ILIKE {p3:String} GROUP BY path, project_id, origin ORDER BY count desc LIMIT {p4:UInt64} OFFSET {p5:UInt64}
+-- V2 params: {"p1":"redcollege","p2":30,"p3":"%libro%","p4":10,"p5":10}
+```
+
+Result (first rows, identical on both sides): `[{"path":"/83/2026/libros","count":522,"project_id":"redcollege","first_seen":"2026-08-11 13:33:59.234","title":"RedCollege | Libro de Clases","origin":"https://libro.redcollege.net"},{"path":"/63/202`
+
+### topPagesQuery — first page, no search
+
+**statement** — IDENTICAL; rows V1/V2 = 20/20; rows_read V1/V2 = 179309/179309; wall V1/V2 = 30.6 ms / 32.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT path, count(*) as count, project_id, first_value(created_at) as first_seen, last_value(properties['__title']) as title, origin FROM events WHERE name = 'screen_view' AND project_id = 'redcollege' AND created_at > now() - INTERVAL 30 DAY GROUP BY path, project_id, origin ORDER BY count desc LIMIT 20 OFFSET 0
+-- V2
+SELECT path, count(*) as count, project_id, first_value(created_at) as first_seen, last_value(properties['__title']) as title, origin FROM events WHERE name = 'screen_view' AND project_id = {p1:String} AND created_at > now() - INTERVAL {p2:UInt64} DAY GROUP BY path, project_id, origin ORDER BY count desc LIMIT {p3:UInt64} OFFSET {p4:UInt64}
+-- V2 params: {"p1":"redcollege","p2":30,"p3":20,"p4":0}
+```
+
+Result (first rows, identical on both sides): `[{"path":"/","count":5026,"project_id":"redcollege","first_seen":"2026-08-11 11:35:22.248","title":"RedCollege | Dashboard","origin":"https://inicio.redcollege.net"},{"path":"/login","count":4461,"pro`
+
+### eventByIdQuery — with createdAt window
+
+**statement 1** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 106218/106218; wall V1/V2 = 36.4 ms / 32.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1
+-- V2 params: {"p1":"107145","p2":"redcollege"}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 24574/24574; wall V1/V2 = 25.2 ms / 14.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events WHERE project_id = 'redcollege' AND created_at BETWEEN '2026-08-24 20:58:43' AND '2026-08-24 20:58:45' AND id = 'db54e0ad-b152-4d6f-9e5d-2aab3e23f9ef' LIMIT 1
+-- V2
+SELECT * FROM events WHERE project_id = {p1:String} AND created_at BETWEEN {p2:String} AND {p3:String} AND id = {p4:String} LIMIT 1
+-- V2 params: {"p1":"redcollege","p2":"2026-08-24 20:58:43","p3":"2026-08-24 20:58:45","p4":"db54e0ad-b152-4d6f-9e5d-2aab3e23f9ef"}
+```
+
+### eventByIdQuery — without createdAt
+
+**statement 1** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 106218/106218; wall V1/V2 = 33.0 ms / 29.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1
+-- V2 params: {"p1":"107145","p2":"redcollege"}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 32766/32766; wall V1/V2 = 14.0 ms / 13.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events WHERE project_id = 'redcollege' AND id = 'db54e0ad-b152-4d6f-9e5d-2aab3e23f9ef' LIMIT 1
+-- V2
+SELECT * FROM events WHERE project_id = {p1:String} AND id = {p2:String} LIMIT 1
+-- V2 params: {"p1":"redcollege","p2":"db54e0ad-b152-4d6f-9e5d-2aab3e23f9ef"}
+```
+
+### topEventNamesQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 7/7; rows_read V1/V2 = 40960/40960; wall V1/V2 = 5.9 ms / 6.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT name, count() as count FROM distinct_event_names_mv WHERE project_id = 'redcollege' GROUP BY name ORDER BY count DESC LIMIT 50
+-- V2
+SELECT name, count() as count FROM distinct_event_names_mv WHERE project_id = {p1:String} GROUP BY name ORDER BY count DESC LIMIT {p2:UInt64}
+-- V2 params: {"p1":"redcollege","p2":50}
+```
+
+Result (first rows, identical on both sides): `[{"name":"screen_view","count":1235},{"name":"session_start","count":1125},{"name":"session_end","count":1117},{"name":"link_out","count":955},{"name":"tema_cambiado","count":41},{"name":"apariencia_c`
+
+### eventPropertiesQuery — all events
+
+**statement** — IDENTICAL; rows V1/V2 = 144/144; rows_read V1/V2 = 131437/131437; wall V1/V2 = 9.7 ms / 9.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT property_key, name as event_name FROM event_property_values_mv WHERE project_id = 'redcollege' GROUP BY property_key, name ORDER BY property_key ASC, name ASC LIMIT 500
+-- V2
+SELECT property_key, name as event_name FROM event_property_values_mv WHERE project_id = {p1:String} GROUP BY property_key, name ORDER BY property_key ASC, name ASC LIMIT {p2:UInt64}
+-- V2 params: {"p1":"redcollege","p2":500}
+```
+
+Result (first rows, identical on both sides): `[{"property_key":"__bot","event_name":"screen_view"},{"property_key":"__bot","event_name":"session_start"},{"property_key":"__bot_reasons","event_name":"apariencia_cambiada"},{"property_key":"__bot_re`
+
+### eventPropertiesQuery — one event
+
+**statement** — IDENTICAL; rows V1/V2 = 64/64; rows_read V1/V2 = 73728/73728; wall V1/V2 = 8.4 ms / 8.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT property_key, name as event_name FROM event_property_values_mv WHERE project_id = 'redcollege' AND name = 'screen_view' GROUP BY property_key, name ORDER BY property_key ASC, name ASC LIMIT 500
+-- V2
+SELECT property_key, name as event_name FROM event_property_values_mv WHERE project_id = {p1:String} AND name = {p2:String} GROUP BY property_key, name ORDER BY property_key ASC, name ASC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"screen_view","p3":500}
+```
+
+Result (first rows, identical on both sides): `[{"property_key":"__bot","event_name":"screen_view"},{"property_key":"__bot_reasons","event_name":"screen_view"},{"property_key":"__query.anexos","event_name":"screen_view"},{"property_key":"__query.a`
+
+### eventPropertyValuesQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 200/200; rows_read V1/V2 = 81920/81920; wall V1/V2 = 8.4 ms / 8.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT property_value as value FROM event_property_values_mv WHERE project_id = 'redcollege' AND name = 'screen_view' AND property_key = '__query.curso' ORDER BY created_at DESC LIMIT 200
+-- V2
+SELECT property_value as value FROM event_property_values_mv WHERE project_id = {p1:String} AND name = {p2:String} AND property_key = {p3:String} ORDER BY created_at DESC LIMIT {p4:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"screen_view","p3":"__query.curso","p4":200}
+```
+
+Result (first rows, identical on both sides): `[{"value":"12735"},{"value":"12734"},{"value":"12736"},{"value":"13028"},{"value":"12681"},{"value":"12770"},{"value":"12775"},{"value":"12382"},{"value":"12731"},{"value":"12810"},{"value":"12806"},{`
+
+### queryEventsQuery — default 30-day range, every equality column, properties, filters
+
+**statement** — IDENTICAL (as row sets; no ORDER BY); rows V1/V2 = 42/42; rows_read V1/V2 = 270051/270051; wall V1/V2 = 70.4 ms / 73.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events WHERE project_id = 'redcollege' AND profile_id IN ('19318', '19315') AND name IN ('screen_view', 'link_out') AND path = '/63/2026/libros' AND referrer = 'https://inicio.redcollege.net' AND referrer_name = 'https://inicio.redcollege.net' AND device = 'desktop' AND country = 'CL' AND city = 'Santiago' AND os = 'Windows' AND browser = 'Chrome' AND properties['__title'] = 'RedCollege | Libro de Clases' AND created_at BETWEEN '2026-08-05 00:00:00' AND '2026-09-04 00:00:00' AND (profile_id IN (SELECT id FROM profiles FINAL WHERE project_id = 'redcollege' AND properties['cargo'] = 'Profesora')) LIMIT 100
+-- V2
+SELECT * FROM events WHERE project_id = {p1:String} AND profile_id IN {p2:Array(String)} AND name IN {p3:Array(String)} AND path = {p4:String} AND referrer = {p5:String} AND referrer_name = {p6:String} AND device = {p7:String} AND country = {p8:String} AND city = {p9:String} AND os = {p10:String} AND browser = {p11:String} AND properties[{p12:String}] = {p13:String} AND created_at BETWEEN {p14:String} AND {p15:String} AND (profile_id IN (SELECT id FROM profiles FINAL WHERE project_id = 'redcollege' AND properties['cargo'] = 'Profesora')) LIMIT {p16:UInt64}
+-- V2 params: {"p1":"redcollege","p2":["19318","19315"],"p3":["screen_view","link_out"],"p4":"/63/2026/libros","p5":"https://inicio.redcollege.net","p6":"https://inicio.redcollege.net","p7":"desktop","p8":"CL","p9":"Santiago","p10":"Windows","p11":"Chrome","p12":"__title","p13":"RedCollege | Libro de Clases","p14":"2026-08-05 00:00:00","p15":"2026-09-04 00:00:00","p16":100}
+```
+
+### queryEventsQuery — sessionId (no date clause), profileId, explicit dates
+
+**statement** — IDENTICAL; rows V1/V2 = 20/20; rows_read V1/V2 = 24575/24575; wall V1/V2 = 22.2 ms / 15.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events WHERE project_id = 'redcollege' AND session_id = '0kiE1SjOk6U6_WDCbuyLeQ' AND profile_id = '107145' LIMIT 20
+-- V2
+SELECT * FROM events WHERE project_id = {p1:String} AND session_id = {p2:String} AND profile_id = {p3:String} LIMIT {p4:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"0kiE1SjOk6U6_WDCbuyLeQ","p3":"107145","p4":20}
+```
+
+### queryEventsQuery — sessionId + explicit startDate/endDate
+
+**statement** — IDENTICAL; rows V1/V2 = 20/20; rows_read V1/V2 = 24575/24575; wall V1/V2 = 14.6 ms / 32.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events WHERE project_id = 'redcollege' AND session_id = '0kiE1SjOk6U6_WDCbuyLeQ' AND created_at BETWEEN '2026-08-01 00:00:00' AND '2026-08-31 00:00:00' LIMIT 20
+-- V2
+SELECT * FROM events WHERE project_id = {p1:String} AND session_id = {p2:String} AND created_at BETWEEN {p3:String} AND {p4:String} LIMIT {p5:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"0kiE1SjOk6U6_WDCbuyLeQ","p3":"2026-08-01 00:00:00","p4":"2026-08-31 00:00:00","p5":20}
+```
+
+### botEventsQuery + botEventsCountQuery (event.bots)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 0/0; wall V1/V2 = 9.0 ms / 6.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events_bots WHERE project_id = 'redcollege'
+-- V2
+SELECT count(*) as count FROM events_bots WHERE project_id = {p1:String}
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":0}]`
+
+**statement 2** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 0/0; wall V1/V2 = 5.9 ms / 6.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events_bots WHERE project_id = 'redcollege' ORDER BY created_at DESC LIMIT 8 OFFSET 8
+-- V2
+SELECT * FROM events_bots WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64} OFFSET {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":8,"p3":8}
+```
+
+The prod-copy has no rows for this case (empty `cohort_members` / `events_bots`), so the same case also ran on the seeded `openpanel_test` copy:
+
+### botEventsQuery + botEventsCountQuery (event.bots)
+
+_Database: `openpanel_test`._
+
+**statement 1** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 1/1; wall V1/V2 = 50.2 ms / 7.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count FROM events_bots WHERE project_id = 'm7-002-proof'
+-- V2
+SELECT count(*) as count FROM events_bots WHERE project_id = {p1:String}
+-- V2 params: {"p1":"m7-002-proof"}
+```
+
+Result (first rows, identical on both sides): `[{"count":23}]`
+
+**statement 2** — IDENTICAL; rows V1/V2 = 8/8; rows_read V1/V2 = 46/46; wall V1/V2 = 51.9 ms / 6.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events_bots WHERE project_id = 'm7-002-proof' ORDER BY created_at DESC LIMIT 8 OFFSET 8
+-- V2
+SELECT * FROM events_bots WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64} OFFSET {p3:UInt64}
+-- V2 params: {"p1":"m7-002-proof","p2":8,"p3":8}
+```
+
+### topOriginsQuery (event.origins)
+
+**statement** — IDENTICAL; rows V1/V2 = 3/3; rows_read V1/V2 = 179309/179309; wall V1/V2 = 19.0 ms / 14.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT DISTINCT origin, count(id) as count FROM events WHERE project_id = 'redcollege' AND origin IS NOT NULL AND origin != '' AND toDate(created_at) > now() - INTERVAL 30 DAY GROUP BY origin ORDER BY count DESC LIMIT 3
+-- V2
+SELECT DISTINCT origin, count(id) as count FROM events WHERE project_id = {p1:String} AND origin IS NOT NULL AND origin != '' AND toDate(created_at) > now() - INTERVAL {p2:UInt64} DAY GROUP BY origin ORDER BY count DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":30,"p3":3}
+```
+
+Result (first rows, identical on both sides): `[{"origin":"https://libro.redcollege.net","count":85533},{"origin":"https://inicio.redcollege.net","count":27307},{"origin":"https://evalua.redcollege.net","count":4725}]`
+
diff --git a/packages/core/src/modules/event/src/event.sql.test.ts b/packages/core/src/modules/event/src/event.sql.test.ts
new file mode 100644
index 000000000..c6020d95c
--- /dev/null
+++ b/packages/core/src/modules/event/src/event.sql.test.ts
@@ -0,0 +1,378 @@
+// Shape tests for the event module's fragments: every user value binds as a
+// `{pN:Type}` parameter (nothing is interpolated), the optional clauses and
+// joins toggle exactly on V1's conditions, and `sql.id` refuses anything off
+// the column whitelists. Result-set equivalence against V1 is not tested here
+// (these run offline); it is recorded per query in event.sql.proof.md.
+
+import { describe, expect, test } from 'bun:test';
+import {
+ botEventsCountQuery,
+ botEventsQuery,
+ EVENT_LIST_COLUMNS,
+ type EventListColumn,
+ eventByIdQuery,
+ eventListQuery,
+ eventPropertiesQuery,
+ eventPropertyValuesQuery,
+ eventsCountQuery,
+ NO_FILTER_JOINS,
+ queryEventsQuery,
+ topEventNamesQuery,
+ topOriginsQuery,
+ topPagesQuery,
+} from './event.sql';
+
+const PROJECT_ID = 'proj-1';
+const HOSTILE = "x' OR 1=1 --";
+const NO_FILTERS = {};
+const CURSOR = new Date('2026-09-01T12:34:56.789Z');
+const START = new Date('2026-08-01T00:00:00.000Z');
+const END = new Date('2026-08-31T23:59:59.000Z');
+
+function collapse(text: string): string {
+ return text.replace(/\s+/g, ' ').trim();
+}
+
+describe('eventListQuery', () => {
+ const minimal = {
+ projectId: PROJECT_ID,
+ columns: ['created_at', 'id', 'name'] as const,
+ take: 50,
+ filterClauses: NO_FILTERS,
+ joins: NO_FILTER_JOINS,
+ };
+
+ test('minimal: whitelisted columns, project guard, no OFFSET, no joins', () => {
+ const { query, query_params } = eventListQuery(minimal).toStatement();
+
+ expect(query).toBe(
+ 'SELECT created_at, id, name FROM events e WHERE project_id = {p1:String} ORDER BY created_at DESC, id ASC LIMIT {p2:UInt64}'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 50 });
+ });
+
+ test('every EVENT_LIST_COLUMNS entry projects; anything else throws', () => {
+ const { query } = eventListQuery({
+ ...minimal,
+ columns: EVENT_LIST_COLUMNS,
+ }).toStatement();
+ expect(query).toStartWith(`SELECT ${EVENT_LIST_COLUMNS.join(', ')} FROM`);
+
+ expect(() =>
+ eventListQuery({
+ ...minimal,
+ columns: ['id', HOSTILE as EventListColumn],
+ })
+ ).toThrow();
+ });
+
+ test('numeric paging: OFFSET only when non-zero', () => {
+ const first = eventListQuery({ ...minimal, offset: 0 }).toStatement();
+ const later = eventListQuery({ ...minimal, offset: 100 }).toStatement();
+
+ expect(first.query).toEndWith('LIMIT {p2:UInt64}');
+ expect(later.query).toEndWith('LIMIT {p2:UInt64} OFFSET {p3:UInt64}');
+ expect(later.query_params.p3).toBe(100);
+ });
+
+ test('date cursor: lookback anchors on the cursor, then the strict upper bound', () => {
+ const { query, query_params } = eventListQuery({
+ ...minimal,
+ cursor: CURSOR,
+ lookbackDays: 7,
+ }).toStatement();
+
+ expect(query).toContain(
+ 'WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND created_at < {p3:String} AND project_id = {p4:String}'
+ );
+ expect(query_params).toMatchObject({
+ p1: '2026-09-01 12:34:56',
+ p2: 7,
+ p3: '2026-09-01 12:34:56',
+ p4: PROJECT_ID,
+ });
+ });
+
+ test('lookback without a cursor anchors on now', () => {
+ const before = Date.now();
+ const { query, query_params } = eventListQuery({
+ ...minimal,
+ lookbackDays: 30,
+ }).toStatement();
+
+ expect(query).toContain(
+ 'WHERE created_at >= toDateTime64({p1:String}, 3) - INTERVAL {p2:Float64} DAY AND project_id = {p3:String}'
+ );
+ const anchor = new Date(`${String(query_params.p1).replace(' ', 'T')}Z`);
+ expect(Math.abs(anchor.getTime() - before)).toBeLessThan(5000);
+ });
+
+ test('every scope condition binds in V1 order and none interpolates', () => {
+ const { query, query_params } = eventListQuery({
+ ...minimal,
+ profileId: HOSTILE,
+ sessionId: 'sess-1',
+ groupId: 'grp-1',
+ cohortId: 'coh-1',
+ startDate: START,
+ endDate: END,
+ events: ['a', HOSTILE],
+ filterClauses: { f0: "(path = '/')" },
+ conversionNames: ['signup'],
+ }).toStatement();
+
+ expect(query).toBe(
+ "SELECT created_at, id, name FROM events e WHERE project_id = {p1:String} AND ((device_id IN (SELECT device_id as did FROM events WHERE project_id = {p2:String} AND device_id != '' AND profile_id = {p3:String} group by did) AND profile_id = device_id) OR profile_id = {p4:String}) AND session_id = {p5:String} AND has(groups, {p6:String}) AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p7:String} AND project_id = {p8:String}) AND toDate(created_at) BETWEEN toDate({p9:String}) AND toDate({p10:String}) AND name IN {p11:Array(String)} AND (path = '/') AND name IN {p12:Array(String)} ORDER BY created_at DESC, id ASC LIMIT {p13:UInt64}"
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: PROJECT_ID,
+ p3: HOSTILE,
+ p4: HOSTILE,
+ p5: 'sess-1',
+ p6: 'grp-1',
+ p7: 'coh-1',
+ p8: PROJECT_ID,
+ p9: '2026-08-01 00:00:00',
+ p10: '2026-08-31 23:59:59',
+ p11: ['a', HOSTILE],
+ p12: ['signup'],
+ p13: 50,
+ });
+ });
+
+ test('empty events / conversionNames lists add no clause', () => {
+ const { query } = eventListQuery({
+ ...minimal,
+ events: [],
+ conversionNames: [],
+ }).toStatement();
+ expect(query).not.toContain('name IN');
+ });
+
+ test('profile join projects only whitelisted columns; group join adds ARRAY JOIN', () => {
+ const { query, query_params } = eventListQuery({
+ ...minimal,
+ joins: { profileColumns: ['email', 'properties'], groups: true },
+ }).toStatement();
+
+ expect(query).toContain(
+ 'FROM events e LEFT ANY JOIN (SELECT id, email, properties FROM profiles FINAL WHERE project_id = {p1:String}) as profile on profile.id = profile_id ARRAY JOIN groups AS _group_id LEFT ANY JOIN (SELECT id, name, type, properties FROM groups FINAL WHERE project_id = {p2:String}) AS _g ON _g.id = _group_id WHERE project_id = {p3:String}'
+ );
+ expect(query_params).toMatchObject({ p1: PROJECT_ID, p2: PROJECT_ID });
+
+ expect(() =>
+ eventListQuery({
+ ...minimal,
+ joins: { profileColumns: ['project_id'], groups: false },
+ })
+ ).toThrow();
+ });
+});
+
+describe('eventsCountQuery', () => {
+ test('uses a plain profile_id equality, not the stitching subquery', () => {
+ const { query, query_params } = eventsCountQuery({
+ projectId: PROJECT_ID,
+ profileId: HOSTILE,
+ groupId: 'grp-1',
+ cohortId: 'coh-1',
+ startDate: START,
+ endDate: END,
+ events: ['a'],
+ filterClauses: { f0: "(path = '/')" },
+ joins: NO_FILTER_JOINS,
+ }).toStatement();
+
+ expect(query).toBe(
+ "SELECT count(*) as count FROM events e WHERE project_id = {p1:String} AND profile_id = {p2:String} AND has(groups, {p3:String}) AND profile_id IN (SELECT profile_id FROM cohort_members FINAL WHERE cohort_id = {p4:String} AND project_id = {p5:String}) AND toDate(created_at) BETWEEN toDate({p6:String}) AND toDate({p7:String}) AND name IN {p8:Array(String)} AND (path = '/')"
+ );
+ expect(query).not.toContain('device_id IN');
+ expect(query_params).toMatchObject({ p1: PROJECT_ID, p2: HOSTILE });
+ });
+
+ test('shares the filter joins with the list', () => {
+ const { query } = eventsCountQuery({
+ projectId: PROJECT_ID,
+ filterClauses: NO_FILTERS,
+ joins: { profileColumns: ['email'], groups: false },
+ }).toStatement();
+
+ expect(query).toContain(
+ 'FROM events e LEFT ANY JOIN (SELECT id, email FROM profiles FINAL WHERE project_id = {p1:String}) as profile on profile.id = profile_id WHERE'
+ );
+ });
+});
+
+describe('single-event lookups', () => {
+ test('eventByIdQuery: ±1s window only with createdAt', () => {
+ const bare = eventByIdQuery({
+ projectId: PROJECT_ID,
+ id: HOSTILE,
+ }).toStatement();
+ const windowed = eventByIdQuery({
+ projectId: PROJECT_ID,
+ id: HOSTILE,
+ createdAt: CURSOR,
+ }).toStatement();
+
+ expect(bare.query).toBe(
+ 'SELECT * FROM events WHERE project_id = {p1:String} AND id = {p2:String} LIMIT 1'
+ );
+ expect(bare.query_params).toEqual({ p1: PROJECT_ID, p2: HOSTILE });
+ expect(windowed.query).toBe(
+ 'SELECT * FROM events WHERE project_id = {p1:String} AND created_at BETWEEN {p2:String} AND {p3:String} AND id = {p4:String} LIMIT 1'
+ );
+ expect(windowed.query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: '2026-09-01 12:34:55',
+ p3: '2026-09-01 12:34:57',
+ p4: HOSTILE,
+ });
+ });
+});
+
+describe('vocab queries', () => {
+ test('topEventNamesQuery reads the MV with a bound limit', () => {
+ const { query, query_params } =
+ topEventNamesQuery(PROJECT_ID).toStatement();
+ expect(query).toBe(
+ 'SELECT name, count() as count FROM distinct_event_names_mv WHERE project_id = {p1:String} GROUP BY name ORDER BY count DESC LIMIT {p2:UInt64}'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 50 });
+ });
+
+ test('eventPropertiesQuery: optional name clause, GROUP BY not DISTINCT', () => {
+ const all = eventPropertiesQuery({ projectId: PROJECT_ID }).toStatement();
+ const one = eventPropertiesQuery({
+ projectId: PROJECT_ID,
+ eventName: HOSTILE,
+ }).toStatement();
+
+ expect(all.query).toBe(
+ 'SELECT property_key, name as event_name FROM event_property_values_mv WHERE project_id = {p1:String} GROUP BY property_key, name ORDER BY property_key ASC, name ASC LIMIT {p2:UInt64}'
+ );
+ expect(one.query).toContain(
+ 'WHERE project_id = {p1:String} AND name = {p2:String} GROUP BY'
+ );
+ expect(one.query_params).toEqual({ p1: PROJECT_ID, p2: HOSTILE, p3: 500 });
+ });
+
+ test('eventPropertyValuesQuery binds all three keys', () => {
+ const { query, query_params } = eventPropertyValuesQuery({
+ projectId: PROJECT_ID,
+ eventName: 'signup',
+ propertyKey: HOSTILE,
+ }).toStatement();
+ expect(query).toBe(
+ 'SELECT property_value as value FROM event_property_values_mv WHERE project_id = {p1:String} AND name = {p2:String} AND property_key = {p3:String} ORDER BY created_at DESC LIMIT {p4:UInt64}'
+ );
+ expect(query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: 'signup',
+ p3: HOSTILE,
+ p4: 200,
+ });
+ });
+});
+
+describe('queryEventsQuery', () => {
+ test('minimal: project guard and limit', () => {
+ const { query, query_params } = queryEventsQuery({
+ projectId: PROJECT_ID,
+ equals: {},
+ filterClauses: NO_FILTERS,
+ limit: 100,
+ }).toStatement();
+ expect(query).toBe(
+ 'SELECT * FROM events WHERE project_id = {p1:String} LIMIT {p2:UInt64}'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 100 });
+ });
+
+ test('equality columns follow V1 order regardless of input order; keys bind too', () => {
+ const { query, query_params } = queryEventsQuery({
+ projectId: PROJECT_ID,
+ sessionId: 'sess-1',
+ profileId: 'prof-1',
+ profileIds: ['a', 'b'],
+ eventNames: ['x'],
+ equals: { browser: 'Firefox', path: HOSTILE, country: 'SE' },
+ properties: { [HOSTILE]: 'v' },
+ dateRange: { start: '2026-08-01 00:00:00', end: '2026-08-31 23:59:59' },
+ filterClauses: { f0: '(1 = 1)' },
+ limit: 10,
+ }).toStatement();
+
+ expect(query).toBe(
+ 'SELECT * FROM events WHERE project_id = {p1:String} AND session_id = {p2:String} AND profile_id = {p3:String} AND profile_id IN {p4:Array(String)} AND name IN {p5:Array(String)} AND path = {p6:String} AND country = {p7:String} AND browser = {p8:String} AND properties[{p9:String}] = {p10:String} AND created_at BETWEEN {p11:String} AND {p12:String} AND (1 = 1) LIMIT {p13:UInt64}'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toMatchObject({
+ p6: HOSTILE,
+ p7: 'SE',
+ p8: 'Firefox',
+ p9: HOSTILE,
+ p10: 'v',
+ });
+ });
+});
+
+describe('the trpc router queries', () => {
+ test('topPagesQuery: 30-day window, optional ILIKE, always OFFSET', () => {
+ const plain = collapse(
+ topPagesQuery({
+ projectId: PROJECT_ID,
+ take: 20,
+ offset: 0,
+ }).toStatement().query
+ );
+ const searched = topPagesQuery({
+ projectId: PROJECT_ID,
+ take: 20,
+ offset: 40,
+ search: HOSTILE,
+ }).toStatement();
+
+ expect(plain).toContain(
+ "WHERE name = 'screen_view' AND project_id = {p1:String} AND created_at > now() - INTERVAL {p2:UInt64} DAY GROUP BY path, project_id, origin ORDER BY count desc LIMIT {p3:UInt64} OFFSET {p4:UInt64}"
+ );
+ expect(collapse(searched.query)).toContain(
+ 'DAY AND path ILIKE {p3:String} GROUP BY'
+ );
+ expect(searched.query).not.toContain(HOSTILE);
+ expect(searched.query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: 30,
+ p3: `%${HOSTILE}%`,
+ p4: 20,
+ p5: 40,
+ });
+ });
+
+ test('bot events page + count read events_bots', () => {
+ const page = botEventsQuery({
+ projectId: PROJECT_ID,
+ limit: 8,
+ offset: 16,
+ }).toStatement();
+ const count = botEventsCountQuery(PROJECT_ID).toStatement();
+
+ expect(page.query).toBe(
+ 'SELECT * FROM events_bots WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64} OFFSET {p3:UInt64}'
+ );
+ expect(page.query_params).toEqual({ p1: PROJECT_ID, p2: 8, p3: 16 });
+ expect(count.query).toBe(
+ 'SELECT count(*) as count FROM events_bots WHERE project_id = {p1:String}'
+ );
+ });
+
+ test('topOriginsQuery keeps the 30-day window and top 3', () => {
+ const { query, query_params } = topOriginsQuery(PROJECT_ID).toStatement();
+ expect(query).toBe(
+ "SELECT DISTINCT origin, count(id) as count FROM events WHERE project_id = {p1:String} AND origin IS NOT NULL AND origin != '' AND toDate(created_at) > now() - INTERVAL {p2:UInt64} DAY GROUP BY origin ORDER BY count DESC LIMIT {p3:UInt64}"
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 30, p3: 3 });
+ });
+});
diff --git a/packages/core/src/modules/event/src/event.sql.ts b/packages/core/src/modules/event/src/event.sql.ts
new file mode 100644
index 000000000..7f681986f
--- /dev/null
+++ b/packages/core/src/modules/event/src/event.sql.ts
@@ -0,0 +1,438 @@
+// Every ClickHouse query the event module runs, as pure `sql` fragments
+// (ADR-013). Converted 1:1 from packages/db/src/services/event.service.ts and
+// packages/trpc/src/routers/event.ts (M7-002): the SQL text is V1's, with
+// every value bound as a `{pN:Type}` parameter instead of an escaped literal.
+// Each builder's result set was diffed against V1's on the local prod-copy;
+// the statements, params, row counts and timings are in event.sql.proof.md.
+//
+// Dates bind as V1's own `YYYY-MM-DD HH:mm:ss` strings on purpose: a String
+// param in a DateTime64 position is parsed exactly like the literal it
+// replaces, so the result sets cannot drift by a millisecond truncation.
+//
+// Cluster note (docs/ENVIRONMENT.md): `events`, `profiles`, `groups` and
+// `cohort_members` are Distributed on Cloud. The identity-stitching and cohort
+// `IN (SELECT ...)` subqueries, the profile/group LEFT ANY JOINs and any
+// `IN (SELECT ...)` a filter compiles keep V1's exact shape and run under the
+// client's `distributed_product_mode: 'allow'` as before — converting a query
+// is not the place to change its cluster semantics. Every `IN` list binds as
+// `Array(String)`, a literal list to the planner.
+
+import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';
+import { formatClickhouseDate } from './dates';
+import {
+ type CompiledFilterClauses,
+ compiledFilterFragments,
+} from './filter-clauses';
+
+const TABLE = {
+ events: 'events',
+ eventsBots: 'events_bots',
+ profiles: 'profiles',
+ groups: 'groups',
+ cohortMembers: 'cohort_members',
+ eventNamesMv: 'distinct_event_names_mv',
+ eventPropertyValuesMv: 'event_property_values_mv',
+} as const;
+
+/** Every column `getEventList` can project, in V1's select order. */
+export const EVENT_LIST_COLUMNS = [
+ 'created_at',
+ 'project_id',
+ 'id',
+ 'name',
+ 'device_id',
+ 'profile_id',
+ 'session_id',
+ 'properties',
+ 'country',
+ 'city',
+ 'region',
+ 'longitude',
+ 'latitude',
+ 'os',
+ 'os_version',
+ 'browser',
+ 'browser_version',
+ 'device',
+ 'brand',
+ 'model',
+ 'path',
+ 'origin',
+ 'referrer',
+ 'referrer_name',
+ 'referrer_type',
+ 'imported_at',
+ 'sdk_name',
+ 'sdk_version',
+ 'revenue',
+ 'groups',
+] as const;
+
+export type EventListColumn = (typeof EVENT_LIST_COLUMNS)[number];
+
+/** What the profile-filter join may project besides `id`. */
+const PROFILE_JOIN_COLUMNS = [
+ 'id',
+ 'first_name',
+ 'last_name',
+ 'email',
+ 'avatar',
+ 'properties',
+ 'is_external',
+ 'created_at',
+ 'last_seen_at',
+ 'groups',
+] as const;
+
+function optional(
+ condition: unknown,
+ fragment: () => SqlFragment
+): SqlFragment {
+ return condition ? fragment() : sql.empty;
+}
+
+function calendarDayRange(startDate: Date, endDate: Date): SqlFragment {
+ return sql`toDate(created_at) BETWEEN toDate(${sql.string(formatClickhouseDate(startDate))}) AND toDate(${sql.string(formatClickhouseDate(endDate))})`;
+}
+
+export interface EventFilterJoins {
+ /** Profile columns the compiled `profile.*` filters read; empty = no join. */
+ profileColumns: readonly string[];
+ /** Whether a compiled `group.*` filter reads the `_g` alias. */
+ groups: boolean;
+}
+
+export const NO_FILTER_JOINS: EventFilterJoins = {
+ profileColumns: [],
+ groups: false,
+};
+
+/** The joins the compiled filters need, with V1's leading space; empty = none. */
+function filterJoins(projectId: string, joins: EventFilterJoins): SqlFragment {
+ const parts: SqlFragment[] = [];
+ if (joins.profileColumns.length > 0) {
+ const columns = sql.join(
+ joins.profileColumns.map((column) =>
+ sql.id(column, PROFILE_JOIN_COLUMNS)
+ ),
+ ', '
+ );
+ parts.push(
+ sql`LEFT ANY JOIN (SELECT id, ${columns} FROM ${sql.id(TABLE.profiles)} FINAL WHERE project_id = ${sql.string(projectId)}) as profile on profile.id = profile_id`
+ );
+ }
+ if (joins.groups) {
+ parts.push(sql`ARRAY JOIN groups AS _group_id`);
+ parts.push(
+ sql`LEFT ANY JOIN (SELECT id, name, type, properties FROM ${sql.id(TABLE.groups)} FINAL WHERE project_id = ${sql.string(projectId)}) AS _g ON _g.id = _group_id`
+ );
+ }
+ if (parts.length === 0) {
+ return sql.empty;
+ }
+ return sql` ${sql.join(parts, ' ')}`;
+}
+
+export interface EventListQuery {
+ projectId: string;
+ columns: readonly EventListColumn[];
+ take: number;
+ /** Numeric cursor pages: `OFFSET` only when non-zero, as V1. */
+ offset?: number;
+ /** Date cursor pages: strict upper bound plus the lookback window. */
+ cursor?: Date;
+ /** The `created_at >= now|cursor - INTERVAL n DAY` narrowing; absent = none. */
+ lookbackDays?: number;
+ profileId?: string;
+ sessionId?: string;
+ groupId?: string;
+ cohortId?: string;
+ startDate?: Date;
+ endDate?: Date;
+ events?: readonly string[];
+ filterClauses: CompiledFilterClauses;
+ joins: EventFilterJoins;
+ /** `event.conversions`' extra `name IN (..)`, appended after the filters as V1 did. */
+ conversionNames?: readonly string[];
+}
+
+/** V1's `sb.where` in insertion order — the text has to match a cached V1 plan byte for byte. */
+function eventListConditions(query: EventListQuery): SqlFragment[] {
+ const conditions: SqlFragment[] = [];
+ const projectId = sql.string(query.projectId);
+
+ if (query.lookbackDays !== undefined) {
+ const anchor = sql.string(formatClickhouseDate(query.cursor ?? new Date()));
+ conditions.push(
+ sql`created_at >= toDateTime64(${anchor}, 3) - INTERVAL ${sql.float64(query.lookbackDays)} DAY`
+ );
+ }
+ if (query.cursor) {
+ conditions.push(
+ sql`created_at < ${sql.string(formatClickhouseDate(query.cursor))}`
+ );
+ }
+ conditions.push(sql`project_id = ${projectId}`);
+
+ if (query.profileId) {
+ // Identity stitching: pre-identification anonymous events from devices
+ // this profile has used, plus the profile's own identified events. The
+ // `profile_id = device_id` guard keeps another user's identified events
+ // out when a device_id collides (NAT, shared UA, server-side senders).
+ const profileId = sql.string(query.profileId);
+ conditions.push(
+ sql`((device_id IN (SELECT device_id as did FROM ${sql.id(TABLE.events)} WHERE project_id = ${projectId} AND device_id != '' AND profile_id = ${profileId} group by did) AND profile_id = device_id) OR profile_id = ${profileId})`
+ );
+ }
+ if (query.sessionId) {
+ conditions.push(sql`session_id = ${sql.string(query.sessionId)}`);
+ }
+ if (query.groupId) {
+ conditions.push(sql`has(groups, ${sql.string(query.groupId)})`);
+ }
+ if (query.cohortId) {
+ conditions.push(
+ sql`profile_id IN (SELECT profile_id FROM ${sql.id(TABLE.cohortMembers)} FINAL WHERE cohort_id = ${sql.string(query.cohortId)} AND project_id = ${projectId})`
+ );
+ }
+ if (query.startDate && query.endDate) {
+ conditions.push(calendarDayRange(query.startDate, query.endDate));
+ }
+ if (query.events && query.events.length > 0) {
+ conditions.push(sql`name IN ${sql.array('String', query.events)}`);
+ }
+ conditions.push(...compiledFilterFragments(query.filterClauses));
+ if (query.conversionNames && query.conversionNames.length > 0) {
+ conditions.push(sql`name IN ${sql.array('String', query.conversionNames)}`);
+ }
+ return conditions;
+}
+
+function eventListWhere(query: EventListQuery): SqlFragment {
+ const conditions = eventListConditions(query);
+ return sql`WHERE ${sql.join(conditions, ' AND ')}`;
+}
+
+export function eventListQuery(query: EventListQuery): SqlFragment {
+ const columns = sql.join(
+ query.columns.map((column) => sql.id(column, EVENT_LIST_COLUMNS)),
+ ', '
+ );
+ const joins = filterJoins(query.projectId, query.joins);
+ return sql`SELECT ${columns} FROM ${sql.id(TABLE.events)} e${joins} ${eventListWhere(query)} ORDER BY created_at DESC, id ASC LIMIT ${sql.uint64(query.take)}${optional(
+ query.offset,
+ () => sql` OFFSET ${sql.uint64(query.offset as number)}`
+ )}`;
+}
+
+export type EventsCountQuery = Pick<
+ EventListQuery,
+ | 'projectId'
+ | 'profileId'
+ | 'groupId'
+ | 'cohortId'
+ | 'startDate'
+ | 'endDate'
+ | 'events'
+ | 'filterClauses'
+ | 'joins'
+>;
+
+/** Same shape as the list minus paging; `profile_id = ..` here, not the stitching subquery. */
+export function eventsCountQuery(query: EventsCountQuery): SqlFragment {
+ const projectId = sql.string(query.projectId);
+ const conditions: SqlFragment[] = [sql`project_id = ${projectId}`];
+ if (query.profileId) {
+ conditions.push(sql`profile_id = ${sql.string(query.profileId)}`);
+ }
+ if (query.groupId) {
+ conditions.push(sql`has(groups, ${sql.string(query.groupId)})`);
+ }
+ if (query.cohortId) {
+ conditions.push(
+ sql`profile_id IN (SELECT profile_id FROM ${sql.id(TABLE.cohortMembers)} FINAL WHERE cohort_id = ${sql.string(query.cohortId)} AND project_id = ${projectId})`
+ );
+ }
+ if (query.startDate && query.endDate) {
+ conditions.push(calendarDayRange(query.startDate, query.endDate));
+ }
+ if (query.events && query.events.length > 0) {
+ conditions.push(sql`name IN ${sql.array('String', query.events)}`);
+ }
+ conditions.push(...compiledFilterFragments(query.filterClauses));
+ const joins = filterJoins(query.projectId, query.joins);
+ return sql`SELECT count(*) as count FROM ${sql.id(TABLE.events)} e${joins} WHERE ${sql.join(conditions, ' AND ')}`;
+}
+
+const TOP_PAGES_WINDOW_DAYS = 30;
+
+export function topPagesQuery(query: {
+ projectId: string;
+ take: number;
+ offset: number;
+ search?: string;
+}): SqlFragment {
+ return sql`
+ SELECT path, count(*) as count, project_id, first_value(created_at) as first_seen, last_value(properties['__title']) as title, origin
+ FROM ${sql.id(TABLE.events)}
+ WHERE name = 'screen_view'
+ AND project_id = ${sql.string(query.projectId)}
+ AND created_at > now() - INTERVAL ${sql.uint64(TOP_PAGES_WINDOW_DAYS)} DAY
+ ${optional(query.search, () => sql`AND path ILIKE ${sql.string(`%${query.search}%`)}`)}
+ GROUP BY path, project_id, origin
+ ORDER BY count desc
+ LIMIT ${sql.uint64(query.take)}
+ OFFSET ${sql.uint64(query.offset)}
+ `;
+}
+
+const BY_ID_WINDOW_MS = 1000;
+
+/** `createdAt` narrows to a ±1s window so the primary key prunes the scan. */
+export function eventByIdQuery(query: {
+ projectId: string;
+ id: string;
+ createdAt?: Date;
+}): SqlFragment {
+ return sql`SELECT * FROM ${sql.id(TABLE.events)} WHERE project_id = ${sql.string(query.projectId)}${optional(
+ query.createdAt,
+ () => {
+ const createdAt = query.createdAt as Date;
+ const from = new Date(createdAt.getTime() - BY_ID_WINDOW_MS);
+ const to = new Date(createdAt.getTime() + BY_ID_WINDOW_MS);
+ return sql` AND created_at BETWEEN ${sql.string(formatClickhouseDate(from))} AND ${sql.string(formatClickhouseDate(to))}`;
+ }
+ )} AND id = ${sql.string(query.id)} LIMIT 1`;
+}
+
+const TOP_EVENT_NAMES_LIMIT = 50;
+
+export function topEventNamesQuery(projectId: string): SqlFragment {
+ return sql`SELECT name, count() as count FROM ${sql.id(TABLE.eventNamesMv)} WHERE project_id = ${sql.string(projectId)} GROUP BY name ORDER BY count DESC LIMIT ${sql.uint64(TOP_EVENT_NAMES_LIMIT)}`;
+}
+
+const EVENT_PROPERTIES_LIMIT = 500;
+
+// GROUP BY rather than DISTINCT: same (property_key, name) set, but a
+// multi-column DISTINCT cannot use the epv_keys aggregating projection and
+// degrades to a full scan of the project's MV slice. `name` tie-breaks the
+// ORDER BY so the LIMIT window is deterministic.
+export function eventPropertiesQuery(query: {
+ projectId: string;
+ eventName?: string;
+}): SqlFragment {
+ return sql`SELECT property_key, name as event_name FROM ${sql.id(TABLE.eventPropertyValuesMv)} WHERE project_id = ${sql.string(query.projectId)}${optional(
+ query.eventName,
+ () => sql` AND name = ${sql.string(query.eventName as string)}`
+ )} GROUP BY property_key, name ORDER BY property_key ASC, name ASC LIMIT ${sql.uint64(EVENT_PROPERTIES_LIMIT)}`;
+}
+
+const EVENT_PROPERTY_VALUES_LIMIT = 200;
+
+export function eventPropertyValuesQuery(query: {
+ projectId: string;
+ eventName: string;
+ propertyKey: string;
+}): SqlFragment {
+ return sql`SELECT property_value as value FROM ${sql.id(TABLE.eventPropertyValuesMv)} WHERE project_id = ${sql.string(query.projectId)} AND name = ${sql.string(query.eventName)} AND property_key = ${sql.string(query.propertyKey)} ORDER BY created_at DESC LIMIT ${sql.uint64(EVENT_PROPERTY_VALUES_LIMIT)}`;
+}
+
+/** The `= value` columns `queryEventsCore` accepts, in V1's clause order. */
+export const QUERY_EVENTS_EQUALITY_COLUMNS = [
+ 'path',
+ 'referrer',
+ 'referrer_name',
+ 'referrer_type',
+ 'device',
+ 'country',
+ 'city',
+ 'os',
+ 'browser',
+] as const;
+
+export type QueryEventsEqualityColumn =
+ (typeof QUERY_EVENTS_EQUALITY_COLUMNS)[number];
+
+export interface QueryEventsQuery {
+ projectId: string;
+ sessionId?: string;
+ profileId?: string;
+ profileIds?: readonly string[];
+ eventNames?: readonly string[];
+ equals: Partial<Record<QueryEventsEqualityColumn, string>>;
+ properties?: Record<string, string>;
+ /** Already resolved `YYYY-MM-DD HH:mm:ss` bounds; absent = no date clause. */
+ dateRange?: { start: string; end: string };
+ filterClauses: CompiledFilterClauses;
+ limit: number;
+}
+
+function queryEventsConditions(query: QueryEventsQuery): SqlFragment[] {
+ const conditions: SqlFragment[] = [
+ sql`project_id = ${sql.string(query.projectId)}`,
+ ];
+ if (query.sessionId) {
+ conditions.push(sql`session_id = ${sql.string(query.sessionId)}`);
+ }
+ if (query.profileId) {
+ conditions.push(sql`profile_id = ${sql.string(query.profileId)}`);
+ }
+ if (query.profileIds?.length) {
+ conditions.push(
+ sql`profile_id IN ${sql.array('String', query.profileIds)}`
+ );
+ }
+ if (query.eventNames?.length) {
+ conditions.push(sql`name IN ${sql.array('String', query.eventNames)}`);
+ }
+ for (const column of QUERY_EVENTS_EQUALITY_COLUMNS) {
+ const value = query.equals[column];
+ if (value) {
+ conditions.push(
+ sql`${sql.id(column, QUERY_EVENTS_EQUALITY_COLUMNS)} = ${sql.string(value)}`
+ );
+ }
+ }
+ if (query.properties) {
+ for (const [key, value] of Object.entries(query.properties)) {
+ conditions.push(
+ sql`properties[${sql.string(key)}] = ${sql.string(value)}`
+ );
+ }
+ }
+ if (query.dateRange) {
+ conditions.push(
+ sql`created_at BETWEEN ${sql.string(query.dateRange.start)} AND ${sql.string(query.dateRange.end)}`
+ );
+ }
+ conditions.push(...compiledFilterFragments(query.filterClauses));
+ return conditions;
+}
+
+export function queryEventsQuery(query: QueryEventsQuery): SqlFragment {
+ return sql`SELECT * FROM ${sql.id(TABLE.events)} WHERE ${sql.join(
+ queryEventsConditions(query),
+ ' AND '
+ )} LIMIT ${sql.uint64(query.limit)}`;
+}
+
+// ---- packages/trpc/src/routers/event.ts's inline queries
+
+export function botEventsQuery(query: {
+ projectId: string;
+ limit: number;
+ offset: number;
+}): SqlFragment {
+ return sql`SELECT * FROM ${sql.id(TABLE.eventsBots)} WHERE project_id = ${sql.string(query.projectId)} ORDER BY created_at DESC LIMIT ${sql.uint64(query.limit)} OFFSET ${sql.uint64(query.offset)}`;
+}
+
+export function botEventsCountQuery(projectId: string): SqlFragment {
+ return sql`SELECT count(*) as count FROM ${sql.id(TABLE.eventsBots)} WHERE project_id = ${sql.string(projectId)}`;
+}
+
+const ORIGINS_WINDOW_DAYS = 30;
+const ORIGINS_LIMIT = 3;
+
+export function topOriginsQuery(projectId: string): SqlFragment {
+ return sql`SELECT DISTINCT origin, count(id) as count FROM ${sql.id(TABLE.events)} WHERE project_id = ${sql.string(projectId)} AND origin IS NOT NULL AND origin != '' AND toDate(created_at) > now() - INTERVAL ${sql.uint64(ORIGINS_WINDOW_DAYS)} DAY GROUP BY origin ORDER BY count DESC LIMIT ${sql.uint64(ORIGINS_LIMIT)}`;
+}
diff --git a/packages/core/src/modules/event/src/filter-clauses.ts b/packages/core/src/modules/event/src/filter-clauses.ts
new file mode 100644
index 000000000..4a4442c24
--- /dev/null
+++ b/packages/core/src/modules/event/src/filter-clauses.ts
@@ -0,0 +1,31 @@
+// The ONE place this module splices pre-compiled filter SQL.
+//
+// `buildFilterWhere` (packages/db/src/services/filter-where.service.ts) is
+// V1's filter compiler and still emits sqlstring-escaped SQL text: ADR-013
+// leaves the filter compilers as they are ("two behaviours, not two builders")
+// until the shared filter compiler converts to fragments. Until then a
+// `sql`-tag query that takes `IChartEventFilter[]` has to splice that text,
+// and it does so here — through the same `SqlFragment` constructor `sql.id`
+// uses — so the bridge is one grep away from deletion when the compiler moves,
+// rather than a `sql.raw()` that would outlive it.
+
+import { SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';
+
+export type CompiledFilterClauses = Record<string, string>;
+
+/** Each compiled clause is already parenthesised by the compiler. */
+export function compiledFilterFragments(
+ clauses: CompiledFilterClauses
+): SqlFragment[] {
+ return Object.values(clauses).map((clause) => new SqlFragment([clause], []));
+}
+
+export function spliceCompiledFilters(
+ clauses: CompiledFilterClauses
+): SqlFragment {
+ const fragments = compiledFilterFragments(clauses);
+ if (fragments.length === 0) {
+ return sql.empty;
+ }
+ return sql`AND ${sql.join(fragments, ' AND ')}`;
+}
diff --git a/packages/core/src/modules/group/group.constants.ts b/packages/core/src/modules/group/group.constants.ts
new file mode 100644
index 000000000..dafa3d641
--- /dev/null
+++ b/packages/core/src/modules/group/group.constants.ts
@@ -0,0 +1,35 @@
+// Moved from packages/validation/src/index.ts (M7-002, ADR-008's module map:
+// group owns "C"). validation's index re-exports this file's
+// `./modules/group/group.constants` subpath, so packages/trpc's group router
+// and apps/start's add-group / edit-group modals keep resolving these symbols
+// through @openpanel/validation unchanged.
+//
+// Isomorphic by the AGENTS.md rule: zod and nothing else.
+
+import { z } from 'zod';
+
+export const zGroupId = z
+ .string()
+ .min(1)
+ .regex(
+ /^[a-z0-9_-]+$/,
+ 'ID must only contain lowercase letters, digits, hyphens, or underscores'
+ );
+
+export const zCreateGroup = z.object({
+ id: zGroupId,
+ projectId: z.string(),
+ type: z.string().min(1),
+ name: z.string().min(1),
+ properties: z.record(z.string(), z.string()).default({}),
+});
+export type ICreateGroup = z.infer<typeof zCreateGroup>;
+
+export const zUpdateGroup = z.object({
+ id: z.string().min(1),
+ projectId: z.string(),
+ type: z.string().min(1).optional(),
+ name: z.string().min(1).optional(),
+ properties: z.record(z.string(), z.string()).optional(),
+});
+export type IUpdateGroup = z.infer<typeof zUpdateGroup>;
diff --git a/packages/core/src/modules/group/group.rpc.test.ts b/packages/core/src/modules/group/group.rpc.test.ts
new file mode 100644
index 000000000..9003fbf07
--- /dev/null
+++ b/packages/core/src/modules/group/group.rpc.test.ts
@@ -0,0 +1,81 @@
+// Only the "is anyone logged in" boundary is exercised here — no database.
+// The access-check + query bodies ride on @openpanel/db (lazy-loaded, see
+// group.service.ts's header); wiring this router end-to-end against a real
+// ClickHouse is P6's (protectedProcedure) job — see group.rpc.ts's header.
+// Same shape as session.rpc.test.ts.
+
+import { expect, test } from 'bun:test';
+import { stubHttpCtx } from '../../../test/rpc-fixtures';
+import { makeTrpcContext } from '../../rpc/base';
+import type { CookieOptions } from '../../shared/cookie';
+import { groupRouter } from './group.rpc';
+
+const COOKIE_OPTIONS: CookieOptions = {
+ domain: '.openpanel.dev',
+ secure: true,
+ sameSite: 'lax',
+ httpOnly: true,
+ path: '/',
+};
+
+const EMPTY_SESSION = { session: null, user: null, userId: null };
+const REF = { id: 'grp_1', projectId: 'proj_1' };
+
+async function anonCaller() {
+ const { ctx } = stubHttpCtx({}, EMPTY_SESSION);
+ const trpcCtx = await makeTrpcContext(ctx, new Headers(), {
+ cookieOptions: COOKIE_OPTIONS,
+ });
+ return groupRouter.createCaller(trpcCtx);
+}
+
+const UNAUTHORIZED = { code: 'UNAUTHORIZED' };
+
+test('every query rejects an unauthenticated caller before touching a database', async () => {
+ const caller = await anonCaller();
+ await expect(caller.list({ projectId: 'proj_1' })).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(caller.byId(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.types({ projectId: 'proj_1' })).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(caller.metrics(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.activity(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.memberGrowth(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(
+ caller.listProfiles({ projectId: 'proj_1', groupId: 'grp_1' })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.mostEvents(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.popularRoutes(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(
+ caller.properties({ projectId: 'proj_1' })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(
+ caller.listByIds({ projectId: 'proj_1', ids: ['grp_1'] })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+});
+
+test('every mutation rejects an unauthenticated caller before touching a database', async () => {
+ const caller = await anonCaller();
+ await expect(
+ caller.create({ ...REF, type: 'company', name: 'Acme', properties: {} })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.update({ ...REF, name: 'Acme' })).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(caller.delete(REF)).rejects.toMatchObject(UNAUTHORIZED);
+});
+
+test('create rejects an id outside zGroupId at the input boundary', async () => {
+ const caller = await anonCaller();
+ await expect(
+ caller.create({
+ id: 'Not Valid',
+ projectId: 'proj_1',
+ type: 'company',
+ name: 'Acme',
+ properties: {},
+ })
+ ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+});
diff --git a/packages/core/src/modules/group/group.rpc.ts b/packages/core/src/modules/group/group.rpc.ts
new file mode 100644
index 000000000..e2c4b3987
--- /dev/null
+++ b/packages/core/src/modules/group/group.rpc.ts
@@ -0,0 +1,181 @@
+// Ported from packages/trpc/src/routers/group.ts (M7-002).
+//
+// Same arrangement as session.rpc.ts: V1's `protectedProcedure` stack lands
+// with auth (P6), so until then each procedure does its own "is anyone logged
+// in" + `requireProjectAccess` off the `projectId` input (`read` for queries,
+// `write` for the three mutations), which is what V1's `enforceUserIsAuthed`
+// + `enforceAccess` middleware pair does implicitly. packages/trpc's group
+// router delegates its handler bodies onto `./group.service` while keeping
+// V1's own `protectedProcedure` stack.
+
+import { z } from 'zod';
+import { createTRPCRouter, procedure } from '../../rpc/base';
+import { TRPCAccessError } from '../../rpc/errors';
+import { zCreateGroup, zUpdateGroup } from './group.constants';
+import {
+ createGroup,
+ deleteGroup,
+ getGroupActivity,
+ getGroupById,
+ getGroupListPage,
+ getGroupMemberGrowth,
+ getGroupMemberProfilesPage,
+ getGroupMetrics,
+ getGroupMostEvents,
+ getGroupPopularRoutes,
+ getGroupPropertyKeys,
+ getGroupsByIds,
+ getGroupTypes,
+ updateGroup,
+} from './group.service';
+
+const DEFAULT_LIST_TAKE = 50;
+
+const zGroupRef = z.object({ id: z.string(), projectId: z.string() });
+
+function loadAccessChecks() {
+ return import('./src/access');
+}
+
+function requireLogin(userId: string | null | undefined): string {
+ if (!userId) {
+ throw new TRPCAccessError('Not authenticated');
+ }
+ return userId;
+}
+
+async function requireAccess(
+ userId: string,
+ projectId: string,
+ level: 'read' | 'write'
+) {
+ const { requireProjectAccess } = await loadAccessChecks();
+ await requireProjectAccess({ userId, projectId, level });
+}
+
+export const groupRouter = createTRPCRouter({
+ list: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ cursor: z.number().optional(),
+ take: z.number().default(DEFAULT_LIST_TAKE),
+ search: z.string().optional(),
+ type: z.string().optional(),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupListPage(input);
+ }),
+
+ byId: procedure.input(zGroupRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupById(input.id, input.projectId);
+ }),
+
+ create: procedure.input(zCreateGroup).mutation(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'write');
+
+ return createGroup(input);
+ }),
+
+ update: procedure.input(zUpdateGroup).mutation(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'write');
+
+ const { id, projectId, ...data } = input;
+ return updateGroup(id, projectId, data);
+ }),
+
+ delete: procedure.input(zGroupRef).mutation(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'write');
+
+ return deleteGroup(input.id, input.projectId);
+ }),
+
+ types: procedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupTypes(input.projectId);
+ }),
+
+ metrics: procedure.input(zGroupRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupMetrics(input.id, input.projectId);
+ }),
+
+ activity: procedure.input(zGroupRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupActivity(input.id, input.projectId);
+ }),
+
+ memberGrowth: procedure.input(zGroupRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupMemberGrowth(input.id, input.projectId);
+ }),
+
+ listProfiles: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ groupId: z.string(),
+ cursor: z.number().optional(),
+ take: z.number().default(DEFAULT_LIST_TAKE),
+ search: z.string().optional(),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupMemberProfilesPage(input);
+ }),
+
+ mostEvents: procedure.input(zGroupRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupMostEvents(input.id, input.projectId);
+ }),
+
+ popularRoutes: procedure.input(zGroupRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupPopularRoutes(input.id, input.projectId);
+ }),
+
+ properties: procedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupPropertyKeys(input.projectId);
+ }),
+
+ listByIds: procedure
+ .input(z.object({ projectId: z.string(), ids: z.array(z.string()) }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireAccess(userId, input.projectId, 'read');
+
+ return getGroupsByIds(input.projectId, input.ids);
+ }),
+});
diff --git a/packages/core/src/modules/group/group.service.ts b/packages/core/src/modules/group/group.service.ts
new file mode 100644
index 000000000..c2917e78e
--- /dev/null
+++ b/packages/core/src/modules/group/group.service.ts
@@ -0,0 +1,482 @@
+// Ported from packages/db/src/services/group.service.ts plus the query bodies
+// of packages/trpc/src/routers/group.ts (M7-002). The db file is now a
+// re-export shim over this one, so @openpanel/db importers (the assistant/mcp
+// tools, apps/api's insights controller) keep working while V1 runs
+// (DELEGATE PATTERN); the trpc router delegates its handler bodies here.
+//
+// Every query is a `sql` fragment (src/group.sql.ts), converted one at a time
+// with a result-set proof each, per ADR-013.
+//
+// db/ch access is LAZY (`loadChClient`) for the reason insight.service.ts's
+// header gives: constructing @openpanel/db's clients at import time spawns a
+// pino-pretty worker per `bun test --isolate` file.
+
+import { toDots } from '@openpanel/common';
+import type { ServiceDeps } from '../../services';
+import { getProfiles, type IServiceProfile } from '../profile/profile.service';
+import { formatClickhouseDate } from './src/dates';
+import {
+ groupActivityQuery,
+ groupByIdQuery,
+ groupEventMetricsQuery,
+ groupListCountQuery,
+ groupListQuery,
+ groupMemberGrowthQuery,
+ groupMemberProfilesQuery,
+ groupMostEventsQuery,
+ groupPopularRoutesQuery,
+ groupPropertyKeysQuery,
+ groupStatsQuery,
+ groupsByIdsQuery,
+ groupTypesQuery,
+ groupUniqueProfilesQuery,
+} from './src/group.sql';
+
+const GROUPS_TABLE = 'groups';
+const FIND_GROUPS_DEFAULT_LIMIT = 20;
+const GROUP_MEMBERS_DEFAULT_LIMIT = 10;
+
+function loadChClient() {
+ return import('@openpanel/db/src/clickhouse/client');
+}
+
+export interface IServiceGroup {
+ id: string;
+ projectId: string;
+ type: string;
+ name: string;
+ properties: Record<string, unknown>;
+ createdAt: Date;
+ updatedAt: Date;
+}
+
+export interface IServiceUpsertGroup {
+ id: string;
+ projectId: string;
+ type: string;
+ name: string;
+ properties?: Record<string, unknown>;
+}
+
+interface IClickhouseGroup {
+ project_id: string;
+ id: string;
+ type: string;
+ name: string;
+ properties: Record<string, string>;
+ created_at: string;
+ version: string;
+}
+
+function transformGroup(row: IClickhouseGroup): IServiceGroup {
+ return {
+ id: row.id,
+ projectId: row.project_id,
+ type: row.type,
+ name: row.name,
+ properties: row.properties,
+ createdAt: new Date(row.created_at),
+ updatedAt: new Date(Number(row.version)),
+ };
+}
+
+function pageOffset(cursor: number | undefined, take: number): number {
+ return Math.max(0, (cursor ?? 0) * take);
+}
+
+async function writeGroupToCh(
+ group: {
+ id: string;
+ projectId: string;
+ type: string;
+ name: string;
+ properties: Record<string, string>;
+ createdAt?: Date;
+ },
+ deleted = 0
+) {
+ const { ch } = await loadChClient();
+ await ch.insert({
+ format: 'JSONEachRow',
+ table: GROUPS_TABLE,
+ values: [
+ {
+ project_id: group.projectId,
+ id: group.id,
+ type: group.type,
+ name: group.name,
+ properties: group.properties,
+ created_at: formatClickhouseDate(group.createdAt ?? new Date()),
+ version: Date.now(),
+ deleted,
+ },
+ ],
+ });
+}
+
+export async function upsertGroup(input: IServiceUpsertGroup) {
+ const existing = await getGroupById(input.id, input.projectId);
+ await writeGroupToCh({
+ id: input.id,
+ projectId: input.projectId,
+ type: input.type,
+ name: input.name,
+ properties: toDots({
+ ...(existing?.properties ?? {}),
+ ...(input.properties ?? {}),
+ }),
+ createdAt: existing?.createdAt,
+ });
+}
+
+export async function getGroupById(
+ id: string,
+ projectId: string
+): Promise<IServiceGroup | null> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<IClickhouseGroup>(
+ groupByIdQuery({ id, projectId })
+ );
+ return rows[0] ? transformGroup(rows[0]) : null;
+}
+
+export interface GetGroupListOptions {
+ projectId: string;
+ cursor?: number;
+ take: number;
+ search?: string;
+ type?: string;
+}
+
+export async function getGroupList({
+ projectId,
+ cursor,
+ take,
+ search,
+ type,
+}: GetGroupListOptions): Promise<IServiceGroup[]> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<IClickhouseGroup>(
+ groupListQuery({
+ projectId,
+ take,
+ offset: pageOffset(cursor, take),
+ search,
+ type,
+ })
+ );
+ return rows.map(transformGroup);
+}
+
+export async function getGroupListCount({
+ projectId,
+ type,
+ search,
+}: {
+ projectId: string;
+ type?: string;
+ search?: string;
+}): Promise<number> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ count: number }>(
+ groupListCountQuery({ projectId, type, search })
+ );
+ return rows[0]?.count ?? 0;
+}
+
+export async function getGroupTypes(projectId: string): Promise<string[]> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ type: string }>(groupTypesQuery(projectId));
+ return rows.map((r) => r.type);
+}
+
+export async function createGroup(input: IServiceUpsertGroup) {
+ await upsertGroup(input);
+ return getGroupById(input.id, input.projectId);
+}
+
+export async function updateGroup(
+ id: string,
+ projectId: string,
+ data: { type?: string; name?: string; properties?: Record<string, unknown> }
+) {
+ const existing = await getGroupById(id, projectId);
+ if (!existing) {
+ throw new Error(`Group ${id} not found`);
+ }
+ const mergedProperties = {
+ ...(existing.properties ?? {}),
+ ...(data.properties ?? {}),
+ };
+ const normalizedProperties = toDots(
+ mergedProperties as Record<string, unknown>
+ );
+ const updated = {
+ id,
+ projectId,
+ type: data.type ?? existing.type,
+ name: data.name ?? existing.name,
+ properties: normalizedProperties,
+ createdAt: existing.createdAt,
+ };
+ await writeGroupToCh(updated);
+ return { ...existing, ...updated };
+}
+
+export async function deleteGroup(id: string, projectId: string) {
+ const existing = await getGroupById(id, projectId);
+ if (!existing) {
+ throw new Error(`Group ${id} not found`);
+ }
+ await writeGroupToCh(
+ {
+ id,
+ projectId,
+ type: existing.type,
+ name: existing.name,
+ properties: existing.properties as Record<string, string>,
+ createdAt: existing.createdAt,
+ },
+ 1
+ );
+ return existing;
+}
+
+export async function getGroupPropertyKeys(
+ projectId: string
+): Promise<string[]> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ key: string }>(
+ groupPropertyKeysQuery(projectId)
+ );
+ return rows.map((r) => r.key).sort();
+}
+
+export interface IServiceGroupStats {
+ groupId: string;
+ memberCount: number;
+ lastActiveAt: Date | null;
+}
+
+export async function getGroupStats(
+ projectId: string,
+ groupIds: string[]
+): Promise<Map<string, IServiceGroupStats>> {
+ if (groupIds.length === 0) {
+ return new Map();
+ }
+
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{
+ group_id: string;
+ member_count: number;
+ last_active_at: string;
+ }>(groupStatsQuery({ projectId, groupIds }));
+
+ return new Map(
+ rows.map((r) => [
+ r.group_id,
+ {
+ groupId: r.group_id,
+ memberCount: r.member_count,
+ lastActiveAt: r.last_active_at ? new Date(r.last_active_at) : null,
+ },
+ ])
+ );
+}
+
+export async function getGroupsByIds(
+ projectId: string,
+ ids: string[]
+): Promise<IServiceGroup[]> {
+ if (ids.length === 0) {
+ return [];
+ }
+
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<IClickhouseGroup>(
+ groupsByIdsQuery({ projectId, ids })
+ );
+ return rows.map(transformGroup);
+}
+
+export interface GetGroupMemberProfilesOptions {
+ projectId: string;
+ groupId: string;
+ cursor?: number;
+ take: number;
+ search?: string;
+}
+
+export async function getGroupMemberProfiles({
+ projectId,
+ groupId,
+ cursor,
+ take,
+ search,
+}: GetGroupMemberProfilesOptions): Promise<{
+ data: IServiceProfile[];
+ count: number;
+}> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ id: string; total_count: number }>(
+ groupMemberProfilesQuery({
+ projectId,
+ groupId,
+ take,
+ offset: pageOffset(cursor, take),
+ search: search?.trim() || undefined,
+ })
+ );
+
+ const count = rows[0]?.total_count ?? 0;
+ const profileIds = rows.map((r) => r.id);
+
+ if (profileIds.length === 0) {
+ return { data: [], count };
+ }
+
+ const profiles = await getProfiles(profileIds, projectId);
+ const byId = new Map(profiles.map((p) => [p.id, p]));
+ const data = profileIds
+ .map((id) => byId.get(id))
+ .filter(Boolean) as IServiceProfile[];
+ return { data, count };
+}
+
+// ---- the trpc group router's bodies
+
+/** `list`: the page plus each group's member count / last activity. */
+export async function getGroupListPage(input: GetGroupListOptions) {
+ const [data, count] = await Promise.all([
+ getGroupList(input),
+ getGroupListCount(input),
+ ]);
+ const stats = await getGroupStats(
+ input.projectId,
+ data.map((g) => g.id)
+ );
+ return {
+ data: data.map((g) => ({
+ ...g,
+ memberCount: stats.get(g.id)?.memberCount ?? 0,
+ lastActiveAt: stats.get(g.id)?.lastActiveAt ?? null,
+ })),
+ meta: { count, take: input.take },
+ };
+}
+
+export async function getGroupMetrics(id: string, projectId: string) {
+ const { chQuery, toNullIfDefaultMinDate } = await loadChClient();
+ const [eventData, profileData] = await Promise.all([
+ chQuery<{ totalEvents: number; firstSeen: string; lastSeen: string }>(
+ groupEventMetricsQuery({ projectId, groupId: id })
+ ),
+ chQuery<{ uniqueProfiles: number }>(
+ groupUniqueProfilesQuery({ projectId, groupId: id })
+ ),
+ ]);
+
+ return {
+ totalEvents: eventData[0]?.totalEvents ?? 0,
+ uniqueProfiles: profileData[0]?.uniqueProfiles ?? 0,
+ firstSeen: toNullIfDefaultMinDate(eventData[0]?.firstSeen),
+ lastSeen: toNullIfDefaultMinDate(eventData[0]?.lastSeen),
+ };
+}
+
+export async function getGroupActivity(id: string, projectId: string) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ count: number; date: string }>(
+ groupActivityQuery({ projectId, groupId: id })
+ );
+}
+
+export async function getGroupMemberGrowth(id: string, projectId: string) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ date: string; count: number }>(
+ groupMemberGrowthQuery({ projectId, groupId: id })
+ );
+}
+
+export async function getGroupMostEvents(id: string, projectId: string) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ count: number; name: string }>(
+ groupMostEventsQuery({ projectId, groupId: id })
+ );
+}
+
+export async function getGroupPopularRoutes(id: string, projectId: string) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ count: number; path: string }>(
+ groupPopularRoutesQuery({ projectId, groupId: id })
+ );
+}
+
+export async function getGroupMemberProfilesPage(
+ input: GetGroupMemberProfilesOptions
+) {
+ const { data, count } = await getGroupMemberProfiles(input);
+ return {
+ data,
+ meta: { count, pageCount: input.take },
+ };
+}
+
+// ---- the assistant/mcp tool entry points
+
+export async function listGroupTypesCore(projectId: string) {
+ const types = await getGroupTypes(projectId);
+ return { types };
+}
+
+export async function findGroupsCore(input: {
+ projectId: string;
+ type?: string;
+ search?: string;
+ limit?: number;
+}) {
+ return getGroupList({
+ projectId: input.projectId,
+ type: input.type,
+ search: input.search,
+ take: input.limit ?? FIND_GROUPS_DEFAULT_LIMIT,
+ });
+}
+
+export async function getGroupCore(input: {
+ projectId: string;
+ groupId: string;
+ memberLimit?: number;
+}) {
+ const [group, members] = await Promise.all([
+ getGroupById(input.groupId, input.projectId),
+ getGroupMemberProfiles({
+ projectId: input.projectId,
+ groupId: input.groupId,
+ take: input.memberLimit ?? GROUP_MEMBERS_DEFAULT_LIMIT,
+ }),
+ ]);
+
+ if (!group) {
+ throw new Error(`Group not found: ${input.groupId}`);
+ }
+
+ return {
+ group,
+ member_count: members.count,
+ members: members.data,
+ };
+}
+
+export interface GroupService {
+ byId(id: string, projectId: string): Promise<IServiceGroup | null>;
+ upsert(input: IServiceUpsertGroup): Promise<void>;
+}
+
+export function createGroupService(_deps: ServiceDeps): GroupService {
+ return {
+ byId: getGroupById,
+ upsert: upsertGroup,
+ };
+}
diff --git a/packages/core/src/modules/group/src/access.ts b/packages/core/src/modules/group/src/access.ts
new file mode 100644
index 000000000..9b407436e
--- /dev/null
+++ b/packages/core/src/modules/group/src/access.ts
@@ -0,0 +1,22 @@
+// Binds core's shared/access.ts ladder to @openpanel/db's real lookups, for
+// this module's own router — the same binding packages/trpc/src/access.ts
+// does for V1, self-contained here because the general core -> db binding
+// itself moves with auth (P6), not this wave. Same shape as
+// session/src/access.ts.
+
+import {
+ canWriteProject,
+ getOrganizationAccess,
+ getProjectAccess,
+} from '@openpanel/db/src/services/access.service';
+import { getProjectById } from '@openpanel/db/src/services/project.service';
+import { createAccessChecks } from '../../../shared/access';
+
+const checks = createAccessChecks({
+ getProjectAccess,
+ canWriteProject,
+ getOrganizationAccess,
+ getProjectById,
+});
+
+export const requireProjectAccess = checks.requireProjectAccess;
diff --git a/packages/core/src/modules/group/src/dates.ts b/packages/core/src/modules/group/src/dates.ts
new file mode 100644
index 000000000..81c54b966
--- /dev/null
+++ b/packages/core/src/modules/group/src/dates.ts
@@ -0,0 +1,13 @@
+// @openpanel/db's clickhouse/client.ts owns this, but importing it constructs
+// a client and a pino logger at import time (see insight.service.ts's header).
+// Same copy session/src/dates.ts carries.
+
+const CLICKHOUSE_DATE_SUFFIX = /(\.\d{3})?Z+$/;
+
+/** `YYYY-MM-DD HH:mm:ss` in UTC — what V1 sent as a date literal. */
+export function formatClickhouseDate(date: Date | string): string {
+ return new Date(date)
+ .toISOString()
+ .replace('T', ' ')
+ .replace(CLICKHOUSE_DATE_SUFFIX, '');
+}
diff --git a/packages/core/src/modules/group/src/group.sql.proof.md b/packages/core/src/modules/group/src/group.sql.proof.md
new file mode 100644
index 000000000..f03729f14
--- /dev/null
+++ b/packages/core/src/modules/group/src/group.sql.proof.md
@@ -0,0 +1,244 @@
+# group.sql.ts — V1 → V2 result-set proof (M7-002)
+
+Every query builder in `group.sql.ts` was executed twice against the same data — once as V1 (the `git HEAD` service/router code, `3300f2a0`) and once as V2 (core's service, which renders the builder) — through one patched ClickHouse client that captured each statement, its `query_params`, `clickhouse_settings`, wall time and the raw JSON response. The two responses were compared on `data` (every row, every column, as JSON) and `meta` (column names and types). Statements without an `ORDER BY` were compared as row sets, because ClickHouse's parallel aggregation returns them in a different order run to run — V1 against itself too.
+
+- **Date**: 2026-09-04. **Data**: local prod-copy `openpanel` (319,499,000 events, static), project `redcollege` unless noted; cases needing rows the prod-copy lacks (`cohort_members`, `events_bots` are empty there) also ran on the isolated `openpanel_test` database with 3,380 events copied from `redcollege` under project `m7-002-proof`, plus seeded cohort/bot rows (deleted afterwards).
+- **Machine**: single-node ClickHouse 26.1.3.52 on a 4-vCPU box — timings are directional only; production is 2 shards × 2 replicas (`docs/ENVIRONMENT.md`). `rows_read` differences on JOIN statements are ClickHouse's per-run accounting of the right-hand side, not a plan difference: the SQL text is identical up to `{pN:Type}` binding.
+- **Verdict**: 16 cases / 18 statements, all IDENTICAL. No conversion changed a result set.
+
+The harness was a throwaway script (it needed verbatim copies of the V1 sources next to V2); each statement below is complete and reproducible with `curl http://127.0.0.1:8123/?database=openpanel`, binding the V2 params as `param_pN=`.
+
+### groupByIdQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 3359/3359; wall V1/V2 = 5.3 ms / 5.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = 'redcollege' AND id = '271' AND deleted = 0
+-- V2
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = {p1:String} AND id = {p2:String} AND deleted = 0
+-- V2 params: {"p1":"redcollege","p2":"271"}
+```
+
+### groupListQuery — page 2, type + search
+
+**statement** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 3359/3359; wall V1/V2 = 5.5 ms / 5.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = 'redcollege' AND deleted = 0 AND type = 'establecimiento' AND (name ILIKE '%colegio%' OR id ILIKE '%colegio%') ORDER BY created_at DESC LIMIT 10 OFFSET 10
+-- V2
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0 AND type = {p2:String} AND (name ILIKE {p3:String} OR id ILIKE {p4:String}) ORDER BY created_at DESC LIMIT {p5:UInt64} OFFSET {p6:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"establecimiento","p3":"%colegio%","p4":"%colegio%","p5":10,"p6":10}
+```
+
+### groupListQuery — first page, no filters
+
+**statement** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 3359/3359; wall V1/V2 = 9.8 ms / 6.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = 'redcollege' AND deleted = 0 ORDER BY created_at DESC LIMIT 10 OFFSET 0
+-- V2
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0 ORDER BY created_at DESC LIMIT {p2:UInt64} OFFSET {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":10,"p3":0}
+```
+
+### groupListCountQuery — type + search
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 3359/3359; wall V1/V2 = 5.3 ms / 5.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() as count FROM groups FINAL WHERE project_id = 'redcollege' AND deleted = 0 AND type = 'establecimiento' AND (name ILIKE '%colegio%' OR id ILIKE '%colegio%')
+-- V2
+SELECT count() as count FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0 AND type = {p2:String} AND (name ILIKE {p3:String} OR id ILIKE {p4:String})
+-- V2 params: {"p1":"redcollege","p2":"establecimiento","p3":"%colegio%","p4":"%colegio%"}
+```
+
+Result (first rows, identical on both sides): `[{"count":42}]`
+
+### groupListCountQuery — plain
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 3359/3359; wall V1/V2 = 5.7 ms / 4.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() as count FROM groups FINAL WHERE project_id = 'redcollege' AND deleted = 0
+-- V2
+SELECT count() as count FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":124}]`
+
+### groupTypesQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 3359/3359; wall V1/V2 = 4.1 ms / 4.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT DISTINCT type FROM groups FINAL WHERE project_id = 'redcollege' AND deleted = 0
+-- V2
+SELECT DISTINCT type FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"type":"establecimiento"}]`
+
+### groupPropertyKeysQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 3359/3359; wall V1/V2 = 6.2 ms / 6.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT DISTINCT arrayJoin(mapKeys(properties)) as key FROM groups FINAL WHERE project_id = 'redcollege' AND deleted = 0
+-- V2
+SELECT DISTINCT arrayJoin(mapKeys(properties)) as key FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"key":"rbd"}]`
+
+### groupStatsQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 147449/147449; wall V1/V2 = 23.6 ms / 17.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT g AS group_id, uniqExact(profile_id) AS member_count, max(created_at) AS last_active_at FROM events ARRAY JOIN groups AS g WHERE project_id = 'redcollege' AND g IN ('271','454','521') AND profile_id != device_id GROUP BY g
+-- V2
+SELECT g AS group_id, uniqExact(profile_id) AS member_count, max(created_at) AS last_active_at FROM events ARRAY JOIN groups AS g WHERE project_id = {p1:String} AND g IN {p2:Array(String)} AND profile_id != device_id GROUP BY g
+-- V2 params: {"p1":"redcollege","p2":["271","454","521"]}
+```
+
+Result (first rows, identical on both sides): `[{"group_id":"271","member_count":76,"last_active_at":"2026-08-25 02:16:23.865"}]`
+
+### groupsByIdsQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 2/2; rows_read V1/V2 = 3359/3359; wall V1/V2 = 5.2 ms / 4.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = 'redcollege' AND id IN ('271','454','missing') AND deleted = 0
+-- V2
+SELECT project_id, id, type, name, properties, created_at, version FROM groups FINAL WHERE project_id = {p1:String} AND id IN {p2:Array(String)} AND deleted = 0
+-- V2 params: {"p1":"redcollege","p2":["271","454","missing"]}
+```
+
+### groupMemberProfilesQuery — search (trimmed), page 2
+
+**statement** — IDENTICAL; rows V1/V2 = 0/0; rows_read V1/V2 = 122602/122602; wall V1/V2 = 23.1 ms / 22.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, count() OVER () AS total_count FROM profiles FINAL WHERE project_id = 'redcollege' AND has(groups, '271') AND (email ILIKE '%maria%' OR first_name ILIKE '%maria%' OR last_name ILIKE '%maria%') ORDER BY created_at DESC LIMIT 5 OFFSET 5
+-- V2
+SELECT id, count() OVER () AS total_count FROM profiles FINAL WHERE project_id = {p1:String} AND has(groups, {p2:String}) AND (email ILIKE {p3:String} OR first_name ILIKE {p4:String} OR last_name ILIKE {p5:String}) ORDER BY created_at DESC LIMIT {p6:UInt64} OFFSET {p7:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"271","p3":"%maria%","p4":"%maria%","p5":"%maria%","p6":5,"p7":5}
+```
+
+### groupMemberProfilesQuery — blank search, first page
+
+**statement 1** — IDENTICAL; rows V1/V2 = 5/5; rows_read V1/V2 = 106218/106218; wall V1/V2 = 35.9 ms / 34.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND id IN {p2:Array(String)}
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND id IN {p2:Array(String)}
+-- V2 params: {"p1":"redcollege","p2":["107142","186276","107079","107111","107918"]}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 5/5; rows_read V1/V2 = 122602/122602; wall V1/V2 = 22.9 ms / 19.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, count() OVER () AS total_count FROM profiles FINAL WHERE project_id = 'redcollege' AND has(groups, '271') ORDER BY created_at DESC LIMIT 5 OFFSET 0
+-- V2
+SELECT id, count() OVER () AS total_count FROM profiles FINAL WHERE project_id = {p1:String} AND has(groups, {p2:String}) ORDER BY created_at DESC LIMIT {p3:UInt64} OFFSET {p4:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"271","p3":5,"p4":0}
+```
+
+### groupEventMetricsQuery + groupUniqueProfilesQuery (group.metrics)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 147449/147449; wall V1/V2 = 13.0 ms / 14.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() AS totalEvents, min(created_at) AS firstSeen, max(created_at) AS lastSeen FROM events WHERE project_id = 'redcollege' AND has(groups, '271')
+-- V2
+SELECT count() AS totalEvents, min(created_at) AS firstSeen, max(created_at) AS lastSeen FROM events WHERE project_id = {p1:String} AND has(groups, {p2:String})
+-- V2 params: {"p1":"redcollege","p2":"271"}
+```
+
+Result (first rows, identical on both sides): `[{"totalEvents":20492,"firstSeen":"2026-08-10 20:02:03.875","lastSeen":"2026-08-25 02:16:23.865"}]`
+
+**statement 2** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 122602/122602; wall V1/V2 = 21.8 ms / 21.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() AS uniqueProfiles FROM profiles FINAL WHERE project_id = 'redcollege' AND has(groups, '271')
+-- V2
+SELECT count() AS uniqueProfiles FROM profiles FINAL WHERE project_id = {p1:String} AND has(groups, {p2:String})
+-- V2 params: {"p1":"redcollege","p2":"271"}
+```
+
+Result (first rows, identical on both sides): `[{"uniqueProfiles":75}]`
+
+### groupActivityQuery (group.activity)
+
+**statement** — IDENTICAL; rows V1/V2 = 16/16; rows_read V1/V2 = 147449/147449; wall V1/V2 = 11.5 ms / 11.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() AS count, toStartOfDay(created_at) AS date FROM events WHERE project_id = 'redcollege' AND has(groups, '271') GROUP BY date ORDER BY date DESC
+-- V2
+SELECT count() AS count, toStartOfDay(created_at) AS date FROM events WHERE project_id = {p1:String} AND has(groups, {p2:String}) GROUP BY date ORDER BY date DESC
+-- V2 params: {"p1":"redcollege","p2":"271"}
+```
+
+Result (first rows, identical on both sides): `[{"count":2,"date":"2026-08-25 00:00:00"},{"count":1985,"date":"2026-08-24 00:00:00"},{"count":72,"date":"2026-08-23 00:00:00"},{"count":41,"date":"2026-08-22 00:00:00"},{"count":1178,"date":"2026-08-`
+
+### groupMemberGrowthQuery (group.memberGrowth)
+
+**statement** — IDENTICAL; rows V1/V2 = 30/30; rows_read V1/V2 = 73450/73450; wall V1/V2 = 12.8 ms / 13.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT toDate(toStartOfDay(created_at)) AS date, count() AS count FROM profiles FINAL WHERE project_id = 'redcollege' AND has(groups, '271') AND created_at >= now() - INTERVAL 30 DAY GROUP BY date ORDER BY date ASC WITH FILL FROM toDate(now() - INTERVAL 29 DAY) TO toDate(now() + INTERVAL 1 DAY) STEP 1
+-- V2
+SELECT toDate(toStartOfDay(created_at)) AS date, count() AS count FROM profiles FINAL WHERE project_id = {p1:String} AND has(groups, {p2:String}) AND created_at >= now() - INTERVAL {p3:UInt64} DAY GROUP BY date ORDER BY date ASC WITH FILL FROM toDate(now() - INTERVAL {p4:UInt64} DAY) TO toDate(now() + INTERVAL 1 DAY) STEP 1
+-- V2 params: {"p1":"redcollege","p2":"271","p3":30,"p4":29}
+```
+
+Result (first rows, identical on both sides): `[{"date":"2026-08-06","count":0},{"date":"2026-08-07","count":0},{"date":"2026-08-08","count":0},{"date":"2026-08-09","count":0},{"date":"2026-08-10","count":22},{"date":"2026-08-11","count":36},{"dat`
+
+### groupMostEventsQuery (group.mostEvents)
+
+**statement** — IDENTICAL; rows V1/V2 = 2/2; rows_read V1/V2 = 147449/147449; wall V1/V2 = 11.6 ms / 16.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() as count, name FROM events WHERE project_id = 'redcollege' AND has(groups, '271') AND name NOT IN ('screen_view', 'session_start', 'session_end') GROUP BY name ORDER BY count DESC LIMIT 10
+-- V2
+SELECT count() as count, name FROM events WHERE project_id = {p1:String} AND has(groups, {p2:String}) AND name NOT IN ('screen_view', 'session_start', 'session_end') GROUP BY name ORDER BY count DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"271","p3":10}
+```
+
+Result (first rows, identical on both sides): `[{"count":854,"name":"link_out"},{"count":1,"name":"banner_click"}]`
+
+### groupPopularRoutesQuery (group.popularRoutes)
+
+**statement** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 147449/147449; wall V1/V2 = 21.0 ms / 15.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count() as count, path FROM events WHERE project_id = 'redcollege' AND has(groups, '271') AND name = 'screen_view' GROUP BY path ORDER BY count DESC LIMIT 10
+-- V2
+SELECT count() as count, path FROM events WHERE project_id = {p1:String} AND has(groups, {p2:String}) AND name = 'screen_view' GROUP BY path ORDER BY count DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"271","p3":10}
+```
+
+Result (first rows, identical on both sides): `[{"count":3460,"path":"/271/2026/libros"},{"count":1648,"path":"/271/2026/inicio"},{"count":903,"path":"/271/2026/asistencia-consolidada"},{"count":181,"path":"/271/2026/libros/12530/asistencia"},{"co`
+
diff --git a/packages/core/src/modules/group/src/group.sql.test.ts b/packages/core/src/modules/group/src/group.sql.test.ts
new file mode 100644
index 000000000..89e4866d5
--- /dev/null
+++ b/packages/core/src/modules/group/src/group.sql.test.ts
@@ -0,0 +1,237 @@
+// Shape tests for the group module's fragments: every user value binds as a
+// `{pN:Type}` parameter (nothing is interpolated), the optional clauses toggle
+// exactly on V1's conditions. Result-set equivalence against V1 was proven per
+// query on the local prod-copy (M7-002 report), not here — these run offline.
+
+import { describe, expect, test } from 'bun:test';
+import {
+ groupActivityQuery,
+ groupByIdQuery,
+ groupEventMetricsQuery,
+ groupListCountQuery,
+ groupListQuery,
+ groupMemberGrowthQuery,
+ groupMemberProfilesQuery,
+ groupMostEventsQuery,
+ groupPopularRoutesQuery,
+ groupPropertyKeysQuery,
+ groupStatsQuery,
+ groupsByIdsQuery,
+ groupTypesQuery,
+ groupUniqueProfilesQuery,
+} from './group.sql';
+
+const PROJECT_ID = 'proj-1';
+const GROUP_ID = 'grp-1';
+const HOSTILE = "x' OR 1=1 --";
+
+function collapse(text: string): string {
+ return text.replace(/\s+/g, ' ').trim();
+}
+
+describe('groupListQuery', () => {
+ test('plain page: project + deleted guard, no type or search clause', () => {
+ const { query, query_params } = groupListQuery({
+ projectId: PROJECT_ID,
+ take: 50,
+ offset: 0,
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain(
+ 'FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0 ORDER BY created_at DESC LIMIT {p2:UInt64} OFFSET {p3:UInt64}'
+ );
+ expect(text).not.toContain('type =');
+ expect(text).not.toContain('ILIKE');
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 50, p3: 0 });
+ });
+
+ test('type + search: both clauses bind, search wraps in %..%', () => {
+ const { query, query_params } = groupListQuery({
+ projectId: PROJECT_ID,
+ take: 50,
+ offset: 100,
+ type: 'company',
+ search: HOSTILE,
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain(
+ 'AND deleted = 0 AND type = {p2:String} AND (name ILIKE {p3:String} OR id ILIKE {p4:String})'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: 'company',
+ p3: `%${HOSTILE}%`,
+ p4: `%${HOSTILE}%`,
+ p5: 50,
+ p6: 100,
+ });
+ });
+
+ test('count shares the exact WHERE of the page', () => {
+ const page = collapse(
+ groupListQuery({
+ projectId: PROJECT_ID,
+ take: 1,
+ offset: 0,
+ type: 'company',
+ search: 'acme',
+ }).toStatement().query
+ );
+ const count = collapse(
+ groupListCountQuery({
+ projectId: PROJECT_ID,
+ type: 'company',
+ search: 'acme',
+ }).toStatement().query
+ );
+ const whereOf = (text: string) =>
+ text.slice(text.indexOf('WHERE')).replace(/ ORDER BY.*$/, '');
+
+ expect(count).toStartWith(
+ 'SELECT count() as count FROM groups FINAL WHERE'
+ );
+ expect(whereOf(count)).toBe(whereOf(page));
+ });
+});
+
+describe('single-group lookups', () => {
+ test('groupByIdQuery binds both keys and keeps the deleted guard', () => {
+ const { query, query_params } = groupByIdQuery({
+ id: HOSTILE,
+ projectId: PROJECT_ID,
+ }).toStatement();
+
+ expect(collapse(query)).toContain(
+ 'WHERE project_id = {p1:String} AND id = {p2:String} AND deleted = 0'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: HOSTILE });
+ });
+
+ test('groupsByIdsQuery binds the id list as one Array(String) param', () => {
+ const { query, query_params } = groupsByIdsQuery({
+ projectId: PROJECT_ID,
+ ids: ['a', 'b'],
+ }).toStatement();
+
+ expect(collapse(query)).toContain('AND id IN {p2:Array(String)}');
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: ['a', 'b'] });
+ });
+
+ test('groupStatsQuery only counts identified members', () => {
+ const { query, query_params } = groupStatsQuery({
+ projectId: PROJECT_ID,
+ groupIds: ['a'],
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain('ARRAY JOIN groups AS g');
+ expect(text).toContain(
+ 'AND g IN {p2:Array(String)} AND profile_id != device_id GROUP BY g'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: ['a'] });
+ });
+});
+
+describe('project-wide vocab', () => {
+ test('groupTypesQuery / groupPropertyKeysQuery bind only the project', () => {
+ for (const build of [groupTypesQuery, groupPropertyKeysQuery]) {
+ const { query, query_params } = build(PROJECT_ID).toStatement();
+ expect(collapse(query)).toContain(
+ 'FROM groups FINAL WHERE project_id = {p1:String} AND deleted = 0'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID });
+ }
+ });
+});
+
+describe('groupMemberProfilesQuery', () => {
+ test('no search: window total rides along, no ILIKE', () => {
+ const { query, query_params } = groupMemberProfilesQuery({
+ projectId: PROJECT_ID,
+ groupId: GROUP_ID,
+ take: 50,
+ offset: 0,
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain(
+ 'count() OVER () AS total_count FROM profiles FINAL'
+ );
+ expect(text).toContain(
+ 'WHERE project_id = {p1:String} AND has(groups, {p2:String}) ORDER BY created_at DESC LIMIT {p3:UInt64} OFFSET {p4:UInt64}'
+ );
+ expect(text).not.toContain('ILIKE');
+ expect(query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: GROUP_ID,
+ p3: 50,
+ p4: 0,
+ });
+ });
+
+ test('search: one %..% pattern bound three times', () => {
+ const { query, query_params } = groupMemberProfilesQuery({
+ projectId: PROJECT_ID,
+ groupId: GROUP_ID,
+ take: 50,
+ offset: 0,
+ search: HOSTILE,
+ }).toStatement();
+
+ expect(collapse(query)).toContain(
+ 'AND (email ILIKE {p3:String} OR first_name ILIKE {p4:String} OR last_name ILIKE {p5:String})'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params.p3).toBe(`%${HOSTILE}%`);
+ expect(query_params.p5).toBe(`%${HOSTILE}%`);
+ });
+});
+
+describe('the trpc router queries', () => {
+ const ref = { projectId: PROJECT_ID, groupId: HOSTILE };
+
+ test('every per-group query binds project then group and interpolates nothing', () => {
+ const builders = [
+ groupEventMetricsQuery,
+ groupUniqueProfilesQuery,
+ groupActivityQuery,
+ groupMemberGrowthQuery,
+ groupMostEventsQuery,
+ groupPopularRoutesQuery,
+ ];
+ for (const build of builders) {
+ const { query, query_params } = build(ref).toStatement();
+ expect(collapse(query)).toContain(
+ 'WHERE project_id = {p1:String} AND has(groups, {p2:String})'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toMatchObject({ p1: PROJECT_ID, p2: HOSTILE });
+ }
+ });
+
+ test('memberGrowth keeps the 30-day window and the WITH FILL frame', () => {
+ const { query, query_params } = groupMemberGrowthQuery(ref).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain(
+ 'AND created_at >= now() - INTERVAL {p3:UInt64} DAY GROUP BY date ORDER BY date ASC WITH FILL FROM toDate(now() - INTERVAL {p4:UInt64} DAY) TO toDate(now() + INTERVAL 1 DAY) STEP 1'
+ );
+ expect(query_params).toMatchObject({ p3: 30, p4: 29 });
+ });
+
+ test('mostEvents excludes the lifecycle events; popularRoutes keeps only screen_view', () => {
+ const most = collapse(groupMostEventsQuery(ref).toStatement().query);
+ const routes = collapse(groupPopularRoutesQuery(ref).toStatement().query);
+
+ expect(most).toContain(
+ "AND name NOT IN ('screen_view', 'session_start', 'session_end') GROUP BY name ORDER BY count DESC LIMIT {p3:UInt64}"
+ );
+ expect(routes).toContain(
+ "AND name = 'screen_view' GROUP BY path ORDER BY count DESC LIMIT {p3:UInt64}"
+ );
+ });
+});
diff --git a/packages/core/src/modules/group/src/group.sql.ts b/packages/core/src/modules/group/src/group.sql.ts
new file mode 100644
index 000000000..99095e71c
--- /dev/null
+++ b/packages/core/src/modules/group/src/group.sql.ts
@@ -0,0 +1,266 @@
+// Every ClickHouse query the group module runs, as pure `sql` fragments
+// (ADR-013). Converted 1:1 from packages/db/src/services/group.service.ts and
+// packages/trpc/src/routers/group.ts (M7-002): the SQL text is V1's, with every
+// value bound as a `{pN:Type}` parameter instead of an escaped literal. Each
+// builder's result set was diffed against V1's on the local prod-copy; the
+// statements, params, row counts and timings are in group.sql.proof.md.
+//
+// Cluster note (docs/ENVIRONMENT.md): `groups`, `profiles` and `events` are
+// Distributed on Cloud. No query here carries an `IN (subquery)`; the `IN`
+// lists bind as `Array(String)` params, which is a literal list to the planner.
+
+import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';
+
+const TABLE = {
+ groups: 'groups',
+ profiles: 'profiles',
+ events: 'events',
+} as const;
+
+const GROUP_COLUMNS = sql`project_id, id, type, name, properties, created_at, version`;
+
+function optional(
+ condition: boolean | string | undefined | null,
+ fragment: () => SqlFragment
+): SqlFragment {
+ return condition ? fragment() : sql.empty;
+}
+
+/** V1's `WHERE project_id = .. AND deleted = 0 [AND type = ..] [AND (name|id ILIKE ..)]`. */
+function liveGroupsCondition(query: {
+ projectId: string;
+ type?: string;
+ search?: string;
+}): SqlFragment {
+ return sql`project_id = ${sql.string(query.projectId)} AND deleted = 0${optional(
+ query.type,
+ () => sql` AND type = ${sql.string(query.type as string)}`
+ )}${optional(query.search, () => {
+ const pattern = sql.string(`%${query.search}%`);
+ return sql` AND (name ILIKE ${pattern} OR id ILIKE ${pattern})`;
+ })}`;
+}
+
+export function groupByIdQuery(query: {
+ id: string;
+ projectId: string;
+}): SqlFragment {
+ return sql`
+ SELECT ${GROUP_COLUMNS}
+ FROM ${sql.id(TABLE.groups)} FINAL
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND id = ${sql.string(query.id)}
+ AND deleted = 0
+ `;
+}
+
+export interface GroupListQuery {
+ projectId: string;
+ take: number;
+ offset: number;
+ search?: string;
+ type?: string;
+}
+
+export function groupListQuery(query: GroupListQuery): SqlFragment {
+ return sql`
+ SELECT ${GROUP_COLUMNS}
+ FROM ${sql.id(TABLE.groups)} FINAL
+ WHERE ${liveGroupsCondition(query)}
+ ORDER BY created_at DESC
+ LIMIT ${sql.uint64(query.take)}
+ OFFSET ${sql.uint64(query.offset)}
+ `;
+}
+
+export function groupListCountQuery(query: {
+ projectId: string;
+ type?: string;
+ search?: string;
+}): SqlFragment {
+ return sql`
+ SELECT count() as count
+ FROM ${sql.id(TABLE.groups)} FINAL
+ WHERE ${liveGroupsCondition(query)}
+ `;
+}
+
+export function groupTypesQuery(projectId: string): SqlFragment {
+ return sql`
+ SELECT DISTINCT type
+ FROM ${sql.id(TABLE.groups)} FINAL
+ WHERE project_id = ${sql.string(projectId)}
+ AND deleted = 0
+ `;
+}
+
+export function groupPropertyKeysQuery(projectId: string): SqlFragment {
+ return sql`
+ SELECT DISTINCT arrayJoin(mapKeys(properties)) as key
+ FROM ${sql.id(TABLE.groups)} FINAL
+ WHERE project_id = ${sql.string(projectId)}
+ AND deleted = 0
+ `;
+}
+
+/** Identified members only: anonymous events carry `profile_id = device_id`. */
+export function groupStatsQuery(query: {
+ projectId: string;
+ groupIds: readonly string[];
+}): SqlFragment {
+ return sql`
+ SELECT
+ g AS group_id,
+ uniqExact(profile_id) AS member_count,
+ max(created_at) AS last_active_at
+ FROM ${sql.id(TABLE.events)}
+ ARRAY JOIN groups AS g
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND g IN ${sql.array('String', query.groupIds)}
+ AND profile_id != device_id
+ GROUP BY g
+ `;
+}
+
+export function groupsByIdsQuery(query: {
+ projectId: string;
+ ids: readonly string[];
+}): SqlFragment {
+ return sql`
+ SELECT ${GROUP_COLUMNS}
+ FROM ${sql.id(TABLE.groups)} FINAL
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND id IN ${sql.array('String', query.ids)}
+ AND deleted = 0
+ `;
+}
+
+export interface GroupMemberProfilesQuery {
+ projectId: string;
+ groupId: string;
+ take: number;
+ offset: number;
+ /** Already trimmed by the caller; empty means no search clause. */
+ search?: string;
+}
+
+/** Member ids plus the window total, so one round trip pages and counts. */
+export function groupMemberProfilesQuery(
+ query: GroupMemberProfilesQuery
+): SqlFragment {
+ return sql`
+ SELECT
+ id,
+ count() OVER () AS total_count
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ ${optional(query.search, () => {
+ const pattern = sql.string(`%${query.search}%`);
+ return sql`AND (email ILIKE ${pattern} OR first_name ILIKE ${pattern} OR last_name ILIKE ${pattern})`;
+ })}
+ ORDER BY created_at DESC
+ LIMIT ${sql.uint64(query.take)}
+ OFFSET ${sql.uint64(query.offset)}
+ `;
+}
+
+// ---- packages/trpc/src/routers/group.ts's inline queries
+
+export function groupEventMetricsQuery(query: {
+ projectId: string;
+ groupId: string;
+}): SqlFragment {
+ return sql`
+ SELECT
+ count() AS totalEvents,
+ min(created_at) AS firstSeen,
+ max(created_at) AS lastSeen
+ FROM ${sql.id(TABLE.events)}
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ `;
+}
+
+export function groupUniqueProfilesQuery(query: {
+ projectId: string;
+ groupId: string;
+}): SqlFragment {
+ return sql`
+ SELECT count() AS uniqueProfiles
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ `;
+}
+
+export function groupActivityQuery(query: {
+ projectId: string;
+ groupId: string;
+}): SqlFragment {
+ return sql`
+ SELECT count() AS count, toStartOfDay(created_at) AS date
+ FROM ${sql.id(TABLE.events)}
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ GROUP BY date
+ ORDER BY date DESC
+ `;
+}
+
+const MEMBER_GROWTH_WINDOW_DAYS = 30;
+const MEMBER_GROWTH_FILL_FROM_DAYS_AGO = MEMBER_GROWTH_WINDOW_DAYS - 1;
+
+export function groupMemberGrowthQuery(query: {
+ projectId: string;
+ groupId: string;
+}): SqlFragment {
+ return sql`
+ SELECT
+ toDate(toStartOfDay(created_at)) AS date,
+ count() AS count
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ AND created_at >= now() - INTERVAL ${sql.uint64(MEMBER_GROWTH_WINDOW_DAYS)} DAY
+ GROUP BY date
+ ORDER BY date ASC WITH FILL
+ FROM toDate(now() - INTERVAL ${sql.uint64(MEMBER_GROWTH_FILL_FROM_DAYS_AGO)} DAY)
+ TO toDate(now() + INTERVAL 1 DAY)
+ STEP 1
+ `;
+}
+
+const TOP_LIST_LIMIT = 10;
+
+export function groupMostEventsQuery(query: {
+ projectId: string;
+ groupId: string;
+}): SqlFragment {
+ return sql`
+ SELECT count() as count, name
+ FROM ${sql.id(TABLE.events)}
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ AND name NOT IN ('screen_view', 'session_start', 'session_end')
+ GROUP BY name
+ ORDER BY count DESC
+ LIMIT ${sql.uint64(TOP_LIST_LIMIT)}
+ `;
+}
+
+export function groupPopularRoutesQuery(query: {
+ projectId: string;
+ groupId: string;
+}): SqlFragment {
+ return sql`
+ SELECT count() as count, path
+ FROM ${sql.id(TABLE.events)}
+ WHERE project_id = ${sql.string(query.projectId)}
+ AND has(groups, ${sql.string(query.groupId)})
+ AND name = 'screen_view'
+ GROUP BY path
+ ORDER BY count DESC
+ LIMIT ${sql.uint64(TOP_LIST_LIMIT)}
+ `;
+}
diff --git a/packages/core/src/modules/gsc/gsc.jobs.test.ts b/packages/core/src/modules/gsc/gsc.jobs.test.ts
index fff1b7051..ce0a7245b 100644
--- a/packages/core/src/modules/gsc/gsc.jobs.test.ts
+++ b/packages/core/src/modules/gsc/gsc.jobs.test.ts
@@ -35,6 +35,9 @@ function stubJobCtx(gsc: Partial<GscService>, jobName = 'test'): JobCtx {
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
@@ -136,6 +139,9 @@ test('gscSync fans out one gscProjectSync enqueue per connected project', async
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
},
requestId: 'req_1',
job: { id: 'job_1', attempt: 0, queue: 'cron', name: 'gscSync' },
diff --git a/packages/core/src/modules/import/import.jobs.test.ts b/packages/core/src/modules/import/import.jobs.test.ts
index 8ce853768..078f1cfbf 100644
--- a/packages/core/src/modules/import/import.jobs.test.ts
+++ b/packages/core/src/modules/import/import.jobs.test.ts
@@ -35,6 +35,9 @@ function stubJobCtx(importService: Partial<ImportService>): JobCtx {
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
diff --git a/packages/core/src/modules/insight/insight.jobs.test.ts b/packages/core/src/modules/insight/insight.jobs.test.ts
index a1f3c9f4e..da48d5ac7 100644
--- a/packages/core/src/modules/insight/insight.jobs.test.ts
+++ b/packages/core/src/modules/insight/insight.jobs.test.ts
@@ -46,6 +46,9 @@ function stubJobCtx(
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
@@ -130,6 +133,9 @@ test('insightsDaily fans out one insightsProject enqueue per candidate, jobId de
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
},
requestId: 'req_1',
job: { id: 'job_1', attempt: 0, queue: 'cron', name: 'insightsDaily' },
diff --git a/packages/core/src/modules/mcp/src/tools/analytics/profiles.test.ts b/packages/core/src/modules/mcp/src/tools/analytics/profiles.test.ts
index 9dbd3654f..9c5cb434d 100644
--- a/packages/core/src/modules/mcp/src/tools/analytics/profiles.test.ts
+++ b/packages/core/src/modules/mcp/src/tools/analytics/profiles.test.ts
@@ -7,6 +7,7 @@ import {
it,
mock,
} from 'bun:test';
+import type { SqlFragment } from '@openpanel/db/src/clickhouse/sql';
const mockChQuery = mock((..._args: unknown[]) =>
Promise.resolve([] as unknown[])
@@ -47,8 +48,16 @@ beforeAll(async () => {
));
});
-function capturedSql(): string {
- return mockChQuery.mock.calls[0]?.[0] as string;
+// Since M7-002 the service hands `chQuery` a `sql` fragment (ADR-013): the
+// text carries `{pN:Type}` placeholders and every value travels in params.
+function captured(): { query: string; params: Record<string, unknown> } {
+ const fragment = mockChQuery.mock.calls[0]?.[0] as SqlFragment;
+ const { query, query_params } = fragment.toStatement();
+ return { query: query.replace(/\s+/g, ' '), params: query_params };
+}
+
+function boundValues(): unknown[] {
+ return Object.values(captured().params);
}
beforeEach(() => {
@@ -59,101 +68,109 @@ beforeEach(() => {
describe('findProfilesCore — SQL conditions', () => {
it('always includes project_id condition', async () => {
await findProfilesCore({ projectId: 'proj-1' });
- expect(capturedSql()).toContain("project_id = 'proj-1'");
+ expect(captured().query).toContain('project_id = {p1:String}');
+ expect(captured().params.p1).toBe('proj-1');
});
it('adds email ILIKE condition when email is provided', async () => {
await findProfilesCore({ projectId: 'proj-1', email: 'carl@' });
- expect(capturedSql()).toContain("email ILIKE '%carl@%'");
+ expect(captured().query).toContain('email ILIKE {p2:String}');
+ expect(captured().params.p2).toBe('%carl@%');
});
it('searches across first/last/full name for name filter', async () => {
await findProfilesCore({ projectId: 'proj-1', name: 'Carl' });
- const sql = capturedSql();
- expect(sql).toContain('first_name ILIKE');
- expect(sql).toContain('last_name ILIKE');
- expect(sql).toContain("concat(first_name, ' ', last_name) ILIKE");
- expect(sql).toContain('%Carl%');
+ const { query } = captured();
+ expect(query).toContain('first_name ILIKE');
+ expect(query).toContain('last_name ILIKE');
+ expect(query).toContain("concat(first_name, ' ', last_name) ILIKE");
+ expect(boundValues()).toContain('%Carl%');
});
it('matches multi-token name queries by ANDing each token', async () => {
await findProfilesCore({ projectId: 'proj-1', name: 'John Smith' });
- const sql = capturedSql();
- expect(sql).toContain('%John%');
- expect(sql).toContain('%Smith%');
+ const { query } = captured();
+ expect(boundValues()).toContain('%John%');
+ expect(boundValues()).toContain('%Smith%');
// Each token wrapped in its own OR-of-fields group, joined by AND.
- expect(sql).toContain(') AND (');
+ expect(query).toContain(') AND (');
});
it('adds country property condition', async () => {
await findProfilesCore({ projectId: 'proj-1', country: 'SE' });
- expect(capturedSql()).toContain("properties['country'] = 'SE'");
+ expect(captured().query).toContain('properties[{p2:String}] = {p3:String}');
+ expect(captured().params).toMatchObject({ p2: 'country', p3: 'SE' });
});
it('adds inactiveDays NOT IN subquery', async () => {
await findProfilesCore({ projectId: 'proj-1', inactiveDays: 14 });
- const sql = capturedSql();
- expect(sql).toContain('NOT IN');
- expect(sql).toContain('INTERVAL 14 DAY');
+ const { query, params } = captured();
+ expect(query).toContain('NOT IN');
+ expect(query).toContain('INTERVAL {p3:UInt64} DAY');
+ expect(params.p3).toBe(14);
});
it('floors inactiveDays to integer (prevents SQL injection via floats)', async () => {
await findProfilesCore({ projectId: 'proj-1', inactiveDays: 14.9 });
- expect(capturedSql()).toContain('INTERVAL 14 DAY');
- expect(capturedSql()).not.toContain('14.9');
+ expect(captured().params.p3).toBe(14);
+ expect(boundValues()).not.toContain(14.9);
});
it('adds minSessions HAVING subquery', async () => {
await findProfilesCore({ projectId: 'proj-1', minSessions: 5 });
- const sql = capturedSql();
- expect(sql).toContain('HAVING count() >= 5');
+ const { query, params } = captured();
+ expect(query).toContain('HAVING count() >= {p3:UInt64}');
+ expect(params.p3).toBe(5);
});
it('adds performedEvent IN subquery', async () => {
await findProfilesCore({ projectId: 'proj-1', performedEvent: 'purchase' });
- expect(capturedSql()).toContain("name = 'purchase'");
+ expect(captured().query).toContain('AND name = {p3:String}');
+ expect(captured().params.p3).toBe('purchase');
});
it('defaults to ORDER BY created_at DESC', async () => {
await findProfilesCore({ projectId: 'proj-1' });
- expect(capturedSql()).toContain('ORDER BY created_at DESC');
+ expect(captured().query).toContain('ORDER BY created_at DESC');
});
it('respects sortOrder: asc', async () => {
await findProfilesCore({ projectId: 'proj-1', sortOrder: 'asc' });
- expect(capturedSql()).toContain('ORDER BY created_at ASC');
+ expect(captured().query).toContain('ORDER BY created_at ASC');
});
it('defaults limit to 20', async () => {
await findProfilesCore({ projectId: 'proj-1' });
- expect(capturedSql()).toContain('LIMIT 20');
+ expect(captured().query).toContain('LIMIT {p2:UInt64}');
+ expect(captured().params.p2).toBe(20);
});
it('caps limit at 100 regardless of input', async () => {
await findProfilesCore({ projectId: 'proj-1', limit: 9999 });
- expect(capturedSql()).toContain('LIMIT 100');
- expect(capturedSql()).not.toContain('LIMIT 9999');
+ expect(captured().params.p2).toBe(100);
+ expect(boundValues()).not.toContain(9999);
});
});
describe('findProfilesCore — SQL injection protection', () => {
- it('escapes single quotes in string values', async () => {
- await findProfilesCore({ projectId: "proj'; DROP TABLE profiles;--" });
- // The projectId must be escaped — raw SQL injection string must not appear
- expect(capturedSql()).not.toContain("proj'; DROP TABLE profiles;--");
+ it('binds the projectId instead of interpolating it', async () => {
+ const hostile = "proj'; DROP TABLE profiles;--";
+ await findProfilesCore({ projectId: hostile });
+ expect(captured().query).not.toContain(hostile);
+ expect(captured().params.p1).toBe(hostile);
});
- it('escapes single quotes in name search', async () => {
+ it('binds an apostrophe in the name search', async () => {
await findProfilesCore({ projectId: 'proj-1', name: "O'Brien" });
- // Unescaped apostrophe in the SQL would break the query
- const sql = capturedSql();
- expect(sql).not.toMatch(/LIKE '%O'Brien%'/);
+ const { query } = captured();
+ expect(query).not.toContain("O'Brien");
+ expect(boundValues()).toContain("%O'Brien%");
});
- it('escapes backslashes in email', async () => {
+ it('binds a backslash in the email', async () => {
await findProfilesCore({ projectId: 'proj-1', email: 'test\\@x.com' });
- // Raw backslash in ClickHouse SQL needs escaping
- expect(capturedSql()).not.toContain("'%test\\@x.com%'");
+ expect(captured().query).not.toContain('test\\@x.com');
+ expect(captured().params.p2).toBe('%test\\@x.com%');
});
});
diff --git a/packages/core/src/modules/notification/notification.jobs.test.ts b/packages/core/src/modules/notification/notification.jobs.test.ts
index 29e993f99..c7a4700c7 100644
--- a/packages/core/src/modules/notification/notification.jobs.test.ts
+++ b/packages/core/src/modules/notification/notification.jobs.test.ts
@@ -35,6 +35,9 @@ function stubJobCtx(notification: Partial<NotificationService>): JobCtx {
organization: {} as Services['organization'],
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
diff --git a/packages/core/src/modules/onboarding/onboarding.jobs.test.ts b/packages/core/src/modules/onboarding/onboarding.jobs.test.ts
index 27cd1cac3..c293149fc 100644
--- a/packages/core/src/modules/onboarding/onboarding.jobs.test.ts
+++ b/packages/core/src/modules/onboarding/onboarding.jobs.test.ts
@@ -38,6 +38,9 @@ function stubJobCtx(
organization: {} as Services['organization'],
onboarding: onboarding as OnboardingService,
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
diff --git a/packages/core/src/modules/organization/organization.jobs.test.ts b/packages/core/src/modules/organization/organization.jobs.test.ts
index 11cac0848..3968c351f 100644
--- a/packages/core/src/modules/organization/organization.jobs.test.ts
+++ b/packages/core/src/modules/organization/organization.jobs.test.ts
@@ -41,6 +41,9 @@ function stubJobCtx(
organization: organization as OrganizationService,
onboarding: {} as Services['onboarding'],
session: {} as Services['session'],
+ event: {} as Services['event'],
+ profile: {} as Services['profile'],
+ group: {} as Services['group'],
};
return {
db: {},
diff --git a/packages/core/src/modules/profile/profile.routes.test.ts b/packages/core/src/modules/profile/profile.routes.test.ts
new file mode 100644
index 000000000..4c7e031a8
--- /dev/null
+++ b/packages/core/src/modules/profile/profile.routes.test.ts
@@ -0,0 +1,163 @@
+// The three /profile routes end to end through `app.handle()`: status codes
+// and text bodies match V1's controller byte for byte, and each handler hands
+// the service exactly what the controller did. `../../http/client-auth` is a
+// P8 stub (always null), so it is mocked like http/auth.test.ts does; the
+// service and the geo lookup are mocked so nothing reaches a database. Every
+// mock is registered before the subject's first (dynamic) import — AGENTS.md.
+
+import { beforeAll, beforeEach, expect, mock, test } from 'bun:test';
+import { stubAppDeps } from '../../../test/http-fixtures';
+import type {
+ AuthenticatedClient,
+ ClientAuthOptions,
+} from '../../http/client-auth';
+import type {
+ AdjustProfilePropertyResult,
+ IdentifyProfileInput,
+ ProfileRequestContext,
+} from './profile.service';
+
+const CLIENT: AuthenticatedClient = {
+ id: 'client-1',
+ projectId: 'proj-1',
+ organizationId: 'org-1',
+ type: 'write',
+ secretPresented: true,
+};
+const GEO = { country: 'SE', city: 'Stockholm' };
+
+let client: AuthenticatedClient | null = CLIENT;
+let adjustResult: AdjustProfilePropertyResult = {
+ status: 'ok',
+ profileId: 'prof-1',
+};
+
+const authenticateClient = mock(
+ (_deps: unknown, _headers: Headers, _options: ClientAuthOptions) =>
+ Promise.resolve(client)
+);
+const identifyProfile = mock(
+ (
+ _projectId: string,
+ _payload: IdentifyProfileInput,
+ _request: ProfileRequestContext
+ ) => Promise.resolve()
+);
+const adjustProfileProperty = mock(
+ (
+ _projectId: string,
+ _input: { profileId: string; property: string; delta: number }
+ ) => Promise.resolve(adjustResult)
+);
+const getGeoLocation = mock((_ip?: string) => Promise.resolve(GEO));
+
+mock.module('../../http/client-auth', () => ({ authenticateClient }));
+mock.module('../../clients/geo', () => ({ getGeoLocation }));
+
+const actualService = await import('./profile.service');
+mock.module('./profile.service', () => ({
+ ...actualService,
+ identifyProfile,
+ adjustProfileProperty,
+}));
+
+let profileRoutes: typeof import('./profile.routes').profileRoutes;
+
+beforeAll(async () => {
+ ({ profileRoutes } = await import('./profile.routes'));
+});
+
+beforeEach(() => {
+ client = CLIENT;
+ adjustResult = { status: 'ok', profileId: 'prof-1' };
+ authenticateClient.mockClear();
+ identifyProfile.mockClear();
+ adjustProfileProperty.mockClear();
+ getGeoLocation.mockClear();
+});
+
+function post(path: string, body: unknown, userAgent = 'Mozilla/5.0 test') {
+ const { deps } = stubAppDeps();
+ return profileRoutes(deps).handle(
+ new Request(`http://localhost${path}`, {
+ method: 'POST',
+ headers: {
+ 'content-type': 'application/json',
+ 'user-agent': userAgent,
+ },
+ body: JSON.stringify(body),
+ })
+ );
+}
+
+test('POST /profile identifies with geo + user agent and answers 202 + profileId', async () => {
+ const payload = {
+ profileId: 'prof-1',
+ firstName: 'Ann',
+ properties: { plan: 'pro' },
+ };
+
+ const response = await post('/profile', payload);
+
+ expect(response.status).toBe(202);
+ expect(await response.text()).toBe('prof-1');
+ expect(identifyProfile).toHaveBeenCalledTimes(1);
+ const [projectId, received, context] = identifyProfile.mock.calls[0]!;
+ expect(projectId).toBe('proj-1');
+ expect(received).toEqual(payload);
+ expect(context.geo).toEqual(GEO);
+ expect(context.userAgent).toHaveProperty('browser');
+ expect(getGeoLocation).toHaveBeenCalledTimes(1);
+});
+
+test('POST /profile/increment passes value through; /decrement negates it', async () => {
+ const body = { profileId: 'prof-1', property: 'visits', value: 3 };
+
+ const incremented = await post('/profile/increment', body);
+ const decremented = await post('/profile/decrement', body);
+
+ expect(incremented.status).toBe(202);
+ expect(await incremented.text()).toBe('prof-1');
+ expect(decremented.status).toBe(202);
+ expect(adjustProfileProperty.mock.calls).toEqual([
+ ['proj-1', { profileId: 'prof-1', property: 'visits', delta: 3 }],
+ ['proj-1', { profileId: 'prof-1', property: 'visits', delta: -3 }],
+ ]);
+});
+
+test('adjust results map to V1 status codes and bodies', async () => {
+ const body = { profileId: 'prof-1', property: 'visits', value: 1 };
+
+ adjustResult = { status: 'not-found' };
+ const notFound = await post('/profile/increment', body);
+ expect(notFound.status).toBe(404);
+ expect(await notFound.text()).toBe('Not found');
+
+ adjustResult = { status: 'not-a-number' };
+ const notNumber = await post('/profile/decrement', body);
+ expect(notNumber.status).toBe(400);
+ expect(await notNumber.text()).toBe('Not number');
+});
+
+test('a client without a project answers 400 before touching the service', async () => {
+ client = { ...CLIENT, projectId: null };
+
+ const response = await post('/profile', { profileId: 'prof-1' });
+
+ expect(response.status).toBe(400);
+ expect(await response.text()).toBe('No projectId');
+ expect(identifyProfile).not.toHaveBeenCalled();
+});
+
+test('every /profile route requires client credentials', async () => {
+ client = null;
+
+ for (const path of ['/profile', '/profile/increment', '/profile/decrement']) {
+ const response = await post(path, { profileId: 'prof-1' });
+ expect(response.status).toBe(401);
+ }
+ expect(authenticateClient).toHaveBeenCalledTimes(3);
+ expect(authenticateClient.mock.calls[0]?.[2]).toEqual({ ingest: true });
+ expect(identifyProfile).not.toHaveBeenCalled();
+ expect(adjustProfileProperty).not.toHaveBeenCalled();
+});
diff --git a/packages/core/src/modules/profile/profile.routes.ts b/packages/core/src/modules/profile/profile.routes.ts
new file mode 100644
index 000000000..fd9c0a0c9
--- /dev/null
+++ b/packages/core/src/modules/profile/profile.routes.ts
@@ -0,0 +1,126 @@
+// Ported from apps/api/src/routes/profile.router.ts +
+// apps/api/src/controllers/profile.controller.ts (M7-002). V1's Fastify
+// controller stays the LIVE route (DELEGATE PATTERN) and delegates its bodies
+// to profile.service.ts's `identifyProfile` / `adjustProfileProperty` — the
+// same functions these routes call. Status codes and text bodies (`202` +
+// profile id, `400 'No projectId'`, `404 'Not found'`, `400 'Not number'`)
+// match V1's `reply.status(..).send(..)` byte for byte.
+//
+// NAMED GAP, same as import.routes.ts: not yet reachable. `authenticateClient`
+// (http/client-auth.ts) is a P8 stub that always returns null, so `clientAuth`
+// 401s every request until it is filled in, and main.ts does not mount
+// `publicApiRoutes` until a real `AppDeps` exists. `ingest: true` is V1's
+// `clientHook` (the SDK credential rules); V1's `isBotHook` and
+// `subscriptionHook` on this router are P8's too — the ingest module owns
+// them, not this one.
+//
+// V1 has no request-body schema for these routes (ADR-003: "/profile, /import,
+// /event and /tools have no request schemas today, and adding them would be a
+// behaviour change"), so the bodies are typed but not shape-validated.
+
+import { getGeoLocation } from '../../clients/geo';
+import { defineRoutes } from '../../http/define';
+import { parseUserAgent } from '../../shared/parser-user-agent';
+import {
+ type AdjustProfilePropertyResult,
+ adjustProfileProperty,
+ type IdentifyProfileInput,
+ identifyProfile,
+} from './profile.service';
+
+const TAGS = ['Profile'];
+
+interface AdjustPropertyBody {
+ profileId: string;
+ property: string;
+ value: number;
+}
+
+type StatusFn = (code: 400 | 404, body: string) => unknown;
+
+function respondAdjusted(
+ result: AdjustProfilePropertyResult,
+ status: StatusFn,
+ set: { status?: number | string }
+) {
+ if (result.status === 'not-found') {
+ return status(404, 'Not found');
+ }
+ if (result.status === 'not-a-number') {
+ return status(400, 'Not number');
+ }
+ set.status = 202;
+ return result.profileId;
+}
+
+export const profileRoutes = defineRoutes((app) =>
+ app
+ .post(
+ '/profile',
+ async ({ body, client, ctx, status, set }) => {
+ if (!client.projectId) {
+ return status(400, 'No projectId');
+ }
+ const payload = body as IdentifyProfileInput;
+ const userAgent = parseUserAgent(
+ ctx.headers.get('user-agent'),
+ payload.properties
+ );
+ const geo = await getGeoLocation(ctx.ip);
+ await identifyProfile(client.projectId, payload, { geo, userAgent });
+ set.status = 202;
+ return payload.profileId;
+ },
+ {
+ clientAuth: { ingest: true },
+ detail: {
+ tags: TAGS,
+ description: 'Identify or update a user profile.',
+ },
+ }
+ )
+ .post(
+ '/profile/increment',
+ async ({ body, client, status, set }) => {
+ if (!client.projectId) {
+ return status(400, 'No projectId');
+ }
+ const { profileId, property, value } = body as AdjustPropertyBody;
+ const result = await adjustProfileProperty(client.projectId, {
+ profileId,
+ property,
+ delta: value,
+ });
+ return respondAdjusted(result, status, set);
+ },
+ {
+ clientAuth: { ingest: true },
+ detail: {
+ tags: TAGS,
+ description: 'Increment a numeric property on a user profile.',
+ },
+ }
+ )
+ .post(
+ '/profile/decrement',
+ async ({ body, client, status, set }) => {
+ if (!client.projectId) {
+ return status(400, 'No projectId');
+ }
+ const { profileId, property, value } = body as AdjustPropertyBody;
+ const result = await adjustProfileProperty(client.projectId, {
+ profileId,
+ property,
+ delta: -value,
+ });
+ return respondAdjusted(result, status, set);
+ },
+ {
+ clientAuth: { ingest: true },
+ detail: {
+ tags: TAGS,
+ description: 'Decrement a numeric property on a user profile.',
+ },
+ }
+ )
+);
diff --git a/packages/core/src/modules/profile/profile.rpc.test.ts b/packages/core/src/modules/profile/profile.rpc.test.ts
new file mode 100644
index 000000000..5355c52d4
--- /dev/null
+++ b/packages/core/src/modules/profile/profile.rpc.test.ts
@@ -0,0 +1,60 @@
+// Only the "is anyone logged in" boundary is exercised here — no database.
+// The access-check + query bodies ride on @openpanel/db (lazy-loaded, see
+// profile.service.ts's header); wiring this router end-to-end against a real
+// ClickHouse is P6's (protectedProcedure) job — see profile.rpc.ts's header.
+// Same shape as session.rpc.test.ts.
+
+import { expect, test } from 'bun:test';
+import { stubHttpCtx } from '../../../test/rpc-fixtures';
+import { makeTrpcContext } from '../../rpc/base';
+import type { CookieOptions } from '../../shared/cookie';
+import { profileRouter } from './profile.rpc';
+
+const COOKIE_OPTIONS: CookieOptions = {
+ domain: '.openpanel.dev',
+ secure: true,
+ sameSite: 'lax',
+ httpOnly: true,
+ path: '/',
+};
+
+const EMPTY_SESSION = { session: null, user: null, userId: null };
+const REF = { profileId: 'prof_1', projectId: 'proj_1' };
+
+async function anonCaller() {
+ const { ctx } = stubHttpCtx({}, EMPTY_SESSION);
+ const trpcCtx = await makeTrpcContext(ctx, new Headers(), {
+ cookieOptions: COOKIE_OPTIONS,
+ });
+ return profileRouter.createCaller(trpcCtx);
+}
+
+const UNAUTHORIZED = { code: 'UNAUTHORIZED' };
+
+test('every procedure rejects an unauthenticated caller before touching a database', async () => {
+ const caller = await anonCaller();
+ await expect(caller.byId(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.metrics(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.activity(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.mostEvents(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.popularRoutes(REF)).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(
+ caller.properties({ projectId: 'proj_1' })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(caller.list({ projectId: 'proj_1' })).rejects.toMatchObject(
+ UNAUTHORIZED
+ );
+ await expect(
+ caller.powerUsers({ projectId: 'proj_1' })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+ await expect(
+ caller.values({ projectId: 'proj_1', property: 'email' })
+ ).rejects.toMatchObject(UNAUTHORIZED);
+});
+
+test('list rejects a malformed filter at the input boundary', async () => {
+ const caller = await anonCaller();
+ await expect(
+ caller.list({ projectId: 'proj_1', filters: [{ bogus: true }] as never })
+ ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+});
diff --git a/packages/core/src/modules/profile/profile.rpc.ts b/packages/core/src/modules/profile/profile.rpc.ts
new file mode 100644
index 000000000..df0e1da6d
--- /dev/null
+++ b/packages/core/src/modules/profile/profile.rpc.ts
@@ -0,0 +1,133 @@
+// Ported from packages/trpc/src/routers/profile.ts (M7-002).
+//
+// Same arrangement as session.rpc.ts: V1's `protectedProcedure` stack lands
+// with auth (P6), so until then each procedure does its own "is anyone logged
+// in" + `requireProjectAccess({ level: 'read' })` off the `projectId` input,
+// which is what V1's `enforceUserIsAuthed` + `enforceAccess` middleware pair
+// does implicitly. packages/trpc's profile router delegates its handler
+// bodies onto `./profile.service` while keeping V1's own `protectedProcedure`
+// stack.
+
+import { zChartEventFilter } from '@openpanel/validation';
+import { z } from 'zod';
+import { createTRPCRouter, procedure } from '../../rpc/base';
+import { TRPCAccessError } from '../../rpc/errors';
+import {
+ getPowerUsers,
+ getProfileActivity,
+ getProfileById,
+ getProfileListPage,
+ getProfileMetrics,
+ getProfileMostEvents,
+ getProfilePopularRoutes,
+ getProfilePropertyNames,
+ getProfileValues,
+} from './profile.service';
+
+const DEFAULT_LIST_TAKE = 50;
+
+const zProfileRef = z.object({ profileId: z.string(), projectId: z.string() });
+
+function loadAccessChecks() {
+ return import('./src/access');
+}
+
+function requireLogin(userId: string | null | undefined): string {
+ if (!userId) {
+ throw new TRPCAccessError('Not authenticated');
+ }
+ return userId;
+}
+
+async function requireReadAccess(userId: string, projectId: string) {
+ const { requireProjectAccess } = await loadAccessChecks();
+ await requireProjectAccess({ userId, projectId, level: 'read' });
+}
+
+export const profileRouter = createTRPCRouter({
+ byId: procedure.input(zProfileRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfileById(input.profileId, input.projectId);
+ }),
+
+ metrics: procedure.input(zProfileRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfileMetrics(input.profileId, input.projectId);
+ }),
+
+ activity: procedure.input(zProfileRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfileActivity(input.profileId, input.projectId);
+ }),
+
+ mostEvents: procedure.input(zProfileRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfileMostEvents(input.profileId, input.projectId);
+ }),
+
+ popularRoutes: procedure.input(zProfileRef).query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfilePopularRoutes(input.profileId, input.projectId);
+ }),
+
+ properties: procedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfilePropertyNames(input.projectId);
+ }),
+
+ list: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ cursor: z.number().optional(),
+ take: z.number().default(DEFAULT_LIST_TAKE),
+ search: z.string().optional(),
+ isExternal: z.boolean().optional(),
+ filters: z.array(zChartEventFilter).default([]),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfileListPage(input);
+ }),
+
+ powerUsers: procedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ cursor: z.number().optional(),
+ take: z.number().default(DEFAULT_LIST_TAKE),
+ })
+ )
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getPowerUsers(input);
+ }),
+
+ values: procedure
+ .input(z.object({ property: z.string(), projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const userId = requireLogin(ctx.session.userId);
+ await requireReadAccess(userId, input.projectId);
+
+ return getProfileValues(input);
+ }),
+});
diff --git a/packages/core/src/modules/profile/profile.service.ts b/packages/core/src/modules/profile/profile.service.ts
new file mode 100644
index 000000000..d85c590db
--- /dev/null
+++ b/packages/core/src/modules/profile/profile.service.ts
@@ -0,0 +1,672 @@
+// Ported from packages/db/src/services/profile.service.ts, the query bodies of
+// packages/trpc/src/routers/profile.ts and apps/api/src/controllers/
+// profile.controller.ts (M7-002). The db file is now a re-export shim over
+// this one, so @openpanel/db importers (packages/trpc, the assistant/mcp
+// tools, apps/api's controllers, notification.service, the buffers' types)
+// keep working while V1 runs (DELEGATE PATTERN).
+//
+// Every query is a `sql` fragment (src/profile.sql.ts), converted one at a
+// time with a result-set proof each, per ADR-013. `buildFilterWhere` is NOT
+// converted here: it is the shared filter compiler, out of this task's scope;
+// src/filter-clauses.ts is the one bridge.
+//
+// db/ch/buffer access is LAZY (`load*` below) for the reason
+// insight.service.ts's header gives: constructing @openpanel/db's clients at
+// import time spawns a pino-pretty worker per `bun test --isolate` file.
+
+import { strip, toObject } from '@openpanel/common';
+import { cacheable } from '@openpanel/redis';
+import type { IChartEventFilter } from '@openpanel/validation';
+import { assocPath, flatten, map, pathOr, pipe, prop, sort, uniq } from 'ramda';
+import type { ServiceDeps } from '../../services';
+import type { IClickhouseEvent } from '../event/event.service';
+import type { IClickhouseSession } from '../session/session.service';
+import { convertClickhouseDateToJs, formatClickhouseDate } from './src/dates';
+import type { CompiledFilterClauses } from './src/filter-clauses';
+import {
+ findProfilesQuery,
+ powerUsersQuery,
+ profileActivityQuery,
+ profileByIdQuery,
+ profileListCountQuery,
+ profileListQuery,
+ profileMetricsQuery,
+ profileMostEventsQuery,
+ profilePopularRoutesQuery,
+ profilePropertyKeysQuery,
+ profilePropertyNamesQuery,
+ profileRecentEventsQuery,
+ profileRowQuery,
+ profileSessionsQuery,
+ profilesByIdsQuery,
+ profileValuesQuery,
+} from './src/profile.sql';
+
+export { profileSearchCondition } from './src/profile.sql';
+
+const PROFILES_CACHE_SECONDS = 60 * 5;
+const PROPERTY_KEYS_CACHE_SECONDS = 60;
+const RECENT_EVENTS_DEFAULT_LIMIT = 10;
+const SESSIONS_DEFAULT_LIMIT = 20;
+const FIND_PROFILES_DEFAULT_LIMIT = 20;
+const FIND_PROFILES_MAX_LIMIT = 100;
+
+// clix always sent `session_timezone: 'UTC'`; the queries converted from clix
+// keep sending it so their result sets stay identical.
+const CLIX_SESSION_TIMEZONE = { session_timezone: 'UTC' } as const;
+
+const PROFILE_FILTER_TARGET = {
+ selfTable: 'profiles',
+ profileIdExpr: 'id',
+ groupsExpr: 'groups',
+} as const;
+
+const ARRAY_INDEX_PATH_SEGMENT = /\.([0-9]+)\./g;
+const ARRAY_INDEX_PATH_TAIL = /\.([0-9]+)/g;
+
+function loadChClient() {
+ return import('@openpanel/db/src/clickhouse/client');
+}
+
+function loadProfileBuffer() {
+ return import('@openpanel/db/src/buffers').then((m) => m.profileBuffer);
+}
+
+function loadFilterCompiler() {
+ return import('@openpanel/db/src/services/filter-where.service');
+}
+
+export interface IProfileMetrics {
+ lastSeen: Date | null;
+ firstSeen: Date | null;
+ screenViews: number;
+ sessions: number;
+ durationAvg: number;
+ durationP90: number;
+ totalEvents: number;
+ uniqueDaysActive: number;
+ bounceRate: number;
+ avgEventsPerSession: number;
+ conversionEvents: number;
+ avgTimeBetweenSessions: number;
+ revenue: number;
+}
+
+export interface IServiceProfile {
+ id: string;
+ email: string;
+ avatar: string;
+ firstName: string;
+ lastName: string;
+ /** First time this profile was seen — preserved across upserts. */
+ createdAt: Date;
+ /** Most recent activity. ReplacingMergeTree version column. */
+ lastSeenAt: Date;
+ isExternal: boolean;
+ projectId: string;
+ groups: string[];
+ properties: Record<string, unknown> & {
+ region?: string;
+ country?: string;
+ city?: string;
+ os?: string;
+ os_version?: string;
+ browser?: string;
+ browser_version?: string;
+ referrer_name?: string;
+ referrer_type?: string;
+ device?: string;
+ brand?: string;
+ model?: string;
+ referrer?: string;
+ };
+}
+
+export interface IClickhouseProfile {
+ id: string;
+ first_name: string;
+ last_name: string;
+ email: string;
+ avatar: string;
+ properties: Record<string, string | undefined>;
+ project_id: string;
+ is_external: boolean;
+ /** First time this profile was seen — preserved across upserts. */
+ created_at: string;
+ /** Most recent activity. ReplacingMergeTree version column. */
+ last_seen_at: string;
+ groups: string[];
+}
+
+export interface IServiceUpsertProfile {
+ projectId: string;
+ id: string | number;
+ firstName?: string;
+ lastName?: string;
+ email?: string;
+ avatar?: string;
+ properties?: Record<string, unknown>;
+ isExternal: boolean;
+ groups?: string[];
+}
+
+export function transformProfile({
+ created_at,
+ last_seen_at,
+ first_name,
+ last_name,
+ ...profile
+}: IClickhouseProfile): IServiceProfile {
+ const createdAtJs = convertClickhouseDateToJs(created_at);
+ return {
+ firstName: first_name,
+ lastName: last_name,
+ isExternal: profile.is_external,
+ properties: toObject(profile.properties),
+ createdAt: createdAtJs,
+ lastSeenAt: last_seen_at
+ ? convertClickhouseDateToJs(last_seen_at)
+ : createdAtJs,
+ projectId: profile.project_id,
+ id: profile.id,
+ email: profile.email,
+ avatar: profile.avatar,
+ groups: profile.groups ?? [],
+ };
+}
+
+async function compileProfileFilters(
+ filters: IChartEventFilter[] | undefined,
+ projectId: string
+): Promise<CompiledFilterClauses> {
+ if (!filters?.length) {
+ return {};
+ }
+ const { buildFilterWhere } = await loadFilterCompiler();
+ return buildFilterWhere(filters, projectId, PROFILE_FILTER_TARGET);
+}
+
+export async function getProfileMetrics(
+ profileId: string,
+ projectId: string
+): Promise<IProfileMetrics> {
+ const { chQuery, toNullIfDefaultMinDate } = await loadChClient();
+ const [data] = await chQuery<
+ Omit<IProfileMetrics, 'lastSeen' | 'firstSeen'> & {
+ lastSeen: string;
+ firstSeen: string;
+ }
+ >(profileMetricsQuery({ profileId, projectId }));
+ const metrics = data!;
+ return {
+ ...metrics,
+ lastSeen: toNullIfDefaultMinDate(metrics.lastSeen),
+ firstSeen: toNullIfDefaultMinDate(metrics.firstSeen),
+ };
+}
+
+export async function getProfileById(
+ id: string,
+ projectId: string
+): Promise<IServiceProfile | null> {
+ if (id === '' || projectId === '') {
+ return null;
+ }
+
+ const profileBuffer = await loadProfileBuffer();
+ const cachedProfile = await profileBuffer.fetchFromCache(id, projectId);
+ if (cachedProfile) {
+ return transformProfile(cachedProfile);
+ }
+
+ const { chQuery } = await loadChClient();
+ const [profile] = await chQuery<IClickhouseProfile>(
+ profileByIdQuery({ id: String(id), projectId })
+ );
+
+ return profile ? transformProfile(profile) : null;
+}
+
+export async function getProfiles(
+ ids: string[],
+ projectId: string
+): Promise<IServiceProfile[]> {
+ const filteredIds = uniq(ids.filter((id) => id !== ''));
+ if (filteredIds.length === 0) {
+ return [];
+ }
+
+ const { chQuery } = await loadChClient();
+ const data = await chQuery<IClickhouseProfile>(
+ profilesByIdsQuery({ projectId, ids: filteredIds })
+ );
+ return data.map(transformProfile);
+}
+
+export const getProfilesCached = cacheable(getProfiles, PROFILES_CACHE_SECONDS);
+
+export interface GetProfileListOptions {
+ projectId: string;
+ take: number;
+ cursor?: number;
+ filters?: IChartEventFilter[];
+ search?: string;
+ isExternal?: boolean;
+}
+
+export async function getProfileList({
+ take,
+ cursor,
+ projectId,
+ filters,
+ search,
+ isExternal,
+}: GetProfileListOptions): Promise<IServiceProfile[]> {
+ const { chQuery } = await loadChClient();
+ const data = await chQuery<IClickhouseProfile>(
+ profileListQuery({
+ projectId,
+ take,
+ offset: Math.max(0, (cursor ?? 0) * take),
+ search,
+ isExternal,
+ filterClauses: await compileProfileFilters(filters, projectId),
+ })
+ );
+ return data.map(transformProfile);
+}
+
+export async function getProfileListCount({
+ projectId,
+ filters,
+ isExternal,
+ search,
+}: Omit<GetProfileListOptions, 'cursor' | 'take'>): Promise<number> {
+ const { chQuery } = await loadChClient();
+ const data = await chQuery<{ count: number }>(
+ profileListCountQuery({
+ projectId,
+ search,
+ isExternal,
+ filterClauses: await compileProfileFilters(filters, projectId),
+ })
+ );
+ return data[0]?.count ?? 0;
+}
+
+export async function upsertProfile(
+ {
+ id,
+ firstName,
+ lastName,
+ email,
+ avatar,
+ properties,
+ projectId,
+ isExternal,
+ groups,
+ }: IServiceUpsertProfile,
+ isFromEvent = false
+): Promise<void> {
+ const now = formatClickhouseDate(new Date());
+ const profile: IClickhouseProfile = {
+ id: String(id),
+ first_name: firstName || '',
+ last_name: lastName || '',
+ email: email || '',
+ avatar: avatar || '',
+ properties: strip((properties as Record<string, string | undefined>) || {}),
+ project_id: projectId,
+ // First-seen value for brand-new profiles; the buffer's mergeProfiles
+ // omits `created_at` from incoming, so an existing profile keeps its own.
+ created_at: now,
+ // RMT version column — must advance on every write so the latest row wins.
+ last_seen_at: now,
+ is_external: isExternal,
+ groups: groups ?? [],
+ };
+
+ const profileBuffer = await loadProfileBuffer();
+ await profileBuffer.add(profile, isFromEvent);
+}
+
+export interface FindProfilesInput {
+ projectId: string;
+ name?: string;
+ email?: string;
+ country?: string;
+ city?: string;
+ device?: string;
+ browser?: string;
+ inactiveDays?: number;
+ minSessions?: number;
+ performedEvent?: string;
+ filters?: IChartEventFilter[];
+ sortBy?: 'created_at';
+ sortOrder?: 'asc' | 'desc';
+ limit?: number;
+}
+
+export async function findProfilesCore(
+ input: FindProfilesInput
+): Promise<IClickhouseProfile[]> {
+ const { chQuery } = await loadChClient();
+ return chQuery<IClickhouseProfile>(
+ findProfilesQuery({
+ ...input,
+ inactiveDays:
+ input.inactiveDays === undefined
+ ? undefined
+ : Math.floor(input.inactiveDays),
+ minSessions:
+ input.minSessions === undefined
+ ? undefined
+ : Math.floor(input.minSessions),
+ filterClauses: await compileProfileFilters(
+ input.filters,
+ input.projectId
+ ),
+ sortOrder: input.sortOrder === 'asc' ? 'asc' : 'desc',
+ limit: Math.min(
+ input.limit ?? FIND_PROFILES_DEFAULT_LIMIT,
+ FIND_PROFILES_MAX_LIMIT
+ ),
+ })
+ );
+}
+
+export async function getProfileWithEvents(
+ projectId: string,
+ profileId: string,
+ eventLimit = RECENT_EVENTS_DEFAULT_LIMIT
+): Promise<{
+ profile: IClickhouseProfile | null;
+ recent_events: IClickhouseEvent[];
+}> {
+ const { chQuery } = await loadChClient();
+ const [profiles, recent_events] = await Promise.all([
+ chQuery<IClickhouseProfile>(profileRowQuery({ projectId, profileId })),
+ chQuery<IClickhouseEvent>(
+ profileRecentEventsQuery({ projectId, profileId, limit: eventLimit }),
+ CLIX_SESSION_TIMEZONE
+ ),
+ ]);
+
+ return { profile: profiles[0] ?? null, recent_events };
+}
+
+export async function getProfileSessionsCore(
+ projectId: string,
+ profileId: string,
+ limit = SESSIONS_DEFAULT_LIMIT
+): Promise<IClickhouseSession[]> {
+ const { chQuery } = await loadChClient();
+ return chQuery<IClickhouseSession>(
+ profileSessionsQuery({ projectId, profileId, limit }),
+ CLIX_SESSION_TIMEZONE
+ );
+}
+
+export async function getProfileMetricsCore(input: {
+ projectId: string;
+ profileId: string;
+}) {
+ const raw = await getProfileMetrics(input.profileId, input.projectId);
+ if (!raw) {
+ throw new Error(`Profile not found or has no events: ${input.profileId}`);
+ }
+ return {
+ profileId: input.profileId,
+ firstSeen: raw.firstSeen,
+ lastSeen: raw.lastSeen,
+ sessions: raw.sessions,
+ screenViews: raw.screenViews,
+ totalEvents: raw.totalEvents,
+ conversionEvents: raw.conversionEvents,
+ uniqueDaysActive: raw.uniqueDaysActive,
+ avgSessionDurationMin: raw.durationAvg,
+ p90SessionDurationMin: raw.durationP90,
+ avgEventsPerSession: raw.avgEventsPerSession,
+ avgTimeBetweenSessionsSec: raw.avgTimeBetweenSessions,
+ bounceRate: raw.bounceRate,
+ revenue: raw.revenue,
+ };
+}
+
+/** Every distinct key in any external profile's `properties` map. */
+export async function getProfilePropertyKeys(
+ projectId: string
+): Promise<string[]> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ key: string }>(
+ profilePropertyKeysQuery(projectId),
+ CLIX_SESSION_TIMEZONE
+ );
+ return rows.map((r) => r.key).sort();
+}
+
+// Cached by projectId only: the picker's tRPC-level cache keys on the whole
+// input, which includes `event`, so without this the full profile scan would
+// repeat once per event within the same window.
+export const getProfilePropertyKeysCached = cacheable(
+ getProfilePropertyKeys,
+ PROPERTY_KEYS_CACHE_SECONDS
+);
+
+// ---- the trpc profile router's bodies
+
+export async function getProfileActivity(profileId: string, projectId: string) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ count: number; date: string }>(
+ profileActivityQuery({ projectId, profileId })
+ );
+}
+
+export async function getProfileMostEvents(
+ profileId: string,
+ projectId: string
+) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ count: number; name: string }>(
+ profileMostEventsQuery({ projectId, profileId })
+ );
+}
+
+export async function getProfilePopularRoutes(
+ profileId: string,
+ projectId: string
+) {
+ const { chQuery } = await loadChClient();
+ return chQuery<{ count: number; path: string }>(
+ profilePopularRoutesQuery({ projectId, profileId })
+ );
+}
+
+/** Property paths for the profile filter picker, array indexes wildcarded. */
+export async function getProfilePropertyNames(
+ projectId: string
+): Promise<string[]> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ keys: string[] }>(
+ profilePropertyNamesQuery(projectId)
+ );
+
+ const properties = rows
+ .flatMap((row) => row.keys)
+ .map((item) => item.replace(ARRAY_INDEX_PATH_SEGMENT, '.*.'))
+ .map((item) => item.replace(ARRAY_INDEX_PATH_TAIL, '[*]'))
+ .map((item) => `properties.${item}`);
+
+ properties.push('id', 'first_name', 'last_name', 'email');
+
+ return pipe(
+ sort<string>((a, b) => a.length - b.length),
+ uniq
+ )(properties);
+}
+
+export async function getProfileListPage(input: GetProfileListOptions) {
+ const [data, count] = await Promise.all([
+ getProfileList(input),
+ getProfileListCount(input),
+ ]);
+ return {
+ data,
+ meta: { count, pageCount: input.take },
+ };
+}
+
+export async function getPowerUsers(input: {
+ projectId: string;
+ cursor?: number;
+ take: number;
+}) {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ profile_id: string; count: number }>(
+ powerUsersQuery({
+ projectId: input.projectId,
+ take: input.take,
+ offset: input.cursor ? input.cursor * input.take : 0,
+ })
+ );
+ const profiles = await getProfiles(
+ rows.map((r) => r.profile_id),
+ input.projectId
+ );
+
+ const data: (IServiceProfile & { count: number })[] = [];
+ for (const row of rows) {
+ const profile = profiles.find((p) => p.id === row.profile_id);
+ // only rows that resolved to a real profile
+ if (profile?.id) {
+ data.push({ count: row.count, ...profile });
+ }
+ }
+
+ return {
+ data,
+ meta: { count: data.length, pageCount: input.take },
+ };
+}
+
+export async function getProfileValues(input: {
+ projectId: string;
+ property: string;
+}): Promise<{ values: string[] }> {
+ const { chQuery } = await loadChClient();
+ const rows = await chQuery<{ values: string[] }>(profileValuesQuery(input));
+
+ const values = pipe(
+ (data: typeof rows) => map(prop('values'), data),
+ flatten,
+ uniq,
+ sort((a, b) => a.length - b.length)
+ )(rows);
+
+ return { values };
+}
+
+// ---- apps/api's /profile controller bodies
+
+export interface IdentifyProfileInput {
+ profileId: string;
+ firstName?: string;
+ lastName?: string;
+ email?: string;
+ avatar?: string;
+ properties?: Record<string, unknown>;
+}
+
+export interface ProfileRequestContext {
+ geo: {
+ country?: string;
+ city?: string;
+ region?: string;
+ longitude?: number;
+ latitude?: number;
+ };
+ userAgent: {
+ os?: string;
+ osVersion?: string;
+ browser?: string;
+ browserVersion?: string;
+ device?: string;
+ brand?: string;
+ model?: string;
+ };
+}
+
+/** `POST /profile`: geo + UA fields override whatever the payload carried. */
+export async function identifyProfile(
+ projectId: string,
+ payload: IdentifyProfileInput,
+ request: ProfileRequestContext
+): Promise<void> {
+ await upsertProfile({
+ ...payload,
+ id: payload.profileId,
+ isExternal: true,
+ projectId,
+ properties: {
+ ...(payload.properties ?? {}),
+ country: request.geo.country,
+ city: request.geo.city,
+ region: request.geo.region,
+ longitude: request.geo.longitude,
+ latitude: request.geo.latitude,
+ os: request.userAgent.os,
+ os_version: request.userAgent.osVersion,
+ browser: request.userAgent.browser,
+ browser_version: request.userAgent.browserVersion,
+ device: request.userAgent.device,
+ brand: request.userAgent.brand,
+ model: request.userAgent.model,
+ },
+ });
+}
+
+export type AdjustProfilePropertyResult =
+ | { status: 'ok'; profileId: string }
+ | { status: 'not-found' }
+ | { status: 'not-a-number' };
+
+/** `POST /profile/increment|decrement`: `delta` is signed by the caller. */
+export async function adjustProfileProperty(
+ projectId: string,
+ input: { profileId: string; property: string; delta: number }
+): Promise<AdjustProfilePropertyResult> {
+ const profile = await getProfileById(input.profileId, projectId);
+ if (!profile) {
+ return { status: 'not-found' };
+ }
+
+ const path = input.property.split('.');
+ const current = Number.parseInt(
+ pathOr<string>('0', path, profile.properties),
+ 10
+ );
+ if (Number.isNaN(current)) {
+ return { status: 'not-a-number' };
+ }
+
+ await upsertProfile({
+ id: profile.id,
+ projectId,
+ properties: assocPath(path, current + input.delta, profile.properties),
+ isExternal: true,
+ });
+
+ return { status: 'ok', profileId: profile.id };
+}
+
+export interface ProfileService {
+ byId(id: string, projectId: string): Promise<IServiceProfile | null>;
+ upsert(input: IServiceUpsertProfile, isFromEvent?: boolean): Promise<void>;
+}
+
+export function createProfileService(_deps: ServiceDeps): ProfileService {
+ return {
+ byId: getProfileById,
+ upsert: upsertProfile,
+ };
+}
diff --git a/packages/core/src/modules/profile/src/access.ts b/packages/core/src/modules/profile/src/access.ts
new file mode 100644
index 000000000..9b407436e
--- /dev/null
+++ b/packages/core/src/modules/profile/src/access.ts
@@ -0,0 +1,22 @@
+// Binds core's shared/access.ts ladder to @openpanel/db's real lookups, for
+// this module's own router — the same binding packages/trpc/src/access.ts
+// does for V1, self-contained here because the general core -> db binding
+// itself moves with auth (P6), not this wave. Same shape as
+// session/src/access.ts.
+
+import {
+ canWriteProject,
+ getOrganizationAccess,
+ getProjectAccess,
+} from '@openpanel/db/src/services/access.service';
+import { getProjectById } from '@openpanel/db/src/services/project.service';
+import { createAccessChecks } from '../../../shared/access';
+
+const checks = createAccessChecks({
+ getProjectAccess,
+ canWriteProject,
+ getOrganizationAccess,
+ getProjectById,
+});
+
+export const requireProjectAccess = checks.requireProjectAccess;
diff --git a/packages/core/src/modules/profile/src/dates.ts b/packages/core/src/modules/profile/src/dates.ts
new file mode 100644
index 000000000..bcfcf8cb5
--- /dev/null
+++ b/packages/core/src/modules/profile/src/dates.ts
@@ -0,0 +1,18 @@
+// @openpanel/db's clickhouse/client.ts owns these, but importing it constructs
+// a client and a pino logger at import time (see insight.service.ts's header),
+// and the fragment builders here must stay pure and synchronous. Same choice
+// cohort.service.ts made for its table map.
+
+const CLICKHOUSE_DATE_SUFFIX = /(\.\d{3})?Z+$/;
+
+/** `YYYY-MM-DD HH:mm:ss` in UTC — what V1 sent as a date literal. */
+export function formatClickhouseDate(date: Date | string): string {
+ return new Date(date)
+ .toISOString()
+ .replace('T', ' ')
+ .replace(CLICKHOUSE_DATE_SUFFIX, '');
+}
+
+export function convertClickhouseDateToJs(date: string): Date {
+ return new Date(`${date.replace(' ', 'T')}Z`);
+}
diff --git a/packages/core/src/modules/profile/src/filter-clauses.ts b/packages/core/src/modules/profile/src/filter-clauses.ts
new file mode 100644
index 000000000..4a4442c24
--- /dev/null
+++ b/packages/core/src/modules/profile/src/filter-clauses.ts
@@ -0,0 +1,31 @@
+// The ONE place this module splices pre-compiled filter SQL.
+//
+// `buildFilterWhere` (packages/db/src/services/filter-where.service.ts) is
+// V1's filter compiler and still emits sqlstring-escaped SQL text: ADR-013
+// leaves the filter compilers as they are ("two behaviours, not two builders")
+// until the shared filter compiler converts to fragments. Until then a
+// `sql`-tag query that takes `IChartEventFilter[]` has to splice that text,
+// and it does so here — through the same `SqlFragment` constructor `sql.id`
+// uses — so the bridge is one grep away from deletion when the compiler moves,
+// rather than a `sql.raw()` that would outlive it.
+
+import { SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';
+
+export type CompiledFilterClauses = Record<string, string>;
+
+/** Each compiled clause is already parenthesised by the compiler. */
+export function compiledFilterFragments(
+ clauses: CompiledFilterClauses
+): SqlFragment[] {
+ return Object.values(clauses).map((clause) => new SqlFragment([clause], []));
+}
+
+export function spliceCompiledFilters(
+ clauses: CompiledFilterClauses
+): SqlFragment {
+ const fragments = compiledFilterFragments(clauses);
+ if (fragments.length === 0) {
+ return sql.empty;
+ }
+ return sql`AND ${sql.join(fragments, ' AND ')}`;
+}
diff --git a/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts b/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts
new file mode 100644
index 000000000..e805adeaa
--- /dev/null
+++ b/packages/core/src/modules/profile/src/profile-metrics-sql.test.ts
@@ -0,0 +1,81 @@
+// SQL-shape tests for the profile metrics query. Ported from
+// packages/db/src/services/profile-metrics-sql.test.ts (M7-002) — minus its
+// itCH ClickHouse-reachability EXPLAIN check, for the reason
+// cohort-sql.test.ts's header gives (a sibling file's client mock applies
+// process-wide). The rendered statement was EXPLAINed and result-diffed
+// against V1 on the local prod-copy by hand instead — see the EXPLAIN section
+// and the profileMetricsQuery case in profile.sql.proof.md. V1's
+// "escapes the identifiers" test becomes "binds the identifiers": the `sql`
+// tag never interpolates, so the hostile value can only appear in the params.
+
+import { describe, expect, test } from 'bun:test';
+import { profileMetricsQuery } from './profile.sql';
+
+const PROJECT_ID = 'test-sql-validation';
+const PROFILE_ID = 'profile-1';
+
+const METRICS = [
+ 'lastSeen',
+ 'firstSeen',
+ 'screenViews',
+ 'sessions',
+ 'durationAvg',
+ 'durationP90',
+ 'totalEvents',
+ 'uniqueDaysActive',
+ 'bounceRate',
+ 'avgEventsPerSession',
+ 'conversionEvents',
+ 'avgTimeBetweenSessions',
+ 'revenue',
+];
+
+function render() {
+ return profileMetricsQuery({
+ profileId: PROFILE_ID,
+ projectId: PROJECT_ID,
+ }).toStatement();
+}
+
+describe('profileMetricsQuery', () => {
+ // Every metric is a plain aggregate over the same
+ // `profile_id = X AND project_id = Y` slice, so the query must read the
+ // events table exactly once — the per-metric-CTE shape scanned it eight
+ // times per profile view.
+ test('scans the events table exactly once', () => {
+ const { query } = render();
+ expect(query.match(/FROM events\b/g)).toHaveLength(1);
+ expect(query.match(/FROM profiles\b/g)).toHaveLength(1);
+ });
+
+ test('keeps every metric of the old per-CTE shape', () => {
+ const { query } = render();
+ for (const metric of METRICS) {
+ expect(query).toContain(`as ${metric}`);
+ }
+ });
+
+ test('binds the identifiers instead of interpolating them', () => {
+ const hostileProfile = "p'--";
+ const hostileProject = "x'--";
+ const { query, query_params } = profileMetricsQuery({
+ profileId: hostileProfile,
+ projectId: hostileProject,
+ }).toStatement();
+
+ expect(query).not.toContain(hostileProfile);
+ expect(query).not.toContain(hostileProject);
+ expect(query).toContain(
+ 'WHERE id = {p1:String} AND project_id = {p2:String}'
+ );
+ expect(query).toContain(
+ 'WHERE profile_id = {p3:String} AND project_id = {p4:String}'
+ );
+ expect(query_params).toEqual({
+ p1: hostileProfile,
+ p2: hostileProject,
+ p3: hostileProfile,
+ p4: hostileProject,
+ });
+ });
+});
diff --git a/packages/core/src/modules/profile/src/profile.sql.proof.md b/packages/core/src/modules/profile/src/profile.sql.proof.md
new file mode 100644
index 000000000..6684806b7
--- /dev/null
+++ b/packages/core/src/modules/profile/src/profile.sql.proof.md
@@ -0,0 +1,317 @@
+# profile.sql.ts — V1 → V2 result-set proof (M7-002)
+
+Every query builder in `profile.sql.ts` was executed twice against the same data — once as V1 (the `git HEAD` service/router code, `3300f2a0`) and once as V2 (core's service, which renders the builder) — through one patched ClickHouse client that captured each statement, its `query_params`, `clickhouse_settings`, wall time and the raw JSON response. The two responses were compared on `data` (every row, every column, as JSON) and `meta` (column names and types). Statements without an `ORDER BY` were compared as row sets, because ClickHouse's parallel aggregation returns them in a different order run to run — V1 against itself too.
+
+- **Date**: 2026-09-04. **Data**: local prod-copy `openpanel` (319,499,000 events, static), project `redcollege` unless noted; cases needing rows the prod-copy lacks (`cohort_members`, `events_bots` are empty there) also ran on the isolated `openpanel_test` database with 3,380 events copied from `redcollege` under project `m7-002-proof`, plus seeded cohort/bot rows (deleted afterwards).
+- **Machine**: single-node ClickHouse 26.1.3.52 on a 4-vCPU box — timings are directional only; production is 2 shards × 2 replicas (`docs/ENVIRONMENT.md`). `rows_read` differences on JOIN statements are ClickHouse's per-run accounting of the right-hand side, not a plan difference: the SQL text is identical up to `{pN:Type}` binding.
+- **Verdict**: 20 cases / 23 statements, all IDENTICAL. No conversion changed a result set.
+
+The harness was a throwaway script (it needed verbatim copies of the V1 sources next to V2); each statement below is complete and reproducible with `curl http://127.0.0.1:8123/?database=openpanel`, binding the V2 params as `param_pN=`.
+
+### profileMetricsQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 335310/335310; wall V1/V2 = 52.5 ms / 49.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+WITH profileSeen AS ( SELECT created_at as firstSeen, last_seen_at as lastSeen FROM profiles FINAL WHERE id = '107145' AND project_id = 'redcollege' LIMIT 1 ), eventStats AS ( SELECT countIf(name = 'screen_view') as screenViews, countIf(name = 'session_start') as sessions, round(avgIf(duration, name = 'session_end' AND duration != 0) / 1000 / 60, 2) as durationAvg, round(quantilesExactInclusiveIf(0.9)(duration, name = 'session_end' AND duration != 0)[1] / 1000 / 60, 2) as durationP90, count(*) as totalEvents, count(DISTINCT toDate(created_at)) as uniqueDaysActive, round(avgIf(properties['__bounce'] = '1', name = 'session_end') * 100, 4) as bounceRate, countIf(name NOT IN ('screen_view', 'session_start', 'session_end')) as conversionEvents, sumIf(revenue, name = 'revenue') as revenue FROM events WHERE profile_id = '107145' AND project_id = 'redcollege' ) SELECT (SELECT lastSeen FROM profileSeen) as lastSeen, (SELECT firstSeen FROM profileSeen) as firstSeen, screenViews, sessions, durationAvg, durationP90, totalEvents, uniqueDaysActive, bounceRate, round(totalEvents / nullIf(sessions, 0), 2) as avgEventsPerSession, conversionEvents, CASE WHEN sessions <= 1 THEN 0 ELSE round(dateDiff('second', (SELECT firstSeen FROM profileSeen), (SELECT lastSeen FROM profileSeen)) / nullIf(sessions - 1, 0), 1) END as avgTimeBetweenSessions, revenue FROM eventStats
+-- V2
+WITH profileSeen AS ( SELECT created_at as firstSeen, last_seen_at as lastSeen FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1 ), eventStats AS ( SELECT countIf(name = 'screen_view') as screenViews, countIf(name = 'session_start') as sessions, round(avgIf(duration, name = 'session_end' AND duration != 0) / 1000 / 60, 2) as durationAvg, round(quantilesExactInclusiveIf(0.9)(duration, name = 'session_end' AND duration != 0)[1] / 1000 / 60, 2) as durationP90, count(*) as totalEvents, count(DISTINCT toDate(created_at)) as uniqueDaysActive, round(avgIf(properties['__bounce'] = '1', name = 'session_end') * 100, 4) as bounceRate, countIf(name NOT IN ('screen_view', 'session_start', 'session_end')) as conversionEvents, sumIf(revenue, name = 'revenue') as revenue FROM events WHERE profile_id = {p3:String} AND project_id = {p4:String} ) SELECT (SELECT lastSeen FROM profileSeen) as lastSeen, (SELECT firstSeen FROM profileSeen) as firstSeen, screenViews, sessions, durationAvg, durationP90, totalEvents, uniqueDaysActive, bounceRate, round(totalEvents / nullIf(sessions, 0), 2) as avgEventsPerSession, conversionEvents, CASE WHEN sessions <= 1 THEN 0 ELSE round(dateDiff('second', (SELECT firstSeen FROM profileSeen), (SELECT lastSeen FROM profileSeen)) / nullIf(sessions - 1, 0), 1) END as avgTimeBetweenSessions, revenue FROM eventStats
+-- V2 params: {"p1":"107145","p2":"redcollege","p3":"107145","p4":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"lastSeen":"2026-08-28 19:45:27.000","firstSeen":"2026-08-10 20:01:50.000","screenViews":1447,"sessions":2,"durationAvg":5.48,"durationP90":9.65,"totalEvents":1482,"uniqueDaysActive":11,"bounceRate"`
+
+### profileByIdQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 106218/106218; wall V1/V2 = 29.0 ms / 29.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE id = '107145' AND project_id = 'redcollege' LIMIT 1
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1
+-- V2 params: {"p1":"107145","p2":"redcollege"}
+```
+
+### profilesByIdsQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 3/3; rows_read V1/V2 = 122602/122602; wall V1/V2 = 38.2 ms / 38.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = 'redcollege' AND id IN ('107145','107075','107098','missing')
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND id IN {p2:Array(String)}
+-- V2 params: {"p1":"redcollege","p2":["107145","107075","107098","missing"]}
+```
+
+### profileListQuery — page 1, no search
+
+**statement** — IDENTICAL; rows V1/V2 = 25/25; rows_read V1/V2 = 122602/122602; wall V1/V2 = 36.8 ms / 36.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM profiles FINAL WHERE project_id = 'redcollege' ORDER BY created_at DESC LIMIT 25
+-- V2
+SELECT * FROM profiles FINAL WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64}
+-- V2 params: {"p1":"redcollege","p2":25}
+```
+
+### profileListQuery — page 3, multi-token search, isExternal, filters
+
+**statement** — IDENTICAL; rows V1/V2 = 2/2; rows_read V1/V2 = 122602/122602; wall V1/V2 = 37.9 ms / 40.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM profiles FINAL WHERE project_id = 'redcollege' AND ((id ILIKE '%maria%' OR email ILIKE '%maria%' OR first_name ILIKE '%maria%' OR last_name ILIKE '%maria%' OR concat(first_name, ' ', last_name) ILIKE '%maria%') AND (id ILIKE '%colegio%' OR email ILIKE '%colegio%' OR first_name ILIKE '%colegio%' OR last_name ILIKE '%colegio%' OR concat(first_name, ' ', last_name) ILIKE '%colegio%')) AND is_external = true ORDER BY created_at DESC LIMIT 2 OFFSET 2
+-- V2
+SELECT * FROM profiles FINAL WHERE project_id = {p1:String} AND ((id ILIKE {p2:String} OR email ILIKE {p3:String} OR first_name ILIKE {p4:String} OR last_name ILIKE {p5:String} OR concat(first_name, ' ', last_name) ILIKE {p6:String}) AND (id ILIKE {p7:String} OR email ILIKE {p8:String} OR first_name ILIKE {p9:String} OR last_name ILIKE {p10:String} OR concat(first_name, ' ', last_name) ILIKE {p11:String})) AND is_external = {p12:Bool} ORDER BY created_at DESC LIMIT {p13:UInt64} OFFSET {p14:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"%maria%","p3":"%maria%","p4":"%maria%","p5":"%maria%","p6":"%maria%","p7":"%colegio%","p8":"%colegio%","p9":"%colegio%","p10":"%colegio%","p11":"%colegio%","p12":true,"p13":2,"p14":2}
+```
+
+### profileListCountQuery — no search
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 57344/57344; wall V1/V2 = 6.9 ms / 7.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(id) as count FROM profiles WHERE project_id = 'redcollege' GROUP BY project_id
+-- V2
+SELECT count(id) as count FROM profiles WHERE project_id = {p1:String} GROUP BY project_id
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"count":5604}]`
+
+### profileListCountQuery — search, isExternal=false, filters
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 24576/24576; wall V1/V2 = 11.9 ms / 10.2 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(id) as count FROM profiles WHERE project_id = 'redcollege' AND ((id ILIKE '%maria%' OR email ILIKE '%maria%' OR first_name ILIKE '%maria%' OR last_name ILIKE '%maria%' OR concat(first_name, ' ', last_name) ILIKE '%maria%')) AND is_external = true GROUP BY project_id
+-- V2
+SELECT count(id) as count FROM profiles WHERE project_id = {p1:String} AND ((id ILIKE {p2:String} OR email ILIKE {p3:String} OR first_name ILIKE {p4:String} OR last_name ILIKE {p5:String} OR concat(first_name, ' ', last_name) ILIKE {p6:String})) AND is_external = {p7:Bool} GROUP BY project_id
+-- V2 params: {"p1":"redcollege","p2":"%maria%","p3":"%maria%","p4":"%maria%","p5":"%maria%","p6":"%maria%","p7":true}
+```
+
+Result (first rows, identical on both sides): `[{"count":23}]`
+
+### findProfilesQuery — every condition, asc, capped limit
+
+**statement** — IDENTICAL; rows V1/V2 = 4/4; rows_read V1/V2 = 351028/351028; wall V1/V2 = 70.5 ms / 61.5 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = 'redcollege' AND email ILIKE '%colegio%' AND ((id ILIKE '%maria%' OR email ILIKE '%maria%' OR first_name ILIKE '%maria%' OR last_name ILIKE '%maria%' OR concat(first_name, ' ', last_name) ILIKE '%maria%')) AND properties['country'] = 'CL' AND properties['city'] = 'Santiago' AND properties['device'] = 'desktop' AND properties['browser'] = 'Chrome' AND id NOT IN ( SELECT DISTINCT profile_id FROM events WHERE project_id = 'redcollege' AND profile_id != '' AND created_at >= now() - INTERVAL 3 DAY ) AND id IN ( SELECT profile_id FROM sessions WHERE project_id = 'redcollege' AND sign = 1 AND profile_id != '' GROUP BY profile_id HAVING count() >= 1 ) AND id IN ( SELECT DISTINCT profile_id FROM events WHERE project_id = 'redcollege' AND name = 'screen_view' ) ORDER BY created_at ASC LIMIT 100
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND email ILIKE {p2:String} AND ((id ILIKE {p3:String} OR email ILIKE {p4:String} OR first_name ILIKE {p5:String} OR last_name ILIKE {p6:String} OR concat(first_name, ' ', last_name) ILIKE {p7:String})) AND properties[{p8:String}] = {p9:String} AND properties[{p10:String}] = {p11:String} AND properties[{p12:String}] = {p13:String} AND properties[{p14:String}] = {p15:String} AND id NOT IN ( SELECT DISTINCT profile_id FROM events WHERE project_id = {p16:String} AND profile_id != '' AND created_at >= now() - INTERVAL {p17:UInt64} DAY ) AND id IN ( SELECT profile_id FROM sessions WHERE project_id = {p18:String} AND sign = 1 AND profile_id != '' GROUP BY profile_id HAVING count() >= {p19:UInt64} ) AND id IN ( SELECT DISTINCT profile_id FROM events WHERE project_id = {p20:String} AND name = {p21:String} ) ORDER BY created_at ASC LIMIT {p22:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"%colegio%","p3":"%maria%","p4":"%maria%","p5":"%maria%","p6":"%maria%","p7":"%maria%","p8":"country","p9":"CL","p10":"city","p11":"Santiago","p12":"device","p13":"desktop","p14":"browser","p15":"Chrome","p16":"redcollege","p17":3,"p18":"redcollege","p19":1,"p20":"redcollege","p21":"screen_view","p22":100}
+```
+
+### findProfilesQuery — defaults (project only)
+
+**statement** — IDENTICAL; rows V1/V2 = 20/20; rows_read V1/V2 = 122602/122602; wall V1/V2 = 41.2 ms / 36.3 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = 'redcollege' ORDER BY created_at DESC LIMIT 20
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64}
+-- V2 params: {"p1":"redcollege","p2":20}
+```
+
+### profileRowQuery + profileRecentEventsQuery (getProfileWithEvents)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 106218/106218; wall V1/V2 = 35.7 ms / 35.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = 'redcollege' AND id = '107145' LIMIT 1
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND id = {p2:String} LIMIT 1
+-- V2 params: {"p1":"redcollege","p2":"107145"}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 7/7; rows_read V1/V2 = 131065/131065; wall V1/V2 = 26.5 ms / 34.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM events WHERE project_id = 'redcollege' AND profile_id = '107145' ORDER BY created_at DESC LIMIT 7
+-- V2
+SELECT * FROM events WHERE project_id = {p1:String} AND profile_id = {p2:String} ORDER BY created_at DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"107145","p3":7}
+```
+
+### profileSessionsQuery
+
+**statement** — IDENTICAL; rows V1/V2 = 2/2; rows_read V1/V2 = 16378/16378; wall V1/V2 = 15.4 ms / 14.8 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT * FROM sessions WHERE project_id = 'redcollege' AND profile_id = '107145' AND sign = 1 ORDER BY created_at DESC LIMIT 5
+-- V2
+SELECT * FROM sessions WHERE project_id = {p1:String} AND profile_id = {p2:String} AND sign = 1 ORDER BY created_at DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"107145","p3":5}
+```
+
+### profilePropertyKeysQuery
+
+**statement** — IDENTICAL (as row sets; no ORDER BY); rows V1/V2 = 23/23; rows_read V1/V2 = 49152/49152; wall V1/V2 = 8.4 ms / 11.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT DISTINCT arrayJoin(mapKeys(properties)) as key FROM profiles WHERE project_id = 'redcollege' AND is_external = true
+-- V2
+SELECT DISTINCT arrayJoin(mapKeys(properties)) as key FROM profiles WHERE project_id = {p1:String} AND is_external = {p2:Bool}
+-- V2 params: {"p1":"redcollege","p2":true}
+```
+
+Result (first rows, identical on both sides): `[{"key":"__referrer"},{"key":"roles"},{"key":"cargo"},{"key":"establecimientoId"},{"key":"establecimientoNombre"},{"key":"country"},{"key":"city"},{"key":"region"},{"key":"longitude"},{"key":"latitude`
+
+### profileActivityQuery (profile.activity)
+
+**statement** — IDENTICAL; rows V1/V2 = 11/11; rows_read V1/V2 = 122874/122874; wall V1/V2 = 12.2 ms / 10.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count, toStartOfDay(created_at) as date FROM events WHERE project_id = 'redcollege' and profile_id = '107145' GROUP BY date ORDER BY date DESC
+-- V2
+SELECT count(*) as count, toStartOfDay(created_at) as date FROM events WHERE project_id = {p1:String} and profile_id = {p2:String} GROUP BY date ORDER BY date DESC
+-- V2 params: {"p1":"redcollege","p2":"107145"}
+```
+
+Result (first rows, identical on both sides): `[{"count":195,"date":"2026-08-24 00:00:00"},{"count":90,"date":"2026-08-21 00:00:00"},{"count":193,"date":"2026-08-20 00:00:00"},{"count":175,"date":"2026-08-19 00:00:00"},{"count":132,"date":"2026-08`
+
+### profileMostEventsQuery (profile.mostEvents)
+
+**statement** — IDENTICAL; rows V1/V2 = 1/1; rows_read V1/V2 = 114683/114683; wall V1/V2 = 11.7 ms / 12.1 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count, name FROM events WHERE name NOT IN ('screen_view', 'session_start', 'session_end') AND project_id = 'redcollege' and profile_id = '107145' GROUP BY name ORDER BY count DESC
+-- V2
+SELECT count(*) as count, name FROM events WHERE name NOT IN ('screen_view', 'session_start', 'session_end') AND project_id = {p1:String} and profile_id = {p2:String} GROUP BY name ORDER BY count DESC
+-- V2 params: {"p1":"redcollege","p2":"107145"}
+```
+
+Result (first rows, identical on both sides): `[{"count":31,"name":"link_out"}]`
+
+### profilePopularRoutesQuery (profile.popularRoutes)
+
+**statement** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 122874/122874; wall V1/V2 = 15.4 ms / 17.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT count(*) as count, path FROM events WHERE name = 'screen_view' AND project_id = 'redcollege' and profile_id = '107145' GROUP BY path ORDER BY count DESC LIMIT 10
+-- V2
+SELECT count(*) as count, path FROM events WHERE name = 'screen_view' AND project_id = {p1:String} and profile_id = {p2:String} GROUP BY path ORDER BY count DESC LIMIT {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":"107145","p3":10}
+```
+
+Result (first rows, identical on both sides): `[{"count":485,"path":"/271/2026/libros"},{"count":231,"path":"/271/2026/asistencia-consolidada"},{"count":33,"path":"/271/2026/inicio"},{"count":28,"path":"/271/2026/libros/12533/asistencia"},{"count"`
+
+### profilePropertyNamesQuery (profile.properties)
+
+**statement** — IDENTICAL (as row sets; no ORDER BY); rows V1/V2 = 281/281; rows_read V1/V2 = 57344/57344; wall V1/V2 = 9.4 ms / 9.4 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT distinct mapKeys(properties) as keys from profiles where project_id = 'redcollege';
+-- V2
+SELECT distinct mapKeys(properties) as keys from profiles where project_id = {p1:String};
+-- V2 params: {"p1":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"keys":["path","country","city","region","longitude","latitude","os","os_version","browser","browser_version","device","referrer","referrer_name"]},{"keys":["path","country","city","region","longitu`
+
+### powerUsersQuery — page 2 (profile.powerUsers)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 106218/106218; wall V1/V2 = 34.7 ms / 34.0 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = 'redcollege' AND id IN ('102208','91117','36357','183365','19316','133571','157236','161982','133563','107114')
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND id IN {p2:Array(String)}
+-- V2 params: {"p1":"redcollege","p2":["102208","91117","36357","183365","19316","133571","157236","161982","133563","107114"]}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 155641/155641; wall V1/V2 = 10.6 ms / 13.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT profile_id, count(*) as count FROM events WHERE profile_id != '' AND project_id = 'redcollege' GROUP BY profile_id ORDER BY count() DESC LIMIT 10 OFFSET 10
+-- V2
+SELECT profile_id, count(*) as count FROM events WHERE profile_id != '' AND project_id = {p1:String} GROUP BY profile_id ORDER BY count() DESC LIMIT {p2:UInt64} OFFSET {p3:UInt64}
+-- V2 params: {"p1":"redcollege","p2":10,"p3":10}
+```
+
+Result (first rows, identical on both sides): `[{"profile_id":"102208","count":776},{"profile_id":"91117","count":728},{"profile_id":"36357","count":722},{"profile_id":"183365","count":721},{"profile_id":"19316","count":687},{"profile_id":"133571"`
+
+### powerUsersQuery — first page (no OFFSET)
+
+**statement 1** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 106218/106218; wall V1/V2 = 34.9 ms / 33.6 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = 'redcollege' AND id IN ('179221','107145','132720','107075','107139','107098','112629','133575','107144','167538')
+-- V2
+SELECT id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups FROM profiles FINAL WHERE project_id = {p1:String} AND id IN {p2:Array(String)}
+-- V2 params: {"p1":"redcollege","p2":["179221","107145","132720","107075","107139","107098","112629","133575","107144","167538"]}
+```
+
+**statement 2** — IDENTICAL; rows V1/V2 = 10/10; rows_read V1/V2 = 155641/155641; wall V1/V2 = 10.0 ms / 10.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT profile_id, count(*) as count FROM events WHERE profile_id != '' AND project_id = 'redcollege' GROUP BY profile_id ORDER BY count() DESC LIMIT 10
+-- V2
+SELECT profile_id, count(*) as count FROM events WHERE profile_id != '' AND project_id = {p1:String} GROUP BY profile_id ORDER BY count() DESC LIMIT {p2:UInt64}
+-- V2 params: {"p1":"redcollege","p2":10}
+```
+
+Result (first rows, identical on both sides): `[{"profile_id":"179221","count":2377},{"profile_id":"107145","count":1482},{"profile_id":"132720","count":1387},{"profile_id":"107075","count":1361},{"profile_id":"107139","count":1182},{"profile_id":`
+
+### profileValuesQuery — properties.* path with array wildcard
+
+**statement** — IDENTICAL; rows V1/V2 = 14/14; rows_read V1/V2 = 57344/57344; wall V1/V2 = 11.4 ms / 10.9 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT distinct arrayMap(x -> trim(x), mapValues(mapExtractKeyLike(properties, 'roles'))) as values FROM profiles WHERE project_id = 'redcollege'
+-- V2
+SELECT distinct arrayMap(x -> trim(x), mapValues(mapExtractKeyLike(properties, {p1:String}))) as values FROM profiles WHERE project_id = {p2:String}
+-- V2 params: {"p1":"roles","p2":"redcollege"}
+```
+
+Result (first rows, identical on both sides): `[{"values":[]},{"values":["[\"Profesor\"]"]},{"values":["[\"Admin\"]"]},{"values":["[\"Admin\",\"Profesor\"]"]},{"values":["[\"Admin\",\"Apoderado\"]"]},{"values":["[\"Profesor\",\"Apoderado\"]"]},{"v`
+
+### profileValuesQuery — bare column
+
+**statement** — IDENTICAL; rows V1/V2 = 5604/5604; rows_read V1/V2 = 57344/57344; wall V1/V2 = 6.6 ms / 6.7 ms; clickhouse_settings same.
+
+```sql
+-- V1
+SELECT first_name as values FROM profiles WHERE project_id = 'redcollege'
+-- V2
+SELECT first_name as values FROM profiles WHERE project_id = {p1:String}
+-- V2 params: {"p1":"redcollege"}
+```
+
+## profileMetricsQuery — EXPLAIN
+
+`profile-metrics-sql.test.ts` drops V1's `itCH('parses and resolves against ClickHouse')` case (see its header for why core's suite cannot host a reachability check). The same check was run by hand on the rendered V2 statement with its bound params (`profile-1` / `test-sql-validation`, the test's own fixtures) against the prod-copy:
+
+```
+EXPLAIN <profileMetricsQuery(...).toStatement().query> -- params {"p1":"profile-1","p2":"test-sql-validation","p3":"profile-1","p4":"test-sql-validation"}
+Expression ((Project names + (Projection + (Change column names to column identifiers + (Project names + Projection)))))
+ Aggregating
+ Expression (Before GROUP BY)
+ Expression ((WHERE + Change column names to column identifiers))
+ ReadFromMergeTree (openpanel.events)
+```
+
+Parsed and resolved (73.6 ms). The plan shows one `ReadFromMergeTree` on `events` — the property the string tests guard; the `profiles` CTE is consumed through scalar subqueries, which ClickHouse evaluates ahead of the plan it prints. The result-set diff for the same builder on a real profile is the `profileMetricsQuery` case above.
+
diff --git a/packages/core/src/modules/profile/src/profile.sql.test.ts b/packages/core/src/modules/profile/src/profile.sql.test.ts
new file mode 100644
index 000000000..e9042776d
--- /dev/null
+++ b/packages/core/src/modules/profile/src/profile.sql.test.ts
@@ -0,0 +1,375 @@
+// Shape tests for the profile module's fragments: every user value binds as a
+// `{pN:Type}` parameter (nothing is interpolated), the optional clauses toggle
+// exactly on V1's conditions, and `sql.id` refuses anything off the column
+// whitelist. Result-set equivalence against V1 was proven per query on the
+// local prod-copy (M7-002 report), not here — these run offline.
+
+import { describe, expect, test } from 'bun:test';
+import {
+ findProfilesQuery,
+ PROFILE_COLUMNS,
+ powerUsersQuery,
+ profileActivityQuery,
+ profileByIdQuery,
+ profileListCountQuery,
+ profileListQuery,
+ profileMostEventsQuery,
+ profilePopularRoutesQuery,
+ profilePropertyKeysQuery,
+ profilePropertyNamesQuery,
+ profileRecentEventsQuery,
+ profileRowQuery,
+ profileSearchCondition,
+ profileSessionsQuery,
+ profilesByIdsQuery,
+ profileValuesQuery,
+} from './profile.sql';
+
+const PROJECT_ID = 'proj-1';
+const PROFILE_ID = 'prof-1';
+const HOSTILE = "x' OR 1=1 --";
+const NO_FILTERS = {};
+const COLUMN_LIST = PROFILE_COLUMNS.join(', ');
+
+function collapse(text: string): string {
+ return text.replace(/\s+/g, ' ').trim();
+}
+
+describe('profileSearchCondition', () => {
+ test('blank search is null', () => {
+ expect(profileSearchCondition(undefined)).toBeNull();
+ expect(profileSearchCondition(null)).toBeNull();
+ expect(profileSearchCondition(' ')).toBeNull();
+ });
+
+ test('one token binds the same %..% pattern to all five columns', () => {
+ const token = "x'OR(1=1)--";
+ const { query, query_params } = (
+ profileSearchCondition(token) as NonNullable<
+ ReturnType<typeof profileSearchCondition>
+ >
+ ).toStatement();
+
+ expect(collapse(query)).toBe(
+ "((id ILIKE {p1:String} OR email ILIKE {p2:String} OR first_name ILIKE {p3:String} OR last_name ILIKE {p4:String} OR concat(first_name, ' ', last_name) ILIKE {p5:String}))"
+ );
+ expect(query).not.toContain(token);
+ expect(Object.values(query_params)).toEqual(
+ new Array(5).fill(`%${token}%`)
+ );
+ });
+
+ test('tokens AND together and cap at five', () => {
+ const { query, query_params } = (
+ profileSearchCondition('a b c d e f g') as NonNullable<
+ ReturnType<typeof profileSearchCondition>
+ >
+ ).toStatement();
+
+ expect(collapse(query).split(') AND (')).toHaveLength(5);
+ expect(Object.keys(query_params)).toHaveLength(25);
+ expect(query_params.p1).toBe('%a%');
+ expect(query_params.p25).toBe('%e%');
+ });
+});
+
+describe('single-profile lookups', () => {
+ test('profileByIdQuery / profileRowQuery select the whitelisted columns', () => {
+ const byId = profileByIdQuery({
+ id: HOSTILE,
+ projectId: PROJECT_ID,
+ }).toStatement();
+ const row = profileRowQuery({
+ projectId: PROJECT_ID,
+ profileId: HOSTILE,
+ }).toStatement();
+
+ expect(collapse(byId.query)).toBe(
+ `SELECT ${COLUMN_LIST} FROM profiles FINAL WHERE id = {p1:String} AND project_id = {p2:String} LIMIT 1`
+ );
+ expect(byId.query_params).toEqual({ p1: HOSTILE, p2: PROJECT_ID });
+ expect(collapse(row.query)).toBe(
+ `SELECT ${COLUMN_LIST} FROM profiles FINAL WHERE project_id = {p1:String} AND id = {p2:String} LIMIT 1`
+ );
+ expect(row.query_params).toEqual({ p1: PROJECT_ID, p2: HOSTILE });
+ });
+
+ test('profilesByIdsQuery binds the id list as one Array(String) param', () => {
+ const { query, query_params } = profilesByIdsQuery({
+ projectId: PROJECT_ID,
+ ids: ['a', HOSTILE],
+ }).toStatement();
+
+ expect(collapse(query)).toContain(
+ 'WHERE project_id = {p1:String} AND id IN {p2:Array(String)}'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: ['a', HOSTILE] });
+ });
+
+ test('recent events / sessions bind project, profile, limit', () => {
+ const events = profileRecentEventsQuery({
+ projectId: PROJECT_ID,
+ profileId: PROFILE_ID,
+ limit: 10,
+ }).toStatement();
+ const sessions = profileSessionsQuery({
+ projectId: PROJECT_ID,
+ profileId: PROFILE_ID,
+ limit: 10,
+ }).toStatement();
+
+ expect(events.query).toBe(
+ 'SELECT * FROM events WHERE project_id = {p1:String} AND profile_id = {p2:String} ORDER BY created_at DESC LIMIT {p3:UInt64}'
+ );
+ expect(sessions.query).toBe(
+ 'SELECT * FROM sessions WHERE project_id = {p1:String} AND profile_id = {p2:String} AND sign = 1 ORDER BY created_at DESC LIMIT {p3:UInt64}'
+ );
+ expect(events.query_params).toEqual({
+ p1: PROJECT_ID,
+ p2: PROFILE_ID,
+ p3: 10,
+ });
+ expect(sessions.query_params).toEqual(events.query_params);
+ });
+});
+
+describe('profileListQuery', () => {
+ test('plain page: project only, no OFFSET at offset 0', () => {
+ const { query, query_params } = profileListQuery({
+ projectId: PROJECT_ID,
+ take: 50,
+ offset: 0,
+ filterClauses: NO_FILTERS,
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toBe(
+ 'SELECT * FROM profiles FINAL WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64}'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 50 });
+ });
+
+ test('search + isExternal + filters + offset all splice in V1 order', () => {
+ const { query, query_params } = profileListQuery({
+ projectId: PROJECT_ID,
+ take: 50,
+ offset: 100,
+ search: 'ann',
+ isExternal: true,
+ filterClauses: { f0: "(properties['plan'] = 'pro')" },
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain(
+ "WHERE project_id = {p1:String} AND ((id ILIKE {p2:String} OR email ILIKE {p3:String} OR first_name ILIKE {p4:String} OR last_name ILIKE {p5:String} OR concat(first_name, ' ', last_name) ILIKE {p6:String})) AND is_external = {p7:Bool} AND (properties['plan'] = 'pro') ORDER BY created_at DESC LIMIT {p8:UInt64} OFFSET {p9:UInt64}"
+ );
+ expect(query_params).toMatchObject({
+ p1: PROJECT_ID,
+ p2: '%ann%',
+ p7: true,
+ p8: 50,
+ p9: 100,
+ });
+ });
+
+ test('count shares the exact WHERE of the page (minus FINAL)', () => {
+ const list = {
+ projectId: PROJECT_ID,
+ search: 'ann',
+ isExternal: false,
+ filterClauses: { f0: "(email != '')" },
+ };
+ const page = collapse(
+ profileListQuery({ ...list, take: 1, offset: 0 }).toStatement().query
+ );
+ const count = collapse(profileListCountQuery(list).toStatement().query);
+ const whereOf = (text: string) =>
+ text
+ .slice(text.indexOf('WHERE'))
+ .replace(/ ORDER BY.*$/, '')
+ .replace(/ GROUP BY.*$/, '');
+
+ expect(count).toStartWith('SELECT count(id) as count FROM profiles WHERE');
+ expect(count).toEndWith('GROUP BY project_id');
+ expect(whereOf(count)).toBe(whereOf(page));
+ });
+});
+
+describe('findProfilesQuery', () => {
+ const base = {
+ projectId: PROJECT_ID,
+ filterClauses: NO_FILTERS,
+ sortOrder: 'desc' as const,
+ limit: 25,
+ };
+
+ test('minimal: project guard, DESC, bound limit', () => {
+ const { query, query_params } = findProfilesQuery(base).toStatement();
+
+ expect(collapse(query)).toBe(
+ `SELECT ${COLUMN_LIST} FROM profiles FINAL WHERE project_id = {p1:String} ORDER BY created_at DESC LIMIT {p2:UInt64}`
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: 25 });
+ });
+
+ test('every optional condition binds and none interpolates', () => {
+ const { query, query_params } = findProfilesQuery({
+ ...base,
+ sortOrder: 'asc',
+ email: HOSTILE,
+ name: 'ann',
+ country: 'SE',
+ city: HOSTILE,
+ device: 'mobile',
+ browser: 'Firefox',
+ inactiveDays: 7,
+ minSessions: 3,
+ performedEvent: HOSTILE,
+ filterClauses: { f0: '(1 = 1)' },
+ }).toStatement();
+ const text = collapse(query);
+
+ expect(text).toContain('AND email ILIKE {p2:String}');
+ expect(text).toContain(
+ 'AND properties[{p8:String}] = {p9:String} AND properties[{p10:String}] = {p11:String} AND properties[{p12:String}] = {p13:String} AND properties[{p14:String}] = {p15:String}'
+ );
+ expect(text).toContain(
+ "AND id NOT IN ( SELECT DISTINCT profile_id FROM events WHERE project_id = {p16:String} AND profile_id != '' AND created_at >= now() - INTERVAL {p17:UInt64} DAY )"
+ );
+ expect(text).toContain(
+ "AND id IN ( SELECT profile_id FROM sessions WHERE project_id = {p18:String} AND sign = 1 AND profile_id != '' GROUP BY profile_id HAVING count() >= {p19:UInt64} )"
+ );
+ expect(text).toContain(
+ 'AND id IN ( SELECT DISTINCT profile_id FROM events WHERE project_id = {p20:String} AND name = {p21:String} )'
+ );
+ expect(text).toEndWith(
+ 'AND (1 = 1) ORDER BY created_at ASC LIMIT {p22:UInt64}'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toMatchObject({
+ p2: `%${HOSTILE}%`,
+ p8: 'country',
+ p9: 'SE',
+ p10: 'city',
+ p11: HOSTILE,
+ p17: 7,
+ p19: 3,
+ p21: HOSTILE,
+ p22: 25,
+ });
+ });
+
+ test('inactiveDays / minSessions toggle on undefined, not on 0', () => {
+ const zero = collapse(
+ findProfilesQuery({
+ ...base,
+ inactiveDays: 0,
+ minSessions: 0,
+ }).toStatement().query
+ );
+ expect(zero).toContain('NOT IN');
+ expect(zero).toContain('INTERVAL {p3:UInt64} DAY');
+ expect(zero).toContain('HAVING count() >= {p5:UInt64}');
+ });
+});
+
+describe('project-wide vocab', () => {
+ test("property keys keeps V1's is_external guard and no FINAL", () => {
+ const { query, query_params } =
+ profilePropertyKeysQuery(PROJECT_ID).toStatement();
+
+ expect(query).toBe(
+ 'SELECT DISTINCT arrayJoin(mapKeys(properties)) as key FROM profiles WHERE project_id = {p1:String} AND is_external = {p2:Bool}'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID, p2: true });
+ });
+
+ test('property names binds only the project', () => {
+ const { query, query_params } =
+ profilePropertyNamesQuery(PROJECT_ID).toStatement();
+
+ expect(query).toContain(
+ 'SELECT distinct mapKeys(properties) as keys from profiles where project_id = {p1:String}'
+ );
+ expect(query_params).toEqual({ p1: PROJECT_ID });
+ });
+});
+
+describe('the trpc router queries', () => {
+ const ref = { projectId: PROJECT_ID, profileId: HOSTILE };
+
+ test('activity / mostEvents / popularRoutes bind project then profile', () => {
+ const activity = profileActivityQuery(ref).toStatement();
+ const most = profileMostEventsQuery(ref).toStatement();
+ const routes = profilePopularRoutesQuery(ref).toStatement();
+
+ for (const { query, query_params } of [activity, most, routes]) {
+ expect(query).toContain(
+ 'project_id = {p1:String} and profile_id = {p2:String}'
+ );
+ expect(query).not.toContain(HOSTILE);
+ expect(query_params).toMatchObject({ p1: PROJECT_ID, p2: HOSTILE });
+ }
+ expect(most.query).toContain(
+ "WHERE name NOT IN ('screen_view', 'session_start', 'session_end')"
+ );
+ expect(routes.query).toEndWith(
+ 'GROUP BY path ORDER BY count DESC LIMIT {p3:UInt64}'
+ );
+ expect(routes.query_params.p3).toBe(10);
+ });
+
+ test('powerUsers: OFFSET only when offset > 0', () => {
+ const first = powerUsersQuery({
+ projectId: PROJECT_ID,
+ take: 50,
+ offset: 0,
+ }).toStatement();
+ const later = powerUsersQuery({
+ projectId: PROJECT_ID,
+ take: 50,
+ offset: 50,
+ }).toStatement();
+
+ expect(collapse(first.query)).toEndWith(
+ 'GROUP BY profile_id ORDER BY count() DESC LIMIT {p2:UInt64}'
+ );
+ expect(first.query_params).toEqual({ p1: PROJECT_ID, p2: 50 });
+ expect(collapse(later.query)).toEndWith(
+ 'LIMIT {p2:UInt64} OFFSET {p3:UInt64}'
+ );
+ expect(later.query_params).toEqual({ p1: PROJECT_ID, p2: 50, p3: 50 });
+ });
+});
+
+describe('profileValuesQuery', () => {
+ test('properties.* path binds the key with .*. rewritten to .%.', () => {
+ const { query, query_params } = profileValuesQuery({
+ projectId: PROJECT_ID,
+ property: 'properties.plan.*.tier',
+ }).toStatement();
+
+ expect(query).toBe(
+ 'SELECT distinct arrayMap(x -> trim(x), mapValues(mapExtractKeyLike(properties, {p1:String}))) as values FROM profiles WHERE project_id = {p2:String}'
+ );
+ expect(query_params).toEqual({ p1: 'plan.%.tier', p2: PROJECT_ID });
+ });
+
+ test('bare column must be one of the picker columns', () => {
+ const { query } = profileValuesQuery({
+ projectId: PROJECT_ID,
+ property: 'email',
+ }).toStatement();
+ expect(query).toBe(
+ 'SELECT email as values FROM profiles WHERE project_id = {p1:String}'
+ );
+
+ expect(() =>
+ profileValuesQuery({ projectId: PROJECT_ID, property: HOSTILE })
+ ).toThrow();
+ expect(() =>
+ profileValuesQuery({ projectId: PROJECT_ID, property: 'project_id' })
+ ).toThrow();
+ });
+});
diff --git a/packages/core/src/modules/profile/src/profile.sql.ts b/packages/core/src/modules/profile/src/profile.sql.ts
new file mode 100644
index 000000000..b44b6fc28
--- /dev/null
+++ b/packages/core/src/modules/profile/src/profile.sql.ts
@@ -0,0 +1,387 @@
+// Every ClickHouse query the profile module runs, as pure `sql` fragments
+// (ADR-013). Converted 1:1 from packages/db/src/services/profile.service.ts
+// and packages/trpc/src/routers/profile.ts (M7-002): the SQL text is V1's,
+// with every value bound as a `{pN:Type}` parameter instead of an escaped
+// literal. Each builder's result set was diffed against V1's on the local
+// prod-copy; the statements, params, row counts and timings are in
+// profile.sql.proof.md.
+//
+// Cluster note (docs/ENVIRONMENT.md): `profiles`, `events` and `sessions` are
+// Distributed on Cloud. `findProfilesQuery`'s three `IN (SELECT ...)`
+// subqueries and any a filter compiles to keep V1's exact shape and run under
+// the client's `distributed_product_mode: 'allow'` as before — converting a
+// query is not the place to change its cluster semantics. Every `IN` list
+// binds as `Array(String)`, a literal list to the planner.
+
+import { type SqlFragment, sql } from '@openpanel/db/src/clickhouse/sql';
+import {
+ type CompiledFilterClauses,
+ compiledFilterFragments,
+ spliceCompiledFilters,
+} from './filter-clauses';
+
+const TABLE = {
+ profiles: 'profiles',
+ events: 'events',
+ sessions: 'sessions',
+} as const;
+
+export const PROFILE_COLUMNS = [
+ 'id',
+ 'first_name',
+ 'last_name',
+ 'email',
+ 'avatar',
+ 'properties',
+ 'project_id',
+ 'is_external',
+ 'created_at',
+ 'last_seen_at',
+ 'groups',
+] as const;
+
+const PROFILE_COLUMNS_FRAGMENT = sql.join(
+ PROFILE_COLUMNS.map((column) => sql.id(column, PROFILE_COLUMNS)),
+ ', '
+);
+
+const SEARCH_MAX_TOKENS = 5;
+const SEARCH_TOKEN_SEPARATOR = /\s+/;
+
+function optional(
+ condition: unknown,
+ fragment: () => SqlFragment
+): SqlFragment {
+ return condition ? fragment() : sql.empty;
+}
+
+/**
+ * Multi-token profile search: every whitespace-separated token (max 5) must
+ * match SOME of id/email/first/last/full name, case-insensitively. `null`
+ * when the search is blank.
+ */
+export function profileSearchCondition(
+ search: string | null | undefined
+): SqlFragment | null {
+ const tokens = (search ?? '')
+ .trim()
+ .split(SEARCH_TOKEN_SEPARATOR)
+ .filter(Boolean)
+ .slice(0, SEARCH_MAX_TOKENS);
+ if (tokens.length === 0) {
+ return null;
+ }
+ const perToken = tokens.map((token) => {
+ const like = sql.string(`%${token}%`);
+ return sql`(id ILIKE ${like} OR email ILIKE ${like} OR first_name ILIKE ${like} OR last_name ILIKE ${like} OR concat(first_name, ' ', last_name) ILIKE ${like})`;
+ });
+ return sql`(${sql.join(perToken, ' AND ')})`;
+}
+
+export function profileMetricsQuery(query: {
+ profileId: string;
+ projectId: string;
+}): SqlFragment {
+ const profileId = sql.string(query.profileId);
+ const projectId = sql.string(query.projectId);
+ return sql`
+ WITH profileSeen AS (
+ SELECT created_at as firstSeen, last_seen_at as lastSeen
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE id = ${profileId} AND project_id = ${projectId}
+ LIMIT 1
+ ),
+ eventStats AS (
+ SELECT
+ countIf(name = 'screen_view') as screenViews,
+ countIf(name = 'session_start') as sessions,
+ round(avgIf(duration, name = 'session_end' AND duration != 0) / 1000 / 60, 2) as durationAvg,
+ round(quantilesExactInclusiveIf(0.9)(duration, name = 'session_end' AND duration != 0)[1] / 1000 / 60, 2) as durationP90,
+ count(*) as totalEvents,
+ count(DISTINCT toDate(created_at)) as uniqueDaysActive,
+ round(avgIf(properties['__bounce'] = '1', name = 'session_end') * 100, 4) as bounceRate,
+ countIf(name NOT IN ('screen_view', 'session_start', 'session_end')) as conversionEvents,
+ sumIf(revenue, name = 'revenue') as revenue
+ FROM ${sql.id(TABLE.events)}
+ WHERE profile_id = ${profileId} AND project_id = ${projectId}
+ )
+ SELECT
+ (SELECT lastSeen FROM profileSeen) as lastSeen,
+ (SELECT firstSeen FROM profileSeen) as firstSeen,
+ screenViews,
+ sessions,
+ durationAvg,
+ durationP90,
+ totalEvents,
+ uniqueDaysActive,
+ bounceRate,
+ round(totalEvents / nullIf(sessions, 0), 2) as avgEventsPerSession,
+ conversionEvents,
+ CASE
+ WHEN sessions <= 1 THEN 0
+ ELSE round(dateDiff('second', (SELECT firstSeen FROM profileSeen), (SELECT lastSeen FROM profileSeen)) / nullIf(sessions - 1, 0), 1)
+ END as avgTimeBetweenSessions,
+ revenue
+ FROM eventStats
+ `;
+}
+
+export function profileByIdQuery(query: {
+ id: string;
+ projectId: string;
+}): SqlFragment {
+ return sql`
+ SELECT ${PROFILE_COLUMNS_FRAGMENT}
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE id = ${sql.string(query.id)} AND project_id = ${sql.string(query.projectId)}
+ LIMIT 1
+ `;
+}
+
+export function profilesByIdsQuery(query: {
+ projectId: string;
+ ids: readonly string[];
+}): SqlFragment {
+ return sql`
+ SELECT ${PROFILE_COLUMNS_FRAGMENT}
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE
+ project_id = ${sql.string(query.projectId)} AND
+ id IN ${sql.array('String', query.ids)}
+ `;
+}
+
+export interface ProfileListQuery {
+ projectId: string;
+ search?: string;
+ isExternal?: boolean;
+ /** Pre-compiled by `buildFilterWhere` (src/filter-clauses.ts). */
+ filterClauses: CompiledFilterClauses;
+}
+
+/** V1's `WHERE project_id = .. [AND search] [AND is_external = ..] [AND filters]`. */
+function profileListCondition(query: ProfileListQuery): SqlFragment {
+ const search = profileSearchCondition(query.search);
+ return sql`project_id = ${sql.string(query.projectId)}${optional(
+ search,
+ () => sql` AND ${search as SqlFragment}`
+ )}${optional(
+ query.isExternal !== undefined,
+ () => sql` AND is_external = ${sql.bool(query.isExternal as boolean)}`
+ )} ${spliceCompiledFilters(query.filterClauses)}`;
+}
+
+export function profileListQuery(
+ query: ProfileListQuery & { take: number; offset: number }
+): SqlFragment {
+ return sql`
+ SELECT *
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE ${profileListCondition(query)}
+ ORDER BY created_at DESC
+ LIMIT ${sql.uint64(query.take)}
+ ${optional(query.offset, () => sql`OFFSET ${sql.uint64(query.offset)}`)}
+ `;
+}
+
+export function profileListCountQuery(query: ProfileListQuery): SqlFragment {
+ return sql`
+ SELECT count(id) as count
+ FROM ${sql.id(TABLE.profiles)}
+ WHERE ${profileListCondition(query)}
+ GROUP BY project_id
+ `;
+}
+
+export interface FindProfilesQuery {
+ projectId: string;
+ name?: string;
+ email?: string;
+ country?: string;
+ city?: string;
+ device?: string;
+ browser?: string;
+ /** Already floored to an integer by the service. */
+ inactiveDays?: number;
+ /** Already floored to an integer by the service. */
+ minSessions?: number;
+ performedEvent?: string;
+ filterClauses: CompiledFilterClauses;
+ sortOrder: 'asc' | 'desc';
+ limit: number;
+}
+
+const PROFILE_PROPERTY_FILTERS = [
+ 'country',
+ 'city',
+ 'device',
+ 'browser',
+] as const;
+
+function findProfilesConditions(query: FindProfilesQuery): SqlFragment[] {
+ const projectId = sql.string(query.projectId);
+ const conditions: SqlFragment[] = [sql`project_id = ${projectId}`];
+
+ if (query.email) {
+ conditions.push(sql`email ILIKE ${sql.string(`%${query.email}%`)}`);
+ }
+ const nameCondition = profileSearchCondition(query.name);
+ if (query.name && nameCondition) {
+ conditions.push(nameCondition);
+ }
+ for (const key of PROFILE_PROPERTY_FILTERS) {
+ const value = query[key];
+ if (value) {
+ conditions.push(
+ sql`properties[${sql.string(key)}] = ${sql.string(value)}`
+ );
+ }
+ }
+
+ if (query.inactiveDays !== undefined) {
+ conditions.push(sql`id NOT IN (
+ SELECT DISTINCT profile_id FROM ${sql.id(TABLE.events)}
+ WHERE project_id = ${projectId}
+ AND profile_id != ''
+ AND created_at >= now() - INTERVAL ${sql.uint64(query.inactiveDays)} DAY
+ )`);
+ }
+
+ if (query.minSessions !== undefined) {
+ conditions.push(sql`id IN (
+ SELECT profile_id FROM ${sql.id(TABLE.sessions)}
+ WHERE project_id = ${projectId}
+ AND sign = 1
+ AND profile_id != ''
+ GROUP BY profile_id
+ HAVING count() >= ${sql.uint64(query.minSessions)}
+ )`);
+ }
+
+ if (query.performedEvent) {
+ conditions.push(sql`id IN (
+ SELECT DISTINCT profile_id FROM ${sql.id(TABLE.events)}
+ WHERE project_id = ${projectId}
+ AND name = ${sql.string(query.performedEvent)}
+ )`);
+ }
+
+ conditions.push(...compiledFilterFragments(query.filterClauses));
+
+ return conditions;
+}
+
+export function findProfilesQuery(query: FindProfilesQuery): SqlFragment {
+ const orderDirection = query.sortOrder === 'asc' ? sql`ASC` : sql`DESC`;
+ return sql`
+ SELECT ${PROFILE_COLUMNS_FRAGMENT}
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE ${sql.join(findProfilesConditions(query), ' AND ')}
+ ORDER BY created_at ${orderDirection}
+ LIMIT ${sql.uint64(query.limit)}
+ `;
+}
+
+export function profileRowQuery(query: {
+ projectId: string;
+ profileId: string;
+}): SqlFragment {
+ return sql`
+ SELECT ${PROFILE_COLUMNS_FRAGMENT}
+ FROM ${sql.id(TABLE.profiles)} FINAL
+ WHERE project_id = ${sql.string(query.projectId)} AND id = ${sql.string(query.profileId)}
+ LIMIT 1
+ `;
+}
+
+export function profileRecentEventsQuery(query: {
+ projectId: string;
+ profileId: string;
+ limit: number;
+}): SqlFragment {
+ return sql`SELECT * FROM ${sql.id(TABLE.events)} WHERE project_id = ${sql.string(query.projectId)} AND profile_id = ${sql.string(query.profileId)} ORDER BY created_at DESC LIMIT ${sql.uint64(query.limit)}`;
+}
+
+export function profileSessionsQuery(query: {
+ projectId: string;
+ profileId: string;
+ limit: number;
+}): SqlFragment {
+ return sql`SELECT * FROM ${sql.id(TABLE.sessions)} WHERE project_id = ${sql.string(query.projectId)} AND profile_id = ${sql.string(query.profileId)} AND sign = 1 ORDER BY created_at DESC LIMIT ${sql.uint64(query.limit)}`;
+}
+
+/** No `FINAL`: older row versions only contribute keys that existed at some point. */
+export function profilePropertyKeysQuery(projectId: string): SqlFragment {
+ return sql`SELECT DISTINCT arrayJoin(mapKeys(properties)) as key FROM ${sql.id(TABLE.profiles)} WHERE project_id = ${sql.string(projectId)} AND is_external = ${sql.bool(true)}`;
+}
+
+// ---- packages/trpc/src/routers/profile.ts's inline queries
+
+export function profileActivityQuery(query: {
+ projectId: string;
+ profileId: string;
+}): SqlFragment {
+ return sql`SELECT count(*) as count, toStartOfDay(created_at) as date FROM ${sql.id(TABLE.events)} WHERE project_id = ${sql.string(query.projectId)} and profile_id = ${sql.string(query.profileId)} GROUP BY date ORDER BY date DESC`;
+}
+
+export function profileMostEventsQuery(query: {
+ projectId: string;
+ profileId: string;
+}): SqlFragment {
+ return sql`SELECT count(*) as count, name FROM ${sql.id(TABLE.events)} WHERE name NOT IN ('screen_view', 'session_start', 'session_end') AND project_id = ${sql.string(query.projectId)} and profile_id = ${sql.string(query.profileId)} GROUP BY name ORDER BY count DESC`;
+}
+
+const POPULAR_ROUTES_LIMIT = 10;
+
+export function profilePopularRoutesQuery(query: {
+ projectId: string;
+ profileId: string;
+}): SqlFragment {
+ return sql`SELECT count(*) as count, path FROM ${sql.id(TABLE.events)} WHERE name = 'screen_view' AND project_id = ${sql.string(query.projectId)} and profile_id = ${sql.string(query.profileId)} GROUP BY path ORDER BY count DESC LIMIT ${sql.uint64(POPULAR_ROUTES_LIMIT)}`;
+}
+
+export function profilePropertyNamesQuery(projectId: string): SqlFragment {
+ return sql`SELECT distinct mapKeys(properties) as keys from ${sql.id(TABLE.profiles)} where project_id = ${sql.string(projectId)};`;
+}
+
+export function powerUsersQuery(query: {
+ projectId: string;
+ take: number;
+ offset: number;
+}): SqlFragment {
+ return sql`
+ SELECT profile_id, count(*) as count
+ FROM ${sql.id(TABLE.events)}
+ WHERE
+ profile_id != ''
+ AND project_id = ${sql.string(query.projectId)}
+ GROUP BY profile_id
+ ORDER BY count() DESC
+ LIMIT ${sql.uint64(query.take)} ${optional(query.offset, () => sql`OFFSET ${sql.uint64(query.offset)}`)}`;
+}
+
+/** The only bare columns `profile.properties` offers the picker. */
+export const PROFILE_VALUE_COLUMNS = [
+ 'id',
+ 'first_name',
+ 'last_name',
+ 'email',
+] as const;
+
+const PROPERTIES_PREFIX = /^properties\./;
+
+/**
+ * V1 interpolated `property` raw into the SELECT; a bare column now has to be
+ * one of `PROFILE_VALUE_COLUMNS` (`sql.id` throws otherwise).
+ */
+export function profileValuesQuery(query: {
+ projectId: string;
+ property: string;
+}): SqlFragment {
+ const values = PROPERTIES_PREFIX.test(query.property)
+ ? sql`distinct arrayMap(x -> trim(x), mapValues(mapExtractKeyLike(properties, ${sql.string(
+ query.property.replace(PROPERTIES_PREFIX, '').replace('.*.', '.%.')
+ )}))) as values`
+ : sql`${sql.id(query.property, PROFILE_VALUE_COLUMNS)} as values`;
+ return sql`SELECT ${values} FROM ${sql.id(TABLE.profiles)} WHERE project_id = ${sql.string(query.projectId)}`;
+}
diff --git a/packages/core/src/modules/realtime/realtime.service.ts b/packages/core/src/modules/realtime/realtime.service.ts
index c7627325d..4dd427f30 100644
--- a/packages/core/src/modules/realtime/realtime.service.ts
+++ b/packages/core/src/modules/realtime/realtime.service.ts
@@ -33,7 +33,7 @@
// and this module's queries haven't been converted yet.
import { clix } from '@openpanel/db/src/clickhouse/query-builder';
-import type { IClickhouseEvent } from '@openpanel/db/src/services/event.service';
+import type { IClickhouseEvent } from '../event/event.service';
import type { IPublishChannels } from '@openpanel/redis';
import { subMinutes } from 'date-fns';
import sqlstring from 'sqlstring';
@@ -54,11 +54,11 @@ function loadChClient() {
}
function loadEventService() {
- return import('@openpanel/db/src/services/event.service');
+ return import('../event/event.service');
}
function loadProfileService() {
- return import('@openpanel/db/src/services/profile.service');
+ return import('../profile/profile.service');
}
function loadEventBuffer() {
diff --git a/packages/core/src/modules/session/session.service.ts b/packages/core/src/modules/session/session.service.ts
index 8b51e4be0..182ef5a63 100644
--- a/packages/core/src/modules/session/session.service.ts
+++ b/packages/core/src/modules/session/session.service.ts
@@ -13,11 +13,11 @@
// pino-pretty worker per `bun test --isolate` file. `@openpanel/redis`'s
// `cacheable` and the `sql` tag have no such side effect.
-import type { IServiceProfile } from '@openpanel/db/src/services/profile.service';
import { cacheable } from '@openpanel/redis';
import type { IChartEventFilter } from '@openpanel/validation';
import type { ServiceDeps } from '../../services';
import { getSafeJson } from '../../shared/json';
+import type { IServiceProfile } from '../profile/profile.service';
import { convertClickhouseDateToJs } from './src/dates';
import {
hasSessionListLookback,
@@ -45,8 +45,12 @@ function loadChClient() {
return import('@openpanel/db/src/clickhouse/client');
}
+// Core's own profile service, not @openpanel/db's shim: the shim re-exports
+// the core barrel, which would route this lazy edge back through
+// session-end → event.service → here — a dynamic-import cycle rolldown
+// cannot finalize when apps/worker bundles the workspace.
function loadProfileService() {
- return import('@openpanel/db/src/services/profile.service');
+ return import('../profile/profile.service');
}
function loadFilterCompiler() {
diff --git a/packages/core/src/modules/session/src/session-end.test.ts b/packages/core/src/modules/session/src/session-end.test.ts
index 080e13a85..442ddb4c6 100644
--- a/packages/core/src/modules/session/src/session-end.test.ts
+++ b/packages/core/src/modules/session/src/session-end.test.ts
@@ -4,7 +4,7 @@
// id-gated to the closed session.
import { describe, expect, mock, test } from 'bun:test';
-import type { IServiceCreateEventPayload } from '@openpanel/db/src/services/event.service';
+import type { IServiceCreateEventPayload } from '../../event/event.service';
import {
createSessionEnd,
getSessionEndJobId,
diff --git a/packages/core/src/modules/session/src/session-end.ts b/packages/core/src/modules/session/src/session-end.ts
index 926728825..45d1a6f1b 100644
--- a/packages/core/src/modules/session/src/session-end.ts
+++ b/packages/core/src/modules/session/src/session-end.ts
@@ -2,13 +2,20 @@
// utils/session-handler.ts (M7-001). The worker's copies are thin delegates
// onto this file until apps/worker dies (P9).
-import type {
- IClickhouseEvent,
- IServiceCreateEventPayload,
- IServiceEvent,
-} from '@openpanel/db/src/services/event.service';
import type { EnqueueOptions } from '../../../jobs/define';
import type { Logger } from '../../../logger';
+// Static, not lazy like the db imports below: core's event.service touches no
+// client at import time, and a dynamic edge here closes a dynamic-import cycle
+// (event.service ⇢ session.service → this file) that panics rolldown when
+// apps/worker bundles the workspace.
+import {
+ createEvent,
+ type IClickhouseEvent,
+ type IServiceCreateEventPayload,
+ type IServiceEvent,
+ transformEvent,
+ transformSessionToEvent,
+} from '../../event/event.service';
import type { INotificationRuleCached } from '../../notification/notification.service';
import type { IClickhouseSession } from '../session.service';
import { convertClickhouseDateToJs } from './dates';
@@ -113,13 +120,11 @@ export async function loadSessionEndDeps(
): Promise<SessionEndDeps> {
const [
{ chQuery },
- eventService,
{ profileBackfillBuffer },
notificationService,
{ checkNotificationRulesForSessionEnd },
] = await Promise.all([
import('@openpanel/db/src/clickhouse/client'),
- import('@openpanel/db/src/services/event.service'),
import('@openpanel/db/src/buffers'),
import('../../notification/notification.service'),
import('@openpanel/db/src/services/notification.service'),
@@ -127,11 +132,11 @@ export async function loadSessionEndDeps(
return {
...runtime,
logger,
- createEvent: eventService.createEvent,
- transformEvent: eventService.transformEvent,
- transformSessionToEvent: eventService.transformSessionToEvent,
+ createEvent,
+ transformEvent,
+ transformSessionToEvent,
getEvents: async (query) =>
- (await chQuery<IClickhouseEvent>(query)).map(eventService.transformEvent),
+ (await chQuery<IClickhouseEvent>(query)).map(transformEvent),
profileBackfill: profileBackfillBuffer,
notifications: {
getRules: notificationService.getNotificationRulesByProjectId,
diff --git a/packages/core/src/rest.routes.ts b/packages/core/src/rest.routes.ts
index a17dbf79a..8896f4993 100644
--- a/packages/core/src/rest.routes.ts
+++ b/packages/core/src/rest.routes.ts
@@ -16,6 +16,7 @@ import { healthRoutes } from './modules/health/health.routes';
import { importRoutes } from './modules/import/import.routes';
import { integrationRoutes } from './modules/integration/integration.routes';
import { mcpRoutes } from './modules/mcp/mcp.routes';
+import { profileRoutes } from './modules/profile/profile.routes';
import { projectRoutes } from './modules/project/project.routes';
import { realtimeRoutes } from './modules/realtime/realtime.routes';
import { subscriptionRoutes } from './modules/subscription/subscription.routes';
@@ -35,8 +36,9 @@ const OPENAPI_EXCLUDED_PATHS = ['/metrics'];
// parameters in a way the bare `Elysia` type cannot express.
//
// import's /import/events is the first module to land here (M5-004);
-// project's and client's /manage/* (M6-002) joined it — root-client-authed
-// API surface, same as /import, not session-authed like dashboardRoutes.
+// project's and client's /manage/* (M6-002) and profile's /profile* (M7-002)
+// joined it — client-authed API surface, same as /import, not session-authed
+// like dashboardRoutes.
// None of it is yet reachable: the clientAuth macro's authenticator is a P8
// stub that always returns null (import.routes.ts's header), and main.ts
// does not mount `publicApiRoutes` until a real `AppDeps` exists (P3/P4/P8).
@@ -44,7 +46,8 @@ export const publicApiRoutes = (deps: AppDeps) =>
new Elysia({ name: 'core/public-api-routes' })
.use(importRoutes(deps))
.use(projectRoutes(deps))
- .use(clientRoutes(deps));
+ .use(clientRoutes(deps))
+ .use(profileRoutes(deps));
// gsc's callback was the first module to land here (M5-002); assistant's
// `/ai/agents/*` (M5-005), mcp's `/mcp` (M5-007) and auth's `/oauth/*`
diff --git a/packages/core/src/rpc.router.ts b/packages/core/src/rpc.router.ts
index 5b9fc2225..d0161de2a 100644
--- a/packages/core/src/rpc.router.ts
+++ b/packages/core/src/rpc.router.ts
@@ -10,6 +10,8 @@ import { clientRouter } from './modules/client/client.rpc';
import { cohortRouter } from './modules/cohort/cohort.rpc';
import { conversationRouter } from './modules/conversation/conversation.rpc';
import { emailRouter } from './modules/email/email.rpc';
+import { eventRouter } from './modules/event/event.rpc';
+import { groupRouter } from './modules/group/group.rpc';
import { gscRouter } from './modules/gsc/gsc.rpc';
import { healthRouter } from './modules/health/health.rpc';
import { importRouter } from './modules/import/import.rpc';
@@ -18,6 +20,7 @@ import { integrationRouter } from './modules/integration/integration.rpc';
import { notificationRouter } from './modules/notification/notification.rpc';
import { onboardingRouter } from './modules/onboarding/onboarding.rpc';
import { organizationRouter } from './modules/organization/organization.rpc';
+import { profileRouter } from './modules/profile/profile.rpc';
import { projectRouter } from './modules/project/project.rpc';
import { realtimeRouter } from './modules/realtime/realtime.rpc';
import { referenceRouter } from './modules/reference/reference.rpc';
@@ -49,6 +52,9 @@ export const appRouter = createTRPCRouter({
integration: integrationRouter,
subscription: subscriptionRouter,
session: sessionRouter,
+ event: eventRouter,
+ profile: profileRouter,
+ group: groupRouter,
});
export type AppRouter = typeof appRouter;
diff --git a/packages/core/src/services.ts b/packages/core/src/services.ts
index b3dc6b17e..c1411ff6d 100644
--- a/packages/core/src/services.ts
+++ b/packages/core/src/services.ts
@@ -11,6 +11,14 @@ import {
type CohortService,
createCohortService,
} from './modules/cohort/cohort.service';
+import {
+ createEventService,
+ type EventService,
+} from './modules/event/event.service';
+import {
+ createGroupService,
+ type GroupService,
+} from './modules/group/group.service';
import { createGscService, type GscService } from './modules/gsc/gsc.service';
import {
createImportService,
@@ -32,6 +40,10 @@ import {
createOrganizationService,
type OrganizationService,
} from './modules/organization/organization.service';
+import {
+ createProfileService,
+ type ProfileService,
+} from './modules/profile/profile.service';
import {
createSessionService,
type SessionService,
@@ -62,6 +74,9 @@ export interface Services {
onboarding: OnboardingService;
notification: NotificationService;
session: SessionService;
+ event: EventService;
+ profile: ProfileService;
+ group: GroupService;
}
export function createServices(deps: ServiceDeps): Services {
@@ -78,5 +93,8 @@ export function createServices(deps: ServiceDeps): Services {
onboarding: createOnboardingService(deps),
notification: createNotificationService(deps),
session: createSessionService(deps),
+ event: createEventService(deps),
+ profile: createProfileService(deps),
+ group: createGroupService(deps),
};
}
diff --git a/packages/db/src/services/event.service.ts b/packages/db/src/services/event.service.ts
index 907607158..989a7fd1b 100644
--- a/packages/db/src/services/event.service.ts
+++ b/packages/db/src/services/event.service.ts
@@ -1,1445 +1,52 @@
-import { DateTime, toDots } from '@openpanel/common';
-import { cacheable } from '@openpanel/redis';
-import type { IChartEventFilter } from '@openpanel/validation';
-import { assocPath, last, mergeDeepRight, path, uniq } from 'ramda';
-import sqlstring from 'sqlstring';
-import { v4 as uuid } from 'uuid';
-import { botBuffer, eventBuffer } from '../buffers';
-import {
- ch,
- chQuery,
- convertClickhouseDateToJs,
- formatClickhouseDate,
- TABLE_NAMES,
-} from '../clickhouse/client';
-import { clix, type Query } from '../clickhouse/query-builder';
-import type { EventMeta, Prisma } from '../prisma-client';
-import { db } from '../prisma-client';
-import { createSqlBuilder, type SqlBuilderObject } from '../sql-builder';
-import { resolveMaxLookbackDays } from './lookback';
-import { getEventFiltersWhereClause } from './chart.service';
-import { buildFilterWhere } from './filter-where.service';
-import type { IServiceProfile, IServiceUpsertProfile } from './profile.service';
-import {
- getProfileById,
- getProfilesCached,
- upsertProfile,
-} from './profile.service';
-import type { IClickhouseSession } from './session.service';
-
-export type IImportedEvent = Omit<
- IClickhouseEvent,
- 'properties' | 'profile' | 'meta' | 'imported_at'
-> & {
- properties: Record<string, unknown>;
-};
-
-export interface IServicePage {
- path: string;
- count: number;
- project_id: string;
- first_seen: string;
- title: string;
- origin: string;
-}
-
-export interface IClickhouseBotEvent {
- id: string;
- name: string;
- type: string;
- project_id: string;
- path: string;
- created_at: string;
-}
-
-export interface IServiceBotEvent {
- id: string;
- name: string;
- type: string;
- projectId: string;
- path: string;
- createdAt: Date;
-}
-
-export type IServiceCreateBotEventPayload = Omit<IServiceBotEvent, 'id'>;
-
-export interface IClickhouseEvent {
- id: string;
- name: string;
- device_id: string;
- profile_id: string;
- project_id: string;
- session_id: string;
- path: string;
- origin: string;
- referrer: string;
- referrer_name: string;
- referrer_type: string;
- duration: number;
- properties: Record<string, string | number | boolean | undefined | null>;
- created_at: string;
- country: string;
- city: string;
- region: string;
- longitude: number | null;
- latitude: number | null;
- os: string;
- os_version: string;
- browser: string;
- browser_version: string;
- device: string;
- brand: string;
- model: string;
- imported_at: string | null;
- // Ingestion (ClickHouse-insert) time. Set explicitly at insert time; the
- // column DEFAULTs to created_at for rows that omit it. Used as the cursor for
- // object-store exports. Optional here because most read queries don't select
- // it.
- inserted_at?: string;
- sdk_name: string;
- sdk_version: string;
- revenue?: number;
- groups: string[];
-
- // They do not exist here. Just make ts happy for now
- profile?: IServiceProfile;
- meta?: EventMeta;
-}
-
-export function transformSessionToEvent(
- session: IClickhouseSession
-): IServiceEvent {
- return {
- id: '', // Not used
- name: 'screen_view',
- sessionId: session.id,
- profileId: session.profile_id,
- path: session.exit_path,
- origin: session.exit_origin,
- createdAt: convertClickhouseDateToJs(session.ended_at),
- referrer: session.referrer,
- referrerName: session.referrer_name,
- referrerType: session.referrer_type,
- os: session.os,
- osVersion: session.os_version,
- browser: session.browser,
- browserVersion: session.browser_version,
- device: session.device,
- brand: session.brand,
- model: session.model,
- country: session.country,
- region: session.region,
- city: session.city,
- longitude: session.longitude,
- latitude: session.latitude,
- projectId: session.project_id,
- deviceId: session.device_id,
- duration: 0,
- revenue: session.revenue,
- properties: {
- is_bounce: session.is_bounce,
- __query: {
- utm_medium: session.utm_medium,
- utm_source: session.utm_source,
- utm_campaign: session.utm_campaign,
- utm_content: session.utm_content,
- utm_term: session.utm_term,
- },
- },
- profile: undefined,
- meta: undefined,
- importedAt: undefined,
- sdkName: undefined,
- sdkVersion: undefined,
- groups: [],
- };
-}
-
-export function transformEvent(event: IClickhouseEvent): IServiceEvent {
- return {
- id: event.id,
- name: event.name,
- deviceId: event.device_id,
- profileId: event.profile_id,
- projectId: event.project_id,
- sessionId: event.session_id,
- properties: event.properties,
- createdAt: convertClickhouseDateToJs(event.created_at),
- country: event.country,
- city: event.city,
- region: event.region,
- longitude: event.longitude,
- latitude: event.latitude,
- os: event.os,
- osVersion: event.os_version,
- browser: event.browser,
- browserVersion: event.browser_version,
- device: event.device,
- brand: event.brand,
- model: event.model,
- path: event.path,
- origin: event.origin,
- referrer: event.referrer,
- referrerName: event.referrer_name,
- referrerType: event.referrer_type,
- meta: event.meta,
- importedAt: event.imported_at ? new Date(event.imported_at) : undefined,
- sdkName: event.sdk_name,
- sdkVersion: event.sdk_version,
- profile: event.profile,
- revenue: event.revenue,
- groups: event.groups ?? [],
- };
-}
-
-export type IServiceCreateEventPayload = Omit<
- IServiceEvent,
- 'id' | 'importedAt' | 'profile' | 'meta'
->;
-/**
- * A create payload whose id was already minted upstream (the ingest producer).
- * Reusing it means a redelivered Kafka message lands as an identical-id row.
- */
-export type IServiceCreateEventPayloadWithId = IServiceCreateEventPayload & {
- id?: string;
-};
-export type IServiceImportedEventPayload = Omit<
- IServiceEvent,
- 'profile' | 'meta'
->;
-
-export interface IServiceEvent {
- id: string;
- name: string;
- deviceId: string;
- profileId: string;
- projectId: string;
- sessionId: string;
- properties: Record<string, unknown> & {
- hash?: string;
- query?: Record<string, unknown>;
- };
- createdAt: Date;
- country?: string | undefined;
- city?: string | undefined;
- region?: string | undefined;
- longitude?: number | undefined | null;
- latitude?: number | undefined | null;
- os?: string | undefined;
- osVersion?: string | undefined;
- browser?: string | undefined;
- browserVersion?: string | undefined;
- device?: string | undefined;
- brand?: string | undefined;
- model?: string | undefined;
- duration?: number;
- path: string;
- origin: string;
- referrer: string | undefined;
- referrerName: string | undefined;
- referrerType: string | undefined;
- importedAt: Date | undefined;
- profile: IServiceProfile | undefined;
- meta: EventMeta | undefined;
- sdkName: string | undefined;
- sdkVersion: string | undefined;
- revenue?: number;
- groups: string[];
-}
-
-type SelectHelper<T> = {
- [K in keyof T]?: boolean;
+// The event service lives in @openpanel/core now (M7-002):
+// packages/core/src/modules/event/event.service.ts, with every ClickHouse
+// query rewritten onto the `sql` tag (packages/core/src/modules/event/src/
+// event.sql.ts). Re-exported here for existing `@openpanel/db` importers
+// (packages/trpc's event router, apps/api's export controller + is-bot hook,
+// apps/worker's incoming-event job, the buffers' row types, the assistant/mcp
+// tools) — same shape as session.service.ts since M7-001.
+export {
+ createBotEvent,
+ createEvent,
+ EVENT_COLUMNS,
+ type EventListSelect,
+ type GetEventListOptions,
+ getConversionEventNames,
+ getEventById,
+ getEventList,
+ getEventMetas,
+ getEventMetasCached,
+ getEventPropertyValuesCore,
+ getEvents,
+ getEventsCount,
+ getTopEventNames,
+ getTopPages,
+ type IClickhouseBotEvent,
+ type IClickhouseEvent,
+ type IEventColumn,
+ type IImportedEvent,
+ type IServiceBotEvent,
+ type IServiceCreateBotEventPayload,
+ type IServiceCreateEventPayload,
+ type IServiceCreateEventPayloadWithId,
+ type IServiceEvent,
+ type IServiceEventMinimal,
+ type IServiceImportedEventPayload,
+ type IServicePage,
+ listEventNamesCore,
+ listEventPropertiesCore,
+ type QueryEventsInput,
+ queryEventsCore,
+ transformEvent,
+ transformMinimalEvent,
+ transformSessionToEvent,
+} from '@openpanel/core';
+
+import { getEventById } from '@openpanel/core';
+
+// V1's `eventService.getById(...)` shape, kept for the callers that still
+// reach it through `@openpanel/db`. Resolved at call time: core ↔ db is an
+// import cycle and this module may evaluate first.
+export const eventService = {
+ getById: (input: Parameters<typeof getEventById>[0]) => getEventById(input),
};
-
-export interface IServiceEventMinimal {
- id: string;
- name: string;
- projectId: string;
- sessionId: string;
- createdAt: Date;
- country?: string | undefined;
- longitude?: number | undefined | null;
- latitude?: number | undefined | null;
- os?: string | undefined;
- browser?: string | undefined;
- device?: string | undefined;
- brand?: string | undefined;
- duration?: number;
- path: string;
- origin: string;
- referrer: string | undefined;
- meta: EventMeta | undefined;
- minimal: boolean;
-}
-
-interface GetEventsOptions {
- profile?: boolean;
- meta?: boolean | Prisma.EventMetaSelect;
-}
-
-function maskString(str: string, mask = '*') {
- const allMasked = str.replace(/(\w)/g, mask);
- if (str.length < 8) {
- return allMasked;
- }
-
- return `${str.slice(0, 4)}${allMasked.slice(4)}`;
-}
-
-export function transformMinimalEvent(
- event: IServiceEvent
-): IServiceEventMinimal {
- return {
- id: event.id,
- name: event.name,
- projectId: event.projectId,
- sessionId: event.sessionId,
- createdAt: event.createdAt,
- country: event.country,
- longitude: event.longitude,
- latitude: event.latitude,
- os: event.os,
- browser: event.browser,
- device: event.device,
- brand: event.brand,
- duration: event.duration,
- path: maskString(event.path),
- origin: event.origin,
- referrer: event.referrer,
- meta: event.meta,
- minimal: true,
- };
-}
-
-export function getEventMetas(projectId: string) {
- return db.eventMeta.findMany({
- where: {
- projectId,
- },
- });
-}
-
-export const getEventMetasCached = cacheable(getEventMetas, 60 * 5);
-
-export async function getEvents(
- sql: string,
- options: GetEventsOptions = {}
-): Promise<IServiceEvent[]> {
- const events = await chQuery<IClickhouseEvent>(sql);
- const projectId = events[0]?.project_id;
- if (options.profile && projectId) {
- const ids = events
- .filter((e) => e.device_id !== e.profile_id)
- .map((e) => e.profile_id);
- const profiles = await getProfilesCached(ids, projectId);
-
- const map = new Map<string, IServiceProfile>();
- for (const profile of profiles) {
- map.set(profile.id, profile);
- }
-
- for (const event of events) {
- event.profile = map.get(event.profile_id) ?? {
- id: event.profile_id,
- email: '',
- avatar: '',
- firstName: '',
- lastName: '',
- createdAt: new Date(),
- lastSeenAt: new Date(),
- projectId,
- isExternal: false,
- properties: {},
- groups: [],
- };
- }
- }
-
- if (options.meta && projectId) {
- const metas = await getEventMetasCached(projectId);
- const map = new Map<string, EventMeta>();
- for (const meta of metas) {
- map.set(meta.name, meta);
- }
- for (const event of events) {
- event.meta = map.get(event.name);
- }
- }
- return events.map(transformEvent);
-}
-
-/**
- * Persist an event to ClickHouse (via the buffer) and upsert the profile
- * on session boundaries.
- *
- * Does NOT touch the session-row buffer. Callers producing non-session_start
- * / session_end events are responsible for calling `sessionBuffer.ingest()`
- * before this. `incoming-event.ts` is the only such caller today; everywhere
- * else (session_start, session_end) the session-row update is correctly a
- * no-op anyway.
- */
-export async function createEvent(payload: IServiceCreateEventPayloadWithId) {
- if (!payload.profileId && payload.deviceId) {
- payload.profileId = payload.deviceId;
- }
-
- const event: IClickhouseEvent = {
- id: payload.id ?? uuid(),
- name: payload.name,
- device_id: payload.deviceId,
- profile_id: payload.profileId ? String(payload.profileId) : '',
- project_id: payload.projectId,
- session_id: payload.sessionId,
- properties: toDots(payload.properties),
- path: payload.path ?? '',
- origin: payload.origin ?? '',
- created_at: DateTime.fromJSDate(payload.createdAt)
- .setZone('UTC')
- .toFormat('yyyy-MM-dd HH:mm:ss.SSS'),
- country: payload.country ?? '',
- city: payload.city ?? '',
- region: payload.region ?? '',
- longitude: payload.longitude ?? null,
- latitude: payload.latitude ?? null,
- os: payload.os ?? '',
- os_version: payload.osVersion ?? '',
- browser: payload.browser ?? '',
- browser_version: payload.browserVersion ?? '',
- device: payload.device ?? '',
- brand: payload.brand ?? '',
- model: payload.model ?? '',
- duration: payload.duration ?? 0,
- referrer: payload.referrer ?? '',
- referrer_name: payload.referrerName ?? '',
- referrer_type: payload.referrerType ?? '',
- imported_at: null,
- // Ingestion time, used as the export cursor. Stamped here rather than via the
- // column DEFAULT so backdated events (server-side, offline, past timestamps)
- // still get a real, monotonic-ish insert time instead of their event time.
- inserted_at: DateTime.utc().toFormat('yyyy-MM-dd HH:mm:ss.SSS'),
- sdk_name: payload.sdkName ?? '',
- sdk_version: payload.sdkVersion ?? '',
- revenue: payload.revenue,
- groups: payload.groups ?? [],
- };
-
- eventBuffer.add(event);
-
- const promises: Promise<unknown>[] = [];
-
- if (payload.profileId) {
- const profile: IServiceUpsertProfile = {
- id: String(payload.profileId),
- isExternal: payload.profileId !== payload.deviceId,
- projectId: payload.projectId,
- properties: {
- path: payload.path,
- country: payload.country,
- city: payload.city,
- region: payload.region,
- longitude: payload.longitude,
- latitude: payload.latitude,
- os: payload.os,
- os_version: payload.osVersion,
- browser: payload.browser,
- browser_version: payload.browserVersion,
- device: payload.device,
- brand: payload.brand,
- model: payload.model,
- referrer: payload.referrer,
- referrer_name: payload.referrerName,
- referrer_type: payload.referrerType,
- },
- };
-
- // Only upsert the profile on session boundaries.
- // - session_start covers fresh activity.
- // - session_end is synthesized server-side by the worker.
- // Identified users' explicit profile writes (op.identify(), op.setProfile())
- // go through the controller path and are not affected by this branch.
- //
- // `isFromEvent=true` activates profile-buffer's cache shortcut: if the
- // profile is in the 1h Redis cache (i.e. recently flushed), the add is
- // skipped. Trade-off: profile.last_seen_at granularity is capped at the
- // cache TTL (~1h) rather than per-session. We accept this because
- // (a) profile-buffer was the leading indicator in the 2026-05-20 buildup
- // and was processing ~2 writes per session per anonymous user;
- // (b) the bulk of those writes carried no new information (anonymous
- // profile data is event-derived and stable across a session);
- // (c) recency queries should derive from event timestamps, not from
- // profile.last_seen_at.
- if (payload.name === 'session_start' || payload.name === 'session_end') {
- promises.push(upsertProfile(profile, true));
- }
- }
-
- await Promise.all(promises);
-
- return {
- document: event,
- };
-}
-
-export interface GetEventListOptions {
- projectId: string;
- profileId?: string;
- sessionId?: string;
- groupId?: string;
- cohortId?: string;
- take: number;
- cursor?: number | Date;
- events?: string[] | null;
- filters?: IChartEventFilter[];
- startDate?: Date;
- endDate?: Date;
- select?: SelectHelper<IServiceEvent>;
- custom?: (sb: SqlBuilderObject) => void;
- dateIntervalInDays?: number;
-}
-
-export async function getEventList(options: GetEventListOptions) {
- const {
- cursor,
- take,
- projectId,
- profileId,
- sessionId,
- groupId,
- cohortId,
- events,
- filters,
- startDate,
- endDate,
- custom,
- select: incomingSelect,
- dateIntervalInDays = 0.5,
- } = options;
- const { sb, getSql, join } = createSqlBuilder();
-
- // Deployment-tunable ceiling for the empty-result lookback (see lookback.ts).
- const MAX_DATE_INTERVAL_IN_DAYS = resolveMaxLookbackDays(
- 'EVENT_LIST_MAX_LOOKBACK_DAYS',
- 365 * 5,
- );
- // Cap the date interval to prevent infinity
- const safeDateIntervalInDays = Math.min(
- dateIntervalInDays,
- MAX_DATE_INTERVAL_IN_DAYS
- );
-
- if (typeof cursor === 'number') {
- sb.offset = Math.max(0, (cursor ?? 0) * take);
- } else if (cursor instanceof Date) {
- sb.where.cursorWindow = `created_at >= toDateTime64(${sqlstring.escape(formatClickhouseDate(cursor))}, 3) - INTERVAL ${safeDateIntervalInDays} DAY`;
- sb.where.cursor = `created_at < ${sqlstring.escape(formatClickhouseDate(cursor))}`;
- }
-
- if (!(cursor || (startDate && endDate))) {
- sb.where.cursorWindow = `created_at >= toDateTime64(${sqlstring.escape(formatClickhouseDate(new Date()))}, 3) - INTERVAL ${safeDateIntervalInDays} DAY`;
- }
-
- sb.limit = take;
- sb.where.projectId = `project_id = ${sqlstring.escape(projectId)}`;
- const select = mergeDeepRight(
- {
- id: true,
- name: true,
- deviceId: true,
- profileId: true,
- sessionId: true,
- projectId: true,
- createdAt: true,
- path: true,
- duration: true,
- city: true,
- country: true,
- os: true,
- browser: true,
- },
- incomingSelect ?? {}
- );
-
- sb.select.createdAt = 'created_at';
- sb.select.projectId = 'project_id';
-
- if (select.id) {
- sb.select.id = 'id';
- }
- if (select.name) {
- sb.select.name = 'name';
- }
- if (select.deviceId) {
- sb.select.deviceId = 'device_id';
- }
- if (select.profileId) {
- sb.select.profileId = 'profile_id';
- }
- if (select.projectId) {
- sb.select.projectId = 'project_id';
- }
- if (select.sessionId) {
- sb.select.sessionId = 'session_id';
- }
- if (select.properties) {
- sb.select.properties = 'properties';
- }
- if (select.country) {
- sb.select.country = 'country';
- }
- if (select.city) {
- sb.select.city = 'city';
- }
- if (select.region) {
- sb.select.region = 'region';
- }
- if (select.longitude) {
- sb.select.longitude = 'longitude';
- }
- if (select.latitude) {
- sb.select.latitude = 'latitude';
- }
- if (select.os) {
- sb.select.os = 'os';
- }
- if (select.osVersion) {
- sb.select.osVersion = 'os_version';
- }
- if (select.browser) {
- sb.select.browser = 'browser';
- }
- if (select.browserVersion) {
- sb.select.browserVersion = 'browser_version';
- }
- if (select.device) {
- sb.select.device = 'device';
- }
- if (select.brand) {
- sb.select.brand = 'brand';
- }
- if (select.model) {
- sb.select.model = 'model';
- }
- if (select.path) {
- sb.select.path = 'path';
- }
- if (select.origin) {
- sb.select.origin = 'origin';
- }
- if (select.referrer) {
- sb.select.referrer = 'referrer';
- }
- if (select.referrerName) {
- sb.select.referrerName = 'referrer_name';
- }
- if (select.referrerType) {
- sb.select.referrerType = 'referrer_type';
- }
- if (select.importedAt) {
- sb.select.importedAt = 'imported_at';
- }
- if (select.sdkName) {
- sb.select.sdkName = 'sdk_name';
- }
- if (select.sdkVersion) {
- sb.select.sdkVersion = 'sdk_version';
- }
- if (select.revenue) {
- sb.select.revenue = 'revenue';
- }
-
- if (select.groups) {
- sb.select.groups = 'groups';
- }
-
- if (profileId) {
- // Identity stitching: pull pre-identification anonymous events from devices
- // this profile has used, plus the profile's own identified events.
- // Anonymous events have profile_id = device_id (see event.service.ts:357);
- // the guard prevents leaking another user's identified events when a
- // device_id collides (NAT, shared UA, server-side senders).
- sb.where.deviceId = `((device_id IN (SELECT device_id as did FROM ${TABLE_NAMES.events} WHERE project_id = ${sqlstring.escape(projectId)} AND device_id != '' AND profile_id = ${sqlstring.escape(profileId)} group by did) AND profile_id = device_id) OR profile_id = ${sqlstring.escape(profileId)})`;
- }
-
- if (sessionId) {
- sb.where.sessionId = `session_id = ${sqlstring.escape(sessionId)}`;
- }
-
- if (groupId) {
- sb.where.groupId = `has(groups, ${sqlstring.escape(groupId)})`;
- }
-
- if (cohortId) {
- sb.where.cohortId = `profile_id IN (SELECT profile_id FROM ${TABLE_NAMES.cohort_members} FINAL WHERE cohort_id = ${sqlstring.escape(cohortId)} AND project_id = ${sqlstring.escape(projectId)})`;
- }
-
- if (startDate && endDate) {
- sb.where.created_at = `toDate(created_at) BETWEEN toDate('${formatClickhouseDate(startDate)}') AND toDate('${formatClickhouseDate(endDate)}')`;
- }
-
- if (events && events.length > 0) {
- sb.where.events = `name IN (${join(
- events.map((event) => sqlstring.escape(event)),
- ','
- )})`;
- }
-
- if (filters) {
- sb.where = {
- ...sb.where,
- ...getEventFiltersWhereClause(filters, projectId, 'e'),
- };
-
- // Join profiles table if any filter uses profile fields
- const profileFilters = filters
- .filter((f) => f.name.startsWith('profile.'))
- .map((f) => f.name.replace('profile.', ''));
-
- if (profileFilters.length > 0) {
- sb.joins.profiles = `LEFT ANY JOIN (SELECT id, ${uniq(profileFilters.map((f) => f.split('.')[0])).join(', ')} FROM ${TABLE_NAMES.profiles} FINAL WHERE project_id = ${sqlstring.escape(projectId)}) as profile on profile.id = profile_id`;
- }
-
- // Join groups table if any filter uses group fields
- const groupFilters = filters.filter((f) => f.name.startsWith('group.'));
- if (groupFilters.length > 0) {
- sb.joins.groups = 'ARRAY JOIN groups AS _group_id';
- sb.joins.groups_cte = `LEFT ANY JOIN (SELECT id, name, type, properties FROM ${TABLE_NAMES.groups} FINAL WHERE project_id = ${sqlstring.escape(projectId)}) AS _g ON _g.id = _group_id`;
- }
- }
-
- sb.orderBy.created_at = 'created_at DESC, id ASC';
-
- if (custom) {
- custom(sb);
- }
-
- const data = await getEvents(getSql(), {
- profile: select.profile ?? true,
- meta: select.meta ?? true,
- });
-
- // If we dont get any events, try without the cursor window
- if (
- data.length === 0 &&
- sb.where.cursorWindow &&
- safeDateIntervalInDays < MAX_DATE_INTERVAL_IN_DAYS
- ) {
- return getEventList({
- ...options,
- dateIntervalInDays: dateIntervalInDays * 2,
- });
- }
-
- return data;
-}
-
-export async function getEventsCount({
- projectId,
- profileId,
- groupId,
- cohortId,
- events,
- filters,
- startDate,
- endDate,
-}: Omit<GetEventListOptions, 'cursor' | 'take'>) {
- const { sb, getSql, join } = createSqlBuilder();
- sb.where.projectId = `project_id = ${sqlstring.escape(projectId)}`;
- if (profileId) {
- sb.where.profileId = `profile_id = ${sqlstring.escape(profileId)}`;
- }
-
- if (groupId) {
- sb.where.groupId = `has(groups, ${sqlstring.escape(groupId)})`;
- }
-
- if (cohortId) {
- sb.where.cohortId = `profile_id IN (SELECT profile_id FROM ${TABLE_NAMES.cohort_members} FINAL WHERE cohort_id = ${sqlstring.escape(cohortId)} AND project_id = ${sqlstring.escape(projectId)})`;
- }
-
- if (startDate && endDate) {
- sb.where.created_at = `toDate(created_at) BETWEEN toDate('${formatClickhouseDate(startDate)}') AND toDate('${formatClickhouseDate(endDate)}')`;
- }
-
- if (events && events.length > 0) {
- sb.where.events = `name IN (${join(
- events.map((event) => sqlstring.escape(event)),
- ','
- )})`;
- }
-
- if (filters) {
- sb.where = {
- ...sb.where,
- ...getEventFiltersWhereClause(filters, projectId, 'e'),
- };
-
- // Join profiles table if any filter uses profile fields
- const profileFilters = filters
- .filter((f) => f.name.startsWith('profile.'))
- .map((f) => f.name.replace('profile.', ''));
-
- if (profileFilters.length > 0) {
- sb.joins.profiles = `LEFT ANY JOIN (SELECT id, ${uniq(profileFilters.map((f) => f.split('.')[0])).join(', ')} FROM ${TABLE_NAMES.profiles} FINAL WHERE project_id = ${sqlstring.escape(projectId)}) as profile on profile.id = profile_id`;
- }
-
- // Join groups table if any filter uses group fields
- const groupFilters = filters.filter((f) => f.name.startsWith('group.'));
- if (groupFilters.length > 0) {
- sb.joins.groups = 'ARRAY JOIN groups AS _group_id';
- sb.joins.groups_cte = `LEFT ANY JOIN (SELECT id, name, type, properties FROM ${TABLE_NAMES.groups} FINAL WHERE project_id = ${sqlstring.escape(projectId)}) AS _g ON _g.id = _group_id`;
- }
- }
-
- const res = await chQuery<{ count: number }>(
- getSql().replace('*', 'count(*) as count')
- );
-
- return res[0]?.count ?? 0;
-}
-
-export function createBotEvent({
- name,
- type,
- projectId,
- createdAt,
- path,
-}: IServiceCreateBotEventPayload) {
- return botBuffer.add({
- id: uuid(),
- name,
- type,
- project_id: projectId,
- path,
- created_at: formatClickhouseDate(createdAt),
- });
-}
-
-export function getConversionEventNames(projectId: string) {
- return db.eventMeta.findMany({
- where: {
- projectId,
- conversion: true,
- },
- });
-}
-
-export async function getTopPages({
- projectId,
- cursor,
- take,
- search,
-}: {
- projectId: string;
- cursor?: number;
- take: number;
- search?: string;
-}) {
- const res = await chQuery<IServicePage>(`
- SELECT path, count(*) as count, project_id, first_value(created_at) as first_seen, last_value(properties['__title']) as title, origin
- FROM ${TABLE_NAMES.events}
- WHERE name = 'screen_view'
- AND project_id = ${sqlstring.escape(projectId)}
- AND created_at > now() - INTERVAL 30 DAY
- ${search ? `AND path ILIKE '%${search}%'` : ''}
- GROUP BY path, project_id, origin
- ORDER BY count desc
- LIMIT ${take}
- OFFSET ${Math.max(0, (cursor ?? 0) * take)}
- `);
-
- return res;
-}
-
-export interface IEventServiceGetList {
- projectId: string;
- profileId?: string;
- cursor?: Date;
- filters?: IChartEventFilter[];
-}
-
-class EventService {
- constructor(private client: typeof ch) {}
-
- query<T>({
- projectId,
- profileId,
- where,
- select,
- limit,
- filters,
- }: {
- projectId: string;
- profileId?: string;
- where?: {
- profile?: (query: Query<T>) => void;
- event?: (query: Query<T>) => void;
- session?: (query: Query<T>) => void;
- };
- select: {
- profile?: Partial<SelectHelper<IServiceProfile>>;
- event: Partial<SelectHelper<IServiceEvent>>;
- };
- limit?: number;
- orderBy?: keyof IClickhouseEvent;
- filters?: IChartEventFilter[];
- }) {
- // Extract profile filters if any
- const profileFilters =
- filters
- ?.filter((f) => f.name.startsWith('profile.'))
- .map((f) => f.name.replace('profile.', '')) ?? [];
-
- const events = clix(this.client)
- .select<
- Partial<IClickhouseEvent> & {
- // profile
- profileId: string;
- profile_firstName: string;
- profile_lastName: string;
- profile_avatar: string;
- profile_isExternal: boolean;
- profile_createdAt: string;
- }
- >([
- select.event.id && 'e.id as id',
- select.event.deviceId && 'e.device_id as device_id',
- select.event.name && 'e.name as name',
- select.event.path && 'e.path as path',
- select.event.country && 'e.country as country',
- select.event.city && 'e.city as city',
- select.event.os && 'e.os as os',
- select.event.browser && 'e.browser as browser',
- select.event.createdAt && 'e.created_at as created_at',
- select.event.projectId && 'e.project_id as project_id',
- 'e.session_id as session_id',
- 'e.profile_id as profile_id',
- ])
- .from('events e')
- .where('project_id', '=', projectId)
- .when(profileFilters.length > 0, (q) => {
- q.leftJoin(
- `(SELECT id, ${uniq(profileFilters.map((f) => f.split('.')[0])).join(', ')} FROM ${TABLE_NAMES.profiles} FINAL WHERE project_id = ${sqlstring.escape(projectId)}) as profile`,
- 'profile.id = e.profile_id'
- );
- })
- .when(!!where?.event, where?.event)
- // Do not limit if profileId, we will limit later since we need the "correct" profileId
- .when(!!limit && !profileId, (q) => q.limit(limit!))
- .orderBy('toDate(created_at)', 'DESC')
- .orderBy('created_at', 'DESC');
-
- const sessions = clix(this.client)
- .select(['id as session_id', 'profile_id'])
- .from('sessions')
- .where('sign', '=', 1)
- .where('project_id', '=', projectId)
- .when(!!where?.session, where?.session)
- .when(!!profileId, (q) => q.where('profile_id', '=', profileId));
-
- const profiles = clix(this.client)
- .select([
- 'id',
- 'any(created_at) as created_at',
- `any(nullIf(first_name, '')) as first_name`,
- `any(nullIf(last_name, '')) as last_name`,
- `any(nullIf(email, '')) as email`,
- `any(nullIf(avatar, '')) as avatar`,
- 'last_value(is_external) as is_external',
- ])
- .from('profiles')
- .where('project_id', '=', projectId)
- .where(
- 'id',
- 'IN',
- clix.exp(
- clix(this.client)
- .select(['profile_id'])
- .from(
- clix.exp(
- clix(this.client)
- .select(['profile_id'])
- .from('cte_sessions')
- .union(
- clix(this.client).select(['profile_id']).from('cte_events')
- )
- )
- )
- .groupBy(['profile_id'])
- )
- )
- .groupBy(['id', 'project_id'])
- .when(!!where?.profile, where?.profile);
-
- return clix(this.client)
- .with('cte_events', events)
- .with('cte_sessions', sessions)
- .with('cte_profiles', profiles)
- .select<
- Partial<IClickhouseEvent> & {
- // profile
- profileId: string;
- profile_firstName: string;
- profile_lastName: string;
- profile_avatar: string;
- profile_isExternal: boolean;
- profile_createdAt: string;
- }
- >([
- select.event.id && 'e.id as id',
- select.event.deviceId && 'e.device_id as device_id',
- select.event.name && 'e.name as name',
- select.event.path && 'e.path as path',
- select.event.country && 'e.country as country',
- select.event.city && 'e.city as city',
- select.event.os && 'e.os as os',
- select.event.browser && 'e.browser as browser',
- select.event.createdAt && 'e.created_at as created_at',
- select.event.projectId && 'e.project_id as project_id',
- select.event.sessionId && 'e.session_id as session_id',
- select.event.profileId && 'e.profile_id as event_profile_id',
- // Profile
- select.profile?.id && 'p.id as profile_id',
- select.profile?.firstName && 'p.first_name as profile_first_name',
- select.profile?.lastName && 'p.last_name as profile_last_name',
- select.profile?.avatar && 'p.avatar as profile_avatar',
- select.profile?.isExternal && 'p.is_external as profile_is_external',
- select.profile?.createdAt && 'p.created_at as profile_created_at',
- select.profile?.email && 'p.email as profile_email',
- select.profile?.properties && 'p.properties as profile_properties',
- ])
- .from('cte_events e')
- .leftJoin('cte_sessions s', 'e.session_id = s.session_id')
- .leftJoin(
- 'cte_profiles p',
- 's.profile_id = p.id AND p.is_external = true'
- )
- .when(!!profileId, (q) => {
- q.where('s.profile_id', '=', profileId);
- q.limit(limit!);
- });
- }
-
- transformFromQuery(res: any[]) {
- return res
- .map((item) => {
- return Object.entries(item).reduce(
- (acc, [prop, val]) => {
- if (prop === 'event_profile_id' && val && !item.profile_id) {
- return assocPath(['profile', 'id'], val, acc);
- }
-
- if (
- prop.startsWith('profile_') &&
- !path(['profile', prop.replace('profile_', '')], acc)
- ) {
- return assocPath(
- ['profile', prop.replace('profile_', '')],
- val,
- acc
- );
- }
- return assocPath([prop], val, acc);
- },
- {
- profile: {},
- } as IClickhouseEvent
- );
- })
- .map(transformEvent);
- }
-
- async getById({
- projectId,
- id,
- createdAt,
- }: {
- projectId: string;
- id: string;
- createdAt?: Date;
- }) {
- const [event, metas] = await Promise.all([
- clix(this.client)
- .select<IClickhouseEvent>(['*'])
- .from('events')
- .where('project_id', '=', projectId)
- .when(!!createdAt, (q) => {
- if (createdAt) {
- q.where('created_at', 'BETWEEN', [
- new Date(createdAt.getTime() - 1000),
- new Date(createdAt.getTime() + 1000),
- ]);
- }
- })
- .where('id', '=', id)
- .limit(1)
- .execute()
- .then((res) => {
- if (!res[0]) {
- return null;
- }
-
- return transformEvent(res[0]);
- }),
- getEventMetasCached(projectId),
- ]);
-
- if (event?.profileId) {
- const profile = await getProfileById(event?.profileId, projectId);
- if (profile) {
- event.profile = profile;
- }
- }
-
- if (event) {
- event.meta = metas.find((meta) => meta.name === event.name);
- }
-
- return event;
- }
-
- async getList({
- projectId,
- profileId,
- cursor,
- filters,
- limit = 50,
- startDate,
- endDate,
- }: IEventServiceGetList & {
- limit?: number;
- startDate?: Date;
- endDate?: Date;
- }) {
- const date = cursor || new Date();
- const query = this.query({
- projectId,
- profileId,
- limit,
- orderBy: 'created_at',
- filters,
- select: {
- event: {
- deviceId: true,
- profileId: true,
- id: true,
- name: true,
- createdAt: true,
- country: true,
- city: true,
- os: true,
- browser: true,
- path: true,
- sessionId: true,
- },
- profile: {
- id: true,
- firstName: true,
- lastName: true,
- avatar: true,
- isExternal: true,
- },
- },
- where: {
- event: (q) => {
- if (startDate && endDate) {
- q.where('created_at', 'BETWEEN', [
- startDate ?? new Date(date.getTime() - 1000 * 60 * 60 * 24 * 3.5),
- cursor ?? endDate,
- ]);
- } else {
- q.where('created_at', '<', date);
- }
- if (filters) {
- q.rawWhere(
- Object.values(
- getEventFiltersWhereClause(filters, projectId)
- ).join(' AND ')
- );
- const groupFilters = filters.filter((f) =>
- f.name.startsWith('group.')
- );
- if (groupFilters.length > 0) {
- q.rawJoin('ARRAY JOIN groups AS _group_id');
- q.rawJoin(
- `LEFT ANY JOIN (SELECT id, name, type, properties FROM ${TABLE_NAMES.groups} FINAL WHERE project_id = ${sqlstring.escape(projectId)}) AS _g ON _g.id = _group_id`
- );
- }
- }
- },
- session: (q) => {
- if (startDate && endDate) {
- q.where('created_at', 'BETWEEN', [
- startDate ?? new Date(date.getTime() - 1000 * 60 * 60 * 24 * 3.5),
- endDate ?? date,
- ]);
- } else {
- q.where('created_at', '<', date);
- }
- },
- },
- })
- .orderBy('toDate(created_at)', 'DESC')
- .orderBy('created_at', 'DESC');
-
- const results = await query.execute();
-
- // Current page items (middle chunk)
- const items = results.slice(0, limit);
-
- // Check if there's a next page
- const hasNext = results.length >= limit;
-
- return {
- items: this.transformFromQuery(items).map((item) => ({
- ...item,
- projectId,
- })),
- meta: {
- next: hasNext ? last(items)?.created_at : null,
- },
- };
- }
-}
-
-export const eventService = new EventService(ch);
-
-import { getCache } from '@openpanel/redis';
-import { resolveDateRange } from './date.service';
-
-export async function getTopEventNames(projectId: string): Promise<string[]> {
- return getCache(`mcp:event-names:${projectId}`, 60 * 10, async () => {
- const rows = await clix(ch)
- .select<IClickhouseEvent>(['name', 'count() as count'])
- .from(TABLE_NAMES.event_names_mv)
- .where('project_id', '=', projectId)
- .groupBy(['name'])
- .orderBy('count', 'DESC')
- .limit(50)
- .execute();
-
- return rows.map((r) => r.name);
- });
-}
-
-export const listEventNamesCore = (projectId: string): Promise<string[]> =>
- getTopEventNames(projectId);
-
-/**
- * Top-level filterable columns on the `events` table. These apply to
- * every event regardless of name and can be passed straight to
- * `getEventFiltersWhereClause` as filter / breakdown `name` values.
- *
- * Kept as a whitelist because the filter builder splices `name` into
- * SQL verbatim — only these are safe to expose through the AI /
- * MCP discovery surface.
- */
-export const EVENT_COLUMNS = [
- 'path',
- 'origin',
- 'referrer',
- 'referrer_name',
- 'referrer_type',
- 'duration',
- 'country',
- 'city',
- 'region',
- 'os',
- 'os_version',
- 'browser',
- 'browser_version',
- 'device',
- 'brand',
- 'model',
- 'sdk_name',
- 'sdk_version',
- 'profile_id',
- 'session_id',
- 'device_id',
- 'revenue',
-] as const;
-
-export type IEventColumn = (typeof EVENT_COLUMNS)[number];
-
-export async function listEventPropertiesCore(input: {
- projectId: string;
- eventName?: string;
-}): Promise<{
- columns: readonly string[];
- properties: Array<{ property_key: string; event_name: string }>;
-}> {
- // GROUP BY rather than DISTINCT: both return the same set of
- // (property_key, name) pairs, but a multi-column DISTINCT cannot be matched
- // against the epv_keys aggregating projection, so it degrades to a full scan
- // of the project's MV slice. `name` is a tie-breaker for the ORDER BY —
- // without it the LIMIT slices an arbitrary subset of the rows sharing a
- // property_key, which is also what made the two spellings return different
- // windows.
- const builder = clix(ch)
- .select<{ property_key: string; event_name: string }>([
- 'property_key',
- 'name as event_name',
- ])
- .from(TABLE_NAMES.event_property_values_mv)
- .where('project_id', '=', input.projectId)
- .groupBy(['property_key', 'name'])
- .orderBy('property_key', 'ASC')
- .orderBy('name', 'ASC')
- .limit(500);
-
- if (input.eventName) {
- builder.where('name', '=', input.eventName);
- }
-
- const rows = await builder.execute();
- return { columns: EVENT_COLUMNS, properties: rows };
-}
-
-export async function getEventPropertyValuesCore(input: {
- projectId: string;
- eventName: string;
- propertyKey: string;
-}): Promise<{ event: string; property: string; values: string[] }> {
- const rows = await clix(ch)
- .select<{ value: string }>(['property_value as value'])
- .from(TABLE_NAMES.event_property_values_mv)
- .where('project_id', '=', input.projectId)
- .where('name', '=', input.eventName)
- .where('property_key', '=', input.propertyKey)
- .orderBy('created_at', 'DESC')
- .limit(200)
- .execute();
-
- return {
- event: input.eventName,
- property: input.propertyKey,
- values: rows.map((r) => r.value),
- };
-}
-
-export interface QueryEventsInput {
- projectId: string;
- startDate?: string;
- endDate?: string;
- eventNames?: string[];
- path?: string;
- country?: string;
- city?: string;
- device?: string;
- browser?: string;
- os?: string;
- referrer?: string;
- referrerName?: string;
- referrerType?: string;
- sessionId?: string;
- profileId?: string;
- profileIds?: string[];
- properties?: Record<string, string>;
- filters?: IChartEventFilter[];
- limit?: number;
-}
-
-export async function queryEventsCore(
- input: QueryEventsInput
-): Promise<IClickhouseEvent[]> {
- const builder = clix(ch)
- .select<IClickhouseEvent>([])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', input.projectId);
-
- if (input.sessionId) {
- builder.where('session_id', '=', input.sessionId);
- }
-
- if (input.profileId) {
- builder.where('profile_id', '=', input.profileId);
- }
-
- if (input.profileIds?.length) {
- builder.where('profile_id', 'IN', input.profileIds);
- }
-
- if (input.eventNames?.length) {
- builder.where('name', 'IN', input.eventNames);
- }
-
- if (input.path) {
- builder.where('path', '=', input.path);
- }
-
- if (input.referrer) {
- builder.where('referrer', '=', input.referrer);
- }
-
- if (input.referrerName) {
- builder.where('referrer_name', '=', input.referrerName);
- }
-
- if (input.referrerType) {
- builder.where('referrer_type', '=', input.referrerType);
- }
-
- if (input.device) {
- builder.where('device', '=', input.device);
- }
-
- if (input.country) {
- builder.where('country', '=', input.country);
- }
-
- if (input.city) {
- builder.where('city', '=', input.city);
- }
-
- if (input.os) {
- builder.where('os', '=', input.os);
- }
-
- if (input.browser) {
- builder.where('browser', '=', input.browser);
- }
-
- if (input.properties) {
- for (const [key, value] of Object.entries(input.properties)) {
- builder.rawWhere(
- `properties[${sqlstring.escape(key)}] = ${sqlstring.escape(value)}`
- );
- }
- }
-
- // Skip the default 30-day date filter when sessionId is set — a
- // session id is unique and narrow enough to query directly. Without
- // this, an older session's events would be silently excluded.
- if (!input.sessionId) {
- const { startDate: start, endDate: end } = resolveDateRange(
- input.startDate,
- input.endDate
- );
- builder.where('created_at', 'BETWEEN', [
- clix.datetime(start),
- clix.datetime(end),
- ]);
- } else if (input.startDate || input.endDate) {
- // If caller still wants to scope by date, honor it.
- const { startDate: start, endDate: end } = resolveDateRange(
- input.startDate,
- input.endDate
- );
- builder.where('created_at', 'BETWEEN', [
- clix.datetime(start),
- clix.datetime(end),
- ]);
- }
-
- if (input.filters?.length) {
- const filterClauses = buildFilterWhere(input.filters, input.projectId, {
- selfTable: 'events',
- profileIdExpr: 'profile_id',
- groupsExpr: 'groups',
- });
- for (const clause of Object.values(filterClauses)) {
- builder.rawWhere(clause);
- }
- }
-
- return builder.limit(input.limit ?? 20).execute();
-}
diff --git a/packages/db/src/services/group.service.ts b/packages/db/src/services/group.service.ts
index baa79b8ff..8251dc235 100644
--- a/packages/db/src/services/group.service.ts
+++ b/packages/db/src/services/group.service.ts
@@ -1,396 +1,26 @@
-import { toDots } from '@openpanel/common';
-import sqlstring from 'sqlstring';
-import {
- ch,
- chQuery,
- formatClickhouseDate,
- TABLE_NAMES,
-} from '../clickhouse/client';
-import type { IServiceProfile } from './profile.service';
-import { getProfiles } from './profile.service';
-
-export type IServiceGroup = {
- id: string;
- projectId: string;
- type: string;
- name: string;
- properties: Record<string, unknown>;
- createdAt: Date;
- updatedAt: Date;
-};
-
-export type IServiceUpsertGroup = {
- id: string;
- projectId: string;
- type: string;
- name: string;
- properties?: Record<string, unknown>;
-};
-
-type IClickhouseGroup = {
- project_id: string;
- id: string;
- type: string;
- name: string;
- properties: Record<string, string>;
- created_at: string;
- version: string;
-};
-
-function transformGroup(row: IClickhouseGroup): IServiceGroup {
- return {
- id: row.id,
- projectId: row.project_id,
- type: row.type,
- name: row.name,
- properties: row.properties,
- createdAt: new Date(row.created_at),
- updatedAt: new Date(Number(row.version)),
- };
-}
-
-async function writeGroupToCh(
- group: {
- id: string;
- projectId: string;
- type: string;
- name: string;
- properties: Record<string, string>;
- createdAt?: Date;
- },
- deleted = 0
-) {
- await ch.insert({
- format: 'JSONEachRow',
- table: TABLE_NAMES.groups,
- values: [
- {
- project_id: group.projectId,
- id: group.id,
- type: group.type,
- name: group.name,
- properties: group.properties,
- created_at: formatClickhouseDate(group.createdAt ?? new Date()),
- version: Date.now(),
- deleted,
- },
- ],
- });
-}
-
-export async function upsertGroup(input: IServiceUpsertGroup) {
- const existing = await getGroupById(input.id, input.projectId);
- await writeGroupToCh({
- id: input.id,
- projectId: input.projectId,
- type: input.type,
- name: input.name,
- properties: toDots({
- ...(existing?.properties ?? {}),
- ...(input.properties ?? {}),
- }),
- createdAt: existing?.createdAt,
- });
-}
-
-export async function getGroupById(
- id: string,
- projectId: string
-): Promise<IServiceGroup | null> {
- const rows = await chQuery<IClickhouseGroup>(`
- SELECT project_id, id, type, name, properties, created_at, version
- FROM ${TABLE_NAMES.groups} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND id = ${sqlstring.escape(id)}
- AND deleted = 0
- `);
- return rows[0] ? transformGroup(rows[0]) : null;
-}
-
-export async function getGroupList({
- projectId,
- cursor,
- take,
- search,
- type,
-}: {
- projectId: string;
- cursor?: number;
- take: number;
- search?: string;
- type?: string;
-}): Promise<IServiceGroup[]> {
- const conditions = [
- `project_id = ${sqlstring.escape(projectId)}`,
- 'deleted = 0',
- ...(type ? [`type = ${sqlstring.escape(type)}`] : []),
- ...(search
- ? [
- `(name ILIKE ${sqlstring.escape(`%${search}%`)} OR id ILIKE ${sqlstring.escape(`%${search}%`)})`,
- ]
- : []),
- ];
-
- const rows = await chQuery<IClickhouseGroup>(`
- SELECT project_id, id, type, name, properties, created_at, version
- FROM ${TABLE_NAMES.groups} FINAL
- WHERE ${conditions.join(' AND ')}
- ORDER BY created_at DESC
- LIMIT ${take}
- OFFSET ${Math.max(0, (cursor ?? 0) * take)}
- `);
- return rows.map(transformGroup);
-}
-
-export async function getGroupListCount({
- projectId,
- type,
- search,
-}: {
- projectId: string;
- type?: string;
- search?: string;
-}): Promise<number> {
- const conditions = [
- `project_id = ${sqlstring.escape(projectId)}`,
- 'deleted = 0',
- ...(type ? [`type = ${sqlstring.escape(type)}`] : []),
- ...(search
- ? [
- `(name ILIKE ${sqlstring.escape(`%${search}%`)} OR id ILIKE ${sqlstring.escape(`%${search}%`)})`,
- ]
- : []),
- ];
-
- const rows = await chQuery<{ count: number }>(`
- SELECT count() as count
- FROM ${TABLE_NAMES.groups} FINAL
- WHERE ${conditions.join(' AND ')}
- `);
- return rows[0]?.count ?? 0;
-}
-
-export async function getGroupTypes(projectId: string): Promise<string[]> {
- const rows = await chQuery<{ type: string }>(`
- SELECT DISTINCT type
- FROM ${TABLE_NAMES.groups} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND deleted = 0
- `);
- return rows.map((r) => r.type);
-}
-
-export async function createGroup(input: IServiceUpsertGroup) {
- await upsertGroup(input);
- return getGroupById(input.id, input.projectId);
-}
-
-export async function updateGroup(
- id: string,
- projectId: string,
- data: { type?: string; name?: string; properties?: Record<string, unknown> }
-) {
- const existing = await getGroupById(id, projectId);
- if (!existing) {
- throw new Error(`Group ${id} not found`);
- }
- const mergedProperties = {
- ...(existing.properties ?? {}),
- ...(data.properties ?? {}),
- };
- const normalizedProperties = toDots(
- mergedProperties as Record<string, unknown>
- );
- const updated = {
- id,
- projectId,
- type: data.type ?? existing.type,
- name: data.name ?? existing.name,
- properties: normalizedProperties,
- createdAt: existing.createdAt,
- };
- await writeGroupToCh(updated);
- return { ...existing, ...updated };
-}
-
-export async function deleteGroup(id: string, projectId: string) {
- const existing = await getGroupById(id, projectId);
- if (!existing) {
- throw new Error(`Group ${id} not found`);
- }
- await writeGroupToCh(
- {
- id,
- projectId,
- type: existing.type,
- name: existing.name,
- properties: existing.properties as Record<string, string>,
- createdAt: existing.createdAt,
- },
- 1
- );
- return existing;
-}
-
-export async function getGroupPropertyKeys(
- projectId: string
-): Promise<string[]> {
- const rows = await chQuery<{ key: string }>(`
- SELECT DISTINCT arrayJoin(mapKeys(properties)) as key
- FROM ${TABLE_NAMES.groups} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND deleted = 0
- `);
- return rows.map((r) => r.key).sort();
-}
-
-export type IServiceGroupStats = {
- groupId: string;
- memberCount: number;
- lastActiveAt: Date | null;
-};
-
-export async function getGroupStats(
- projectId: string,
- groupIds: string[]
-): Promise<Map<string, IServiceGroupStats>> {
- if (groupIds.length === 0) {
- return new Map();
- }
-
- const rows = await chQuery<{
- group_id: string;
- member_count: number;
- last_active_at: string;
- }>(`
- SELECT
- g AS group_id,
- uniqExact(profile_id) AS member_count,
- max(created_at) AS last_active_at
- FROM ${TABLE_NAMES.events}
- ARRAY JOIN groups AS g
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND g IN (${groupIds.map((id) => sqlstring.escape(id)).join(',')})
- AND profile_id != device_id
- GROUP BY g
- `);
-
- return new Map(
- rows.map((r) => [
- r.group_id,
- {
- groupId: r.group_id,
- memberCount: r.member_count,
- lastActiveAt: r.last_active_at ? new Date(r.last_active_at) : null,
- },
- ])
- );
-}
-
-export async function getGroupsByIds(
- projectId: string,
- ids: string[]
-): Promise<IServiceGroup[]> {
- if (ids.length === 0) {
- return [];
- }
-
- const rows = await chQuery<IClickhouseGroup>(`
- SELECT project_id, id, type, name, properties, created_at, version
- FROM ${TABLE_NAMES.groups} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND id IN (${ids.map((id) => sqlstring.escape(id)).join(',')})
- AND deleted = 0
- `);
- return rows.map(transformGroup);
-}
-
-export async function getGroupMemberProfiles({
- projectId,
- groupId,
- cursor,
- take,
- search,
-}: {
- projectId: string;
- groupId: string;
- cursor?: number;
- take: number;
- search?: string;
-}): Promise<{ data: IServiceProfile[]; count: number }> {
- const offset = Math.max(0, (cursor ?? 0) * take);
- const searchCondition = search?.trim()
- ? `AND (email ILIKE ${sqlstring.escape(`%${search.trim()}%`)} OR first_name ILIKE ${sqlstring.escape(`%${search.trim()}%`)} OR last_name ILIKE ${sqlstring.escape(`%${search.trim()}%`)})`
- : '';
-
- const rows = await chQuery<{ id: string; total_count: number }>(`
- SELECT
- id,
- count() OVER () AS total_count
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(groupId)})
- ${searchCondition}
- ORDER BY created_at DESC
- LIMIT ${take}
- OFFSET ${offset}
- `);
-
- const count = rows[0]?.total_count ?? 0;
- const profileIds = rows.map((r) => r.id);
-
- if (profileIds.length === 0) {
- return { data: [], count };
- }
-
- const profiles = await getProfiles(profileIds, projectId);
- const byId = new Map(profiles.map((p) => [p.id, p]));
- const data = profileIds
- .map((id) => byId.get(id))
- .filter(Boolean) as IServiceProfile[];
- return { data, count };
-}
-
-export async function listGroupTypesCore(projectId: string) {
- const types = await getGroupTypes(projectId);
- return { types };
-}
-
-export async function findGroupsCore(input: {
- projectId: string;
- type?: string;
- search?: string;
- limit?: number;
-}) {
- return getGroupList({
- projectId: input.projectId,
- type: input.type,
- search: input.search,
- take: input.limit ?? 20,
- });
-}
-
-export async function getGroupCore(input: {
- projectId: string;
- groupId: string;
- memberLimit?: number;
-}) {
- const [group, members] = await Promise.all([
- getGroupById(input.groupId, input.projectId),
- getGroupMemberProfiles({
- projectId: input.projectId,
- groupId: input.groupId,
- take: input.memberLimit ?? 10,
- }),
- ]);
-
- if (!group) {
- throw new Error(`Group not found: ${input.groupId}`);
- }
-
- return {
- group,
- member_count: members.count,
- members: members.data,
- };
-}
+// The group service lives in @openpanel/core now (M7-002):
+// packages/core/src/modules/group/group.service.ts, with every ClickHouse
+// query rewritten onto the `sql` tag (packages/core/src/modules/group/src/
+// group.sql.ts). Re-exported here for existing `@openpanel/db` importers
+// (packages/trpc's group router, the assistant/mcp tools) — same shape as
+// session.service.ts since M7-001.
+export {
+ createGroup,
+ deleteGroup,
+ findGroupsCore,
+ getGroupById,
+ getGroupCore,
+ getGroupList,
+ getGroupListCount,
+ getGroupMemberProfiles,
+ getGroupPropertyKeys,
+ getGroupStats,
+ getGroupsByIds,
+ getGroupTypes,
+ type IServiceGroup,
+ type IServiceGroupStats,
+ type IServiceUpsertGroup,
+ listGroupTypesCore,
+ updateGroup,
+ upsertGroup,
+} from '@openpanel/core';
diff --git a/packages/db/src/services/profile-metrics-sql.test.ts b/packages/db/src/services/profile-metrics-sql.test.ts
deleted file mode 100644
index 8ae256503..000000000
--- a/packages/db/src/services/profile-metrics-sql.test.ts
+++ /dev/null
@@ -1,82 +0,0 @@
-/**
- * SQL-shape tests for the profile metrics query.
- *
- * Same strategy as chart-sql.test.ts / funnel-sql.test.ts: string assertions
- * always run; `EXPLAIN` validation runs against a locally reachable
- * ClickHouse (`pnpm dock:up`) and skips otherwise.
- */
-import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
-
-import { ch } from '../clickhouse/client';
-import { buildProfileMetricsSql } from './profile.service';
-
-const PROJECT_ID = 'test-sql-validation';
-const PROFILE_ID = 'profile-1';
-
-let chReachable = false;
-
-beforeAll(async () => {
- vi.spyOn(console, 'log').mockImplementation(() => {});
- try {
- await ch.command({ query: 'SELECT 1' });
- chReachable = true;
- } catch {
- chReachable = false;
- }
-});
-
-afterAll(() => {
- vi.restoreAllMocks();
-});
-
-const itCH = (name: string, fn: () => Promise<void>) =>
- it(name, async (ctx) => {
- if (!chReachable) {
- ctx.skip('ClickHouse not reachable at CLICKHOUSE_URL');
- }
- await fn();
- });
-
-describe('buildProfileMetricsSql', () => {
- // Every metric is a plain aggregate over the same
- // `profile_id = X AND project_id = Y` slice, so the query must read the
- // events table exactly once — the per-metric-CTE shape scanned it eight
- // times per profile view.
- it('scans the events table exactly once', () => {
- const sql = buildProfileMetricsSql(PROFILE_ID, PROJECT_ID);
- expect(sql.match(/FROM events\b/g)).toHaveLength(1);
- expect(sql.match(/FROM profiles\b/g)).toHaveLength(1);
- });
-
- it('keeps every metric of the old per-CTE shape', () => {
- const sql = buildProfileMetricsSql(PROFILE_ID, PROJECT_ID);
- for (const metric of [
- 'lastSeen',
- 'firstSeen',
- 'screenViews',
- 'sessions',
- 'durationAvg',
- 'durationP90',
- 'totalEvents',
- 'uniqueDaysActive',
- 'bounceRate',
- 'avgEventsPerSession',
- 'conversionEvents',
- 'avgTimeBetweenSessions',
- 'revenue',
- ]) {
- expect(sql).toContain(`as ${metric}`);
- }
- });
-
- it('escapes the identifiers', () => {
- const sql = buildProfileMetricsSql("p'--", "x'--");
- expect(sql).not.toContain("p'--");
- expect(sql).toContain("'p\\'--'");
- });
-
- itCH('parses and resolves against ClickHouse', async () => {
- const sql = buildProfileMetricsSql(PROFILE_ID, PROJECT_ID);
- await ch.command({ query: `EXPLAIN ${sql}` });
- });
-});
diff --git a/packages/db/src/services/profile.service.ts b/packages/db/src/services/profile.service.ts
index 5eddf7ae1..8c9bcaa67 100644
--- a/packages/db/src/services/profile.service.ts
+++ b/packages/db/src/services/profile.service.ts
@@ -1,577 +1,55 @@
-import { strip, toObject } from '@openpanel/common';
-import { cacheable } from '@openpanel/redis';
-import type { IChartEventFilter } from '@openpanel/validation';
-import { uniq } from 'ramda';
+// The profile service lives in @openpanel/core now (M7-002):
+// packages/core/src/modules/profile/profile.service.ts, with every ClickHouse
+// query rewritten onto the `sql` tag (packages/core/src/modules/profile/src/
+// profile.sql.ts). Re-exported here for existing `@openpanel/db` importers
+// (packages/trpc's profile/chart routers, apps/api's insights controller,
+// the assistant/mcp tools, profile-buffer's IClickhouseProfile type) — same
+// shape as session.service.ts since M7-001.
+export {
+ type FindProfilesInput,
+ findProfilesCore,
+ getProfileById,
+ getProfileList,
+ getProfileListCount,
+ getProfileMetrics,
+ getProfileMetricsCore,
+ getProfilePropertyKeys,
+ getProfilePropertyKeysCached,
+ getProfileSessionsCore,
+ getProfiles,
+ getProfilesCached,
+ getProfileWithEvents,
+ type IClickhouseProfile,
+ type IProfileMetrics,
+ type IServiceProfile,
+ type IServiceUpsertProfile,
+ transformProfile,
+ upsertProfile,
+} from '@openpanel/core';
+
import sqlstring from 'sqlstring';
-import { profileBuffer } from '../buffers';
-import {
- ch,
- chQuery,
- convertClickhouseDateToJs,
- formatClickhouseDate,
- TABLE_NAMES,
- toNullIfDefaultMinDate,
-} from '../clickhouse/client';
-import { clix } from '../clickhouse/query-builder';
-import { createSqlBuilder } from '../sql-builder';
-import type { IClickhouseEvent } from './event.service';
-import { buildFilterWhere } from './filter-where.service';
-import type { IClickhouseSession } from './session.service';
-export interface IProfileMetrics {
- lastSeen: Date | null;
- firstSeen: Date | null;
- screenViews: number;
- sessions: number;
- durationAvg: number;
- durationP90: number;
- totalEvents: number;
- uniqueDaysActive: number;
- bounceRate: number;
- avgEventsPerSession: number;
- conversionEvents: number;
- avgTimeBetweenSessions: number;
- revenue: number;
-}
+const MAX_SEARCH_TOKENS = 5;
+
/**
- * SQL for the profile metrics panel: one point-read of the profile row
- * (first/last seen) plus ONE conditional-aggregate scan of the profile's
- * events.
- *
- * Previously every metric lived in its own CTE, so the same
- * `profile_id = X AND project_id = Y` slice of the events table was scanned
- * eight times per profile view. All of those metrics are plain aggregates
- * over the same rows, so they collapse into a single pass with
- * countIf/avgIf/sumIf — identical values, one scan.
- *
- * Exported for SQL-shape tests.
+ * String-SQL twin of core's `profileSearchCondition`, kept for
+ * cohort.service.ts's `getCohortProfiles`, which still composes V1 text
+ * queries. Goes with that query when it moves onto the `sql` tag.
*/
-export function buildProfileMetricsSql(
- profileId: string,
- projectId: string
-): string {
- const pid = sqlstring.escape(projectId);
- const uid = sqlstring.escape(profileId);
- return `
- WITH profileSeen AS (
- SELECT created_at as firstSeen, last_seen_at as lastSeen
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE id = ${uid} AND project_id = ${pid}
- LIMIT 1
- ),
- eventStats AS (
- SELECT
- countIf(name = 'screen_view') as screenViews,
- countIf(name = 'session_start') as sessions,
- round(avgIf(duration, name = 'session_end' AND duration != 0) / 1000 / 60, 2) as durationAvg,
- round(quantilesExactInclusiveIf(0.9)(duration, name = 'session_end' AND duration != 0)[1] / 1000 / 60, 2) as durationP90,
- count(*) as totalEvents,
- count(DISTINCT toDate(created_at)) as uniqueDaysActive,
- round(avgIf(properties['__bounce'] = '1', name = 'session_end') * 100, 4) as bounceRate,
- countIf(name NOT IN ('screen_view', 'session_start', 'session_end')) as conversionEvents,
- sumIf(revenue, name = 'revenue') as revenue
- FROM ${TABLE_NAMES.events}
- WHERE profile_id = ${uid} AND project_id = ${pid}
- )
- SELECT
- (SELECT lastSeen FROM profileSeen) as lastSeen,
- (SELECT firstSeen FROM profileSeen) as firstSeen,
- screenViews,
- sessions,
- durationAvg,
- durationP90,
- totalEvents,
- uniqueDaysActive,
- bounceRate,
- round(totalEvents / nullIf(sessions, 0), 2) as avgEventsPerSession,
- conversionEvents,
- CASE
- WHEN sessions <= 1 THEN 0
- ELSE round(dateDiff('second', (SELECT firstSeen FROM profileSeen), (SELECT lastSeen FROM profileSeen)) / nullIf(sessions - 1, 0), 1)
- END as avgTimeBetweenSessions,
- revenue
- FROM eventStats
- `;
-}
-
-export function getProfileMetrics(profileId: string, projectId: string) {
- return chQuery<
- Omit<IProfileMetrics, 'lastSeen' | 'firstSeen'> & {
- lastSeen: string;
- firstSeen: string;
- }
- >(buildProfileMetricsSql(profileId, projectId))
- .then((data) => data[0]!)
- .then((data) => {
- return {
- ...data,
- lastSeen: toNullIfDefaultMinDate(data.lastSeen),
- firstSeen: toNullIfDefaultMinDate(data.firstSeen),
- };
- });
-}
-
-export async function getProfileById(id: string, projectId: string) {
- if (id === '' || projectId === '') {
- return null;
- }
-
- const cachedProfile = await profileBuffer.fetchFromCache(id, projectId);
- if (cachedProfile) {
- return transformProfile(cachedProfile);
- }
-
- const [profile] = await chQuery<IClickhouseProfile>(
- `SELECT ${PROFILE_COLUMNS}
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE id = ${sqlstring.escape(String(id))} AND project_id = ${sqlstring.escape(projectId)}
- LIMIT 1`
- );
-
- if (!profile) {
+export function profileSearchSql(
+ search: string | null | undefined
+): string | null {
+ const tokens = (search ?? '')
+ .trim()
+ .split(/\s+/)
+ .filter(Boolean)
+ .slice(0, MAX_SEARCH_TOKENS);
+ if (tokens.length === 0) {
return null;
}
-
- return transformProfile(profile);
-}
-
-interface GetProfileListOptions {
- projectId: string;
- take: number;
- cursor?: number;
- filters?: IChartEventFilter[];
- search?: string;
- isExternal?: boolean;
-}
-
-/**
- * Build a profile search predicate that handles multi-token queries like
- * "John Smith" — splits on whitespace, requires every token to match SOME
- * profile field (id/email/first/last/full name), case-insensitively. Pasting a
- * full profile id matches on `id`. Returns `null` when the search string is
- * empty.
- */
-export function profileSearchSql(search: string | null | undefined): string | null {
- const tokens = (search ?? '').trim().split(/\s+/).filter(Boolean).slice(0, 5);
- if (tokens.length === 0) return null;
const perToken = tokens.map((token) => {
const like = sqlstring.escape(`%${token}%`);
return `(id ILIKE ${like} OR email ILIKE ${like} OR first_name ILIKE ${like} OR last_name ILIKE ${like} OR concat(first_name, ' ', last_name) ILIKE ${like})`;
});
return `(${perToken.join(' AND ')})`;
}
-
-export async function getProfiles(ids: string[], projectId: string) {
- const filteredIds = uniq(ids.filter((id) => id !== ''));
-
- if (filteredIds.length === 0) {
- return [];
- }
-
- const data = await chQuery<IClickhouseProfile>(
- `SELECT ${PROFILE_COLUMNS}
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE
- project_id = ${sqlstring.escape(projectId)} AND
- id IN (${filteredIds.map((id) => sqlstring.escape(id)).join(',')})
- `
- );
-
- return data.map(transformProfile);
-}
-
-export const getProfilesCached = cacheable(getProfiles, 60 * 5);
-
-export async function getProfileList({
- take,
- cursor,
- projectId,
- filters,
- search,
- isExternal,
-}: GetProfileListOptions) {
- const { sb, getSql } = createSqlBuilder();
- sb.from = `${TABLE_NAMES.profiles} FINAL`;
- sb.select.all = '*';
- sb.where.project_id = `project_id = ${sqlstring.escape(projectId)}`;
- sb.limit = take;
- sb.offset = Math.max(0, (cursor ?? 0) * take);
- sb.orderBy.created_at = 'created_at DESC';
- const searchClause = profileSearchSql(search);
- if (searchClause) {
- sb.where.search = searchClause;
- }
- if (isExternal !== undefined) {
- sb.where.external = `is_external = ${isExternal ? 'true' : 'false'}`;
- }
- if (filters?.length) {
- Object.assign(
- sb.where,
- buildFilterWhere(filters, projectId, {
- selfTable: 'profiles',
- profileIdExpr: 'id',
- groupsExpr: 'groups',
- }),
- );
- }
- const data = await chQuery<IClickhouseProfile>(getSql());
- return data.map(transformProfile);
-}
-
-export async function getProfileListCount({
- projectId,
- filters,
- isExternal,
- search,
-}: Omit<GetProfileListOptions, 'cursor' | 'take'>) {
- const { sb, getSql } = createSqlBuilder();
- sb.from = 'profiles';
- sb.select.count = 'count(id) as count';
- sb.where.project_id = `project_id = ${sqlstring.escape(projectId)}`;
- sb.groupBy.project_id = 'project_id';
- const searchClause = profileSearchSql(search);
- if (searchClause) {
- sb.where.search = searchClause;
- }
- if (isExternal !== undefined) {
- sb.where.external = `is_external = ${isExternal ? 'true' : 'false'}`;
- }
- if (filters?.length) {
- Object.assign(
- sb.where,
- buildFilterWhere(filters, projectId, {
- selfTable: 'profiles',
- profileIdExpr: 'id',
- groupsExpr: 'groups',
- }),
- );
- }
- const data = await chQuery<{ count: number }>(getSql());
- return data[0]?.count ?? 0;
-}
-
-export interface IServiceProfile {
- id: string;
- email: string;
- avatar: string;
- firstName: string;
- lastName: string;
- /** First time this profile was seen — preserved across upserts. */
- createdAt: Date;
- /** Most recent activity. ReplacingMergeTree version column. */
- lastSeenAt: Date;
- isExternal: boolean;
- projectId: string;
- groups: string[];
- properties: Record<string, unknown> & {
- region?: string;
- country?: string;
- city?: string;
- os?: string;
- os_version?: string;
- browser?: string;
- browser_version?: string;
- referrer_name?: string;
- referrer_type?: string;
- device?: string;
- brand?: string;
- model?: string;
- referrer?: string;
- };
-}
-
-export interface IClickhouseProfile {
- id: string;
- first_name: string;
- last_name: string;
- email: string;
- avatar: string;
- properties: Record<string, string | undefined>;
- project_id: string;
- is_external: boolean;
- /** First time this profile was seen — preserved across upserts. */
- created_at: string;
- /** Most recent activity. ReplacingMergeTree version column. */
- last_seen_at: string;
- groups: string[];
-}
-
-export interface IServiceUpsertProfile {
- projectId: string;
- id: string | number;
- firstName?: string;
- lastName?: string;
- email?: string;
- avatar?: string;
- properties?: Record<string, unknown>;
- isExternal: boolean;
- groups?: string[];
-}
-
-export function transformProfile({
- created_at,
- last_seen_at,
- first_name,
- last_name,
- ...profile
-}: IClickhouseProfile): IServiceProfile {
- const createdAtJs = convertClickhouseDateToJs(created_at);
- return {
- firstName: first_name,
- lastName: last_name,
- isExternal: profile.is_external,
- properties: toObject(profile.properties),
- createdAt: createdAtJs,
- lastSeenAt: last_seen_at
- ? convertClickhouseDateToJs(last_seen_at)
- : createdAtJs,
- projectId: profile.project_id,
- id: profile.id,
- email: profile.email,
- avatar: profile.avatar,
- groups: profile.groups ?? [],
- };
-}
-
-export function upsertProfile(
- {
- id,
- firstName,
- lastName,
- email,
- avatar,
- properties,
- projectId,
- isExternal,
- groups,
- }: IServiceUpsertProfile,
- isFromEvent = false
-) {
- const now = formatClickhouseDate(new Date());
- const profile: IClickhouseProfile = {
- id: String(id),
- first_name: firstName || '',
- last_name: lastName || '',
- email: email || '',
- avatar: avatar || '',
- properties: strip((properties as Record<string, string | undefined>) || {}),
- project_id: projectId,
- // First-seen value for brand-new profiles. The buffer's mergeProfiles
- // omits `created_at` from incoming, so for existing profiles the original
- // value is carried forward.
- created_at: now,
- // RMT version column — must advance on every write so the latest row wins.
- last_seen_at: now,
- is_external: isExternal,
- groups: groups ?? [],
- };
-
- return profileBuffer.add(profile, isFromEvent);
-}
-
-export const PROFILE_COLUMNS =
- 'id, first_name, last_name, email, avatar, properties, project_id, is_external, created_at, last_seen_at, groups';
-
-export interface FindProfilesInput {
- projectId: string;
- name?: string;
- email?: string;
- country?: string;
- city?: string;
- device?: string;
- browser?: string;
- inactiveDays?: number;
- minSessions?: number;
- performedEvent?: string;
- filters?: IChartEventFilter[];
- sortBy?: 'created_at';
- sortOrder?: 'asc' | 'desc';
- limit?: number;
-}
-
-export function findProfilesCore(
- input: FindProfilesInput
-): Promise<IClickhouseProfile[]> {
- const pid = sqlstring.escape(input.projectId);
- const conditions: string[] = [`project_id = ${pid}`];
-
- if (input.email) {
- conditions.push(`email ILIKE ${sqlstring.escape(`%${input.email}%`)}`);
- }
- if (input.name) {
- const nameClause = profileSearchSql(input.name);
- if (nameClause) conditions.push(nameClause);
- }
- if (input.country) {
- conditions.push(
- `properties['country'] = ${sqlstring.escape(input.country)}`
- );
- }
- if (input.city) {
- conditions.push(`properties['city'] = ${sqlstring.escape(input.city)}`);
- }
- if (input.device) {
- conditions.push(`properties['device'] = ${sqlstring.escape(input.device)}`);
- }
- if (input.browser) {
- conditions.push(
- `properties['browser'] = ${sqlstring.escape(input.browser)}`
- );
- }
-
- if (input.inactiveDays !== undefined) {
- const days = Math.floor(input.inactiveDays);
- conditions.push(`id NOT IN (
- SELECT DISTINCT profile_id FROM ${TABLE_NAMES.events}
- WHERE project_id = ${pid}
- AND profile_id != ''
- AND created_at >= now() - INTERVAL ${days} DAY
- )`);
- }
-
- if (input.minSessions !== undefined) {
- const min = Math.floor(input.minSessions);
- conditions.push(`id IN (
- SELECT profile_id FROM ${TABLE_NAMES.sessions}
- WHERE project_id = ${pid}
- AND sign = 1
- AND profile_id != ''
- GROUP BY profile_id
- HAVING count() >= ${min}
- )`);
- }
-
- if (input.performedEvent) {
- conditions.push(`id IN (
- SELECT DISTINCT profile_id FROM ${TABLE_NAMES.events}
- WHERE project_id = ${pid}
- AND name = ${sqlstring.escape(input.performedEvent)}
- )`);
- }
-
- if (input.filters?.length) {
- const filterClauses = buildFilterWhere(input.filters, input.projectId, {
- selfTable: 'profiles',
- profileIdExpr: 'id',
- groupsExpr: 'groups',
- });
- conditions.push(...Object.values(filterClauses));
- }
-
- const orderDir = input.sortOrder === 'asc' ? 'ASC' : 'DESC';
- const limit = Math.min(input.limit ?? 20, 100);
-
- const sql = `
- SELECT ${PROFILE_COLUMNS}
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE ${conditions.join(' AND ')}
- ORDER BY created_at ${orderDir}
- LIMIT ${limit}
- `;
-
- return chQuery<IClickhouseProfile>(sql);
-}
-
-export async function getProfileWithEvents(
- projectId: string,
- profileId: string,
- eventLimit = 10
-): Promise<{
- profile: IClickhouseProfile | null;
- recent_events: IClickhouseEvent[];
-}> {
- const [profiles, recent_events] = await Promise.all([
- chQuery<IClickhouseProfile>(`
- SELECT ${PROFILE_COLUMNS}
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)} AND id = ${sqlstring.escape(profileId)}
- LIMIT 1
- `),
- clix(ch)
- .select<IClickhouseEvent>([])
- .from(TABLE_NAMES.events)
- .where('project_id', '=', projectId)
- .where('profile_id', '=', profileId)
- .orderBy('created_at', 'DESC')
- .limit(eventLimit)
- .execute(),
- ]);
-
- return { profile: profiles[0] ?? null, recent_events };
-}
-
-export function getProfileSessionsCore(
- projectId: string,
- profileId: string,
- limit = 20
-): Promise<IClickhouseSession[]> {
- return clix(ch)
- .select<IClickhouseSession>([])
- .from(TABLE_NAMES.sessions)
- .where('project_id', '=', projectId)
- .where('profile_id', '=', profileId)
- .where('sign', '=', 1)
- .orderBy('created_at', 'DESC')
- .limit(limit)
- .execute();
-}
-
-export async function getProfileMetricsCore(input: {
- projectId: string;
- profileId: string;
-}) {
- const raw = await getProfileMetrics(input.profileId, input.projectId);
- if (!raw) {
- throw new Error(`Profile not found or has no events: ${input.profileId}`);
- }
- return {
- profileId: input.profileId,
- firstSeen: raw.firstSeen,
- lastSeen: raw.lastSeen,
- sessions: raw.sessions,
- screenViews: raw.screenViews,
- totalEvents: raw.totalEvents,
- conversionEvents: raw.conversionEvents,
- uniqueDaysActive: raw.uniqueDaysActive,
- avgSessionDurationMin: raw.durationAvg,
- p90SessionDurationMin: raw.durationP90,
- avgEventsPerSession: raw.avgEventsPerSession,
- avgTimeBetweenSessionsSec: raw.avgTimeBetweenSessions,
- bounceRate: raw.bounceRate,
- revenue: raw.revenue,
- };
-}
-
-/**
- * Every distinct key present in any external profile's `properties` map.
- *
- * Aggregated across all profiles rather than sampled — a `LIMIT n` sample with
- * no `ORDER BY` returns whichever rows ClickHouse's scheduler happens to
- * produce, so the key set varied between requests and properties set on a small
- * fraction of profiles were usually missing from the picker entirely.
- *
- * `FINAL` isn't needed: older row versions can only contribute keys that
- * genuinely existed at some point.
- */
-export async function getProfilePropertyKeys(
- projectId: string,
-): Promise<string[]> {
- const rows = await clix(ch)
- .select<{ key: string }>(['DISTINCT arrayJoin(mapKeys(properties)) as key'])
- .from(TABLE_NAMES.profiles)
- .where('project_id', '=', projectId)
- .where('is_external', '=', true)
- .execute();
- return rows.map((r) => r.key).sort();
-}
-
-/**
- * Cached by projectId only. The picker's tRPC-level cache keys on the whole
- * input, which includes `event` — so without this the full profile scan would
- * repeat once per event within the same window, even though the profile keys
- * don't depend on the event at all.
- */
-export const getProfilePropertyKeysCached = cacheable(
- getProfilePropertyKeys,
- 60,
-);
diff --git a/packages/trpc/src/routers/event.ts b/packages/trpc/src/routers/event.ts
index 018b8aaf4..5c6b576e1 100644
--- a/packages/trpc/src/routers/event.ts
+++ b/packages/trpc/src/routers/event.ts
@@ -1,33 +1,47 @@
-import { TRPCError } from '@trpc/server';
-import sqlstring from 'sqlstring';
-import { z } from 'zod';
+// Dissolved into @openpanel/core's event module (M7-002): the ClickHouse
+// queries moved to packages/core/src/modules/event/event.service.ts and
+// src/event.sql.ts. This router stays (DELEGATE PATTERN) — it keeps V1's
+// protectedProcedure stack and delegates every handler body to core's event
+// functions, same as session.ts.
+//
+// `bots` was a `publicProcedure` that let anonymous callers in on the mere
+// existence of a ShareOverview row; ADR-011 (§9, P6 row) makes it
+// `protectedProcedure`. The pages* procedures still read `pagesService`,
+// which the overview module owns (its own task).
import {
- type IServiceProfile,
- type IServiceSession,
- TABLE_NAMES,
- chQuery,
- convertClickhouseDateToJs,
- db,
- eventService,
- getChartStartEndDate,
+ getBotEventsPage,
getConversionEventNames,
- getEventList,
- getEventMetasCached,
+ getConversionListPage,
+ getEventById,
+ getEventDetails,
+ getEventListPage,
+ getTopOrigins,
+ updateEventMeta,
+} from '@openpanel/core';
+import {
+ getChartStartEndDate,
getSettingsForProject,
pagesService,
- sessionService,
} from '@openpanel/db';
import {
zChartEventFilter,
zRange,
zTimeInterval,
} from '@openpanel/validation';
+import { TRPCError } from '@trpc/server';
+import { z } from 'zod';
+import { createTRPCRouter, protectedProcedure } from '../trpc';
-import { clone } from 'ramda';
-import { getProjectAccess } from '../access';
-import { TRPCForbiddenError } from '../errors';
-import { createTRPCRouter, protectedProcedure, publicProcedure } from '../trpc';
+const zEventRef = z.object({
+ id: z.string(),
+ projectId: z.string(),
+ createdAt: z.date().optional(),
+});
+
+function eventNotFound() {
+ return new TRPCError({ code: 'NOT_FOUND', message: 'Event not found' });
+}
export const eventRouter = createTRPCRouter({
updateEventMeta: protectedProcedure
@@ -38,83 +52,25 @@ export const eventRouter = createTRPCRouter({
icon: z.string().optional(),
color: z.string().optional(),
conversion: z.boolean().optional(),
- }),
+ })
)
- .mutation(
- async ({ input: { projectId, name, icon, color, conversion } }) => {
- await getEventMetasCached.clear(projectId);
- return db.eventMeta.upsert({
- where: {
- name_projectId: {
- name,
- projectId,
- },
- },
- create: { projectId, name, icon, color, conversion },
- update: { icon, color, conversion },
- });
- },
- ),
-
- byId: protectedProcedure
- .input(
- z.object({
- id: z.string(),
- projectId: z.string(),
- createdAt: z.date().optional(),
- }),
- )
- .query(async ({ input: { id, projectId, createdAt } }) => {
- const res = await eventService.getById({
- projectId,
- id,
- createdAt,
- });
-
- if (!res) {
- throw new TRPCError({
- code: 'NOT_FOUND',
- message: 'Event not found',
- });
- }
-
- return res;
- }),
-
- details: protectedProcedure
- .input(
- z.object({
- id: z.string(),
- projectId: z.string(),
- createdAt: z.date().optional(),
- }),
- )
- .query(async ({ input: { id, projectId, createdAt } }) => {
- const res = await eventService.getById({
- projectId,
- id,
- createdAt,
- });
-
- if (!res) {
- throw new TRPCError({
- code: 'NOT_FOUND',
- message: 'Event not found',
- });
- }
-
- let session: IServiceSession | undefined;
- if (res?.sessionId) {
- session = await sessionService
- .byId(res?.sessionId, projectId)
- .catch(() => undefined);
- }
-
- return {
- event: res,
- session,
- };
- }),
+ .mutation(({ input }) => updateEventMeta(input)),
+
+ byId: protectedProcedure.input(zEventRef).query(async ({ input }) => {
+ const res = await getEventById(input);
+ if (!res) {
+ throw eventNotFound();
+ }
+ return res;
+ }),
+
+ details: protectedProcedure.input(zEventRef).query(async ({ input }) => {
+ const res = await getEventDetails(input);
+ if (!res) {
+ throw eventNotFound();
+ }
+ return res;
+ }),
events: protectedProcedure
.input(
@@ -130,67 +86,14 @@ export const eventRouter = createTRPCRouter({
endDate: z.date().nullish(),
events: z.array(z.string()).nullish(),
columnVisibility: z.record(z.string(), z.boolean()).nullish(),
- }),
+ })
)
- .query(async ({ input: { columnVisibility, ...input } }) => {
- const items = await getEventList({
- projectId: input.projectId,
- filters: input.filters,
- profileId: input.profileId ?? undefined,
- sessionId: input.sessionId ?? undefined,
- groupId: input.groupId ?? undefined,
- cohortId: input.cohortId ?? undefined,
- startDate: input.startDate ?? undefined,
- endDate: input.endDate ?? undefined,
- events: input.events ?? undefined,
- take: 50,
- cursor: input.cursor ? new Date(input.cursor) : undefined,
- select: {
- ...columnVisibility,
- city: columnVisibility?.country ?? true,
- path: columnVisibility?.name ?? true,
- duration: columnVisibility?.name ?? true,
- projectId: false,
- revenue: true,
- },
- });
-
- // Hacky join to get profile for entire session
- // TODO: Replace this with a join on the session table
- const map = new Map<string, IServiceProfile>(); // sessionId -> profileId
- for (const item of items) {
- if (item.sessionId && item.profile?.isExternal === true) {
- map.set(item.sessionId, item.profile);
- }
- }
-
- for (const item of items) {
- const profile = map.get(item.sessionId);
- if (profile && (item.profile?.isExternal === false || !item.profile)) {
- item.profile = clone(profile);
- if (item?.profile?.firstName) {
- item.profile.firstName = `* ${item.profile.firstName}`;
- }
- }
- }
-
- const lastItem = items[items.length - 1];
+ .query(({ input }) => getEventListPage(input)),
- return {
- data: items,
- meta: {
- next:
- items.length > 0 && lastItem
- ? lastItem.createdAt.toISOString()
- : null,
- },
- };
- }),
conversionNames: protectedProcedure
.input(z.object({ projectId: z.string() }))
- .query(async ({ input: { projectId } }) => {
- return getConversionEventNames(projectId);
- }),
+ .query(({ input: { projectId } }) => getConversionEventNames(projectId)),
+
conversions: protectedProcedure
.input(
z.object({
@@ -200,133 +103,19 @@ export const eventRouter = createTRPCRouter({
endDate: z.date().nullish(),
events: z.array(z.string()).nullish(),
columnVisibility: z.record(z.string(), z.boolean()).nullish(),
- }),
+ })
)
- .query(async ({ input: { columnVisibility, ...input } }) => {
- const conversions = await getConversionEventNames(input.projectId);
- const filteredConversions = conversions.filter((event) => {
- if (input.events && input.events.length > 0) {
- return input.events.includes(event.name);
- }
- return true;
- });
-
- if (filteredConversions.length === 0) {
- return {
- data: [],
- meta: {
- next: null,
- },
- };
- }
-
- const items = await getEventList({
- projectId: input.projectId,
- startDate: input.startDate ?? undefined,
- endDate: input.endDate ?? undefined,
- events: input.events ?? undefined,
- take: 50,
- cursor: input.cursor ? new Date(input.cursor) : undefined,
- select: {
- ...columnVisibility,
- city: columnVisibility?.country ?? true,
- path: columnVisibility?.name ?? true,
- duration: columnVisibility?.name ?? true,
- projectId: false,
- revenue: true,
- },
- custom: (sb) => {
- sb.where.name = `name IN (${filteredConversions.map((event) => sqlstring.escape(event.name)).join(',')})`;
- },
- });
-
- // Hacky join to get profile for entire session
- // TODO: Replace this with a join on the session table
- const map = new Map<string, IServiceProfile>(); // sessionId -> profileId
- for (const item of items) {
- if (item.sessionId && item.profile?.isExternal === true) {
- map.set(item.sessionId, item.profile);
- }
- }
-
- for (const item of items) {
- const profile = map.get(item.sessionId);
- if (profile && (item.profile?.isExternal === false || !item.profile)) {
- item.profile = clone(profile);
- if (item?.profile?.firstName) {
- item.profile.firstName = `* ${item.profile.firstName}`;
- }
- }
- }
-
- const lastItem = items[items.length - 1];
+ .query(({ input }) => getConversionListPage(input)),
- return {
- data: items,
- meta: {
- next:
- items.length > 0 && lastItem
- ? lastItem.createdAt.toISOString()
- : null,
- },
- };
- }),
-
- bots: publicProcedure
+ bots: protectedProcedure
.input(
z.object({
projectId: z.string(),
cursor: z.number().optional(),
limit: z.number().default(8),
- }),
+ })
)
- .query(async ({ input: { projectId, cursor, limit }, ctx }) => {
- if (ctx.session.userId) {
- const access = await getProjectAccess({
- projectId,
- userId: ctx.session.userId,
- });
- if (!access) {
- throw new TRPCForbiddenError('You do not have access to this project');
- }
- } else {
- const share = await db.shareOverview.findFirst({
- where: {
- projectId,
- },
- });
-
- if (!share) {
- throw new TRPCForbiddenError('You do not have access to this project');
- }
- }
-
- const [events, counts] = await Promise.all([
- chQuery<{
- id: string;
- project_id: string;
- name: string;
- type: string;
- path: string;
- created_at: string;
- }>(
- `SELECT * FROM ${TABLE_NAMES.events_bots} WHERE project_id = ${sqlstring.escape(projectId)} ORDER BY created_at DESC LIMIT ${limit} OFFSET ${(cursor ?? 0) * limit}`,
- ),
- chQuery<{
- count: number;
- }>(
- `SELECT count(*) as count FROM ${TABLE_NAMES.events_bots} WHERE project_id = ${sqlstring.escape(projectId)}`,
- ),
- ]);
-
- return {
- data: events.map((item) => ({
- ...item,
- createdAt: convertClickhouseDateToJs(item.created_at),
- })),
- count: counts[0]?.count ?? 0,
- };
- }),
+ .query(({ input }) => getBotEventsPage(input)),
pages: protectedProcedure
.input(
@@ -337,7 +126,7 @@ export const eventRouter = createTRPCRouter({
search: z.string().optional(),
range: zRange,
interval: zTimeInterval,
- }),
+ })
)
.query(async ({ input }) => {
const { timezone } = await getSettingsForProject(input.projectId);
@@ -358,7 +147,7 @@ export const eventRouter = createTRPCRouter({
projectId: z.string(),
range: zRange,
interval: zTimeInterval,
- }),
+ })
)
.query(async ({ input }) => {
const { timezone } = await getSettingsForProject(input.projectId);
@@ -378,7 +167,7 @@ export const eventRouter = createTRPCRouter({
projectId: z.string(),
range: zRange,
interval: zTimeInterval,
- }),
+ })
)
.query(async ({ input }) => {
const { timezone } = await getSettingsForProject(input.projectId);
@@ -390,8 +179,7 @@ export const eventRouter = createTRPCRouter({
const prevEnd = new Date(startMs - 1);
const prevStart = new Date(prevEnd.getTime() - duration);
- const fmt = (d: Date) =>
- d.toISOString().slice(0, 19).replace('T', ' ');
+ const fmt = (d: Date) => d.toISOString().slice(0, 19).replace('T', ' ');
return pagesService.getTopPages({
projectId: input.projectId,
@@ -409,7 +197,7 @@ export const eventRouter = createTRPCRouter({
interval: zTimeInterval,
origin: z.string(),
path: z.string(),
- }),
+ })
)
.query(async ({ input }) => {
const { timezone } = await getSettingsForProject(input.projectId);
@@ -426,18 +214,6 @@ export const eventRouter = createTRPCRouter({
}),
origin: protectedProcedure
- .input(
- z.object({
- projectId: z.string(),
- }),
- )
- .query(async ({ input }) => {
- const res = await chQuery<{ origin: string }>(
- `SELECT DISTINCT origin, count(id) as count FROM ${TABLE_NAMES.events} WHERE project_id = ${sqlstring.escape(
- input.projectId,
- )} AND origin IS NOT NULL AND origin != '' AND toDate(created_at) > now() - INTERVAL 30 DAY GROUP BY origin ORDER BY count DESC LIMIT 3`,
- );
-
- return res.filter((item) => item.origin && !item.origin.includes('localhost:'));
- }),
+ .input(z.object({ projectId: z.string() }))
+ .query(({ input: { projectId } }) => getTopOrigins(projectId)),
});
diff --git a/packages/trpc/src/routers/group.ts b/packages/trpc/src/routers/group.ts
index 0711c941b..c971cda25 100644
--- a/packages/trpc/src/routers/group.ts
+++ b/packages/trpc/src/routers/group.ts
@@ -1,24 +1,31 @@
+// Dissolved into @openpanel/core's group module (M7-002): the ClickHouse
+// queries moved to packages/core/src/modules/group/group.service.ts and
+// src/group.sql.ts. This router stays (DELEGATE PATTERN) — it keeps V1's
+// protectedProcedure stack and delegates every handler body to core's group
+// functions, same as session.ts.
+
import {
- chQuery,
createGroup,
deleteGroup,
+ getGroupActivity,
getGroupById,
- getGroupList,
- getGroupListCount,
- getGroupMemberProfiles,
+ getGroupListPage,
+ getGroupMemberGrowth,
+ getGroupMemberProfilesPage,
+ getGroupMetrics,
+ getGroupMostEvents,
+ getGroupPopularRoutes,
getGroupPropertyKeys,
- getGroupStats,
getGroupsByIds,
getGroupTypes,
- TABLE_NAMES,
- toNullIfDefaultMinDate,
updateGroup,
-} from '@openpanel/db';
+} from '@openpanel/core';
import { zCreateGroup, zUpdateGroup } from '@openpanel/validation';
-import sqlstring from 'sqlstring';
import { z } from 'zod';
import { createTRPCRouter, protectedProcedure } from '../trpc';
+const zGroupRef = z.object({ id: z.string(), projectId: z.string() });
+
export const groupRouter = createTRPCRouter({
list: protectedProcedure
.input(
@@ -30,115 +37,43 @@ export const groupRouter = createTRPCRouter({
type: z.string().optional(),
})
)
- .query(async ({ input }) => {
- const [data, count] = await Promise.all([
- getGroupList(input),
- getGroupListCount(input),
- ]);
- const stats = await getGroupStats(
- input.projectId,
- data.map((g) => g.id)
- );
- return {
- data: data.map((g) => ({
- ...g,
- memberCount: stats.get(g.id)?.memberCount ?? 0,
- lastActiveAt: stats.get(g.id)?.lastActiveAt ?? null,
- })),
- meta: { count, take: input.take },
- };
- }),
+ .query(({ input }) => getGroupListPage(input)),
byId: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .query(({ input: { id, projectId } }) => {
- return getGroupById(id, projectId);
- }),
+ .input(zGroupRef)
+ .query(({ input: { id, projectId } }) => getGroupById(id, projectId)),
create: protectedProcedure
.input(zCreateGroup)
- .mutation(({ input }) => {
- return createGroup(input);
- }),
+ .mutation(({ input }) => createGroup(input)),
update: protectedProcedure
.input(zUpdateGroup)
- .mutation(({ input: { id, projectId, ...data } }) => {
- return updateGroup(id, projectId, data);
- }),
+ .mutation(({ input: { id, projectId, ...data } }) =>
+ updateGroup(id, projectId, data)
+ ),
delete: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .mutation(({ input: { id, projectId } }) => {
- return deleteGroup(id, projectId);
- }),
+ .input(zGroupRef)
+ .mutation(({ input: { id, projectId } }) => deleteGroup(id, projectId)),
types: protectedProcedure
.input(z.object({ projectId: z.string() }))
- .query(({ input: { projectId } }) => {
- return getGroupTypes(projectId);
- }),
+ .query(({ input: { projectId } }) => getGroupTypes(projectId)),
metrics: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .query(async ({ input: { id, projectId } }) => {
- const [eventData, profileData] = await Promise.all([
- chQuery<{ totalEvents: number; firstSeen: string; lastSeen: string }>(`
- SELECT
- count() AS totalEvents,
- min(created_at) AS firstSeen,
- max(created_at) AS lastSeen
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(id)})
- `),
- chQuery<{ uniqueProfiles: number }>(`
- SELECT count() AS uniqueProfiles
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(id)})
- `),
- ]);
-
- return {
- totalEvents: eventData[0]?.totalEvents ?? 0,
- uniqueProfiles: profileData[0]?.uniqueProfiles ?? 0,
- firstSeen: toNullIfDefaultMinDate(eventData[0]?.firstSeen),
- lastSeen: toNullIfDefaultMinDate(eventData[0]?.lastSeen),
- };
- }),
+ .input(zGroupRef)
+ .query(({ input: { id, projectId } }) => getGroupMetrics(id, projectId)),
activity: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .query(({ input: { id, projectId } }) => {
- return chQuery<{ count: number; date: string }>(`
- SELECT count() AS count, toStartOfDay(created_at) AS date
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(id)})
- GROUP BY date
- ORDER BY date DESC
- `);
- }),
+ .input(zGroupRef)
+ .query(({ input: { id, projectId } }) => getGroupActivity(id, projectId)),
memberGrowth: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .query(({ input: { id, projectId } }) => {
- return chQuery<{ date: string; count: number }>(`
- SELECT
- toDate(toStartOfDay(created_at)) AS date,
- count() AS count
- FROM ${TABLE_NAMES.profiles} FINAL
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(id)})
- AND created_at >= now() - INTERVAL 30 DAY
- GROUP BY date
- ORDER BY date ASC WITH FILL
- FROM toDate(now() - INTERVAL 29 DAY)
- TO toDate(now() + INTERVAL 1 DAY)
- STEP 1
- `);
- }),
+ .input(zGroupRef)
+ .query(({ input: { id, projectId } }) =>
+ getGroupMemberGrowth(id, projectId)
+ ),
listProfiles: protectedProcedure
.input(
@@ -150,59 +85,23 @@ export const groupRouter = createTRPCRouter({
search: z.string().optional(),
})
)
- .query(async ({ input }) => {
- const { data, count } = await getGroupMemberProfiles({
- projectId: input.projectId,
- groupId: input.groupId,
- cursor: input.cursor,
- take: input.take,
- search: input.search,
- });
- return {
- data,
- meta: { count, pageCount: input.take },
- };
- }),
+ .query(({ input }) => getGroupMemberProfilesPage(input)),
mostEvents: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .query(({ input: { id, projectId } }) => {
- return chQuery<{ count: number; name: string }>(`
- SELECT count() as count, name
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(id)})
- AND name NOT IN ('screen_view', 'session_start', 'session_end')
- GROUP BY name
- ORDER BY count DESC
- LIMIT 10
- `);
- }),
+ .input(zGroupRef)
+ .query(({ input: { id, projectId } }) => getGroupMostEvents(id, projectId)),
popularRoutes: protectedProcedure
- .input(z.object({ id: z.string(), projectId: z.string() }))
- .query(({ input: { id, projectId } }) => {
- return chQuery<{ count: number; path: string }>(`
- SELECT count() as count, path
- FROM ${TABLE_NAMES.events}
- WHERE project_id = ${sqlstring.escape(projectId)}
- AND has(groups, ${sqlstring.escape(id)})
- AND name = 'screen_view'
- GROUP BY path
- ORDER BY count DESC
- LIMIT 10
- `);
- }),
+ .input(zGroupRef)
+ .query(({ input: { id, projectId } }) =>
+ getGroupPopularRoutes(id, projectId)
+ ),
properties: protectedProcedure
.input(z.object({ projectId: z.string() }))
- .query(({ input: { projectId } }) => {
- return getGroupPropertyKeys(projectId);
- }),
+ .query(({ input: { projectId } }) => getGroupPropertyKeys(projectId)),
listByIds: protectedProcedure
.input(z.object({ projectId: z.string(), ids: z.array(z.string()) }))
- .query(({ input: { projectId, ids } }) => {
- return getGroupsByIds(projectId, ids);
- }),
+ .query(({ input: { projectId, ids } }) => getGroupsByIds(projectId, ids)),
});
diff --git a/packages/trpc/src/routers/profile.ts b/packages/trpc/src/routers/profile.ts
index 3c1441b91..fdb6fb3ff 100644
--- a/packages/trpc/src/routers/profile.ts
+++ b/packages/trpc/src/routers/profile.ts
@@ -1,78 +1,60 @@
-import { flatten, map, pipe, prop, sort, uniq } from 'ramda';
-import sqlstring from 'sqlstring';
-import { z } from 'zod';
+// Dissolved into @openpanel/core's profile module (M7-002): the ClickHouse
+// queries moved to packages/core/src/modules/profile/profile.service.ts and
+// src/profile.sql.ts. This router stays (DELEGATE PATTERN) — it keeps V1's
+// protectedProcedure stack and delegates every handler body to core's
+// profile functions, same as session.ts.
import {
- TABLE_NAMES,
- chQuery,
- createSqlBuilder,
+ getPowerUsers,
+ getProfileActivity,
getProfileById,
- getProfileList,
- getProfileListCount,
+ getProfileListPage,
getProfileMetrics,
- getProfiles,
-} from '@openpanel/db';
+ getProfileMostEvents,
+ getProfilePopularRoutes,
+ getProfilePropertyNames,
+ getProfileValues,
+} from '@openpanel/core';
import { zChartEventFilter } from '@openpanel/validation';
-
+import { z } from 'zod';
import { createTRPCRouter, protectedProcedure } from '../trpc';
+const zProfileRef = z.object({ profileId: z.string(), projectId: z.string() });
+
export const profileRouter = createTRPCRouter({
byId: protectedProcedure
- .input(z.object({ profileId: z.string(), projectId: z.string() }))
- .query(async ({ input: { profileId, projectId } }) => {
- return getProfileById(profileId, projectId);
- }),
+ .input(zProfileRef)
+ .query(({ input: { profileId, projectId } }) =>
+ getProfileById(profileId, projectId)
+ ),
metrics: protectedProcedure
- .input(z.object({ profileId: z.string(), projectId: z.string() }))
- .query(async ({ input: { profileId, projectId } }) => {
- return getProfileMetrics(profileId, projectId);
- }),
+ .input(zProfileRef)
+ .query(({ input: { profileId, projectId } }) =>
+ getProfileMetrics(profileId, projectId)
+ ),
activity: protectedProcedure
- .input(z.object({ profileId: z.string(), projectId: z.string() }))
- .query(async ({ input: { profileId, projectId } }) => {
- return chQuery<{ count: number; date: string }>(
- `SELECT count(*) as count, toStartOfDay(created_at) as date FROM ${TABLE_NAMES.events} WHERE project_id = ${sqlstring.escape(projectId)} and profile_id = ${sqlstring.escape(profileId)} GROUP BY date ORDER BY date DESC`,
- );
- }),
+ .input(zProfileRef)
+ .query(({ input: { profileId, projectId } }) =>
+ getProfileActivity(profileId, projectId)
+ ),
mostEvents: protectedProcedure
- .input(z.object({ profileId: z.string(), projectId: z.string() }))
- .query(async ({ input: { profileId, projectId } }) => {
- return chQuery<{ count: number; name: string }>(
- `SELECT count(*) as count, name FROM ${TABLE_NAMES.events} WHERE name NOT IN ('screen_view', 'session_start', 'session_end') AND project_id = ${sqlstring.escape(projectId)} and profile_id = ${sqlstring.escape(profileId)} GROUP BY name ORDER BY count DESC`,
- );
- }),
+ .input(zProfileRef)
+ .query(({ input: { profileId, projectId } }) =>
+ getProfileMostEvents(profileId, projectId)
+ ),
popularRoutes: protectedProcedure
- .input(z.object({ profileId: z.string(), projectId: z.string() }))
- .query(async ({ input: { profileId, projectId } }) => {
- return chQuery<{ count: number; path: string }>(
- `SELECT count(*) as count, path FROM ${TABLE_NAMES.events} WHERE name = 'screen_view' AND project_id = ${sqlstring.escape(projectId)} and profile_id = ${sqlstring.escape(profileId)} GROUP BY path ORDER BY count DESC LIMIT 10`,
- );
- }),
+ .input(zProfileRef)
+ .query(({ input: { profileId, projectId } }) =>
+ getProfilePopularRoutes(profileId, projectId)
+ ),
properties: protectedProcedure
.input(z.object({ projectId: z.string() }))
- .query(async ({ input: { projectId } }) => {
- const events = await chQuery<{ keys: string[] }>(
- `SELECT distinct mapKeys(properties) as keys from ${TABLE_NAMES.profiles} where project_id = ${sqlstring.escape(projectId)};`,
- );
-
- const properties = events
- .flatMap((event) => event.keys)
- .map((item) => item.replace(/\.([0-9]+)\./g, '.*.'))
- .map((item) => item.replace(/\.([0-9]+)/g, '[*]'))
- .map((item) => `properties.${item}`);
-
- properties.push('id', 'first_name', 'last_name', 'email');
-
- return pipe(
- sort<string>((a, b) => a.length - b.length),
- uniq,
- )(properties);
- }),
+ .query(({ input: { projectId } }) => getProfilePropertyNames(projectId)),
list: protectedProcedure
.input(
@@ -83,21 +65,9 @@ export const profileRouter = createTRPCRouter({
search: z.string().optional(),
isExternal: z.boolean().optional(),
filters: z.array(zChartEventFilter).default([]),
- }),
+ })
)
- .query(async ({ input }) => {
- const [data, count] = await Promise.all([
- getProfileList(input),
- getProfileListCount(input),
- ]);
- return {
- data,
- meta: {
- count,
- pageCount: input.take,
- },
- };
- }),
+ .query(({ input }) => getProfileListPage(input)),
powerUsers: protectedProcedure
.input(
@@ -105,74 +75,11 @@ export const profileRouter = createTRPCRouter({
projectId: z.string(),
cursor: z.number().optional(),
take: z.number().default(50),
- }),
+ })
)
- .query(async ({ input: { projectId, cursor, take } }) => {
- const res = await chQuery<{ profile_id: string; count: number }>(
- `
- SELECT profile_id, count(*) as count
- FROM ${TABLE_NAMES.events}
- WHERE
- profile_id != ''
- AND project_id = ${sqlstring.escape(projectId)}
- GROUP BY profile_id
- ORDER BY count() DESC
- LIMIT ${take} ${cursor ? `OFFSET ${cursor * take}` : ''}`,
- );
- const profiles = await getProfiles(
- res.map((r) => r.profile_id),
- projectId,
- );
-
- const data = res
- .map((item) => {
- return {
- count: item.count,
- ...(profiles.find((p) => p.id === item.profile_id)! ?? {}),
- };
- })
- // Make sure we return actual profiles
- .filter((item) => item.id);
-
- return {
- data,
- meta: {
- count: data.length,
- pageCount: take,
- },
- };
- }),
+ .query(({ input }) => getPowerUsers(input)),
values: protectedProcedure
- .input(
- z.object({
- property: z.string(),
- projectId: z.string(),
- }),
- )
- .query(async ({ input: { property, projectId } }) => {
- const { sb, getSql } = createSqlBuilder();
- sb.from = TABLE_NAMES.profiles;
- sb.where.project_id = `project_id = ${sqlstring.escape(projectId)}`;
- if (property.startsWith('properties.')) {
- sb.select.values = `distinct arrayMap(x -> trim(x), mapValues(mapExtractKeyLike(properties, ${sqlstring.escape(
- property.replace(/^properties\./, '').replace('.*.', '.%.'),
- )}))) as values`;
- } else {
- sb.select.values = `${property} as values`;
- }
-
- const profiles = await chQuery<{ values: string[] }>(getSql());
-
- const values = pipe(
- (data: typeof profiles) => map(prop('values'), data),
- flatten,
- uniq,
- sort((a, b) => a.length - b.length),
- )(profiles);
-
- return {
- values,
- };
- }),
+ .input(z.object({ property: z.string(), projectId: z.string() }))
+ .query(({ input }) => getProfileValues(input)),
});
diff --git a/packages/validation/src/index.ts b/packages/validation/src/index.ts
index 3c1554d0a..32edaed71 100644
--- a/packages/validation/src/index.ts
+++ b/packages/validation/src/index.ts
@@ -436,6 +436,11 @@ export type IProjectUpdate = z.infer<typeof zProjectUpdate>;
// importers (packages/trpc's auth router, apps/start's sign-in/sign-up
// forms) — same shape as ./cohort.validation.ts since M5-003.
export * from '@openpanel/core/modules/auth/auth.constants';
+// Moved into @openpanel/core's group module (M7-002, ADR-008's module map:
+// group owns "C"). Re-exported here for existing @openpanel/validation
+// importers (packages/trpc's group router, apps/start's add-group /
+// edit-group modals) — same shape as the subscription re-export above.
+export * from '@openpanel/core/modules/group/group.constants';
// Moved into @openpanel/core's subscription module (M6-006, ADR-008's module
// map: subscription owns "C"). Re-exported here for existing
// @openpanel/validation importers (packages/trpc's subscription router,
@@ -443,32 +448,6 @@ export * from '@openpanel/core/modules/auth/auth.constants';
// re-export since M6-003.
export * from '@openpanel/core/modules/subscription/subscription.constants';
-export const zGroupId = z
- .string()
- .min(1)
- .regex(
- /^[a-z0-9_-]+$/,
- 'ID must only contain lowercase letters, digits, hyphens, or underscores'
- );
-
-export const zCreateGroup = z.object({
- id: zGroupId,
- projectId: z.string(),
- type: z.string().min(1),
- name: z.string().min(1),
- properties: z.record(z.string(), z.string()).default({}),
-});
-export type ICreateGroup = z.infer<typeof zCreateGroup>;
-
-export const zUpdateGroup = z.object({
- id: z.string().min(1),
- projectId: z.string(),
- type: z.string().min(1).optional(),
- name: z.string().min(1).optional(),
- properties: z.record(z.string(), z.string()).optional(),
-});
-export type IUpdateGroup = z.infer<typeof zUpdateGroup>;
-
export const zEditOrganization = z.object({
id: z.string().min(2),
name: z.string().min(2),