SPB Git

Repository Public

templates-api.md 4.2 KB 51 lines markdown

1# SP Mail — studio de modèles : API de session23Routes pour le webmail et les apps (session cookie ou jeton natif ; non-GET : `Origin` + `X-SPMail: 1` côté web). Un modèle appartient à un utilisateur ; celui d'un autre répond 404.4Implémentation : `server/src/templates.ts`, `templates-ai.ts`, `template-sanitize.ts`. Tests : `server/src/template-sanitize.test.ts`, `tests/integration/templates.test.ts`.56## Objets78```jsonc9Template {10  "id": "uuid", "name": "…", "category": "transactional|notification|newsletter|announcement|personal|invitation|receipt|security|other",11  "subject": "Bonjour {{first_name}}", "preheader": "…",12  "variables": [{ "name": "first_name", "description": "…", "example": "Zoé", "required": true }],13  "brand": { "name"?: "…", "accent"?: "#4f46e5", "logo_url"?: "https://…", "tone"?: "…", "footer"?: "…", "website"?: "https://…" },14  "source": "manual|ai", "ai_model": "claude-opus-5-5"|null, "design_notes": "…", "version": 3,15  "created_at": "…", "updated_at": "…", "size_bytes": 14230,16  // seulement hors liste :17  "html": "<!DOCTYPE html>…", "text": "…", "ai_brief": "…"|null18}19```20Variables : `{{nom}}`, `nom` = `^[a-z][a-z0-9_]{0,39}$`. À l'enregistrement, le HTML est assaini (scripts, cadres, formulaires, gestionnaires, URL non http(s)/mailto, `@import`, `url()` non https retirés ; `<style>`, requêtes média, mode sombre et commentaires conditionnels Outlook conservés) et la liste `variables` est **réalignée** sur les variables réellement présentes dans l'objet, l'aperçu, le HTML et le texte.2122## Routes2324| Route | Corps → Réponse |25|---|---|26| `GET /api/templates` | → `{templates: Template[] (sans html/text), ai: {configured, model}, categories: string[]}` |27| `POST /api/templates` | `{name, html, category?, subject?, preheader?, text?, variables?, brand?}` → `Template` |28| `GET /api/templates/:id` | → `Template` |29| `PUT /api/templates/:id` | champs partiels + `note?` → `Template` (toute modification de contenu archive la version précédente ; un renommage seul non) |30| `DELETE /api/templates/:id` | → `{ok}` (archivage) |31| `POST /api/templates/:id/unarchive` | → `Template` (annule un archivage de moins de 30 jours) |32| `POST /api/templates/:id/duplicate` | → `Template` |33| `GET /api/templates/:id/versions` | → `[{version, subject, note, created_at, size_bytes}]` (50 dernières) |34| `GET /api/templates/:id/versions/:n` | → `{version, subject, preheader, html, text, variables, note, created_at}` |35| `POST /api/templates/:id/versions/:n/restore` | → `Template` (nouvelle version) |36| `POST /api/templates/:id/render` | `{values?: {nom: "valeur"}, use_examples?: true}` → `{subject, preheader, html, text, missing: string[]}` — valeurs échappées ; une valeur placée dans `href`/`src` doit être une URL http(s)/mailto, sinon `#` |37| `POST /api/templates/preview` | brouillon non enregistré `{html, subject?, preheader?, text?, variables?, values?}` → rendu + `variables` réalignées + `sanitized_html` |38| `POST /api/templates/generate` | `{brief (8–6000 car.), language: "fr"|"en", category?, brand?, base_template_id?}` → **`text/event-stream`** |39| `GET /api/templates/ai/usage` | → `{last_30_days: {generations, input_tokens, output_tokens}, model, configured}` |4041### Flux de `generate`4243```44event: start      data: {"model":"claude-opus-5-5","revising":false}45event: progress   data: {"chars":1234}            (tous les ~400 caractères ; des lignes « : ping » toutes les 15 s)46event: done       data: {"template": Template, "usage": {"input_tokens","output_tokens","model","seconds"}}47event: error      data: {"code":"ai_not_configured|ai_refused|ai_rate_limited|ai_output_truncated|ai_invalid_output|ai_unreachable|ai_error|cancelled","message":"…"}48```49Durée observée : 60 à 150 s. Sans `base_template_id` un nouveau modèle est créé ; avec, le modèle existant reçoit une nouvelle version (retouche décrite par `brief`). Fermer la connexion annule la génération. Limite : 30 générations par heure et par utilisateur ; `503 ai_not_configured` (JSON, hors flux) si aucune clé n'est configurée.50Seuls le brief, la marque et, pour une retouche, le modèle de base sont envoyés à l'API d'Anthropic — jamais de contenu de boîte aux lettres.51
Files main
Menu

Theme