Thank you, {{userName}}!
\nTotal: {{amount | currency}}
\n `,\n text: 'Order #{{orderId}} confirmed. Total: {{amount}}',\n },\n\n sms: {\n message: '[{{appName}}] Order #{{orderId}} confirmed. Total: {{amount | currency}}',\n },\n});\n```\n\n### Localised Templates\n\nA template can carry content per locale. A send picks one with `locale`:\n\n```typescript\nregisterTemplate({\n name: 'order-shipped',\n channels: ['email', 'sms'],\n defaultLocale: 'en',\n locales: {\n ko: { email: { subject: '{{orderId}} 주문이 발송되었습니다', text: '…' }, sms: { message: '…' } },\n en: { email: { subject: 'Order {{orderId}} has shipped', text: '…' } },\n },\n});\n\nawait sendEmail({ to, template: 'order-shipped', data: { orderId }, locale: user.locale });\n```\n\n- Resolution: the exact tag (`ko-KR`), then its base language (`ko`), then `defaultLocale`,\n then the template's unlocalised `email`/`sms`/`slack` content. Tags match\n case-insensitively.\n- It resolves per channel. A locale that has no content for the channel falls through to\n the next candidate. In the example, an SMS with `locale: 'en'` finds no `en` SMS, then no\n unlocalised SMS, and is refused; with `locale: 'ko'` it is sent in Korean.\n- A template with `locales` that has nothing for the channel in any candidate is refused\n (`success: false`) instead of sending empty content. A template without `locales`\n behaves as before.\n- The history row records the locale whose content was sent (`null` for unlocalised\n content).\n- `locale` works on every send, bulk item and schedule; a scheduled send renders in it\n when the job runs.\n\n### Template Filters\n\n```\n{{variable}} - Basic substitution\n{{variable | uppercase}} - Convert to uppercase\n{{variable | lowercase}} - Convert to lowercase\n{{variable | currency}} - Format as currency (1,000)\n{{variable | date}} - Format as date\n{{variable | date:YYYY-MM-DD}} - Custom date format\n{{variable | truncate:20}} - Truncate to length\n{{variable | default:N/A}} - Default value if empty\n```\n\n### Custom Filters\n\n```typescript\nimport { registerFilter } from '@spfn/notification/server';\n\nregisterFilter('phone', (value) => {\n const str = String(value);\n return `${str.slice(0, 3)}-${str.slice(3, 7)}-${str.slice(7)}`;\n});\n\n// Usage: {{phoneNumber | phone}} -> 010-1234-5678\n```\n\n## Custom Providers\n\n### Email Provider\n\n```typescript\nimport { registerEmailProvider, EmailProvider } from '@spfn/notification/server';\n\nconst sendgridProvider: EmailProvider = {\n name: 'sendgrid',\n async send(params) {\n // Your SendGrid implementation\n return { success: true, messageId: '...' };\n },\n};\n\nregisterEmailProvider(sendgridProvider);\n```\n\n### SMS Provider\n\n```typescript\nimport { registerSMSProvider, SMSProvider } from '@spfn/notification/server';\n\nconst twilioProvider: SMSProvider = {\n name: 'twilio',\n async send(params) {\n // Your Twilio implementation\n return { success: true, messageId: '...' };\n },\n};\n\nregisterSMSProvider(twilioProvider);\n```\n\n## Logging & Error Handling\n\nAll channels log via `@spfn/core/logger`. Logs are tagged by channel.\n\n**Recipient fields never appear raw in logs.** Every recipient field this\npackage writes — success, failure, and validation logs alike — carries a masked\nvalue (`jo***@example.com`, `+8210******78`). A send resolved as `sensitive`\n(see [Sensitive sends](#sensitive-sends)) also keeps its subject out of the log,\nbecause a verification subject line carries the code itself; the log identifies\nthe send by template name instead. The masking helpers are exported\n(`maskEmail`, `maskPhone`, `maskRecipient`, `maskRecipients`) for application-side\nlogging of the same values.\n\n**Provider error text is scrubbed too.** A provider failure is free text and\nroutinely quotes the recipient back — an SES sandbox `MessageRejected` reads\n*\"The following identities failed the check in region US-EAST-1:\nlearner@example.com\"*. Every provider error is scrubbed of email and phone\ntokens before it reaches a log line or `history.error_message`, at the channel's\nprovider boundary — so a custom provider (see [Custom Providers](#custom-providers))\nis covered without doing anything — and again in the service that writes the\ncolumn. Only address-shaped tokens are replaced: the error *name* (`MessageRejected`),\nthe region, the request id, timestamps and message ids are the diagnostic value\nand survive untouched, and the built-in AWS providers log that name and the HTTP\nstatus alongside the scrubbed message. `scrubProviderError(text)` is exported for\napplications that log provider errors themselves.\n\nChannel tags:\n\n- `@spfn/notification:email` — Email send success/failure, validation errors\n- `@spfn/notification:sms` — SMS send success/failure, validation errors\n- `@spfn/notification:slack` — Slack send success/failure, validation errors\n- `@spfn/notification:ses` — AWS SES client lifecycle, provider errors\n- `@spfn/notification:sns` — AWS SNS client lifecycle, provider errors\n\n`sendEmail`, `sendSMS`, `sendSlack` are designed to **not throw** — they return a `SendResult` object. Always check the result:\n\n```typescript\nconst result = await sendEmail({\n to: 'user@example.com',\n template: 'welcome',\n data: { name: 'John' },\n});\n\nif (!result.success)\n{\n // result.error contains the failure reason\n console.error('Email failed:', result.error);\n}\n```\n\n## Notification History\n\nEnable history tracking to store all notifications in the database:\n\n```typescript\nconfigureNotification({\n enableHistory: true,\n});\n```\n\n### What a row stores — and how to store less\n\nA history row is the anchor for tracking (FK), scheduling (cancellation) and\nbulk status, so the row itself is always created when history is enabled. What\nlands **in** it is configurable, because two of its columns are privacy\nsurfaces: `recipient` is a person's address, and `content` / `template_data`\ncan carry a live credential (a magic link, an OTP code). `error_message` holds\nthe scrubbed provider message, so a row whose `recipient` is hashed cannot carry\nthe raw address in its failure text either.\n\n```typescript\nconfigureNotification({\n enableHistory: true,\n history: {\n // Keep rendered content and template data out of every row.\n // Status, provider message id, error and timestamps still land.\n storeContent: false,\n\n // Store an HMAC per recipient instead of the raw address.\n // findNotifications({ recipient }) keeps working — the filter is\n // hashed the same way. Requires a secret (config or\n // SPFN_NOTIFICATION_HISTORY_HASH_SECRET). A plain hash would be\n // reversible by dictionary, which is why a keyed HMAC is used.\n storeRecipient: 'hashed',\n },\n});\n```\n\nNeither option needs a migration — the payload columns are nullable and the\nHMAC satisfies the `recipient` column as-is.\n\n### Sensitive sends\n\nA send whose rendered output *is* a credential can opt out of payload storage\nper send, regardless of the global `storeContent` setting:\n\n```typescript\nawait sendEmail({\n to: 'user@example.com',\n subject: 'Your access link',\n html: accessLinkHtml,\n sensitive: true, // no content, template data, or subject in the history row\n});\n```\n\nA template can declare it for every send that uses it — the built-in\n`verification-code` template does, since both its body and its subject line\ncontain the code. A per-send `sensitive: true/false` overrides the template's\ndeclaration.\n\n**Scheduled and distributed sends caveat:** a scheduled send's payload (raw\nrecipient, content, template data) necessarily travels through the pg-boss job\ntable — that is what gets sent later — and stays there until pg-boss archives\nthe job. The same applies to `sendEmailBulk` / `sendSMSBulk` with\n`distributed: true`. The history options above do not change that. If your\ncontract forbids persisting a credential at all, send it immediately and\nin-process rather than scheduling or distributing it.\n\n### Query History\n\n```typescript\nimport {\n findNotifications,\n getNotificationStats,\n findScheduledNotifications,\n} from '@spfn/notification/server';\n\n// Find notifications\nconst notifications = await findNotifications({\n channel: 'email',\n status: 'sent',\n recipient: 'user@example.com',\n from: new Date('2024-01-01'),\n limit: 100,\n});\n\n// Get statistics\nconst stats = await getNotificationStats({ channel: 'email' });\n// { total: 1000, scheduled: 10, pending: 5, sent: 980, failed: 3, cancelled: 2 }\n\n// Find scheduled notifications\nconst scheduled = await findScheduledNotifications({\n channel: 'email',\n from: new Date(),\n to: new Date(Date.now() + 24 * 60 * 60 * 1000),\n});\n```\n\n## Email Tracking\n\nTrack email opens and link clicks to measure engagement.\n\n### How It Works\n\n1. **Open tracking**: A 1x1 transparent GIF is inserted before `