@agent-native/core 0.138.0 → 0.139.0

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7638
+- template files: 7654

package/corpus/templates/analytics/server/lib/dashboard-report.ts

@@ -18,6 +18,7 @@ import {
   type DashboardReportCaptureOutcome,
   type DashboardReportSubscription,
 } from "./dashboard-report-subscriptions";
+import { ANALYTICS_DASHBOARD_REPORT_EMAIL_ID } from "./emails";
 
 const DATE_FILTER_TYPES: ReadonlySet<FilterType> = new Set([
   "date",
@@ -326,6 +327,7 @@ export async function sendDashboardReportSubscription(
         ? { attachments: rendered.attachments }
         : {}),
       timeoutMs: emailTimeoutMs,
+      templateId: ANALYTICS_DASHBOARD_REPORT_EMAIL_ID,
     });
   }
 

package/corpus/templates/analytics/server/lib/emails.ts

@@ -0,0 +1,51 @@
+/**
+ * Catalog entries for the transactional emails Analytics sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+import { emailStrong, renderEmail } from "@agent-native/core/server";
+
+export const ANALYTICS_DASHBOARD_REPORT_EMAIL_ID = "analytics.dashboard-report";
+
+let registered = false;
+
+export function registerAnalyticsEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: ANALYTICS_DASHBOARD_REPORT_EMAIL_ID,
+    name: "Scheduled dashboard report",
+    trigger:
+      "A dashboard report subscription comes due and at least one panel produced usable data. A run where every queried panel failed throws instead of mailing, and a degraded run is skipped when the subscription asks for complete reports only.",
+    recipientLabel: "Subscription recipients",
+    recipient:
+      "The normalized recipient list stored on the subscription. One email per address, all carrying the same rendered snapshot.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    // The real renderer runs every panel query and rasterizes charts, so it
+    // cannot back a preview that must stay offline. This shows the frame a
+    // recipient sees; the panel body is whatever that run produced.
+    preview: () => ({
+      subject: "Daily dashboard: Growth overview — 3/4/2025",
+      ...renderEmail({
+        preheader: "Your daily Growth overview report is ready.",
+        heading: "Daily dashboard: Growth overview",
+        paragraphs: [
+          `This report renders each panel of ${emailStrong("Growth overview")} as of the run time, with charts drawn server-side and attached inline.`,
+          "Panels that could not be queried are called out in place rather than dropped, so a partial report never reads as a complete one.",
+        ],
+        cta: {
+          label: "Open dashboard",
+          url: "https://example.com/dashboards/dash_sample",
+        },
+        footer:
+          "You received this because you are on the recipient list for this dashboard report.",
+      }),
+    }),
+  });
+}

package/corpus/templates/analytics/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerAnalyticsEmails } from "../lib/emails";
+
+export default function registerTransactionalEmails(): void {
+  registerAnalyticsEmails();
+}

package/corpus/templates/calendar/server/lib/booking-emails.ts

@@ -11,6 +11,12 @@ import {
   DEFAULT_BOOKING_TIMEZONE,
   safeBookingTimeZone,
 } from "./booking-timezone.js";
+import {
+  CALENDAR_BOOKING_CANCELLED_EMAIL_ID,
+  CALENDAR_BOOKING_CANCELLED_HOST_EMAIL_ID,
+  CALENDAR_BOOKING_CONFIRMED_EMAIL_ID,
+  CALENDAR_BOOKING_RECEIVED_EMAIL_ID,
+} from "./emails.js";
 
 function stripCrlf(value: string | undefined): string {
   return (value ?? "").replace(/[\r\n]+/g, " ").trim();
@@ -57,6 +63,128 @@ async function sendBestEffort(
   }
 }
 
+export function renderBookingConfirmedEmail({
+  title,
+  when,
+  host,
+  manageUrl,
+  meetingLink,
+}: {
+  title: string;
+  when: string;
+  host: string;
+  manageUrl: string;
+  meetingLink?: string | null;
+}) {
+  const paragraphs = [
+    `You're booked for ${emailStrong(title)} with ${emailStrong(host)}.`,
+    `Time: ${emailStrong(when)}.`,
+  ];
+  if (meetingLink) {
+    paragraphs.push(`Meeting link: ${emailLink("Join meeting", meetingLink)}.`);
+  }
+
+  return {
+    subject: `Confirmed: ${title}`,
+    ...renderEmail({
+      preheader: `You're booked for ${title} on ${when}.`,
+      heading: "Your meeting is booked",
+      paragraphs,
+      cta: { label: "Manage booking", url: manageUrl },
+      footer:
+        "Use the manage link if you need to cancel or reschedule this meeting.",
+    }),
+  };
+}
+
+export function renderBookingReceivedEmail({
+  title,
+  when,
+  attendeeName,
+  attendee,
+  manageUrl,
+  meetingLink,
+}: {
+  title: string;
+  when: string;
+  attendeeName: string;
+  attendee: string;
+  manageUrl: string;
+  meetingLink?: string | null;
+}) {
+  return {
+    subject: `New booking: ${title}`,
+    ...renderEmail({
+      preheader: `${attendeeName} booked ${title} on ${when}.`,
+      heading: "New booking",
+      paragraphs: [
+        `${emailStrong(attendeeName)} booked ${emailStrong(title)}.`,
+        `Time: ${emailStrong(when)}.`,
+        `Guest: ${emailStrong(attendee)}.`,
+        ...(meetingLink
+          ? [`Meeting link: ${emailLink("Join meeting", meetingLink)}.`]
+          : []),
+      ],
+      cta: { label: "View booking", url: manageUrl },
+      footer: "This booking was created from your calendar booking link.",
+    }),
+  };
+}
+
+export function renderBookingCancelledEmail({
+  title,
+  when,
+  host,
+  bookAgainUrl,
+}: {
+  title: string;
+  when: string;
+  host: string;
+  bookAgainUrl?: string;
+}) {
+  return {
+    subject: `Cancelled: ${title}`,
+    ...renderEmail({
+      preheader: `${title} on ${when} was cancelled.`,
+      heading: "Your meeting was cancelled",
+      paragraphs: [
+        `${emailStrong(title)} with ${emailStrong(host || "the host")} has been cancelled.`,
+        `Original time: ${emailStrong(when)}.`,
+      ],
+      cta: bookAgainUrl
+        ? { label: "Book another time", url: bookAgainUrl }
+        : undefined,
+      footer: "If this was unexpected, contact the meeting host.",
+    }),
+  };
+}
+
+export function renderBookingCancelledHostEmail({
+  title,
+  when,
+  attendeeName,
+  attendee,
+}: {
+  title: string;
+  when: string;
+  attendeeName: string;
+  attendee: string;
+}) {
+  return {
+    subject: `Cancelled booking: ${title}`,
+    ...renderEmail({
+      preheader: `${attendeeName}'s booking for ${title} was cancelled.`,
+      heading: "Booking cancelled",
+      paragraphs: [
+        `${emailStrong(attendeeName)}'s booking for ${emailStrong(title)} was cancelled.`,
+        `Original time: ${emailStrong(when)}.`,
+        `Guest: ${emailStrong(attendee)}.`,
+      ],
+      footer: "No further action is needed.",
+    }),
+  };
+}
+
 export async function sendBookingConfirmationEmails({
   booking,
   hostEmail,
@@ -74,54 +202,31 @@ export async function sendBookingConfirmationEmails({
   const attendee = stripCrlf(booking.email);
   const attendeeName = stripCrlf(booking.name) || "there";
 
-  const attendeeParagraphs = [
-    `You're booked for ${emailStrong(title)} with ${emailStrong(host)}.`,
-    `Time: ${emailStrong(when)}.`,
-  ];
-  if (booking.meetingLink) {
-    attendeeParagraphs.push(
-      `Meeting link: ${emailLink("Join meeting", booking.meetingLink)}.`,
-    );
-  }
-
-  const attendeeEmail = renderEmail({
-    preheader: `You're booked for ${title} on ${when}.`,
-    heading: "Your meeting is booked",
-    paragraphs: attendeeParagraphs,
-    cta: { label: "Manage booking", url: manageUrl },
-    footer:
-      "Use the manage link if you need to cancel or reschedule this meeting.",
-  });
-
   await sendBestEffort("attendee confirmation", {
     to: attendee,
-    subject: `Confirmed: ${title}`,
-    html: attendeeEmail.html,
-    text: attendeeEmail.text,
+    ...renderBookingConfirmedEmail({
+      title,
+      when,
+      host,
+      manageUrl,
+      meetingLink: booking.meetingLink,
+    }),
     replyTo: host,
-  });
-
-  const hostEmailMessage = renderEmail({
-    preheader: `${attendeeName} booked ${title} on ${when}.`,
-    heading: "New booking",
-    paragraphs: [
-      `${emailStrong(attendeeName)} booked ${emailStrong(title)}.`,
-      `Time: ${emailStrong(when)}.`,
-      `Guest: ${emailStrong(attendee)}.`,
-      ...(booking.meetingLink
-        ? [`Meeting link: ${emailLink("Join meeting", booking.meetingLink)}.`]
-        : []),
-    ],
-    cta: { label: "View booking", url: manageUrl },
-    footer: "This booking was created from your calendar booking link.",
+    templateId: CALENDAR_BOOKING_CONFIRMED_EMAIL_ID,
   });
 
   await sendBestEffort("host notification", {
     to: host,
-    subject: `New booking: ${title}`,
-    html: hostEmailMessage.html,
-    text: hostEmailMessage.text,
+    ...renderBookingReceivedEmail({
+      title,
+      when,
+      attendeeName,
+      attendee,
+      manageUrl,
+      meetingLink: booking.meetingLink,
+    }),
     replyTo: attendee,
+    templateId: CALENDAR_BOOKING_RECEIVED_EMAIL_ID,
   });
 }
 
@@ -142,45 +247,24 @@ export async function sendBookingCancellationEmails({
   const attendee = stripCrlf(booking.email);
   const attendeeName = stripCrlf(booking.name) || "The guest";
 
-  const attendeeEmail = renderEmail({
-    preheader: `${title} on ${when} was cancelled.`,
-    heading: "Your meeting was cancelled",
-    paragraphs: [
-      `${emailStrong(title)} with ${emailStrong(host || "the host")} has been cancelled.`,
-      `Original time: ${emailStrong(when)}.`,
-    ],
-    cta: bookAgainUrl
-      ? { label: "Book another time", url: bookAgainUrl }
-      : undefined,
-    footer: "If this was unexpected, contact the meeting host.",
-  });
-
   await sendBestEffort("attendee cancellation", {
     to: attendee,
-    subject: `Cancelled: ${title}`,
-    html: attendeeEmail.html,
-    text: attendeeEmail.text,
+    ...renderBookingCancelledEmail({ title, when, host, bookAgainUrl }),
     replyTo: host || undefined,
+    templateId: CALENDAR_BOOKING_CANCELLED_EMAIL_ID,
   });
 
   if (!host) return;
 
-  const hostEmailMessage = renderEmail({
-    preheader: `${attendeeName}'s booking for ${title} was cancelled.`,
-    heading: "Booking cancelled",
-    paragraphs: [
-      `${emailStrong(attendeeName)}'s booking for ${emailStrong(title)} was cancelled.`,
-      `Original time: ${emailStrong(when)}.`,
-      `Guest: ${emailStrong(attendee)}.`,
-    ],
-    footer: "No further action is needed.",
-  });
-
   await sendBestEffort("host cancellation notification", {
     to: host,
-    subject: `Cancelled booking: ${title}`,
-    html: hostEmailMessage.html,
-    text: hostEmailMessage.text,
+    ...renderBookingCancelledHostEmail({
+      title,
+      when,
+      attendeeName,
+      attendee,
+    }),
     replyTo: attendee,
+    templateId: CALENDAR_BOOKING_CANCELLED_HOST_EMAIL_ID,
   });
 }

package/corpus/templates/calendar/server/lib/emails.ts

@@ -0,0 +1,167 @@
+/**
+ * Catalog entries for the transactional emails Calendar sends.
+ *
+ * Registered from `server/plugins/transactional-emails.ts` so Dispatch can list
+ * and preview them without the app having sent anything yet.
+ */
+
+import { defineTransactionalEmail } from "@agent-native/core/email-catalog";
+
+import {
+  renderBookingCancelledEmail,
+  renderBookingCancelledHostEmail,
+  renderBookingConfirmedEmail,
+  renderBookingReceivedEmail,
+} from "./booking-emails.js";
+import { renderEventGuestNote } from "./event-guest-notifications.js";
+
+/** Obviously-fake sample data — these render in a preview pane, never send. */
+const SAMPLE_TITLE = "Intro call";
+const SAMPLE_WHEN = "Tuesday, March 4, 2025, 10:00 AM - 10:30 AM PST";
+const SAMPLE_HOST = "dana.hill@example.com";
+const SAMPLE_GUEST = "sam.rivera@example.com";
+const SAMPLE_GUEST_NAME = "Sam Rivera";
+const SAMPLE_MANAGE_URL = "https://example.com/book/dana/manage/sample-token";
+const SAMPLE_BOOK_AGAIN_URL = "https://example.com/book/dana/intro-call";
+const SAMPLE_MEETING_LINK = "https://meet.example.com/sample-intro-call";
+
+export const CALENDAR_BOOKING_CONFIRMED_EMAIL_ID = "calendar.booking-confirmed";
+export const CALENDAR_BOOKING_RECEIVED_EMAIL_ID = "calendar.booking-received";
+export const CALENDAR_BOOKING_CANCELLED_EMAIL_ID = "calendar.booking-cancelled";
+export const CALENDAR_BOOKING_CANCELLED_HOST_EMAIL_ID =
+  "calendar.booking-cancelled-host";
+export const CALENDAR_EVENT_UPDATE_NOTE_EMAIL_ID = "calendar.event-update-note";
+export const CALENDAR_EVENT_CANCELLATION_NOTE_EMAIL_ID =
+  "calendar.event-cancellation-note";
+
+let registered = false;
+
+export function registerCalendarEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: CALENDAR_BOOKING_CONFIRMED_EMAIL_ID,
+    name: "Booking confirmed (guest)",
+    trigger:
+      "A guest completes a booking on a public `/book/{username}/{slug}` page and the booking row is created.",
+    recipientLabel: "Booking guest",
+    recipient:
+      "The email address the guest typed into the booking form (`booking.email`).",
+    senderLabel: "Default, reply-to host",
+    sender:
+      "The configured EMAIL_FROM, with reply-to set to the booking link owner's address.",
+    preview: () =>
+      renderBookingConfirmedEmail({
+        title: SAMPLE_TITLE,
+        when: SAMPLE_WHEN,
+        host: SAMPLE_HOST,
+        manageUrl: SAMPLE_MANAGE_URL,
+        meetingLink: SAMPLE_MEETING_LINK,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CALENDAR_BOOKING_RECEIVED_EMAIL_ID,
+    name: "New booking (host)",
+    trigger:
+      "Sent alongside the guest confirmation, immediately after a public booking is created.",
+    recipientLabel: "Booking link owner",
+    recipient:
+      "The owner of the booking link, looked up from the link's slug at send time.",
+    senderLabel: "Default, reply-to guest",
+    sender:
+      "The configured EMAIL_FROM, with reply-to set to the guest so the host can reply directly.",
+    preview: () =>
+      renderBookingReceivedEmail({
+        title: SAMPLE_TITLE,
+        when: SAMPLE_WHEN,
+        attendeeName: SAMPLE_GUEST_NAME,
+        attendee: SAMPLE_GUEST,
+        manageUrl: SAMPLE_MANAGE_URL,
+        meetingLink: SAMPLE_MEETING_LINK,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CALENDAR_BOOKING_CANCELLED_EMAIL_ID,
+    name: "Booking cancelled (guest)",
+    trigger:
+      "A booking that was not already cancelled is cancelled, either by the guest through the manage/cancel token link or by someone with access to the booking link.",
+    recipientLabel: "Booking guest",
+    recipient: "The guest address stored on the booking row.",
+    senderLabel: "Default, reply-to host",
+    sender:
+      "The configured EMAIL_FROM, with reply-to set to the host when a host address could be resolved from the link slug.",
+    preview: () =>
+      renderBookingCancelledEmail({
+        title: SAMPLE_TITLE,
+        when: SAMPLE_WHEN,
+        host: SAMPLE_HOST,
+        bookAgainUrl: SAMPLE_BOOK_AGAIN_URL,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CALENDAR_BOOKING_CANCELLED_HOST_EMAIL_ID,
+    name: "Booking cancelled (host)",
+    trigger:
+      "Sent after the guest cancellation notice, and only when a host address could be resolved from the booking link slug.",
+    recipientLabel: "Booking link owner",
+    recipient: "The booking link owner's address.",
+    senderLabel: "Default, reply-to guest",
+    sender:
+      "The configured EMAIL_FROM, with reply-to set to the guest who was booked.",
+    preview: () =>
+      renderBookingCancelledHostEmail({
+        title: SAMPLE_TITLE,
+        when: SAMPLE_WHEN,
+        attendeeName: SAMPLE_GUEST_NAME,
+        attendee: SAMPLE_GUEST,
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CALENDAR_EVENT_UPDATE_NOTE_EMAIL_ID,
+    name: "Event update note",
+    trigger:
+      "`update-event` runs with a non-empty guest notification message. Google Calendar still sends its own update invite; this carries only the organizer's note.",
+    recipientLabel: "Event attendees",
+    recipient:
+      "Every attendee on the event with a syntactically valid address, excluding the organizer's own `self` attendee row. One email per address.",
+    senderLabel: "Default, reply-to organizer",
+    sender:
+      "The configured EMAIL_FROM, with reply-to set to the organizer running the update.",
+    preview: () =>
+      renderEventGuestNote({
+        title: "Design review",
+        organizer: "Dana Hill",
+        message: "Moving this an hour later so the whole team can join.",
+        when: SAMPLE_WHEN,
+        kind: "update",
+        htmlLink: "https://calendar.example.com/event/sample",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: CALENDAR_EVENT_CANCELLATION_NOTE_EMAIL_ID,
+    name: "Event cancellation note",
+    trigger:
+      "`delete-event` runs with guest notification requested and a non-empty message. Google Calendar sends the cancellation itself; this carries only the organizer's note.",
+    recipientLabel: "Event attendees",
+    recipient:
+      "Every attendee on the deleted event with a syntactically valid address, excluding the organizer's own `self` attendee row. One email per address.",
+    senderLabel: "Default, reply-to organizer",
+    sender:
+      "The configured EMAIL_FROM, with reply-to set to the organizer running the deletion.",
+    preview: () =>
+      renderEventGuestNote({
+        title: "Design review",
+        organizer: "Dana Hill",
+        message: "Cancelling this week — we will pick it up after the launch.",
+        when: SAMPLE_WHEN,
+        kind: "cancellation",
+        appliesTo: "all events in the series",
+      }),
+  });
+}

package/corpus/templates/calendar/server/lib/event-guest-notifications.ts

@@ -6,6 +6,10 @@ import {
 } from "@agent-native/core/server";
 
 import type { CalendarEvent, DeleteEventScope } from "../../shared/api.js";
+import {
+  CALENDAR_EVENT_CANCELLATION_NOTE_EMAIL_ID,
+  CALENDAR_EVENT_UPDATE_NOTE_EMAIL_ID,
+} from "./emails.js";
 
 export interface GuestNotificationResult {
   requested: boolean;
@@ -96,6 +100,53 @@ function scopeLabel(scope: DeleteEventScope | undefined): string | undefined {
   return "this and following events";
 }
 
+export function renderEventGuestNote({
+  title,
+  organizer,
+  message,
+  when,
+  kind,
+  appliesTo,
+  htmlLink,
+}: {
+  title: string;
+  organizer: string;
+  message: string;
+  when: string;
+  kind: GuestNotificationKind;
+  appliesTo?: string;
+  htmlLink?: string | null;
+}) {
+  const heading =
+    kind === "cancellation" ? "Event cancellation note" : "Event update note";
+  const subjectPrefix =
+    kind === "cancellation" ? "Cancellation note" : "Update note";
+  const eventAction = kind === "cancellation" ? "cancelling" : "updating";
+  const paragraphs = [
+    `${emailStrong(organizer)} added this note while ${eventAction} ${emailStrong(title)}.`,
+    messageParagraph(message),
+    `When: ${emailStrong(when)}.`,
+  ];
+  if (appliesTo) {
+    paragraphs.push(`Applies to: ${emailStrong(appliesTo)}.`);
+  }
+
+  return {
+    subject: `${subjectPrefix}: ${title}`,
+    ...renderEmail({
+      preheader: `${subjectPrefix}: ${title}`,
+      heading,
+      paragraphs,
+      cta:
+        kind === "update" && htmlLink
+          ? { label: "Open in Google Calendar", url: htmlLink }
+          : undefined,
+      footer:
+        "Google Calendar sends the calendar update separately. This message carries the organizer note.",
+    }),
+  };
+}
+
 export async function sendEventGuestNotificationNote({
   event,
   organizerEmail,
@@ -138,33 +189,14 @@ export async function sendEventGuestNotificationNote({
     };
   }
 
-  const title = stripCrlf(event.title) || "Calendar event";
-  const organizer = stripCrlf(event.organizer?.displayName) || organizerEmail;
-  const heading =
-    kind === "cancellation" ? "Event cancellation note" : "Event update note";
-  const subjectPrefix =
-    kind === "cancellation" ? "Cancellation note" : "Update note";
-  const eventAction = kind === "cancellation" ? "cancelling" : "updating";
-  const paragraphs = [
-    `${emailStrong(organizer)} added this note while ${eventAction} ${emailStrong(title)}.`,
-    messageParagraph(normalizedMessage),
-    `When: ${emailStrong(formatWhen(event))}.`,
-  ];
-  const appliesTo = scopeLabel(scope);
-  if (appliesTo) {
-    paragraphs.push(`Applies to: ${emailStrong(appliesTo)}.`);
-  }
-
-  const rendered = renderEmail({
-    preheader: `${subjectPrefix}: ${title}`,
-    heading,
-    paragraphs,
-    cta:
-      kind === "update" && event.htmlLink
-        ? { label: "Open in Google Calendar", url: event.htmlLink }
-        : undefined,
-    footer:
-      "Google Calendar sends the calendar update separately. This message carries the organizer note.",
+  const rendered = renderEventGuestNote({
+    title: stripCrlf(event.title) || "Calendar event",
+    organizer: stripCrlf(event.organizer?.displayName) || organizerEmail,
+    message: normalizedMessage,
+    when: formatWhen(event),
+    kind,
+    appliesTo: scopeLabel(scope),
+    htmlLink: event.htmlLink,
   });
 
   let sentCount = 0;
@@ -174,10 +206,14 @@ export async function sendEventGuestNotificationNote({
       try {
         await sendEmail({
           to,
-          subject: `${subjectPrefix}: ${title}`,
+          subject: rendered.subject,
           html: rendered.html,
           text: rendered.text,
           replyTo: organizerEmail,
+          templateId:
+            kind === "cancellation"
+              ? CALENDAR_EVENT_CANCELLATION_NOTE_EMAIL_ID
+              : CALENDAR_EVENT_UPDATE_NOTE_EMAIL_ID,
         });
         sentCount += 1;
       } catch (error) {

package/corpus/templates/calendar/server/plugins/transactional-emails.ts

@@ -0,0 +1,5 @@
+import { registerCalendarEmails } from "../lib/emails.js";
+
+export default function registerTransactionalEmails(): void {
+  registerCalendarEmails();
+}