@agent-native/core 0.84.21 → 0.84.22

package/corpus/templates/analytics/actions/delete-analytics-alert-rule.ts

@@ -0,0 +1,23 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { deleteAnalyticsAlertRule } from "../server/lib/analytics-alerts";
+
+export default defineAction({
+  description: "Delete a reusable first-party analytics alert rule.",
+  schema: z.object({
+    id: z.string().describe("Alert rule ID"),
+  }),
+  http: { method: "POST" },
+  run: async ({ id }) => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() || null;
+    await deleteAnalyticsAlertRule(id, { email, orgId });
+    return { ok: true };
+  },
+});

package/corpus/templates/analytics/actions/list-analytics-alert-rules.ts

@@ -0,0 +1,20 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { listAnalyticsAlertRules } from "../server/lib/analytics-alerts";
+
+export default defineAction({
+  description: "List reusable alert rules over first-party analytics events.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() || null;
+    return listAnalyticsAlertRules({ email, orgId });
+  },
+});

package/corpus/templates/analytics/actions/run-analytics-alerts.ts

@@ -0,0 +1,23 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { runAnalyticsAlertsOnce } from "../server/jobs/analytics-alerts";
+
+export default defineAction({
+  description:
+    "Run one alert sweep for the current user's first-party analytics alert rules.",
+  schema: z.object({
+    limit: z.number().int().min(1).max(500).optional(),
+  }),
+  http: { method: "POST" },
+  run: async ({ limit }) => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() || null;
+    return runAnalyticsAlertsOnce({ ownerEmail: email, orgId, limit });
+  },
+});

package/corpus/templates/analytics/actions/save-analytics-alert-rule.ts

@@ -0,0 +1,69 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server";
+import { z } from "zod";
+
+import { saveAnalyticsAlertRule } from "../server/lib/analytics-alerts";
+
+const filterSchema = z.object({
+  field: z
+    .string()
+    .describe(
+      "Analytics field path, e.g. event_name, app, template, properties.error_code, or context.url.",
+    ),
+  op: z
+    .enum(["equals", "not_equals", "contains", "in", "exists"])
+    .optional()
+    .describe("Filter operator; defaults to equals."),
+  value: z.unknown().optional().describe("Value to compare against."),
+});
+
+export default defineAction({
+  description:
+    "Create or update a reusable alert rule over first-party analytics events.",
+  schema: z.object({
+    id: z.string().optional().describe("Existing alert rule ID to update"),
+    name: z.string().describe("Human-readable alert name"),
+    description: z.string().optional(),
+    eventName: z
+      .string()
+      .optional()
+      .nullable()
+      .describe("Optional exact event name to target before filters run."),
+    filters: z
+      .array(filterSchema)
+      .optional()
+      .describe("Generic event filters evaluated over columns/properties."),
+    thresholdMode: z
+      .enum(["event_count", "distinct_count"])
+      .optional()
+      .describe("Count matching events or distinct values."),
+    distinctBy: z
+      .string()
+      .optional()
+      .nullable()
+      .describe("Field path used when thresholdMode is distinct_count."),
+    threshold: z.number().int().min(1),
+    windowMinutes: z.number().int().min(1).max(1440),
+    cooldownMinutes: z.number().int().min(0).max(1440).optional(),
+    severity: z.enum(["warning", "critical"]).optional(),
+    channels: z
+      .array(z.string())
+      .optional()
+      .describe("Notification channels, e.g. inbox, email, slack, webhook."),
+    emailRecipients: z
+      .array(z.string().email())
+      .optional()
+      .describe("Email recipients passed to the generic email channel."),
+    enabled: z.boolean().optional(),
+  }),
+  http: { method: "POST" },
+  run: async (args) => {
+    const email = getRequestUserEmail();
+    if (!email) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId() || null;
+    return saveAnalyticsAlertRule(args, { email, orgId });
+  },
+});

package/corpus/templates/analytics/changelog/2026-07-01-analytics-can-alert-when-first-party-events-spike.md

@@ -0,0 +1,6 @@
+---
+type: added
+date: 2026-07-01
+---
+
+Analytics can now notify inbox, email, Slack, or webhook channels when first-party events spike.

package/corpus/templates/analytics/changelog/2026-07-01-session-replays-play-back-in-production-instead-of-showing.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-01
+---
+
+Session replays now play back in production instead of showing a blank recording, because chunk downloads no longer rely on a manual gzip content-encoding that serverless hosts corrupted.

package/corpus/templates/analytics/netlify.toml

@@ -20,3 +20,6 @@ timeout = 75
 [functions.dashboard-report-sweep-background]
 timeout = 300
 memory = "2gb"
+
+[functions.analytics-alert-sweep-background]
+timeout = 120

package/corpus/templates/analytics/scripts/emit-netlify-dashboard-report-cron.ts

@@ -12,6 +12,10 @@ const SCHEDULED_NAME = "dashboard-report-cron";
 const WORKER_NAME = "dashboard-report-sweep-background";
 const ROUTE_PATH = "/api/dashboard-reports/run";
 const SCHEDULE = "*/15 * * * *";
+const ALERT_SCHEDULED_NAME = "analytics-alert-cron";
+const ALERT_WORKER_NAME = "analytics-alert-sweep-background";
+const ALERT_ROUTE_PATH = "/api/analytics-alerts/run";
+const ALERT_SCHEDULE = "*/5 * * * *";
 
 function ensureDir(dir: string) {
   mkdirSync(dir, { recursive: true });
@@ -116,6 +120,105 @@ export const config = {
   writeFileSync(path.join(dest, `${WORKER_NAME}.mjs`), source);
 }
 
+function emitAlertScheduledTrigger(token: string) {
+  const dest = path.join(FUNCTIONS_DIR, ALERT_SCHEDULED_NAME);
+  rmSync(dest, { recursive: true, force: true });
+  ensureDir(dest);
+
+  const source = `const WORKER_PATH = "/.netlify/functions/${ALERT_WORKER_NAME}";
+const CRON_TOKEN = ${JSON.stringify(token)};
+
+function siteOrigin(request) {
+  const configured = process.env.URL || process.env.DEPLOY_URL;
+  if (configured) return configured;
+  const url = new URL(request.url);
+  return url.origin;
+}
+
+export default async function handler(request) {
+  const url = new URL(WORKER_PATH, siteOrigin(request));
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-agent-native-analytics-alert-cron": CRON_TOKEN,
+    },
+    body: JSON.stringify({ scheduled: true }),
+  });
+
+  if (!response.ok && response.status !== 202) {
+    console.error(
+      "[analytics-alert-cron] Background sweep trigger failed:",
+      response.status,
+      await response.text().catch(() => ""),
+    );
+  }
+}
+
+export const config = {
+  name: "analytics alert cron trigger",
+  generator: "agent-native analytics build",
+  schedule: ${JSON.stringify(ALERT_SCHEDULE)},
+};
+`;
+
+  writeFileSync(path.join(dest, `${ALERT_SCHEDULED_NAME}.mjs`), source);
+}
+
+function emitAlertBackgroundWorker(token: string) {
+  const dest = path.join(FUNCTIONS_DIR, ALERT_WORKER_NAME);
+  rmSync(dest, { recursive: true, force: true });
+  cpSync(SERVER_DIR, dest, { recursive: true });
+  rmSync(path.join(dest, "server.mjs"), { force: true });
+
+  const source = `globalThis.__AGENT_NATIVE_ANALYTICS_ALERT_SCHEDULED_RUNTIME__ = true;
+
+const CRON_TOKEN = ${JSON.stringify(token)};
+const ROUTE_PATH = ${JSON.stringify(ALERT_ROUTE_PATH)};
+let cachedHandler;
+
+function timingSafeEquals(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+export default async function handler(request, context) {
+  const token = request.headers.get("x-agent-native-analytics-alert-cron") || "";
+  if (!timingSafeEquals(token, CRON_TOKEN)) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  cachedHandler ??= (await import("./main.mjs")).default;
+  const url = new URL(request.url);
+  url.pathname = ROUTE_PATH;
+  url.search = "";
+
+  const rewritten = new Request(url.toString(), {
+    method: "POST",
+    headers: new Headers({ "content-type": "application/json" }),
+    body: JSON.stringify({ scheduled: true }),
+  });
+
+  return await cachedHandler(rewritten, context);
+}
+
+export const config = {
+  name: "analytics alert background sweep",
+  generator: "agent-native analytics build",
+  background: true,
+  nodeBundler: "none",
+  includedFiles: ["**"],
+  preferStatic: false,
+};
+`;
+
+  writeFileSync(path.join(dest, `${ALERT_WORKER_NAME}.mjs`), source);
+}
+
 function isDirectRun(): boolean {
   const entrypoint = process.argv[1];
   return Boolean(
@@ -133,11 +236,17 @@ function main(): void {
   }
 
   const token = randomBytes(32).toString("hex");
+  const alertToken = randomBytes(32).toString("hex");
   emitScheduledTrigger(token);
   emitBackgroundWorker(token);
+  emitAlertScheduledTrigger(alertToken);
+  emitAlertBackgroundWorker(alertToken);
   console.log(
     `[dashboard-report-cron] Emitted Netlify scheduled trigger "${SCHEDULED_NAME}" (${SCHEDULE}) and background worker "${WORKER_NAME}".`,
   );
+  console.log(
+    `[analytics-alert-cron] Emitted Netlify scheduled trigger "${ALERT_SCHEDULED_NAME}" (${ALERT_SCHEDULE}) and background worker "${ALERT_WORKER_NAME}".`,
+  );
 }
 
 if (isDirectRun()) {

package/corpus/templates/analytics/server/db/schema.ts

@@ -179,6 +179,61 @@ export const analyticsEvents = table("analytics_events", {
   orgId: text("org_id"),
 });
 
+/**
+ * Generic alert rules over first-party analytics events. Rules are owned by a
+ * user/org but can target any app, template, event name, or event property.
+ */
+export const analyticsAlertRules = table("analytics_alert_rules", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  description: text("description").notNull().default(""),
+  eventName: text("event_name"),
+  filters: text("filters").notNull().default("[]"),
+  thresholdMode: text("threshold_mode", {
+    enum: ["event_count", "distinct_count"],
+  })
+    .notNull()
+    .default("event_count"),
+  distinctBy: text("distinct_by"),
+  threshold: integer("threshold").notNull().default(1),
+  windowMinutes: integer("window_minutes").notNull().default(10),
+  cooldownMinutes: integer("cooldown_minutes").notNull().default(30),
+  severity: text("severity", { enum: ["warning", "critical"] })
+    .notNull()
+    .default("warning"),
+  channels: text("channels").notNull().default('["inbox"]'),
+  emailRecipients: text("email_recipients").notNull().default("[]"),
+  enabled: integer("enabled", { mode: "boolean" }).notNull().default(true),
+  lastEvaluatedAt: text("last_evaluated_at"),
+  lastTriggeredAt: text("last_triggered_at"),
+  lastStatus: text("last_status", {
+    enum: ["ok", "triggered", "cooldown", "error"],
+  }),
+  lastError: text("last_error"),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+  ownerEmail: text("owner_email").notNull().default("local@localhost"),
+  orgId: text("org_id"),
+});
+
+export const analyticsAlertIncidents = table("analytics_alert_incidents", {
+  id: text("id").primaryKey(),
+  ruleId: text("rule_id").notNull(),
+  triggeredAt: text("triggered_at").notNull(),
+  windowStart: text("window_start").notNull(),
+  windowEnd: text("window_end").notNull(),
+  threshold: integer("threshold").notNull(),
+  observedValue: integer("observed_value").notNull(),
+  eventCount: integer("event_count").notNull(),
+  severity: text("severity", { enum: ["warning", "critical"] }).notNull(),
+  channels: text("channels").notNull().default("[]"),
+  sampleEvents: text("sample_events").notNull().default("[]"),
+  notificationId: text("notification_id"),
+  createdAt: text("created_at").notNull().default(now()),
+  ownerEmail: text("owner_email").notNull().default("local@localhost"),
+  orgId: text("org_id"),
+});
+
 /**
  * Session replay summaries recorded through the first-party analytics replay
  * endpoint. Raw replay chunks live in session_replay_chunks and are only read

package/corpus/templates/analytics/server/handlers/session-replay.ts

@@ -355,12 +355,15 @@ export const handleSessionReplayChunkBytes = defineEventHandler(
           userEmail: ctx.userEmail,
           orgId: ctx.orgId ?? null,
         });
+        // Serve decompressed JSON and let the platform negotiate wire
+        // compression. Manually returning a pre-gzipped body with a
+        // `Content-Encoding: gzip` header corrupted replay downloads on
+        // serverless hosts and left playback blank in production.
         setResponseHeader(event, "Content-Type", "application/json");
-        setResponseHeader(event, "Content-Encoding", "gzip");
         setResponseHeader(event, "Cache-Control", "no-store");
         setResponseHeader(event, "X-Session-Replay-Seq", String(result.seq));
         setResponseHeader(event, "X-Session-Replay-Checksum", result.checksum);
-        return result.data;
+        return result.json;
       } catch (error: any) {
         setResponseStatus(event, statusFromError(error));
         return { error: messageFromError(error) };

package/corpus/templates/analytics/server/jobs/analytics-alerts.ts

@@ -0,0 +1,71 @@
+import {
+  evaluateAndNotifyAnalyticsAlertRule,
+  listEnabledAnalyticsAlertRules,
+  markAnalyticsAlertRuleError,
+} from "../lib/analytics-alerts";
+
+let running = false;
+const DEFAULT_MAX_RULES_PER_SWEEP = 100;
+
+function maxRulesPerSweep(input?: number): number {
+  if (input) return Math.max(1, Math.min(500, Math.floor(input)));
+  const raw = process.env.ANALYTICS_ALERT_SWEEP_LIMIT?.trim();
+  if (!raw) return DEFAULT_MAX_RULES_PER_SWEEP;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0
+    ? parsed
+    : DEFAULT_MAX_RULES_PER_SWEEP;
+}
+
+/**
+ * Run one analytics alert sweep. Exported for deployment-specific scheduled
+ * functions that should not rely on a long-lived Node process.
+ */
+export async function runAnalyticsAlertsOnce(
+  options: {
+    ownerEmail?: string;
+    orgId?: string | null;
+    limit?: number;
+  } = {},
+): Promise<{
+  processed: number;
+  triggered: number;
+  failed: number;
+  remaining: number;
+}> {
+  if (running) return { processed: 0, triggered: 0, failed: 0, remaining: 0 };
+  running = true;
+  let processed = 0;
+  let triggered = 0;
+  let failed = 0;
+  let remaining = 0;
+
+  try {
+    const sweepLimit = maxRulesPerSweep(options.limit);
+    const rules = await listEnabledAnalyticsAlertRules({
+      limit: sweepLimit,
+      ownerEmail: options.ownerEmail,
+      orgId: options.orgId,
+    });
+    remaining = rules.length >= sweepLimit ? 1 : 0;
+
+    for (const rule of rules) {
+      processed++;
+      try {
+        const result = await evaluateAndNotifyAnalyticsAlertRule(rule);
+        if (result.status === "triggered") triggered++;
+      } catch (err) {
+        failed++;
+        await markAnalyticsAlertRuleError(rule.id, err).catch(() => {});
+        console.error(
+          `[analytics-alerts] Rule ${rule.id} (${rule.name}) failed:`,
+          err,
+        );
+      }
+    }
+  } finally {
+    running = false;
+  }
+
+  return { processed, triggered, failed, remaining };
+}