Typované parametre (npx frontmail types)

Parametre šablón sa validujú na serveri, chyby však môžete zachytiť oveľa skôr: CLI frontmail stiahne schémy parametrov vašich šablón a vygeneruje z nich TypeScript typy. Potom už send() vie, aké parametre ktorá šablóna potrebuje.

Generovanie

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

CLI frontmail je súčasťou balíka @frontmail/node. Nainštalujte ho ako vývojovú závislosť (npm install -D @frontmail/node) alebo ho spustite bez inštalácie: npx -p @frontmail/node frontmail types.

Voľba	Predvolené	Význam
--out <file>	frontmail-env.d.ts	Kam zapísať deklarácie
--module <pkg>	SDK balíky nájdené vo vašom package.json (ak žiadny, tak všetky SDK)	Balík, ktorého rozhranie FrontmailTemplates sa rozšíri; pre viac balíkov voľbu zopakujte
--api-url <url>	$FRONTMAIL_API_URL alebo https://api.frontmail.dev	Základná URL API
--stdout	–	Vypíše deklarácie namiesto zápisu do súboru
-h, --help	–	Zobrazí nápovedu

Súkromný kľúč sa číta z premennej prostredia FRONTMAIL_PRIVATE_KEY (voľbu preň CLI nemá, takže neskončí v histórii shellu). Príkaz volá GET /v1/templates; spúšťajte ho lokálne alebo v CI, nikdy v prehliadači. Overte, že výstupný súbor zahŕňa váš tsconfig.json.

Čo sa vygeneruje

Pre projekt, ktorý závisí od @frontmail/browser (komentáre generátor píše po anglicky, popisy parametrov preberá zo šablóny):

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 meno */
  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;
  }
}

Mapovanie typov: string, text, email, url, html → string; number → number; boolean → boolean; date → string; enum → union literálov; list → pole objektov podľa itemFields. Parametre s default sú voliteľné.

Použitie

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 šablóny našepkáva známe ID. Neznáme ID sa napriek tomu skompilujú s voľnými parametrami Record<string, unknown>, takže pridanie šablóny vám build nerozbije.

Po zmene schémy šablóny typy vygenerujte znova – napríklad v skripte prebuild alebo v kroku CI, ktorý zlyhá, keď je commitnutý súbor zastaraný.