@dbx-tools/shared-email 0.1.2

package/README.md

@@ -0,0 +1,64 @@
+# @dbx-tools/shared-email
+
+Browser-safe email schemas and inferred types.
+
+Import this package when a UI, Mastra tool schema, server route, or test needs
+to validate the same email payloads that
+[`@dbx-tools/node-email`](../../node/email) sends.
+
+Key features:
+
+- Shared `EmailMessage` contract for generated email drafts and direct sends.
+- Attachment schema that supports inline content, file paths, URLs, encoding,
+  and content-type hints.
+- Send-result schema for SMTP and outbox responses.
+- Sender-options schema for AppKit routes that expose allowed `From` values to
+  a browser client.
+- Model/tool-friendly schemas that avoid JSON Schema constraints known to cause
+  problems with some serving endpoints.
+
+## Validate A Drafted Message
+
+```ts
+import { email, type EmailMessage } from "@dbx-tools/shared-email";
+
+const message: EmailMessage = email.emailMessageSchema.parse({
+  to: ["alice@example.com"],
+  subject: "Report",
+  body: "# Done\nThe report is attached.",
+  attachments: [{ filename: "report.csv", content: "a,b\n1,2\n" }],
+});
+```
+
+The message schema covers recipients, subject, Markdown body, and attachments.
+Attachments can carry inline content, a local path, a URL, encoding metadata, and
+content type hints.
+
+## Validate Send Results
+
+```ts
+const result = email.emailResultSchema.parse(await sendResponse.json());
+```
+
+`emailResultSchema` is the shared shape for SMTP sends and outbox writes. Use it
+for approval UI state and test assertions.
+
+## Render Sender Choices
+
+```ts
+const senders = email.emailSendersSchema.parse(
+  await fetch("/api/email/senders").then((r) => r.json()),
+);
+```
+
+The sender schema describes the concrete `From` choices for the current user,
+the default sender, and whether the list is restricted by policy.
+
+## Module
+
+- `email` - `emailAttachmentSchema`, `emailMessageSchema`,
+  `emailResultSchema`, `emailSendersSchema`, and flat inferred types:
+  `EmailAttachment`, `EmailMessage`, `EmailResult`, and `EmailSenders`.
+
+The schemas intentionally avoid array `.min()` constraints so they can be reused
+as model/tool JSON schemas for serving endpoints that reject `minItems`.

package/index.ts

@@ -0,0 +1,6 @@
+// GENERATED by projen watch - DO NOT EDIT.
+// Regenerated from the exporting modules in ./src.
+// Hand edits are overwritten on the next watch; this file is read-only.
+
+export * as email from "./src/email";
+export type { EmailAttachment, EmailMessage, EmailResult, EmailSenders } from "./src/email";

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dbx-tools/shared-email",
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "zod": "^4.3.6",
+    "@dbx-tools/shared-core": "0.1.2"
+  },
+  "main": "index.ts",
+  "license": "UNLICENSED",
+  "version": "0.1.2",
+  "types": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./package.json": "./package.json"
+  },
+  "dbxToolsConfig": {
+    "tags": [
+      "shared"
+    ]
+  },
+  "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"pnpm exec projen\".",
+  "scripts": {
+    "build": "projen build",
+    "compile": "projen compile",
+    "default": "projen default",
+    "package": "projen package",
+    "post-compile": "projen post-compile",
+    "pre-compile": "projen pre-compile",
+    "test": "projen test",
+    "watch": "projen watch",
+    "projen": "projen"
+  }
+}

package/src/email.ts

@@ -0,0 +1,116 @@
+/**
+ * Wire-format contract for the email add-on: the email a model drafts and the
+ * result of dispatching it. Pure (zod + inferred types, no Node-only imports)
+ * so the server-side sender, the Mastra tool, and the React approval UI all
+ * validate / type against one definition.
+ *
+ * Array fields intentionally avoid `.min()` / `.nonempty()`: those emit
+ * `minItems` in the JSON schema, which some Model Serving endpoints reject
+ * ("array types do not support minItems") when the schema is forwarded as a
+ * tool definition.
+ */
+
+import { z } from "zod";
+
+/** Schema for a single file attached to an outbound email. */
+export const emailAttachmentSchema = z.object({
+  filename: z.string().describe('File name shown to the recipient (e.g. "report.pdf").'),
+  content: z
+    .string()
+    .optional()
+    .describe(
+      'Inline file content as a string. For binary data set `encoding` (e.g. "base64"). Provide this or `path`, not both.',
+    ),
+  encoding: z
+    .string()
+    .optional()
+    .describe(
+      'Encoding of `content` (e.g. "base64", "utf-8", "hex"). Defaults to utf-8 when omitted.',
+    ),
+  path: z
+    .string()
+    .optional()
+    .describe(
+      "Read the content from here instead of inlining it: a local file path, a data: URI, or an https URL. Provide this or `content`, not both.",
+    ),
+  contentType: z
+    .string()
+    .optional()
+    .describe(
+      'MIME type override (e.g. "application/pdf"). Inferred from the filename when omitted.',
+    ),
+});
+
+/** A single file attached to an {@link EmailMessage}. */
+export type EmailAttachment = z.infer<typeof emailAttachmentSchema>;
+
+/** Schema for the email a model asks to send (the tool input). */
+export const emailMessageSchema = z.object({
+  to: z
+    .array(z.string())
+    .describe(
+      'One or more recipient email addresses (e.g. ["alice@example.com", "bob@example.com"]). Provide at least one.',
+    ),
+  subject: z.string().describe("Subject line. Keep it short and specific."),
+  body: z
+    .string()
+    .describe(
+      [
+        "Email body in GitHub-Flavored Markdown; it is rendered to HTML before sending.",
+        "Use real Markdown structure: '#'/'##' headings, '-' or '1.' lists, **bold**/_italic_, '>' blockquotes, and fenced ``` code blocks.",
+        "For tabular data, emit a real Markdown table: a header row, then a '| --- | --- |' separator row, then one '| ... |' row per record.",
+        "Do NOT format with ASCII art: no '=====' or '-----' divider lines, and never hand-draw tables or bar charts with spaces, pipes, or '#'. Use the Markdown constructs above instead.",
+        "Be self-contained: the recipient has none of the chat context.",
+      ].join(" "),
+    ),
+  cc: z.array(z.string()).optional().describe("Optional CC recipient addresses (one or more)."),
+  bcc: z.array(z.string()).optional().describe("Optional BCC recipient addresses (one or more)."),
+  attachments: z
+    .array(emailAttachmentSchema)
+    .optional()
+    .describe("Optional file attachments to include with the message."),
+});
+
+/** A validated outbound email message. */
+export type EmailMessage = z.infer<typeof emailMessageSchema>;
+
+/** Schema for the dispatch result returned to the model after a send. */
+export const emailResultSchema = z.object({
+  sent: z.boolean().describe("True once the message was handed to the SMTP server."),
+  recipient: z
+    .string()
+    .describe("Echo of the `to` recipients (comma-joined) for confirmation."),
+  from: z.string().describe("The resolved sender address the message was actually sent from."),
+  messageId: z
+    .string()
+    .optional()
+    .describe("SMTP message id assigned by the server, when one was returned."),
+});
+
+/** The outcome of dispatching an {@link EmailMessage}. */
+export type EmailResult = z.infer<typeof emailResultSchema>;
+
+/**
+ * Schema for the sender options a UI can offer for the `From` address - the
+ * payload of the plugin's `GET /senders` route. When the plugin configures a
+ * sender allow-list, `senders` holds the concrete addresses the current user
+ * may send as (domain wildcards expanded against the user's local part) and
+ * `restricted` is true; a picker should require a choice from the list. When
+ * unrestricted, `senders` holds at most the single default address (if one can
+ * be resolved) and `restricted` is false, so a UI may allow free entry.
+ */
+export const emailSendersSchema = z.object({
+  senders: z
+    .array(z.string())
+    .describe("Permitted sender addresses to offer as `From` choices."),
+  defaultSender: z
+    .string()
+    .optional()
+    .describe("The address a send uses by default (first `senders` entry, if any)."),
+  restricted: z
+    .boolean()
+    .describe("True when `senders` is an enforced allow-list rather than a hint."),
+});
+
+/** Sender options for a `From` picker (see {@link emailSendersSchema}). */
+export type EmailSenders = z.infer<typeof emailSendersSchema>;

package/tsconfig.json

@@ -0,0 +1,40 @@
+// ~~ Generated by projen. To modify, edit .projenrc.js and run "pnpm exec projen".
+{
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib",
+    "alwaysStrict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "inlineSourceMap": true,
+    "inlineSources": true,
+    "lib": [
+      "ES2022",
+      "WebWorker"
+    ],
+    "module": "ESNext",
+    "noEmitOnError": false,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "strictNullChecks": true,
+    "strictPropertyInitialization": true,
+    "stripInternal": true,
+    "target": "ES2022",
+    "types": [],
+    "moduleResolution": "bundler",
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}