Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
feat(api): format webhook email payload (#955)
Acho Arnold96a431926853
diff --git a/api/pkg/emails/event_payload_formatter.go b/api/pkg/emails/event_payload_formatter.gonew file mode 100644index 00000000..130aaf6f--- /dev/null+++ b/api/pkg/emails/event_payload_formatter.go@@ -0,0 +1,128 @@+package emails++import (+ "bytes"+ "encoding/json"+ "html"+ "html/template"+ "strings"+)++const (+ eventPayloadCodeBlockStyle = "margin:0;padding:12px;border:1px solid #D0D7DE;border-radius:6px;background:#F6F8FA;color:#24292F;font-family:Consolas,Monaco,'Courier New',monospace;font-size:13px;line-height:1.5;white-space:pre-wrap;word-break:break-word;overflow-wrap:anywhere;"+ jsonKeyStyle = "color:#0550AE;font-weight:600;"+ jsonStringStyle = "color:#0A3069;"+ jsonNumberStyle = "color:#953800;"+ jsonLiteralStyle = "color:#8250DF;"+)++func formatEventPayload(payload string) (string, template.HTML) {+ formattedPayload, isJSON := indentEventPayloadJSON(payload)+ content := html.EscapeString(formattedPayload)+ if isJSON {+ content = highlightEventPayloadJSON(formattedPayload)+ }++ // Every payload token is escaped before this trusted wrapper is constructed.+ richPayload := template.HTML(`<pre style="` + eventPayloadCodeBlockStyle + `">` + content + `</pre>`)+ return formattedPayload, richPayload+}++func indentEventPayloadJSON(payload string) (string, bool) {+ var formatted bytes.Buffer+ if err := json.Indent(&formatted, []byte(payload), "", " "); err != nil {+ return payload, false+ }++ return formatted.String(), true+}++func highlightEventPayloadJSON(payload string) string {+ var highlighted strings.Builder+ highlighted.Grow(len(payload))++ for index := 0; index < len(payload); {+ switch {+ case payload[index] == '"':+ end := eventPayloadJSONStringEnd(payload, index)+ style := jsonStringStyle+ if eventPayloadNextNonSpace(payload, end) == ':' {+ style = jsonKeyStyle+ }+ writeEventPayloadToken(&highlighted, style, payload[index:end])+ index = end+ case payload[index] == '-' || isEventPayloadDigit(payload[index]):+ end := index + 1+ // json.Indent already validated this as JSON, so this continuation set only sees JSON number bytes.+ for end < len(payload) && isEventPayloadNumberCharacter(payload[end]) {+ end+++ }+ writeEventPayloadToken(&highlighted, jsonNumberStyle, payload[index:end])+ index = end+ case strings.HasPrefix(payload[index:], "true"):+ writeEventPayloadToken(&highlighted, jsonLiteralStyle, "true")+ index += len("true")+ case strings.HasPrefix(payload[index:], "false"):+ writeEventPayloadToken(&highlighted, jsonLiteralStyle, "false")+ index += len("false")+ case strings.HasPrefix(payload[index:], "null"):+ writeEventPayloadToken(&highlighted, jsonLiteralStyle, "null")+ index += len("null")+ default:+ highlighted.WriteString(html.EscapeString(payload[index : index+1]))+ index+++ }+ }++ return highlighted.String()+}++func eventPayloadJSONStringEnd(payload string, start int) int {+ escaped := false+ for index := start + 1; index < len(payload); index++ {+ switch {+ case escaped:+ escaped = false+ case payload[index] == '\\':+ escaped = true+ case payload[index] == '"':+ return index + 1+ }+ }++ return len(payload)+}++func eventPayloadNextNonSpace(payload string, start int) byte {+ for index := start; index < len(payload); index++ {+ switch payload[index] {+ case ' ', '\n', '\r', '\t':+ continue+ default:+ return payload[index]+ }+ }++ return 0+}++func isEventPayloadDigit(value byte) bool {+ return value >= '0' && value <= '9'+}++func isEventPayloadNumberCharacter(value byte) bool {+ return isEventPayloadDigit(value) ||+ value == '-' ||+ value == '+' ||+ value == '.' ||+ value == 'e' ||+ value == 'E'+}++func writeEventPayloadToken(builder *strings.Builder, style string, token string) {+ builder.WriteString(`<span style="`)+ builder.WriteString(style)+ builder.WriteString(`">`)+ builder.WriteString(html.EscapeString(token))+ builder.WriteString(`</span>`)+}diff --git a/api/pkg/emails/event_payload_formatter_test.go b/api/pkg/emails/event_payload_formatter_test.gonew file mode 100644index 00000000..9617ebb0--- /dev/null+++ b/api/pkg/emails/event_payload_formatter_test.go@@ -0,0 +1,113 @@+package emails++import (+ "strings"+ "testing"++ "github.com/stretchr/testify/assert"+)++func TestFormatEventPayloadIndentsAndHighlightsJSON(t *testing.T) {+ payload := `{"message":"hello","count":2,"ratio":1.5,"enabled":true,"disabled":false,"missing":null,"nested":{"value":"ok"}}`++ plain, rich := formatEventPayload(payload)+ html := string(rich)++ assert.Equal(t, `{+ "message": "hello",+ "count": 2,+ "ratio": 1.5,+ "enabled": true,+ "disabled": false,+ "missing": null,+ "nested": {+ "value": "ok"+ }+}`, plain)+ assert.Contains(t, html, `<span style="color:#0550AE;font-weight:600;">"message"</span>`)+ assert.Contains(t, html, `<span style="color:#0A3069;">"hello"</span>`)+ assert.Contains(t, html, `<span style="color:#953800;">2</span>`)+ assert.Contains(t, html, `<span style="color:#953800;">1.5</span>`)+ assert.Contains(t, html, `<span style="color:#8250DF;">true</span>`)+ assert.Contains(t, html, `<span style="color:#8250DF;">false</span>`)+ assert.Contains(t, html, `<span style="color:#8250DF;">null</span>`)+ assert.Contains(t, html, `white-space:pre-wrap`)+}++func TestFormatEventPayloadEscapesPayloadHTML(t *testing.T) {+ plain, rich := formatEventPayload(`{"message":"<script>alert(\"x\")</script>&"}`)+ html := string(rich)++ assert.Contains(t, plain, `<script>alert`)+ assert.NotContains(t, html, `<script>`)+ assert.Contains(t, html, `<script>`)+ assert.Contains(t, html, `&`)+}++func TestFormatEventPayloadPreservesInvalidJSONWithoutHighlighting(t *testing.T) {+ payload := "line one\n <strong>line two</strong>"++ plain, rich := formatEventPayload(payload)+ html := string(rich)++ assert.Equal(t, payload, plain)+ assert.Contains(t, html, "line one\n <strong>line two</strong>")+ assert.NotContains(t, html, `<strong>`)+ assert.NotContains(t, html, `<span style="color:`)+ assert.Equal(t, 1, strings.Count(html, `<pre style=`))+}++func TestFormatEventPayloadHandlesTopLevelPayloadShapes(t *testing.T) {+ tests := []struct {+ name string+ payload string+ wantPlain string+ wantHTMLContains []string+ wantHTMLNotContains []string+ }{+ {+ name: "empty payload falls back to unhighlighted block",+ payload: "",+ wantPlain: "",+ wantHTMLContains: []string{`<pre style="`, `</pre>`},+ wantHTMLNotContains: []string{`<span style="color:`},+ },+ {+ name: "top-level number stays valid JSON",+ payload: "42",+ wantPlain: "42",+ wantHTMLContains: []string{`<span style="color:#953800;">42</span>`},+ wantHTMLNotContains: []string{`color:#0550AE`},+ },+ {+ name: "json array stays readable and escaped",+ payload: `[{"message":"<b>safe</b>"},true,null,3]`,+ wantPlain: "[\n {\n \"message\": \"<b>safe</b>\"\n },\n true,\n null,\n 3\n]",+ wantHTMLContains: []string{+ "[\n {",+ `"message"`,+ `<b>safe</b>`,+ `<span style="color:#953800;">3</span>`,+ },+ wantHTMLNotContains: []string{`<b>safe</b>`},+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ plain, rich := formatEventPayload(tt.payload)+ html := string(rich)++ assert.Equal(t, tt.wantPlain, plain)+ assert.Equal(t, 1, strings.Count(html, `<pre style=`))++ for _, want := range tt.wantHTMLContains {+ assert.Contains(t, html, want)+ }++ for _, unwanted := range tt.wantHTMLNotContains {+ assert.NotContains(t, html, unwanted)+ }+ })+ }+}diff --git a/api/pkg/emails/hermes_notification_email_factory.go b/api/pkg/emails/hermes_notification_email_factory.goindex 7c4b7bc5..73f129de 100644--- a/api/pkg/emails/hermes_notification_email_factory.go+++ b/api/pkg/emails/hermes_notification_email_factory.go@@ -2,6 +2,7 @@ package emailsimport ("fmt"+ "strings""time""github.com/NdoleStudio/httpsms/pkg/events"@@ -17,6 +18,8 @@ type hermesNotificationEmailFactory struct {generator hermes.Hermes}+const webhookSendFailedEventPayloadPlaceholder = "__HTTPSMS_WEBHOOK_SEND_FAILED_EVENT_PAYLOAD__"+// NewHermesNotificationEmailFactory creates a new instance of the UserEmailFactoryfunc NewHermesNotificationEmailFactory(config *HermesGeneratorConfig) NotificationEmailFactory {return &hermesNotificationEmailFactory{@@ -76,6 +79,8 @@ func (factory *hermesNotificationEmailFactory) DiscordSendFailed(user *entities.}func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.User, payload *events.WebhookSendFailedPayload) (*Email, error) {+ formattedPayload, formattedPayloadHTML := formatEventPayload(payload.EventPayload)+email := hermes.Email{Body: hermes.Body{Title: "Hello",@@ -89,7 +94,11 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.{Key: "Phone Number", Value: factory.formatPhoneNumber(payload.Owner)},{Key: "HTTP Response Code", Value: factory.formatHTTPResponseCode(payload.HTTPResponseStatusCode)},{Key: "Error Message / HTTP Response", Value: payload.ErrorMessage},- {Key: "Event Payload", Value: payload.EventPayload},+ {+ Key: "Event Payload",+ Value: webhookSendFailedEventPayloadPlaceholder,+ UnsafeValue: formattedPayloadHTML,+ },},Actions: []hermes.Action{{@@ -118,6 +127,8 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.if err != nil {return nil, stacktrace.Propagate(err, "cannot generate text email")}+ // Hermes/html2text collapses dictionary whitespace, so restore the payload after plain-text generation.+ text = replaceWebhookSendFailedEventPayloadPlaceholder(text, formattedPayload)return &Email{ToEmail: user.Email,@@ -127,6 +138,15 @@ func (factory *hermesNotificationEmailFactory) WebhookSendFailed(user *entities.}, nil}+func replaceWebhookSendFailedEventPayloadPlaceholder(text string, formattedPayload string) string {+ before, after, found := strings.Cut(text, webhookSendFailedEventPayloadPlaceholder)+ if !found {+ return text+ }++ return before + formattedPayload + after+}+func (factory *hermesNotificationEmailFactory) MessageExpired(user *entities.User, payload *events.MessageSendExpiredPayload) (*Email, error) {email := hermes.Email{Body: hermes.Body{diff --git a/api/pkg/emails/hermes_notification_email_factory_test.go b/api/pkg/emails/hermes_notification_email_factory_test.gonew file mode 100644index 00000000..37c9333a--- /dev/null+++ b/api/pkg/emails/hermes_notification_email_factory_test.go@@ -0,0 +1,105 @@+package emails++import (+ "strings"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func testNotificationEmailFactory() NotificationEmailFactory {+ return NewHermesNotificationEmailFactory(&HermesGeneratorConfig{+ AppURL: "https://httpsms.com",+ AppName: "httpSMS",+ AppLogoURL: "https://httpsms.com/logo.png",+ })+}++func TestWebhookSendFailedFormatsOnlyEventPayload(t *testing.T) {+ statusCode := 500+ factory := testNotificationEmailFactory()+ user := &entities.User{+ Email: "[email protected]",+ Timezone: "UTC",+ }+ payload := &events.WebhookSendFailedPayload{+ WebhookID: uuid.New(),+ WebhookURL: "https://example.com/webhooks",+ Owner: "+237612345678",+ EventID: "event-id",+ EventType: "message.phone.received",+ EventPayload: `{"message":"hello","retry":false}`,+ HTTPResponseStatusCode: &statusCode,+ ErrorMessage: "plain failure response",+ }++ email, err := factory.WebhookSendFailed(user, payload)+ require.NoError(t, err)++ assert.Equal(t, "[email protected]", email.ToEmail)+ assert.Equal(t, "📢 We could not forward a webhook event to your server", email.Subject)+ assert.Contains(t, email.HTML, `<pre style=`)+ assert.Equal(t, 1, strings.Count(email.HTML, `<pre style=`))+ assert.Contains(t, email.HTML, `"message"`)+ assert.Contains(t, email.HTML, `plain failure response`)+ assert.Contains(t, email.Text, `"message": "hello"`)+ assert.Contains(t, email.Text, `"retry": false`)+ assert.NotContains(t, email.Text, "<pre")+ assert.NotContains(t, email.Text, webhookSendFailedEventPayloadPlaceholder)+}++func TestWebhookSendFailedPreservesNonJSONEventPayload(t *testing.T) {+ factory := testNotificationEmailFactory()+ user := &entities.User{+ Email: "[email protected]",+ Timezone: "UTC",+ }+ payload := &events.WebhookSendFailedPayload{+ WebhookID: uuid.New(),+ WebhookURL: "https://example.com/webhooks",+ Owner: "+237612345678",+ EventID: "event-id",+ EventType: "message.phone.received",+ EventPayload: "line one\n line two",+ ErrorMessage: "plain failure response",+ }++ email, err := factory.WebhookSendFailed(user, payload)+ require.NoError(t, err)++ assert.Contains(t, email.HTML, "line one\n line two")+ assert.NotContains(t, email.HTML, `<span style="color:`)+ assert.Contains(t, email.Text, "line one\n line two")+}++func TestReplaceWebhookSendFailedEventPayloadPlaceholder(t *testing.T) {+ tests := []struct {+ name string+ text string+ formattedPayload string+ want string+ }{+ {+ name: "replaces placeholder and preserves remaining text",+ text: "before\n" + webhookSendFailedEventPayloadPlaceholder + "\nafter",+ formattedPayload: "{\n \"message\": \"hello\"\n}",+ want: "before\n{\n \"message\": \"hello\"\n}\nafter",+ },+ {+ name: "returns original text when placeholder is missing",+ text: "before\nafter",+ formattedPayload: "{\n \"message\": \"hello\"\n}",+ want: "before\nafter",+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ assert.Equal(t, tt.want, replaceWebhookSendFailedEventPayloadPlaceholder(tt.text, tt.formattedPayload))+ })+ }+}diff --git a/api/pkg/emails/hermes_theme.go b/api/pkg/emails/hermes_theme.goindex 9d8cc471..34e35d5c 100644--- a/api/pkg/emails/hermes_theme.go+++ b/api/pkg/emails/hermes_theme.go@@ -327,7 +327,7 @@ func (dt *hermesTheme) HTMLTemplate() string {<dl class="body-dictionary">{{ range $entry := . }}<dt>{{ $entry.Key }}:</dt>- <dd>{{ $entry.Value }}</dd>+ <dd>{{ if $entry.UnsafeValue }}{{ $entry.UnsafeValue }}{{ else }}{{ $entry.Value }}{{ end }}</dd>{{ end }}</dl>{{ end }}diff --git a/api/pkg/emails/hermes_theme_test.go b/api/pkg/emails/hermes_theme_test.gonew file mode 100644index 00000000..25b69508--- /dev/null+++ b/api/pkg/emails/hermes_theme_test.go@@ -0,0 +1,46 @@+package emails++import (+ "html/template"+ "testing"++ "github.com/go-hermes/hermes/v2"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestHermesThemeRendersUnsafeDictionaryValueOnlyWhenProvided(t *testing.T) {+ generator := (&HermesGeneratorConfig{+ AppURL: "https://httpsms.com",+ AppName: "httpSMS",+ AppLogoURL: "https://httpsms.com/logo.png",+ }).Generator()++ email := hermes.Email{+ Body: hermes.Body{+ Title: "Hello",+ Dictionary: []hermes.Entry{+ {Key: "Normal", Value: "<b>escaped</b>"},+ {+ Key: "Payload",+ Value: "plain payload",+ UnsafeValue: template.HTML(`<pre style="white-space:pre-wrap">rich payload</pre>`),+ },+ },+ },+ }++ htmlEmail, err := generator.GenerateHTML(email)+ require.NoError(t, err)++ textEmail, err := generator.GeneratePlainText(email)+ require.NoError(t, err)++ assert.Contains(t, htmlEmail, `<b>escaped</b>`)+ assert.NotContains(t, htmlEmail, `<b>escaped</b>`)+ assert.Contains(t, htmlEmail, `<pre style="white-space:pre-wrap">rich payload</pre>`)+ assert.NotContains(t, htmlEmail, `<dd>plain payload</dd>`)+ assert.Contains(t, textEmail, "Normal: <b>escaped</b>")+ assert.Contains(t, textEmail, "Payload: plain payload")+ assert.NotContains(t, textEmail, "<pre")+}diff --git a/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md b/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.mdnew file mode 100644index 00000000..c5c9b3e2--- /dev/null+++ b/docs/superpowers/plans/2026-07-18-webhook-email-payload-formatting.md@@ -0,0 +1,593 @@+# Webhook Email Payload Formatting Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Render the webhook failure email's Event Payload as readable indented JSON with safe lightweight syntax colors in HTML and readable indentation in plain text.++**Architecture:** Add a focused formatter in `api/pkg/emails` that produces a plain string and a safely constructed `template.HTML` code block. Teach the custom Hermes HTML dictionary template to use `hermes.Entry.UnsafeValue` when explicitly supplied, then wire only the webhook email's Event Payload entry to that path.++**Tech Stack:** Go 1.25.8 module, Go standard library (`bytes`, `encoding/json`, `html`, `html/template`, `strings`), go-hermes v2.6.2, testify v1.11.1.++## Global Constraints++- Format only the webhook email's **Event Payload** value.+- Leave SMS content, failure reasons, HTTP responses, and every other email field unchanged.+- Pretty-print valid JSON with indentation.+- Render valid JSON in HTML with lightweight colors for keys, strings, numbers, booleans, and `null`.+- Render invalid JSON in the same monospace block with original whitespace and no syntax colors.+- Add no third-party dependency.+- HTML-escape every payload token before converting the completed markup to `template.HTML`.+- Invalid JSON must not prevent email generation or delivery.+- Preserve the existing plain-text email behavior except for readable payload indentation.+- Use `stacktrace.Propagate` for existing Hermes generation errors; this feature introduces no new returned error.++---++## File Structure++- Create `api/pkg/emails/event_payload_formatter.go`: JSON indentation, token highlighting, HTML escaping, and code-block construction.+- Create `api/pkg/emails/event_payload_formatter_test.go`: focused tests for valid JSON tokens, escaping, and invalid JSON fallback.+- Create `api/pkg/emails/hermes_theme_test.go`: verifies safe opt-in HTML dictionary rendering and unchanged plain-text rendering.+- Modify `api/pkg/emails/hermes_theme.go:325-334`: render `Entry.UnsafeValue` only when present.+- Create `api/pkg/emails/hermes_notification_email_factory_test.go`: end-to-end factory coverage for the webhook notification email.+- Modify `api/pkg/emails/hermes_notification_email_factory.go:78-122`: format and attach only the Event Payload dictionary entry.++### Task 1: Build the event payload formatter++**Files:**+- Create: `api/pkg/emails/event_payload_formatter.go`+- Create: `api/pkg/emails/event_payload_formatter_test.go`++**Interfaces:**+- Consumes: a raw webhook event payload `string`.+- Produces: `formatEventPayload(payload string) (string, template.HTML)`.+- Produces: plain indented JSON for `hermes.Entry.Value` and an escaped styled code block for `hermes.Entry.UnsafeValue`.++- [ ] **Step 1: Write the failing formatter tests**++Create `api/pkg/emails/event_payload_formatter_test.go`:++```go+package emails++import (+ "strings"+ "testing"++ "github.com/stretchr/testify/assert"+)++func TestFormatEventPayloadIndentsAndHighlightsJSON(t *testing.T) {+ payload := `{"message":"hello","count":2,"ratio":1.5,"enabled":true,"disabled":false,"missing":null,"nested":{"value":"ok"}}`++ plain, rich := formatEventPayload(payload)+ html := string(rich)++ assert.Equal(t, `{+ "message": "hello",+ "count": 2,+ "ratio": 1.5,+ "enabled": true,+ "disabled": false,+ "missing": null,+ "nested": {+ "value": "ok"+ }+}`, plain)+ assert.Contains(t, html, `<span style="color:#0550AE;font-weight:600;">"message"</span>`)+ assert.Contains(t, html, `<span style="color:#0A3069;">"hello"</span>`)+ assert.Contains(t, html, `<span style="color:#953800;">2</span>`)+ assert.Contains(t, html, `<span style="color:#953800;">1.5</span>`)+ assert.Contains(t, html, `<span style="color:#8250DF;">true</span>`)+ assert.Contains(t, html, `<span style="color:#8250DF;">false</span>`)+ assert.Contains(t, html, `<span style="color:#8250DF;">null</span>`)+ assert.Contains(t, html, `white-space:pre-wrap`)+}++func TestFormatEventPayloadEscapesPayloadHTML(t *testing.T) {+ plain, rich := formatEventPayload(`{"message":"<script>alert(\"x\")</script>&"}`)+ html := string(rich)++ assert.Contains(t, plain, `<script>alert`)+ assert.NotContains(t, html, `<script>`)+ assert.Contains(t, html, `<script>`)+ assert.Contains(t, html, `&`)+}++func TestFormatEventPayloadPreservesInvalidJSONWithoutHighlighting(t *testing.T) {+ payload := "line one\n <strong>line two</strong>"++ plain, rich := formatEventPayload(payload)+ html := string(rich)++ assert.Equal(t, payload, plain)+ assert.Contains(t, html, "line one\n <strong>line two</strong>")+ assert.NotContains(t, html, `<strong>`)+ assert.NotContains(t, html, `<span style="color:`)+ assert.Equal(t, 1, strings.Count(html, `<pre style=`))+}+```++- [ ] **Step 2: Run the formatter tests to verify they fail**++Run:++```powershell+Set-Location api+go test ./pkg/emails -run '^TestFormatEventPayload' -count=1+```++Expected: build failure with `undefined: formatEventPayload`.++- [ ] **Step 3: Implement the formatter**++Create `api/pkg/emails/event_payload_formatter.go`:++```go+package emails++import (+ "bytes"+ "encoding/json"+ "html"+ "html/template"+ "strings"+)++const (+ eventPayloadCodeBlockStyle = "margin:0;padding:12px;border:1px solid #D0D7DE;border-radius:6px;background:#F6F8FA;color:#24292F;font-family:Consolas,Monaco,'Courier New',monospace;font-size:13px;line-height:1.5;white-space:pre-wrap;word-break:break-word;overflow-wrap:anywhere;"+ jsonKeyStyle = "color:#0550AE;font-weight:600;"+ jsonStringStyle = "color:#0A3069;"+ jsonNumberStyle = "color:#953800;"+ jsonLiteralStyle = "color:#8250DF;"+)++func formatEventPayload(payload string) (string, template.HTML) {+ formattedPayload, isJSON := indentEventPayloadJSON(payload)+ content := html.EscapeString(formattedPayload)+ if isJSON {+ content = highlightEventPayloadJSON(formattedPayload)+ }++ // Every payload token is escaped before this trusted wrapper is constructed.+ richPayload := template.HTML(`<pre style="` + eventPayloadCodeBlockStyle + `">` + content + `</pre>`)+ return formattedPayload, richPayload+}++func indentEventPayloadJSON(payload string) (string, bool) {+ var formatted bytes.Buffer+ if err := json.Indent(&formatted, []byte(payload), "", " "); err != nil {+ return payload, false+ }++ return formatted.String(), true+}++func highlightEventPayloadJSON(payload string) string {+ var highlighted strings.Builder+ highlighted.Grow(len(payload))++ for index := 0; index < len(payload); {+ switch {+ case payload[index] == '"':+ end := eventPayloadJSONStringEnd(payload, index)+ style := jsonStringStyle+ if eventPayloadNextNonSpace(payload, end) == ':' {+ style = jsonKeyStyle+ }+ writeEventPayloadToken(&highlighted, style, payload[index:end])+ index = end+ case payload[index] == '-' || isEventPayloadDigit(payload[index]):+ end := index + 1+ for end < len(payload) && isEventPayloadNumberCharacter(payload[end]) {+ end+++ }+ writeEventPayloadToken(&highlighted, jsonNumberStyle, payload[index:end])+ index = end+ case strings.HasPrefix(payload[index:], "true"):+ writeEventPayloadToken(&highlighted, jsonLiteralStyle, "true")+ index += len("true")+ case strings.HasPrefix(payload[index:], "false"):+ writeEventPayloadToken(&highlighted, jsonLiteralStyle, "false")+ index += len("false")+ case strings.HasPrefix(payload[index:], "null"):+ writeEventPayloadToken(&highlighted, jsonLiteralStyle, "null")+ index += len("null")+ default:+ highlighted.WriteString(html.EscapeString(payload[index : index+1]))+ index+++ }+ }++ return highlighted.String()+}++func eventPayloadJSONStringEnd(payload string, start int) int {+ escaped := false+ for index := start + 1; index < len(payload); index++ {+ switch {+ case escaped:+ escaped = false+ case payload[index] == '\\':+ escaped = true+ case payload[index] == '"':+ return index + 1+ }+ }++ return len(payload)+}++func eventPayloadNextNonSpace(payload string, start int) byte {+ for index := start; index < len(payload); index++ {+ switch payload[index] {+ case ' ', '\n', '\r', '\t':+ continue+ default:+ return payload[index]+ }+ }++ return 0+}++func isEventPayloadDigit(value byte) bool {+ return value >= '0' && value <= '9'+}++func isEventPayloadNumberCharacter(value byte) bool {+ return isEventPayloadDigit(value) ||+ value == '-' ||+ value == '+' ||+ value == '.' ||+ value == 'e' ||+ value == 'E'+}++func writeEventPayloadToken(builder *strings.Builder, style string, token string) {+ builder.WriteString(`<span style="`)+ builder.WriteString(style)+ builder.WriteString(`">`)+ builder.WriteString(html.EscapeString(token))+ builder.WriteString(`</span>`)+}+```++- [ ] **Step 4: Format and run the formatter tests**++Run:++```powershell+pre-commit run go-fumpt --files api/pkg/emails/event_payload_formatter.go api/pkg/emails/event_payload_formatter_test.go+Set-Location api+go test ./pkg/emails -run '^TestFormatEventPayload' -count=1+```++Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),+then all three formatter tests pass.++- [ ] **Step 5: Commit the formatter**++Run from the repository root:++```powershell+git add -- api\pkg\emails\event_payload_formatter.go api\pkg\emails\event_payload_formatter_test.go+git commit -m "feat(api): format webhook email payload" -m "Co-authored-by: Copilot <[email protected]>" -m "Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11"+```++Expected: one commit containing only the formatter and its tests.++### Task 2: Add opt-in rich dictionary rendering to the Hermes theme++**Files:**+- Create: `api/pkg/emails/hermes_theme_test.go`+- Modify: `api/pkg/emails/hermes_theme.go:325-334`++**Interfaces:**+- Consumes: `hermes.Entry{Value: plain, UnsafeValue: rich}`.+- Produces: HTML rendering that uses `UnsafeValue` only when non-empty.+- Preserves: plain-text rendering always uses `Value`.++- [ ] **Step 1: Write the failing Hermes theme test**++Create `api/pkg/emails/hermes_theme_test.go`:++```go+package emails++import (+ "html/template"+ "testing"++ "github.com/go-hermes/hermes/v2"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestHermesThemeRendersUnsafeDictionaryValueOnlyWhenProvided(t *testing.T) {+ generator := (&HermesGeneratorConfig{+ AppURL: "https://httpsms.com",+ AppName: "httpSMS",+ AppLogoURL: "https://httpsms.com/logo.png",+ }).Generator()+ email := hermes.Email{+ Body: hermes.Body{+ Title: "Hello",+ Dictionary: []hermes.Entry{+ {Key: "Normal", Value: "<b>escaped</b>"},+ {+ Key: "Payload",+ Value: "plain payload",+ UnsafeValue: template.HTML(`<pre style="white-space:pre-wrap">rich payload</pre>`),+ },+ },+ },+ }++ htmlEmail, err := generator.GenerateHTML(email)+ require.NoError(t, err)+ textEmail, err := generator.GeneratePlainText(email)+ require.NoError(t, err)++ assert.Contains(t, htmlEmail, `<b>escaped</b>`)+ assert.NotContains(t, htmlEmail, `<b>escaped</b>`)+ assert.Contains(t, htmlEmail, `<pre style="white-space:pre-wrap">rich payload</pre>`)+ assert.NotContains(t, htmlEmail, `<dd>plain payload</dd>`)+ assert.Contains(t, textEmail, "Normal: <b>escaped</b>")+ assert.Contains(t, textEmail, "Payload: plain payload")+ assert.NotContains(t, textEmail, "<pre")+}+```++- [ ] **Step 2: Run the theme test to verify it fails**++Run:++```powershell+Set-Location api+go test ./pkg/emails -run '^TestHermesThemeRendersUnsafeDictionaryValueOnlyWhenProvided$' -count=1+```++Expected: failure because the generated HTML contains `plain payload` instead+of the `<pre>` block.++- [ ] **Step 3: Update the HTML dictionary template**++In `api/pkg/emails/hermes_theme.go`, replace:++```gotemplate+<dd>{{ $entry.Value }}</dd>+```++with:++```gotemplate+<dd>{{ if $entry.UnsafeValue }}{{ $entry.UnsafeValue }}{{ else }}{{ $entry.Value }}{{ end }}</dd>+```++Do not change the plain-text template at `api/pkg/emails/hermes_theme.go:523-528`;+it must continue to render:++```gotemplate+<li>{{ $entry.Key }}: {{ $entry.Value }}</li>+```++- [ ] **Step 4: Format and run the theme and formatter tests**++Run:++```powershell+pre-commit run go-fumpt --files api/pkg/emails/hermes_theme.go api/pkg/emails/hermes_theme_test.go+Set-Location api+go test ./pkg/emails -run '^(TestHermesTheme|TestFormatEventPayload)' -count=1+```++Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),+then the theme test and all formatter tests pass.++- [ ] **Step 5: Commit the theme support**++Run from the repository root:++```powershell+git add -- api\pkg\emails\hermes_theme.go api\pkg\emails\hermes_theme_test.go+git commit -m "feat(api): render rich email dictionary values" -m "Co-authored-by: Copilot <[email protected]>" -m "Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11"+```++Expected: one commit containing only the Hermes template opt-in and its test.++### Task 3: Wire formatting into the webhook failure email++**Files:**+- Create: `api/pkg/emails/hermes_notification_email_factory_test.go`+- Modify: `api/pkg/emails/hermes_notification_email_factory.go:78-122`++**Interfaces:**+- Consumes: `formatEventPayload(payload string) (string, template.HTML)` from Task 1.+- Produces: the existing `NotificationEmailFactory.WebhookSendFailed` email with only its Event Payload entry using `UnsafeValue`.+- Preserves: factory interface, subjects, recipients, other dictionary entries, actions, and error propagation.++- [ ] **Step 1: Write the failing webhook factory tests**++Create `api/pkg/emails/hermes_notification_email_factory_test.go`:++```go+package emails++import (+ "strings"+ "testing"++ "github.com/NdoleStudio/httpsms/pkg/entities"+ "github.com/NdoleStudio/httpsms/pkg/events"+ "github.com/google/uuid"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func testNotificationEmailFactory() NotificationEmailFactory {+ return NewHermesNotificationEmailFactory(&HermesGeneratorConfig{+ AppURL: "https://httpsms.com",+ AppName: "httpSMS",+ AppLogoURL: "https://httpsms.com/logo.png",+ })+}++func TestWebhookSendFailedFormatsOnlyEventPayload(t *testing.T) {+ statusCode := 500+ factory := testNotificationEmailFactory()+ user := &entities.User{+ Email: "[email protected]",+ Timezone: "UTC",+ }+ payload := &events.WebhookSendFailedPayload{+ WebhookID: uuid.New(),+ WebhookURL: "https://example.com/webhooks",+ Owner: "+237612345678",+ EventID: "event-id",+ EventType: "message.phone.received",+ EventPayload: `{"message":"hello","retry":false}`,+ HTTPResponseStatusCode: &statusCode,+ ErrorMessage: "plain failure response",+ }++ email, err := factory.WebhookSendFailed(user, payload)+ require.NoError(t, err)++ assert.Equal(t, "[email protected]", email.ToEmail)+ assert.Equal(t, "📢 We could not forward a webhook event to your server", email.Subject)+ assert.Contains(t, email.HTML, `<pre style=`)+ assert.Equal(t, 1, strings.Count(email.HTML, `<pre style=`))+ assert.Contains(t, email.HTML, `"message"`)+ assert.Contains(t, email.HTML, `plain failure response`)+ assert.Contains(t, email.Text, `"message": "hello"`)+ assert.Contains(t, email.Text, `"retry": false`)+ assert.NotContains(t, email.Text, "<pre")+}++func TestWebhookSendFailedPreservesNonJSONEventPayload(t *testing.T) {+ factory := testNotificationEmailFactory()+ user := &entities.User{+ Email: "[email protected]",+ Timezone: "UTC",+ }+ payload := &events.WebhookSendFailedPayload{+ WebhookID: uuid.New(),+ WebhookURL: "https://example.com/webhooks",+ Owner: "+237612345678",+ EventID: "event-id",+ EventType: "message.phone.received",+ EventPayload: "line one\n line two",+ ErrorMessage: "plain failure response",+ }++ email, err := factory.WebhookSendFailed(user, payload)+ require.NoError(t, err)++ assert.Contains(t, email.HTML, "line one\n line two")+ assert.NotContains(t, email.HTML, `<span style="color:`)+ assert.Contains(t, email.Text, "line one\n line two")+}+```++- [ ] **Step 2: Run the webhook factory tests to verify they fail**++Run:++```powershell+Set-Location api+go test ./pkg/emails -run '^TestWebhookSendFailed' -count=1+```++Expected: failure because Event Payload still renders as an ordinary dictionary+value and no `<pre>` block is present.++- [ ] **Step 3: Format Event Payload in the webhook factory**++At the start of+`hermesNotificationEmailFactory.WebhookSendFailed` in+`api/pkg/emails/hermes_notification_email_factory.go`, add:++```go+formattedPayload, formattedPayloadHTML := formatEventPayload(payload.EventPayload)+```++Replace the existing Event Payload dictionary entry:++```go+{Key: "Event Payload", Value: payload.EventPayload},+```++with:++```go+{+ Key: "Event Payload",+ Value: formattedPayload,+ UnsafeValue: formattedPayloadHTML,+},+```++Do not change the Error Message / HTTP Response entry or any SMS email method.++- [ ] **Step 4: Format and run all email package tests**++Run:++```powershell+pre-commit run go-fumpt --files api/pkg/emails/hermes_notification_email_factory.go api/pkg/emails/hermes_notification_email_factory_test.go+Set-Location api+go test ./pkg/emails -count=1+```++Expected: `go-fumpt` passes (rerun it once if it initially reformats the files),+then all `pkg/emails` tests pass.++- [ ] **Step 5: Run the stable API package regression suite**++Run:++```powershell+Set-Location api+$env:GOTOOLCHAIN = 'go1.25.8'+$packages = go list ./... | Where-Object { $_ -ne 'github.com/NdoleStudio/httpsms/pkg/handlers' }+go test -vet=off $packages+```++Expected: all selected API packages pass without adding or changing+dependencies.++The clean baseline cannot use plain `go test ./...`: existing stacktrace calls+fail Go vet's non-constant-format check, and+`pkg/handlers.TestPhoneAPIKeyHandler_store` requires an API server at+`localhost:8000`. Do not change those unrelated packages as part of this+feature.++- [ ] **Step 6: Review the final diff**++Run from the repository root:++```powershell+git --no-pager diff --check+git --no-pager diff -- api\pkg\emails+```++Expected:++- no whitespace errors;+- only the formatter, Hermes dictionary opt-in, webhook Event Payload wiring,+ and their tests are present;+- SMS content, error responses, and failure reasons are unchanged; and+- `api\go.mod` and `api\go.sum` are unchanged.++- [ ] **Step 7: Commit the webhook factory integration**++Run from the repository root:++```powershell+git add -- api\pkg\emails\hermes_notification_email_factory.go api\pkg\emails\hermes_notification_email_factory_test.go+git commit -m "feat(api): highlight webhook email payload" -m "Co-authored-by: Copilot <[email protected]>" -m "Copilot-Session: 48f6d946-ae22-4440-b7a1-44e939419b11"+```++Expected: one commit containing only the webhook factory integration and its+tests.diff --git a/docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.md b/docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.mdnew file mode 100644index 00000000..56e2e7e8--- /dev/null+++ b/docs/superpowers/specs/2026-07-18-webhook-email-payload-formatting-design.md@@ -0,0 +1,116 @@+# Webhook Email Payload Formatting++- Date: 2026-07-18+- Status: Approved (design)+- Scope: `api/` email rendering only.++## Problem++Failed-webhook notification emails currently display the event payload as an+unformatted dictionary value. Nested JSON is difficult to scan, and multiline+payloads lose the visual structure users need when diagnosing webhook failures.++## Decisions++- Format only the webhook email's **Event Payload** value.+- Leave SMS content, failure reasons, HTTP responses, and every other email+ field unchanged.+- Pretty-print valid JSON with indentation.+- Render valid JSON in the HTML email with lightweight colors for keys, strings,+ numbers, booleans, and `null`.+- Render non-JSON payloads in the same monospace block while preserving their+ original whitespace, without syntax colors.+- Use only the Go standard library and the existing Hermes email integration.+- Keep the plain-text email readable with indentation but no HTML styling.++## Design++### 1. Payload formatter++Add a focused formatter under `api/pkg/emails` that accepts the event payload+string and returns:++- a plain-text value for `hermes.Entry.Value`; and+- safely escaped highlighted markup for `hermes.Entry.UnsafeValue`.++For valid JSON, use the Go standard library to produce deterministic+indentation. A small JSON-aware tokenizer will wrap keys, strings, numbers,+booleans, and `null` in spans with inline colors. Inline styles are preferred+because many email clients strip style blocks or external styles.++All payload tokens must be HTML-escaped before they are inserted into the+trusted template value. Payload content must never be interpreted as HTML.++For invalid JSON, return the original payload unchanged as the plain-text value+and HTML-escape it into an unhighlighted code block. Invalid JSON is an expected+fallback and must not prevent email generation or delivery.++### 2. Hermes dictionary rendering++Update the custom HTML template in `api/pkg/emails/hermes_theme.go` so dictionary+entries render `UnsafeValue` when it is present and otherwise retain the current+escaped `Value` rendering.++The payload block will use email-compatible markup and inline styles:++- a neutral light background and subtle border;+- padding and a monospace font;+- `white-space: pre-wrap` to preserve indentation and line breaks; and+- safe wrapping for long values so the email remains usable on narrow clients.++The plain-text template continues to render `Entry.Value`, so it contains+readable indented JSON without HTML tags or colors.++### 3. Webhook email factory++In `hermesNotificationEmailFactory.WebhookSendFailed`, pass+`payload.EventPayload` through the formatter. Set both `Value` and+`UnsafeValue` only on the existing `Event Payload` dictionary entry.++No other dictionary entry or notification email uses the new unsafe rendering+path. The order, subject, explanatory text, action button, and delivery behavior+of the webhook failure email remain unchanged.++## Data Flow++1. `WebhookSendFailed` receives `payload.EventPayload`.+2. The formatter checks whether the string is valid JSON.+3. Valid JSON is indented and highlighted; invalid JSON preserves its original+ text and receives code-block styling only.+4. Hermes uses the plain value for the text email and the escaped styled value+ for the HTML email.+5. The existing mailer sends both representations without service or listener+ changes.++## Error Handling and Security++- Invalid JSON falls back to a whitespace-preserving code block.+- Formatting does not introduce a new email-generation failure path.+- Payload markup, quotes, ampersands, and other special characters are escaped+ before insertion.+- Highlighting is generated server-side and requires no JavaScript, remote+ assets, or external CSS.+- Existing Hermes generation errors continue to use the current stacktrace+ propagation behavior.++## Testing++Add targeted tests under `api/pkg/emails` covering:++- nested valid JSON is consistently indented;+- keys, strings, numbers, booleans, and `null` receive the expected HTML spans;+- payload HTML is escaped and cannot inject markup;+- invalid JSON preserves whitespace and is not syntax-highlighted;+- the webhook email HTML renders only `Event Payload` as a code block;+- the webhook email plain text contains readable indented JSON; and+- existing non-payload dictionary entries keep their current rendering.++Run the targeted email package tests, then `go test ./...` in `api/`.++## Out of Scope++- Formatting SMS message content or failure reasons.+- Formatting HTTP response bodies or error messages.+- Highlighting non-JSON languages.+- Adding a third-party syntax-highlighting dependency.+- Changing webhook retries, event payload generation, or email delivery logic.