@stacksjs/notifications 0.75.137 → 0.75.139

package/README.md

@@ -53,6 +53,56 @@ The database inbox and `notification_deliveries` tracking log are separate.
 Apply their model-driven migrations before relying on persistence. Inspect the
 returned channel results; the tracking log is not a final receipt.
 
+## Marketing unsubscribe
+
+`payload.unsubscribe` (build it with `notificationUnsubscribeLinks(userId)`)
+puts an Unsubscribe link in the email footer and text part and sets
+`List-Unsubscribe` / `List-Unsubscribe-Post` (RFC 8058). A `marketing` text
+ends with "Reply STOP to opt out." unless `payload.smsOptOut` says otherwise.
+The signed token turns off one channel + category preference; handle the
+app's route with `unsubscribeWithToken(await unsubscribeTokenFromRequest(request))`.
+
+## Templates
+
+`@stacksjs/notifications/templates` (also re-exported from the package root)
+keeps an app's messages in one catalog: each named message has its copy per
+language and, optionally, the email's button. It is pure and browser-safe.
+
+```ts
+import { accountNotificationTemplates, createNotificationTemplates, defineNotificationTemplates } from '@stacksjs/notifications/templates'
+
+const templates = createNotificationTemplates({
+  ...accountNotificationTemplates({ resetPassword: '/forgot-password' }),
+  ...defineNotificationTemplates({
+    class_booked: {
+      copy: {
+        en: { subject: 'You’re booked at {{gym}}', body: 'See you at {{class_name}} on {{date}}.' },
+        de: { subject: 'Gebucht bei {{gym}}', body: 'Bis {{date}} bei {{class_name}}.' },
+      },
+      action: { path: '/schedule', label: { en: 'View your schedule', de: 'Zum Stundenplan' } },
+    },
+  }),
+}, { baseUrl: () => process.env.APP_URL || '' })
+
+await notify({ email }, templates.render('class_booked', { gym, class_name, date }, user.locale), ['email'])
+```
+
+`{{name}}` is replaced by that variable, a missing one by nothing. A button
+whose path needs a variable that was not given is left out. A path that renders
+to an absolute URL (a one-time link) is used as it is; any other is joined to
+`baseUrl`. `de-AT` falls back to `de`, then to `fallbackLocale` (`en`).
+
+Built-in catalogs, in English and German, take the paths their buttons lead to:
+
+| Catalog | Messages |
+| --- | --- |
+| `accountNotificationTemplates()` | `password_changed`, `email_changed` (send to both addresses), `account_deleted`, `account_created` (someone made the account; set-password link) |
+| `commerceNotificationTemplates()` | `order_receipt`, `order_refunded`, `new_sale` (to the seller), `account_credit_added` |
+| `subscriptionNotificationTemplates()` | `subscription_trial_ending`, `subscription_payment_failed`, `subscription_ended` |
+
+Each documents its variables. Format amounts first: `receiptLinesText()` from
+`@stacksjs/commerce/receipt-text` builds the receipt's `lines`.
+
 ## Inbox ownership
 
 ```ts

package/dist/email-body.d.ts

@@ -1,3 +1,4 @@
+import type { EmailMessage } from '@stacksjs/types';
 /**
  * A plain-text notification body as the paragraphs of its email. Blank lines
  * separate paragraphs, a single newline stays a line break, and an address is
@@ -10,15 +11,62 @@ export declare function emailParagraphs(body: string): EmailBodyPart[][];
  * the same layout as every other Stacks email. It used to be the body in a
  * bare `<p>`, which mail clients showed as unstyled text with dead links.
  * Falls back to that only if the template cannot be rendered.
+ *
+ * With `unsubscribe`, the footer says why the email came and links to
+ * Unsubscribe (and the preferences page) instead of "do not reply".
  */
-export declare function notificationEmailHtml(payload: { subject?: string, body: string, action?: NotificationAction }): Promise<string>;
-/** The plain-text part, with the action's link spelled out. */
-export declare function notificationEmailText(payload: { body: string, action?: NotificationAction }): string;
+export declare function notificationEmailHtml(payload: NotificationEmailPayload): Promise<string>;
+/** The plain-text part, with the action's link and any unsubscribe link spelled out. */
+export declare function notificationEmailText(payload: { body: string, action?: NotificationAction, unsubscribe?: NotificationUnsubscribe }): string;
+/**
+ * `List-Unsubscribe` for a payload's unsubscribe links (RFC 2369), plus
+ * `List-Unsubscribe-Post` when there is a one-click endpoint (RFC 8058).
+ * Empty without `unsubscribe`.
+ */
+export declare function listUnsubscribeHeaders(unsubscribe?: NotificationUnsubscribe): Record<string, string>;
+/**
+ * Everything `notify()` hands the mailer for one email: the text and HTML
+ * parts, and the payload's own headers with the unsubscribe ones on top.
+ */
+export declare function notificationEmailMessage(to: string, payload: NotificationEmailPayload): Promise<EmailMessage>;
+/**
+ * What a notification texts. A `marketing` text ends with
+ * {@link DEFAULT_SMS_OPT_OUT} on its own line; `smsOptOut` replaces that line
+ * (and adds it to any category), and `false` leaves it out. A body that
+ * already contains the line is left alone.
+ */
+export declare function notificationSmsBody(payload: { body: string, smsOptOut?: string | false }, category?: string): string;
+/** The footer sentence of an email with an unsubscribe link, unless the payload names its own. */
+export declare const DEFAULT_UNSUBSCRIBE_NOTICE: 'You are receiving this because these emails are turned on in your settings.';
+/**
+ * The line a marketing text ends with, unless the payload names its own
+ * (`smsOptOut`). Carriers expect opt-out instructions on marketing texts, and
+ * STOP is the keyword every provider and `@stacksjs/sms` honour.
+ */
+export declare const DEFAULT_SMS_OPT_OUT: 'Reply STOP to opt out.';
 /** Where a notification leads: the email's button. */
 export declare interface NotificationAction {
   label: string
   url: string
 }
+/**
+ * The two ways out a marketing notification carries (see `notify()`'s
+ * `payload.unsubscribe`).
+ */
+export declare interface NotificationUnsubscribe {
+  url: string
+  oneClickUrl?: string
+  preferencesUrl?: string
+  notice?: string
+}
+/** What the email builders read from a notification payload. */
+export declare interface NotificationEmailPayload {
+  subject?: string
+  body: string
+  action?: NotificationAction
+  unsubscribe?: NotificationUnsubscribe
+  headers?: Record<string, string>
+}
 /**
  * One run of a notification email paragraph: text, a link, or a line break.
  * A type, not an interface: template variables take index-signature types,

package/dist/index.d.ts

@@ -3,13 +3,15 @@ import { chat, email, push, sms } from './drivers/index';
 import { DatabaseNotificationDriver } from './drivers/database';
 import { filterChannelsByPreferences } from './preferences';
 import { makeDeliveryRecord, recordNotificationDelivery } from './delivery';
-import { type NotificationAction, notificationEmailHtml, notificationEmailText } from './email-body';
+import { type NotificationAction, type NotificationUnsubscribe, notificationEmailMessage, notificationSmsBody } from './email-body';
 import type { ChatMessage, ChatResult, EmailMessage, EmailResult, SmsMessage, SmsSendResult } from '@stacksjs/types';
 export type { BroadcastNotificationOptions, BroadcastNotificationResult } from './drivers/broadcast';
 export type { NotificationDeliveryRecord } from './delivery';
 export type { CreateNotificationOptions, DatabaseNotification } from './drivers/database';
 export type { NotificationPreferenceRow, PreferenceChannel } from './preferences';
-export type { EmailBodyPart, NotificationAction } from './email-body';
+export type { EmailBodyPart, NotificationAction, NotificationEmailPayload, NotificationUnsubscribe } from './email-body';
+export type { ParsedUnsubscribeToken, UnsubscribeChannel, UnsubscribeLinkOptions } from './unsubscribe';
+export type { AccountNotificationPaths, AccountNotificationTemplateName, CommerceNotificationPaths, CommerceNotificationTemplateName, NotificationTemplateAction, NotificationTemplateCatalog, NotificationTemplateCatalogOptions, NotificationTemplateCopy, NotificationTemplateDefinition, NotificationTemplateVariables, RenderedNotificationTemplate, RenderNotificationTemplateOptions, SubscriptionNotificationPaths, SubscriptionNotificationTemplateName } from './templates';
 export declare function ensureSuccessfulEmailResult(result: EmailResult): void;
 /** Require at least one delivered channel and surface partial fan-out failure. */
 export declare function ensureSuccessfulNotificationResults(results: readonly NotifyResult[]): void;
@@ -95,6 +97,9 @@ export declare interface NotificationPayload {
   body: string
   data?: Record<string, unknown>
   action?: NotificationAction
+  unsubscribe?: NotificationUnsubscribe
+  headers?: Record<string, string>
+  smsOptOut?: string | false
 }
 export declare interface NotificationRecipient {
   email?: string
@@ -127,4 +132,6 @@ export {
   setNotificationPreference,
   wherePreferenceCategory,
 } from './preferences';
-export { emailParagraphs, notificationEmailHtml, notificationEmailText } from './email-body';
+export { DEFAULT_SMS_OPT_OUT, DEFAULT_UNSUBSCRIBE_NOTICE, emailParagraphs, listUnsubscribeHeaders, notificationEmailHtml, notificationEmailMessage, notificationEmailText, notificationSmsBody } from './email-body';
+export { notificationUnsubscribeLinks, notificationUnsubscribeToken, parseNotificationUnsubscribeToken, unsubscribeTokenFromRequest, unsubscribeWithToken } from './unsubscribe';
+export { accountNotificationTemplates, commerceNotificationTemplates, createNotificationTemplates, defineNotificationTemplates, interpolateNotificationText, notificationTemplateVariables, renderNotificationTemplate, resolveNotificationLocale, subscriptionNotificationTemplates } from './templates';

package/dist/index.js

@@ -1,6 +1,49 @@
 // @bun
-import{log as _}from"@stacksjs/cli";import{notification as oe}from"@stacksjs/config";import{mail as U}from"@stacksjs/email";import{log as D}from"@stacksjs/cli";var d={async send(e){let t=e.event??"notification",r=e.channel;if(!r)r=e.userId!==void 0?`private-user.${e.userId}`:"notifications";try{let n=await import("@stacksjs/realtime").catch(()=>null),a=n?.emit,i=n?.getServer;if(!a||!i)return{delivered:!1,channel:r,event:t,reason:"@stacksjs/realtime is not available"};if(!i())return{delivered:!1,channel:r,event:t,reason:"realtime server not running"};let o=e.private??e.userId!==void 0;return a(r,t,e.data,{private:o}),D.info(`[notifications] broadcast to '${r}' (${t})`),{delivered:!0,channel:r,event:t}}catch(n){let a=n instanceof Error?n.message:String(n);return D.warn(`[notifications] broadcast failed: ${a}`),{delivered:!1,channel:r,event:t,reason:a}}}};import*as T from"@stacksjs/chat";import{log as S}from"@stacksjs/cli";import{createHash as Q}from"crypto";import{db as u,enqueueAfterCommit as z,lockRow as G,sqlDateTime as g}from"@stacksjs/database/runtime";import{emit as V,getServer as W}from"@stacksjs/realtime";function A(e){return`private-user.${e}`}function b(e,t,r){let n=()=>{try{if(W())V(A(e),t,r)}catch{S.warn("Notification inbox broadcast failed; the persisted inbox remains available")}};if(!z(n))n()}async function C(e,t){let r=g(),a=await u.insertInto("notifications").values({user_id:e.userId,...t?{uuid:t}:{},type:e.type,data:JSON.stringify(e.data),read_at:null,created_at:r,updated_at:r}).returning("id").execute(),i=Array.isArray(a)?a[0]:a,o=Number(i?.id??i?.insertId??i?.lastInsertRowid??i?.lastInsertId??0);if(!Number.isSafeInteger(o)||o<=0)throw Error("Database notification did not return a generated id");if(S.info(`Database notification sent to user ${e.userId}: ${e.type}`),e.broadcast!==!1)b(e.userId,"notifications.created",{id:o});return{id:o,user_id:e.userId,type:e.type,data:JSON.stringify(e.data),read_at:null,created_at:r,updated_at:r}}var m={async send(e){if(e.idempotencyKey!==void 0){if(!e.idempotencyKey||e.idempotencyKey.length>255)throw Error("A notification idempotency key must contain 1 to 255 characters");let t=Q("sha256").update(JSON.stringify([e.userId,e.type,e.idempotencyKey])).digest("hex"),r=`${t.slice(0,8)}-${t.slice(8,12)}-8${t.slice(13,16)}-8${t.slice(17,20)}-${t.slice(20,32)}`;return u.transaction(async(n)=>{if(!await G(n,"users",{id:e.userId}))throw Error("Notification recipient not found");let i=await u.selectFrom("notifications").selectAll().where("user_id","=",e.userId).where("uuid","=",r).executeTakeFirst();if(i)return{...i,id:Number(i.id),user_id:Number(i.user_id)};return C(e,r)})}return C(e)},async getUserNotifications(e){return(await u.selectFrom("notifications").selectAll().where("user_id","=",e).orderBy("created_at","desc").execute()).map((r)=>({...r,id:Number(r.id),user_id:Number(r.user_id)}))},async getUnreadNotifications(e){return(await u.selectFrom("notifications").selectAll().where("user_id","=",e).whereNull("read_at").orderBy("created_at","desc").execute()).map((r)=>({...r,id:Number(r.id),user_id:Number(r.user_id)}))},async markAsRead(e,t){let r=u.updateTable("notifications").set({read_at:g()}).where("id","=",e).whereNull("read_at");if(t!==void 0)r=r.where("user_id","=",t);if(await r.execute(),t)b(t,"notifications.read",{id:e})},async markAllAsRead(e){await u.updateTable("notifications").set({read_at:g()}).where("user_id","=",e).whereNull("read_at").execute(),b(e,"notifications.read",{all:!0})},async unreadCount(e){let t=await u.selectFrom("notifications").select(u.fn.countAll().as("count")).where("user_id","=",e).whereNull("read_at").executeTakeFirst();return Number(t?.count??0)},async deleteNotification(e,t){let r=u.deleteFrom("notifications").where("id","=",e);if(t!==void 0)r=r.where("user_id","=",t);await r.execute()},async deleteAllNotifications(e){await u.deleteFrom("notifications").where("user_id","=",e).execute()}};import*as I from"@stacksjs/push";import*as h from"@stacksjs/sms";import{log as X}from"@stacksjs/cli";import{config as j}from"@stacksjs/config";import{db as Y,sqlDateTime as B}from"@stacksjs/database/runtime";function O(e,t){switch(t){case"email":return e.email||"";case"sms":return e.phone||"";case"push":return Array.isArray(e.pushTokens)?e.pushTokens.join(", "):e.pushTokens||"";case"broadcast":return e.broadcastChannel||(e.userId?`private-user.${e.userId}`:"notifications");case"database":return e.userId?`User #${e.userId}`:"";case"chat":return Array.isArray(e.chatRecipient)?e.chatRecipient.join(", "):e.chatRecipient||""}}function y(e,t,r,n,a=B()){return{userId:e.userId,channel:r.channel,recipient:O(e,r.channel),subject:t.subject,body:t.body,status:r.success?"sent":"failed",error:r.error?.message,metadata:{...t.data,...n.category?{category:n.category}:{}},sentAt:a}}function Z(e){let t=j.notification?.tracking;if(t?.enabled===!1)return!1;let r=t?.channels;if(!r||r.length===0)return!0;return r.includes(e)}async function w(e){if(!Z(e.channel))return;let t=B();try{await Y.insertInto("notification_deliveries").values({user_id:e.userId??null,channel:e.channel,recipient:e.recipient,subject:e.subject??null,body:j.notification?.tracking?.body===!1?"":e.body,status:e.status,error:e.error??null,metadata:e.metadata?JSON.stringify(e.metadata):null,sent_at:e.sentAt,created_at:t,updated_at:t}).execute()}catch(r){let n=r instanceof Error?r.message:String(r);X.warn(`[notifications] could not record ${e.channel} delivery: ${n}`)}}import{templateByName as ee}from"@stacksjs/email";var te=/https?:\/\/[^\s<>"']+[^\s<>"'.,;:!?)\]]/g;function q(e){return String(e??"").replace(/\r\n?/g,`
-`).split(/\n\s*\n/).map((t)=>t.trim()).filter(Boolean).map((t)=>{let r=[];return t.split(`
-`).forEach((n,a)=>{if(a>0)r.push({br:!0});let i=0;for(let o of n.matchAll(te)){if(o.index>i)r.push({text:n.slice(i,o.index)});r.push({url:o[0]}),i=o.index+o[0].length}if(i<n.length)r.push({text:n.slice(i)})}),r})}function N(e){return String(e??"").replace(/[&<>"']/g,(t)=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"})[t])}async function v(e){try{let{html:r}=await ee("notification",{subject:e.subject??"",variables:{subject:e.subject??"",paragraphs:q(e.body),preheader:String(e.body??"").replace(/\s+/g," ").trim().slice(0,140),...e.action?.url?{actionUrl:e.action.url,actionLabel:e.action.label||"Open"}:{}}});if(r)return r}catch{}let t=e.action?.url?`<p><a href="${N(e.action.url)}">${N(e.action.label||e.action.url)}</a></p>`:"";return`<p>${N(e.body)}</p>${t}`}function x(e){return e.action?.url?`${e.body}
+import{log as S}from"@stacksjs/cli";import{notification as Ae}from"@stacksjs/config";import{mail as se}from"@stacksjs/email";import{log as A}from"@stacksjs/cli";var m={async send(e){let t=e.event??"notification",n=e.channel;if(!n)n=e.userId!==void 0?`private-user.${e.userId}`:"notifications";try{let i=await import("@stacksjs/realtime").catch(()=>null),r=i?.emit,a=i?.getServer;if(!r||!a)return{delivered:!1,channel:n,event:t,reason:"@stacksjs/realtime is not available"};if(!a())return{delivered:!1,channel:n,event:t,reason:"realtime server not running"};let s=e.private??e.userId!==void 0;return r(n,t,e.data,{private:s}),A.info(`[notifications] broadcast to '${n}' (${t})`),{delivered:!0,channel:n,event:t}}catch(i){let r=i instanceof Error?i.message:String(i);return A.warn(`[notifications] broadcast failed: ${r}`),{delivered:!1,channel:n,event:t,reason:r}}}};import*as j from"@stacksjs/chat";import{log as I}from"@stacksjs/cli";import{createHash as fe}from"crypto";import{db as u,enqueueAfterCommit as de,lockRow as pe,sqlDateTime as T}from"@stacksjs/database/runtime";import{emit as me,getServer as be}from"@stacksjs/realtime";function B(e){return`private-user.${e}`}function x(e,t,n){let i=()=>{try{if(be())me(B(e),t,n)}catch{I.warn("Notification inbox broadcast failed; the persisted inbox remains available")}};if(!de(i))i()}async function O(e,t){let n=T(),r=await u.insertInto("notifications").values({user_id:e.userId,...t?{uuid:t}:{},type:e.type,data:JSON.stringify(e.data),read_at:null,created_at:n,updated_at:n}).returning("id").execute(),a=Array.isArray(r)?r[0]:r,s=Number(a?.id??a?.insertId??a?.lastInsertRowid??a?.lastInsertId??0);if(!Number.isSafeInteger(s)||s<=0)throw Error("Database notification did not return a generated id");if(I.info(`Database notification sent to user ${e.userId}: ${e.type}`),e.broadcast!==!1)x(e.userId,"notifications.created",{id:s});return{id:s,user_id:e.userId,type:e.type,data:JSON.stringify(e.data),read_at:null,created_at:n,updated_at:n}}var b={async send(e){if(e.idempotencyKey!==void 0){if(!e.idempotencyKey||e.idempotencyKey.length>255)throw Error("A notification idempotency key must contain 1 to 255 characters");let t=fe("sha256").update(JSON.stringify([e.userId,e.type,e.idempotencyKey])).digest("hex"),n=`${t.slice(0,8)}-${t.slice(8,12)}-8${t.slice(13,16)}-8${t.slice(17,20)}-${t.slice(20,32)}`;return u.transaction(async(i)=>{if(!await pe(i,"users",{id:e.userId}))throw Error("Notification recipient not found");let a=await u.selectFrom("notifications").selectAll().where("user_id","=",e.userId).where("uuid","=",n).executeTakeFirst();if(a)return{...a,id:Number(a.id),user_id:Number(a.user_id)};return O(e,n)})}return O(e)},async getUserNotifications(e){return(await u.selectFrom("notifications").selectAll().where("user_id","=",e).orderBy("created_at","desc").execute()).map((n)=>({...n,id:Number(n.id),user_id:Number(n.user_id)}))},async getUnreadNotifications(e){return(await u.selectFrom("notifications").selectAll().where("user_id","=",e).whereNull("read_at").orderBy("created_at","desc").execute()).map((n)=>({...n,id:Number(n.id),user_id:Number(n.user_id)}))},async markAsRead(e,t){let n=u.updateTable("notifications").set({read_at:T()}).where("id","=",e).whereNull("read_at");if(t!==void 0)n=n.where("user_id","=",t);if(await n.execute(),t)x(t,"notifications.read",{id:e})},async markAllAsRead(e){await u.updateTable("notifications").set({read_at:T()}).where("user_id","=",e).whereNull("read_at").execute(),x(e,"notifications.read",{all:!0})},async unreadCount(e){let t=await u.selectFrom("notifications").select(u.fn.countAll().as("count")).where("user_id","=",e).whereNull("read_at").executeTakeFirst();return Number(t?.count??0)},async deleteNotification(e,t){let n=u.deleteFrom("notifications").where("id","=",e);if(t!==void 0)n=n.where("user_id","=",t);await n.execute()},async deleteAllNotifications(e){await u.deleteFrom("notifications").where("user_id","=",e).execute()}};import*as L from"@stacksjs/push";import*as h from"@stacksjs/sms";import{log as he}from"@stacksjs/cli";import{config as M}from"@stacksjs/config";import{db as ge,sqlDateTime as F}from"@stacksjs/database/runtime";function K(e,t){switch(t){case"email":return e.email||"";case"sms":return e.phone||"";case"push":return Array.isArray(e.pushTokens)?e.pushTokens.join(", "):e.pushTokens||"";case"broadcast":return e.broadcastChannel||(e.userId?`private-user.${e.userId}`:"notifications");case"database":return e.userId?`User #${e.userId}`:"";case"chat":return Array.isArray(e.chatRecipient)?e.chatRecipient.join(", "):e.chatRecipient||""}}function k(e,t,n,i,r=F()){return{userId:e.userId,channel:n.channel,recipient:K(e,n.channel),subject:t.subject,body:t.body,status:n.success?"sent":"failed",error:n.error?.message,metadata:{...t.data,...i.category?{category:i.category}:{}},sentAt:r}}function ye(e){let t=M.notification?.tracking;if(t?.enabled===!1)return!1;let n=t?.channels;if(!n||n.length===0)return!0;return n.includes(e)}async function P(e){if(!ye(e.channel))return;let t=F();try{await ge.insertInto("notification_deliveries").values({user_id:e.userId??null,channel:e.channel,recipient:e.recipient,subject:e.subject??null,body:M.notification?.tracking?.body===!1?"":e.body,status:e.status,error:e.error??null,metadata:e.metadata?JSON.stringify(e.metadata):null,sent_at:e.sentAt,created_at:t,updated_at:t}).execute()}catch(n){let i=n instanceof Error?n.message:String(n);he.warn(`[notifications] could not record ${e.channel} delivery: ${i}`)}}import{templateByName as Ne}from"@stacksjs/email";var g="You are receiving this because these emails are turned on in your settings.",z="Reply STOP to opt out.",we=/https?:\/\/[^\s<>"']+[^\s<>"'.,;:!?)\]]/g;function q(e){return String(e??"").replace(/\r\n?/g,`
+`).split(/\n\s*\n/).map((t)=>t.trim()).filter(Boolean).map((t)=>{let n=[];return t.split(`
+`).forEach((i,r)=>{if(r>0)n.push({br:!0});let a=0;for(let s of i.matchAll(we)){if(s.index>a)n.push({text:i.slice(a,s.index)});n.push({url:s[0]}),a=s.index+s[0].length}if(a<i.length)n.push({text:i.slice(a)})}),n})}function d(e){return String(e??"").replace(/[&<>"']/g,(t)=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"})[t])}async function Y(e){let t=e.unsubscribe?.url?e.unsubscribe:void 0;try{let{html:r}=await Ne("notification",{subject:e.subject??"",variables:{subject:e.subject??"",paragraphs:q(e.body),preheader:String(e.body??"").replace(/\s+/g," ").trim().slice(0,140),...e.action?.url?{actionUrl:e.action.url,actionLabel:e.action.label||"Open"}:{},...t?{unsubscribeUrl:t.url,unsubscribeNotice:t.notice||g,...t.preferencesUrl?{preferencesUrl:t.preferencesUrl}:{}}:{}}});if(r)return r}catch{}let n=e.action?.url?`<p><a href="${d(e.action.url)}">${d(e.action.label||e.action.url)}</a></p>`:"",i=t?`<p>${d(t.notice||g)} <a href="${d(t.url)}">Unsubscribe</a></p>`:"";return`<p>${d(e.body)}</p>${n}${i}`}function V(e){let t=e.action?.url?`${e.body}
 
-${e.action.label||"Open"}: ${e.action.url}`:e.body}import{log as re}from"@stacksjs/cli";import{db as l,lockRow as M,sqlDateTime as ne}from"@stacksjs/database/runtime";var p="notification_preferences";function R(e,t){return t===null?e.whereNull("category"):e.where("category","=",t)}async function P(e,t){let r=new Map;try{let a=await R(l.selectFrom(p).select(["channel","enabled","category"]).where("user_id","=",e),t??null).execute();for(let i of a)r.set(i.channel,i.enabled===!0||i.enabled===1)}catch(n){re.debug?.(`[notifications] preferences lookup failed (table missing?): ${n.message}`)}return r}async function ie(e,t,r,n){await l.transaction(async(a)=>{await M(a,"users",{id:e}),await F(e,t,r,n)})}async function F(e,t,r,n){if(!Number.isSafeInteger(e)||e<=0||typeof r!=="boolean")throw Error("A notification preference needs a valid user id and enabled boolean");let a=ne(),i=n??null,o=l.selectFrom(p).select(["id"]).where("user_id","=",e).where("channel","=",t),s=await R(o,i).executeTakeFirst();if(s?.id){await l.updateTable(p).set({enabled:r,updated_at:a}).where("id","=",s.id).execute();return}await l.insertInto(p).values({user_id:e,channel:t,enabled:r,category:i,created_at:a,updated_at:a}).execute()}async function ae(e,t){await l.transaction(async(r)=>{await M(r,"users",{id:e});for(let n of t)await F(e,n.channel,n.enabled,n.category)})}async function k(e,t,r){let n=await P(e,r);if(r!==void 0){let a=await P(e,void 0);for(let[i,o]of a)if(!o||!n.has(i))n.set(i,o)}return t.filter((a)=>{let i=n.get(a);return i===void 0?!0:i===!0})}var se=oe;function ce(e){if(!e.success)throw Error(e.message||`Email delivery failed through ${e.provider||"the configured provider"}.`)}function Ue(e){if(!e.length)throw Error("No notification channels were delivered");let t=e.filter((r)=>!r.success);if(t.length){let r=t.map((n)=>n.error instanceof Error?n.error:Error(`Notification delivery failed through ${n.channel}`));if(r.length===1)throw r[0];throw AggregateError(r,r.map((n)=>n.message).join("; "))}}function E(e){if(!e.success)throw Error(e.error||e.message||"Notification provider rejected delivery")}function L(e){let t=e||"slack";if(!["slack","discord","teams"].includes(t))throw Error(`Unsupported chat driver: ${t}`);return T[t]}function H(e){if(e)try{return U.use(e)}catch(t){_.warn(`[notifications] email driver '${e}' not registered - falling back to default mail singleton (${t.message})`)}return U}function K(e){if(!e)return h;if(e!=="twilio"&&e!=="vonage")throw Error(`Unsupported SMS driver: ${e}`);let t=e;return{send:async(r)=>(await h.init(),h.getDriver(t).send(r))}}function ue(){return I}function fe(){return m}function Le(){return d}function le(e,t){let r=e||se?.default||"email",n=t;switch(r){case"email":return H(n);case"chat":return L(n);case"sms":return K(n);case"database":return fe();default:throw Error(`Notification type "${r}" is not supported`)}}async function He(e,t,r=["email"],n={}){let a=[...new Set(r)];if(e.userId&&!n.ignorePreferences)try{a=await k(e.userId,a,n.category)}catch(s){_.warn(`[notify] preferences filter failed, sending all channels: ${s.message}`)}let o=(await Promise.allSettled(a.map(async(s)=>{switch(s){case"email":{if(!e.email)throw Error("[notify] email channel requires recipient.email");let f=await H().send({to:e.email,subject:t.subject??"",text:x(t),html:await v(t)});ce(f);break}case"sms":{if(!e.phone)throw Error("[notify] sms channel requires recipient.phone");if(n.ignorePreferences!==!0){let{isPhoneOptedOut:f}=await import("@stacksjs/sms");if(await f(e.phone))throw Error("[notify] sms recipient has opted out (STOP)")}let c=K();E(await c.send({to:e.phone,body:t.body}));break}case"chat":{if(!e.chatRecipient||Array.isArray(e.chatRecipient)&&!e.chatRecipient.length)throw Error("[notify] chat channel requires recipient.chatRecipient");let c=L();E(await c.send({to:e.chatRecipient,content:t.body,subject:t.subject,data:t.data}));break}case"database":{if(!e.userId)throw Error("[notify] database channel requires recipient.userId");await m.send({userId:e.userId,type:t.subject||"notification",data:{body:t.body,...t.data}});break}case"push":{if(!e.pushTokens||Array.isArray(e.pushTokens)&&e.pushTokens.length===0)throw Error("[notify] push channel requires recipient.pushTokens");let c=ue();E(await c.send(e.pushTokens,{title:t.subject,body:t.body,data:t.data},{driver:e.pushDriver}));break}case"broadcast":{let c=await d.send({channel:e.broadcastChannel,userId:e.userId,event:t.subject??"notification",data:{body:t.body,...t.data}});if(!c.delivered)throw Error(c.reason||"Broadcast notification was not delivered");break}default:throw Error(`Unsupported notification channel: ${s}`)}}))).map((s,c)=>{let f=a[c];if(!f)throw Error(`Missing notification channel for result ${c}`);if(s.status==="rejected"){let J=s.reason instanceof Error?s.reason.message:String(s.reason);_.warn(`[notify] ${f} channel failed: ${J}`)}return{channel:f,success:s.status==="fulfilled",error:s.status==="rejected"?s.reason instanceof Error?s.reason:Error(String(s.reason)):void 0}});return await Promise.all(o.map((s)=>w(y(e,t,s,n)))),o}function Ke(){return le()}export{d as BroadcastNotificationDriver,m as DatabaseNotificationDriver,ae as bulkSetPreferences,q as emailParagraphs,ce as ensureSuccessfulEmailResult,Ue as ensureSuccessfulNotificationResults,k as filterChannelsByPreferences,P as getNotificationPreferences,y as makeDeliveryRecord,Ke as notification,A as notificationChannel,v as notificationEmailHtml,x as notificationEmailText,He as notify,w as recordNotificationDelivery,O as resolveDeliveryRecipient,ie as setNotificationPreference,Le as useBroadcast,L as useChat,fe as useDatabase,H as useEmail,le as useNotification,ue as usePush,K as useSMS,R as wherePreferenceCategory};
+${e.action.label||"Open"}: ${e.action.url}`:e.body;if(e.unsubscribe?.url)t+=`
+
+${e.unsubscribe.notice||g}
+Unsubscribe: ${e.unsubscribe.url}`;return t}function W(e){if(!e?.url)return{};return{"List-Unsubscribe":`<${e.oneClickUrl||e.url}>`,...e.oneClickUrl?{"List-Unsubscribe-Post":"List-Unsubscribe=One-Click"}:{}}}async function v(e,t){let n={...t.headers,...W(t.unsubscribe)};return{to:e,subject:t.subject??"",text:V(t),html:await Y(t),...Object.keys(n).length?{headers:n}:{}}}function _(e,t){let n=String(e.body??"");if(e.smsOptOut===!1)return n;let i=typeof e.smsOptOut==="string"?e.smsOptOut.trim():t==="marketing"?z:"";if(!i||n.toLowerCase().includes(i.toLowerCase()))return n;return`${n.trimEnd()}
+
+${i}`}import{log as Te}from"@stacksjs/cli";import{db as f,lockRow as H,sqlDateTime as xe}from"@stacksjs/database/runtime";var y="notification_preferences";function R(e,t){return t===null?e.whereNull("category"):e.where("category","=",t)}async function E(e,t){let n=new Map;try{let r=await R(f.selectFrom(y).select(["channel","enabled","category"]).where("user_id","=",e),t??null).execute();for(let a of r)n.set(a.channel,a.enabled===!0||a.enabled===1)}catch(i){Te.debug?.(`[notifications] preferences lookup failed (table missing?): ${i.message}`)}return n}async function C(e,t,n,i){await f.transaction(async(r)=>{await H(r,"users",{id:e}),await J(e,t,n,i)})}async function J(e,t,n,i){if(!Number.isSafeInteger(e)||e<=0||typeof n!=="boolean")throw Error("A notification preference needs a valid user id and enabled boolean");let r=xe(),a=i??null,s=f.selectFrom(y).select(["id"]).where("user_id","=",e).where("channel","=",t),o=await R(s,a).executeTakeFirst();if(o?.id){await f.updateTable(y).set({enabled:n,updated_at:r}).where("id","=",o.id).execute();return}await f.insertInto(y).values({user_id:e,channel:t,enabled:n,category:a,created_at:r,updated_at:r}).execute()}async function ke(e,t){await f.transaction(async(n)=>{await H(n,"users",{id:e});for(let i of t)await J(e,i.channel,i.enabled,i.category)})}async function D(e,t,n){let i=await E(e,n);if(n!==void 0){let r=await E(e,void 0);for(let[a,s]of r)if(!s||!i.has(a))i.set(a,s)}return t.filter((r)=>{let a=i.get(r);return a===void 0?!0:a===!0})}import N from"process";import{createHmac as Pe,timingSafeEqual as ve}from"crypto";var Q=["email","sms"];function _e(){let e=N.env.APP_KEY;if((!e||e.length<16)&&(N.env.APP_ENV==="production"||N.env.NODE_ENV==="production"))throw Error("[notifications/unsubscribe] APP_KEY is missing or too short (need at least 16 characters). Cannot sign unsubscribe links.");return e||"stacks-default-key-dev-only-do-not-use-prod"}function Z(e){return Pe("sha256",_e()).update(e).digest("hex")}function G(e,t,n="marketing"){if(!Number.isSafeInteger(e)||e<=0)throw Error("An unsubscribe token needs a positive user id");if(!Q.includes(t))throw Error(`Unsupported unsubscribe channel: ${t}`);if(!n||n.includes(":"))throw Error("An unsubscribe category must be non-empty and contain no colon");let i=`${e}:${t}:${n}`;return Buffer.from(`${i}:${Z(i)}`).toString("base64url")}function X(e){try{let t=Buffer.from(String(e??""),"base64url").toString("utf8");if(!e||Buffer.from(t).toString("base64url")!==e)return null;let n=t.split(":");if(n.length!==4)return null;let[i,r,a,s]=n;if(!i||!a||!s||!Q.includes(r))return null;let o=Z(`${i}:${r}:${a}`);if(s.length!==o.length||!ve(Buffer.from(s),Buffer.from(o)))return null;let c=Number(i);return Number.isSafeInteger(c)&&c>0&&String(c)===i?{userId:c,channel:r,category:a}:null}catch{return null}}function Ee(e,t={}){let n=String(t.baseUrl||N.env.APP_URL||"http://localhost").replace(/\/$/,""),i=G(e,t.channel??"email",t.category??"marketing"),r=(a)=>a.startsWith("/")?a:`/${a}`;return{url:`${n}${r(t.pagePath??"/unsubscribe")}?token=${i}`,oneClickUrl:`${n}${r(t.endpointPath??"/api/notifications/unsubscribe")}?token=${i}`,...t.preferencesPath===!1?{}:{preferencesUrl:`${n}${r(t.preferencesPath??"/settings")}`},...t.notice?{notice:t.notice}:{}}}async function Re(e){let t=new URL(e.url,"http://localhost").searchParams.get("token");if(t)return t;let n=await e.json?.().catch(()=>({}));return String(n?.token||"")}async function Ce(e){let t=X(e);if(!t)return null;return await C(t.userId,t.channel,!1,t.category),t}function ee(e={}){let t=e.resetPassword??"/forgot-password";return{password_changed:{copy:{en:{subject:"Your {{app}} password was changed",body:`The password for your {{app}} account was changed.
+
+If you did this, there\u2019s nothing else to do. If you didn\u2019t, reset your password right away and let us know at {{support_email}}.`},de:{subject:"Dein {{app}}-Passwort wurde ge\xE4ndert",body:`Das Passwort f\xFCr dein {{app}}-Konto wurde ge\xE4ndert.
+
+Warst du das, musst du nichts weiter tun. Falls nicht, setze dein Passwort sofort zur\xFCck und gib uns unter {{support_email}} Bescheid.`}},action:{path:t,label:{en:"Reset your password",de:"Passwort zur\xFCcksetzen"}}},email_changed:{copy:{en:{subject:"Your {{app}} sign-in email was changed",body:`The email address for your {{app}} account was changed from {{old_email}} to {{new_email}}. From now on, you sign in and get email at {{new_email}}.
+
+If you didn\u2019t make this change, write to us at {{support_email}} straight away.`},de:{subject:"Deine Anmelde-E-Mail bei {{app}} wurde ge\xE4ndert",body:`Die E-Mail-Adresse deines {{app}}-Kontos wurde von {{old_email}} zu {{new_email}} ge\xE4ndert. Ab jetzt meldest du dich mit {{new_email}} an und bekommst dort deine E-Mails.
+
+Warst du das nicht, schreib uns sofort an {{support_email}}.`}}},account_deleted:{copy:{en:{subject:"Your {{app}} account is deleted",body:`Your {{app}} account was deleted on {{date}}. This is the last email we\u2019ll send to this address.
+
+If you didn\u2019t ask for this, write to us at {{support_email}}.`},de:{subject:"Dein {{app}}-Konto ist gel\xF6scht",body:`Dein {{app}}-Konto wurde am {{date}} gel\xF6scht. Das ist die letzte E-Mail, die wir an diese Adresse schicken.
+
+Hast du das nicht veranlasst, schreib uns an {{support_email}}.`}}},account_created:{copy:{en:{subject:"{{inviter}} added you to {{app}}",body:`{{inviter}} created an {{app}} account for you with this email address.
+
+Set a password to sign in. The link works for {{days}} days; after that, use \u201CForgot password\u201D on the sign-in page.`},de:{subject:"{{inviter}} hat dich zu {{app}} hinzugef\xFCgt",body:`{{inviter}} hat f\xFCr dich ein {{app}}-Konto mit dieser E-Mail-Adresse angelegt.
+
+Lege ein Passwort fest, um dich anzumelden. Der Link gilt {{days}} Tage; danach nutze \u201EPasswort vergessen\u201C auf der Anmeldeseite.`}},action:{path:"{{set_password_url}}",label:{en:"Set your password",de:"Passwort festlegen"}}}}}function te(e={}){let t=e.orders??"/orders",n=e.sales??"/orders";return{order_receipt:{copy:{en:{subject:"Your receipt from {{seller}}",body:`Thanks for your purchase from {{seller}}.
+
+{{lines}}
+Total: {{total}}
+
+Order {{order_number}}, paid {{date}}.`},de:{subject:"Deine Quittung von {{seller}}",body:`Danke f\xFCr deinen Einkauf bei {{seller}}.
+
+{{lines}}
+Summe: {{total}}
+
+Bestellung {{order_number}}, bezahlt am {{date}}.`}},action:{path:t,label:{en:"View your purchases",de:"Deine K\xE4ufe ansehen"}}},order_refunded:{copy:{en:{subject:"Refund from {{seller}}: {{amount}}",body:`{{seller}} refunded {{amount}} for order {{order_number}}.
+
+Money paid by card goes back to that card, which usually takes 5 to 10 business days to show. Anything refunded as account credit is ready for your next purchase.`},de:{subject:"Erstattung von {{seller}}: {{amount}}",body:`{{seller}} hat dir {{amount}} f\xFCr die Bestellung {{order_number}} erstattet.
+
+Per Karte Bezahltes geht auf diese Karte zur\xFCck, was meist 5 bis 10 Werktage dauert. Als Guthaben Erstattetes kannst du bei deinem n\xE4chsten Einkauf verwenden.`}},action:{path:t,label:{en:"View your purchases",de:"Deine K\xE4ufe ansehen"}}},new_sale:{copy:{en:{subject:"New sale: {{item}}",body:`{{buyer}} bought {{item}} for {{total}}.
+
+Order {{order_number}}.`},de:{subject:"Neuer Verkauf: {{item}}",body:`{{buyer}} hat {{item}} f\xFCr {{total}} gekauft.
+
+Bestellung {{order_number}}.`}},action:{path:n,label:{en:"View your sales",de:"Verk\xE4ufe ansehen"}}},account_credit_added:{copy:{en:{subject:"{{amount}} credit from {{seller}}",body:`{{seller}} added {{amount}} to your account: {{reason}}
+
+Your balance is now {{balance}}. You can use it on your next purchase.`},de:{subject:"{{amount}} Guthaben von {{seller}}",body:`{{seller}} hat deinem Konto {{amount}} gutgeschrieben: {{reason}}
+
+Dein Guthaben betr\xE4gt jetzt {{balance}}. Du kannst es bei deinem n\xE4chsten Einkauf verwenden.`}}}}}function ne(e={}){let t=e.billing??"/billing";return{subscription_trial_ending:{copy:{en:{subject:"Your {{app}} trial ends on {{date}}",body:"Your {{plan}} trial ends on {{date}}. To keep using {{plan}}, check that your payment details are up to date. To stop, cancel before then and you won\u2019t be charged."},de:{subject:"Deine {{app}}-Testphase endet am {{date}}",body:"Deine Testphase f\xFCr {{plan}} endet am {{date}}. Wenn du {{plan}} weiter nutzen willst, pr\xFCfe, ob deine Zahlungsdaten aktuell sind. Wenn nicht, k\xFCndige vorher, dann wird nichts berechnet."}},action:{path:t,label:{en:"Manage billing",de:"Abrechnung verwalten"}}},subscription_payment_failed:{copy:{en:{subject:"Payment for {{plan}} failed",body:"We couldn\u2019t charge your payment method for your {{app}} {{plan}} plan. Update it to keep {{plan}} active."},de:{subject:"Zahlung f\xFCr {{plan}} fehlgeschlagen",body:"Wir konnten deine Zahlungsmethode f\xFCr deinen {{app}}-Tarif {{plan}} nicht belasten. Aktualisiere sie, damit {{plan}} aktiv bleibt."}},action:{path:t,label:{en:"Update payment method",de:"Zahlungsmethode aktualisieren"}}},subscription_ended:{copy:{en:{subject:"Your {{app}} {{plan}} plan has ended",body:"Your {{plan}} plan ended on {{date}}. Your account and data are still here; choose a plan again whenever you\u2019re ready."},de:{subject:"Dein {{app}}-Tarif {{plan}} ist beendet",body:"Dein Tarif {{plan}} endete am {{date}}. Dein Konto und deine Daten bleiben erhalten; du kannst jederzeit wieder einen Tarif w\xE4hlen."}},action:{path:t,label:{en:"Choose a plan",de:"Tarif w\xE4hlen"}}}}}var ie=/\{\{\s*([a-z0-9_]+)\s*\}\}/gi;function De(e){return e}function w(e,t={}){return e.replace(ie,(n,i)=>{let r=t[i];return r==null?"":String(r)})}function re(e){return[...new Set([...e.matchAll(ie)].map((t)=>t[1]))]}function ae(e,t,n="en"){let i=String(t||"").trim();if(i&&e.includes(i))return i;let r=i.split(/[-_]/)[0]?.toLowerCase();if(r&&e.includes(r))return r;if(e.includes(n))return n;let a=e[0];if(!a)throw Error("A notification template needs copy in at least one language");return a}function Ue(e,t){if(/^https?:\/\//i.test(t))return t;let n=String(e||"").replace(/\/+$/,"");if(!t)return n;return`${n}${t.startsWith("/")?"":"/"}${t}`}function oe(e,t={},n={}){let i=n.fallbackLocale||"en",r=ae(Object.keys(e.copy),n.locale,i),a=e.copy[r],s={subject:w(a.subject,t),body:w(a.body,t)},o=e.action;if(o){let c=re(o.path).some((p)=>t[p]==null||t[p]===""),l=o.label[r]??o.label[i]??Object.values(o.label)[0];if(!c&&l)s.action={label:l,url:Ue(n.baseUrl,w(o.path,t))}}return s}function Se(e,t={}){let n=Object.keys(e),i=()=>typeof t.baseUrl==="function"?t.baseUrl():t.baseUrl;return{templates:e,names:n,has:(r)=>Object.hasOwn(e,r),render(r,a={},s){let o=e[r];if(!o)throw Error(`Unknown notification template "${String(r)}"`);return oe(o,a,{locale:s,fallbackLocale:t.fallbackLocale,baseUrl:i()})}}}var $e=Ae;function je(e){if(!e.success)throw Error(e.message||`Email delivery failed through ${e.provider||"the configured provider"}.`)}function vt(e){if(!e.length)throw Error("No notification channels were delivered");let t=e.filter((n)=>!n.success);if(t.length){let n=t.map((i)=>i.error instanceof Error?i.error:Error(`Notification delivery failed through ${i.channel}`));if(n.length===1)throw n[0];throw AggregateError(n,n.map((i)=>i.message).join("; "))}}function U(e){if(!e.success)throw Error(e.error||e.message||"Notification provider rejected delivery")}function ce(e){let t=e||"slack";if(!["slack","discord","teams"].includes(t))throw Error(`Unsupported chat driver: ${t}`);return j[t]}function ue(e){if(e)try{return se.use(e)}catch(t){S.warn(`[notifications] email driver '${e}' not registered - falling back to default mail singleton (${t.message})`)}return se}function le(e){if(!e)return h;if(e!=="twilio"&&e!=="vonage")throw Error(`Unsupported SMS driver: ${e}`);let t=e;return{send:async(n)=>(await h.init(),h.getDriver(t).send(n))}}function Oe(){return L}function Ie(){return b}function _t(){return m}function Be(e,t){let n=e||$e?.default||"email",i=t;switch(n){case"email":return ue(i);case"chat":return ce(i);case"sms":return le(i);case"database":return Ie();default:throw Error(`Notification type "${n}" is not supported`)}}async function Et(e,t,n=["email"],i={}){let r=[...new Set(n)];if(e.userId&&!i.ignorePreferences)try{r=await D(e.userId,r,i.category)}catch(o){S.warn(`[notify] preferences filter failed, sending all channels: ${o.message}`)}let s=(await Promise.allSettled(r.map(async(o)=>{switch(o){case"email":{if(!e.email)throw Error("[notify] email channel requires recipient.email");let l=await ue().send(await v(e.email,t));je(l);break}case"sms":{if(!e.phone)throw Error("[notify] sms channel requires recipient.phone");if(i.ignorePreferences!==!0){let{isPhoneOptedOut:l}=await import("@stacksjs/sms");if(await l(e.phone))throw Error("[notify] sms recipient has opted out (STOP)")}let c=le();U(await c.send({to:e.phone,body:_(t,i.category)}));break}case"chat":{if(!e.chatRecipient||Array.isArray(e.chatRecipient)&&!e.chatRecipient.length)throw Error("[notify] chat channel requires recipient.chatRecipient");let c=ce();U(await c.send({to:e.chatRecipient,content:t.body,subject:t.subject,data:t.data}));break}case"database":{if(!e.userId)throw Error("[notify] database channel requires recipient.userId");await b.send({userId:e.userId,type:t.subject||"notification",data:{body:t.body,...t.data}});break}case"push":{if(!e.pushTokens||Array.isArray(e.pushTokens)&&e.pushTokens.length===0)throw Error("[notify] push channel requires recipient.pushTokens");let c=Oe();U(await c.send(e.pushTokens,{title:t.subject,body:t.body,data:t.data},{driver:e.pushDriver}));break}case"broadcast":{let c=await m.send({channel:e.broadcastChannel,userId:e.userId,event:t.subject??"notification",data:{body:t.body,...t.data}});if(!c.delivered)throw Error(c.reason||"Broadcast notification was not delivered");break}default:throw Error(`Unsupported notification channel: ${o}`)}}))).map((o,c)=>{let l=r[c];if(!l)throw Error(`Missing notification channel for result ${c}`);if(o.status==="rejected"){let p=o.reason instanceof Error?o.reason.message:String(o.reason);S.warn(`[notify] ${l} channel failed: ${p}`)}return{channel:l,success:o.status==="fulfilled",error:o.status==="rejected"?o.reason instanceof Error?o.reason:Error(String(o.reason)):void 0}});return await Promise.all(s.map((o)=>P(k(e,t,o,i)))),s}function Rt(){return Be()}export{m as BroadcastNotificationDriver,z as DEFAULT_SMS_OPT_OUT,g as DEFAULT_UNSUBSCRIBE_NOTICE,b as DatabaseNotificationDriver,ee as accountNotificationTemplates,ke as bulkSetPreferences,te as commerceNotificationTemplates,Se as createNotificationTemplates,De as defineNotificationTemplates,q as emailParagraphs,je as ensureSuccessfulEmailResult,vt as ensureSuccessfulNotificationResults,D as filterChannelsByPreferences,E as getNotificationPreferences,w as interpolateNotificationText,W as listUnsubscribeHeaders,k as makeDeliveryRecord,Rt as notification,B as notificationChannel,Y as notificationEmailHtml,v as notificationEmailMessage,V as notificationEmailText,_ as notificationSmsBody,re as notificationTemplateVariables,Ee as notificationUnsubscribeLinks,G as notificationUnsubscribeToken,Et as notify,X as parseNotificationUnsubscribeToken,P as recordNotificationDelivery,oe as renderNotificationTemplate,K as resolveDeliveryRecipient,ae as resolveNotificationLocale,C as setNotificationPreference,ne as subscriptionNotificationTemplates,Re as unsubscribeTokenFromRequest,Ce as unsubscribeWithToken,_t as useBroadcast,ce as useChat,Ie as useDatabase,ue as useEmail,Be as useNotification,Oe as usePush,le as useSMS,R as wherePreferenceCategory};

package/dist/template-catalogs/account.d.ts

@@ -0,0 +1,21 @@
+import type { NotificationTemplateDefinition } from '../templates';
+export declare function accountNotificationTemplates(paths?: AccountNotificationPaths): Record<AccountNotificationTemplateName, NotificationTemplateDefinition>;
+/** Where the account messages' buttons lead. Defaults are the framework's own pages. */
+export declare interface AccountNotificationPaths {
+  resetPassword?: string
+}
+/**
+ * Account security messages, in English and German. Every one is
+ * transactional: send it whatever the person's preferences say.
+ *
+ * Variables: `app` (the app's name) and `support_email` in all of them, plus
+ * - `password_changed`: none;
+ * - `email_changed`: `old_email`, `new_email`. Send it to both addresses: the
+ *   old one is how the owner learns of a change they did not make;
+ * - `account_deleted`: `date`. Send it before the address is erased;
+ * - `account_created`: `inviter` (who created it), `set_password_url` (a
+ *   one-time link, so send it outside any stored queue) and `days` (how long
+ *   that link works; two or more).
+ */
+/** The names this catalog defines. */
+export type AccountNotificationTemplateName = 'password_changed' | 'email_changed' | 'account_deleted' | 'account_created';

package/dist/template-catalogs/commerce.d.ts

@@ -0,0 +1,21 @@
+import type { NotificationTemplateDefinition } from '../templates';
+export declare function commerceNotificationTemplates(paths?: CommerceNotificationPaths): Record<CommerceNotificationTemplateName, NotificationTemplateDefinition>;
+/** Where the commerce messages' buttons lead. */
+export declare interface CommerceNotificationPaths {
+  orders?: string
+  sales?: string
+}
+/**
+ * Receipts and money messages, in English and German. Format every amount
+ * before passing it (`formatMinor` from `@stacksjs/commerce/money`), so the
+ * currency is right; `lines` is the itemized purchase, one line each
+ * (`receiptLinesText` from `@stacksjs/commerce/receipt-text`).
+ *
+ * Variables:
+ * - `order_receipt` (to the buyer): `seller`, `lines`, `total`, `order_number`, `date`;
+ * - `order_refunded` (to the buyer): `seller`, `amount`, `order_number`;
+ * - `new_sale` (to the seller): `buyer`, `item`, `total`, `order_number`;
+ * - `account_credit_added` (to the customer): `seller`, `amount`, `reason`, `balance`.
+ */
+/** The names this catalog defines. */
+export type CommerceNotificationTemplateName = 'order_receipt' | 'order_refunded' | 'new_sale' | 'account_credit_added';

package/dist/template-catalogs/subscription.d.ts

@@ -0,0 +1,14 @@
+import type { NotificationTemplateDefinition } from '../templates';
+export declare function subscriptionNotificationTemplates(paths?: SubscriptionNotificationPaths): Record<SubscriptionNotificationTemplateName, NotificationTemplateDefinition>;
+/** Where the subscription messages' buttons lead. */
+export declare interface SubscriptionNotificationPaths {
+  billing?: string
+}
+/**
+ * A subscriber's own plan with the app (SaaS billing), in English and German.
+ *
+ * Variables: `app`, `plan` (its name), plus `date` for `subscription_trial_ending`
+ * (the last day of the trial) and `subscription_ended` (when it ended).
+ */
+/** The names this catalog defines. */
+export type SubscriptionNotificationTemplateName = 'subscription_trial_ending' | 'subscription_payment_failed' | 'subscription_ended';

package/dist/templates.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Declare a catalog. Returns it unchanged; the point is the checked shape and
+ * the literal names, so `render('nmae')` is a type error.
+ */
+export declare function defineNotificationTemplates<const T extends Record<string, NotificationTemplateDefinition>>(templates: T): T;
+/** Replace every `{{name}}` with that variable; a missing or null one becomes empty. */
+export declare function interpolateNotificationText(text: string, variables?: NotificationTemplateVariables): string;
+/** The variables a text refers to, in order of first use. */
+export declare function notificationTemplateVariables(text: string): string[];
+/** The language a template is rendered in: exact, then the base language, then the fallback, then its first. */
+export declare function resolveNotificationLocale(available: readonly string[], locale?: string | null, fallbackLocale?: string): string;
+/** Render one template definition for one recipient. */
+export declare function renderNotificationTemplate(definition: NotificationTemplateDefinition, variables?: NotificationTemplateVariables, options?: RenderNotificationTemplateOptions): RenderedNotificationTemplate;
+/** A catalog bound to the app's URL and fallback language. */
+export declare function createNotificationTemplates<const T extends Record<string, NotificationTemplateDefinition>>(templates: T, options?: NotificationTemplateCatalogOptions): NotificationTemplateCatalog<T>;
+/** One language's copy of a message. */
+export declare interface NotificationTemplateCopy {
+  subject: string
+  body: string
+}
+/** The email's button: where it leads (a path or URL) and its label per language. */
+export declare interface NotificationTemplateAction {
+  path: string
+  label: Record<string, string>
+}
+/** A named message: its copy per language and, optionally, a button. */
+export declare interface NotificationTemplateDefinition {
+  copy: Record<string, NotificationTemplateCopy>
+  action?: NotificationTemplateAction
+}
+/** What a template renders to: the payload `notify()` takes. */
+export declare interface RenderedNotificationTemplate {
+  subject: string
+  body: string
+  action?: { label: string, url: string }
+}
+export declare interface RenderNotificationTemplateOptions {
+  locale?: string | null
+  fallbackLocale?: string
+  baseUrl?: string
+}
+export declare interface NotificationTemplateCatalogOptions {
+  baseUrl?: string | (() => string)
+  fallbackLocale?: string
+}
+export declare interface NotificationTemplateCatalog<T extends Record<string, NotificationTemplateDefinition>> {
+  readonly templates: T
+  readonly names: Array<keyof T & string>
+  has: (name: string) => name is keyof T & string
+  render: (name: keyof T & string, variables?: NotificationTemplateVariables, locale?: string | null) => RenderedNotificationTemplate
+}
+export type NotificationTemplateVariables = Record<string, unknown>;
+/**
+ * Localized notification templates: a catalog of named messages, each with
+ * its copy in every language the app speaks and the email's button, rendered
+ * into the `{ subject, body, action }` that `notify()` sends.
+ *
+ * ```ts
+ * import { accountNotificationTemplates, createNotificationTemplates, defineNotificationTemplates } from '@stacksjs/notifications/templates'
+ *
+ * const templates = createNotificationTemplates({
+ *   ...accountNotificationTemplates(),
+ *   ...defineNotificationTemplates({
+ *     class_booked: {
+ *       copy: {
+ *         en: { subject: 'You’re booked', body: 'See you at {{class_name}} on {{date}}.' },
+ *         de: { subject: 'Du bist gebucht', body: 'Bis {{date}} bei {{class_name}}.' },
+ *       },
+ *       action: { path: '/schedule', label: { en: 'View your schedule', de: 'Zum Stundenplan' } },
+ *     },
+ *   }),
+ * }, { baseUrl: 'https://example.com' })
+ *
+ * templates.render('class_booked', { class_name: 'Strength', date: '2026-07-20' }, 'de')
+ * ```
+ *
+ * `{{name}}` in a subject, body or button path is replaced by that variable
+ * (a missing one by nothing). A button whose path needs a variable that was
+ * not given is left out rather than sent half-built. A path that renders to an
+ * absolute URL is used as it is; any other is joined to `baseUrl`.
+ *
+ * Pure and browser-safe: no database, config or mail imports.
+ */
+export {
+  accountNotificationTemplates,
+  type AccountNotificationPaths,
+  type AccountNotificationTemplateName,
+} from './template-catalogs/account';
+export {
+  commerceNotificationTemplates,
+  type CommerceNotificationPaths,
+  type CommerceNotificationTemplateName,
+} from './template-catalogs/commerce';
+export {
+  subscriptionNotificationTemplates,
+  type SubscriptionNotificationPaths,
+  type SubscriptionNotificationTemplateName,
+} from './template-catalogs/subscription';

package/dist/templates.js

@@ -0,0 +1,40 @@
+// @bun
+function f(t={}){let e=t.resetPassword??"/forgot-password";return{password_changed:{copy:{en:{subject:"Your {{app}} password was changed",body:`The password for your {{app}} account was changed.
+
+If you did this, there\u2019s nothing else to do. If you didn\u2019t, reset your password right away and let us know at {{support_email}}.`},de:{subject:"Dein {{app}}-Passwort wurde ge\xE4ndert",body:`Das Passwort f\xFCr dein {{app}}-Konto wurde ge\xE4ndert.
+
+Warst du das, musst du nichts weiter tun. Falls nicht, setze dein Passwort sofort zur\xFCck und gib uns unter {{support_email}} Bescheid.`}},action:{path:e,label:{en:"Reset your password",de:"Passwort zur\xFCcksetzen"}}},email_changed:{copy:{en:{subject:"Your {{app}} sign-in email was changed",body:`The email address for your {{app}} account was changed from {{old_email}} to {{new_email}}. From now on, you sign in and get email at {{new_email}}.
+
+If you didn\u2019t make this change, write to us at {{support_email}} straight away.`},de:{subject:"Deine Anmelde-E-Mail bei {{app}} wurde ge\xE4ndert",body:`Die E-Mail-Adresse deines {{app}}-Kontos wurde von {{old_email}} zu {{new_email}} ge\xE4ndert. Ab jetzt meldest du dich mit {{new_email}} an und bekommst dort deine E-Mails.
+
+Warst du das nicht, schreib uns sofort an {{support_email}}.`}}},account_deleted:{copy:{en:{subject:"Your {{app}} account is deleted",body:`Your {{app}} account was deleted on {{date}}. This is the last email we\u2019ll send to this address.
+
+If you didn\u2019t ask for this, write to us at {{support_email}}.`},de:{subject:"Dein {{app}}-Konto ist gel\xF6scht",body:`Dein {{app}}-Konto wurde am {{date}} gel\xF6scht. Das ist die letzte E-Mail, die wir an diese Adresse schicken.
+
+Hast du das nicht veranlasst, schreib uns an {{support_email}}.`}}},account_created:{copy:{en:{subject:"{{inviter}} added you to {{app}}",body:`{{inviter}} created an {{app}} account for you with this email address.
+
+Set a password to sign in. The link works for {{days}} days; after that, use \u201CForgot password\u201D on the sign-in page.`},de:{subject:"{{inviter}} hat dich zu {{app}} hinzugef\xFCgt",body:`{{inviter}} hat f\xFCr dich ein {{app}}-Konto mit dieser E-Mail-Adresse angelegt.
+
+Lege ein Passwort fest, um dich anzumelden. Der Link gilt {{days}} Tage; danach nutze \u201EPasswort vergessen\u201C auf der Anmeldeseite.`}},action:{path:"{{set_password_url}}",label:{en:"Set your password",de:"Passwort festlegen"}}}}}function m(t={}){let e=t.orders??"/orders",n=t.sales??"/orders";return{order_receipt:{copy:{en:{subject:"Your receipt from {{seller}}",body:`Thanks for your purchase from {{seller}}.
+
+{{lines}}
+Total: {{total}}
+
+Order {{order_number}}, paid {{date}}.`},de:{subject:"Deine Quittung von {{seller}}",body:`Danke f\xFCr deinen Einkauf bei {{seller}}.
+
+{{lines}}
+Summe: {{total}}
+
+Bestellung {{order_number}}, bezahlt am {{date}}.`}},action:{path:e,label:{en:"View your purchases",de:"Deine K\xE4ufe ansehen"}}},order_refunded:{copy:{en:{subject:"Refund from {{seller}}: {{amount}}",body:`{{seller}} refunded {{amount}} for order {{order_number}}.
+
+Money paid by card goes back to that card, which usually takes 5 to 10 business days to show. Anything refunded as account credit is ready for your next purchase.`},de:{subject:"Erstattung von {{seller}}: {{amount}}",body:`{{seller}} hat dir {{amount}} f\xFCr die Bestellung {{order_number}} erstattet.
+
+Per Karte Bezahltes geht auf diese Karte zur\xFCck, was meist 5 bis 10 Werktage dauert. Als Guthaben Erstattetes kannst du bei deinem n\xE4chsten Einkauf verwenden.`}},action:{path:e,label:{en:"View your purchases",de:"Deine K\xE4ufe ansehen"}}},new_sale:{copy:{en:{subject:"New sale: {{item}}",body:`{{buyer}} bought {{item}} for {{total}}.
+
+Order {{order_number}}.`},de:{subject:"Neuer Verkauf: {{item}}",body:`{{buyer}} hat {{item}} f\xFCr {{total}} gekauft.
+
+Bestellung {{order_number}}.`}},action:{path:n,label:{en:"View your sales",de:"Verk\xE4ufe ansehen"}}},account_credit_added:{copy:{en:{subject:"{{amount}} credit from {{seller}}",body:`{{seller}} added {{amount}} to your account: {{reason}}
+
+Your balance is now {{balance}}. You can use it on your next purchase.`},de:{subject:"{{amount}} Guthaben von {{seller}}",body:`{{seller}} hat deinem Konto {{amount}} gutgeschrieben: {{reason}}
+
+Dein Guthaben betr\xE4gt jetzt {{balance}}. Du kannst es bei deinem n\xE4chsten Einkauf verwenden.`}}}}}function b(t={}){let e=t.billing??"/billing";return{subscription_trial_ending:{copy:{en:{subject:"Your {{app}} trial ends on {{date}}",body:"Your {{plan}} trial ends on {{date}}. To keep using {{plan}}, check that your payment details are up to date. To stop, cancel before then and you won\u2019t be charged."},de:{subject:"Deine {{app}}-Testphase endet am {{date}}",body:"Deine Testphase f\xFCr {{plan}} endet am {{date}}. Wenn du {{plan}} weiter nutzen willst, pr\xFCfe, ob deine Zahlungsdaten aktuell sind. Wenn nicht, k\xFCndige vorher, dann wird nichts berechnet."}},action:{path:e,label:{en:"Manage billing",de:"Abrechnung verwalten"}}},subscription_payment_failed:{copy:{en:{subject:"Payment for {{plan}} failed",body:"We couldn\u2019t charge your payment method for your {{app}} {{plan}} plan. Update it to keep {{plan}} active."},de:{subject:"Zahlung f\xFCr {{plan}} fehlgeschlagen",body:"Wir konnten deine Zahlungsmethode f\xFCr deinen {{app}}-Tarif {{plan}} nicht belasten. Aktualisiere sie, damit {{plan}} aktiv bleibt."}},action:{path:e,label:{en:"Update payment method",de:"Zahlungsmethode aktualisieren"}}},subscription_ended:{copy:{en:{subject:"Your {{app}} {{plan}} plan has ended",body:"Your {{plan}} plan ended on {{date}}. Your account and data are still here; choose a plan again whenever you\u2019re ready."},de:{subject:"Dein {{app}}-Tarif {{plan}} ist beendet",body:"Dein Tarif {{plan}} endete am {{date}}. Dein Konto und deine Daten bleiben erhalten; du kannst jederzeit wieder einen Tarif w\xE4hlen."}},action:{path:e,label:{en:"Choose a plan",de:"Tarif w\xE4hlen"}}}}}var u=/\{\{\s*([a-z0-9_]+)\s*\}\}/gi;function k(t){return t}function c(t,e={}){return t.replace(u,(n,i)=>{let a=e[i];return a==null?"":String(a)})}function g(t){return[...new Set([...t.matchAll(u)].map((e)=>e[1]))]}function h(t,e,n="en"){let i=String(e||"").trim();if(i&&t.includes(i))return i;let a=i.split(/[-_]/)[0]?.toLowerCase();if(a&&t.includes(a))return a;if(t.includes(n))return n;let r=t[0];if(!r)throw Error("A notification template needs copy in at least one language");return r}function y(t,e){if(/^https?:\/\//i.test(e))return e;let n=String(t||"").replace(/\/+$/,"");if(!e)return n;return`${n}${e.startsWith("/")?"":"/"}${e}`}function T(t,e={},n={}){let i=n.fallbackLocale||"en",a=h(Object.keys(t.copy),n.locale,i),r=t.copy[a],s={subject:c(r.subject,e),body:c(r.body,e)},o=t.action;if(o){let p=g(o.path).some((d)=>e[d]==null||e[d]===""),l=o.label[a]??o.label[i]??Object.values(o.label)[0];if(!p&&l)s.action={label:l,url:y(n.baseUrl,c(o.path,e))}}return s}function j(t,e={}){let n=Object.keys(t),i=()=>typeof e.baseUrl==="function"?e.baseUrl():e.baseUrl;return{templates:t,names:n,has:(a)=>Object.hasOwn(t,a),render(a,r={},s){let o=t[a];if(!o)throw Error(`Unknown notification template "${String(a)}"`);return T(o,r,{locale:s,fallbackLocale:e.fallbackLocale,baseUrl:i()})}}}export{f as accountNotificationTemplates,m as commerceNotificationTemplates,j as createNotificationTemplates,k as defineNotificationTemplates,c as interpolateNotificationText,g as notificationTemplateVariables,T as renderNotificationTemplate,h as resolveNotificationLocale,b as subscriptionNotificationTemplates};

package/dist/unsubscribe.d.ts

@@ -0,0 +1,55 @@
+import type { NotificationUnsubscribe } from './email-body';
+/** A signed token that turns off `category` on `channel` for `userId`. */
+export declare function notificationUnsubscribeToken(userId: number, channel: UnsubscribeChannel, category?: string): string;
+/**
+ * Verify a token from {@link notificationUnsubscribeToken}. Null when it is
+ * malformed, not canonical base64url, for an unsupported channel, or not
+ * signed with this app's key. Signatures are compared in constant time.
+ */
+export declare function parseNotificationUnsubscribeToken(token: string): ParsedUnsubscribeToken | null;
+/**
+ * The `payload.unsubscribe` for one person: the page link (`?token=`), the
+ * one-click endpoint (`?token=`, so a mail client's form POST carries it),
+ * and the preferences page.
+ */
+export declare function notificationUnsubscribeLinks(userId: number, options?: UnsubscribeLinkOptions): NotificationUnsubscribe;
+/**
+ * The token an unsubscribe request carries. A page posts `{ token }` as JSON;
+ * a mail client's one-click button POSTs `List-Unsubscribe=One-Click` as a
+ * form to the `List-Unsubscribe` URL, so there it is in the query string.
+ */
+export declare function unsubscribeTokenFromRequest(request: { url: string, json?: () => Promise<any> }): Promise<string>;
+/**
+ * Verify a token and turn its preference off. Returns what was turned off,
+ * or null for an invalid token (answer 422).
+ */
+export declare function unsubscribeWithToken(token: string): Promise<ParsedUnsubscribeToken | null>;
+export declare interface ParsedUnsubscribeToken {
+  userId: number
+  channel: UnsubscribeChannel
+  category: string
+}
+export declare interface UnsubscribeLinkOptions {
+  channel?: UnsubscribeChannel
+  category?: string
+  baseUrl?: string
+  pagePath?: string
+  endpointPath?: string
+  preferencesPath?: string | false
+  notice?: string
+}
+/**
+ * Signed unsubscribe links for notification preferences.
+ *
+ * `@stacksjs/email` has its own unsubscribe tokens, which suppress an
+ * address in `email_suppressions` for good. These are for the softer and
+ * more common case: one person turning off one category on one channel
+ * (marketing email, say), the same row a settings page writes. The token
+ * names the user, channel and category and is signed with `APP_KEY`, so a
+ * link can only ever switch off what it was minted for.
+ *
+ * The format is `base64url("{userId}:{channel}:{category}:{hmac-sha256 hex}")`.
+ * It does not expire: an archived marketing email must still be able to
+ * unsubscribe, and the worst a leaked link can do is stop marketing.
+ */
+export type UnsubscribeChannel = 'email' | 'sms';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/notifications",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.137",
+  "version": "0.75.139",
   "description": "The Stacks notifications integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -64,18 +64,18 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@stacksjs/chat": "0.75.137",
-    "@stacksjs/cli": "0.75.137",
-    "@stacksjs/config": "0.75.137",
-    "@stacksjs/database": "0.75.137",
-    "@stacksjs/email": "0.75.137",
-    "@stacksjs/push": "0.75.137",
-    "@stacksjs/realtime": "0.75.137",
-    "@stacksjs/sms": "0.75.137"
+    "@stacksjs/chat": "0.75.139",
+    "@stacksjs/cli": "0.75.139",
+    "@stacksjs/config": "0.75.139",
+    "@stacksjs/database": "0.75.139",
+    "@stacksjs/email": "0.75.139",
+    "@stacksjs/push": "0.75.139",
+    "@stacksjs/realtime": "0.75.139",
+    "@stacksjs/sms": "0.75.139"
   },
   "devDependencies": {
-    "@stacksjs/error-handling": "0.75.137",
-    "@stacksjs/types": "0.75.137",
+    "@stacksjs/error-handling": "0.75.139",
+    "@stacksjs/types": "0.75.139",
     "better-dx": "^0.2.24"
   }
 }