@syncello/auth 4.0.0 → 4.2.0

package/README.md

@@ -297,6 +297,29 @@ A `verify` hook that throws is logged and treated as "not invited": invitation m
 OAuth sign-up in open mode goes ahead unlinked, and a password signup with the token answers
 `400`.
 
+## Custom Emails
+
+`renderEmail` puts an app's own emails in the same template as the auth emails. Every value is
+plain text and escaped; every URL must be http(s) on `appUrl`'s host or a subdomain.
+
+```typescript
+import { renderEmail } from '@syncello/auth';
+
+const html = renderEmail({
+  heading: 'Your daily digest',
+  paragraphs: ['Here is what changed today.'],
+  sections: [
+    { title: 'Acme', url: `${appUrl}/accounts/1`, rows: [{ text: 'PO 1001 shipped', url: `${appUrl}/orders/1001` }] },
+  ],
+  button: { label: 'Open the portal', url: `${appUrl}/orders` },
+  notice: 'This link expires in 7 days.',
+  footerNote: 'You get this because you follow Acme.',
+  appUrl,
+  appName: 'My App',
+  branding: emailBranding,
+});
+```
+
 ## Direct Imports
 
 For advanced usage, you can import utilities directly:
@@ -319,6 +342,30 @@ import {
 
 ## Release Notes
 
+### 4.2.0
+
+- `renderEmail` renders an app's own emails (invitations, notifications, digests) in the
+  template the auth emails use, from plain text: a heading, paragraphs, optional sections of
+  rows, a button, a notice, a footer note and `EmailBranding`. It escapes every value and
+  refuses links off the app's host (see Custom Emails).
+- `emailBranding.logoWidth` and `logoHeight` (CSS px, positive integers, given together): the
+  header logo renders at that fixed size, with `width` and `height` attributes so mail clients
+  reserve its space and Outlook sizes it right, instead of filling half the email's width.
+- A cleaner template for every email, with no new options needed: a white card on a light grey
+  page, a left-aligned heading and body, the notice as a grey panel edged in `headingColor`
+  instead of the cyan box, and the link to copy small and grey under a thin rule. URLs in the
+  markup are now HTML-escaped (`&` is written `&`), which browsers read as the same URL.
+
+### 4.1.0
+
+- `emailBranding.marketingUrl`: the site the email footer's Privacy Policy (`/privacy`) and Get
+  in Touch (`/contact`) links point at. Without it the footer has no links; they used to point
+  at the app, where those pages don't exist.
+- Emails state each link's or code's real lifetime from `AUTH_DEFAULTS`: the password reset
+  email said 1 hour for a 15-minute token, and the verification email 48 hours for a 24-hour
+  one. `AUTH_DEFAULTS` gains `EMAIL_VERIFICATION_TTL_HOURS`, `EMAIL_CHANGE_TTL_HOURS` and
+  `TWO_FACTOR_EMAIL_CODE_TTL_MINUTES`, which the token code now reads too (values unchanged).
+
 ### 4.0.0
 
 **Breaking:** `verifyWebhookSignature` takes all three svix headers. Svix signs