@beechcms/api 0.5.0 → 0.6.0-preview.2

package/src/features/email/email.service.ts

@@ -1,93 +1,98 @@
-/**
- * Email Service — orchestrator of the Beech CMS email module.
- *
- * Sending pipeline:
- *   caller → service function → template builder → provider → Resend (or other)
- *
- * This is the only file that imports from both templates and the provider.
- * No other layer knows the entire pipeline.
- *
- * ─── CHANGING PROVIDER ───────────────────────────────────────────────────────
- * To replace Resend with another service, ONLY modify the
- * `createProvider()` function below: change the import and instantiation.
- * No other module file — nor anywhere else in the project — needs to be touched.
- * ─────────────────────────────────────────────────────────────────────────────
- */
-import { ResendEmailProvider } from './providers/resend'
-import { buildPasswordResetEmail } from './templates/password-reset'
-import { buildPasswordChangedEmail } from './templates/password-changed'
-import { buildAutomationEmail } from './templates/automation-mail'
-import type { EmailProvider } from './email.provider'
-import type {
-  PasswordResetEmailParams,
-  PasswordChangedEmailParams,
-  AutomationMailParams,
-} from './email.types'
-
-/** Default sender address (Resend test sender, works without a verified domain). */
-const DEFAULT_FROM = 'Beech CMS <onboarding@resend.dev>'
-
-/**
- * Instantiates the active email provider.
- *
- * This is the single point for changing the provider: replace the
- * `new ResendEmailProvider(...)` line with any class that implements `EmailProvider`.
- */
-function createProvider(apiKey: string, isDev: boolean): EmailProvider {
-  return new ResendEmailProvider(apiKey, isDev)
-}
-
-/**
- * Sends the password reset link email to the specified recipient.
- *
- * The email body is built from the localized template in
- * `templates/password-reset.ts` and composed with the base layout in
- * `templates/shell.ts`.
- *
- * @throws If the provider rejects the request. The caller decides whether to propagate
- *         the error (request fail) or handle it silently (fire-and-forget).
- */
-export async function sendPasswordResetEmail(
-  params: PasswordResetEmailParams,
-): Promise<void> {
-  const provider = createProvider(params.apiKey, params.isDev ?? false)
-  const { subject, html } = buildPasswordResetEmail(params.resetUrl, params.locale)
-  await provider.send({
-    from: params.from ?? DEFAULT_FROM,
-    to: [params.to],
-    subject,
-    html,
-  })
-}
-
-/**
- * Sends the "password changed" security notification to the account owner.
- *
- * Called after a successful password reset to notify the user. It does not have a
- * CTA button — it is a pure notification, no action required from the user.
- *
- * @throws If the provider rejects the request.
- */
-export async function sendPasswordChangedEmail(
-  params: PasswordChangedEmailParams,
-): Promise<void> {
-  const provider = createProvider(params.apiKey, params.isDev ?? false)
-  const { subject, html } = buildPasswordChangedEmail(params.locale)
-  await provider.send({
-    from: params.from ?? DEFAULT_FROM,
-    to: [params.to],
-    subject,
-    html,
-  })
-}
-
-export async function sendAutomationMail(params: AutomationMailParams): Promise<void> {
-  const provider = createProvider(params.apiKey ?? params.resendApiKey ?? '', false)
-  const message = buildAutomationEmail(params)
-  await provider.send({
-    from: params.from ?? DEFAULT_FROM,
-    to: [message.to],
-    subject: message.subject,
-    html: message.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 { ResendEmailProvider } from './providers/resend'
+import { SmtpEmailProvider } from './providers/smtp'
+import { buildPasswordResetEmail } from './templates/password-reset'
+import { buildPasswordChangedEmail } from './templates/password-changed'
+import { buildAutomationEmail } from './templates/automation-mail'
+import type { EmailProvider } from './email.provider'
+import type {
+  PasswordResetEmailParams,
+  PasswordChangedEmailParams,
+  AutomationMailParams,
+} from './email.types'
+
+const DEFAULT_FROM = 'Beech CMS <onboarding@resend.dev>'
+
+export interface EmailProviderEnv {
+  /** "smtp" | "resend"; default "resend" if absent */
+  provider?: string
+  /** Resend API key, used when provider is "resend" */
+  apiKey?: string
+  /** Mailpit base URL (e.g. http://localhost:8025), used when provider is "smtp" */
+  smtpBaseUrl?: string
+  isDev?: boolean
+}
+
+// TODO: il sistema di selezione provider è attualmente hardcoded su "smtp" | "resend".
+// Sarebbe meglio aprirlo a provider di terze parti (Postmark, SendGrid, Brevo, SES, ...)
+// senza che l'utente debba toccare il codice. Opzioni da valutare:
+//   1. Strategia plugin: EMAIL_PROVIDER accetta un path a modulo ES (`./my-provider.ts`)
+//      che esporta default class implementing EmailProvider — zero lock-in.
+//   2. Provider SMTP generico: rimuovere il coupling con Mailpit dalla denominazione
+//      e accettare qualsiasi server SMTP via SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS
+//      (il SmtpEmailProvider attuale usa già l'HTTP API di Mailpit, non SMTP raw —
+//      andrebbe riscritto con nodemailer o un client SMTP standard per coprire qualsiasi server).
+//   3. Webhook email: EMAIL_PROVIDER=webhook + EMAIL_WEBHOOK_URL per integrazioni custom.
+// Riferimento: email.provider.ts definisce l'interfaccia — è già sufficientemente astratta.
+function createProvider(env: EmailProviderEnv): EmailProvider {
+  if (env.provider === 'smtp') {
+    if (!env.smtpBaseUrl) throw new Error('SMTP provider selected but SMTP_HOST is missing')
+    return new SmtpEmailProvider({ baseUrl: env.smtpBaseUrl })
+  }
+  return new ResendEmailProvider(env.apiKey ?? '', env.isDev ?? false)
+}
+
+export async function sendPasswordResetEmail(
+  params: PasswordResetEmailParams,
+): Promise<void> {
+  const provider = createProvider({
+    provider: params.provider,
+    apiKey: params.apiKey,
+    smtpBaseUrl: params.smtpBaseUrl,
+    isDev: params.isDev ?? false,
+  })
+  const { subject, html } = buildPasswordResetEmail(params.resetUrl, params.locale)
+  await provider.send({
+    from: params.from ?? DEFAULT_FROM,
+    to: [params.to],
+    subject,
+    html,
+  })
+}
+
+export async function sendPasswordChangedEmail(
+  params: PasswordChangedEmailParams,
+): Promise<void> {
+  const provider = createProvider({
+    provider: params.provider,
+    apiKey: params.apiKey,
+    smtpBaseUrl: params.smtpBaseUrl,
+    isDev: params.isDev ?? false,
+  })
+  const { subject, html } = buildPasswordChangedEmail(params.locale)
+  await provider.send({
+    from: params.from ?? DEFAULT_FROM,
+    to: [params.to],
+    subject,
+    html,
+  })
+}
+
+export async function sendAutomationMail(params: AutomationMailParams): Promise<void> {
+  const provider = createProvider({
+    provider: params.provider,
+    apiKey: params.apiKey ?? params.resendApiKey,
+    smtpBaseUrl: params.smtpBaseUrl,
+    isDev: false,
+  })
+  const message = buildAutomationEmail(params)
+  await provider.send({
+    from: params.from ?? DEFAULT_FROM,
+    to: [message.to],
+    subject: message.subject,
+    html: message.html,
+  })
+}

package/src/features/email/email.types.ts

@@ -1,108 +1,119 @@
-/**
- * Shared types for the Beech CMS email module.
- *
- * All types used across provider, service, and templates are defined here
- * so that each layer remains decoupled from the others.
- */
-
-// ── Locale ────────────────────────────────────────────────────────────────────
-
-/**
- * Supported languages for the email template system.
- *
- * To add a new language:
- *  1. Add the ISO code here (e.g., `'fr'`).
- *  2. Add the corresponding translation in the `COPY` object of every
- *     file in `templates/`. TypeScript will flag missing keys.
- */
-export const SUPPORTED_EMAIL_LOCALES = ['en', 'it'] as const
-export type EmailLocale = (typeof SUPPORTED_EMAIL_LOCALES)[number]
-
-/**
- * Resolves an unverified locale string (e.g., from a request body)
- * to a supported `EmailLocale` value. Any unknown value
- * safely falls back to `'en'`.
- *
- * @param raw - Raw value from the client (can be anything).
- * @returns A valid `EmailLocale`, always.
- */
-export function resolveEmailLocale(raw: unknown): EmailLocale {
-  if (
-    typeof raw === 'string' &&
-    (SUPPORTED_EMAIL_LOCALES as readonly string[]).includes(raw)
-  ) {
-    return raw as EmailLocale
-  }
-  return 'en'
-}
-
-// ── Outbound message ──────────────────────────────────────────────────────────
-
-/**
- * The resolved email message that the provider receives and sends.
- * It is constructed by the service by combining the call parameters
- * with the template builder output.
- */
-export interface OutboundEmail {
-  /** Sender address in RFC 5321 format (e.g., "Beech CMS <noreply@beechcms.dev>"). */
-  from: string
-  /** List of recipient addresses. Must contain at least one element. */
-  to: string[]
-  subject: string
-  /** Complete HTML body. Must be a valid HTML document (see `templates/shell.ts`). */
-  html: string
-}
-
-// ── Service function parameters ───────────────────────────────────────────────
-
-/**
- * Shared parameters for every email sending function in `email.service.ts`.
- * Specific functions extend this type with the additional fields
- * required for their respective templates.
- */
-export interface BaseEmailParams {
-  /** Main recipient address. */
-  to: string
-  /** Email body language. Use `resolveEmailLocale()` before passing it here. */
-  locale: EmailLocale
-  /**
-   * Resend API key (or the active provider's key). Must be non-empty —
-   * the caller is responsible for validating it before invoking the service.
-   */
-  apiKey: string
-  /**
-   * Sender address in RFC 5321 format.
-   * Default: "Beech CMS <onboarding@resend.dev>" (Resend test sender).
-   * In production, set a verified address via the
-   * `EMAIL_FROM` environment variable.
-   */
-  from?: string
-  /**
-   * When `true`, provider errors are logged to the console.
-   * Set to `false` in production to avoid exposing internal details.
-   */
-  isDev?: boolean
-}
-
-/** Parameters for the password reset email — adds the reset URL. */
-export interface PasswordResetEmailParams extends BaseEmailParams {
-  /**
-   * Complete URL that the user clicks to set the new password.
-   * Contains the token in plain text as a query param `?token=<uuid>`.
-   * Constructed by the caller as `${APP_URL}/reset-password?token=${token}`.
-   */
-  resetUrl: string
-}
-
-/** Parameters for the "password changed" notification. No additional fields. */
-export type PasswordChangedEmailParams = BaseEmailParams
-
-export interface AutomationMailParams {
-  to: string
-  subject: string
-  /** Plain text or HTML — passed verbatim to provider. */
-  body: string
-  apiKey?: string
-  resendApiKey?: string
-  from?: string
-}
+// 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.
+
+/**
+ * Shared types for the Beech CMS email module.
+ *
+ * All types used across provider, service, and templates are defined here
+ * so that each layer remains decoupled from the others.
+ */
+
+// ── Locale ────────────────────────────────────────────────────────────────────
+
+/**
+ * Supported languages for the email template system.
+ *
+ * To add a new language:
+ *  1. Add the ISO code here (e.g., `'fr'`).
+ *  2. Add the corresponding translation in the `COPY` object of every
+ *     file in `templates/`. TypeScript will flag missing keys.
+ */
+export const SUPPORTED_EMAIL_LOCALES = ['en', 'it'] as const
+export type EmailLocale = (typeof SUPPORTED_EMAIL_LOCALES)[number]
+
+/**
+ * Resolves an unverified locale string (e.g., from a request body)
+ * to a supported `EmailLocale` value. Any unknown value
+ * safely falls back to `'en'`.
+ *
+ * @param raw - Raw value from the client (can be anything).
+ * @returns A valid `EmailLocale`, always.
+ */
+export function resolveEmailLocale(raw: unknown): EmailLocale {
+  if (
+    typeof raw === 'string' &&
+    (SUPPORTED_EMAIL_LOCALES as readonly string[]).includes(raw)
+  ) {
+    return raw as EmailLocale
+  }
+  return 'en'
+}
+
+// ── Outbound message ──────────────────────────────────────────────────────────
+
+/**
+ * The resolved email message that the provider receives and sends.
+ * It is constructed by the service by combining the call parameters
+ * with the template builder output.
+ */
+export interface OutboundEmail {
+  /** Sender address in RFC 5321 format (e.g., "Beech CMS <noreply@beechcms.dev>"). */
+  from: string
+  /** List of recipient addresses. Must contain at least one element. */
+  to: string[]
+  subject: string
+  /** Complete HTML body. Must be a valid HTML document (see `templates/shell.ts`). */
+  html: string
+}
+
+// ── Service function parameters ───────────────────────────────────────────────
+
+/**
+ * Shared parameters for every email sending function in `email.service.ts`.
+ * Specific functions extend this type with the additional fields
+ * required for their respective templates.
+ */
+export interface BaseEmailParams {
+  /** Main recipient address. */
+  to: string
+  /** Email body language. Use `resolveEmailLocale()` before passing it here. */
+  locale: EmailLocale
+  /**
+   * Resend API key (or the active provider's key). Must be non-empty —
+   * the caller is responsible for validating it before invoking the service.
+   */
+  apiKey: string
+  /**
+   * Sender address in RFC 5321 format.
+   * Default: "Beech CMS <onboarding@resend.dev>" (Resend test sender).
+   * In production, set a verified address via the
+   * `EMAIL_FROM` environment variable.
+   */
+  from?: string
+  /**
+   * When `true`, provider errors are logged to the console.
+   * Set to `false` in production to avoid exposing internal details.
+   */
+  isDev?: boolean
+}
+
+/** Parameters for the password reset email — adds the reset URL. */
+export interface PasswordResetEmailParams extends BaseEmailParams {
+  /**
+   * Complete URL that the user clicks to set the new password.
+   * Contains the token in plain text as a query param `?token=<uuid>`.
+   * Constructed by the caller as `${APP_URL}/reset-password?token=${token}`.
+   */
+  resetUrl: string
+  provider?: 'smtp' | 'resend'
+  smtpBaseUrl?: string
+}
+
+/** Parameters for the "password changed" notification. No additional fields. */
+export interface PasswordChangedEmailParams extends BaseEmailParams {
+  provider?: 'smtp' | 'resend'
+  smtpBaseUrl?: string
+}
+
+export interface AutomationMailParams {
+  to: string
+  subject: string
+  /** Plain text or HTML — passed verbatim to provider. */
+  body: string
+  apiKey?: string
+  resendApiKey?: string
+  from?: string
+  provider?: 'smtp' | 'resend'
+  smtpBaseUrl?: string
+}

package/src/features/email/index.ts

@@ -1,29 +1,33 @@
-/**
- * Public API — modulo email di Beech CMS
- *
- * Questo è l'UNICO file da importare da codice esterno a questa feature.
- * I dettagli implementativi interni (provider, template, shell) sono privati
- * alla slice e non devono mai essere importati direttamente dall'esterno.
- *
- * ─── FUNZIONI ESPORTATE ───────────────────────────────────────────────────────
- *   sendPasswordResetEmail    — invia l'email con il link di reset
- *   sendPasswordChangedEmail  — invia la notifica "password modificata"
- *
- * ─── TIPI E UTILITY ESPORTATI ────────────────────────────────────────────────
- *   EmailLocale               — 'en' | 'it'  (aggiungere lingue in email.types.ts)
- *   resolveEmailLocale        — resolver sicuro per locale da input non verificato
- *   PasswordResetEmailParams  — shape dei parametri per sendPasswordResetEmail
- *   PasswordChangedEmailParams — shape dei parametri per sendPasswordChangedEmail
- */
-
-export { sendPasswordResetEmail, sendPasswordChangedEmail, sendAutomationMail } from './email.service'
-export {
-  resolveEmailLocale,
-  SUPPORTED_EMAIL_LOCALES,
-} from './email.types'
-export type {
-  EmailLocale,
-  PasswordResetEmailParams,
-  PasswordChangedEmailParams,
-  AutomationMailParams,
-} from './email.types'
+// 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.
+
+/**
+ * Public API — modulo email di Beech CMS
+ *
+ * Questo è l'UNICO file da importare da codice esterno a questa feature.
+ * I dettagli implementativi interni (provider, template, shell) sono privati
+ * alla slice e non devono mai essere importati direttamente dall'esterno.
+ *
+ * ─── FUNZIONI ESPORTATE ───────────────────────────────────────────────────────
+ *   sendPasswordResetEmail    — invia l'email con il link di reset
+ *   sendPasswordChangedEmail  — invia la notifica "password modificata"
+ *
+ * ─── TIPI E UTILITY ESPORTATI ────────────────────────────────────────────────
+ *   EmailLocale               — 'en' | 'it'  (aggiungere lingue in email.types.ts)
+ *   resolveEmailLocale        — resolver sicuro per locale da input non verificato
+ *   PasswordResetEmailParams  — shape dei parametri per sendPasswordResetEmail
+ *   PasswordChangedEmailParams — shape dei parametri per sendPasswordChangedEmail
+ */
+
+export { sendPasswordResetEmail, sendPasswordChangedEmail, sendAutomationMail } from './email.service'
+export {
+  resolveEmailLocale,
+  SUPPORTED_EMAIL_LOCALES,
+} from './email.types'
+export type {
+  EmailLocale,
+  PasswordResetEmailParams,
+  PasswordChangedEmailParams,
+  AutomationMailParams,
+} from './email.types'

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

@@ -1,63 +1,67 @@
-/// <reference types="@cloudflare/workers-types" />
-import type { EmailProvider } from '../email.provider'
-import type { OutboundEmail } from '../email.types'
-
-/** Resend REST endpoint for sending emails. */
-const RESEND_API_URL = 'https://api.resend.com/emails'
-
-/**
- * Resend implementation of EmailProvider.
- *
- * This is the ONLY file in the email module that knows about Resend.
- * Every other file is completely unaware of which provider is active.
- *
- * ─── HOW TO REPLACE THIS PROVIDER ──────────────────────────────────────────
- *  1. Create a new file in `providers/` (e.g., `providers/sendgrid.ts`).
- *  2. Export a class that implements `EmailProvider` (a single method: `send`).
- *  3. In `email.service.ts`, replace `new ResendEmailProvider(...)` with
- *     your new class in the `createProvider()` function.
- *  4. Update the environment variables in `types.ts` and `wrangler.jsonc`.
- *  5. No other file in the project needs to be modified.
- *
- * Resend API Documentation: https://resend.com/docs/api-reference/emails/send-email
- * ─────────────────────────────────────────────────────────────────────────────
- */
-export class ResendEmailProvider implements EmailProvider {
-  private readonly apiKey: string
-
-  /** When `true`, errors are logged to the console (development only). */
-  private readonly isDev: boolean
-
-  constructor(apiKey: string, isDev = false) {
-    this.apiKey = apiKey
-    this.isDev = isDev
-  }
-
-  /**
-   * Sends the email via the Resend REST API (`POST /emails`).
-   *
-   * Throws an exception if Resend responds with a non-2xx status, so that
-   * the caller (`email.service.ts`) can decide whether to propagate the error
-   * or handle it silently (fire-and-forget).
-   *
-   * The response body is read for logging only in the development environment,
-   * to avoid unnecessarily consuming the body stream in production.
-   */
-  async send(email: OutboundEmail): Promise<void> {
-    const response = await fetch(RESEND_API_URL, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-        },
-      body: JSON.stringify(email),
-    })
-
-    if (!response.ok) {
-      const detail = this.isDev
-        ? await response.text()
-        : `HTTP ${response.status}`
-      throw new Error(`[ResendEmailProvider] send failed — ${detail}`)
-    }
-  }
-}
+// 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'
+
+/** Resend REST endpoint for sending emails. */
+const RESEND_API_URL = 'https://api.resend.com/emails'
+
+/**
+ * Resend implementation of EmailProvider.
+ *
+ * This is the ONLY file in the email module that knows about Resend.
+ * Every other file is completely unaware of which provider is active.
+ *
+ * ─── HOW TO REPLACE THIS PROVIDER ──────────────────────────────────────────
+ *  1. Create a new file in `providers/` (e.g., `providers/sendgrid.ts`).
+ *  2. Export a class that implements `EmailProvider` (a single method: `send`).
+ *  3. In `email.service.ts`, replace `new ResendEmailProvider(...)` with
+ *     your new class in the `createProvider()` function.
+ *  4. Update the environment variables in `types.ts` and `wrangler.jsonc`.
+ *  5. No other file in the project needs to be modified.
+ *
+ * Resend API Documentation: https://resend.com/docs/api-reference/emails/send-email
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export class ResendEmailProvider implements EmailProvider {
+  private readonly apiKey: string
+
+  /** When `true`, errors are logged to the console (development only). */
+  private readonly isDev: boolean
+
+  constructor(apiKey: string, isDev = false) {
+    this.apiKey = apiKey
+    this.isDev = isDev
+  }
+
+  /**
+   * Sends the email via the Resend REST API (`POST /emails`).
+   *
+   * Throws an exception if Resend responds with a non-2xx status, so that
+   * the caller (`email.service.ts`) can decide whether to propagate the error
+   * or handle it silently (fire-and-forget).
+   *
+   * The response body is read for logging only in the development environment,
+   * to avoid unnecessarily consuming the body stream in production.
+   */
+  async send(email: OutboundEmail): Promise<void> {
+    const response = await fetch(RESEND_API_URL, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        },
+      body: JSON.stringify(email),
+    })
+
+    if (!response.ok) {
+      const detail = this.isDev
+        ? await response.text()
+        : `HTTP ${response.status}`
+      throw new Error(`[ResendEmailProvider] send failed — ${detail}`)
+    }
+  }
+}