Typisierte Parameter (npx frontmail types)

Vorlagenparameter werden auf dem Server validiert, Fehler lassen sich aber viel früher abfangen: Die CLI frontmail lädt die Parameterschemas Ihrer Vorlagen herunter und erzeugt daraus TypeScript-Typen. Danach weiß send(), welche Parameter jede Vorlage braucht.

Generieren

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

Die CLI frontmail ist Teil von @frontmail/node. Installieren Sie das Paket als Dev-Dependency (npm install -D @frontmail/node) oder führen Sie es ohne Installation aus: npx -p @frontmail/node frontmail types.

Option	Standard	Bedeutung
--out <file>	frontmail-env.d.ts	Zieldatei für die Deklarationen
--module <pkg>	SDK-Pakete aus Ihrer package.json (alle SDKs, wenn keines gefunden wird)	Paket, dessen Interface FrontmailTemplates erweitert wird; für mehrere wiederholen
--api-url <url>	$FRONTMAIL_API_URL oder https://api.frontmail.dev	Basis-URL der API
--stdout	–	Deklarationen ausgeben statt in eine Datei zu schreiben
-h, --help	–	Hilfe anzeigen

Der private Schlüssel wird aus der Umgebungsvariable FRONTMAIL_PRIVATE_KEY gelesen (ein Flag dafür gibt es nicht, damit er nicht in Ihrer Shell-History landet). Der Befehl ruft GET /v1/templates auf; führen Sie ihn lokal oder in der CI aus, niemals im Browser. Achten Sie darauf, dass Ihre tsconfig.json die erzeugte Datei einbezieht.

Was erzeugt wird

Für ein Projekt, das von @frontmail/browser abhängt:

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 {
  /** Your name */
  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;
  }
}

Typzuordnung: string, text, email, url, html → string; number → number; boolean → boolean; date → string; enum → Union aus Literalen; list → Array von Objekten aus itemFields. Parameter mit default sind optional.

Verwenden

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

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

Für das Argument mit der Vorlagen-ID werden bekannte IDs automatisch vervollständigt. Unbekannte IDs kompilieren weiterhin mit lockeren Parametern vom Typ Record<string, unknown> – eine neue Vorlage bricht Ihren Build also nicht.

Erzeugen Sie die Typen neu, nachdem Sie das Schema einer Vorlage geändert haben – etwa in einem prebuild-Skript oder in einem CI-Schritt, der fehlschlägt, wenn die eingecheckte Datei veraltet ist.