@ozura/email-renderer

Shared email rendering core for Ozura. A pure function: template data in, rendered HTML/text out. No file I/O beyond the bundled Nunjucks templates and no runtime dependency on any data store or config — globals are passed in by the caller.

Install

npm install @ozura/email-renderer

Scoped to the private @ozura org on npm — you must be a member and authenticated (npm login) to install.

Usage

const { render, renderObject, BLOCK_DEFS } = require("@ozura/email-renderer");

const globals = {
  companyAddress: "Ozura, 1441 Brickell Avenue, 1400, Miami, FL 33131 US",
  logoUrl: "https://.../ozulogo.png",
};

const out = render(
  {
    subject: "Welcome, {{ name }}",
    blocks: [
      { type: "heading", text: "Welcome, {{ name }}" },
      { type: "text", html: "Your account is ready." },
      { type: "button", label: "Open dashboard", href: "https://app.ozura.com" },
    ],
    vars: { name: "Alex" },
  },
  globals,
  "dark" // "dark" (default) | "light"
);

// out => { subject, format: "html", html, text }

renderObject is an alias for render with an identical signature — named separately so CMS/editor call sites read distinctly from service call sites.

Browser-safe block metadata

BLOCK_DEFS (block type display names + editable fields) is also exported from a Node-free subpath for client-side editor UIs:

import { BLOCK_DEFS } from "@ozura/email-renderer/block-defs";

API

render(input, globals, theme?) → RenderOutput

| Param | Type | Notes | |-------|------|-------| | input | EmailInput | { subject?, format?, blocks?, text?, vars?, align?, preheader? } | | globals | Globals | { companyAddress, logoUrl } | | theme | "dark" \| "light" | Defaults to "dark" |

Returns { subject, format, html?, text? }. For format: "text", only subject and text are produced.

Blocks must be plain objects. ORM documents (e.g. Mongoose subdocuments) are normalized via a duck-typed toObject() before rendering, so passing Mongoose blocks works — but any other document wrapper should be converted to a POJO first.

Variable interpolation is logic-less by design. Only {{ name }} / {{ a.b }} placeholders in field strings are substituted (HTML-escaped); filters, function calls, and {% %} tags are left as literal text and never executed, preventing server-side template injection.

Supported block types

heading, text, muted, button, cred, divider, sectionTitle, note, stat, statPair. See BLOCK_DEFS for each type's editable fields.

Development

npm test   # parity test vs. the ozura-email-gallery reference templates

Note: the parity test reads reference templates from a sibling ozura-email-gallery checkout and is a local dev harness, not a standalone CI gate.

License

UNLICENSED — internal Ozura use only.