@robodev-ai/runtime 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robodev-ai/runtime",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Robodev project runtime — deploy-file classification, esbuild compile, module loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth, the socket engine, and local file storage. Shared by hosted Starbase and `robodev dev`.",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,7 @@
     "pg": "^8.16.3",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.24.6",
-    "@robodev-ai/sdk": "0.11.0"
+    "@robodev-ai/sdk": "0.11.1"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.4",

package/src/email-templates.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  escapeEmailHtml,
+  extractTemplateVars,
+  htmlToPlainText,
+  isCustomEmailSlug,
+  loadLocalEmailTemplate,
+  mergeCustomTemplateVariables,
+  renderEmailFields,
+  renderEmailTemplate,
+  resolveEmailSendInput,
+} from "./email-templates.js";
+
+test("renderEmailTemplate replaces whitespace-tolerant vars", () => {
+  assert.equal(renderEmailTemplate("Hi {{ name }}", { name: "Ada" }), "Hi Ada");
+  assert.equal(renderEmailTemplate("Hi {{name}}", { name: "Ada" }), "Hi Ada");
+  assert.equal(renderEmailTemplate("Hi {{ missing }}", {}), "Hi ");
+  assert.equal(renderEmailTemplate("Hi {{1bad}}", { "1bad": "x" }), "Hi {{1bad}}");
+});
+
+test("renderEmailTemplate HTML-escapes only in html mode", () => {
+  assert.equal(
+    renderEmailTemplate("<p>{{name}}</p>", { name: `<a>"'` }, { html: true }),
+    `<p>${escapeEmailHtml(`<a>"'`)}</p>`,
+  );
+  assert.equal(renderEmailTemplate("{{name}}", { name: "<x>" }), "<x>");
+});
+
+test("extractTemplateVars unions unique names in order", () => {
+  assert.deepEqual(extractTemplateVars("{{email}} {{name}}", "{{email}} {{link}}"), [
+    "email",
+    "name",
+    "link",
+  ]);
+});
+
+test("htmlToPlainText strips tags", () => {
+  assert.equal(htmlToPlainText("<p>Your reset code is <code>123</code>.</p>"), "Your reset code is 123 .");
+});
+
+test("resolveEmailSendInput renders catalog then applies overrides", () => {
+  const resolved = resolveEmailSendInput(
+    {
+      to: "a@b.com",
+      template: "welcome",
+      vars: { name: "Ada" },
+      subject: "Override",
+    },
+    { subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>", text: "Hello {{name}}" },
+  );
+  assert.equal(resolved.subject, "Override");
+  assert.equal(resolved.html, "<p>Hello Ada</p>");
+  assert.equal(resolved.text, "Hello Ada");
+});
+
+test("resolveEmailSendInput throws template_not_found without catalog or body", () => {
+  assert.throws(
+    () => resolveEmailSendInput({ to: "a@b.com", template: "missing" }, null),
+    (error: unknown) => error instanceof Error && error.message === "template_not_found",
+  );
+});
+
+test("loadLocalEmailTemplate reads html plus optional json", async () => {
+  const root = await mkdtemp(join(tmpdir(), "robodev-emails-"));
+  await mkdir(join(root, "robodev", "emails"), { recursive: true });
+  await writeFile(join(root, "robodev", "emails", "welcome.html"), "<p>Hi {{name}}</p>", "utf8");
+  await writeFile(
+    join(root, "robodev", "emails", "welcome.json"),
+    JSON.stringify({ subject: "Hello", text: "Hi {{name}}" }),
+    "utf8",
+  );
+  const loaded = await loadLocalEmailTemplate(root, "welcome");
+  assert.deepEqual(loaded, {
+    slug: "welcome",
+    subject: "Hello",
+    html: "<p>Hi {{name}}</p>",
+    text: "Hi {{name}}",
+  });
+  assert.equal(await loadLocalEmailTemplate(root, "missing"), null);
+});
+
+test("custom slug and variable merge rules", () => {
+  assert.equal(isCustomEmailSlug("welcome"), true);
+  assert.equal(isCustomEmailSlug("auth.welcome"), false);
+  assert.equal(isCustomEmailSlug("Welcome"), false);
+  assert.deepEqual(mergeCustomTemplateVariables(["email", "name"], ["extra", "email", "1bad"]), [
+    "email",
+    "name",
+    "extra",
+  ]);
+});
+
+test("renderEmailFields derives plaintext when text is empty", () => {
+  const rendered = renderEmailFields(
+    { subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>", text: "" },
+    { name: "Ada" },
+  );
+  assert.equal(rendered.subject, "Hi Ada");
+  assert.equal(rendered.html, "<p>Hello Ada</p>");
+  assert.equal(rendered.text, "Hello Ada");
+});

package/src/email-templates.ts

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { EmailSendInput } from "@robodev-ai/sdk";
+
+export const EMAIL_TEMPLATE_VAR_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+export const EMAIL_TEMPLATE_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const EMAIL_TEMPLATE_MAX_VARS = 32;
+export const EMAIL_TEMPLATE_MAX_VAR_NAME = 40;
+export const EMAIL_TEMPLATE_MAX_BYTES = 200 * 1024;
+export const EMAIL_TEMPLATE_MAX_SUBJECT = 200;
+export const EMAIL_TEMPLATE_MAX_CUSTOM = 40;
+export const CUSTOM_EMAIL_SLUG_RE = /^[a-z][a-z0-9-]{0,62}$/;
+
+export const SYSTEM_EMAIL_SLUGS = ["auth.welcome", "auth.magic-link", "auth.forgot-password"] as const;
+export type SystemEmailSlug = (typeof SYSTEM_EMAIL_SLUGS)[number];
+
+export type EmailTemplateKind = "system" | "custom";
+
+export type LocalEmailTemplate = {
+  slug: string;
+  subject: string;
+  html: string;
+  text: string;
+};
+
+export type EmailTemplateVars = Record<string, string | number | boolean>;
+
+export function isSystemEmailSlug(slug: string): slug is SystemEmailSlug {
+  return (SYSTEM_EMAIL_SLUGS as readonly string[]).includes(slug);
+}
+
+export function isCustomEmailSlug(slug: string): boolean {
+  return CUSTOM_EMAIL_SLUG_RE.test(slug) && !slug.startsWith("auth.");
+}
+
+export function escapeEmailHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+export function htmlToPlainText(html: string): string {
+  return html
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, " ")
+    .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function extractTemplateVars(...parts: Array<string | null | undefined>): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const part of parts) {
+    if (!part) continue;
+    const re = new RegExp(EMAIL_TEMPLATE_VAR_RE.source, "g");
+    for (const match of part.matchAll(re)) {
+      const name = match[1] ?? "";
+      if (!name || seen.has(name)) continue;
+      seen.add(name);
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+export function renderEmailTemplate(
+  template: string,
+  vars: EmailTemplateVars = {},
+  options: { html?: boolean } = {},
+): string {
+  return template.replace(EMAIL_TEMPLATE_VAR_RE, (token, name: string) => {
+    if (!Object.prototype.hasOwnProperty.call(vars, name)) return "";
+    const raw = vars[name];
+    const value = raw == null ? "" : String(raw);
+    return options.html ? escapeEmailHtml(value) : value;
+  });
+}
+
+export function renderEmailFields(
+  input: { subject: string; html: string; text?: string },
+  vars: EmailTemplateVars = {},
+): { subject: string; html: string; text: string } {
+  const html = renderEmailTemplate(input.html, vars, { html: true });
+  const textSource = input.text?.trim()
+    ? renderEmailTemplate(input.text, vars)
+    : htmlToPlainText(html);
+  return {
+    subject: renderEmailTemplate(input.subject, vars),
+    html,
+    text: textSource,
+  };
+}
+
+export function localEmailTemplatePaths(slug: string): { html: string; json: string } {
+  return {
+    html: `robodev/emails/${slug}.html`,
+    json: `robodev/emails/${slug}.json`,
+  };
+}
+
+export async function loadLocalEmailTemplate(
+  projectRoot: string,
+  slug: string,
+): Promise<LocalEmailTemplate | null> {
+  const paths = localEmailTemplatePaths(slug);
+  let html: string;
+  try {
+    html = await readFile(join(projectRoot, paths.html), "utf8");
+  } catch {
+    return null;
+  }
+  let subject = "";
+  let text = "";
+  try {
+    const raw = await readFile(join(projectRoot, paths.json), "utf8");
+    const parsed = JSON.parse(raw) as { subject?: unknown; text?: unknown };
+    if (typeof parsed.subject === "string") subject = parsed.subject;
+    if (typeof parsed.text === "string") text = parsed.text;
+  } catch {
+    /* html-only catalog row */
+  }
+  return { slug, subject, html, text };
+}
+
+export function resolveEmailSendInput(
+  input: EmailSendInput,
+  catalog: { subject: string; html: string; text?: string } | null,
+): EmailSendInput {
+  if (!input.template) return input;
+  if (!catalog) {
+    if (input.html || input.text) return input;
+    throw Object.assign(new Error("template_not_found"), { code: "template_not_found" });
+  }
+  const rendered = renderEmailFields(catalog, input.vars ?? {});
+  return {
+    ...input,
+    subject: input.subject ?? rendered.subject,
+    html: input.html ?? rendered.html,
+    text: input.text ?? rendered.text,
+  };
+}
+
+export function mergeCustomTemplateVariables(
+  extracted: readonly string[],
+  extras: readonly string[] = [],
+): string[] {
+  const names: string[] = [];
+  const seen = new Set<string>();
+  for (const name of [...extracted, ...extras]) {
+    if (!EMAIL_TEMPLATE_VAR_NAME_RE.test(name) || name.length > EMAIL_TEMPLATE_MAX_VAR_NAME) {
+      continue;
+    }
+    if (seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+    if (names.length >= EMAIL_TEMPLATE_MAX_VARS) break;
+  }
+  return names;
+}

package/src/index.ts

@@ -2,7 +2,8 @@
  * `@robodev-ai/runtime` — the project runtime shared by hosted Starbase deploys and the
  * offline `robodev dev` loop: deploy-file classification, the esbuild compile, module
  * loading, schema push, route matching, OpenAPI, handler invocation, Robodev Auth,
- * the socket engine, local file storage, and the offline `robodev dev` jobs engine.
+ * the socket engine, local file storage, the offline `robodev dev` jobs engine,
+ * and email template rendering.
  */
 
 export {
@@ -279,6 +280,33 @@ export {
   type StorageQueryable,
 } from "./local-storage.js";
 
+export {
+  CUSTOM_EMAIL_SLUG_RE,
+  EMAIL_TEMPLATE_MAX_BYTES,
+  EMAIL_TEMPLATE_MAX_CUSTOM,
+  EMAIL_TEMPLATE_MAX_SUBJECT,
+  EMAIL_TEMPLATE_MAX_VAR_NAME,
+  EMAIL_TEMPLATE_MAX_VARS,
+  EMAIL_TEMPLATE_VAR_NAME_RE,
+  EMAIL_TEMPLATE_VAR_RE,
+  SYSTEM_EMAIL_SLUGS,
+  escapeEmailHtml,
+  extractTemplateVars,
+  htmlToPlainText,
+  isCustomEmailSlug,
+  isSystemEmailSlug,
+  loadLocalEmailTemplate,
+  localEmailTemplatePaths,
+  mergeCustomTemplateVariables,
+  renderEmailFields,
+  renderEmailTemplate,
+  resolveEmailSendInput,
+  type EmailTemplateKind,
+  type EmailTemplateVars,
+  type LocalEmailTemplate,
+  type SystemEmailSlug,
+} from "./email-templates.js";
+
 export {
   LOCAL_DEV_IDENTITY_AUD,
   LOCAL_DEV_IDENTITY_TYP,