@agent-native/core 0.140.0 → 0.141.0

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

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

@@ -1,212 +0,0 @@
-/**
- * Drizzle schema for the transactional email send log.
- *
- * One row per `sendEmail` attempt, written by the transport itself so every
- * send is recorded regardless of which app or code path triggered it. This is
- * the durable record of "did we send it": the provider's own activity feed ages
- * out (SendGrid keeps 3 days without the extended-retention add-on), so send
- * counts and last-sent must not depend on it.
- *
- * Engagement (opens, clicks, bounces) is deliberately NOT stored here. Only the
- * provider knows it, and mirroring it would go stale the moment a recipient
- * opens an old message. Dispatch reads engagement live from the provider and
- * joins on `template_id`.
- */
-export declare const emailLog: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
-    name: "email_log";
-    schema: undefined;
-    columns: {
-        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "id";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: true;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        templateId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "template_id";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        app: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "app";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        recipient: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "recipient";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        sender: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "sender";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        subject: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "subject";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        status: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "status";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: "failed" | "sent";
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: ["sent", "failed"];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        error: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "error";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: false;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        provider: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "provider";
-            tableName: "email_log";
-            dataType: "string";
-            columnType: "SQLiteText";
-            data: string;
-            driverParam: string;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: [string, ...string[]];
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {
-            length: number;
-        }>;
-        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
-            name: "created_at";
-            tableName: "email_log";
-            dataType: "number";
-            columnType: "SQLiteInteger";
-            data: number;
-            driverParam: number;
-            notNull: true;
-            hasDefault: false;
-            isPrimaryKey: false;
-            isAutoincrement: false;
-            hasRuntimeDefault: false;
-            enumValues: undefined;
-            baseColumn: never;
-            identity: undefined;
-            generated: undefined;
-        }, {}, {}>;
-    };
-    dialect: 'sqlite';
-}>;
-export declare const EMAIL_LOG_CREATE_SQL = "CREATE TABLE IF NOT EXISTS email_log (\n  id TEXT PRIMARY KEY,\n  template_id TEXT,\n  app TEXT,\n  recipient TEXT NOT NULL,\n  sender TEXT NOT NULL,\n  subject TEXT NOT NULL,\n  status TEXT NOT NULL,\n  error TEXT,\n  provider TEXT NOT NULL,\n  created_at INTEGER NOT NULL\n)";
-export declare const EMAIL_LOG_TEMPLATE_INDEX_SQL = "CREATE INDEX IF NOT EXISTS email_log_template_created_idx\n  ON email_log (template_id, created_at)";
-//# sourceMappingURL=schema.d.ts.map

package/dist/email-catalog/schema.js

@@ -1,49 +0,0 @@
-/**
- * Drizzle schema for the transactional email send log.
- *
- * One row per `sendEmail` attempt, written by the transport itself so every
- * send is recorded regardless of which app or code path triggered it. This is
- * the durable record of "did we send it": the provider's own activity feed ages
- * out (SendGrid keeps 3 days without the extended-retention add-on), so send
- * counts and last-sent must not depend on it.
- *
- * Engagement (opens, clicks, bounces) is deliberately NOT stored here. Only the
- * provider knows it, and mirroring it would go stale the moment a recipient
- * opens an old message. Dispatch reads engagement live from the provider and
- * joins on `template_id`.
- */
-import { table, text, integer } from "../db/schema.js";
-export const emailLog = table("email_log", {
-    id: text("id").primaryKey(),
-    /** Registered transactional email id, e.g. "calendar.booking-confirmed". */
-    templateId: text("template_id"),
-    /** App slug that sent it. */
-    app: text("app"),
-    /** Recipient address. */
-    recipient: text("recipient").notNull(),
-    /** Resolved From address, after app-sender branding is applied. */
-    sender: text("sender").notNull(),
-    subject: text("subject").notNull(),
-    /** "sent" once the provider accepted it, or "failed". Never optimistic. */
-    status: text("status", { enum: ["sent", "failed"] }).notNull(),
-    /** Provider error text when status is "failed". */
-    error: text("error"),
-    /** "resend" | "sendgrid" | "dev". */
-    provider: text("provider").notNull(),
-    createdAt: integer("created_at").notNull(),
-});
-export const EMAIL_LOG_CREATE_SQL = `CREATE TABLE IF NOT EXISTS email_log (
-  id TEXT PRIMARY KEY,
-  template_id TEXT,
-  app TEXT,
-  recipient TEXT NOT NULL,
-  sender TEXT NOT NULL,
-  subject TEXT NOT NULL,
-  status TEXT NOT NULL,
-  error TEXT,
-  provider TEXT NOT NULL,
-  created_at INTEGER NOT NULL
-)`;
-export const EMAIL_LOG_TEMPLATE_INDEX_SQL = `CREATE INDEX IF NOT EXISTS email_log_template_created_idx
-  ON email_log (template_id, created_at)`;
-//# sourceMappingURL=schema.js.map

package/dist/email-catalog/system-emails.d.ts

@@ -1,14 +0,0 @@
-/**
- * Catalog entries for the framework's own system emails.
- *
- * These ship with every app rather than belonging to one, so they register
- * under the `core` app instead of the running app's slug. Importing this module
- * performs the registration; `register-system-emails.ts` is the single import
- * site so the emails appear in every app's catalog without each template
- * remembering to opt in.
- */
-export declare const CORE_INVITE_EMAIL_ID = "core.organization-invite";
-export declare const CORE_VERIFY_SIGNUP_EMAIL_ID = "core.verify-signup";
-export declare const CORE_RESET_PASSWORD_EMAIL_ID = "core.reset-password";
-export declare function registerCoreSystemEmails(): void;
-//# sourceMappingURL=system-emails.d.ts.map