Paramètres typés (npx frontmail types)

Les paramètres des modèles sont validés côté serveur, mais vous pouvez détecter les erreurs bien plus tôt : la CLI frontmail télécharge les schémas de paramètres de vos modèles et génère des types TypeScript. Dès lors, send() sait de quels paramètres chaque modèle a besoin.

Génération

FRONTMAIL_PRIVATE_KEY=sk_… npx frontmail types --out src/frontmail-env.d.ts

La CLI frontmail est fournie avec @frontmail/node. Installez-la comme dépendance de développement (npm install -D @frontmail/node) ou exécutez-la sans installation : npx -p @frontmail/node frontmail types.

Option	Par défaut	Signification
--out <file>	frontmail-env.d.ts	Où écrire les déclarations
--module <pkg>	Les paquets SDK trouvés dans votre package.json (tous les SDK s’il n’y en a aucun)	Paquet dont l’interface FrontmailTemplates est étendue ; répétez l’option pour plusieurs paquets
--api-url <url>	$FRONTMAIL_API_URL ou https://api.frontmail.dev	URL de base de l’API
--stdout	–	Affiche les déclarations au lieu d’écrire un fichier
-h, --help	–	Affiche l’aide

La clé privée est lue dans la variable d’environnement FRONTMAIL_PRIVATE_KEY (il n’existe pas d’option pour elle, afin qu’elle ne finisse pas dans l’historique de votre shell). La commande appelle GET /v1/templates ; exécutez-la en local ou en CI, jamais dans le navigateur. Vérifiez que le fichier généré est inclus par votre tsconfig.json.

Ce qui est généré

Pour un projet qui dépend de @frontmail/browser :

src/frontmail-env.d.ts

// Generated by `frontmail types`. Do not edit by hand – re-run the command instead.
/* eslint-disable */

/** Contact form (tpl_01J9ZCONTACT) */
export interface ContactFormParams {
  /** Votre nom */
  name: string;
  /** email address */
  email: string;
  topic?: "sales" | "support" | "other";
  /** multi-line text */
  message: string;
  newsletter?: boolean;
}

/** Order confirmation (tpl_01J9ZORDER) */
export interface OrderConfirmationParams {
  order_id: string;
  items: Array<{
    title: string;
    qty: number;
    price: number;
  }>;
  total: number;
  /** date – ISO 8601 (`YYYY-MM-DD` or full timestamp) */
  delivery_date?: string;
}

/** Template id → params. */
export interface FrontmailTemplates {
  "tpl_01J9ZCONTACT": ContactFormParams;
  "tpl_01J9ZORDER": OrderConfirmationParams;
}

export type FrontmailTemplateId = keyof FrontmailTemplates;

declare module "@frontmail/browser" {
  interface FrontmailTemplates {
    "tpl_01J9ZCONTACT": ContactFormParams;
    "tpl_01J9ZORDER": OrderConfirmationParams;
  }
}

Correspondance des types : string, text, email, url, html → string ; number → number ; boolean → boolean ; date → string ; enum → union de littéraux ; list → tableau d’objets issus de itemFields. Les paramètres ayant une valeur default sont facultatifs.

Utilisation

import { send } from '@frontmail/browser';

await send('svc_01J9…', 'tpl_01J9ZCONTACT', { name: 'Jana', email: 'jana@example.com', message: 'Bonjour' }); // ✓
await send('svc_01J9…', 'tpl_01J9ZCONTACT', { name: 'Jana' });
//                                          ~~~~~~~~~~~~~~ Property 'email' is missing

L’argument d’identifiant de modèle propose l’autocomplétion des identifiants connus. Les identifiants inconnus compilent quand même, avec des paramètres lâches de type Record<string, unknown> : ajouter un modèle ne casse donc pas votre build.

Régénérez les types après avoir modifié le schéma d’un modèle – par exemple dans un script prebuild ou dans une étape de CI qui échoue lorsque le fichier commité n’est plus à jour.