@beechcms/api 0.4.0-preview.12 → 0.4.0-preview.13

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

@@ -1,59 +1,59 @@
-import type { EmailLocale } from '../email.types'
-import { buildEmailShell } from './shell'
-
-/**
- * Testi localizzati per la notifica di sicurezza "password modificata".
- *
- * ─── AGGIUNGERE UNA NUOVA LINGUA ─────────────────────────────────────────────
- * Vedi le istruzioni 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.',
-  },
-}
-
-/**
- * Costruisce l'email di notifica "password modificata".
- *
- * Questa email non ha un pulsante CTA — è una pura notifica di sicurezza.
- * Il blocco `warning` (testo rosso) avvisa l'utente di agire se non è
- * stato lui a modificare la password.
- *
- * @param locale - Lingua per oggetto e corpo dell'email.
- * @returns Oggetto con `subject` (stringa) e `html` (documento HTML completo).
- */
-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,
-    }),
-  }
-}
+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,64 @@
-import type { EmailLocale } from '../email.types'
-import { buildEmailShell } from './shell'
-
-/**
- * Testi localizzati per l'email di reset password.
- *
- * ─── AGGIUNGERE UNA NUOVA LINGUA ─────────────────────────────────────────────
- * 1. Aggiungi il codice ISO in `SUPPORTED_EMAIL_LOCALES` (email.types.ts).
- * 2. Aggiungi una chiave corrispondente in questo oggetto con tutti i campi.
- *    TypeScript segnala immediatamente le chiavi mancanti grazie a
- *    `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.',
-  },
-}
-
-/**
- * Costruisce l'email con il link di reset password.
- *
- * Compone il contenuto localizzato con il layout base (`buildEmailShell`)
- * iniettando il pulsante CTA che punta all'URL di reset.
- *
- * @param resetUrl - URL completo con il token in chiaro, es.
- *                   `https://dashboard.beechcms.dev/reset-password?token=<uuid>`.
- *                   Viene incorporato direttamente nel pulsante CTA — non sanificare
- *                   ulteriormente: il token è un UUID generato internamente.
- * @param locale   - Lingua per oggetto e corpo dell'email.
- * @returns Oggetto con `subject` (stringa) e `html` (documento HTML completo).
- */
-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,
-    }),
-  }
-}
+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,93 +1,92 @@
-import type { EmailLocale } from '../email.types'
-
-/**
- * Slot di contenuto che ogni template deve fornire per comporre un'email completa.
- * Ogni slot corrisponde a un blocco visivo nel layout della card email.
- */
-export interface EmailShellSlots {
-  /**
-   * Heading H2 mostrato in cima alla card. Mantienilo sotto ~50 caratteri
-   * per garantire una buona leggibilità su client mobile.
-   */
-  title: string
-
-  /**
-   * Testo principale del corpo. Renderizzato come paragrafo.
-   * È ammesso HTML inline sicuro (es. `<strong>`, `<a href="...">`),
-   * ma evita elementi block (`<p>`, `<div>`) che potrebbero rompere
-   * la struttura del layout in client email rigidi (Outlook, Gmail).
-   */
-  body: string
-
-  /**
-   * Pulsante call-to-action opzionale, renderizzato come link-button scuro.
-   * Ometti per email di sola notifica che non richiedono azione da parte dell'utente.
-   */
-  cta?: { label: string; href: string }
-
-  /**
-   * Paragrafo di avviso opzionale. Renderizzato in rosso (#ef4444) per attirare
-   * l'attenzione. Usalo per avvisi di sicurezza
-   * ("se non sei stato tu, agisci immediatamente").
-   */
-  warning?: string
-
-  /**
-   * Testo piccolo grigio in fondo alla card.
-   * Usato per note del tipo "notifica automatica, non rispondere".
-   */
-  footer: string
-}
-
-/**
- * Costruisce il layout HTML base condiviso da tutte le email transazionali
- * di Beech CMS.
- *
- * ─── FONTE UNICA DI VERITÀ PER IL BRANDING ───────────────────────────────────
- * Modificare questa funzione cambia l'aspetto visivo di TUTTE le email
- * in uscita contemporaneamente:
- *   - colore di sfondo e della card
- *   - stile del bordo e del border-radius
- *   - scala tipografica e spaziatura
- *   - stile del pulsante CTA
- *
- * Per cambiare il testo o la struttura di una email specifica, modifica invece
- * il file template corrispondente (`templates/password-reset.ts`, ecc.).
- * ─────────────────────────────────────────────────────────────────────────────
- *
- * @param locale - Usato per l'attributo `lang` del tag `<html>`.
- * @param slots  - Blocchi di contenuto iniettati nel layout.
- * @returns Un documento HTML completo e self-contained pronto per l'invio.
- */
-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>`
-}
+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 @@
-export { notificationsApp } from './notifications.handler'
+export { notificationsApp } from './notifications.handler'