@agent-native/core 0.138.0 → 0.139.0

package/corpus/templates/plan/actions/request-plan-access.ts

@@ -22,6 +22,8 @@ import {
 } from "../server/lib/local-identity.js";
 import { newId, nowIso, planPath, writeEvent } from "../server/plans.js";
 
+export const PLAN_ACCESS_REQUEST_EMAIL_ID = "plan.access-request";
+
 function httpError(message: string, statusCode: number): Error {
   return Object.assign(new Error(message), { statusCode });
 }
@@ -49,6 +51,28 @@ function absolutePlanUrl(planId: string, kind: "plan" | "recap"): string {
   }
 }
 
+export function renderPlanAccessRequestEmail(input: {
+  requesterName: string;
+  requesterEmail: string;
+  planTitle: string;
+  url: string;
+}) {
+  const subject = `${input.requesterName} requested access to "${input.planTitle}"`;
+  return {
+    subject,
+    ...renderEmail({
+      preheader: subject,
+      heading: "Access request",
+      paragraphs: [
+        `${emailStrong(input.requesterName)} (${emailStrong(input.requesterEmail)}) requested access to ${emailStrong(input.planTitle)}.`,
+        "Open the plan and use Share to grant access if this request should be approved.",
+      ],
+      cta: { label: "Open plan", url: input.url },
+      footer: "You received this because you own this Agent-Native Plan.",
+    }),
+  };
+}
+
 async function notifyOwner(input: {
   planId: string;
   planKind: "plan" | "recap";
@@ -62,19 +86,16 @@ async function notifyOwner(input: {
     return false;
   }
 
-  const url = absolutePlanUrl(input.planId, input.planKind);
-  const subject = `${input.requesterName} requested access to "${input.planTitle}"`;
-  const { html, text } = renderEmail({
-    preheader: subject,
-    heading: "Access request",
-    paragraphs: [
-      `${emailStrong(input.requesterName)} (${emailStrong(input.requesterEmail)}) requested access to ${emailStrong(input.planTitle)}.`,
-      "Open the plan and use Share to grant access if this request should be approved.",
-    ],
-    cta: { label: "Open plan", url },
-    footer: "You received this because you own this Agent-Native Plan.",
+  await sendEmail({
+    ...renderPlanAccessRequestEmail({
+      requesterName: input.requesterName,
+      requesterEmail: input.requesterEmail,
+      planTitle: input.planTitle,
+      url: absolutePlanUrl(input.planId, input.planKind),
+    }),
+    to: input.ownerEmail,
+    templateId: PLAN_ACCESS_REQUEST_EMAIL_ID,
   });
-  await sendEmail({ to: input.ownerEmail, subject, html, text });
   return true;
 }
 

package/corpus/templates/plan/server/lib/comment-notifications.ts

@@ -14,6 +14,8 @@ import {
 import type { PlanBundle, PlanComment } from "../../shared/types.js";
 import { getDb, schema } from "../db/index.js";
 
+export const PLAN_COMMENT_EMAIL_ID = "plan.plan-comment";
+
 type CommentNotificationInput = {
   bundle: PlanBundle;
   insertedCommentIds: string[];
@@ -205,40 +207,64 @@ export function planCommentNotificationRecipients(input: {
   return Array.from(recipients.values());
 }
 
-async function sendPlanCommentNotification(input: {
-  recipient: NotificationRecipient;
-  comment: PlanComment;
+export function renderPlanCommentEmail(input: {
+  actor: string;
+  app: string;
   planTitle: string;
-  planId: string;
+  planUrl: string;
+  message: string;
+  isReply: boolean;
+  reason: NotificationRecipient["reason"];
 }) {
-  const actor = actorName(input.comment);
-  const app = appName();
-  const isReply = Boolean(input.comment.parentCommentId);
-  const subject = isReply
-    ? `${actor} replied to a comment on "${input.planTitle}"`
-    : `${actor} commented on "${input.planTitle}"`;
   const actionText =
-    input.recipient.reason === "mention"
+    input.reason === "mention"
       ? "mentioned you in a comment on"
-      : input.recipient.reason === "plan-owner"
+      : input.reason === "plan-owner"
         ? "left a comment on your plan"
         : "replied in a comment thread you participated in";
-  const { html, text } = renderEmail({
-    preheader: `${actor} ${actionText} on ${app}.`,
-    heading: isReply ? "New reply on your plan" : "New comment on your plan",
-    paragraphs: [
-      `${emailStrong(actor)} ${actionText} ${emailStrong(input.planTitle)}.`,
-      `Comment: "${commentExcerpt(input.comment.message)}"`,
-    ],
-    cta: { label: "Open plan", url: planUrl(input.planId) },
-    footer:
-      input.recipient.reason === "plan-owner"
-        ? "You received this because you own this plan."
-        : input.recipient.reason === "mention"
-          ? "You received this because you were mentioned in this comment."
-          : "You received this because you participated in this comment thread.",
+  return {
+    subject: input.isReply
+      ? `${input.actor} replied to a comment on "${input.planTitle}"`
+      : `${input.actor} commented on "${input.planTitle}"`,
+    ...renderEmail({
+      preheader: `${input.actor} ${actionText} on ${input.app}.`,
+      heading: input.isReply
+        ? "New reply on your plan"
+        : "New comment on your plan",
+      paragraphs: [
+        `${emailStrong(input.actor)} ${actionText} ${emailStrong(input.planTitle)}.`,
+        `Comment: "${commentExcerpt(input.message)}"`,
+      ],
+      cta: { label: "Open plan", url: input.planUrl },
+      footer:
+        input.reason === "plan-owner"
+          ? "You received this because you own this plan."
+          : input.reason === "mention"
+            ? "You received this because you were mentioned in this comment."
+            : "You received this because you participated in this comment thread.",
+    }),
+  };
+}
+
+async function sendPlanCommentNotification(input: {
+  recipient: NotificationRecipient;
+  comment: PlanComment;
+  planTitle: string;
+  planId: string;
+}) {
+  await sendEmail({
+    ...renderPlanCommentEmail({
+      actor: actorName(input.comment),
+      app: appName(),
+      planTitle: input.planTitle,
+      planUrl: planUrl(input.planId),
+      message: input.comment.message,
+      isReply: Boolean(input.comment.parentCommentId),
+      reason: input.recipient.reason,
+    }),
+    to: input.recipient.email,
+    templateId: PLAN_COMMENT_EMAIL_ID,
   });
-  await sendEmail({ to: input.recipient.email, subject, html, text });
 }
 
 export async function notifyPlanCommentRecipients({

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

@@ -0,0 +1,67 @@
+/**
+ * Catalog entries for the transactional emails Plan 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 {
+  PLAN_ACCESS_REQUEST_EMAIL_ID,
+  renderPlanAccessRequestEmail,
+} from "../../actions/request-plan-access.js";
+import {
+  PLAN_COMMENT_EMAIL_ID,
+  renderPlanCommentEmail,
+} from "./comment-notifications.js";
+
+let registered = false;
+
+export function registerPlanEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: PLAN_COMMENT_EMAIL_ID,
+    name: "Plan comment",
+    trigger:
+      "A human (never the agent) posts a comment or reply on a plan or recap. The subject changes for a reply and the body changes with why the recipient was picked; all variants send under this id.",
+    recipientLabel: "Owner, mentions, authors",
+    recipient:
+      "The plan owner, everyone mentioned in the comment, and — for a reply — every other human author in the same thread. The comment's own author, synthetic QA addresses, and the owner when the comment mentions the source author are all dropped. One email per remaining address.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderPlanCommentEmail({
+        actor: "Sam Rivera",
+        app: "Agent-Native Plan",
+        planTitle: "Checkout rewrite",
+        planUrl: "https://example.com/plans/plan_sample",
+        message: "Can we split the migration into two deploys?",
+        isReply: false,
+        reason: "plan-owner",
+      }),
+  });
+
+  defineTransactionalEmail({
+    id: PLAN_ACCESS_REQUEST_EMAIL_ID,
+    name: "Plan access request",
+    trigger:
+      "A signed-in user who cannot resolve access calls `request-plan-access` on a private plan URL. Skipped when email is not configured or the requester is the owner.",
+    recipientLabel: "Plan owner",
+    recipient:
+      "The plan's `ownerEmail` column. Anonymous public viewers and guest author identities cannot reach this path.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`, so the owner cannot reply straight to the requester.",
+    preview: () =>
+      renderPlanAccessRequestEmail({
+        requesterName: "Sam Rivera",
+        requesterEmail: "sam.rivera@example.com",
+        planTitle: "Checkout rewrite",
+        url: "https://example.com/plans/plan_sample",
+      }),
+  });
+}

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

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

package/corpus/templates/slides/server/lib/comment-notifications.ts

@@ -21,6 +21,7 @@ import { and, eq } from "drizzle-orm";
 import { getDeckUrl } from "../../actions/_app-url.js";
 import { SLIDES_USER_PREFS_KEY } from "../../shared/slides-user-prefs.js";
 import { getDb, schema } from "../db/index.js";
+import { SLIDES_DECK_COMMENT_EMAIL_ID } from "./emails.js";
 
 /**
  * `deck-missing` stays distinct from `no-recipients`: one means the deck could
@@ -99,6 +100,41 @@ async function threadParticipants(
   return rows.map((row) => row.authorEmail);
 }
 
+export function renderDeckCommentEmail({
+  actor,
+  title,
+  url,
+  content,
+  isReply,
+}: {
+  actor: string;
+  title: string;
+  url: string;
+  content: string;
+  isReply: boolean;
+}) {
+  return {
+    subject: isReply
+      ? `${actor} replied to a comment on "${title}"`
+      : `${actor} commented on "${title}"`,
+    ...renderEmail({
+      preheader: isReply
+        ? `${actor} replied to a comment on ${title}.`
+        : `${actor} commented on ${title}.`,
+      heading: isReply ? "New reply on your deck" : "New comment",
+      paragraphs: [
+        isReply
+          ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(title)}.`
+          : `${emailStrong(actor)} commented on ${emailStrong(title)}.`,
+        `"${excerpt(content)}"`,
+      ],
+      cta: { label: "Open deck", url },
+      footer:
+        "You received this because you own or participated in this thread. Turn these off in Slides settings.",
+    }),
+  };
+}
+
 export async function notifyDeckComment(input: {
   deckId: string;
   slideId: string;
@@ -153,29 +189,16 @@ async function deliverDeckCommentEmails(input: {
     preferenceKey: SLIDES_USER_PREFS_KEY,
     logLabel: LOG_LABEL,
     send: async (to) => {
-      const { html, text } = renderEmail({
-        preheader: input.isReply
-          ? `${actor} replied to a comment on ${deck.title}.`
-          : `${actor} commented on ${deck.title}.`,
-        heading: input.isReply ? "New reply on your deck" : "New comment",
-        paragraphs: [
-          input.isReply
-            ? `${emailStrong(actor)} replied in a comment thread on ${emailStrong(deck.title)}.`
-            : `${emailStrong(actor)} commented on ${emailStrong(deck.title)}.`,
-          `"${excerpt(input.content)}"`,
-        ],
-        cta: { label: "Open deck", url },
-        footer:
-          "You received this because you own or participated in this thread. Turn these off in Slides settings.",
-      });
-
       await sendEmail({
+        ...renderDeckCommentEmail({
+          actor,
+          title: deck.title,
+          url,
+          content: input.content,
+          isReply: input.isReply,
+        }),
         to,
-        subject: input.isReply
-          ? `${actor} replied to a comment on "${deck.title}"`
-          : `${actor} commented on "${deck.title}"`,
-        html,
-        text,
+        templateId: SLIDES_DECK_COMMENT_EMAIL_ID,
       });
     },
   });

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

@@ -0,0 +1,40 @@
+/**
+ * Catalog entries for the transactional emails Slides 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 { renderDeckCommentEmail } from "./comment-notifications.js";
+
+export const SLIDES_DECK_COMMENT_EMAIL_ID = "slides.deck-comment";
+
+let registered = false;
+
+export function registerSlidesEmails(): void {
+  if (registered) return;
+  registered = true;
+
+  defineTransactionalEmail({
+    id: SLIDES_DECK_COMMENT_EMAIL_ID,
+    name: "Deck comment",
+    trigger:
+      "Someone posts a comment or a thread reply on a slide. Subject and copy differ slightly for a reply; both send under this id.",
+    recipientLabel: "Deck owner and authors",
+    recipient:
+      "The deck owner, plus every prior author in the thread when the new comment is a reply. The list is re-checked against the deck's live ACL and filtered by each user's `emailNotifications` preference; the comment's own author never receives it.",
+    senderLabel: "Default sender",
+    sender:
+      "The configured default sender. This call site sets no `from`, `fromName`, `replyTo`, or `appSender`.",
+    preview: () =>
+      renderDeckCommentEmail({
+        actor: "Sam Rivera",
+        title: "Series A narrative",
+        url: "https://example.com/decks/deck_sample?slide=3",
+        content: "Slide 3 needs the updated revenue chart before Thursday.",
+        isReply: false,
+      }),
+  });
+}

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

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

package/dist/collab/routes.d.ts

@@ -41,9 +41,9 @@ export declare const postCollabUpdate: import("h3").EventHandlerWithFetch<import
  * Body: { text: string, fieldName?: string, requestSource?: string }
  */
 export declare const postCollabText: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    text?: undefined;
     ok?: undefined;
     error: string;
+    text?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/collab/struct-routes.d.ts

@@ -13,8 +13,8 @@
  * Body: { json: any, fieldName?: string, type?: "map"|"array", requestSource?: string }
  */
 export declare const postCollabJson: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
-    ok?: undefined;
     error: string;
+    ok?: undefined;
 } | {
     error?: undefined;
     ok: boolean;

package/dist/email-catalog/actions/list-email-activity.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    templateId: string;
+    limit?: unknown;
+}, import("../provider-metrics.js").ProviderMetricsResult<import("../provider-metrics.js").EmailActivityEntry[]>>;
+export default _default;
+//# sourceMappingURL=list-email-activity.d.ts.map

package/dist/email-catalog/actions/list-email-activity.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { fetchEmailActivity } from "../provider-metrics.js";
+export default defineAction({
+    description: "List recent provider activity for one registered transactional email in this app. Organization admin only.",
+    schema: z.object({
+        templateId: z.string().min(1),
+        limit: z.coerce.number().int().min(1).max(1000).default(50),
+    }),
+    http: { method: "GET" },
+    authorize: ({ templateId }) => authorizeTransactionalEmailRead([templateId]),
+    run: async ({ templateId, limit }) => fetchEmailActivity({ templateId, limit }),
+});
+//# sourceMappingURL=list-email-activity.js.map

package/dist/email-catalog/actions/list-email-engagement.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    templateIds: string[];
+    windowDays?: unknown;
+}, import("../provider-metrics.js").ProviderMetricsResult<import("../provider-metrics.js").EmailEngagement[]>>;
+export default _default;
+//# sourceMappingURL=list-email-engagement.d.ts.map

package/dist/email-catalog/actions/list-email-engagement.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { fetchEmailEngagement } from "../provider-metrics.js";
+export default defineAction({
+    description: "Read provider engagement metrics for registered transactional emails in this app. Organization admin only.",
+    schema: z.object({
+        templateIds: z.array(z.string().min(1)).max(100),
+        windowDays: z.coerce.number().int().min(1).max(365).default(30),
+    }),
+    http: { method: "POST" },
+    authorize: ({ templateIds }) => authorizeTransactionalEmailRead(templateIds),
+    run: async ({ templateIds, windowDays }) => fetchEmailEngagement(templateIds, windowDays),
+});
+//# sourceMappingURL=list-email-engagement.js.map

package/dist/email-catalog/actions/list-email-log.d.ts

@@ -0,0 +1,8 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    templateId?: string;
+    limit?: unknown;
+}, {
+    entries: import("../log.js").EmailLogEntry[];
+}>;
+export default _default;
+//# sourceMappingURL=list-email-log.d.ts.map

package/dist/email-catalog/actions/list-email-log.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getAppSlug } from "../../server/app-name.js";
+import { authorizeTransactionalEmailRead } from "../authorize.js";
+import { listEmailLog } from "../log.js";
+export default defineAction({
+    description: "List recent transactional email sends from this app, newest first, optionally filtered to one registered email id.",
+    schema: z.object({
+        templateId: z.string().optional(),
+        limit: z.coerce.number().int().min(1).max(500).default(100),
+    }),
+    http: { method: "GET" },
+    authorize: ({ templateId }) => authorizeTransactionalEmailRead(templateId ? [templateId] : []),
+    run: async ({ templateId, limit }) => ({
+        entries: await listEmailLog({
+            app: getAppSlug() ?? "unknown",
+            templateId,
+            limit,
+        }),
+    }),
+});
+//# sourceMappingURL=list-email-log.js.map

package/dist/email-catalog/actions/list-transactional-emails.d.ts

@@ -0,0 +1,23 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    windowDays?: unknown;
+}, {
+    app: string;
+    windowDays: number;
+    statsAvailable: boolean;
+    statsError: string;
+    emails: {
+        id: string;
+        app: string;
+        name: string;
+        trigger: string;
+        recipient: string;
+        recipientLabel: string;
+        sender: string;
+        senderLabel: string;
+        sent: number;
+        failed: number;
+        lastSentAt: number;
+    }[];
+}>;
+export default _default;
+//# sourceMappingURL=list-transactional-emails.d.ts.map

package/dist/email-catalog/actions/list-transactional-emails.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { getAppSlug } from "../../server/app-name.js";
+import { getEmailSendStats } from "../log.js";
+import { listTransactionalEmails } from "../registry.js";
+import { registerCoreSystemEmails } from "../system-emails.js";
+const DEFAULT_WINDOW_DAYS = 30;
+export default defineAction({
+    description: "List the transactional emails this app can send, with the trigger, recipient and sender logic for each, plus local send counts and last-sent. Engagement metrics such as open rate are not included here — they live at the email provider.",
+    schema: z.object({
+        windowDays: z.coerce
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(DEFAULT_WINDOW_DAYS)
+            .describe("How many days of send history to summarize."),
+    }),
+    http: { method: "GET" },
+    run: async ({ windowDays }) => {
+        registerCoreSystemEmails();
+        const since = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+        const app = getAppSlug() ?? "unknown";
+        const definitions = listTransactionalEmails();
+        // A failed stats read must not masquerade as "no email ever sent" — the
+        // catalog is still worth returning, but the caller has to be able to tell
+        // that the numbers are missing rather than zero.
+        let statsById = null;
+        let statsError = null;
+        try {
+            const stats = await getEmailSendStats(since, app);
+            statsById = new Map(stats.map((row) => [row.templateId, row]));
+        }
+        catch (error) {
+            statsError = error instanceof Error ? error.message : String(error);
+        }
+        return {
+            app,
+            windowDays,
+            statsAvailable: statsError === null,
+            statsError,
+            emails: definitions.map((definition) => {
+                const stats = statsById?.get(definition.id);
+                return {
+                    id: definition.id,
+                    app: definition.app,
+                    name: definition.name,
+                    trigger: definition.trigger,
+                    recipient: definition.recipient,
+                    recipientLabel: definition.recipientLabel,
+                    sender: definition.sender,
+                    senderLabel: definition.senderLabel,
+                    sent: stats?.sent ?? (statsById ? 0 : null),
+                    failed: stats?.failed ?? (statsById ? 0 : null),
+                    lastSentAt: stats?.lastSentAt ?? null,
+                };
+            }),
+        };
+    },
+});
+//# sourceMappingURL=list-transactional-emails.js.map

package/dist/email-catalog/actions/render-transactional-email-preview.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("../../action.js").ActionDefinition<{
+    id: string;
+}, {
+    id: string;
+    subject: string;
+    html: string;
+    text: string;
+}>;
+export default _default;
+//# sourceMappingURL=render-transactional-email-preview.d.ts.map

package/dist/email-catalog/actions/render-transactional-email-preview.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { defineAction } from "../../action.js";
+import { renderTransactionalEmailPreview } from "../registry.js";
+import { registerCoreSystemEmails } from "../system-emails.js";
+export default defineAction({
+    description: "Render one of this app's transactional emails with representative dummy data, returning the subject, HTML and plain-text bodies for preview.",
+    schema: z.object({
+        id: z
+            .string()
+            .describe("Registered email id, e.g. calendar.booking-confirmed."),
+    }),
+    http: { method: "GET" },
+    run: async ({ id }) => {
+        registerCoreSystemEmails();
+        const rendered = renderTransactionalEmailPreview(id);
+        return {
+            id,
+            subject: rendered.subject,
+            html: rendered.html,
+            text: rendered.text,
+        };
+    },
+});
+//# sourceMappingURL=render-transactional-email-preview.js.map

package/dist/email-catalog/authorize.d.ts

@@ -0,0 +1,2 @@
+export declare function authorizeTransactionalEmailRead(templateIds?: string[]): Promise<boolean>;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/email-catalog/authorize.js

@@ -0,0 +1,10 @@
+import { currentRequestUserIsOrgAdmin } from "../server/org-admin.js";
+import { getTransactionalEmail } from "./registry.js";
+import { registerCoreSystemEmails } from "./system-emails.js";
+export async function authorizeTransactionalEmailRead(templateIds = []) {
+    if (!(await currentRequestUserIsOrgAdmin()))
+        return false;
+    registerCoreSystemEmails();
+    return templateIds.every((id) => Boolean(getTransactionalEmail(id)));
+}
+//# sourceMappingURL=authorize.js.map