@agent-native/core 0.139.0 → 0.141.0

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

@@ -1,61 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

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

package/dist/email-catalog/authorize.js

@@ -1,10 +0,0 @@
-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

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

@@ -1,57 +0,0 @@
-/**
- * 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.
- */
-export interface RecordEmailSendArgs {
-    templateId?: string;
-    app?: string;
-    recipient: string;
-    sender: string;
-    subject: string;
-    status: "sent" | "failed";
-    error?: string;
-    provider: string;
-}
-/**
- * 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 declare function recordEmailSend(args: RecordEmailSendArgs): Promise<void>;
-export interface EmailSendStats {
-    templateId: string;
-    sent: number;
-    failed: number;
-    lastSentAt: number | null;
-}
-/**
- * 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 declare function getEmailSendStats(since: number, app: string): Promise<EmailSendStats[]>;
-export interface EmailLogEntry {
-    id: string;
-    templateId: string | null;
-    app: string | null;
-    recipient: string;
-    sender: string;
-    subject: string;
-    status: string;
-    error: string | null;
-    provider: string;
-    createdAt: number;
-}
-/** Most recent sends for one app, newest first, optionally filtered to one template. */
-export declare function listEmailLog(options: {
-    app: string;
-    templateId?: string;
-    limit?: number;
-}): Promise<EmailLogEntry[]>;
-//# sourceMappingURL=log.d.ts.map

package/dist/email-catalog/log.js

@@ -1,117 +0,0 @@
-/**
- * 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 { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
-let _initPromise;
-async function ensureTable() {
-    if (!_initPromise) {
-        _initPromise = (async () => {
-            const { EMAIL_LOG_CREATE_SQL, EMAIL_LOG_TEMPLATE_INDEX_SQL } = await import("./schema.js");
-            // 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;
-            await ensureTableExists("email_log", createSql);
-            await ensureIndexExists("email_log_template_created_idx", EMAIL_LOG_TEMPLATE_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();
-        await getDbExec().execute({
-            sql: `INSERT INTO email_log
-        (id, template_id, app, recipient, sender, subject, status, error, provider, created_at)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-            args: [
-                randomUUID(),
-                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) {
-    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 app = ? AND template_id IS NOT NULL AND created_at >= ?
-      GROUP BY template_id`,
-        args: [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 app = ? AND template_id = ?`
-        : `WHERE app = ?`;
-    const args = options.templateId
-        ? [options.app, options.templateId, limit]
-        : [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),
-    }));
-}
-//# sourceMappingURL=log.js.map

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

@@ -1,34 +0,0 @@
-/**
- * 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): 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;
-    limit?: number;
-}): Promise<ProviderMetricsResult<EmailActivityEntry[]>>;
-//# sourceMappingURL=provider-metrics.d.ts.map

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

@@ -1,165 +0,0 @@
-/**
- * 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";
-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) {
-    if (!templateIds.length)
-        return { available: true, data: [] };
-    const sendgrid = await activeSendGrid();
-    if (!sendgrid.available)
-        return sendgrid;
-    const end = Date.now();
-    const start = end - windowDays * 24 * 60 * 60 * 1000;
-    const requested = new Set(templateIds);
-    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: 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) {
-    const sendgrid = await activeSendGrid();
-    if (!sendgrid.available)
-        return sendgrid;
-    const limit = Math.min(Math.max(options.limit ?? 50, 1), 1000);
-    const safe = options.templateId.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),
-        };
-    }
-}
-//# sourceMappingURL=provider-metrics.js.map

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

@@ -1,79 +0,0 @@
-/**
- * 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;
-//# sourceMappingURL=registry.d.ts.map

package/dist/email-catalog/registry.js

@@ -1,71 +0,0 @@
-/**
- * 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();
-}
-//# sourceMappingURL=registry.js.map