Parámetros tipados (npx frontmail types)

Los parámetros de las plantillas se validan en el servidor, pero puedes detectar los errores mucho antes: la CLI frontmail descarga los esquemas de parámetros de tus plantillas y genera tipos de TypeScript. A partir de ahí, send() sabe qué parámetros necesita cada plantilla.

Generar los tipos

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

La CLI frontmail viene con @frontmail/node. Instálalo como dependencia de desarrollo (npm install -D @frontmail/node) o ejecútalo sin instalar: npx -p @frontmail/node frontmail types.

Opción	Valor por defecto	Significado
--out <file>	frontmail-env.d.ts	Dónde escribir las declaraciones
--module <pkg>	Los paquetes de SDK que aparecen en tu package.json (todos los SDK si no hay ninguno)	Paquete cuya interfaz FrontmailTemplates se amplía; repítela para varios
--api-url <url>	$FRONTMAIL_API_URL o https://api.frontmail.dev	URL base de la API
--stdout	–	Imprime las declaraciones en lugar de escribir un archivo
-h, --help	–	Muestra la ayuda

La clave privada se lee de la variable de entorno FRONTMAIL_PRIVATE_KEY (no hay ninguna opción para ella, así que no acaba en el historial de tu shell). El comando llama a GET /v1/templates; ejecútalo en local o en CI, nunca en el navegador. Asegúrate de que tu tsconfig.json incluye el archivo generado.

Qué se genera

Para un proyecto que depende de @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 {
  /** Tu nombre */
  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;
  }
}

Correspondencia de tipos: string, text, email, url, html → string; number → number; boolean → boolean; date → string; enum → unión de literales; list → array de objetos según itemFields. Los parámetros con default son opcionales.

Uso

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

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

El argumento del ID de plantilla autocompleta los ID conocidos. Los ID desconocidos siguen compilando con parámetros laxos de tipo Record<string, unknown>, así que añadir una plantilla no rompe tu build.

Vuelve a generar los tipos después de cambiar el esquema de una plantilla; por ejemplo, en un script prebuild o en un paso de CI que falle cuando el archivo confirmado en el repositorio esté desactualizado.