@agent-native/core 0.136.0 → 0.136.3

package/corpus/templates/clips/scripts/send-real-recap.ts

@@ -0,0 +1,165 @@
+/**
+ * Send the monthly recap for a real account using live Clips data.
+ *
+ * Talks to the database directly with a read-only driver instead of booting
+ * the app, so it cannot run a migration against a shared database. Copy is
+ * composed exactly as the worker composes it, so this sends the real thing.
+ *
+ *   npx tsx scripts/send-real-recap.ts --owner a@b.com --to a@b.com --month 2026-07
+ */
+
+import postgres from "postgres";
+
+import {
+  composeRecapCopy,
+  sendClipsTransactionalEmail,
+} from "../server/lib/transactional-email-templates.js";
+
+function arg(args: string[], name: string): string | undefined {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+function required(args: string[], name: string): string {
+  const value = arg(args, name);
+  if (!value) throw new Error(`--${name} is required`);
+  return value;
+}
+
+async function main(args: string[]): Promise<void> {
+  const owner = required(args, "owner");
+  const to = required(args, "to");
+  const month = required(args, "month");
+  const databaseUrl = process.env.CLIPS_DATABASE_URL;
+  if (!databaseUrl) throw new Error("CLIPS_DATABASE_URL is not set");
+
+  const [year, monthNumber] = month.split("-").map(Number);
+  const startAt = new Date(Date.UTC(year, monthNumber - 1, 1)).toISOString();
+  const endAt = new Date(Date.UTC(year, monthNumber, 1)).toISOString();
+
+  const sql = postgres(databaseUrl, { ssl: "require", max: 1 });
+  try {
+    const owned = await sql<
+      {
+        id: string;
+        title: string;
+        thumbnail_url: string | null;
+        duration_ms: number;
+        created_at: string;
+      }[]
+    >`select id, title, thumbnail_url, duration_ms, created_at
+        from recordings where lower(owner_email) = lower(${owner})`;
+    if (owned.length === 0) throw new Error(`${owner} owns no recordings`);
+    const ids = owned.map((row) => row.id);
+
+    const humans = await sql<{ recording_id: string; n: number }[]>`
+      select recording_id, count(*)::int n
+        from recording_views
+       where recording_id in ${sql(ids)}
+         and viewed_at >= ${startAt} and viewed_at < ${endAt}
+       group by recording_id`;
+    const agents = await sql<{ recording_id: string; n: number }[]>`
+      select recording_id, count(*)::int n
+        from recording_agent_views
+       where recording_id in ${sql(ids)}
+         and first_seen_at >= ${startAt} and first_seen_at < ${endAt}
+       group by recording_id`;
+
+    const humanByClip = new Map(humans.map((row) => [row.recording_id, row.n]));
+    const agentByClip = new Map(agents.map((row) => [row.recording_id, row.n]));
+    const humanViews = [...humanByClip.values()].reduce((a, b) => a + b, 0);
+    const agentSessions = [...agentByClip.values()].reduce((a, b) => a + b, 0);
+    if (humanViews === 0 && agentSessions === 0) {
+      throw new Error(`${owner} had no audience in ${month}; no recap is due`);
+    }
+
+    const top = owned
+      .filter((row) => humanByClip.has(row.id) || agentByClip.has(row.id))
+      .map((row) => ({
+        row,
+        audience:
+          (humanByClip.get(row.id) ?? 0) + (agentByClip.get(row.id) ?? 0),
+      }))
+      .sort(
+        (left, right) =>
+          right.audience - left.audience ||
+          right.row.created_at.localeCompare(left.row.created_at) ||
+          left.row.id.localeCompare(right.row.id),
+      )[0].row;
+
+    const monthViewerIds = (
+      await sql<{ viewer_id: string }[]>`
+        select distinct viewer_id from recording_views
+         where recording_id = ${top.id}
+           and viewed_at >= ${startAt} and viewed_at < ${endAt}`
+    ).map((row) => row.viewer_id);
+    let completedPct = 0;
+    let dropOffMs: number | null = null;
+    if (monthViewerIds.length > 0) {
+      const [completion] = await sql<{ mean: string | null }[]>`
+        select avg(completed_pct) mean from recording_viewers
+         where recording_id = ${top.id} and id in ${sql(monthViewerIds)}`;
+      completedPct = Math.round(Number(completion?.mean ?? 0));
+      const [progress] = await sql<{ timestamp_ms: number }[]>`
+        select timestamp_ms from recording_events
+         where recording_id = ${top.id} and viewer_id in ${sql(monthViewerIds)}
+           and kind in ('watch-progress', 'pause')
+           and created_at >= ${startAt} and created_at < ${endAt}
+         order by timestamp_ms desc limit 1`;
+      dropOffMs = progress ? Number(progress.timestamp_ms) : null;
+    }
+    const agentBreakdown = (
+      await sql<{ agent_label: string | null; n: number }[]>`
+        select agent_label, count(*)::int n from recording_agent_views
+         where recording_id = ${top.id}
+           and first_seen_at >= ${startAt} and first_seen_at < ${endAt}
+         group by agent_label order by n desc, agent_label asc`
+    ).map((row) => ({
+      // "Agent" is the agent-views fallback label, not a product name.
+      agentLabel: row.agent_label === "Agent" ? null : row.agent_label,
+      sessions: row.n,
+    }));
+
+    console.log(
+      `Account totals for ${month}: ${humanViews} human views, ${agentSessions} agent sessions`,
+    );
+    console.log(
+      `Top clip: ${top.title} (${humanByClip.get(top.id) ?? 0} human / ${agentByClip.get(top.id) ?? 0} agent)`,
+    );
+
+    await sendClipsTransactionalEmail({
+      kind: "monthly-recap",
+      to,
+      month,
+      humanViews,
+      agentSessions,
+      topClip: {
+        recordingId: top.id,
+        title: top.title,
+        thumbnailUrl: top.thumbnail_url,
+        durationMs: Number(top.duration_ms),
+        recordedAt: top.created_at,
+        humanViews: humanByClip.get(top.id) ?? 0,
+        agentSessions: agentByClip.get(top.id) ?? 0,
+      },
+      copy: composeRecapCopy({
+        humanViews,
+        agentSessions,
+        topClip: {
+          humanViews: humanByClip.get(top.id) ?? 0,
+          completedPct,
+          dropOffMs,
+          agentBreakdown,
+        },
+      }),
+    });
+    console.log(`Sent monthly-recap for ${owner} to ${to}`);
+  } finally {
+    await sql.end();
+  }
+}
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/corpus/templates/clips/scripts/send-test-emails.ts

@@ -0,0 +1,60 @@
+/**
+ * One-off: send the two new Clips transactional emails to a real inbox so the
+ * rendering can be eyeballed in a mail client. Sample data only — this never
+ * touches the job queue or real recordings.
+ *
+ *   pnpm script send-test-emails --to someone@example.com
+ */
+
+import { getEmailProvider, isEmailConfigured } from "@agent-native/core/server";
+
+import { sendClipsTransactionalEmail } from "../server/lib/transactional-email-templates.js";
+
+function argValue(args: string[], name: string): string | undefined {
+  const index = args.indexOf(`--${name}`);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+export default async function main(args: string[]): Promise<void> {
+  const to = argValue(args, "to");
+  if (!to) throw new Error("--to <email> is required");
+
+  if (!(await isEmailConfigured())) {
+    throw new Error(
+      "No email provider configured; set SENDGRID_API_KEY or RESEND_API_KEY.",
+    );
+  }
+  console.log(`Provider: ${await getEmailProvider()}`);
+
+  await sendClipsTransactionalEmail({
+    kind: "first-agent-view",
+    to,
+    recordingId: "demo-agent-view",
+    title: "Deploy walkthrough",
+    agentName: "Claude",
+  });
+  console.log(`Sent first-agent-view to ${to}`);
+
+  await sendClipsTransactionalEmail({
+    kind: "monthly-recap",
+    to,
+    month: "2026-07",
+    humanViews: 9,
+    agentSessions: 4,
+    topClip: {
+      recordingId: "demo-recap-top",
+      title: "Deploy walkthrough",
+      thumbnailUrl: null,
+      durationMs: 252_000,
+      recordedAt: "2026-07-12T00:00:00.000Z",
+      humanViews: 9,
+      agentSessions: 4,
+    },
+    copy: {
+      heroLine: "9 people watched your clip. 4 agents read it.",
+      agentBreakdown: "3 from Claude · 1 from ChatGPT",
+      completionNote: "71% average completion · most stopped at 4:12",
+    },
+  });
+  console.log(`Sent monthly-recap to ${to}`);
+}

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

@@ -414,7 +414,11 @@ export const recordingAgentViews = table(
     recordingId: text("recording_id").notNull(),
     // sha256 of user-agent + request IP. Never stores the raw IP.
     agentKey: text("agent_key").notNull(),
+    // Null when nothing named the agent — distinct from a self-declared name.
     agentLabel: text("agent_label"),
+    // Raw (truncated) user-agent, kept so an unnamed agent stays identifiable
+    // and new AGENT_LABELS patterns come from real traffic, not guesses.
+    userAgent: text("user_agent"),
     // Time bucket that collapses one agent's burst of context/transcript/frame
     // polls into a single view.
     viewSessionId: text("view_session_id").notNull(),

package/corpus/templates/clips/server/jobs/transactional-emails.ts

@@ -18,6 +18,13 @@ import {
 } from "drizzle-orm";
 
 import { getDb, schema } from "../db/index.js";
+import {
+  computeMonthlyRecap,
+  listOwnersWithMonthlyAudience,
+  previousRecapMonth,
+  recapMonthRange,
+  type MonthlyRecap,
+} from "../lib/recap-metrics.js";
 import { ownerEmailMatches } from "../lib/recordings.js";
 import {
   AI_DISPATCH_STALE_MS,
@@ -26,6 +33,7 @@ import {
   type TransactionalEmailJob,
 } from "../lib/transactional-email-store.js";
 import {
+  composeRecapCopy,
   sendClipsTransactionalEmail,
   type ClipsTransactionalEmailInput,
 } from "../lib/transactional-email-templates.js";
@@ -36,6 +44,7 @@ const RECONCILIATION_WRITE_CONCURRENCY = 8;
 const RECIPIENT_SHARE_BATCH_SIZE = 2;
 const DELIVERY_BATCH_SIZE = 25;
 const REMINDER_DELAY_MS = 48 * 60 * 60 * 1000;
+const RECAP_SEND_HOUR_UTC = 14;
 const SENDING_LEASE_MS = 2 * 60 * 1000;
 const MAX_ATTEMPTS = 3;
 const RETRY_BASE_DELAY_MS = 60_000;
@@ -73,6 +82,17 @@ type FirstViewCandidate = CountedView & {
   ownerEmail: string;
 };
 
+type AgentView = {
+  id: string;
+  recordingId: string;
+  agentLabel: string | null;
+  firstSeenAt: string;
+};
+
+type AgentViewCandidate = AgentView & {
+  ownerEmail: string;
+};
+
 type ReconciliationCursor = {
   createdAt: string;
   id: string;
@@ -109,6 +129,7 @@ export type TransactionalEmailStore = Pick<
   | "transitionSending"
   | "updateReconciliationCursor"
   | "enqueueOrConvergeFirstImport"
+  | "readJob"
 >;
 
 export interface TransactionalEmailRepository {
@@ -133,6 +154,15 @@ export interface TransactionalEmailRepository {
     cursor: ReconciliationCursor | null,
     limit: number,
   ): Promise<FirstViewCandidate[]>;
+  listAgentViews(
+    enabledAt: string,
+    cursor: ReconciliationCursor | null,
+    limit: number,
+  ): Promise<AgentViewCandidate[]>;
+  getFirstOwnerAgentView(
+    ownerEmail: string,
+    enabledAt: string,
+  ): Promise<AgentView | null>;
   listReadyImports(
     enabledAt: string,
     cursor: ReconciliationCursor | null,
@@ -164,6 +194,11 @@ export interface TransactionalEmailRepository {
     recipient: string,
     enabledAt: string,
   ): Promise<boolean>;
+  listOwnersWithMonthlyAudience(month: string): Promise<string[]>;
+  computeMonthlyRecap(
+    ownerEmail: string,
+    month: string,
+  ): Promise<MonthlyRecap | null>;
 }
 
 export interface TransactionalEmailWorkerDependencies {
@@ -372,6 +407,69 @@ function defaultRepository(): TransactionalEmailRepository {
         )
         .limit(limit);
     },
+    async listAgentViews(enabledAt, cursor, limit) {
+      return db
+        .select({
+          id: schema.recordingAgentViews.id,
+          recordingId: schema.recordingAgentViews.recordingId,
+          agentLabel: schema.recordingAgentViews.agentLabel,
+          firstSeenAt: schema.recordingAgentViews.firstSeenAt,
+          ownerEmail: schema.recordings.ownerEmail,
+        })
+        .from(schema.recordingAgentViews)
+        .innerJoin(
+          schema.recordings,
+          eq(schema.recordings.id, schema.recordingAgentViews.recordingId),
+        )
+        .where(
+          and(
+            gte(schema.recordingAgentViews.firstSeenAt, enabledAt),
+            cursor
+              ? or(
+                  gt(schema.recordingAgentViews.firstSeenAt, cursor.createdAt),
+                  and(
+                    eq(
+                      schema.recordingAgentViews.firstSeenAt,
+                      cursor.createdAt,
+                    ),
+                    gt(schema.recordingAgentViews.id, cursor.id),
+                  ),
+                )
+              : undefined,
+          ),
+        )
+        .orderBy(
+          asc(schema.recordingAgentViews.firstSeenAt),
+          asc(schema.recordingAgentViews.id),
+        )
+        .limit(limit);
+    },
+    async getFirstOwnerAgentView(ownerEmail, enabledAt) {
+      const [view] = await db
+        .select({
+          id: schema.recordingAgentViews.id,
+          recordingId: schema.recordingAgentViews.recordingId,
+          agentLabel: schema.recordingAgentViews.agentLabel,
+          firstSeenAt: schema.recordingAgentViews.firstSeenAt,
+        })
+        .from(schema.recordingAgentViews)
+        .innerJoin(
+          schema.recordings,
+          eq(schema.recordings.id, schema.recordingAgentViews.recordingId),
+        )
+        .where(
+          and(
+            ownerEmailMatches(schema.recordings.ownerEmail, ownerEmail),
+            gte(schema.recordingAgentViews.firstSeenAt, enabledAt),
+          ),
+        )
+        .orderBy(
+          asc(schema.recordingAgentViews.firstSeenAt),
+          asc(schema.recordingAgentViews.id),
+        )
+        .limit(1);
+      return view ?? null;
+    },
     async listReadyImports(enabledAt, cursor, limit) {
       return db
         .select({
@@ -524,6 +622,8 @@ function defaultRepository(): TransactionalEmailRepository {
         .limit(1);
       return view ?? null;
     },
+    listOwnersWithMonthlyAudience,
+    computeMonthlyRecap,
     async isFirstImport(recording, recipient, enabledAt) {
       if (!isImportedRecording(recording)) return false;
       const imports = await db
@@ -700,6 +800,41 @@ async function reconcileFirstViews(
   };
 }
 
+async function reconcileFirstAgentViews(
+  repository: TransactionalEmailRepository,
+  store: TransactionalEmailStore,
+  enabledAt: string,
+  cursor: ReconciliationCursor | null,
+  limit: number,
+): Promise<{ enqueued: number; nextCursor: ReconciliationCursor | null }> {
+  const page = await repository.listAgentViews(enabledAt, cursor, limit);
+  let enqueued = 0;
+  for (const candidate of page) {
+    const ownerEmail = normalizedEmail(candidate.ownerEmail);
+    if (!ownerEmail || isSuppressedTransactionalRecipient(ownerEmail)) continue;
+    const firstAgentView = await repository.getFirstOwnerAgentView(
+      ownerEmail,
+      enabledAt,
+    );
+    if (!firstAgentView || firstAgentView.id !== candidate.id) continue;
+    const result = await store.enqueue(`first-agent-view:${ownerEmail}`, {
+      type: "first-agent-view",
+      recipient: ownerEmail,
+      recordingIds: [candidate.recordingId],
+      requestedBy: ownerEmail,
+    });
+    if (result.created) enqueued += 1;
+  }
+  const lastView = page[page.length - 1];
+  return {
+    enqueued,
+    nextCursor:
+      page.length >= limit && lastView
+        ? { createdAt: lastView.firstSeenAt, id: lastView.id }
+        : null,
+  };
+}
+
 async function reconcileFirstImports(
   repository: TransactionalEmailRepository,
   store: TransactionalEmailStore,
@@ -732,6 +867,49 @@ async function reconcileFirstImports(
   };
 }
 
+/**
+ * Recaps close on the UTC month boundary but wait until `RECAP_SEND_HOUR_UTC`
+ * on the 1st so they land mid-morning in the Americas rather than at midnight.
+ * A month is only ever enqueued once per owner, so a late first run of the day
+ * still sends rather than skipping the month.
+ */
+async function reconcileMonthlyRecaps(
+  repository: TransactionalEmailRepository,
+  store: TransactionalEmailStore,
+  enabledAt: string,
+  now: Date,
+): Promise<number> {
+  if (now.getUTCHours() < RECAP_SEND_HOUR_UTC) return 0;
+  const month = previousRecapMonth(now);
+  // Never recap a month that closed before transactional email was switched
+  // on. A month still open at that point does get a recap: the audience it
+  // reports is the owner's own, and skipping it would cost them a full month.
+  if (recapMonthRange(month).endAt <= enabledAt) return 0;
+
+  let enqueued = 0;
+  for (const ownerEmail of await repository.listOwnersWithMonthlyAudience(
+    month,
+  )) {
+    const recipient = normalizedEmail(ownerEmail);
+    if (!recipient || isSuppressedTransactionalRecipient(recipient)) continue;
+    const logicalKey = `monthly-recap:${recipient}:${month}`;
+    // Checked before the analytics work: this pass reruns every minute for the
+    // rest of the month, and recomputing a recap already queued is pure waste.
+    if (await store.readJob(logicalKey)) continue;
+    const recap = await repository.computeMonthlyRecap(recipient, month);
+    if (!recap) continue;
+    const result = await store.enqueue(logicalKey, {
+      type: "monthly-recap",
+      recipient,
+      recordingIds: [recap.topClip.recordingId],
+      requestedBy: recipient,
+      month,
+    });
+    if (result.created) enqueued += 1;
+  }
+  return enqueued;
+}
+
 async function makeSendInput(
   job: TransactionalEmailJob,
   repository: TransactionalEmailRepository,
@@ -739,6 +917,45 @@ async function makeSendInput(
 ): Promise<ClipsTransactionalEmailInput | null> {
   const recipient = normalizedEmail(job.recipient);
   if (!recipient || isSuppressedTransactionalRecipient(recipient)) return null;
+
+  if (job.type === "monthly-recap") {
+    // Ranked again at send time instead of trusting the queued clip: a month
+    // whose top clip was trashed or overtaken still deserves its recap, and
+    // the analytics already exclude clips the owner can no longer open.
+    if (!job.month) return null;
+    const recap = await repository.computeMonthlyRecap(recipient, job.month);
+    if (!recap) return null;
+    return {
+      kind: "monthly-recap",
+      to: recipient,
+      month: job.month,
+      humanViews: recap.humanViews,
+      agentSessions: recap.agentSessions,
+      topClip: {
+        recordingId: recap.topClip.recordingId,
+        title: recap.topClip.title,
+        thumbnailUrl: recap.topClip.thumbnailUrl,
+        durationMs: recap.topClip.durationMs,
+        recordedAt: recap.topClip.recordedAt,
+        humanViews: recap.topClip.humanViews,
+        agentSessions: recap.topClip.agentSessions,
+      },
+      copy: composeRecapCopy({
+        humanViews: recap.humanViews,
+        agentSessions: recap.agentSessions,
+        topClip: {
+          humanViews: recap.topClip.humanViews,
+          completedPct: recap.topClip.completedPct,
+          dropOffMs: recap.topClip.dropOffMs,
+          agentBreakdown: recap.topClip.agentBreakdown.map((entry) => ({
+            agentLabel: entry.agentLabel,
+            sessions: entry.sessions,
+          })),
+        },
+      }),
+    };
+  }
+
   const recordings = await Promise.all(
     job.recordingIds.map((recordingId) => repository.getRecording(recordingId)),
   );
@@ -788,6 +1005,24 @@ async function makeSendInput(
     };
   }
 
+  if (job.type === "first-agent-view") {
+    if (normalizedEmail(recordings[0].ownerEmail) !== recipient) return null;
+    const firstAgentView = await repository.getFirstOwnerAgentView(
+      recipient,
+      enabledAt,
+    );
+    if (!firstAgentView || firstAgentView.recordingId !== recordings[0].id) {
+      return null;
+    }
+    return {
+      kind: "first-agent-view",
+      to: recipient,
+      recordingId: recordings[0].id,
+      title: recordings[0].title,
+      agentName: firstAgentView.agentLabel,
+    };
+  }
+
   if (job.type === "first-import") {
     if (
       normalizedEmail(recordings[0].ownerEmail) !== recipient ||
@@ -889,6 +1124,18 @@ export async function runTransactionalEmailsOnce(
       "firstViewCursor",
       firstViews.nextCursor,
     );
+    const firstAgentViews = await reconcileFirstAgentViews(
+      repository,
+      store,
+      config.enabledAt,
+      config.firstAgentViewCursor ?? null,
+      reconciliationLimit,
+    );
+    result.enqueued += firstAgentViews.enqueued;
+    await store.updateReconciliationCursor(
+      "firstAgentViewCursor",
+      firstAgentViews.nextCursor,
+    );
     const firstImports = await reconcileFirstImports(
       repository,
       store,
@@ -902,6 +1149,13 @@ export async function runTransactionalEmailsOnce(
       firstImports.nextCursor,
     );
 
+    result.enqueued += await reconcileMonthlyRecaps(
+      repository,
+      store,
+      config.enabledAt,
+      currentTime,
+    );
+
     const jobs = await store.listJobs();
     const warn = dependencies.warn ?? console.warn;
     for (const job of jobs) {
@@ -921,7 +1175,9 @@ export async function runTransactionalEmailsOnce(
         (job) =>
           job.state === "pending" &&
           (job.type === "first-view" ||
+            job.type === "first-agent-view" ||
             job.type === "first-import" ||
+            job.type === "monthly-recap" ||
             job.type === "unviewed-reminder"),
       ),
       (job) => store.transition(job.logicalKey, ["pending"], "ready"),