@beechcms/api 0.4.0-preview.8 → 0.4.0

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

@@ -1,80 +1,80 @@
-/**
- * Email Service — orchestratore del modulo email di Beech CMS.
- *
- * Pipeline di invio:
- *   chiamante → funzione service → template builder → provider → Resend (o altro)
- *
- * Questo è l'unico file che importa sia dai template che dal provider.
- * Nessun altro layer conosce l'intera pipeline.
- *
- * ─── CAMBIO PROVIDER ─────────────────────────────────────────────────────────
- * Per sostituire Resend con un altro servizio, modifica SOLO la funzione
- * `createProvider()` qui sotto: cambia l'import e l'istanziazione.
- * Nessun altro file del modulo — né nel resto del progetto — va toccato.
- * ─────────────────────────────────────────────────────────────────────────────
- */
-import { ResendEmailProvider } from './providers/resend'
-import { buildPasswordResetEmail } from './templates/password-reset'
-import { buildPasswordChangedEmail } from './templates/password-changed'
-import type { EmailProvider } from './email.provider'
-import type {
-  PasswordResetEmailParams,
-  PasswordChangedEmailParams,
-} from './email.types'
-
-/** Indirizzo mittente di default (mittente di test Resend, funziona senza dominio verificato). */
-const DEFAULT_FROM = 'Beech CMS <onboarding@resend.dev>'
-
-/**
- * Istanzia il provider email attivo.
- *
- * Questo è il punto singolo di cambio provider: sostituisci la riga
- * `new ResendEmailProvider(…)` con qualsiasi classe che implementi `EmailProvider`.
- */
-function createProvider(apiKey: string, isDev: boolean): EmailProvider {
-  return new ResendEmailProvider(apiKey, isDev)
-}
-
-/**
- * Invia l'email con il link di reset password al destinatario specificato.
- *
- * Il corpo dell'email è costruito dal template localizzato in
- * `templates/password-reset.ts` e composto con il layout base in
- * `templates/shell.ts`.
- *
- * @throws Se il provider rifiuta la richiesta. Il chiamante decide se propagare
- *         l'errore (fail della request) o gestirlo silenziosamente (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,
-  })
-}
-
-/**
- * Invia la notifica di sicurezza "password modificata" al proprietario dell'account.
- *
- * Chiamata dopo un reset password riuscito per avvisare l'utente. Non ha un
- * pulsante CTA — è una pura notifica, nessuna azione richiesta all'utente.
- *
- * @throws Se il provider rifiuta la richiesta.
- */
-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,
-  })
-}
+/**
+ * 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 type { EmailProvider } from './email.provider'
+import type {
+  PasswordResetEmailParams,
+  PasswordChangedEmailParams,
+} 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,
+  })
+}

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

@@ -1,98 +1,98 @@
-/**
- * Tipi condivisi del modulo email di Beech CMS.
- *
- * Tutti i tipi usati tra provider, service e template sono definiti qui
- * in modo che ogni layer rimanga disaccoppiato dagli altri.
- */
-
-// ── Locale ────────────────────────────────────────────────────────────────────
-
-/**
- * Lingue supportate dal sistema di template email.
- *
- * Per aggiungere una nuova lingua:
- *  1. Aggiungi il codice ISO qui (es. `'fr'`).
- *  2. Aggiungi la traduzione corrispondente nell'oggetto `COPY` di ogni
- *     file in `templates/`. TypeScript segnalerà le chiavi mancanti.
- */
-export const SUPPORTED_EMAIL_LOCALES = ['en', 'it'] as const
-export type EmailLocale = (typeof SUPPORTED_EMAIL_LOCALES)[number]
-
-/**
- * Risolve una stringa locale non verificata (es. dal body di una request)
- * a un valore `EmailLocale` supportato. Qualsiasi valore sconosciuto
- * ricade su `'en'` in modo sicuro.
- *
- * @param raw - Valore grezzo dal client (può essere qualsiasi cosa).
- * @returns Un `EmailLocale` valido, sempre.
- */
-export function resolveEmailLocale(raw: unknown): EmailLocale {
-  if (
-    typeof raw === 'string' &&
-    (SUPPORTED_EMAIL_LOCALES as readonly string[]).includes(raw)
-  ) {
-    return raw as EmailLocale
-  }
-  return 'en'
-}
-
-// ── Messaggio outbound ────────────────────────────────────────────────────────
-
-/**
- * Il messaggio email risolto che il provider riceve e invia.
- * Viene costruito dal service combinando i parametri della chiamata
- * con l'output del template builder.
- */
-export interface OutboundEmail {
-  /** Indirizzo mittente in formato RFC 5321 (es. "Beech CMS <noreply@beechcms.dev>"). */
-  from: string
-  /** Lista degli indirizzi destinatari. Deve contenere almeno un elemento. */
-  to: string[]
-  subject: string
-  /** Corpo HTML completo. Deve essere un documento HTML valido (vedi `templates/shell.ts`). */
-  html: string
-}
-
-// ── Parametri delle funzioni del service ──────────────────────────────────────
-
-/**
- * Parametri condivisi da ogni funzione di invio email in `email.service.ts`.
- * Le funzioni specifiche estendono questo tipo con i campi aggiuntivi
- * necessari al proprio template.
- */
-export interface BaseEmailParams {
-  /** Indirizzo del destinatario principale. */
-  to: string
-  /** Lingua del corpo email. Usa `resolveEmailLocale()` prima di passarlo qui. */
-  locale: EmailLocale
-  /**
-   * API key Resend (o del provider attivo). Deve essere non vuota —
-   * il chiamante è responsabile di validarla prima di invocare il service.
-   */
-  apiKey: string
-  /**
-   * Indirizzo mittente in formato RFC 5321.
-   * Default: "Beech CMS <onboarding@resend.dev>" (mittente di test Resend).
-   * In produzione, impostare un indirizzo verificato tramite la variabile
-   * d'ambiente `EMAIL_FROM`.
-   */
-  from?: string
-  /**
-   * Quando `true`, gli errori del provider vengono loggati in console.
-   * Impostare `false` in produzione per non esporre dettagli interni.
-   */
-  isDev?: boolean
-}
-
-/** Parametri per l'email di reset password — aggiunge l'URL di reset. */
-export interface PasswordResetEmailParams extends BaseEmailParams {
-  /**
-   * URL completo che l'utente clicca per impostare la nuova password.
-   * Contiene il token in chiaro come query param `?token=<uuid>`.
-   * Costruito dal chiamante come `${APP_URL}/reset-password?token=${token}`.
-   */
-  resetUrl: string
-}
-
-/** Parametri per la notifica "password modificata". Nessun campo aggiuntivo. */
-export type PasswordChangedEmailParams = BaseEmailParams
+/**
+ * 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

package/src/features/email/index.ts

@@ -1,28 +1,28 @@
-/**
- * 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 } from './email.service'
-export {
-  resolveEmailLocale,
-  SUPPORTED_EMAIL_LOCALES,
-} from './email.types'
-export type {
-  EmailLocale,
-  PasswordResetEmailParams,
-  PasswordChangedEmailParams,
-} from './email.types'
+/**
+ * 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 } from './email.service'
+export {
+  resolveEmailLocale,
+  SUPPORTED_EMAIL_LOCALES,
+} from './email.types'
+export type {
+  EmailLocale,
+  PasswordResetEmailParams,
+  PasswordChangedEmailParams,
+} from './email.types'

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

@@ -1,63 +1,63 @@
-/// <reference types="@cloudflare/workers-types" />
-import type { EmailProvider } from '../email.provider'
-import type { OutboundEmail } from '../email.types'
-
-/** Endpoint REST di Resend per l'invio email. */
-const RESEND_API_URL = 'https://api.resend.com/emails'
-
-/**
- * Implementazione Resend di EmailProvider.
- *
- * Questo è l'UNICO file del modulo email che conosce Resend.
- * Ogni altro file è completamente ignaro di quale provider sia attivo.
- *
- * ─── COME SOSTITUIRE QUESTO PROVIDER ─────────────────────────────────────────
- *  1. Crea un nuovo file in `providers/`  (es. `providers/sendgrid.ts`).
- *  2. Esporta una classe che implementa `EmailProvider`  (un solo metodo: `send`).
- *  3. In `email.service.ts` sostituisci `new ResendEmailProvider(…)` con la
- *     tua nuova classe nella funzione `createProvider()`.
- *  4. Aggiorna le variabili d'ambiente in `types.ts` e `wrangler.jsonc`.
- *  5. Nessun altro file nel progetto va modificato.
- *
- * Documentazione API Resend: https://resend.com/docs/api-reference/emails/send-email
- * ─────────────────────────────────────────────────────────────────────────────
- */
-export class ResendEmailProvider implements EmailProvider {
-  private readonly apiKey: string
-
-  /** Quando `true`, gli errori vengono loggati in console (solo in sviluppo). */
-  private readonly isDev: boolean
-
-  constructor(apiKey: string, isDev = false) {
-    this.apiKey = apiKey
-    this.isDev = isDev
-  }
-
-  /**
-   * Invia l'email tramite la REST API di Resend (`POST /emails`).
-   *
-   * Lancia un'eccezione se Resend risponde con uno status non-2xx, in modo
-   * che il chiamante (`email.service.ts`) possa decidere se propagare l'errore
-   * o gestirlo silenziosamente (fire-and-forget).
-   *
-   * Il corpo della response viene letto per il log solo in ambiente di sviluppo,
-   * per evitare di consumare il body stream in produzione inutilmente.
-   */
-  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] invio fallito — ${detail}`)
-    }
-  }
-}
+/// <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}`)
+    }
+  }
+}