@dbx-tools/email 0.9.5 → 0.9.7

package/package.json

@@ -28,11 +28,11 @@
   },
   "dependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/appkit": "^0.9.5",
-    "@dbx-tools/core": "^0.9.5",
-    "@dbx-tools/shared-core": "^0.9.5",
-    "@dbx-tools/shared-email": "^0.9.5",
-    "@dbx-tools/shared-email-template": "^0.9.5",
+    "@dbx-tools/appkit": "^0.9.7",
+    "@dbx-tools/core": "^0.9.7",
+    "@dbx-tools/shared-core": "^0.9.7",
+    "@dbx-tools/shared-email": "^0.9.7",
+    "@dbx-tools/shared-email-template": "^0.9.7",
     "@mastra/core": "1.71.0",
     "@react-email/render": "^2.1.0",
     "nodemailer": "^7.0.13",
@@ -53,7 +53,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.5",
+  "version": "0.9.7",
   "types": "./lib/index.d.ts",
   "type": "module",
   "exports": {
@@ -66,6 +66,7 @@
   "files": [
     "index.ts",
     "src",
+    "exports.ts",
     "lib"
   ],
   "dbxToolsConfig": {

package/src/config.ts

@@ -26,7 +26,7 @@
  */
 import { resolve } from "node:path";
 import { ConfigurationError, ValidationError, type BasePluginConfig } from "@databricks/appkit";
-import { config as coreConfig } from "@dbx-tools/core";
+import { configUtils } from "@dbx-tools/core";
 import { object } from "@dbx-tools/shared-core";
 import type { JSONSchema7 } from "json-schema";
 import { defaultEmailBrand, type EmailBrand } from "./brand.ts";
@@ -272,13 +272,15 @@ export const EMAIL_CONFIG_SCHEMA: JSONSchema7 = {
 /** Parse the `SMTP_SECURE` env / config flag, defaulting by port. */
 function resolveSecure(flag: boolean | undefined, port: number): boolean {
   return (
-    coreConfig.boolean(flag, "SMTP_SECURE", coreConfig.ENV_ONLY) ?? port === IMPLICIT_TLS_SMTP_PORT
+    configUtils.boolean(flag, "SMTP_SECURE", configUtils.ENV_ONLY) ??
+    port === IMPLICIT_TLS_SMTP_PORT
   );
 }
 
 /** Parse the `EMAIL_SENDER_POLICY` env / config value, defaulting to deny-by-default. */
 function resolveSenderPolicy(policy: SenderPolicy | undefined): SenderPolicy {
-  const raw = policy ?? coreConfig.text("EMAIL_SENDER_POLICY", coreConfig.ENV_ONLY)?.toLowerCase();
+  const raw =
+    policy ?? configUtils.text("EMAIL_SENDER_POLICY", configUtils.ENV_ONLY)?.toLowerCase();
   if (raw === "unrestricted") return "unrestricted";
   if (raw === undefined || raw === "" || raw === "allowlist") return "allowlist";
   throw ValidationError.invalidValue("senderPolicy", raw, '"allowlist" or "unrestricted"');
@@ -311,7 +313,7 @@ function impliedSenderPatterns(sender: {
 
 /** Whether `EMAIL_OUTBOX_MODE` explicitly opts into the file/outbox fallback. */
 function isOutboxModeEnabled(): boolean {
-  return coreConfig.boolean(undefined, "EMAIL_OUTBOX_MODE", coreConfig.ENV_ONLY) ?? false;
+  return configUtils.boolean(undefined, "EMAIL_OUTBOX_MODE", configUtils.ENV_ONLY) ?? false;
 }
 
 const SMTP_REQUIRED_FIELDS = ["SMTP_HOST", "SMTP_USER", "SMTP_PASSWORD"] as const;
@@ -347,15 +349,19 @@ function missingSmtpFields(
  */
 export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmailConfig {
   const smtp = config.smtp ?? {};
-  const host = coreConfig.string(smtp.host, "SMTP_HOST", coreConfig.ENV_ONLY);
-  const user = coreConfig.string(smtp.user, "SMTP_USER", coreConfig.ENV_ONLY);
-  const pass = coreConfig.string(smtp.password, "SMTP_PASSWORD", coreConfig.ENV_ONLY);
-  const domain = coreConfig.string(config.domain, "EMAIL_DOMAIN", coreConfig.ENV_ONLY);
-  const from = coreConfig.string(config.from, "EMAIL_FROM", coreConfig.ENV_ONLY);
-  const systemFrom = coreConfig.string(config.systemFrom, "EMAIL_SYSTEM_FROM", coreConfig.ENV_ONLY);
+  const host = configUtils.string(smtp.host, "SMTP_HOST", configUtils.ENV_ONLY);
+  const user = configUtils.string(smtp.user, "SMTP_USER", configUtils.ENV_ONLY);
+  const pass = configUtils.string(smtp.password, "SMTP_PASSWORD", configUtils.ENV_ONLY);
+  const domain = configUtils.string(config.domain, "EMAIL_DOMAIN", configUtils.ENV_ONLY);
+  const from = configUtils.string(config.from, "EMAIL_FROM", configUtils.ENV_ONLY);
+  const systemFrom = configUtils.string(
+    config.systemFrom,
+    "EMAIL_SYSTEM_FROM",
+    configUtils.ENV_ONLY,
+  );
   const senderPolicy = resolveSenderPolicy(config.senderPolicy);
   const configuredSenders = parseAllowedSenders(
-    config.allowedSenders ?? coreConfig.text("EMAIL_ALLOWED_SENDERS", coreConfig.ENV_ONLY),
+    config.allowedSenders ?? configUtils.text("EMAIL_ALLOWED_SENDERS", configUtils.ENV_ONLY),
   );
   const allowedSenders =
     configuredSenders.length > 0 || senderPolicy === "unrestricted"
@@ -384,7 +390,7 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
         "Set EMAIL_DOMAIN to derive <user-local-part>@<domain> (and no-reply@<domain> for system mail), or EMAIL_FROM for a fixed address.",
       );
     }
-    const port = coreConfig.port(smtp.port, "SMTP_PORT", DEFAULT_SMTP_PORT, coreConfig.ENV_ONLY);
+    const port = configUtils.port(smtp.port, "SMTP_PORT", DEFAULT_SMTP_PORT, configUtils.ENV_ONLY);
     return {
       mode: "smtp",
       host: host!,
@@ -403,7 +409,7 @@ export function resolveEmailConfig(config: EmailPluginConfig = {}): ResolvedEmai
   }
 
   const outDir = resolve(
-    coreConfig.string(config.outDir, "EMAIL_OUTBOX_DIR", coreConfig.ENV_ONLY) ??
+    configUtils.string(config.outDir, "EMAIL_OUTBOX_DIR", configUtils.ENV_ONLY) ??
       resolve(process.cwd(), "tmp"),
   );
   return { mode: "file", outDir, ...sender };

package/src/email-html.ts

@@ -1,11 +1,11 @@
 /** Node rendering adapters for the shared React Email document. @module */
-import { string } from "@dbx-tools/shared-core";
+import { stringUtils } from "@dbx-tools/shared-core";
 import { EmailDocument, type EmailDocumentProps } from "@dbx-tools/shared-email-template";
 import { render } from "@react-email/render";
 import { createElement } from "react";
 
 /** Escape HTML-significant characters (re-exported from shared-core). */
-export const escapeHtml = string.escapeHtml;
+export const escapeHtml = stringUtils.escapeHtml;
 
 /** Options accepted by the shared React Email document. */
 export type EmailHtmlOptions = EmailDocumentProps;

package/src/outbox.ts

@@ -15,7 +15,7 @@
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { string } from "@dbx-tools/shared-core";
+import { stringUtils } from "@dbx-tools/shared-core";
 import type { EmailMessage } from "@dbx-tools/shared-email";
 import type { EmailBrand } from "./brand.ts";
 import { renderEmailHtml, type EmailHtmlOptions } from "./email-html.ts";
@@ -28,7 +28,7 @@ const SUBJECT_SLUG_MAX_LENGTH = 48;
 
 /** Filesystem-safe slug of the subject for the file name. */
 function subjectSlug(subject: string): string {
-  return string.toSlugWithOptions({ maxLength: SUBJECT_SLUG_MAX_LENGTH }, subject) || "email";
+  return stringUtils.toSlugWithOptions({ maxLength: SUBJECT_SLUG_MAX_LENGTH }, subject) || "email";
 }
 
 /** The envelope rows shown above the body in the preview file. */

package/src/plugin.ts

@@ -29,7 +29,6 @@ import {
   ConnectionError,
   ExecutionError,
   getExecutionContext,
-  Plugin,
   toPlugin,
   ValidationError,
   type AppKitError,
@@ -37,16 +36,9 @@ import {
   type IAppRouter,
   type PluginManifest,
 } from "@databricks/appkit";
-import {
-  defineTool,
-  executeFromRegistry,
-  toolsFromRegistry,
-  type AgentToolDefinition,
-  type ToolProvider,
-  type ToolRegistry,
-} from "@databricks/appkit/beta";
-import { brand as appkitBrand } from "@dbx-tools/appkit";
-import { log, string, token } from "@dbx-tools/shared-core";
+import { defineTool, type ToolRegistry } from "@databricks/appkit/beta";
+import { brandContext, ToolRegistryPlugin } from "@dbx-tools/appkit";
+import { log, stringUtils, token } from "@dbx-tools/shared-core";
 import {
   email as sharedEmail,
   type EmailMessage,
@@ -82,12 +74,12 @@ const logger = log.logger("email");
  * @example
  * ```ts
  * import { createApp, server } from "@databricks/appkit";
- * import { plugin as emailPlugin } from "@dbx-tools/email";
+ * import { email } from "@dbx-tools/email";
  *
  * await createApp({
  *   plugins: [
  *     server(),
- *     emailPlugin.email({
+ *     email({
  *       smtp: { host: "smtp.example.com", user: "apikey", password: process.env.SMTP_KEY },
  *       domain: "mail.example.com",
  *     }),
@@ -95,7 +87,7 @@ const logger = log.logger("email");
  * });
  * ```
  */
-export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvider {
+export class EmailPlugin extends ToolRegistryPlugin<EmailPluginConfig> {
   static manifest = {
     name: "email",
     displayName: "Email",
@@ -121,7 +113,7 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
    * against the same schema first, but re-parsing is what gives the body typed
    * arguments instead of `unknown`.
    */
-  private readonly tools: ToolRegistry = {
+  protected readonly toolRegistry: ToolRegistry = {
     [SEND_TOOL]: defineTool({
       description: SEND_EMAIL_DESCRIPTION,
       schema: sharedEmail.emailMessageSchema,
@@ -146,7 +138,7 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
   override async setup(): Promise<void> {
     const { transporter, config } = getEmailRuntime({
       ...this.config,
-      brand: this.config.brand ?? emailBrandFromContext(appkitBrand.getBrandContext()),
+      brand: this.config.brand ?? emailBrandFromContext(brandContext.getBrandContext()),
     });
     setEmailExecutor((fn, settings) => this.execute(fn, settings));
     const policy = {
@@ -230,7 +222,7 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
       method: "get",
       path: SENDERS_ROUTE,
       handler: async (req, res) => {
-        const oboToken = string.trimToNull(req.header(token.ACCESS_TOKEN_HEADER));
+        const oboToken = stringUtils.trimToNull(req.header(token.ACCESS_TOKEN_HEADER));
         const scoped = oboToken === null ? this : this.asUser(req);
         const result = await scoped.executeListSenders();
         if (!result.ok) {
@@ -263,20 +255,6 @@ export class EmailPlugin extends Plugin<EmailPluginConfig> implements ToolProvid
     };
   }
 
-  /** AppKit `ToolProvider`: the tool definitions offered to an agent. */
-  getAgentTools(): AgentToolDefinition[] {
-    return toolsFromRegistry(this.tools);
-  }
-
-  /**
-   * AppKit `ToolProvider`: run one tool call. Arguments are validated against
-   * the tool's schema first, and a validation failure comes back as an
-   * LLM-friendly string so the model can correct itself on the next turn.
-   */
-  async executeAgentTool(name: string, args: unknown, signal?: AbortSignal): Promise<unknown> {
-    return executeFromRegistry(this.tools, name, args, signal);
-  }
-
   /**
    * Send one message, resolving the sender for the caller in scope when
    * `from` is not pinned. The interceptor chain is applied inside
@@ -362,15 +340,15 @@ function unwrap<T>(result: ExecutionResult<T>): T {
  * @example
  * ```ts
  * import { createApp, server } from "@databricks/appkit";
- * import { brand, plugin as emailPlugin } from "@dbx-tools/email";
+ * import { defaultEmailBrand, email } from "@dbx-tools/email";
  *
  * await createApp({
  *   plugins: [
  *     server(),
- *     emailPlugin.email({
+ *     email({
  *       domain: "mail.example.com",
  *       allowedSenders: ["*@mail.example.com"],
- *       brand: brand.defaultEmailBrand,
+ *       brand: defaultEmailBrand,
  *     }),
  *   ],
  * });

package/src/sender.ts

@@ -28,7 +28,7 @@
  */
 
 import { ConfigurationError, ValidationError } from "@databricks/appkit";
-import { log, net, string } from "@dbx-tools/shared-core";
+import { log, net, stringUtils } from "@dbx-tools/shared-core";
 
 import type { ResolvedEmailConfig, ResolvedSender } from "./config.ts";
 
@@ -132,11 +132,11 @@ type SenderSource = Pick<ResolvedSender, "systemFrom" | "domain" | "from">;
  * result into the sender allow-list before any send happens.
  */
 export function systemSenderAddress(source: SenderSource): string | undefined {
-  const explicit = string.trimToNull(source.systemFrom);
+  const explicit = stringUtils.trimToNull(source.systemFrom);
   if (explicit) return explicit;
-  const domain = string.trimToNull(source.domain);
+  const domain = stringUtils.trimToNull(source.domain);
   if (domain) return `${SYSTEM_SENDER_LOCAL_PART}@${domain}`;
-  return string.trimToNull(source.from) ?? undefined;
+  return stringUtils.trimToNull(source.from) ?? undefined;
 }
 
 /**
@@ -166,7 +166,7 @@ export function resolveSenderAddress(
   config: ResolvedEmailConfig,
   userEmail: string | undefined,
 ): string {
-  const email = string.trimToNull(userEmail);
+  const email = stringUtils.trimToNull(userEmail);
   if (!email) return resolveSystemSenderAddress(config);
   if (config.from) return config.from;
   if (config.domain) return deriveSenderAddress(email, config.domain);

package/src/tool.ts

@@ -18,7 +18,7 @@
  */
 
 import { getExecutionContext } from "@databricks/appkit";
-import { log, string } from "@dbx-tools/shared-core";
+import { log, stringUtils } from "@dbx-tools/shared-core";
 import { email } from "@dbx-tools/shared-email";
 import { createTool, type ToolAction } from "@mastra/core/tools";
 import { resolveSenderAddress } from "./sender.ts";
@@ -31,7 +31,7 @@ const logger = log.logger("email/tool/send-email");
  * {@link emailTool} and the AppKit `email.send` tool so both agents get the
  * same guidance about approval and scope.
  */
-export const SEND_EMAIL_DESCRIPTION = string.toDescription(`
+export const SEND_EMAIL_DESCRIPTION = stringUtils.toDescription(`
   Send an email on the user's behalf. Pass one or more recipient
   addresses (with optional cc / bcc and file attachments), a subject,
   and a body; the configured approval policy runs before it goes out.

package/src/transport.ts

@@ -22,12 +22,8 @@
  * @module
  */
 
-import {
-  ConfigurationError,
-  ExecutionError,
-  ValidationError,
-  type ExecutionResult,
-} from "@databricks/appkit";
+import { ConfigurationError, ValidationError, type ExecutionResult } from "@databricks/appkit";
+import { pluginExecution } from "@dbx-tools/appkit";
 import { execution, log } from "@dbx-tools/shared-core";
 import type { EmailAttachment, EmailMessage, EmailResult } from "@dbx-tools/shared-email";
 import nodemailer, { type SendMailOptions, type Transporter } from "nodemailer";
@@ -146,23 +142,14 @@ export async function executeWrite<T>(
   signal?: AbortSignal,
 ): Promise<T> {
   const { execute } = getEmailRuntime();
-  return execution.run({
+  return pluginExecution.runPluginExecution({
+    plugin: "email",
+    logger,
     operation,
     settings,
     execute,
     fn,
     signal,
-    canceled: ExecutionError.canceled,
-    failed: (failure) => {
-      logger.warn("execution-failed", {
-        operation: failure.operation,
-        status: failure.status,
-        error: failure.message,
-      });
-      return new ExecutionError(`email: ${failure.operation} failed`, {
-        context: { operation: failure.operation, status: failure.status },
-      });
-    },
   });
 }