@agent-native/core 0.141.3 → 0.141.4

package/dist/email-catalog/log.js

@@ -0,0 +1,142 @@
+/**
+ * Durable send log for transactional emails.
+ *
+ * Written by `sendEmail` on every attempt, successful or not. Read by Dispatch
+ * to report per-email send counts and last-sent without depending on the
+ * provider's activity retention window.
+ */
+import { randomUUID } from "node:crypto";
+import { getDbExec, isPostgres } from "../db/client.js";
+import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../db/ddl-guard.js";
+import { getRequestOrgId } from "../server/request-context.js";
+let _initPromise;
+async function ensureTable() {
+    if (!_initPromise) {
+        _initPromise = (async () => {
+            const { EMAIL_LOG_CREATE_SQL, EMAIL_LOG_ORG_APP_INDEX_SQL, EMAIL_LOG_TEMPLATE_INDEX_SQL, } = await import("./schema.js");
+            const client = getDbExec();
+            // Generic INTEGER maps to BIGINT on Postgres, which millisecond
+            // timestamps need.
+            const createSql = isPostgres()
+                ? EMAIL_LOG_CREATE_SQL.replace(/\bINTEGER\b/g, "BIGINT")
+                : EMAIL_LOG_CREATE_SQL;
+            if (isPostgres()) {
+                await ensureTableExists("email_log", createSql);
+                await ensureColumnExists("email_log", "org_id", "ALTER TABLE email_log ADD COLUMN IF NOT EXISTS org_id TEXT");
+                await ensureIndexExists("email_log_template_created_idx", EMAIL_LOG_TEMPLATE_INDEX_SQL);
+                await ensureIndexExists("email_log_org_app_created_idx", EMAIL_LOG_ORG_APP_INDEX_SQL);
+                return;
+            }
+            await client.execute(createSql);
+            try {
+                await client.execute("ALTER TABLE email_log ADD COLUMN org_id TEXT");
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (!/already exists|duplicate column name/i.test(message)) {
+                    throw error;
+                }
+                console.info("[agent-native:email] email_log.org_id already exists during local bootstrap");
+            }
+            await client.execute(EMAIL_LOG_TEMPLATE_INDEX_SQL);
+            await client.execute(EMAIL_LOG_ORG_APP_INDEX_SQL);
+        })().catch((error) => {
+            // Don't memoize a failed bootstrap — the next send should retry rather
+            // than log nothing forever.
+            _initPromise = undefined;
+            throw error;
+        });
+    }
+    return _initPromise;
+}
+/**
+ * Append one send record.
+ *
+ * Callers treat logging as best-effort: a logging failure must not turn a
+ * delivered email into a thrown send. The failure is surfaced on the console
+ * rather than swallowed, so a persistently broken log is visible instead of
+ * quietly producing an empty activity view.
+ */
+export async function recordEmailSend(args) {
+    try {
+        await ensureTable();
+        const orgId = args.orgId ?? getRequestOrgId() ?? null;
+        await getDbExec().execute({
+            sql: `INSERT INTO email_log
+        (id, org_id, template_id, app, recipient, sender, subject, status, error, provider, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [
+                randomUUID(),
+                orgId,
+                args.templateId ?? null,
+                args.app ?? null,
+                args.recipient,
+                args.sender,
+                args.subject,
+                args.status,
+                args.error ?? null,
+                args.provider,
+                Date.now(),
+            ],
+        });
+    }
+    catch (error) {
+        console.error("[agent-native:email] failed to record send", error);
+    }
+}
+/**
+ * Per-template send counts and last-sent, for sends at or after `since`.
+ * Templates with no rows are absent from the result — callers distinguish
+ * "never sent" from "sent zero times in window" by that absence.
+ */
+export async function getEmailSendStats(since, app, orgId) {
+    await ensureTable();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT template_id,
+        SUM(CASE WHEN status = 'sent' THEN 1 ELSE 0 END) AS sent,
+        SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS failed,
+        MAX(CASE WHEN status = 'sent' THEN created_at END) AS last_sent_at
+      FROM email_log
+      WHERE org_id = ? AND app = ? AND template_id IS NOT NULL AND created_at >= ?
+      GROUP BY template_id`,
+        args: [orgId, app, since],
+    });
+    return rows.map((row) => ({
+        templateId: String(row.template_id),
+        sent: Number(row.sent ?? 0),
+        failed: Number(row.failed ?? 0),
+        lastSentAt: row.last_sent_at == null ? null : Number(row.last_sent_at),
+    }));
+}
+/** Most recent sends for one app, newest first, optionally filtered to one template. */
+export async function listEmailLog(options) {
+    await ensureTable();
+    const limit = Math.min(Math.max(options.limit ?? 100, 1), 500);
+    const where = options.templateId
+        ? `WHERE org_id = ? AND app = ? AND template_id = ?`
+        : `WHERE org_id = ? AND app = ?`;
+    const args = options.templateId
+        ? [options.orgId, options.app, options.templateId, limit]
+        : [options.orgId, options.app, limit];
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT id, template_id, app, recipient, sender, subject, status, error, provider, created_at
+      FROM email_log ${where} ORDER BY created_at DESC LIMIT ?`,
+        args,
+    });
+    return rows.map((row) => ({
+        id: String(row.id),
+        templateId: row.template_id == null ? null : String(row.template_id),
+        app: row.app == null ? null : String(row.app),
+        recipient: String(row.recipient),
+        sender: String(row.sender),
+        subject: String(row.subject),
+        status: String(row.status),
+        error: row.error == null ? null : String(row.error),
+        provider: String(row.provider),
+        createdAt: Number(row.created_at),
+    }));
+}
+/** Provider category that is safe to query for one organization only. */
+export function getScopedEmailProviderCategory(templateId, orgId) {
+    return `${templateId}::org::${encodeURIComponent(orgId)}`;
+}

package/dist/email-catalog/provider-metrics.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Engagement metrics and activity for registered transactional emails, read
+ * from the active provider in the current app's request context.
+ */
+export type ProviderMetricsResult<T> = {
+    available: true;
+    data: T;
+} | {
+    available: false;
+    reason: string;
+};
+export interface EmailEngagement {
+    templateId: string;
+    delivered: number;
+    uniqueOpens: number;
+    uniqueClicks: number;
+    openRate: number | null;
+}
+export declare function fetchEmailEngagement(templateIds: string[], windowDays: number, orgId?: string): Promise<ProviderMetricsResult<EmailEngagement[]>>;
+export interface EmailActivityEntry {
+    msgId: string;
+    toEmail: string;
+    fromEmail: string;
+    subject: string;
+    status: string;
+    opensCount: number;
+    clicksCount: number;
+    lastEventTime: string;
+}
+export declare function fetchEmailActivity(options: {
+    templateId: string;
+    orgId?: string;
+    limit?: number;
+}): Promise<ProviderMetricsResult<EmailActivityEntry[]>>;

package/dist/email-catalog/provider-metrics.js

@@ -0,0 +1,182 @@
+/**
+ * Engagement metrics and activity for registered transactional emails, read
+ * from the active provider in the current app's request context.
+ */
+import { z } from "zod";
+import { resolveSecret } from "../server/credential-provider.js";
+import { getEmailProvider } from "../server/email.js";
+import { getScopedEmailProviderCategory } from "./log.js";
+const SENDGRID_API = "https://api.sendgrid.com/v3";
+const SENDGRID_PAGE_SIZE = 1000;
+const SENDGRID_MAX_PAGES = 10;
+const categoryMetricsSchema = z
+    .object({
+    delivered: z.number().default(0),
+    unique_opens: z.number().default(0),
+    unique_clicks: z.number().default(0),
+})
+    .passthrough();
+const categoryStatSchema = z
+    .object({
+    name: z.string(),
+    metrics: categoryMetricsSchema.default(() => ({
+        delivered: 0,
+        unique_opens: 0,
+        unique_clicks: 0,
+    })),
+})
+    .passthrough();
+const categorySumsSchema = z.object({
+    stats: z.array(categoryStatSchema).default([]),
+});
+const activitySchema = z.object({
+    messages: z
+        .array(z
+        .object({
+        msg_id: z.string().default(""),
+        to_email: z.string().default(""),
+        from_email: z.string().default(""),
+        subject: z.string().default(""),
+        status: z.string().default(""),
+        opens_count: z.coerce.number().default(0),
+        clicks_count: z.coerce.number().default(0),
+        last_event_time: z.string().default(""),
+    })
+        .passthrough())
+        .default([]),
+});
+async function activeSendGrid() {
+    const provider = await getEmailProvider();
+    if (provider === "resend") {
+        return {
+            available: false,
+            reason: "Email delivery uses Resend, so SendGrid metrics do not describe the active transport.",
+        };
+    }
+    if (provider !== "sendgrid") {
+        return {
+            available: false,
+            reason: "No email provider is configured, so provider metrics cannot be read.",
+        };
+    }
+    const key = await resolveSecret("SENDGRID_API_KEY");
+    if (!key) {
+        return {
+            available: false,
+            reason: "SendGrid is the active email transport, but SENDGRID_API_KEY could not be resolved.",
+        };
+    }
+    return { available: true, key };
+}
+function isoDate(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+async function sendgridGet(key, path, params) {
+    const url = new URL(`${SENDGRID_API}${path}`);
+    for (const [name, value] of params)
+        url.searchParams.append(name, value);
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${key}` },
+    });
+    if (!res.ok) {
+        const body = await res
+            .text()
+            .catch((cause) => `<error body unreadable: ${cause}>`);
+        throw new Error(`SendGrid ${res.status} on ${path}: ${body.slice(0, 300)}`);
+    }
+    return res.json();
+}
+export async function fetchEmailEngagement(templateIds, windowDays, orgId) {
+    if (!templateIds.length)
+        return { available: true, data: [] };
+    if (!orgId) {
+        return {
+            available: false,
+            reason: "Organization context is required for provider email metrics.",
+        };
+    }
+    const sendgrid = await activeSendGrid();
+    if (!sendgrid.available)
+        return sendgrid;
+    const end = Date.now();
+    const start = end - windowDays * 24 * 60 * 60 * 1000;
+    const categoryToTemplate = new Map(templateIds.map((templateId) => [
+        getScopedEmailProviderCategory(templateId, orgId),
+        templateId,
+    ]));
+    const requested = new Set(categoryToTemplate.keys());
+    const data = [];
+    try {
+        for (let page = 0; page < SENDGRID_MAX_PAGES; page += 1) {
+            const payload = categorySumsSchema.parse(await sendgridGet(sendgrid.key, "/categories/stats/sums", [
+                ["start_date", isoDate(start)],
+                ["end_date", isoDate(end)],
+                ["limit", String(SENDGRID_PAGE_SIZE)],
+                ["offset", String(page * SENDGRID_PAGE_SIZE)],
+            ]));
+            for (const entry of payload.stats) {
+                if (!requested.has(entry.name))
+                    continue;
+                requested.delete(entry.name);
+                const delivered = entry.metrics.delivered;
+                const uniqueOpens = entry.metrics.unique_opens;
+                data.push({
+                    templateId: categoryToTemplate.get(entry.name),
+                    delivered,
+                    uniqueOpens,
+                    uniqueClicks: entry.metrics.unique_clicks,
+                    openRate: delivered > 0 ? Math.min(uniqueOpens / delivered, 1) : null,
+                });
+            }
+            if (requested.size === 0 || payload.stats.length < SENDGRID_PAGE_SIZE) {
+                break;
+            }
+        }
+        return { available: true, data };
+    }
+    catch (error) {
+        return {
+            available: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function fetchEmailActivity(options) {
+    if (!options.orgId) {
+        return {
+            available: false,
+            reason: "Organization context is required for provider email activity.",
+        };
+    }
+    const sendgrid = await activeSendGrid();
+    if (!sendgrid.available)
+        return sendgrid;
+    const limit = Math.min(Math.max(options.limit ?? 50, 1), 1000);
+    const category = getScopedEmailProviderCategory(options.templateId, options.orgId);
+    const safe = category.replace(/["\\]/g, "");
+    try {
+        const payload = activitySchema.parse(await sendgridGet(sendgrid.key, "/messages", [
+            ["limit", String(limit)],
+            ["query", `category="${safe}"`],
+        ]));
+        return {
+            available: true,
+            data: payload.messages.map((message) => ({
+                msgId: message.msg_id,
+                toEmail: message.to_email,
+                fromEmail: message.from_email,
+                subject: message.subject,
+                status: message.status,
+                opensCount: message.opens_count,
+                clicksCount: message.clicks_count,
+                lastEventTime: message.last_event_time,
+            })),
+        };
+    }
+    catch (error) {
+        return {
+            available: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Registry of the transactional emails an app can send.
+ *
+ * An app declares each email it sends here so the workspace can answer, without
+ * reading the app's source: what emails exist, what makes one send, who it goes
+ * to, who it comes from, and what it looks like. Dispatch aggregates these
+ * across every mounted app via the `list-transactional-emails` action.
+ *
+ * Declare emails next to the code that sends them, then import that module from
+ * a server plugin so registration happens at startup:
+ *
+ *   defineTransactionalEmail({
+ *     id: "calendar.booking-confirmed",
+ *     name: "Booking confirmed",
+ *     trigger: "A guest completes a booking on a public scheduling page.",
+ *     recipient: "The guest email captured on the booking form.",
+ *     sender: "EMAIL_FROM, with reply-to set to the event host.",
+ *     preview: () => renderBookingConfirmedEmail(SAMPLE_BOOKING),
+ *   });
+ *
+ * The `id` doubles as the SendGrid category `sendEmail` tags the message with,
+ * which is how per-email delivery and open metrics are attributed later.
+ */
+import type { RenderedEmailMessage } from "../server/email-templates.js";
+export interface TransactionalEmailDefinition {
+    /**
+     * Stable, globally unique id in `<app>.<email>` form, e.g.
+     * `calendar.booking-confirmed`. Used as the SendGrid category, so changing it
+     * orphans historical metrics for this email.
+     */
+    id: string;
+    /** Human-readable name, e.g. "Booking confirmed". */
+    name: string;
+    /**
+     * App slug this email belongs to. Defaults to the running app, which is
+     * correct for every app-declared email; core system emails set it explicitly.
+     */
+    app?: string;
+    /** Plain-language description of the condition that causes a send. */
+    trigger: string;
+    /** Plain-language description of how the recipient address is chosen. */
+    recipient: string;
+    /**
+     * Two-to-four word summary of the recipient for table cells, e.g.
+     * "Booking guest". The full `recipient` sentence is shown on the detail view.
+     */
+    recipientLabel: string;
+    /** Plain-language description of how From and Reply-To are chosen. */
+    sender: string;
+    /** Two-to-four word summary of the sender, e.g. "Default, reply-to host". */
+    senderLabel: string;
+    /**
+     * Render the email with representative dummy data. Must not read from the
+     * database or touch the network — previews are rendered on demand from
+     * Dispatch, for apps whose data the caller may not be able to see.
+     */
+    preview: () => RenderedEmailMessage;
+}
+/** A definition with its app resolved, as returned to callers. */
+export type RegisteredTransactionalEmail = TransactionalEmailDefinition & {
+    app: string;
+};
+/**
+ * Register a transactional email. Returns the definition so the call site can
+ * export it and reuse `id` when sending.
+ */
+export declare function defineTransactionalEmail(definition: TransactionalEmailDefinition): RegisteredTransactionalEmail;
+/** Every registered email, sorted by app then name. */
+export declare function listTransactionalEmails(): RegisteredTransactionalEmail[];
+export declare function getTransactionalEmail(id: string): RegisteredTransactionalEmail | undefined;
+/**
+ * Render one email's preview. Throws when the id is unknown or the renderer
+ * fails — a preview that silently returns an empty body would look like an
+ * email that legitimately renders blank.
+ */
+export declare function renderTransactionalEmailPreview(id: string): RenderedEmailMessage;
+/** Test seam — drops all registrations. */
+export declare function resetTransactionalEmailRegistry(): void;

package/dist/email-catalog/registry.js

@@ -0,0 +1,70 @@
+/**
+ * Registry of the transactional emails an app can send.
+ *
+ * An app declares each email it sends here so the workspace can answer, without
+ * reading the app's source: what emails exist, what makes one send, who it goes
+ * to, who it comes from, and what it looks like. Dispatch aggregates these
+ * across every mounted app via the `list-transactional-emails` action.
+ *
+ * Declare emails next to the code that sends them, then import that module from
+ * a server plugin so registration happens at startup:
+ *
+ *   defineTransactionalEmail({
+ *     id: "calendar.booking-confirmed",
+ *     name: "Booking confirmed",
+ *     trigger: "A guest completes a booking on a public scheduling page.",
+ *     recipient: "The guest email captured on the booking form.",
+ *     sender: "EMAIL_FROM, with reply-to set to the event host.",
+ *     preview: () => renderBookingConfirmedEmail(SAMPLE_BOOKING),
+ *   });
+ *
+ * The `id` doubles as the SendGrid category `sendEmail` tags the message with,
+ * which is how per-email delivery and open metrics are attributed later.
+ */
+import { getAppSlug } from "../server/app-name.js";
+const registry = new Map();
+/** Source definitions, so re-registering the same one is a no-op rather than a clash. */
+const sources = new Map();
+/**
+ * Register a transactional email. Returns the definition so the call site can
+ * export it and reuse `id` when sending.
+ */
+export function defineTransactionalEmail(definition) {
+    const existing = sources.get(definition.id);
+    if (existing && existing !== definition) {
+        // Two emails sharing an id would silently merge their metrics and make the
+        // catalog claim one exists when the other actually sent.
+        throw new Error(`Duplicate transactional email id "${definition.id}". Ids must be unique across the app.`);
+    }
+    const resolved = {
+        ...definition,
+        app: definition.app ?? getAppSlug() ?? "unknown",
+    };
+    registry.set(definition.id, resolved);
+    sources.set(definition.id, definition);
+    return resolved;
+}
+/** Every registered email, sorted by app then name. */
+export function listTransactionalEmails() {
+    return [...registry.values()].sort((a, b) => a.app.localeCompare(b.app) || a.name.localeCompare(b.name));
+}
+export function getTransactionalEmail(id) {
+    return registry.get(id);
+}
+/**
+ * Render one email's preview. Throws when the id is unknown or the renderer
+ * fails — a preview that silently returns an empty body would look like an
+ * email that legitimately renders blank.
+ */
+export function renderTransactionalEmailPreview(id) {
+    const definition = registry.get(id);
+    if (!definition) {
+        throw new Error(`Unknown transactional email "${id}".`);
+    }
+    return definition.preview();
+}
+/** Test seam — drops all registrations. */
+export function resetTransactionalEmailRegistry() {
+    registry.clear();
+    sources.clear();
+}