@beechcms/api 0.4.0-preview.1

package/src/features/draft/draft.handler.ts

@@ -0,0 +1,198 @@
+/// <reference types="@cloudflare/workers-types" />
+import { Hono } from 'hono'
+import { validateAndSanitizeSeedPayload, resolvePolicies, serializeForDb, deserializeFromDb } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+import { publicProblem } from '../../public/problem-details'
+import { logActivity } from '../../shared/activity-logger'
+import { cleanStr } from '../../shared/query-utils'
+import { applyVisibility } from '../../shared/apply-policies'
+
+type Bindings = { DB: D1Database }
+type Variables = {
+  jwtPayload: { sub: string; email?: string }
+  getSeed: (slug: string) => Seed | null
+  seedRegistry: Record<string, Seed>
+}
+
+const draftApp = new Hono<{ Bindings: Bindings; Variables: Variables }>()
+
+function normalizeBody(raw: unknown): Record<string, unknown> {
+  return typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>) : {}
+}
+
+function draftNotAllowed(c: Parameters<typeof publicProblem>[0]) {
+  return publicProblem(c, {
+    type: 'draft-not-allowed', title: 'Method Not Allowed', status: 405,
+    detail: 'This content type does not support pending drafts. Set allowDrafts: true on the Seed to enable.',
+  })
+}
+
+// PUT /:slug/:id/draft — crea o sovrascrive la bozza in content_{slug}_drafts
+draftApp.put('/:slug/:id/draft', async (c) => {
+  const slug = c.req.param('slug')
+  const id = c.req.param('id')
+
+  const seed = c.get('getSeed')(slug)
+  if (!seed) return publicProblem(c, { type: 'content-seed-not-found', title: 'Not Found', status: 404, detail: 'Seed not found' })
+  if (!seed.allowDrafts) return draftNotAllowed(c)
+
+  let body: Record<string, unknown>
+  try {
+    body = normalizeBody(await c.req.json<unknown>())
+  } catch {
+    return publicProblem(c, { type: 'content-invalid-json', title: 'Bad Request', status: 400, detail: 'Invalid JSON body' })
+  }
+
+  const { DB } = c.env
+  const existing = await DB.prepare(`SELECT id FROM content_${slug} WHERE id = ?`).bind(id).first<{ id: string }>()
+  if (!existing) return publicProblem(c, { type: 'content-not-found', title: 'Not Found', status: 404, detail: 'Not found' })
+
+  const sensitiveAliases = Object.keys(body).filter((alias) => {
+    const branch = seed.branches.find((b) => b.alias === alias)
+    return branch != null && resolvePolicies(branch).privacy !== 'plain'
+  })
+  if (sensitiveAliases.length > 0) {
+    return publicProblem(c, { type: 'content-sensitive-field-edit', title: 'Unprocessable Entity', status: 422, detail: `Cannot draft sensitive fields: ${sensitiveAliases.join(', ')}` })
+  }
+
+  const validation = validateAndSanitizeSeedPayload(seed, body, {
+    operation: 'update', allowNull: true, requireAtLeastOneValidField: true, enforceRequiredFields: false,
+  })
+  if (validation.dangerousFields.length > 0) {
+    return publicProblem(c, { type: 'content-dangerous-content', title: 'Unprocessable Entity', status: 422, detail: `Dangerous markup in field '${validation.dangerousFields[0]}'` })
+  }
+  if (validation.details.length > 0) {
+    return publicProblem(c, { type: 'content-validation-failed', title: 'Bad Request', status: 400, detail: 'Validation failed', errors: validation.details })
+  }
+
+  // UPSERT in content_{slug}_drafts — solo colonne branch, nullable
+  const draftTable = `content_${slug}_drafts`
+  const cols: string[] = []
+  const placeholders: string[] = []
+  const bindings: (string | number | null)[] = []
+  for (const branch of seed.branches) {
+    if (Object.hasOwn(validation.data, branch.alias)) {
+      cols.push(branch.alias)
+      placeholders.push('?')
+      bindings.push(serializeForDb(branch, validation.data[branch.alias]))
+    }
+  }
+
+  const now = Math.floor(Date.now() / 1000)
+  const updateSet = cols.map((c) => `${c} = excluded.${c}`).join(', ')
+  await DB.prepare(
+    `INSERT INTO ${draftTable} (entry_id, ${cols.join(', ')}, updated_at)
+     VALUES (?, ${placeholders.join(', ')}, ?)
+     ON CONFLICT(entry_id) DO UPDATE SET ${updateSet}, updated_at = excluded.updated_at`
+  ).bind(id, ...bindings, now).run()
+
+  logActivity(c, {
+    action: 'update', entityType: 'content', entityId: id, entitySlug: slug,
+    details: { title: cleanStr(validation.data[seed.displayNameAlias]) ?? id, note: 'draft saved' },
+  })
+
+  return c.json({ success: true })
+})
+
+// GET /:slug/:id/draft — legge la bozza pendente
+draftApp.get('/:slug/:id/draft', async (c) => {
+  const slug = c.req.param('slug')
+  const id = c.req.param('id')
+
+  const seed = c.get('getSeed')(slug)
+  if (!seed) return publicProblem(c, { type: 'content-seed-not-found', title: 'Not Found', status: 404, detail: 'Seed not found' })
+  if (!seed.allowDrafts) return draftNotAllowed(c)
+
+  const { DB } = c.env
+  const row = await DB.prepare(`SELECT * FROM content_${slug}_drafts WHERE entry_id = ?`)
+    .bind(id)
+    .first<Record<string, unknown>>()
+
+  if (!row) {
+    // Verifica se entry esiste
+    const entry = await DB.prepare(`SELECT id FROM content_${slug} WHERE id = ?`).bind(id).first()
+    if (!entry) return publicProblem(c, { type: 'content-not-found', title: 'Not Found', status: 404, detail: 'Not found' })
+    return publicProblem(c, { type: 'draft-not-found', title: 'Not Found', status: 404, detail: 'No pending draft for this entry' })
+  }
+
+  // Deserializza colonne branch reali
+  const data: Record<string, unknown> = {}
+  for (const branch of seed.branches) {
+    if (Object.hasOwn(row, branch.alias)) {
+      data[branch.alias] = deserializeFromDb(branch, row[branch.alias] ?? null)
+    }
+  }
+
+  return c.json({ data: applyVisibility(data, seed) })
+})
+
+// POST /:slug/:id/draft/publish — promuove bozza → live atomicamente
+draftApp.post('/:slug/:id/draft/publish', async (c) => {
+  const slug = c.req.param('slug')
+  const id = c.req.param('id')
+
+  const seed = c.get('getSeed')(slug)
+  if (!seed) return publicProblem(c, { type: 'content-seed-not-found', title: 'Not Found', status: 404, detail: 'Seed not found' })
+  if (!seed.allowDrafts) return draftNotAllowed(c)
+
+  const { DB } = c.env
+  const draftRow = await DB.prepare(`SELECT * FROM content_${slug}_drafts WHERE entry_id = ?`)
+    .bind(id)
+    .first<Record<string, unknown>>()
+
+  if (!draftRow) {
+    const entry = await DB.prepare(`SELECT id FROM content_${slug} WHERE id = ?`).bind(id).first()
+    if (!entry) return publicProblem(c, { type: 'content-not-found', title: 'Not Found', status: 404, detail: 'Not found' })
+    return publicProblem(c, { type: 'draft-not-found', title: 'Not Found', status: 404, detail: 'No pending draft to publish' })
+  }
+
+  // Costruisce SET clause dal draft per UPDATE atomico
+  const now = Math.floor(Date.now() / 1000)
+  const setParts: string[] = ['status = ?', 'updated_at = ?']
+  const setBindings: (string | number | null)[] = ['published', now]
+
+  for (const branch of seed.branches) {
+    if (Object.hasOwn(draftRow, branch.alias) && draftRow[branch.alias] !== null) {
+      setParts.push(`${branch.alias} = ?`)
+      setBindings.push(draftRow[branch.alias] as string | number | null)
+    }
+  }
+
+  await DB.batch([
+    DB.prepare(`UPDATE content_${slug} SET ${setParts.join(', ')} WHERE id = ?`)
+      .bind(...setBindings, id),
+    DB.prepare(`DELETE FROM content_${slug}_drafts WHERE entry_id = ?`)
+      .bind(id),
+  ])
+
+  // Deserializza per activity log
+  const displayValue = draftRow[seed.displayNameAlias]
+  const displayStr = typeof displayValue === 'string' ? displayValue : id
+
+  logActivity(c, {
+    action: 'update', entityType: 'content', entityId: id, entitySlug: slug,
+    details: { title: displayStr, note: 'draft published' },
+  })
+
+  return c.json({ success: true })
+})
+
+// DELETE /:slug/:id/draft — scarta la bozza pendente
+draftApp.delete('/:slug/:id/draft', async (c) => {
+  const slug = c.req.param('slug')
+  const id = c.req.param('id')
+
+  const seed = c.get('getSeed')(slug)
+  if (!seed) return publicProblem(c, { type: 'content-seed-not-found', title: 'Not Found', status: 404, detail: 'Seed not found' })
+  if (!seed.allowDrafts) return draftNotAllowed(c)
+
+  const { DB } = c.env
+  const existing = await DB.prepare(`SELECT id FROM content_${slug} WHERE id = ?`).bind(id).first<{ id: string }>()
+  if (!existing) return publicProblem(c, { type: 'content-not-found', title: 'Not Found', status: 404, detail: 'Not found' })
+
+  await DB.prepare(`DELETE FROM content_${slug}_drafts WHERE entry_id = ?`).bind(id).run()
+
+  return c.json({ success: true })
+})
+
+export { draftApp }

package/src/features/draft/draft.test.ts

@@ -0,0 +1,315 @@
+/// <reference types="@cloudflare/workers-types" />
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { Seed } from '@beechcms/core'
+
+// --- Mock jose (auth bypass) ---
+const mockJwtVerify = vi.hoisted(() => vi.fn())
+vi.mock('jose', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('jose')>()
+  return { ...actual, jwtVerify: mockJwtVerify }
+})
+
+// --- Seed di test (hoisted so they're available inside vi.mock factory) ---
+const { DRAFT_SEED, NO_DRAFT_SEED } = vi.hoisted(() => {
+  const DRAFT_SEED = {
+    slug: 'test-articoli',
+    label: 'Articolo',
+    displayNameAlias: 'title',
+    allowDrafts: true,
+    branches: [
+      { id: 'br_01', alias: 'title', label: 'Titolo', type: 'text', requiredOnCreate: true },
+      { id: 'br_02', alias: 'body', label: 'Corpo', type: 'text' },
+    ],
+  }
+  const NO_DRAFT_SEED = {
+    slug: 'test-messaggi',
+    label: 'Messaggio',
+    displayNameAlias: 'name',
+    branches: [
+      { id: 'br_01', alias: 'name', label: 'Nome', type: 'text' },
+    ],
+  }
+  return { DRAFT_SEED, NO_DRAFT_SEED }
+})
+
+vi.mock('@beechcms/core', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@beechcms/core')>()
+  return {
+    ...actual,
+    SEED_REGISTRY: {
+      ...actual.SEED_REGISTRY,
+      'test-articoli': DRAFT_SEED,
+      'test-messaggi': NO_DRAFT_SEED,
+    },
+    getSeed: (slug: string) => {
+      if (slug === 'test-articoli') return DRAFT_SEED
+      if (slug === 'test-messaggi') return NO_DRAFT_SEED
+      return actual.getSeed(slug)
+    },
+  }
+})
+
+import app from '../../index'
+
+// --- Helpers ---
+
+const ENTRY_ID = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
+
+function makeAuthHeader() {
+  return { Authorization: 'Bearer test-token' }
+}
+
+/**
+ * v0.4.0 Helper: returns a row as it would appear in content_{slug} 
+ */
+function makeLiveRow(overrides: Record<string, any> = {}) {
+  return {
+    id: ENTRY_ID,
+    slug: 'test-article',
+    status: 'published',
+    title: 'Titolo live',
+    body: 'Corpo live',
+    created_at: 1_000_000,
+    updated_at: 1_000_000,
+    ...overrides
+  }
+}
+
+/**
+ * v0.4.0 Helper: returns a row as it would appear in content_{slug}_drafts
+ */
+function makeDraftRow(overrides: Record<string, any> = {}) {
+  return {
+    entry_id: ENTRY_ID,
+    title: 'Titolo in bozza',
+    body: 'Corpo in bozza',
+    updated_at: 1_000_001,
+    ...overrides
+  }
+}
+
+function makeMockDB(options: { 
+  liveRow?: object | null, 
+  draftRow?: object | null,
+  bindCalls?: Array<{ sql: string; args: unknown[] }>
+} = {}) {
+  const { liveRow = null, draftRow = null, bindCalls = [] } = options
+
+  const prepare = vi.fn((sql: string) => ({
+    bind: vi.fn((...args: unknown[]) => {
+      bindCalls.push({ sql, args })
+      return {
+        first: vi.fn(async () => {
+          if (sql.includes('_drafts')) return draftRow
+          return liveRow
+        }),
+        run: vi.fn(async () => ({ success: true, meta: { changes: 1 } })),
+        all: vi.fn(async () => ({ results: [] })),
+      }
+    }),
+    first: vi.fn(async () => {
+       if (sql.includes('_drafts')) return draftRow
+       return liveRow
+    }),
+    run: vi.fn(async () => ({ success: true, meta: { changes: 1 } })),
+  }))
+
+  return {
+    prepare,
+    batch: vi.fn(async (stmts: any[]) => {
+      // In tests, we just assume they run fine
+      return stmts.map(() => ({ success: true }))
+    })
+  } as unknown as D1Database
+}
+
+// --- Suite ---
+
+describe('Draft feature — PUT /:slug/:id/draft', () => {
+  beforeEach(() => {
+    mockJwtVerify.mockReset()
+    mockJwtVerify.mockResolvedValue({
+      payload: { sub: 'user-1', email: 'admin@beech.local' },
+      protectedHeader: { alg: 'HS256', typ: 'JWT' },
+    })
+  })
+
+  it('returns 200 when draft is saved', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', ...makeAuthHeader() },
+        body: JSON.stringify({ title: 'Bozza titolo' }),
+      },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow() }) }
+    )
+    expect(res.status).toBe(200)
+    const json = await res.json<{ success: boolean }>()
+    expect(json.success).toBe(true)
+  })
+
+  it('stores aliases as column names in content_{slug}_drafts', async () => {
+    const bindCalls: Array<{ sql: string; args: unknown[] }> = []
+    const mockDB = makeMockDB({ liveRow: makeLiveRow(), bindCalls })
+
+    await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', ...makeAuthHeader() },
+        body: JSON.stringify({ title: 'Titolo in bozza' }),
+      },
+      { JWT_SECRET: 'test-secret', DB: mockDB }
+    )
+
+    const upsertCall = bindCalls.find((c) => c.sql.includes('INSERT INTO content_test-articoli_drafts'))
+    expect(upsertCall).toBeDefined()
+    // Column 'title' should be present in the SQL
+    expect(upsertCall!.sql).toContain('title')
+    // The value should be the second bind (first is ID)
+    expect(upsertCall!.args[1]).toBe('Titolo in bozza')
+  })
+
+  it('returns 405 when seed does not allow drafts', async () => {
+    const res = await app.request(
+      `/api/content/test-messaggi/${ENTRY_ID}/draft`,
+      {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', ...makeAuthHeader() },
+        body: JSON.stringify({ name: 'test' }),
+      },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow() }) }
+    )
+    expect(res.status).toBe(405)
+  })
+
+  it('returns 404 when entry does not exist', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', ...makeAuthHeader() },
+        body: JSON.stringify({ title: 'Test' }),
+      },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: null }) }
+    )
+    expect(res.status).toBe(404)
+  })
+})
+
+describe('Draft feature — GET /:slug/:id/draft', () => {
+  beforeEach(() => {
+    mockJwtVerify.mockReset()
+    mockJwtVerify.mockResolvedValue({
+      payload: { sub: 'user-1', email: 'admin@beech.local' },
+      protectedHeader: { alg: 'HS256', typ: 'JWT' },
+    })
+  })
+
+  it('returns draft data with aliases', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      { headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow(), draftRow: makeDraftRow() }) }
+    )
+    expect(res.status).toBe(200)
+    const json = await res.json<{ data: Record<string, unknown> }>()
+    expect(json.data.title).toBe('Titolo in bozza')
+    expect(json.data.body).toBe('Corpo in bozza')
+  })
+
+  it('returns 404 when no draft exists', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      { headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow(), draftRow: null }) }
+    )
+    expect(res.status).toBe(404)
+  })
+
+  it('returns 404 when entry does not exist', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      { headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: null }) }
+    )
+    expect(res.status).toBe(404)
+  })
+})
+
+describe('Draft feature — POST /:slug/:id/draft/publish', () => {
+  beforeEach(() => {
+    mockJwtVerify.mockReset()
+    mockJwtVerify.mockResolvedValue({
+      payload: { sub: 'user-1', email: 'admin@beech.local' },
+      protectedHeader: { alg: 'HS256', typ: 'JWT' },
+    })
+  })
+
+  it('returns 200 and promotes draft to live', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft/publish`,
+      { method: 'POST', headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow(), draftRow: makeDraftRow() }) }
+    )
+    expect(res.status).toBe(200)
+    const json = await res.json<{ success: boolean }>()
+    expect(json.success).toBe(true)
+  })
+
+  it('uses DB.batch to update live table and delete draft', async () => {
+    const mockDB = makeMockDB({ liveRow: makeLiveRow(), draftRow: makeDraftRow() })
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft/publish`,
+      { method: 'POST', headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: mockDB }
+    )
+    expect(res.status).toBe(200)
+    expect(mockDB.batch).toHaveBeenCalled()
+  })
+
+  it('returns 404 when no pending draft exists', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft/publish`,
+      { method: 'POST', headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow(), draftRow: null }) }
+    )
+    expect(res.status).toBe(404)
+  })
+})
+
+describe('Draft feature — DELETE /:slug/:id/draft', () => {
+  beforeEach(() => {
+    mockJwtVerify.mockReset()
+    mockJwtVerify.mockResolvedValue({
+      payload: { sub: 'user-1', email: 'admin@beech.local' },
+      protectedHeader: { alg: 'HS256', typ: 'JWT' },
+    })
+  })
+
+  it('returns 200 when draft is discarded', async () => {
+    const res = await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      { method: 'DELETE', headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: makeMockDB({ liveRow: makeLiveRow(), draftRow: makeDraftRow() }) }
+    )
+    expect(res.status).toBe(200)
+    const json = await res.json<{ success: boolean }>()
+    expect(json.success).toBe(true)
+  })
+
+  it('issues DELETE FROM content_{slug}_drafts', async () => {
+    const bindCalls: Array<{ sql: string; args: unknown[] }> = []
+    const mockDB = makeMockDB({ liveRow: makeLiveRow(), bindCalls })
+
+    await app.request(
+      `/api/content/test-articoli/${ENTRY_ID}/draft`,
+      { method: 'DELETE', headers: makeAuthHeader() },
+      { JWT_SECRET: 'test-secret', DB: mockDB }
+    )
+
+    const deleteCall = bindCalls.find((c) => c.sql.includes('DELETE FROM content_test-articoli_drafts'))
+    expect(deleteCall).toBeDefined()
+  })
+})

package/src/features/draft/index.ts

@@ -0,0 +1 @@
+export { draftApp } from './draft.handler'

package/src/features/email/email.provider.ts

@@ -0,0 +1,38 @@
+import type { OutboundEmail } from './email.types'
+
+/**
+ * EmailProvider — contratto formale per i provider di invio email.
+ *
+ * Ogni implementazione (Resend, SendGrid, Mailgun, SMTP, …) DEVE rispettare
+ * questa interfaccia. È l'unico punto di accoppiamento tra il modulo email e
+ * qualsiasi servizio esterno di terze parti.
+ *
+ * ─── COME CAMBIARE PROVIDER ──────────────────────────────────────────────────
+ *  1. Crea un nuovo file sotto `providers/`  (es. `providers/sendgrid.ts`).
+ *  2. Esporta una classe che implementa questa interfaccia.
+ *  3. In `email.service.ts` sostituisci l'import e l'istanziazione del provider
+ *     attuale con la tua nuova classe nella funzione `createProvider()`.
+ *  4. Aggiorna le variabili d'ambiente necessarie in `types.ts` e `wrangler.jsonc`.
+ *  5. Nessun altro file del progetto va toccato.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+export interface EmailProvider {
+  /**
+   * Invia una singola email transazionale.
+   *
+   * @param email - Il messaggio completamente risolto: mittente, destinatario,
+   *               oggetto e corpo HTML. Usa i builder in `templates/` per
+   *               costruire questo oggetto in modo corretto.
+   *
+   * @returns Promise che si risolve quando il provider ha **accettato** il
+   *          messaggio per la consegna. L'accettazione non garantisce la ricezione
+   *          in inbox — quella dipende dal server del destinatario e dalla
+   *          deliverability del provider.
+   *
+   * @throws {Error} Se il provider rifiuta la richiesta (autenticazione fallita,
+   *                 errore di rete, payload non valido). Il chiamante
+   *                 (`email.service.ts`) è responsabile di catturare e gestire
+   *                 questo errore in modo appropriato.
+   */
+  send(email: OutboundEmail): Promise<void>
+}

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

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