Typované parametry (npx frontmail types)

Parametry šablon se validují na serveru, chyby ale můžete zachytit mnohem dřív: CLI frontmail stáhne schémata parametrů vašich šablon a vygeneruje z nich TypeScript typy. Pak už send() ví, jaké parametry která šablona potřebuje.

Generování

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

CLI frontmail je součástí balíčku @frontmail/node. Nainstalujte ho jako vývojovou závislost (npm install -D @frontmail/node), nebo ho spusťte bez instalace: npx -p @frontmail/node frontmail types.

Volba	Výchozí	Význam
--out <file>	frontmail-env.d.ts	Kam zapsat deklarace
--module <pkg>	SDK balíčky nalezené ve vašem package.json (když žádný, tak všechna SDK)	Balíček, jehož rozhraní FrontmailTemplates se rozšíří; pro víc balíčků volbu zopakujte
--api-url <url>	$FRONTMAIL_API_URL nebo https://api.frontmail.dev	Základní URL API
--stdout	–	Vypíše deklarace místo zápisu do souboru
-h, --help	–	Zobrazí nápovědu

Private key se čte z proměnné prostředí FRONTMAIL_PRIVATE_KEY (volbu pro něj CLI nemá, takže neskončí v historii shellu). Příkaz volá GET /v1/templates; spouštějte ho lokálně nebo v CI, nikdy v prohlížeči. Ověřte, že výstupní soubor zahrnuje váš tsconfig.json.

Co se vygeneruje

Pro projekt, který závisí na @frontmail/browser (komentáře generátor píše anglicky, popisky parametrů přebírá ze šablony):

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 {
  /** Vaše jméno */
  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;
  }
}

Mapování typů: string, text, email, url, html → string; number → number; boolean → boolean; date → string; enum → union literálů; list → pole objektů podle itemFields. Parametry s default jsou volitelné.

Použití

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

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

Argument s ID šablony našeptává známá ID. Neznámá ID se přesto zkompilují s volnými parametry Record<string, unknown>, takže přidání šablony vám build nerozbije.

Po změně schématu šablony typy vygenerujte znovu – například ve skriptu prebuild nebo v kroku CI, který selže, když je commitnutý soubor zastaralý.