create-email-renderer 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,18 @@ Renderiza plantillas de email por bloques a **HTML email-safe sin React**. JS pu
 
 Es el compañero de [`create-email-template`](https://www.npmjs.com/package/create-email-template) (editor visual). Comparten el mismo core: los tipos, los defaults y la normalización son idénticos en ambos lados, por lo que el preview del editor y el HTML final nunca divergen.
 
+## ¿Programas con una IA o vas a integrarlo?
+
+La documentación para agentes viaja dentro del paquete:
+
+- **[`SKILL.md`](./SKILL.md)** — orientación: modelo mental del payload, los 3 flujos, recetas
+  (tarea → API) y reglas de oro.
+- **[`docs/BLOCKS.md`](./docs/BLOCKS.md)** — catálogo de los **25 bloques** con props, defaults,
+  variantes y ejemplos `blockJson` copiables.
+- **[`docs/MCP.md`](./docs/MCP.md)** — cómo exponer el renderer como **servidor MCP** (tools
+  `list_blocks`, `build_block`, `render_email`, `validate_template`…).
+- **[`llms.txt`](./llms.txt)** — índice corto para herramientas que lo buscan por convención.
+
 ## Instalación
 
 ```sh
@@ -39,8 +51,9 @@ await emailClient.send({ to: user.email, subject, html });
 | `subject` | `string` | — (obligatorio) | Asunto del correo. **Resuelve variables**: `"Hola {firstName}"` → `"Hola Danny"`. También queda en `<title>` y en el preview oculto del email. |
 | `payload` | `string \| object \| null` | — | El JSON del editor. Tolera `null`/`undefined`/string inválido (devuelve vacío). |
 | `context` | `EmailContext` | `SAMPLE_CONTEXT` | Valores para las variables `{key}`. Se mezcla sobre `SAMPLE_CONTEXT`, así que los correos de prueba siempre se ven completos aunque falten claves. |
-| `settings` | `Partial<EmailSettings>` | settings del payload | Sobrescribe `{ pageBackground, cardBorderWidth, cardBorderRadius }` guardados. |
+| `settings` | `Partial<EmailSettings>` | settings del payload | Sobrescribe `{ pageBackground, cardBorderWidth, cardBorderRadius, fontFamily }` guardados. |
 | `palette` | `EmailPalette` | `DEFAULT_PALETTE` | Sobrescribe los colores: `{ INK, DARK, GOLD, CREAM_DIM }`. |
+| `tracking` | `EmailTracking` | — | Trackeo **por envío**: pixel de apertura y reescritura de enlaces. Ver [Trackeo](#trackeo-aperturas-y-clics). |
 
 **Comportamiento**: lanza `Template payload has no blocks` si tras normalizar no queda ningún bloque. En cualquier otro caso de datos sucios, normaliza sin quejarse (ver [Normalización](#normalización-de-payloads)).
 
@@ -97,9 +110,99 @@ Esto significa que **añadir props nuevas a un bloque no rompe las plantillas ya
 | `extractVariables(text)` / `validateVariables(text, knownKeys)` | Inspección de variables usadas/no reconocidas. |
 | `renderRichText(html)` | Sanitiza y aplica estilos inline al rich text del editor. |
 | `sanitizeRichText` / `escapeHtml` / `normalizeBlockHtml` / `isRichText` | Piezas del pipeline por separado. |
-| `createBlock(type, library)` | Crea un bloque nuevo con defaultProps (útil para generar plantillas por código). |
+| `blockJson(type, props?)` | Constructor **tipado** de un bloque: defaults del esquema, coerción de tipos e ids automáticos. Tipo desconocido → `null`. |
+| `templateJson(blocks, settings?)` | Arma el payload completo (`{ content, settings }`) para `renderTemplateEmail`. |
+| `createBlock(type, library)` | Crea un bloque nuevo con defaultProps (helper de bajo nivel del editor). |
 | Defaults | `DEFAULT_BLOCK_LIBRARY`, `DEFAULT_PALETTE`, `DEFAULT_SETTINGS`, `DEFAULT_VARIABLES`, `SAMPLE_CONTEXT`. |
 
+## Construir bloques desde el back-end (`blockJson`)
+
+Para inyectar contenido que no vive en la plantilla (un producto, un carrito, una imagen) no
+hace falta escribir el JSON a mano: `blockJson` parte de los **defaults del esquema vivo**,
+coacciona tipos, genera los ids y completa los arrays de registros.
+
+```ts
+import { blockJson, templateJson } from "create-email-renderer";
+
+// Un bloque suelto: lo que no pases queda con su default.
+const promo = blockJson("image", { src: "https://…/promo.jpg", alt: "Promo" });
+
+// Carrito real: los registros se completan solos (id, imageUrl, quantity…).
+const carrito = blockJson("checkout", {
+  heading: "Tu pedido está listo",
+  lines: cart.items.map((i) => ({ name: i.name, price: i.price, quantity: String(i.qty) })),
+});
+
+// Correo completo listo para enviar.
+const { html, subject } = await renderTemplateEmail({
+  subject: "Tu pedido {orderId}",
+  payload: templateJson([promo, carrito], { cardBorderWidth: 0 }),
+  context: { orderId: "A-123" },
+});
+```
+
+- **Posicional**: `blockJson(type, props?)` y `templateJson(blocks, settings?)`.
+- **Tipado**: el editor autocompleta solo las props del tipo elegido; una prop inexistente es error de compilación.
+- **Tolerante**: un tipo desconocido devuelve `null` (y `templateJson` lo descarta).
+- **Anidamiento**: `columns` / `blocks` aceptan `blockJson(...)`, el atajo `[type, props]` o `{ type, props }`; se respeta la profundidad máxima (`MAX_BLOCK_DEPTH`).
+- **Ids**: nunca los administras, se generan con `newId()`.
+
+## Trackeo (aperturas y clics)
+
+Opcional y **por envío** (no se guarda en la plantilla, así que el preview del editor nunca
+lleva pixel). Con `tracking` apagado la salida es idéntica a no usarlo.
+
+```ts
+await renderTemplateEmail({
+  subject: "Tu carrito te espera",
+  payload,
+  context: { email: "ana@ejemplo.com" },
+  tracking: {
+    pixelUrl: "https://track.mi-app.com/o?cid=cart-123&e={email}",   // apertura (1×1)
+    clickUrl: "https://track.mi-app.com/c?cid=cart-123&u={url}",     // clics
+    utm: { source: "email", medium: "email", campaign: "carrito" },
+    exclude: ["/baja"],                                            // extra opcional
+    // transformLink: (href) => `https://mi-redirect/?to=${encodeURIComponent(href)}`,
+  },
+});
+```
+
+| Campo | Qué hace |
+|---|---|
+| `pixelUrl` | Inyecta un `<img width="1" height="1">` antes de `</body>`. Acepta `{variables}`. |
+| `clickUrl` | Reescribe cada `<a href>`: el destino va en `{url}` (codificado) y el tracker recibe las mismas `{variables}`. |
+| `utm` | Añade `utm_*` al destino **antes** de pasarlo por el tracker (respeta los parámetros que ya existían). |
+| `exclude` | Substrings de href que no se reescriben; se suman a los de por defecto (`mailto:`, `tel:`, `sms:`, `#`, `unsubscribe`, `/baja`, `optout`…). |
+| `transformLink` | Control total: devuelve el href final tú mismo. |
+
+**Caveats honestos**
+
+- Las **aperturas** ya no son fiables: Apple Mail precarga las imágenes (MPP) y Gmail las sirve
+  por proxy. Úsalo como tendencia, no como verdad.
+- El **click tracking** cambia la URL visible al pasar el ratón y la vista previa del enlace en
+  algunos clientes; y **nunca** debe pasar por el tracker el enlace de baja.
+- Si tu ESP (Mailflare, Resend, SES…) ya trackea, no lo dupliques: aquí tienes `transformLink`
+  como salida de emergencia.
+
+## Tipografía
+
+El correo lleva un **stack de fuentes de sistema** (lista ordenada: el cliente usa la primera que
+tenga instalada) para no depender de la fuente por defecto del cliente —que en Gmail/Outlook suele
+ser Times New Roman—:
+
+```ts
+await renderTemplateEmail({
+  subject: "Hola",
+  payload,
+  settings: { fontFamily: "Georgia, 'Times New Roman', serif" }, // o "" para no emitir nada
+});
+```
+
+`FONT_STACKS` trae 7 grupos listos (Sistema, Arial/Helvetica, Verdana/Tahoma, Trebuchet MS,
+Georgia, Times New Roman y Monoespaciada) y `DEFAULT_SETTINGS.fontFamily` es el stack de sistema.
+Las **webfonts** (`@font-face`) no son fiables: Gmail las elimina y Outlook escritorio las ignora,
+así que conviene dejar siempre un fallback de sistema al final del stack.
+
 ## Subpaths
 
 Todo está disponible desde la raíz. Si prefieres imports granulares (menos bundle en serverless):
@@ -112,6 +215,7 @@ create-email-renderer/types           → todos los tipos + createBlock
 create-email-renderer/variables       → variables, contextos y resolve
 create-email-renderer/richtext        → helpers de rich text
 create-email-renderer/default-blocks  → defaults de bloques, paleta y settings
+create-email-renderer/build           → blockJson, templateJson
 ```
 
 ## Licencia

package/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: create-email-renderer
+description: Render and build email templates as JSON blocks into email-safe HTML without React (Node, Workers, edge)
+licence: MIT
+metadata:
+  author: asmel2020
+  version: 1.0.0
+---
+
+# Skill: `create-email-renderer`
+
+Renderiza plantillas de email **por bloques** (JSON → HTML email-safe) **sin React**. JS puro:
+corre en Node, Cloudflare Workers, Vercel Edge, Deno y Bun. Es el compañero sin UI de
+`create-email-template` (el editor visual): comparten el mismo core, así que el preview del
+editor y el HTML final nunca divergen.
+
+- 📖 Catálogo de los **25 bloques** (props, defaults, variantes, ejemplos): [`docs/BLOCKS.md`](./docs/BLOCKS.md)
+- 🔌 Cómo exponerlo como **MCP**: [`docs/MCP.md`](./docs/MCP.md)
+
+---
+
+## Cuándo usar esto
+
+| Quieres… | Usa |
+|---|---|
+| Mandar un correo desde el back-end a partir de una plantilla guardada | `renderTemplateEmail` |
+| Construir el correo por código (sin editor) | `blockJson` + `templateJson` |
+| Inyectar datos reales (carrito, pedido, productos) en una plantilla guardada | mutar `content` del payload y renderizar |
+| Leer/limpiar un payload viejo o sucio | `parseTemplatePayload` / `normalizeBlocks` |
+| Píxel de apertura y tracking de clics | opción `tracking` |
+
+## Instalación
+
+```sh
+npm install create-email-renderer
+```
+
+Sin React, sin DOM, sin peer deps. Única dependencia: `sanitize-html`.
+
+## Modelo mental (30 segundos)
+
+```
+payload = { content: EmailBlock[], settings }      ← lo que guarda el editor
+            └── block = { id, type, props }        ← uno de los 25 tipos
+```
+
+1. **`content`** es una lista ordenada de bloques. Cada bloque tiene un `type` y sus `props`.
+2. Lo que no venga en `props` se completa con el **default del esquema**, y lo desconocido se
+   descarta (`normalizeBlocks`) → **añadir props nuevas no rompe plantillas viejas**.
+3. Las variables `{clave}` se resuelven con el `context` en tiempo de render.
+4. El HTML final es tablas con estilos inline (`<table role="presentation">`), email-safe.
+
+## Los 3 flujos
+
+```
+① Editor (create-email-template) ──getPayload()──▶ { content, settings } ──PUT──▶ tu backend
+② Tu backend ──renderTemplateEmail({ subject, payload, context })──▶ { html, subject } ──▶ ESP
+③ Tu backend ──blockJson()/templateJson()──▶ payload ──▶ mismo render (sin editor de por medio)
+```
+
+## Recetas (tarea → API)
+
+### Renderizar una plantilla guardada
+
+```ts
+import { renderTemplateEmail } from "create-email-renderer/server";
+
+const { html, subject } = await renderTemplateEmail({
+  subject: "Hola {firstName}",                 // resuelve variables
+  payload: template.payload,                   // string JSON u objeto {content, settings}
+  context: { firstName: user.name },
+  settings: { cardBorderWidth: 0 },            // sobrescribe los settings guardados
+  palette: { INK: "#111", DARK: "#000", GOLD: "#d7b227", CREAM_DIM: "#aaa" },
+});
+```
+
+- `payload` tolera `null`/string inválido (devuelve vacío) pero **lanza** `Template payload has no blocks` si tras normalizar no queda ningún bloque.
+- No re-exporta `renderEmailHtml` (el paquete UI tiene su versión React con el mismo nombre). Para el HTML puro: `create-email-renderer/html-render`.
+
+### Construir un bloque (tipado, con defaults e ids)
+
+```ts
+import { blockJson, templateJson } from "create-email-renderer";
+
+blockJson("image", { src: "https://…/foto.jpg", alt: "Foto" });
+blockJson("checkout", { lines: [{ name: "Camiseta", price: "$20" }] }); // id/quantity se rellenan
+blockJson("columns", { columns: [{ blocks: [["text", { text: "Hola" }]] }] });
+
+templateJson([/* bloques */], { fontFamily: "" }); // → { content, settings } listo para render
+```
+
+- Posicional y **tipado** (`blockJson("image", {` autocompleta solo las props de `image`).
+- Tipo desconocido → `null` (y `templateJson` lo descarta).
+- **Nunca administras ids**: se generan para el bloque y para cada registro.
+- Hijos: acepta `blockJson(...)`, `[type, props]` o `{ type, props }`; respeta `MAX_BLOCK_DEPTH = 1`.
+
+### Inyectar el carrito / datos del pedido
+
+```ts
+import { parseTemplatePayload } from "create-email-renderer";
+
+const { content, settings } = parseTemplatePayload(template.payload);
+const blocks = content.map((b) =>
+  b.type === "checkout"
+    ? { ...b, props: { ...b.props, heading: "Tu pedido está listo",
+        lines: cart.items.map((i) => ({ name: i.name, price: i.price, quantity: String(i.qty) })) } }
+    : b,
+);
+const html = await renderEmailHtml({ blocks, subject, context, settings });
+```
+
+`normalize` repara ids/tipos de los registros, así que puedes construir el array "flojo".
+Ver [`docs/BLOCKS.md`](./docs/BLOCKS.md) para las props de cada bloque y
+[`docs/MCP.md`](./docs/MCP.md) para exponer esto como tool.
+
+### Tracking (opt-in, por envío)
+
+```ts
+await renderTemplateEmail({
+  subject, payload, context,
+  tracking: {
+    pixelUrl: "https://track.mi-app.com/o?cid=123&e={email}",   // apertura 1×1
+    clickUrl: "https://track.mi-app.com/c?cid=123&u={url}",     // clics
+    utm: { source: "email", medium: "email", campaign: "carrito" },
+    // exclude: ["/baja"], transformLink: (href) => …
+  },
+});
+```
+
+Nunca se guarda en la plantilla (no contamina el preview) y con `tracking` apagado la salida es
+idéntica. La baja (`/baja`, `unsubscribe`, `mailto:`…) **no** se reescribe ni con `exclude` por
+defecto.
+
+### Otros helpers
+
+| Export | Para qué |
+|---|---|
+| `parseTemplatePayload(raw)` | `{ content, settings }` normalizado, nunca lanza. |
+| `normalizeBlocks(input, library?)` / `normalizeSettings(input)` | Limpiar payloads legacy. |
+| `resolveVariables(text, ctx)` / `extractVariables` / `validateVariables` | Variables `{key}`. |
+| `buildTemplateContext(base, extra?)` | Contexto limpio (quita `null`/`""`) sobre `SAMPLE_CONTEXT`. |
+| `renderRichText` / `sanitizeRichText` / `escapeHtml` | Pipeline de rich text. |
+| `DEFAULT_BLOCK_LIBRARY` / `DEFAULT_PALETTE` / `DEFAULT_SETTINGS` / `SAMPLE_CONTEXT` | Defaults. |
+| `listBlockDefinitions()` / `registerBlock()` | Registry vivo: catálogo y plugins. |
+
+## Subpaths
+
+```
+create-email-renderer                  → todo
+create-email-renderer/server           → parseTemplatePayload, renderTemplateEmail, buildTemplateContext
+create-email-renderer/html-render      → renderEmailHtml
+create-email-renderer/build            → blockJson, templateJson
+create-email-renderer/normalize        → normalizeBlocks, normalizeSettings
+create-email-renderer/types            → tipos (EmailBlock, EmailBlockType, EmailSettings…)
+create-email-renderer/variables        → variables + contextos
+create-email-renderer/richtext         → helpers de rich text
+create-email-renderer/default-blocks   → defaults de bloques, paleta y settings
+create-email-renderer/registry         → registerBlock, listBlockDefinitions
+```
+
+## Reglas de oro (no las rompas)
+
+1. **Este paquete nunca depende de React** ni de nada que lo arrastre. Si algo necesita DOM/JSX,
+   pertenece a `create-email-template`.
+2. **El core vive aquí**: tipos, defaults, normalización y preset de bloques. El paquete UI los
+   reexporta con shims de una línea. No dupliques esa lógica.
+3. **Todo helper nuevo debe ser puro y no-lanzador** con datos corruptos (salvo `blockJson` con
+   tipo desconocido → `null`, y `renderTemplateEmail` sin bloques → throw).
+4. **Es aditivo por diseño**: no cambies defaults ni el HTML existente sin querer; hay un snapshot
+   de paridad por tipo de bloque para vigilarlo.
+
+## Errores comunes
+
+| Síntoma | Causa |
+|---|---|
+| `Template payload has no blocks` | Todo el `content` se descartó al normalizar (tipos desconocidos). |
+| `{firstName}` sale literal en el correo | La clave no está en el `context` (las desconocidas se dejan tal cual). |
+| El correo se ve con otra tipografía | `settings.fontFamily` vacío ⇒ hereda la del cliente; pon un stack. |
+| Las imágenes se estiran | `imageHeight` con `object-fit` en Outlook escritorio; usa `0`. |
+| Las imágenes no cargan en Gmail | Son `data:` (SVG inline); Gmail las descarta. Usa URLs `https:`. |
+| Un array de registros queda vacío | Usaste `items` para registros: los registros van en `lines`/`products`/… |
+| El bloque anidado desaparece | `MAX_BLOCK_DEPTH = 1`: los hijos no pueden contener bloques. |
+
+## Verificación antes de dar algo por hecho
+
+```sh
+pnpm --filter create-email-renderer test     # snapshots de paridad + unitarios
+pnpm lint && pnpm check-types && pnpm build
+```

package/dist/build.d.ts

@@ -0,0 +1,52 @@
+import type { BlockPropsMap, EmailBlock, EmailBlockType, EmailSettings } from "./types.js";
+/**
+ * Registro de un array de registros en la entrada: sin `id` y con todos los
+ * campos opcionales (el constructor rellena ids y defaults).
+ */
+export type RecordInput<T> = Partial<Omit<T, "id">>;
+/**
+ * Props de entrada de un bloque: todo opcional (los defaults completan) y los
+ * arrays de registros aceptan entradas sin `id`.
+ */
+export type BlockInputProps<T extends EmailBlockType> = Omit<{
+    [K in keyof BlockPropsMap[T]]?: BlockPropsMap[T][K] extends Array<infer I> ? I extends {
+        id: string;
+    } ? RecordInput<I>[] : BlockPropsMap[T][K] : BlockPropsMap[T][K];
+}, never>;
+/** Celda de un contenedor: ancho + hijos (bloques o atajos). */
+export interface ColumnInput {
+    id?: string;
+    width?: number;
+    blocks?: BlockInput[];
+}
+/** Bloque ya construido o el atajo `[type, props]` / `{ type, props }`. */
+export type BlockShorthand<T extends EmailBlockType = EmailBlockType> = {
+    [K in T]: [K, BlockInputProps<K>?] | {
+        type: K;
+        props?: BlockInputProps<K>;
+    };
+}[T];
+export type BlockInput = EmailBlock | BlockShorthand | (BlockInputProps<EmailBlockType> & {
+    type: EmailBlockType;
+});
+/**
+ * Construye un bloque a partir de su tipo y (opcionalmente) props parciales.
+ * Lo que no pases queda con el default del esquema; los ids se generan solos.
+ * Devuelve `null` si el tipo no existe en la librería viva.
+ *
+ * ```ts
+ * blockJson("image", { src: "https://…/foto.jpg", alt: "Foto" })
+ * blockJson("checkout", { lines: [{ name: "Camiseta", price: "$20" }] })
+ * ```
+ */
+export declare function blockJson<T extends EmailBlockType>(type: T, props?: BlockInputProps<T>): EmailBlock;
+export declare function blockJson(type: string, props?: Record<string, unknown>): EmailBlock | null;
+/**
+ * Construye el payload completo (`{ content, settings }`) listo para
+ * `renderTemplateEmail({ payload })`. Descarta los bloques inválidos (`null`).
+ */
+export declare const templateJson: (blocks: Array<EmailBlock | null | undefined>, settings?: Partial<EmailSettings>) => {
+    content: EmailBlock[];
+    settings: Partial<EmailSettings>;
+};
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,aAAa,EAEb,UAAU,EAEV,cAAc,EACd,aAAa,EACd,MAAM,YAAY,CAAC;AAapB;;;GAGG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI,IAAI,CAC1D;KACG,CAAC,IAAI,MAAM,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GACtE,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GACtB,WAAW,CAAC,CAAC,CAAC,EAAE,GAChB,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACrB,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxB,EACD,KAAK,CACN,CAAC;AAEF,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,2EAA2E;AAC3E,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;KACrE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;KAAE;CAC7E,CAAC,CAAC,CAAC,CAAC;AAEL,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,cAAc,GACd,CAAC,eAAe,CAAC,cAAc,CAAC,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC,CAAC;AAyIjE;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,cAAc,EAChD,IAAI,EAAE,CAAC,EACP,KAAK,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GACzB,UAAU,CAAC;AACd,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,UAAU,GAAG,IAAI,CAAC;AAerB;;;GAGG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,KAAK,CAAC,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,EAC5C,WAAW,OAAO,CAAC,aAAa,CAAC,KAChC;IAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;CAO1D,CAAC"}

package/dist/build.js

@@ -0,0 +1,169 @@
+// Constructor de bloques para consumidores sin editor (back-end, Workers,
+// scripts): arma un `EmailBlock` válido partiendo de los defaults del esquema
+// vivo, coacciona tipos, genera ids y completa los arrays de registros.
+// Es puramente aditivo: no altera `normalize`, el render ni los defaults.
+import { DEFAULT_BLOCK_LIBRARY, DEFAULT_SETTINGS, } from "./default-blocks.js";
+import { newId } from "./id.js";
+import { coerceNumber, normalizeRecordArray, RECORD_ARRAY_FIELDS, } from "./records.js";
+import { listBlockDefinitions } from "./registry.js";
+import { normalizeSettings } from "./normalize.js";
+import { isContainerType } from "./types.js";
+/** Props de layout opcionales (mismo conjunto que normaliza `normalize.ts`). */
+const LAYOUT_KEYS = [
+    "paddingTop",
+    "paddingRight",
+    "paddingBottom",
+    "paddingLeft",
+    "marginTop",
+    "marginBottom",
+    "gap",
+];
+const isEmailBlock = (value) => {
+    const block = value;
+    return (!!block &&
+        typeof block === "object" &&
+        typeof block.id === "string" &&
+        typeof block.type === "string" &&
+        !!block.props &&
+        typeof block.props === "object");
+};
+/** Normaliza las formas aceptadas de un hijo a `[type, props]`. */
+const asShorthand = (value) => {
+    if (Array.isArray(value)) {
+        const [type, props] = value;
+        return typeof type === "string" ? { type, props } : null;
+    }
+    if (value && typeof value === "object") {
+        const raw = value;
+        return typeof raw.type === "string"
+            ? { type: raw.type, props: raw.props ?? {} }
+            : null;
+    }
+    return null;
+};
+const resolveDefinition = (type) => {
+    const live = listBlockDefinitions();
+    const library = live.length > 0 ? live : DEFAULT_BLOCK_LIBRARY;
+    return library.find((def) => def.type === type);
+};
+/**
+ * Construye las props de un bloque: defaults del esquema + lo que pases,
+ * coaccionando tipos y completando registros e hijos.
+ */
+const buildProps = (definition, input, depth) => {
+    const props = structuredClone(definition.defaultProps);
+    const def = definition.type;
+    for (const key of Object.keys(props)) {
+        const value = input[key];
+        if (value === undefined || value === null)
+            continue;
+        const fallback = props[key];
+        if (key === "columns" && Array.isArray(fallback)) {
+            props[key] = buildColumns(value, depth);
+        }
+        else if (key === "blocks" && def === "container") {
+            props[key] = buildBlockList(value, depth + 1);
+        }
+        else if (key === "columns" && def === "gallery") {
+            props[key] = coerceNumber(value, fallback);
+        }
+        else if (RECORD_ARRAY_FIELDS[key]) {
+            props[key] = normalizeRecordArray(value, fallback, RECORD_ARRAY_FIELDS[key]);
+        }
+        else if (typeof fallback === "number") {
+            props[key] = coerceNumber(value, fallback);
+        }
+        else if (typeof fallback === "boolean") {
+            props[key] = value === true || value === "true";
+        }
+        else if (Array.isArray(fallback)) {
+            props[key] = Array.isArray(value) ? value.map((v) => String(v)) : fallback;
+        }
+        else if (typeof fallback === "string") {
+            props[key] = String(value);
+        }
+        else {
+            props[key] = value;
+        }
+    }
+    // Overrides de layout opcionales que no viven en los defaults.
+    for (const key of LAYOUT_KEYS) {
+        const value = input[key];
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value === "number" && Number.isFinite(value)) {
+            props[key] = value;
+        }
+        else if (typeof value === "string" && value.trim() !== "") {
+            const parsed = parseFloat(value);
+            if (Number.isFinite(parsed))
+                props[key] = parsed;
+        }
+    }
+    return props;
+};
+/** Construye una lista de bloques (hijos de contenedores/columnas). */
+const buildBlockList = (input, depth) => {
+    if (!Array.isArray(input))
+        return [];
+    const blocks = [];
+    for (const entry of input) {
+        if (isEmailBlock(entry)) {
+            // Ya es un bloque (p. ej. salido de `blockJson`): se respeta tal cual,
+            // salvo que sea un contenedor demasiado profundo.
+            if (depth > 0 && isContainerType(entry.type))
+                continue;
+            blocks.push(entry);
+            continue;
+        }
+        const shorthand = asShorthand(entry);
+        if (!shorthand)
+            continue;
+        if (depth > 0 && isContainerType(shorthand.type))
+            continue;
+        const definition = resolveDefinition(shorthand.type);
+        if (!definition)
+            continue;
+        blocks.push({
+            id: newId(),
+            type: definition.type,
+            props: buildProps(definition, shorthand.props ?? {}, depth),
+        });
+    }
+    return blocks;
+};
+/** Construye las celdas de `columns` / `grid` / `footer`. */
+const buildColumns = (input, depth) => {
+    if (!Array.isArray(input))
+        return [];
+    return input.map((raw) => {
+        const col = (raw ?? {});
+        const id = typeof col.id === "string" && col.id ? col.id : newId();
+        const blocks = buildBlockList(col.blocks, depth + 1);
+        const width = coerceNumber(col.width, 0);
+        return width > 0 ? { id, blocks, width } : { id, blocks };
+    });
+};
+export function blockJson(type, props) {
+    if (typeof type !== "string" || !type)
+        return null;
+    const definition = resolveDefinition(type);
+    if (!definition)
+        return null;
+    return {
+        id: newId(),
+        type: definition.type,
+        props: buildProps(definition, props ?? {}, 0),
+    };
+}
+/**
+ * Construye el payload completo (`{ content, settings }`) listo para
+ * `renderTemplateEmail({ payload })`. Descarta los bloques inválidos (`null`).
+ */
+export const templateJson = (blocks, settings) => ({
+    content: blocks.filter((block) => !!block && !!block.props),
+    settings: settings
+        ? normalizeSettings({ ...DEFAULT_SETTINGS, ...settings })
+        : {},
+});
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/default-blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default-blocks.d.ts","sourceRoot":"","sources":["../src/default-blocks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE9E,eAAO,MAAM,eAAe,EAAE,YAK7B,CAAA;AAED,eAAO,MAAM,gBAAgB,EAAE,aAI9B,CAAA;AAED,eAAO,MAAM,qBAAqB,EAAE,eAAe,EAiJlD,CAAA"}
+{"version":3,"file":"default-blocks.d.ts","sourceRoot":"","sources":["../src/default-blocks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE9E,eAAO,MAAM,eAAe,EAAE,YAK7B,CAAA;AAED,eAAO,MAAM,gBAAgB,EAAE,aAK9B,CAAA;AAED,eAAO,MAAM,qBAAqB,EAAE,eAAe,EAwelD,CAAA"}