Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat(api/monitoring): capture monitoring interest into clickhouse (ENG-4874) (#3514)

Gergő Móricz5fbdc0a36b4b
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index b5e042f68..d58732f99 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -36,6 +36,7 @@ const configSchema = z.object({
FIRECRAWL_APP_PORT: z.string().default("3002"),
FIRECRAWL_APP_SCHEME: z.string().default("http"),
LOGGING_LEVEL: z.string().optional(),
+ FIRECRAWL_DASHBOARD_URL: z.url().default("https://www.firecrawl.dev"),
SUPPORT_AGENT_URL: z.string().url().optional(),
SUPPORT_AGENT_VERCEL_BYPASS_SECRET: z.string().optional(),
diff --git a/apps/api/src/controllers/v2/monitor.ts b/apps/api/src/controllers/v2/monitor.ts
index 914b43c85..29d0a2180 100644
--- a/apps/api/src/controllers/v2/monitor.ts
+++ b/apps/api/src/controllers/v2/monitor.ts
@@ -1,5 +1,6 @@
import { Response } from "express";
import { z } from "zod";
+import { logger as _logger } from "../../lib/logger";
import { RequestWithAuth } from "./types";
import { getScrapeZDR } from "../../lib/zdr-helpers";
import { getMonitorDiffArtifact } from "../../lib/gcs-monitoring";
@@ -29,6 +30,13 @@ import {
estimateRunsPerMonth,
validateMonitorCron,
} from "../../services/monitoring/cron";
+import {
+ getRemovedMonitorTargets,
+ trackMonitorConfiguredInterest,
+ trackMonitorDeactivatedInterest,
+} from "../../services/monitoring/interest";
+
+const logger = _logger.child({ module: "monitor-controller" });
const monitorParamsSchema = z.strictObject({
monitorId: z.uuid(),
@@ -131,6 +139,17 @@ export async function createMonitorController(
intervalMs: schedule.intervalMs,
});
+ trackMonitorConfiguredInterest({
+ monitor,
+ intervalMs: schedule.intervalMs,
+ }).catch(error =>
+ logger.warn("Failed to track monitor target interest", {
+ error,
+ monitorId: monitor.id,
+ eventType: "configured",
+ }),
+ );
+
res.status(200).json({
success: true,
data: serializeMonitor(monitor),
@@ -202,6 +221,47 @@ export async function updateMonitorController(
intervalMs:
input.schedule || input.targets ? schedule.intervalMs : undefined,
});
+ if (!monitor) {
+ return res.status(404).json({ success: false, error: "Monitor not found" });
+ }
+
+ const interestTracking: Promise<void>[] = [];
+ const removedTargets = input.targets
+ ? getRemovedMonitorTargets({ before: existing, after: monitor })
+ : [];
+ if (removedTargets.length > 0) {
+ interestTracking.push(
+ trackMonitorDeactivatedInterest({
+ monitor: existing,
+ targets: removedTargets,
+ }),
+ );
+ }
+ if (
+ monitor.status === "paused" &&
+ (input.status === "paused" || input.schedule || input.targets)
+ ) {
+ interestTracking.push(
+ trackMonitorDeactivatedInterest({
+ monitor,
+ intervalMs: schedule.intervalMs,
+ }),
+ );
+ } else if (input.schedule || input.targets || input.status === "active") {
+ interestTracking.push(
+ trackMonitorConfiguredInterest({
+ monitor,
+ intervalMs: schedule.intervalMs,
+ }),
+ );
+ }
+ Promise.all(interestTracking).catch(error =>
+ logger.warn("Failed to track monitor target interest", {
+ error,
+ monitorId: monitor.id,
+ eventType: "update",
+ }),
+ );
res.status(200).json({
success: true,
@@ -214,6 +274,11 @@ export async function deleteMonitorController(
res: Response,
) {
const { monitorId } = monitorParamsSchema.parse(req.params);
+ const existing = await getMonitorForUpdate(req.auth.team_id, monitorId);
+ if (!existing) {
+ return res.status(404).json({ success: false, error: "Monitor not found" });
+ }
+
const deleted = await deleteMonitor({
teamId: req.auth.team_id,
monitorId,
@@ -222,6 +287,16 @@ export async function deleteMonitorController(
return res.status(404).json({ success: false, error: "Monitor not found" });
}
+ trackMonitorDeactivatedInterest({
+ monitor: { ...existing, status: "deleted" },
+ }).catch(error =>
+ logger.warn("Failed to track monitor target interest", {
+ error,
+ monitorId,
+ eventType: "deactivated",
+ }),
+ );
+
res.status(200).json({ success: true });
}
diff --git a/apps/api/src/lib/tracking.test.ts b/apps/api/src/lib/tracking.test.ts
new file mode 100644
index 000000000..a4b2109e7
--- /dev/null
+++ b/apps/api/src/lib/tracking.test.ts
@@ -0,0 +1,135 @@
+import { chInsert } from "./clickhouse-client";
+import {
+ buildMonitorTargetInterestRows,
+ trackMonitorTargetInterest,
+} from "./tracking";
+import type { MonitorTarget } from "../services/monitoring/types";
+
+jest.mock("./clickhouse-client", () => ({
+ chInsert: jest.fn(),
+}));
+
+const scrapeTarget: MonitorTarget = {
+ id: "target-scrape",
+ type: "scrape",
+ urls: ["https://example.com/b#fragment", "https://example.com/a/"],
+ scrapeOptions: {},
+};
+
+const crawlTarget: MonitorTarget = {
+ id: "target-crawl",
+ type: "crawl",
+ url: "https://Docs.Example.com/start#section",
+ crawlOptions: {
+ limit: 250,
+ maxDiscoveryDepth: 3,
+ includePaths: ["/docs"],
+ excludePaths: ["/docs/archive"],
+ },
+ scrapeOptions: {},
+};
+
+describe("monitor target interest tracking", () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it("builds target-grain rows for scrape and crawl monitors", () => {
+ const rows = buildMonitorTargetInterestRows({
+ eventType: "configured",
+ teamId: "team-1",
+ monitorId: "monitor-1",
+ monitorStatus: "active",
+ scheduleCron: "0 * * * *",
+ scheduleTimezone: "UTC",
+ intervalMs: 60 * 60 * 1000,
+ targets: [scrapeTarget, crawlTarget],
+ zeroDataRetention: false,
+ eventTime: new Date("2026-05-12T15:00:00.000Z"),
+ });
+
+ expect(rows).toHaveLength(2);
+ expect(rows[0]).toEqual(
+ expect.objectContaining({
+ event_time: "2026-05-12T15:00:00.000Z",
+ event_type: "configured",
+ team_id: "team-1",
+ monitor_id: "monitor-1",
+ target_id: "target-scrape",
+ target_type: "scrape",
+ target_url: null,
+ target_domain: null,
+ scrape_url_count: 2,
+ crawl_limit: null,
+ crawl_max_depth: null,
+ interval_seconds: 3600,
+ runs_per_day: 24,
+ frequency_bucket: "hourly",
+ is_active: 1,
+ estimated_credits_per_run: 2,
+ }),
+ );
+ expect(rows[0].target_signature).toEqual(expect.any(String));
+ expect(String(rows[0].target_signature)).toHaveLength(64);
+
+ expect(rows[1]).toEqual(
+ expect.objectContaining({
+ target_id: "target-crawl",
+ target_type: "crawl",
+ target_url: "https://Docs.Example.com/start#section",
+ target_domain: "docs.example.com",
+ scrape_url_count: 0,
+ crawl_limit: 250,
+ crawl_max_depth: 3,
+ estimated_credits_per_run: 250,
+ }),
+ );
+ expect(rows[1].target_signature).toEqual(expect.any(String));
+ expect(String(rows[1].target_signature)).toHaveLength(64);
+ expect(rows[1].target_signature).not.toBe(rows[0].target_signature);
+ });
+
+ it("sends rows to the monitor target ClickHouse table", async () => {
+ await trackMonitorTargetInterest({
+ eventType: "check_started",
+ teamId: "team-1",
+ monitorId: "monitor-1",
+ monitorStatus: "active",
+ scheduleCron: "*/30 * * * *",
+ scheduleTimezone: "UTC",
+ intervalMs: 30 * 60 * 1000,
+ targets: [{ ...scrapeTarget, urls: ["https://example.com/page"] }],
+ checkId: "check-1",
+ zeroDataRetention: false,
+ eventTime: new Date("2026-05-12T15:30:00.000Z"),
+ });
+
+ expect(chInsert).toHaveBeenCalledWith("monitor_target_interest_events", [
+ expect.objectContaining({
+ event_type: "check_started",
+ check_id: "check-1",
+ target_url: "https://example.com/page",
+ target_domain: "example.com",
+ scrape_url_count: 1,
+ interval_seconds: 1800,
+ frequency_bucket: "30m",
+ }),
+ ]);
+ });
+
+ it("does not insert monitor interest for zero data retention", async () => {
+ await trackMonitorTargetInterest({
+ eventType: "configured",
+ teamId: "team-1",
+ monitorId: "monitor-1",
+ monitorStatus: "active",
+ scheduleCron: "0 * * * *",
+ scheduleTimezone: "UTC",
+ intervalMs: 60 * 60 * 1000,
+ targets: [scrapeTarget],
+ zeroDataRetention: true,
+ });
+
+ expect(chInsert).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/api/src/lib/tracking.ts b/apps/api/src/lib/tracking.ts
index e37c751a6..a58466c1e 100644
--- a/apps/api/src/lib/tracking.ts
+++ b/apps/api/src/lib/tracking.ts
@@ -1,5 +1,7 @@
+import { createHash } from "crypto";
import { chInsert } from "./clickhouse-client";
import type { SearchV2Response } from "./entities";
+import type { MonitorTarget } from "../services/monitoring/types";
function extractDomain(url: string): string {
try {
@@ -9,6 +11,25 @@ function extractDomain(url: string): string {
}
}
+function normalizeTrackingUrl(url: string): string {
+ try {
+ const parsed = new URL(url);
+ parsed.protocol = parsed.protocol.toLowerCase();
+ parsed.hostname = parsed.hostname.toLowerCase();
+ parsed.hash = "";
+ if (parsed.pathname !== "/") {
+ parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+ }
+ return parsed.toString();
+ } catch {
+ return url.trim();
+ }
+}
+
+function hashSignature(value: unknown): string {
+ return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
// =========================================
// Scrape tracking
// =========================================
@@ -46,6 +67,148 @@ export async function trackScrape(opts: TrackScrapeParams): Promise<void> {
]);
}
+// =========================================
+// Monitor target interest tracking
+// =========================================
+
+type MonitorTargetInterestEventType =
+ | "configured"
+ | "deactivated"
+ | "check_started";
+
+interface TrackMonitorTargetInterestParams {
+ eventType: MonitorTargetInterestEventType;
+ teamId: string;
+ monitorId: string;
+ monitorStatus: string;
+ scheduleCron: string;
+ scheduleTimezone: string;
+ intervalMs: number;
+ targets: MonitorTarget[];
+ checkId?: string | null;
+ zeroDataRetention: boolean;
+ eventTime?: Date;
+}
+
+function frequencyBucket(intervalSeconds: number): string {
+ if (intervalSeconds <= 15 * 60) return "15m";
+ if (intervalSeconds <= 30 * 60) return "30m";
+ if (intervalSeconds <= 60 * 60) return "hourly";
+ if (intervalSeconds <= 6 * 60 * 60) return "sub_daily";
+ if (intervalSeconds <= 24 * 60 * 60) return "daily";
+ if (intervalSeconds <= 7 * 24 * 60 * 60) return "weekly";
+ return "other";
+}
+
+function unsignedIntegerOrNull(value: unknown): number | null {
+ return typeof value === "number" && Number.isFinite(value) && value >= 0
+ ? Math.floor(value)
+ : null;
+}
+
+function positiveIntegerOrNull(value: unknown): number | null {
+ return typeof value === "number" && Number.isFinite(value) && value > 0
+ ? Math.floor(value)
+ : null;
+}
+
+function estimateMonitorTargetCredits(target: MonitorTarget): number {
+ if (target.type === "scrape") {
+ return target.urls.length;
+ }
+
+ return positiveIntegerOrNull(target.crawlOptions?.limit) ?? 10000;
+}
+
+function monitorTargetSignature(target: MonitorTarget): string {
+ if (target.type === "scrape") {
+ return hashSignature({
+ type: "scrape",
+ urls: target.urls.map(normalizeTrackingUrl).sort(),
+ });
+ }
+
+ return hashSignature({
+ type: "crawl",
+ url: normalizeTrackingUrl(target.url),
+ limit: positiveIntegerOrNull(target.crawlOptions?.limit),
+ maxDiscoveryDepth: unsignedIntegerOrNull(
+ target.crawlOptions?.maxDiscoveryDepth,
+ ),
+ includePaths: Array.isArray(target.crawlOptions?.includePaths)
+ ? [...target.crawlOptions.includePaths].sort()
+ : [],
+ excludePaths: Array.isArray(target.crawlOptions?.excludePaths)
+ ? [...target.crawlOptions.excludePaths].sort()
+ : [],
+ crawlEntireDomain: target.crawlOptions?.crawlEntireDomain ?? null,
+ allowExternalLinks: target.crawlOptions?.allowExternalLinks ?? null,
+ allowSubdomains: target.crawlOptions?.allowSubdomains ?? null,
+ sitemap: target.crawlOptions?.sitemap ?? null,
+ });
+}
+
+export function buildMonitorTargetInterestRows(
+ opts: TrackMonitorTargetInterestParams,
+): Record<string, unknown>[] {
+ const intervalSeconds = Math.max(1, Math.round(opts.intervalMs / 1000));
+ const eventTime = (opts.eventTime ?? new Date()).toISOString();
+ const isActive =
+ opts.eventType !== "deactivated" && opts.monitorStatus === "active";
+
+ return opts.targets.map(target => {
+ const isSingleScrapeTarget =
+ target.type === "scrape" && target.urls.length === 1;
+ const targetUrl =
+ target.type === "crawl"
+ ? target.url
+ : isSingleScrapeTarget
+ ? target.urls[0]
+ : null;
+
+ return {
+ event_time: eventTime,
+ event_type: opts.eventType,
+ team_id: opts.teamId,
+ monitor_id: opts.monitorId,
+ target_id: target.id,
+ check_id: opts.checkId ?? null,
+ target_type: target.type,
+ monitor_status: opts.monitorStatus,
+ target_url: targetUrl,
+ target_domain: targetUrl ? extractDomain(targetUrl) : null,
+ target_signature: monitorTargetSignature(target),
+ scrape_url_count: target.type === "scrape" ? target.urls.length : 0,
+ crawl_limit:
+ target.type === "crawl"
+ ? positiveIntegerOrNull(target.crawlOptions?.limit)
+ : null,
+ crawl_max_depth:
+ target.type === "crawl"
+ ? unsignedIntegerOrNull(target.crawlOptions?.maxDiscoveryDepth)
+ : null,
+ schedule_cron: opts.scheduleCron,
+ schedule_timezone: opts.scheduleTimezone,
+ interval_seconds: intervalSeconds,
+ runs_per_day: 86400 / intervalSeconds,
+ frequency_bucket: frequencyBucket(intervalSeconds),
+ is_active: isActive ? 1 : 0,
+ estimated_credits_per_run: estimateMonitorTargetCredits(target),
+ };
+ });
+}
+
+export async function trackMonitorTargetInterest(
+ opts: TrackMonitorTargetInterestParams,
+): Promise<void> {
+ if (opts.zeroDataRetention) return;
+
+ await chInsert(
+ "monitor_target_interest_events",
+ buildMonitorTargetInterestRows(opts),
+ );
+}
+
// =========================================
// Search request tracking
// =========================================
diff --git a/apps/api/src/services/monitoring/interest.test.ts b/apps/api/src/services/monitoring/interest.test.ts
new file mode 100644
index 000000000..c5453c0a1
--- /dev/null
+++ b/apps/api/src/services/monitoring/interest.test.ts
@@ -0,0 +1,103 @@
+import { trackMonitorTargetInterest } from "../../lib/tracking";
+import {
+ getRemovedMonitorTargets,
+ trackMonitorCheckStartedInterest,
+ trackMonitorConfiguredInterest,
+ trackMonitorDeactivatedInterest,
+} from "./interest";
+import type { MonitorCheckRow, MonitorRow, MonitorTarget } from "./types";
+
+jest.mock("../../lib/tracking", () => ({
+ trackMonitorTargetInterest: jest.fn(),
+}));
+
+const scrapeTarget: MonitorTarget = {
+ id: "scrape-target",
+ type: "scrape",
+ urls: ["https://example.com/a"],
+ scrapeOptions: {},
+};
+
+const crawlTarget: MonitorTarget = {
+ id: "crawl-target",
+ type: "crawl",
+ url: "https://example.com/docs",
+ crawlOptions: { limit: 50, maxDiscoveryDepth: 2 },
+ scrapeOptions: {},
+};
+
+const monitor = {
+ id: "monitor-1",
+ team_id: "team-1",
+ status: "active",
+ schedule_cron: "0 * * * *",
+ schedule_timezone: "UTC",
+ targets: [scrapeTarget, crawlTarget],
+} as MonitorRow;
+
+describe("monitor interest emit helpers", () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ (trackMonitorTargetInterest as jest.Mock).mockResolvedValue(undefined);
+ });
+
+ it("finds configured targets removed by an update", () => {
+ expect(
+ getRemovedMonitorTargets({
+ before: monitor,
+ after: { ...monitor, targets: [crawlTarget] },
+ }),
+ ).toEqual([scrapeTarget]);
+ });
+
+ it("emits configured interest for all monitor targets", async () => {
+ await trackMonitorConfiguredInterest({
+ monitor,
+ intervalMs: 60 * 60 * 1000,
+ });
+
+ expect(trackMonitorTargetInterest).toHaveBeenCalledWith(
+ expect.objectContaining({
+ eventType: "configured",
+ teamId: "team-1",
+ monitorId: "monitor-1",
+ monitorStatus: "active",
+ intervalMs: 60 * 60 * 1000,
+ targets: [scrapeTarget, crawlTarget],
+ zeroDataRetention: false,
+ }),
+ );
+ });
+
+ it("emits deactivated interest for a target subset", async () => {
+ await trackMonitorDeactivatedInterest({
+ monitor: { ...monitor, status: "paused" },
+ targets: [scrapeTarget],
+ intervalMs: 60 * 60 * 1000,
+ });
+
+ expect(trackMonitorTargetInterest).toHaveBeenCalledWith(
+ expect.objectContaining({
+ eventType: "deactivated",
+ monitorStatus: "paused",
+ targets: [scrapeTarget],
+ }),
+ );
+ });
+
+ it("emits check_started interest with a check id", async () => {
+ await trackMonitorCheckStartedInterest({
+ monitor,
+ check: { id: "check-1" } as MonitorCheckRow,
+ });
+
+ expect(trackMonitorTargetInterest).toHaveBeenCalledWith(
+ expect.objectContaining({
+ eventType: "check_started",
+ checkId: "check-1",
+ intervalMs: 60 * 60 * 1000,
+ targets: [scrapeTarget, crawlTarget],
+ }),
+ );
+ });
+});
diff --git a/apps/api/src/services/monitoring/interest.ts b/apps/api/src/services/monitoring/interest.ts
new file mode 100644
index 000000000..4d80b5b28
--- /dev/null
+++ b/apps/api/src/services/monitoring/interest.ts
@@ -0,0 +1,77 @@
+import { trackMonitorTargetInterest } from "../../lib/tracking";
+import { validateMonitorCron } from "./cron";
+import type { MonitorCheckRow, MonitorRow, MonitorTarget } from "./types";
+
+function monitorIntervalMs(monitor: MonitorRow): number {
+ return validateMonitorCron(monitor.schedule_cron, monitor.schedule_timezone)
+ .intervalMs;
+}
+
+function interestTargets(monitor: MonitorRow): MonitorTarget[] {
+ return monitor.targets ?? [];
+}
+
+export function getRemovedMonitorTargets(params: {
+ before: MonitorRow;
+ after: MonitorRow;
+}): MonitorTarget[] {
+ const afterIds = new Set(
+ interestTargets(params.after).map(target => target.id),
+ );
+ return interestTargets(params.before).filter(
+ target => !afterIds.has(target.id),
+ );
+}
+
+export async function trackMonitorConfiguredInterest(params: {
+ monitor: MonitorRow;
+ intervalMs?: number;
+}): Promise<void> {
+ await trackMonitorTargetInterest({
+ eventType: "configured",
+ teamId: params.monitor.team_id,
+ monitorId: params.monitor.id,
+ monitorStatus: params.monitor.status,
+ scheduleCron: params.monitor.schedule_cron,
+ scheduleTimezone: params.monitor.schedule_timezone,
+ intervalMs: params.intervalMs ?? monitorIntervalMs(params.monitor),
+ targets: interestTargets(params.monitor),
+ zeroDataRetention: false,
+ });
+}
+
+export async function trackMonitorDeactivatedInterest(params: {
+ monitor: MonitorRow;
+ targets?: MonitorTarget[];
+ intervalMs?: number;
+}): Promise<void> {
+ await trackMonitorTargetInterest({
+ eventType: "deactivated",
+ teamId: params.monitor.team_id,
+ monitorId: params.monitor.id,
+ monitorStatus: params.monitor.status,
+ scheduleCron: params.monitor.schedule_cron,
+ scheduleTimezone: params.monitor.schedule_timezone,
+ intervalMs: params.intervalMs ?? monitorIntervalMs(params.monitor),
+ targets: params.targets ?? interestTargets(params.monitor),
+ zeroDataRetention: false,
+ });
+}
+
+export async function trackMonitorCheckStartedInterest(params: {
+ monitor: MonitorRow;
+ check: MonitorCheckRow;
+}): Promise<void> {
+ await trackMonitorTargetInterest({
+ eventType: "check_started",
+ teamId: params.monitor.team_id,
+ monitorId: params.monitor.id,
+ monitorStatus: params.monitor.status,
+ scheduleCron: params.monitor.schedule_cron,
+ scheduleTimezone: params.monitor.schedule_timezone,
+ intervalMs: monitorIntervalMs(params.monitor),
+ targets: interestTargets(params.monitor),
+ checkId: params.check.id,
+ zeroDataRetention: false,
+ });
+}
diff --git a/apps/api/src/services/monitoring/runner.ts b/apps/api/src/services/monitoring/runner.ts
index 42a74a479..ed110dd18 100644
--- a/apps/api/src/services/monitoring/runner.ts
+++ b/apps/api/src/services/monitoring/runner.ts
@@ -57,6 +57,7 @@ import {
isMonitorCheckStale,
MONITOR_CHECK_STALE_TIMEOUT_MS,
} from "./stale";
+import { trackMonitorCheckStartedInterest } from "./interest";
const logger = _logger.child({ module: "monitoring-runner" });
const poll = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
@@ -816,6 +817,15 @@ export async function processMonitorCheckJob(
started_at: new Date().toISOString(),
});
+ trackMonitorCheckStartedInterest({ monitor, check }).catch(error =>
+ logger.warn("Failed to track monitor target interest", {
+ error,
+ monitorId: monitor.id,
+ checkId: check.id,
+ eventType: "check_started",
+ }),
+ );
+
let lockId: string | null = null;
try {
lockId = await autumnService.lockCredits({
diff --git a/apps/api/src/services/notification/monitoring_email.test.ts b/apps/api/src/services/notification/monitoring_email.test.ts
new file mode 100644
index 000000000..1c2306819
--- /dev/null
+++ b/apps/api/src/services/notification/monitoring_email.test.ts
@@ -0,0 +1,59 @@
+jest.mock("../supabase", () => ({
+ supabase_service: {},
+}));
+
+import {
+ buildHtml,
+ buildMonitoringCheckDashboardUrl,
+ type MonitoringEmailPayload,
+} from "./monitoring_email";
+
+describe("monitoring email", () => {
+ it("builds a dashboard link for a monitor check", () => {
+ expect(
+ buildMonitoringCheckDashboardUrl(
+ {
+ monitorId: "019e07fb-fb25-74cb-9a6c-f36c685c6e5b",
+ checkId: "019e0903-bf7c-779f-a8a5-736ba82d3974",
+ },
+ "https://firecrawl-o2cg7p09w-side-guide.vercel.app/",
+ ),
+ ).toBe(
+ "https://firecrawl-o2cg7p09w-side-guide.vercel.app/app/monitoring/019e07fb-fb25-74cb-9a6c-f36c685c6e5b?checkId=019e0903-bf7c-779f-a8a5-736ba82d3974",
+ );
+ });
+
+ it("includes the dashboard check link in the email html", () => {
+ const dashboardUrl = buildMonitoringCheckDashboardUrl(
+ {
+ monitorId: "monitor-1",
+ checkId: "check-1",
+ },
+ "https://www.firecrawl.dev",
+ );
+ const payload: MonitoringEmailPayload = {
+ monitorId: "monitor-1",
+ monitorName: "Docs monitor",
+ checkId: "check-1",
+ dashboardUrl,
+ summary: {
+ changed: 1,
+ new: 0,
+ removed: 0,
+ error: 0,
+ totalPages: 1,
+ },
+ pages: [
+ {
+ url: "https://example.com/docs",
+ status: "changed",
+ },
+ ],
+ creditsUsed: 1,
+ };
+
+ expect(buildHtml(payload)).toContain(
+ `<a href="${dashboardUrl}">View this check in the dashboard</a>`,
+ );
+ });
+});
diff --git a/apps/api/src/services/notification/monitoring_email.ts b/apps/api/src/services/notification/monitoring_email.ts
index 06d90ed83..df3b53b5d 100644
--- a/apps/api/src/services/notification/monitoring_email.ts
+++ b/apps/api/src/services/notification/monitoring_email.ts
@@ -13,10 +13,11 @@ type MonitoringEmailPage = {
error?: string | null;
};
-type MonitoringEmailPayload = {
+export type MonitoringEmailPayload = {
monitorId: string;
monitorName: string;
checkId: string;
+ dashboardUrl: string;
summary: {
changed: number;
new: number;
@@ -64,7 +65,19 @@ async function getTeamEmails(teamId: string): Promise<string[]> {
return [...emails];
}
-function buildHtml(payload: MonitoringEmailPayload): string {
+export function buildMonitoringCheckDashboardUrl(
+ params: { monitorId: string; checkId: string },
+ baseUrl: string = config.FIRECRAWL_DASHBOARD_URL,
+): string {
+ const url = new URL(
+ `/app/monitoring/${encodeURIComponent(params.monitorId)}`,
+ baseUrl.trim(),
+ );
+ url.searchParams.set("checkId", params.checkId);
+ return url.toString();
+}
+
+export function buildHtml(payload: MonitoringEmailPayload): string {
const pageItems = payload.pages
.slice(0, 20)
.map(page => {
@@ -74,6 +87,7 @@ function buildHtml(payload: MonitoringEmailPayload): string {
}</li>`;
})
.join("");
+ const dashboardUrl = escapeHtml(payload.dashboardUrl);
return `Hey there,<br/>
<p>Your Firecrawl monitor <strong>${escapeHtml(payload.monitorName)}</strong> detected activity.</p>
@@ -85,6 +99,7 @@ function buildHtml(payload: MonitoringEmailPayload): string {
<li>Total pages checked: ${payload.summary.totalPages}</li>
</ul>
${pageItems ? `<p>Top pages:</p><ul>${pageItems}</ul>` : ""}
+<p><a href="${dashboardUrl}">View this check in the dashboard</a></p>
<p>Check ID: <code>${escapeHtml(payload.checkId)}</code></p>
<p>Credits used: ${payload.creditsUsed ?? "unknown"}</p>
<br/>Thanks,<br/>Firecrawl Team<br/>`;
@@ -161,6 +176,10 @@ export async function sendMonitoringEmailSummary(params: {
monitorId: params.monitor.id,
monitorName: params.monitor.name,
checkId: params.check.id,
+ dashboardUrl: buildMonitoringCheckDashboardUrl({
+ monitorId: params.monitor.id,
+ checkId: params.check.id,
+ }),
summary: {
changed: params.check.changed_count,
new: params.check.new_count,