with a title table(rows ...string) string // a real row(label, valueHTML string) string // one label/value link(url string) string // escaped kvTable(m *OMap) string // every key/value of an object as one table renderDataAsTable(v any, depth int) string // arbitrary nested JSON as tables (generic fallback) ``` Example: ```go body := section("💳 Payment Details", table( row("Event", h(event)), row("Amount", h(amount)+" "+h(currency)), row("Customer", h(customer)), )) + section("📝 Note", `
`+esc(note)+`
`) ``` **Other classes you can use inside a section:** | Class | Use for | |-------|---------| | `.subsection-title` | A bold sub-heading | | `.data-box` | A `
` for raw JSON, headers, or code (dark block) |
| `.message-box` | Quoted free text such as an SMS body |
| `.error-box` | Error details |
| `.array-item` / `.array-item-title` | A card for one item of a list (an alert, a commit) |
| `.path-title` | A breadcrumb pill above a nested table, e.g. `order->items->[0]` |
| `.commit-item` with `.sha`, `.who`, `.msg` | The GitHub commit card, reusable for any id + author + message list |

### Reading values

```go
str(v)                       // scalar as text ("" for null, "true"/"false" for bools)
strOr(v, "N/A")              // PHP's `?? 'N/A'`: only missing/null takes the default
get(payload, "repository", "full_name")   // nested lookup, nil if any step is missing
asObject(v)                  // *OMap or nil
isContainer(v)               // object or array?
num(v)                       // float64 for a json.Number, else 0
```

### Escaping

Two helpers, use the right one:

- `h(s)` for anything that goes into an attribute or a single-line value.
- `esc(s)` for free text that may contain line breaks (commit messages, descriptions, SMS bodies). It escapes **and** converts newlines to `
`.

Subjects are plain text, never escaped.

---

## 📝 Example: Simple Parser

`parser_simplepay.go` for a fictional "SimplePay" service:

```go
package main

import "net/http"

func simplepayParse(raw []byte, headers http.Header, meta Meta) (string, string, bool) {
	payload := asObject(mustDecode(raw))
	if payload == nil {
		return "", "", false // not a JSON object: use the default email
	}

	event := strOr(payload.Get("event"), "Unknown")
	amount := strOr(payload.Get("amount"), "N/A")
	currency := strOr(payload.Get("currency"), "USD")
	customer := strOr(payload.Get("customer_email"), "Unknown")
	note := strOr(payload.Get("note"), "")

	body := section("💳 Payment Details", table(
		row("Event", h(event)),
		row("Amount", h(amount)+" "+h(currency)),
		row("Customer", h(customer)),
		row("IP Address", h(meta.IP)),
	))
	if note != "" {
		body += section("📝 Note", ``+esc(note)+``)
	}

	html := emailShell("💳 SimplePay: "+h(event), h(meta.Date), body,
		"This SimplePay webhook was automatically forwarded to your email address.")
	return html, "💳 SimplePay " + event + " - " + amount + " " + currency, true
}

func mustDecode(raw []byte) any {
	v, err := decodeJSON(raw)
	if err != nil {
		return nil
	}
	return v
}
```

---

## 🎨 Style Guidelines

The shell owns colours, fonts, and spacing. Parsers only choose structure and words.

1. **Sections**: one `section` per logical group
2. **Tables**: `table(row(...))` for label/value pairs, never hand-written divs
3. **Lists**: one `.array-item` card per item (alerts, commits, line items)
4. **Raw data**: `.data-box` for anything the reader might want to copy
5. **Free text**: `.message-box`, escaped with `esc`
6. **Links**: `link(url)`

### Emojis

- 💳 Payment events
- 🚀 Deployments/releases
- 📤 Push/upload events
- 🔀 Merge/pull request events
- ⚠️ Errors/warnings
- ✅ Success events
- 🔔 Notifications

Put the same emoji at the start of the subject line so inbox filters can key on it.

---

## 🔒 Security Best Practices

### 1. Escape everything dynamic

```go
// ❌ DANGEROUS - XSS in the email
body += "" + str(payload.Get("user_input")) + ""

// ✅ SAFE (single line)
body += "" + h(str(payload.Get("user_input"))) + ""

// ✅ SAFE (multi-line free text)
body += `` + esc(str(payload.Get("message"))) + ``
```

### 2. Validate input

```go
if payload == nil || payload.Get("event_type") == nil {
    return "", "", false
}
```

### 3. Verify signatures (optional)

```go
sig := headers.Get("X-Service-Signature")
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(raw)
if sig == "" || !hmac.Equal([]byte(sig), []byte(hex.EncodeToString(mac.Sum(nil)))) {
    return "", "", false
}
```

---

## 🧪 Testing Your Parser

### 1. Unit test

`main_test.go` has a `capture(t)` helper that swaps the mailer for an in-memory one and a `do(...)` helper that drives the handler. Add a test in the same style:

```go
func TestSimplePay(t *testing.T) {
	c := capture(t)
	_, out := do(t, "POST", "/t%40e.com/simplepay", `{"event":"paid","amount":"9.99"}`, nil)
	if out["subject"] != "💳 SimplePay paid - 9.99 USD" || !strings.Contains(c.html, "9.99") {
		t.Fatalf("%v", out["subject"])
	}
}
```

```bash
go test ./...
```

### 2. Run locally without sending mail

Point the server at any SMTP sink (the repo's tests don't need one, but for eyeballing the HTML):

```bash
LISTEN=127.0.0.1:8098 SMTP_ADDR=127.0.0.1:2525 go run .
curl -X POST http://127.0.0.1:8098/test%40example.com/simplepay \
  -H "Content-Type: application/json" \
  -d '{"event":"paid","amount":"9.99","currency":"USD"}'
```

The JSON response tells you which parser ran and what subject was used.

### 3. Test the failure case

Send invalid data and confirm the response shows the default subject (`‼️ Webhook Request Received`).

### 4. Test a lowercase header

Real deliveries over HTTP/2 arrive with lowercase header names. `headers.Get` handles it, but if you read `headers[...]` directly you will miss them.

---

## 📋 Parser Checklist

- [ ] File is `parser_{servicename}.go` and the function matches the `Parser` type
- [ ] Registered in the `parsers` map in `main.go`
- [ ] Returns `false` on failure/invalid data
- [ ] Header lookups use `headers.Get`
- [ ] All dynamic content goes through `h` or `esc`
- [ ] Body uses `section` / `table` / `row` and is wrapped with `emailShell`
- [ ] Subject line includes an emoji and key information
- [ ] Unit test added and `go test ./...` passes
- [ ] README section added for the parser

---

## 🤝 Contributing Parsers

1. Add `parser_{servicename}.go` and register it
2. Add a test
3. Document usage in README.md (service name, URL format, supported events)
4. Submit a pull request with an example payload in the description

---

## 📚 Reference

### Existing parsers

- `parser_github.go` - Multiple event types, commit cards, generic fallback
- `parser_grafana.go` - Nested alert cards with label and annotation tables
- `parser_json.go` - Recursive rendering with path breadcrumbs
- `parser_wxinteract.go` - Many event types in one switch
- `render.go` - `emailShell`, `esc`, `h`, `decodeJSON`, `renderDataAsTable`, table helpers
- `main.go` - Routing, JSON response, default email, parser registry
- `mail.go` - SMTP delivery

### Configuration

| Variable | Default | Meaning |
|----------|---------|---------|
| `LISTEN` | `127.0.0.1:8080` | Address to listen on (`:8080` in the container) |
| `SMTP_ADDR` | `127.0.0.1:25` | SMTP relay (`172.17.0.1:25` in the container, the host's postfix) |
| `MAIL_FROM` | `no-reply@dixon.cx` | Envelope and From address |
| `PUBLIC_HOST` | `webhook.me.uk` | Host shown in email footers |

---

## ❓ FAQ

**Q: Can I use external libraries?**
A: The project has no dependencies beyond the standard library. Keep it that way unless there is a very good reason.

**Q: Can I make API calls in a parser?**
A: Not recommended. Parsers should be fast and not depend on external services.

**Q: What if my service sends different content types?**
A: Check `meta.ContentType` and parse accordingly.

**Q: Can I create multiple parsers for one service?**
A: Yes. Register as many names as you like.

**Q: Can I change the colours or fonts?**
A: Change `shellSrc` in `render.go` and every email picks it up.

---

**Happy Parser Building! 🚀**