OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
// `overviewProcedure` is `publicProcedure` plus one middleware that resolves
// share-or-membership off the raw `projectId`/`shareId`, BEFORE the input
// parser.
import { getChartPrevStartEndDate } from '@openpanel/shared';
import { format } from 'date-fns';
import { z } from 'zod';
import {
createTRPCRouter,
protectedProcedure,
publicProcedure,
type TrpcContext,
} from '../../rpc/base';
import { TRPCForbiddenError } from '../../rpc/errors';
import type { ServiceDeps } from '../../services';
import { getConversionEventNames } from '../event/event.service';
import { getReferrerSpikes } from '../insight/insight.service';
import {
getOrganizationSubscriptionChartEndDate,
getSettingsForProject,
} from '../organization/organization.service';
import { type IChartRange, zRange } from '../report/report.constants';
import { getChartStartEndDate } from '../report/src/chart-dates';
import {
zGetMapDataInput,
zGetMetricsInput,
zGetTopEventsInput,
zGetTopGenericInput,
zGetTopGenericSeriesInput,
zGetTopLinkOutInput,
zGetTopPagesInput,
zGetUserJourneyInput,
} from './overview.service';
/**
* Share-aware access: with `shareId`, a public (optionally password-unlocked)
* overview share is enough; without it, the caller must be a project member.
* A password-protected share without the unlock cookie comes back as
* `{ isValid: false }` rather than throwing, so the result must be checked —
* ignoring it leaves the data open to anyone holding the link.
*/
async function resolveOverviewAccess(
ctx: TrpcContext,
input: { projectId: string; shareId?: string }
): Promise<void> {
if (input.shareId) {
const shareValidation =
await ctx.services.share.validateOverviewShareAccess(
input.shareId,
input.projectId,
{
cookies: ctx.cookies,
session: ctx.session.userId
? { userId: ctx.session.userId }
: undefined,
}
);
if (!shareValidation.isValid) {
throw new TRPCForbiddenError('You do not have access to this share');
}
return;
}
await ctx.services.auth.requireProjectAccess({
userId: ctx.services.auth.requireLogin(ctx.session.userId),
projectId: input.projectId,
level: 'read',
});
}
const overviewProcedure = publicProcedure.use(
async ({ ctx, next, getRawInput }) => {
const rawInput = (await getRawInput()) as {
projectId: string;
shareId?: string;
};
await resolveOverviewAccess(ctx, rawInput);
return next();
}
);
interface DateRange {
startDate: string;
endDate: string;
}
/** Ends a range at the organization's subscription cutoff, if it has one. */
async function clampToSubscriptionEnd(
ctx: ServiceDeps,
projectId: string,
range: DateRange
): Promise<DateRange> {
const endDate = await getOrganizationSubscriptionChartEndDate(
ctx,
projectId,
range.endDate
);
if (!endDate) {
return range;
}
const startsAfterCutoff = new Date(range.startDate) > new Date(endDate);
return { startDate: startsAfterCutoff ? endDate : range.startDate, endDate };
}
function getCurrentAndPrevious<
T extends {
startDate?: string | null;
endDate?: string | null;
range: IChartRange;
projectId: string;
},
>(input: T, fetchPrevious: boolean, timezone: string, ctx: ServiceDeps) {
const current = getChartStartEndDate(input, timezone);
const previous = getChartPrevStartEndDate(current);
return async <R>(
fn: (input: T & DateRange) => Promise<R>
): Promise<{
current: R;
previous: R | null;
}> => {
// Both ranges are clamped: after an expired trial the previous period can
// still end past the cutoff.
const [currentRange, previousRange] = await Promise.all([
clampToSubscriptionEnd(ctx, input.projectId, current),
fetchPrevious
? clampToSubscriptionEnd(ctx, input.projectId, previous)
: null,
]);
const res = await Promise.all([
fn({ ...input, ...currentRange }),
previousRange ? fn({ ...input, ...previousRange }) : null,
]);
return {
current: res[0],
previous: res[1],
};
};
}
/** What the command bar tells the model about the current view. */
const zFilterCommandPageContext = z.object({
filters: z
.object({
range: z.string().optional(),
startDate: z.string().optional(),
endDate: z.string().optional(),
interval: z.string().optional(),
eventNames: z.array(z.string()).optional(),
eventFilters: z.array(z.record(z.string(), z.unknown())).optional(),
})
.optional(),
});
export const overviewRouter = createTRPCRouter({
liveVisitors: overviewProcedure
.input(z.object({ projectId: z.string(), shareId: z.string().optional() }))
.query(async ({ input, ctx }) => {
return ctx.services.realtime.getActiveVisitorCount(input.projectId);
}),
liveData: overviewProcedure
.input(z.object({ projectId: z.string(), shareId: z.string().optional() }))
.query(async ({ input, ctx }) => {
return ctx.services.overview.getLiveData(input.projectId);
}),
stats: overviewProcedure
.input(
zGetMetricsInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current, previous } = await getCurrentAndPrevious(
{ ...input, timezone },
true,
timezone,
ctx
)(ctx.services.overview.getMetrics);
return {
metrics: {
...current.metrics,
prev_bounce_rate: previous?.metrics.bounce_rate || null,
prev_unique_visitors: previous?.metrics.unique_visitors || null,
prev_total_screen_views: previous?.metrics.total_screen_views || null,
prev_avg_session_duration:
previous?.metrics.avg_session_duration || null,
prev_views_per_session: previous?.metrics.views_per_session || null,
prev_total_sessions: previous?.metrics.total_sessions || null,
prev_total_revenue: previous?.metrics.total_revenue || null,
},
series: current.series.map((item, index) => {
const prev = previous?.series[index];
return {
...item,
date: format(item.date, 'yyyy-MM-dd HH:mm:ss'),
prev_bounce_rate: prev?.bounce_rate,
prev_unique_visitors: prev?.unique_visitors,
prev_total_screen_views: prev?.total_screen_views,
prev_avg_session_duration: prev?.avg_session_duration,
prev_views_per_session: prev?.views_per_session,
prev_total_sessions: prev?.total_sessions,
prev_total_revenue: prev?.total_revenue,
};
}),
};
}),
getReferrerSpikes: overviewProcedure
.input(
zGetMetricsInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { startDate, endDate } = getChartStartEndDate(input, timezone);
const clusters = await getReferrerSpikes(ctx, {
projectId: input.projectId,
filters: input.filters,
interval: input.interval,
startDate,
endDate,
timezone,
});
// Reformat every spike date (and the cluster's anchor) to match
// overview.stats' series date format, so markers x-align with the
// chart's data points (xScale matches by Date identity).
const fmt = (iso: string) => format(new Date(iso), 'yyyy-MM-dd HH:mm:ss');
return clusters.map((cluster) => ({
anchorDate: fmt(cluster.anchorDate),
spikes: cluster.spikes.map((spike) => ({
...spike,
date: fmt(spike.date),
})),
}));
}),
topPages: overviewProcedure
.input(
zGetTopPagesInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
mode: z.enum(['page', 'entry', 'exit', 'bot']),
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input },
false,
timezone,
ctx
)(async (input) => {
if (input.mode === 'page') {
return ctx.services.overview.getTopPages({ ...input, timezone });
}
if (input.mode === 'bot') {
return Promise.resolve([]);
}
return ctx.services.overview.getTopEntryExit({
...input,
mode: input.mode,
timezone,
});
});
return current;
}),
topGeneric: overviewProcedure
.input(
zGetTopGenericInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input, timezone },
false,
timezone,
ctx
)(ctx.services.overview.getTopGeneric);
return current;
}),
topGenericSeries: overviewProcedure
.input(
zGetTopGenericSeriesInput
.omit({ startDate: true, endDate: true })
.extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input, timezone },
false,
timezone,
ctx
)(ctx.services.overview.getTopGenericSeries);
return current;
}),
userJourney: overviewProcedure
.input(
zGetUserJourneyInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
steps: z.number().min(2).max(10).default(5).optional(),
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input, timezone },
false,
timezone,
ctx
)(async (input) => {
return ctx.services.overview.getUserJourney({
...input,
steps: input.steps ?? 5,
timezone,
});
});
return current;
}),
topEvents: overviewProcedure
.input(
zGetTopEventsInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input, timezone },
false,
timezone,
ctx
)(ctx.services.overview.getTopEvents);
return current;
}),
topConversions: overviewProcedure
.input(
z.object({
projectId: z.string(),
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
return getConversionEventNames(ctx, input.projectId);
}),
topLinkOut: overviewProcedure
.input(
zGetTopLinkOutInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input, timezone },
false,
timezone,
ctx
)(ctx.services.overview.getTopLinkOut);
return current;
}),
// One-shot AI command bar — converts natural-language requests
// ("show 7 aug to 11 aug", "from google", "mobile only for august
// last year") into structured filter changes the dashboard can apply
// through the same handlers the chat panel uses.
runFilterCommand: protectedProcedure
// Computes filter changes for the caller's own UI; changes no project state.
.meta({ readOnlyMutation: true })
.input(
z.object({
projectId: z.string(),
query: z.string().min(1).max(500),
pageContext: zFilterCommandPageContext.optional(),
})
)
.mutation(async ({ ctx, input }) => {
await ctx.services.auth.requireProjectAccess({
userId: ctx.session.userId,
projectId: input.projectId,
level: 'read',
});
const { timezone } = await getSettingsForProject(ctx, input.projectId);
return ctx.services.assistant.runFilterCommand({
query: input.query,
projectId: input.projectId,
pageContext: input.pageContext,
timezone: timezone || 'UTC',
userId: ctx.session.userId,
});
}),
map: overviewProcedure
.input(
zGetMapDataInput.omit({ startDate: true, endDate: true }).extend({
startDate: z.string().nullish(),
endDate: z.string().nullish(),
range: zRange,
shareId: z.string().optional(),
})
)
.query(async ({ input, ctx }) => {
const { timezone } = await getSettingsForProject(ctx, input.projectId);
const { current } = await getCurrentAndPrevious(
{ ...input, timezone },
false,
timezone,
ctx
)(ctx.services.overview.getMapData);
return current;
}),
});