@beechcms/api 0.4.0-preview.1

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

@@ -0,0 +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

package/src/features/email/index.ts

@@ -0,0 +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'

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

@@ -0,0 +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}`)
+    }
+  }
+}

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

@@ -0,0 +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,
+    }),
+  }
+}

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

@@ -0,0 +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,
+    }),
+  }
+}

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

@@ -0,0 +1,93 @@
+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>`
+}

package/src/features/notifications/index.ts

@@ -0,0 +1 @@
+export { notificationsApp } from './notifications.handler'

package/src/features/notifications/notifications.handler.ts

@@ -0,0 +1,88 @@
+/// <reference types="@cloudflare/workers-types" />
+import { Hono } from 'hono'
+import type { Env, Variables } from '../../types'
+
+const notificationsApp = new Hono<{ Bindings: Env; Variables: Variables }>()
+
+// GET /notifications — lista con ETag/304
+notificationsApp.get('/notifications', async (c) => {
+    try {
+        const { DB } = c.env
+
+        const stats = await DB.prepare(
+            'SELECT COUNT(*) as count, MAX(created_at) as latest, SUM(is_read) as read_sum FROM notifications'
+        ).first<{ count: number; latest: number | null; read_sum: number | null }>()
+
+        const count = stats?.count ?? 0
+        const latest = stats?.latest ?? 0
+        const readSum = stats?.read_sum ?? 0
+        const etag = `W/"${count}-${latest}-${readSum}"`
+
+        const ifNoneMatch = c.req.header('If-None-Match')
+        if (ifNoneMatch === etag) {
+            return new Response(null, { status: 304 })
+        }
+
+        const result = await DB.prepare(
+            'SELECT id, title, message, type, is_read, created_at FROM notifications ORDER BY created_at DESC LIMIT 50'
+        ).all()
+
+        c.header('ETag', etag)
+        c.header('Cache-Control', 'no-cache, must-revalidate')
+
+        return c.json(result.results ?? [])
+    } catch (err) {
+        console.error('Notifications fetch error:', err)
+        return c.json({ error: 'Failed to fetch notifications' }, 500)
+    }
+})
+
+
+// PATCH /notifications/:id/read — segna come letta
+notificationsApp.patch('/notifications/:id/read', async (c) => {
+    try {
+        const id = c.req.param('id')
+        const { DB } = c.env
+        await DB.prepare('UPDATE notifications SET is_read = 1 WHERE id = ?').bind(id).run()
+        return c.json({ success: true })
+    } catch (err) {
+        return c.json({ error: 'Failed to update notification' }, 500)
+    }
+})
+// PATCH /notifications/:id/unread - Segna come non letta
+notificationsApp.patch('/notifications/:id/unread', async (c) => {
+    try {
+        const id = c.req.param('id')
+        const { DB } = c.env
+        await DB.prepare('UPDATE notifications SET is_read = 0 WHERE id = ?').bind(id).run()
+        return c.json({ success: true })
+    } catch (err) {
+        return c.json({ error: 'Failed to update notification' }, 500)
+    }
+})
+
+
+// DELETE /notifications/:id — elimina notifica
+notificationsApp.delete('/notifications/:id', async (c) => {
+    try {
+        const id = c.req.param('id')
+        const { DB } = c.env
+        await DB.prepare('DELETE FROM notifications WHERE id = ?').bind(id).run()
+        return c.json({ success: true })
+    } catch (err) {
+        return c.json({ error: 'Failed to delete notification' }, 500)
+    }
+})
+
+
+// POST /notifications/mark-all-read — segna tutte come lette
+notificationsApp.post('/notifications/mark-all-read', async (c) => {
+    try {
+        const { DB } = c.env
+        await DB.prepare('UPDATE notifications SET is_read = 1').run()
+        return c.json({ success: true })
+    } catch (err) {
+        return c.json({ error: 'Failed to update notifications' }, 500)
+    }
+})
+export { notificationsApp }

package/src/features/password-reset/index.ts

@@ -0,0 +1,15 @@
+/// <reference types="@cloudflare/workers-types" />
+import { Hono } from 'hono'
+import type { Env, Variables } from '../../types'
+import { requestPasswordReset } from './request'
+import { resetPassword } from './reset'
+
+export const passwordResetApp = new Hono<{ Bindings: Env; Variables: Variables }>()
+
+// Feature flag: lets the dashboard know whether to show the forgot-password link
+passwordResetApp.get('/auth/features', (c) => {
+  return c.json({ passwordReset: Boolean(c.env.RESEND_API_KEY) })
+})
+
+passwordResetApp.post('/auth/forgot-password', requestPasswordReset)
+passwordResetApp.post('/auth/reset-password', resetPassword)

package/src/features/password-reset/request.ts

@@ -0,0 +1,88 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Context } from 'hono'
+import type { Env, Variables } from '../../types'
+import { sendPasswordResetEmail, resolveEmailLocale } from '../email'
+
+const TOKEN_EXPIRY_SECONDS = 30 * 60
+
+async function sha256hex(text: string): Promise<string> {
+  const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text))
+  return Array.from(new Uint8Array(buf))
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+export async function requestPasswordReset(
+  c: Context<{ Bindings: Env; Variables: Variables }>
+): Promise<Response> {
+  if (!c.env.RESEND_API_KEY) {
+    return c.json({ error: 'Not available' }, 503)
+  }
+
+  let body: Record<string, unknown>
+  try {
+    body = await c.req.json()
+  } catch {
+    return c.json({ error: 'Invalid request body' }, 400)
+  }
+
+  if (typeof body.email !== 'string' || !body.email.trim()) {
+    return c.json({ error: 'Invalid request' }, 400)
+  }
+
+  const email = body.email.trim().toLowerCase()
+  const locale = resolveEmailLocale(body.locale)
+
+  if (c.env.FORGOT_PASSWORD_RATE_LIMITER) {
+    const ip = c.req.raw.headers.get('cf-connecting-ip') ?? 'unknown'
+    const { success } = await c.env.FORGOT_PASSWORD_RATE_LIMITER.limit({ key: ip })
+    if (!success) {
+      return c.json({ error: 'Too many requests' }, 429)
+    }
+  }
+
+  // Sempre 200 per evitare user enumeration
+  const user = await c.env.DB
+    .prepare('SELECT id FROM users WHERE email = ?')
+    .bind(email)
+    .first<{ id: string }>()
+
+  if (!user) {
+    return c.json({ success: true })
+  }
+
+  // Invalida eventuali token pendenti per lo stesso utente prima di emetterne uno nuovo
+  await c.env.DB
+    .prepare('UPDATE password_reset_tokens SET used_at = unixepoch() WHERE user_id = ? AND used_at IS NULL')
+    .bind(user.id)
+    .run()
+
+  const token = crypto.randomUUID()
+  const tokenHash = await sha256hex(token)
+  const expiresAt = Math.floor(Date.now() / 1000) + TOKEN_EXPIRY_SECONDS
+
+  await c.env.DB
+    .prepare('INSERT INTO password_reset_tokens (id, user_id, token_hash, expires_at) VALUES (?, ?, ?, ?)')
+    .bind(crypto.randomUUID(), user.id, tokenHash, expiresAt)
+    .run()
+
+  const appUrl = (c.env.APP_URL ?? new URL(c.req.url).origin).replace(/\/$/, '')
+  const resetUrl = `${appUrl}/reset-password?token=${token}`
+
+  try {
+    await sendPasswordResetEmail({
+      to: email,
+      resetUrl,
+      locale,
+      apiKey: c.env.RESEND_API_KEY,
+      from: c.env.EMAIL_FROM,
+      isDev: c.env.ENV !== 'production',
+    })
+  } catch (err) {
+    if (c.env.ENV !== 'production') {
+      console.error('[password-reset] invio email fallito:', err)
+    }
+  }
+
+  return c.json({ success: true })
+}