API reference

import "github.com/sulv-io/lttr"

func Compile[T any](reg *Registry, name string, src []byte) (*Template[T], error)
func MustCompile[T any](reg *Registry, name string, src []byte) *Template[T]

type Template[T any] struct{ /* unexported */ }

func (t *Template[T]) Render(r *Renderer, to Recipient, v T) (*Message, error)
func (t *Template[T]) Meta() TemplateMeta
func (t *Template[T]) Name() string

type TemplateMeta struct {
    Name     string
    Family   string
    Stream   Stream    // the family's stream, or its legal stream with "legal: true"
    Tags     []TagInfo // in source order
    Modules  []string  // module kinds in order, e.g. "statement"
    Warnings []string  // "name:line:col: warning: msg"
}

type TagInfo struct {
    Path    string // dotted path, e.g. "driver.first_name"
    Type    string // the Go type it resolves to, e.g. "string", "data.Money"
    Pos     string // "line:col" in the template source
    Binding bool   // a :key="path" binding rather than a {{path}} tag
}

func NewRenderer(cfg Config) (*Renderer, error)

type Renderer struct{ /* unexported */ }

type Config struct {
    Domain    string // sending domain; the {domain} placeholder
    SiteURL   string // absolute https URL; the {site} placeholder
    AssetBase string // base URL of the logo files

    Theme    Theme     // palettes, fonts and brand mark
    Families *Registry // the family registry templates are compiled against

    Entities      map[string]Entity // region → entity, for the footer address
    DefaultRegion string            // region used when a recipient has none; must be in Entities

    AllowRelativeURLs bool // previews only: relative asset and link URLs are allowed
}

type Entity struct {
    Address string
}

type Vars struct {
    Site        string `json:"site"`        // Config.SiteURL
    Brand       string `json:"brand"`       // Theme.Brand.Name
    Domain      string `json:"domain"`      // Config.Domain
    Region      string `json:"region"`      // the recipient's region, or Config.DefaultRegion
    Address     string `json:"address"`     // the entity address for the region
    About       string `json:"about"`       // the F2 about value (family copy or footer.about)
    Prefs       string `json:"prefs"`       // the recipient's preferences URL
    Unsubscribe string `json:"unsubscribe"` // the recipient's unsubscribe URL
    Issue       string `json:"issue"`       // the evaluated frontmatter issue (H3 masthead)
}

type Theme = theme.Theme
type Recipient = data.Recipient

func NewRegistry(families ...Family) *Registry

type Registry struct{ /* unexported */ }

func (r *Registry) Lookup(name string) (Family, bool)
func (r *Registry) Names() []string
func (r *Registry) Validate(domain string) error

type Family struct {
    Name            string
    From            mail.Address   // fixed sender; zero when FromFrontmatter
    FromFrontmatter bool           // the template's frontmatter "from" is required and is the sender
    SenderDomain    string         // allowed sender domain; "" = Config.Domain; may use {domain}
    Stream          Stream         // sending stream
    Header          HeaderVariant  // header chrome
    Footer          FooterVariant  // footer chrome
    Copy            FooterCopy     // footer copy for Footer
    Masthead        string         // H3 masthead copy, e.g. "Journal · No. {issue}"; required for H3
    Banner          string         // H2 banner copy; required for H2
    Legal           *LegalOverride // what frontmatter "legal: true" switches to; nil = not allowed
    Forbidden       []ir.Kind      // modules templates of this family may not use
    Tracking        bool           // whether the sending service may track opens and clicks
}

type FooterCopy struct {
    Nav       []NavLink  // F1 nav row; empty = no row
    Reason    string     // F1 lead (Markdown)
    Links     string     // F1 links after the reason
    Note      string     // F2 lead (Markdown)
    About     string     // F2 {about} value (plain text); "" drops the service line
    Service   string     // F2 service line
    OptOut    string     // F3 lead (Markdown)
    Internal  string     // F3·i lead (Markdown)
    Address   string     // every variant, plain text, e.g. "{brand} · {address}"
    TextLinks []TextLink // plain-text URL lines after the address
}

type LegalOverride struct {
    Stream Stream
    Footer FooterVariant
    Copy   FooterCopy
}

type NavLink struct{ Label, Href string }
type TextLink struct{ Label, URL string }

type HeaderVariant = layout.HeaderVariant
type FooterVariant = layout.FooterVariant

const (
    H1 = layout.H1 // logo
    H2 = layout.H2 // logo with the internal banner (Family.Banner)
    H3 = layout.H3 // newsletter masthead (Family.Masthead)
)

const (
    F1         = layout.F1         // marketing: nav, reason, unsubscribe and preferences links
    F2         = layout.F2         // service: note and "service email about {about}" line
    F3         = layout.F3         // outreach: opt-out line
    F3Internal = layout.F3Internal // internal: internal-only line
)

type Stream string

const (
    Transactional Stream = "transactional" // mail the recipient triggered: receipts, orders, payouts
    Security      Stream = "security"      // account security: sign-in codes, password resets
    Marketing     Stream = "marketing"     // opted-in promotional mail; carries List-Unsubscribe
    Outreach      Stream = "outreach"      // business-to-business mail, kept apart from Marketing
    Internal      Stream = "internal"      // mail to the operator's own staff only
)

func (s Stream) Valid() bool

type Message struct {
    Template, Family   string       // not written to the wire
    Stream             Stream       // selects the Router's sender
    From, To           mail.Address // sender and the single recipient
    Subject, Preheader string
    HTML, Text         string       // the two bodies of the multipart/alternative message
    Tracking           bool         // whether the HTML carries tracked links (the family's Tracking)
    Warnings           []string     // non-fatal findings from compile and render
    // unexported header fields
}

func (m *Message) MIME(date time.Time) ([]byte, error)
func (m *Message) SetHeader(name, value string) error
func (m *Message) SetListUnsubscribe(u string) error
func (m *Message) Header(name string) string
func (m *Message) Headers() []string
func (m *Message) Clone() *Message

type Sender interface {
    Send(ctx context.Context, m *Message) error
}

type Router struct {
    Streams         map[Stream]Sender
    InternalAllowed func(addr string) bool                                     // nil denies all Internal mail
    Suppressed      func(ctx context.Context, s Stream, addr string) (bool, error) // nil suppresses nothing
}

func (r *Router) Send(ctx context.Context, m *Message) error

type SMTP struct {
    Addr    string            // host:port
    Auth    smtp.Auth         // nil sends without authentication
    Headers map[string]string // added to a copy of every message, e.g. X-SES-CONFIGURATION-SET
    Now     func() time.Time  // stamps the Date header; nil means time.Now
}

func (s *SMTP) Send(ctx context.Context, m *Message) error

var ErrSuppressed = errors.New("recipient suppressed")

const Version = "v0.0.0-dev"

import "github.com/sulv-io/lttr/comark"

func Parse(src []byte) (*Document, error)
func ParseAttrs(s string, base Pos) (Attrs, int, error)
func ParseText(s string, base Pos) (Text, error)
func NodeAttrs(n ast.Node) (Attrs, bool)
func PlainText(n ast.Node, src []byte) string

type Document struct {
    Frontmatter    map[string]any
    FrontmatterPos map[string]Pos // dotted key path ("footer.note") → key position
    Root           ast.Node
    Source         []byte         // the source without a leading BOM
}

func (d *Document) Pos(n ast.Node) Pos

type Pos struct{ Line, Col int }
func (p Pos) String() string // "3:7"

type Error struct {
    Pos Pos
    Msg string
}
func (e *Error) Error() string // "line:col: msg"

type Attrs struct {
    ID       string
    Classes  []string
    Values   map[string]Text   // plain attributes; a flag maps to an empty Text
    Flags    map[string]bool   // bare keys with no value
    Bindings map[string]string // :key="path"
    Pos      Pos               // position of the opening "{"
}

type Text []Part
func (t Text) String() string

type Part struct {
    Lit     string // set when Tag == nil
    Tag     *Tag
    Suspect bool   // Lit came from a malformed "{{" tag attempt
}

type Tag struct {
    Path        string // dotted, e.g. "driver.first_name"
    Fallback    string
    HasFallback bool
    Pos         Pos
}
func (t Tag) String() string // {{path}} or {{path | fallback}}

var (
    KindComponent       = ast.NewNodeKind("Component")
    KindSlot            = ast.NewNodeKind("Slot")
    KindInlineComponent = ast.NewNodeKind("InlineComponent")
    KindSpan            = ast.NewNodeKind("Span")
    KindMergeTag        = ast.NewNodeKind("MergeTag")
)

import "github.com/sulv-io/lttr/data"

type Money struct {
    Minor    int64    // minor units, e.g. cents
    Currency Currency
}

func XCD(minor int64) Money
func USD(minor int64) Money
func (m Money) String() string // "EC$1,019.90", "US$378", "−US$65"
func (m Money) Approx() string // "≈ US$378"

type Exact Money
func (e Exact) String() string // always two decimals: "EC$1,085.00"

type Currency string

const (
    XCDCode Currency = "XCD" // EC$
    USDCode Currency = "USD" // US$
    EURCode Currency = "EUR" // €
    GBPCode Currency = "GBP" // £
)

type Receipt struct {
    Lines      []ReceiptLine
    Fees       []Fee
    Total      Money
    TotalUSD   *Money // optional; shown as ≈ US$
    TotalLabel string // default "Total"
}

type ReceiptLine struct {
    Name, Detail string
    Qty          int
    Amount       Money
    Thumb        string
    Tone         Tone
}

type Fee struct {
    Label  string
    Amount Money
}

type Product struct {
    Name        string
    Price       Money
    Href, Image string
    Tone        Tone
}

type StockItem struct {
    Name, SKU string
    Left      int
}

type Tone string

const (
    ToneNone Tone = ""
    ToneWarm Tone = "warm"
    ToneSea  Tone = "sea"
    ToneSun  Tone = "sun"
    ToneMap  Tone = "map"
)

func (t Tone) Valid() bool

type Recipient struct {
    Address        string // RFC 5322 address
    FirstName      string `json:"first_name"`
    Region         string `json:"region"`
    EntityAddress  string `json:"entity_address"`
    PreferencesURL string `json:"preferences_url"`
    UnsubscribeURL string `json:"unsubscribe_url"`
}

func NewScope(roots ...Root) Scope
func (s Scope) Resolve(path string) (Accessor, error)

type Root struct {
    Slot int
    Type reflect.Type
}

func (a Accessor) Get(roots []reflect.Value) (reflect.Value, bool)
func (a Accessor) Path() string
func (a Accessor) Type() reflect.Type

func IsScalar(t reflect.Type) bool
func FormatScalar(v reflect.Value) string

import "github.com/sulv-io/lttr/ir"

func Compile(name string, src []byte, opts Options) (*Document, error)
func CompileCopy(label, src string, vars reflect.Type) (Inline, error)
func CompileCopyText(label, src string, vars reflect.Type) (Text, error)

type Options struct {
    Data      reflect.Type // the template's T
    Recipient reflect.Type // reflect.TypeOf(data.Recipient{})
    Vars      reflect.Type // lttr.Vars: {name} placeholders in footer.* frontmatter
}

type Document struct {
    Name     string
    Front    Frontmatter
    Modules  []Module
    Warnings []Diagnostic
    Tags     []TagUse
}

type Error struct {
    Name string // template (or copy) name
    Pos  Pos
    Msg  string
}
func (e *Error) Error() string // "name:line:col: msg", or "line:col: msg" without a name

type Diagnostic struct {
    Pos Pos
    Msg string
}
func (d Diagnostic) Format(name string) string // "name:line:col: warning: msg"

type Pos = comark.Pos

type Frontmatter struct {
    Template, Family                string
    Subject, Preheader, From, Issue Text
    Legal                           bool
    Footer                          FooterOverrides
    Pos                             map[string]Pos // dotted key → key position
}

type FooterOverrides struct {
    Note, Reason, OptOut *Inline // Markdown, one paragraph
    About                *Text   // F2 {about}; empty drops the service line
    Nav                  *bool   // F1 nav row
}

type TagUse struct {
    Path    string
    Type    reflect.Type // the resolved type, pointers dereferenced
    Pos     Pos
    Binding bool         // a :key="path" binding rather than a {{path}} tag
}

type Module interface {
    Kind() Kind
    Class() Class
    Pos() Pos
}

type Kind string
func Lookup(name string) (Kind, bool)

type Class uint8

const (
    ClassHero Class = iota + 1
    ClassBand
    ClassTabular
    ClassBody
    ClassNotice
    ClassSignoff
    ClassTail
    ClassRule
    ClassEditorial
)

type Block interface{ /* unexported */ }       // Heading, Para, ActionRow or List
type InlineNode interface{ /* unexported */ }  // TextRun, Strong, Em, CodeSpan, Link, Span or Break
type Inline []InlineNode

type SpanStyle uint8

const (
    Muted SpanStyle = 1 << iota // .muted
    Teal                        // .teal
    Mono                        // .mono
    Small                       // .small
    Bold                        // .bold
)

func (s SpanStyle) Has(x SpanStyle) bool

type Text []Part

type Part struct {
    Lit string
    Ref *Ref
}

type Ref struct {
    Path        string
    Fallback    string
    HasFallback bool
    Pos         Pos
    Get         data.Accessor // precompiled; indexes Env.Roots
    Placeholder bool          // a {name} placeholder rather than a {{path}} merge tag
}
func (r *Ref) String() string // {{path}} or {name}

type Env struct {
    Name  string          // template name, for error positions
    Roots []reflect.Value // [data, recipient, vars], indexed by the Slot constants
}

const (
    SlotData      = 0
    SlotRecipient = 1
    SlotVars      = 2
)

func Lit(s string) Text
func (t Text) Literal() (string, bool)
func (t Text) Eval(env Env) (string, error)
func (t Text) EvalOptional(env Env) (string, error)
func (t Text) EvalURL(env Env) (string, error)
func (t Text) EvalURLOptional(env Env) (string, error)

import "github.com/sulv-io/lttr/layout"

func Arrange(mods []ir.Module, header HeaderVariant) []Section

type Section struct {
    Module            ir.Module
    PadTop, PadBottom int
}

type Document struct {
    Name               string // template name, for render errors
    Subject, Preheader string
    Header             Header
    Sections           []Section
    Footer             Footer
    Theme              theme.Theme
    AllowRelativeURLs  bool
}

type Header struct {
    Variant     HeaderVariant
    Banner      string // H2 banner text
    Masthead    string // H3 masthead text
    LogoURL     string
    LogoDarkURL string
}

type Footer struct {
    Variant  FooterVariant
    Nav      []ir.Action // F1 nav row; empty = no row
    Lead     ir.Inline   // F1 reason · F2 note · F3 opt-out · F3·i internal line
    Links    ir.Inline   // F1 unsubscribe and preferences links
    Service  ir.Inline   // F2 service line; empty = dropped
    Address  ir.Text     // "{brand} · {address}"
    TextURLs []TextURL   // plain-text footer URL lines, in order
}

type TextURL struct {
    Label  string
    URL    ir.Text
    Source string // the copy it was written in, naming render errors
}

type HeaderVariant uint8

const (
    H1 HeaderVariant = iota + 1 // logo
    H2                          // logo with the internal banner
    H3                          // newsletter masthead
)

type FooterVariant uint8

const (
    F1         FooterVariant = iota + 1 // marketing: nav, reason, unsubscribe and preferences
    F2                                  // service: note, "service email about …", address
    F3                                  // outreach: address and opt-out
    F3Internal                          // internal: internal line and address
)

type Rule struct {
    Prev, Next          Selector
    PrevBottom, NextTop *int
    Source              string // the handoff frame the value comes from, e.g. "Q2 (D10)"
}

type Selector struct {
    Class ir.Class
    Kind  ir.Kind // empty matches any kind of Class
}

import "github.com/sulv-io/lttr/theme"

type Theme struct {
    Light Light
    Dark  Dark
    Fonts Fonts
    Brand Brand
}

func (t Theme) Validate() error

type Color string
func (c Color) Valid() bool

type Fonts struct {
    Serif, Sans, Mono string
}

type Brand struct {
    Name     string // header text, logo alt and the default sign-off
    Logo     string // file name under Config.AssetBase, e.g. "logo.png" (72×72, shown at LogoSize)
    LogoDark string // white-chip version for dark mode
    LogoSize int    // display size in CSS pixels, 16..96
}

type Light struct {
    Ink, Body, Secondary, StrongBody Color
    Action, PillText, Accent         Color
    Hairline, RowRule, NoticeBorder  Color
    Ground, Canvas                   Color
    WarnBg, WarnBorder, WarnText     Color
    OutOfStock                       Color
    BannerBg, BannerText             Color
    Warm, Sea, Map, Sun              Color
}

type Dark struct {
    Canvas, Footer, Hairline     Color
    Headline, Body               Color
    Action, PillText             Color
    CurrentStep, AccentText      Color
    BannerBg, BannerText         Color
    Placeholder                  Color
    WarnBg, WarnBorder, WarnText Color
    OutOfStock                   Color
}

import htmlr "github.com/sulv-io/lttr/render/html"

func Render(doc layout.Document, env ir.Env) (string, error)
func CheckURL(raw string, allowRelative bool) (template.URL, error)

type Pill struct {
    Href       template.URL
    Label      string
    Fill, Text theme.Color
    Width      int // estimated width in px; zero means computed from Label
}

type Style struct{ /* unexported */ }
func (s Style) CSS() template.CSS

import "github.com/sulv-io/lttr/render/text"

func Render(doc layout.Document, env ir.Env) (string, error)

import "github.com/sulv-io/lttr/mapbox"

type Static struct {
    Token   string
    Style   string // owner/id map style
    Width   int    // default 600
    Height  int    // default 240
    Padding int    // default 80

    RouteColor   string // route line stroke; required, six hex digits without '#'
    PickupColor  string // pickup pin; required
    DropoffColor string // drop-off pin; required
}

func (s Static) URL(pickup, dropoff Point, route []Point) (string, error)
func (s Static) Fetch(ctx context.Context, c *http.Client, pickup, dropoff Point, route []Point) ([]byte, error)

type Point struct {
    Lng, Lat float64
}