auth-transactional-emails

The template-authoring half of the auth-email pattern: MJML/EJS source, brand-token theming, the compiled artifact that carries rendered template content, and pushing that content into Supabase's mailer. It is the counterpart to skills/auth-email-provisioning — that skill provisions the SES/Cloudflare/Turnstile infra and pushes SMTP/captcha config; this skill never touches SMTP or captcha config, and the sibling never touches template content.

The split

• 8 templates are Supabase-native: confirmation, recovery, magic_link, invite, email_change, email_changed_notification, password_changed_notification, reauthentication. Compiled HTML/subject get PATCHed into Supabase's own mailer config — Supabase sends them through its own pipeline, never a custom SMTP relay.
• 1 template is out-of-band: new_device_login. It's never compiled into the artifact or pushed to Supabase — it's rendered at request time with real runtime values and sent by a standalone Hono send-service, authenticated by a v2-timestamped HMAC contract.

The chain

src/emails/templates/*  ──renderEmail──▶  compile-templates.mjs  ──▶  compiled-templates.json  ──▶  sync-templates.mjs --apply  ──▶  Supabase mailer
new_device_login (excluded from the artifact)  ──renderEmail (with real values)──▶  send-service route  ──HMAC-signed POST──▶  app

Use it

Read SKILL.md for the 7 invariants (one verifiable todo each), the red flags, and the full ## References cross-link to the sibling auth-email-provisioning skill. Copy the genericized templates from references/:

• RENDER-CONTRACT.md — the render-core contract (renderEmail public API, template/layout/partial conventions, the EJS-context shape).
• brand-tokens.ts — BrandTokens + the fail-closed getBrandTokens (a deliberate correction from upstream @cogs/emails, which fails open to Workloom branding on an unknown slug).
• emails/templates/*, emails/layouts/base/, emails/partials/* — the complete 8 Supabase-native + 1 out-of-band + layout + 6-partial inventory.
• sync-templates.mjs — sole owner of the mailer template-content push; dry-run by default, --apply required, fails closed on a malformed artifact before issuing any PATCH.
• compile-templates.mjs — renders the 8 Supabase-native templates with no values into the versioned compiled-templates.json artifact, so Supabase's own {{ .TokenHash }}/{{ .SiteURL }} placeholders survive untouched.
• send-service-route.example.ts — the reference Hono route implementing the HMAC contract for the out-of-band new_device_login send.

Scaffold directly

node bin/add-auth-emails.mjs \
  --scope @acme \
  --brand-name Acme \
  --templates confirmation,recovery,magic_link,invite,email_change,email_changed_notification,password_changed_notification,reauthentication \
  --emails cogs        # 'cogs' -> depend on published @cogs/emails; 'local' -> fork this skill's fail-closed render core

--emails cogs|local mirrors kubb-react-query's --seams cogs|local: cogs depends on the published @cogs/emails package as-is (including its brand fail-open behavior); local forks this skill's own genericized, fail-closed render core into the consumer's repo instead.

Install globally

Symlink into your global skills the same way as the other next-starters skills:

skills add [email protected]:catesandrew/next-starters.git \
  --skill skills/auth-transactional-emails -g

Layout

auth-transactional-emails/
  SKILL.md                          the 7 invariants + decision procedure
  metadata.json
  README.md
  references/
    RENDER-CONTRACT.md              render-core contract
    brand-tokens.ts                 BrandTokens + fail-closed getBrandTokens
    emails/
      templates/{confirmation,recovery,magic_link,invite,email_change,
                 email_changed_notification,password_changed_notification,
                 reauthentication,new_device_login}/
      layouts/base/
      partials/{button,footer,support,userInfo,userDevice,userLocation}/
    compile-templates.mjs           templates -> compiled-templates.json
    sync-templates.mjs              compiled-templates.json -> Supabase mailer (sole owner)
    send-service-route.example.ts   HMAC-authenticated new_device_login send route

The scaffolder lives at next-starters/bin/add-auth-emails.mjs.

Companion

Pairs with skills/auth-email-provisioning (Terraform infra + SMTP/captcha config push — this skill's compile-templates.mjs/sync-templates.mjs chain never crosses into that scope, and vice versa), and companion-links skills/runtime-env-config, skills/local-dev-stack, and skills/prod-deploy.