@beechcms/api 0.5.0 → 0.6.0-preview.2

package/src/features/email/providers/smtp.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import type { EmailProvider } from '../email.provider'
+import type { OutboundEmail } from '../email.types'
+
+export interface SmtpProviderConfig {
+  /** Base URL of the Mailpit HTTP API, e.g. http://localhost:8025 */
+  baseUrl: string
+}
+
+interface MailpitAddress { Name?: string; Email: string }
+interface MailpitSendPayload {
+  From: MailpitAddress
+  To: MailpitAddress[]
+  Subject: string
+  HTML?: string
+  Text?: string
+}
+
+function parseAddress(raw: string): MailpitAddress {
+  const match = raw.match(/^\s*(.+?)\s*<([^>]+)>\s*$/)
+  if (match) return { Name: match[1], Email: match[2] }
+  return { Email: raw.trim() }
+}
+
+export class SmtpEmailProvider implements EmailProvider {
+  private readonly endpoint: string
+
+  constructor(config: SmtpProviderConfig) {
+    this.endpoint = `${config.baseUrl.replace(/\/$/, '')}/api/v1/send`
+  }
+
+  async send(email: OutboundEmail): Promise<void> {
+    const payload: MailpitSendPayload = {
+      From: parseAddress(email.from),
+      To: email.to.map(parseAddress),
+      Subject: email.subject,
+      HTML: email.html,
+    }
+
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => `HTTP ${response.status}`)
+      throw new Error(`[SmtpEmailProvider] send failed — ${body}`)
+    }
+  }
+}

package/src/features/email/templates/automation-mail.ts

@@ -1,15 +1,19 @@
-import type { AutomationMailParams } from '../email.types'
-
-/** Identity builder: automation payloads are already user-authored. */
-export function buildAutomationEmail(params: AutomationMailParams) {
-  return {
-    to: params.to,
-    subject: params.subject,
-    html: params.body,
-    text: stripHtml(params.body),
-  }
-}
-
-function stripHtml(input: string): string {
-  return input.replace(/<[^>]+>/g, '').trim()
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { AutomationMailParams } from '../email.types'
+
+/** Identity builder: automation payloads are already user-authored. */
+export function buildAutomationEmail(params: AutomationMailParams) {
+  return {
+    to: params.to,
+    subject: params.subject,
+    html: params.body,
+    text: stripHtml(params.body),
+  }
+}
+
+function stripHtml(input: string): string {
+  return input.replace(/<[^>]+>/g, '').trim()
+}

package/src/features/email/templates/password-changed.ts

@@ -1,59 +1,63 @@
-import type { EmailLocale } from '../email.types'
-import { buildEmailShell } from './shell'
-
-/**
- * Localized texts for the "password changed" security notification.
- *
- * ─── ADDING A NEW LANGUAGE ──────────────────────────────────────────────────
- * See instructions in `templates/password-reset.ts`.
- * ─────────────────────────────────────────────────────────────────────────────
- */
-const COPY: Record<EmailLocale, {
-  subject: string
-  title: string
-  body: string
-  warning: string
-  footer: string
-}> = {
-  en: {
-    subject: 'Your Beech CMS password has been changed',
-    title: 'Your password has been changed',
-    body: 'Your Beech CMS account password was successfully changed. If you made this change, no action is needed.',
-    warning:
-      'If you did not make this change, your account may be compromised. Contact your administrator immediately.',
-    footer: 'This is an automated security notification. Do not reply to this email.',
-  },
-  it: {
-    subject: 'La tua password Beech CMS è stata modificata',
-    title: 'La tua password è stata modificata',
-    body: 'La password del tuo account Beech CMS è stata modificata con successo. Se hai effettuato tu questa modifica, non devi fare nulla.',
-    warning:
-      'Se non hai effettuato tu questa modifica, il tuo account potrebbe essere compromesso. Contatta immediatamente il tuo amministratore.',
-    footer: 'Questa è una notifica di sicurezza automatica. Non rispondere a questa email.',
-  },
-}
-
-/**
- * Builds the "password changed" notification email.
- *
- * This email does not have a CTA button — it is a pure security notification.
- * The `warning` block (red text) warns the user to take action if they
- * were not the one who changed the password.
- *
- * @param locale - Language for the email subject and body.
- * @returns Object with `subject` (string) and `html` (complete HTML document).
- */
-export function buildPasswordChangedEmail(
-  locale: EmailLocale,
-): { subject: string; html: string } {
-  const c = COPY[locale]
-  return {
-    subject: c.subject,
-    html: buildEmailShell(locale, {
-      title: c.title,
-      body: c.body,
-      warning: c.warning,
-      footer: c.footer,
-    }),
-  }
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { EmailLocale } from '../email.types'
+import { buildEmailShell } from './shell'
+
+/**
+ * Localized texts for the "password changed" security notification.
+ *
+ * ─── ADDING A NEW LANGUAGE ──────────────────────────────────────────────────
+ * See instructions in `templates/password-reset.ts`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+const COPY: Record<EmailLocale, {
+  subject: string
+  title: string
+  body: string
+  warning: string
+  footer: string
+}> = {
+  en: {
+    subject: 'Your Beech CMS password has been changed',
+    title: 'Your password has been changed',
+    body: 'Your Beech CMS account password was successfully changed. If you made this change, no action is needed.',
+    warning:
+      'If you did not make this change, your account may be compromised. Contact your administrator immediately.',
+    footer: 'This is an automated security notification. Do not reply to this email.',
+  },
+  it: {
+    subject: 'La tua password Beech CMS è stata modificata',
+    title: 'La tua password è stata modificata',
+    body: 'La password del tuo account Beech CMS è stata modificata con successo. Se hai effettuato tu questa modifica, non devi fare nulla.',
+    warning:
+      'Se non hai effettuato tu questa modifica, il tuo account potrebbe essere compromesso. Contatta immediatamente il tuo amministratore.',
+    footer: 'Questa è una notifica di sicurezza automatica. Non rispondere a questa email.',
+  },
+}
+
+/**
+ * Builds the "password changed" notification email.
+ *
+ * This email does not have a CTA button — it is a pure security notification.
+ * The `warning` block (red text) warns the user to take action if they
+ * were not the one who changed the password.
+ *
+ * @param locale - Language for the email subject and body.
+ * @returns Object with `subject` (string) and `html` (complete HTML document).
+ */
+export function buildPasswordChangedEmail(
+  locale: EmailLocale,
+): { subject: string; html: string } {
+  const c = COPY[locale]
+  return {
+    subject: c.subject,
+    html: buildEmailShell(locale, {
+      title: c.title,
+      body: c.body,
+      warning: c.warning,
+      footer: c.footer,
+    }),
+  }
+}

package/src/features/email/templates/password-reset.ts

@@ -1,64 +1,68 @@
-import type { EmailLocale } from '../email.types'
-import { buildEmailShell } from './shell'
-
-/**
- * Localized texts for the password reset email.
- *
- * ─── ADDING A NEW LANGUAGE ──────────────────────────────────────────────────
- * 1. Add the ISO code in `SUPPORTED_EMAIL_LOCALES` (`email.types.ts`).
- * 2. Add a corresponding key in this object with all fields.
- *    TypeScript immediately reports missing keys thanks to
- *    `Record<EmailLocale, …>`.
- * ─────────────────────────────────────────────────────────────────────────────
- */
-const COPY: Record<EmailLocale, {
-  subject: string
-  title: string
-  body: string
-  ctaLabel: string
-  footer: string
-}> = {
-  en: {
-    subject: 'Reset your Beech CMS password',
-    title: 'Reset your password',
-    body: 'You requested a password reset for your Beech CMS account. Click the button below to set a new password. This link expires in 30 minutes.',
-    ctaLabel: 'Reset password',
-    footer: "If you didn't request this, you can safely ignore this email.",
-  },
-  it: {
-    subject: 'Reimposta la tua password Beech CMS',
-    title: 'Reimposta la tua password',
-    body: 'Hai richiesto il reset della password per il tuo account Beech CMS. Clicca il pulsante qui sotto per impostare una nuova password. Questo link scade tra 30 minuti.',
-    ctaLabel: 'Reimposta password',
-    footer: 'Se non hai richiesto questo, puoi ignorare questa email in tutta sicurezza.',
-  },
-}
-
-/**
- * Builds the email with the password reset link.
- *
- * Composes the localized content with the base layout (`buildEmailShell`)
- * injecting the CTA button pointing to the reset URL.
- *
- * @param resetUrl - Complete URL with the token in plain text, e.g.
- *                   `https://dashboard.beechcms.dev/reset-password?token=<uuid>`.
- *                   It is directly embedded in the CTA button — do not sanitize
- *                   further: the token is an internally generated UUID.
- * @param locale   - Language for the email subject and body.
- * @returns Object with `subject` (string) and `html` (complete HTML document).
- */
-export function buildPasswordResetEmail(
-  resetUrl: string,
-  locale: EmailLocale,
-): { subject: string; html: string } {
-  const c = COPY[locale]
-  return {
-    subject: c.subject,
-    html: buildEmailShell(locale, {
-      title: c.title,
-      body: c.body,
-      cta: { label: c.ctaLabel, href: resetUrl },
-      footer: c.footer,
-    }),
-  }
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { EmailLocale } from '../email.types'
+import { buildEmailShell } from './shell'
+
+/**
+ * Localized texts for the password reset email.
+ *
+ * ─── ADDING A NEW LANGUAGE ──────────────────────────────────────────────────
+ * 1. Add the ISO code in `SUPPORTED_EMAIL_LOCALES` (`email.types.ts`).
+ * 2. Add a corresponding key in this object with all fields.
+ *    TypeScript immediately reports missing keys thanks to
+ *    `Record<EmailLocale, …>`.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+const COPY: Record<EmailLocale, {
+  subject: string
+  title: string
+  body: string
+  ctaLabel: string
+  footer: string
+}> = {
+  en: {
+    subject: 'Reset your Beech CMS password',
+    title: 'Reset your password',
+    body: 'You requested a password reset for your Beech CMS account. Click the button below to set a new password. This link expires in 30 minutes.',
+    ctaLabel: 'Reset password',
+    footer: "If you didn't request this, you can safely ignore this email.",
+  },
+  it: {
+    subject: 'Reimposta la tua password Beech CMS',
+    title: 'Reimposta la tua password',
+    body: 'Hai richiesto il reset della password per il tuo account Beech CMS. Clicca il pulsante qui sotto per impostare una nuova password. Questo link scade tra 30 minuti.',
+    ctaLabel: 'Reimposta password',
+    footer: 'Se non hai richiesto questo, puoi ignorare questa email in tutta sicurezza.',
+  },
+}
+
+/**
+ * Builds the email with the password reset link.
+ *
+ * Composes the localized content with the base layout (`buildEmailShell`)
+ * injecting the CTA button pointing to the reset URL.
+ *
+ * @param resetUrl - Complete URL with the token in plain text, e.g.
+ *                   `https://dashboard.beechcms.dev/reset-password?token=<uuid>`.
+ *                   It is directly embedded in the CTA button — do not sanitize
+ *                   further: the token is an internally generated UUID.
+ * @param locale   - Language for the email subject and body.
+ * @returns Object with `subject` (string) and `html` (complete HTML document).
+ */
+export function buildPasswordResetEmail(
+  resetUrl: string,
+  locale: EmailLocale,
+): { subject: string; html: string } {
+  const c = COPY[locale]
+  return {
+    subject: c.subject,
+    html: buildEmailShell(locale, {
+      title: c.title,
+      body: c.body,
+      cta: { label: c.ctaLabel, href: resetUrl },
+      footer: c.footer,
+    }),
+  }
+}

package/src/features/email/templates/shell.ts

@@ -1,92 +1,96 @@
-import type { EmailLocale } from '../email.types'
-
-/**
- * Content slots that every template must provide to compose a complete email.
- * Each slot corresponds to a visual block in the email card layout.
- */
-export interface EmailShellSlots {
-  /**
-   * H2 heading shown at the top of the card. Keep it under ~50 characters
-   * to ensure good readability on mobile clients.
-   */
-  title: string
-
-  /**
-   * Main body text. Rendered as a paragraph.
-   * Safe inline HTML is allowed (e.g., `<strong>`, `<a href="...">`),
-   * but avoid block elements (`<p>`, `<div>`) that could break
-   * the layout structure in rigid email clients (Outlook, Gmail).
-   */
-  body: string
-
-  /**
-   * Optional call-to-action button, rendered as a dark link-button.
-   * Omit for notification-only emails that do not require user action.
-   */
-  cta?: { label: string; href: string }
-
-  /**
-   * Optional warning paragraph. Rendered in red (#ef4444) to attract
-   * attention. Use it for security alerts
-   * ("if it wasn't you, act immediately").
-   */
-  warning?: string
-
-  /**
-   * Small gray text at the bottom of the card.
-   * Used for notes like "automated notification, do not reply".
-   */
-  footer: string
-}
-
-/**
- * Builds the base HTML layout shared by all Beech CMS transactional emails.
- *
- * ─── SINGLE SOURCE OF TRUTH FOR BRANDING ─────────────────────────────────────
- * Modifying this function changes the visual appearance of ALL outgoing emails
- * simultaneously:
- *   - background and card color
- *   - border style and border-radius
- *   - typographic scale and spacing
- *   - CTA button style
- *
- * To change the text or structure of a specific email, instead modify
- * the corresponding template file (`templates/password-reset.ts`, etc.).
- * ─────────────────────────────────────────────────────────────────────────────
- *
- * @param locale - Used for the `lang` attribute of the `<html>` tag.
- * @param slots  - Content blocks injected into the layout.
- * @returns A complete and self-contained HTML document ready to be sent.
- */
-export function buildEmailShell(locale: EmailLocale, slots: EmailShellSlots): string {
-  const ctaBlock = slots.cta
-    ? `<a href="${slots.cta.href}"
-          style="display:inline-block;background:#111;color:#fff;padding:12px 24px;
-                 border-radius:6px;text-decoration:none;font-size:15px;font-weight:500;
-                 margin-bottom:24px">
-         ${slots.cta.label}
-       </a>`
-    : ''
-
-  const warningBlock = slots.warning
-    ? `<p style="margin:0 0 24px;color:#ef4444;font-size:15px;line-height:1.5;font-weight:500">
-         ${slots.warning}
-       </p>`
-    : ''
-
-  return `<!DOCTYPE html>
-<html lang="${locale}">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width,initial-scale=1">
-</head>
-<body style="font-family:sans-serif;background:#f9f9f9;margin:0;padding:32px">
-  <div style="max-width:480px;margin:0 auto;background:#fff;border-radius:8px;
-              padding:32px;border:1px solid #e5e5e5">
-    <h2 style="margin:0 0 16px;font-size:20px;color:#111">${slots.title}</h2>
-    <p style="margin:0 0 24px;color:#555;font-size:15px;line-height:1.5">${slots.body}</p>
-    ${ctaBlock}${warningBlock}<p style="margin:0;color:#999;font-size:13px">${slots.footer}</p>
-  </div>
-</body>
-</html>`
-}
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import type { EmailLocale } from '../email.types'
+
+/**
+ * Content slots that every template must provide to compose a complete email.
+ * Each slot corresponds to a visual block in the email card layout.
+ */
+export interface EmailShellSlots {
+  /**
+   * H2 heading shown at the top of the card. Keep it under ~50 characters
+   * to ensure good readability on mobile clients.
+   */
+  title: string
+
+  /**
+   * Main body text. Rendered as a paragraph.
+   * Safe inline HTML is allowed (e.g., `<strong>`, `<a href="...">`),
+   * but avoid block elements (`<p>`, `<div>`) that could break
+   * the layout structure in rigid email clients (Outlook, Gmail).
+   */
+  body: string
+
+  /**
+   * Optional call-to-action button, rendered as a dark link-button.
+   * Omit for notification-only emails that do not require user action.
+   */
+  cta?: { label: string; href: string }
+
+  /**
+   * Optional warning paragraph. Rendered in red (#ef4444) to attract
+   * attention. Use it for security alerts
+   * ("if it wasn't you, act immediately").
+   */
+  warning?: string
+
+  /**
+   * Small gray text at the bottom of the card.
+   * Used for notes like "automated notification, do not reply".
+   */
+  footer: string
+}
+
+/**
+ * Builds the base HTML layout shared by all Beech CMS transactional emails.
+ *
+ * ─── SINGLE SOURCE OF TRUTH FOR BRANDING ─────────────────────────────────────
+ * Modifying this function changes the visual appearance of ALL outgoing emails
+ * simultaneously:
+ *   - background and card color
+ *   - border style and border-radius
+ *   - typographic scale and spacing
+ *   - CTA button style
+ *
+ * To change the text or structure of a specific email, instead modify
+ * the corresponding template file (`templates/password-reset.ts`, etc.).
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * @param locale - Used for the `lang` attribute of the `<html>` tag.
+ * @param slots  - Content blocks injected into the layout.
+ * @returns A complete and self-contained HTML document ready to be sent.
+ */
+export function buildEmailShell(locale: EmailLocale, slots: EmailShellSlots): string {
+  const ctaBlock = slots.cta
+    ? `<a href="${slots.cta.href}"
+          style="display:inline-block;background:#111;color:#fff;padding:12px 24px;
+                 border-radius:6px;text-decoration:none;font-size:15px;font-weight:500;
+                 margin-bottom:24px">
+         ${slots.cta.label}
+       </a>`
+    : ''
+
+  const warningBlock = slots.warning
+    ? `<p style="margin:0 0 24px;color:#ef4444;font-size:15px;line-height:1.5;font-weight:500">
+         ${slots.warning}
+       </p>`
+    : ''
+
+  return `<!DOCTYPE html>
+<html lang="${locale}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+</head>
+<body style="font-family:sans-serif;background:#f9f9f9;margin:0;padding:32px">
+  <div style="max-width:480px;margin:0 auto;background:#fff;border-radius:8px;
+              padding:32px;border:1px solid #e5e5e5">
+    <h2 style="margin:0 0 16px;font-size:20px;color:#111">${slots.title}</h2>
+    <p style="margin:0 0 24px;color:#555;font-size:15px;line-height:1.5">${slots.body}</p>
+    ${ctaBlock}${warningBlock}<p style="margin:0;color:#999;font-size:13px">${slots.footer}</p>
+  </div>
+</body>
+</html>`
+}

package/src/features/notifications/index.ts

@@ -1 +1,5 @@
-export { notificationsApp } from './notifications.handler'
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+export { notificationsApp } from './notifications.handler'