@stacksjs/defaults 0.75.137 → 0.75.138

package/ai/skills/stacks-native/CATALOG.md

@@ -63,7 +63,7 @@ Browser runtime bindings are documented separately in `stacks-auto-imports`.
 | `@stacksjs/mobile` | [`stacks-mobile`](../stacks-mobile/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/mobile/src/index.ts) | 12 |
 | `@stacksjs/model-meta` | [`stacks-models`](../stacks-models/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/model-meta/src/index.ts) | 1 |
 | `@stacksjs/newsletter` | [`stacks-newsletter`](../stacks-newsletter/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/newsletter/src/index.ts) | 7 |
-| `@stacksjs/notifications` | [`stacks-notifications`](../stacks-notifications/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts) | 11 |
+| `@stacksjs/notifications` | [`stacks-notifications`](../stacks-notifications/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts) | 12 |
 | `@stacksjs/objects` | [`stacks-objects`](../stacks-objects/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/objects/src/index.ts) | 4 |
 | `@stacksjs/orm` | [`stacks-orm`](../stacks-orm/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/orm/src/index.ts) | 60 |
 | `@stacksjs/pagination` | [`stacks-pagination`](../stacks-pagination/SKILL.md) | [entrypoint](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/pagination/src/index.ts) | 0 |
@@ -607,11 +607,11 @@ Evidence directory: [7 retained tests](https://github.com/stacksjs/stacks/blob/m
 
 Guidance: [`stacks-notifications`](../stacks-notifications/SKILL.md). Source: [storage/framework/core/notifications/src/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/index.ts).
 
-Declared runtime exports: `BroadcastNotificationDriver`, `DatabaseNotificationDriver`, `bulkSetPreferences`, `emailParagraphs`, `ensureSuccessfulEmailResult`, `ensureSuccessfulNotificationResults`, `filterChannelsByPreferences`, `getNotificationPreferences`, `makeDeliveryRecord`, `notification`, `notificationChannel`, `notificationEmailHtml`, `notificationEmailText`, `notify`, `recordNotificationDelivery`, `resolveDeliveryRecipient`, `setNotificationPreference`, `useBroadcast`, `useChat`, `useDatabase`, `useEmail`, `useNotification`, `usePush`, `useSMS`, `wherePreferenceCategory`.
+Declared runtime exports: `BroadcastNotificationDriver`, `DEFAULT_SMS_OPT_OUT`, `DEFAULT_UNSUBSCRIBE_NOTICE`, `DatabaseNotificationDriver`, `bulkSetPreferences`, `emailParagraphs`, `ensureSuccessfulEmailResult`, `ensureSuccessfulNotificationResults`, `filterChannelsByPreferences`, `getNotificationPreferences`, `listUnsubscribeHeaders`, `makeDeliveryRecord`, `notification`, `notificationChannel`, `notificationEmailHtml`, `notificationEmailMessage`, `notificationEmailText`, `notificationSmsBody`, `notificationUnsubscribeLinks`, `notificationUnsubscribeToken`, `notify`, `parseNotificationUnsubscribeToken`, `recordNotificationDelivery`, `resolveDeliveryRecipient`, `setNotificationPreference`, `unsubscribeTokenFromRequest`, `unsubscribeWithToken`, `useBroadcast`, `useChat`, `useDatabase`, `useEmail`, `useNotification`, `usePush`, `useSMS`, `wherePreferenceCategory`.
 
-Local source modules: [src/delivery.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/delivery.ts), [src/drivers/broadcast.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/broadcast.ts), [src/drivers/database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/database.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/index.ts), [src/email-body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/email-body.ts), [src/preferences.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/preferences.ts).
+Local source modules: [src/delivery.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/delivery.ts), [src/drivers/broadcast.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/broadcast.ts), [src/drivers/database.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/database.ts), [src/drivers/index.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/drivers/index.ts), [src/email-body.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/email-body.ts), [src/preferences.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/preferences.ts), [src/unsubscribe.ts](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/src/unsubscribe.ts).
 
-Evidence directory: [11 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
+Evidence directory: [12 retained tests](https://github.com/stacksjs/stacks/blob/main/storage/framework/core/notifications/tests). These files are evidence pointers, not a claim that all tests were run for this catalog.
 
 ### @stacksjs/objects
 

package/ai/skills/stacks-notifications/SKILL.md

@@ -78,6 +78,44 @@ missing optional schema compatibility from real persistence failures. Apply
 model-driven migrations before relying on persistence. Inspect channel results
 and transport results rather than assuming a delivery log is provider proof.
 
+## Marketing: unsubscribe links and opt-out lines
+
+Give a marketing notification `payload.unsubscribe`, built per person with
+`notificationUnsubscribeLinks(userId, { notice })`:
+
+```ts
+await notify(
+  { userId, email },
+  { subject, body, unsubscribe: notificationUnsubscribeLinks(userId, { notice: 'You get these because marketing email is on.' }) },
+  ['email'],
+  { category: 'marketing' },
+)
+```
+
+The email's footer then shows the notice, **Unsubscribe** (`url`, default
+`{APP_URL}/unsubscribe?token=`) and **Email preferences** (`/settings`) instead
+of "do not reply"; the text part spells the link out; and the message carries
+`List-Unsubscribe: <oneClickUrl>` plus `List-Unsubscribe-Post:
+List-Unsubscribe=One-Click` (RFC 8058, default
+`{APP_URL}/api/notifications/unsubscribe?token=`). `payload.headers` adds
+other headers. The pure builders are `notificationEmailMessage`,
+`notificationEmailHtml`, `notificationEmailText` and `listUnsubscribeHeaders`.
+
+The token (`notificationUnsubscribeToken`, `parseNotificationUnsubscribeToken`)
+is `base64url("{userId}:{channel}:{category}:{hmac}")` signed with `APP_KEY`,
+which must be set in production. It does not expire. It turns off one
+preference (channel + category), unlike `@stacksjs/email`'s tokens, which
+suppress an address for good. The app owns the page and the route; the route's
+handler is `unsubscribeWithToken(await unsubscribeTokenFromRequest(request))`,
+which reads the query string (one-click form POSTs) before a JSON body, and
+answers 422 when it returns null. Ask before unsubscribing on the page, so a
+link scanner opening the URL changes nothing.
+
+A `marketing` text ends with "Reply STOP to opt out." (`notificationSmsBody`).
+`payload.smsOptOut` replaces the line (and adds it to other categories), and
+`false` leaves it out. STOP only becomes an opt-out the app sees when inbound
+SMS is wired up; see `stacks-sms`.
+
 ## Channel factories
 
 - `useEmail(driver?)` returns a sendable transport. Without a driver it uses

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.137",
+  "version": "0.75.138",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.137",
+  "version": "0.75.138",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,7 +55,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "0.75.137",
+    "@stacksjs/mobile": "0.75.138",
     "@stacksjs/sanitizer": "^0.2.422",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",

package/resources/emails/notification.stx

@@ -4,7 +4,8 @@
 // breaks kept, addresses as links) and, when the notification names one, a
 // button to where it happened. Same <EmailLayout> as the other prebaked
 // mailers (stacksjs/stacks#1901); an app's own resources/emails/notification
-// wins over this one.
+// wins over this one. A notification with `unsubscribe` (marketing) says why
+// it came and links to Unsubscribe in the footer instead of "do not reply".
 const appName = props.appName || 'Stacks'
 const primaryColor = props.primaryColor || '#3451b2'
 const subject = props.subject || appName
@@ -12,6 +13,9 @@ const paragraphs = Array.isArray(props.paragraphs) ? props.paragraphs : []
 const actionUrl = props.actionUrl || ''
 const actionLabel = props.actionLabel || 'Open'
 const preheader = props.preheader || ''
+const unsubscribeUrl = props.unsubscribeUrl || ''
+const unsubscribeNotice = props.unsubscribeNotice || 'You are receiving this because these emails are turned on in your settings.'
+const preferencesUrl = props.preferencesUrl || ''
 const year = props.year || new Date().getFullYear()
 </script>
 
@@ -36,7 +40,12 @@ const year = props.year || new Date().getFullYear()
   <template #footer>
     <tr>
       <td style="padding:20px 40px;background-color:#f9fafb;border-top:1px solid #e5e7eb;">
-        <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">This is an automated message from {{ appName }}. Please do not reply to this email.</p>
+        @if(unsubscribeUrl)
+          <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">{{ unsubscribeNotice }}</p>
+          <p style="margin:8px 0 0 0;color:#6b7280;font-size:12px;text-align:center;"><a href="{{ unsubscribeUrl }}" style="color:#6b7280;text-decoration:underline;">Unsubscribe</a>@if(preferencesUrl) &middot; <a href="{{ preferencesUrl }}" style="color:#6b7280;text-decoration:underline;">Email preferences</a>@endif</p>
+        @else
+          <p style="margin:0;color:#6b7280;font-size:12px;text-align:center;">This is an automated message from {{ appName }}. Please do not reply to this email.</p>
+        @endif
         <p style="margin:10px 0 0 0;color:#9ca3af;font-size:11px;text-align:center;">&copy; {{ year }} {{ appName }}. All rights reserved.</p>
       </td>
     </tr>