Typowane parametry (npx frontmail types)

Parametry szablonów są walidowane na serwerze, ale błędy możesz wyłapać dużo wcześniej: CLI frontmail pobiera schematy parametrów twoich szablonów i generuje z nich typy TypeScript. Od tej chwili send() wie, jakich parametrów potrzebuje każdy szablon.

Generowanie

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

CLI frontmail jest częścią pakietu @frontmail/node. Zainstaluj go jako zależność deweloperską (npm install -D @frontmail/node) albo uruchom bez instalacji: npx -p @frontmail/node frontmail types.

Opcja	Domyślnie	Znaczenie
--out <file>	frontmail-env.d.ts	Gdzie zapisać deklaracje
--module <pkg>	pakiety SDK znalezione w twoim package.json (jeśli żadnego nie ma – wszystkie SDK)	Pakiet, którego interfejs FrontmailTemplates zostanie rozszerzony; dla kilku pakietów powtórz opcję
--api-url <url>	$FRONTMAIL_API_URL lub https://api.frontmail.dev	Bazowy URL API
--stdout	–	Wypisuje deklaracje zamiast zapisywać plik
-h, --help	–	Wyświetla pomoc

Klucz prywatny jest odczytywany ze zmiennej środowiskowej FRONTMAIL_PRIVATE_KEY (CLI nie ma na niego opcji, więc nie trafi do historii powłoki). Polecenie wywołuje GET /v1/templates; uruchamiaj je lokalnie albo w CI, nigdy w przeglądarce. Upewnij się, że plik wynikowy jest objęty przez twój tsconfig.json.

Co jest generowane

Dla projektu, który zależy od @frontmail/browser (komentarze generator pisze po angielsku, opisy parametrów bierze z szablonu):

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 {
  /** Twoje imię */
  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;
  }
}

Mapowanie typów: string, text, email, url, html → string; number → number; boolean → boolean; date → string; enum → unia literałów; list → tablica obiektów według itemFields. Parametry z default są opcjonalne.

Użycie

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

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

Argument z ID szablonu podpowiada znane ID. Nieznane ID nadal się kompilują z luźnymi parametrami Record<string, unknown>, więc dodanie szablonu nie zepsuje ci builda.

Po zmianie schematu szablonu wygeneruj typy ponownie – na przykład w skrypcie prebuild albo w kroku CI, który kończy się błędem, gdy zacommitowany plik jest nieaktualny.