Parametri tipizzati (npx frontmail types)

I parametri dei modelli vengono validati sul server, ma puoi intercettare gli errori molto prima: la CLI frontmail scarica gli schemi dei parametri dei tuoi modelli e genera i tipi TypeScript. Da quel momento send() sa di quali parametri ha bisogno ogni modello.

Generazione

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

La CLI frontmail è inclusa in @frontmail/node. Installala come dipendenza di sviluppo (npm install -D @frontmail/node) oppure eseguila senza installarla: npx -p @frontmail/node frontmail types.

Opzione	Predefinito	Significato
--out <file>	frontmail-env.d.ts	Dove scrivere le dichiarazioni
--module <pkg>	I pacchetti SDK trovati nel tuo package.json (tutti gli SDK se non ce ne sono)	Pacchetto la cui interfaccia FrontmailTemplates viene estesa; ripetila per più pacchetti
--api-url <url>	$FRONTMAIL_API_URL o https://api.frontmail.dev	URL di base dell’API
--stdout	–	Stampa le dichiarazioni invece di scrivere un file
-h, --help	–	Mostra l’aiuto

La chiave privata viene letta dalla variabile d’ambiente FRONTMAIL_PRIVATE_KEY (non esiste un flag apposito, così non finisce nella cronologia della shell). Il comando chiama GET /v1/templates; eseguilo in locale o nella CI, mai nel browser. Assicurati che il file di output sia incluso dal tuo tsconfig.json.

Cosa viene generato

Per un progetto che dipende da @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 {
  /** Il tuo nome */
  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;
  }
}

Mappatura dei tipi: string, text, email, url, html → string; number → number; boolean → boolean; date → string; enum → unione di letterali; list → array di oggetti da itemFields. I parametri con un default sono facoltativi.

Utilizzo

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

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

L’argomento con l’ID del modello propone in autocompletamento gli ID noti. Gli ID sconosciuti vengono comunque compilati con parametri generici Record<string, unknown>, quindi aggiungere un modello non rompe la tua build.

Rigenera i tipi dopo aver modificato lo schema di un modello – per esempio in uno script prebuild o in un passaggio della CI che fallisce quando il file committato non è aggiornato.