@stacksjs/notifications 0.70.23 → 0.70.26

package/dist/index.js

@@ -1,2 +1,2 @@
 // @bun
-import m from"node:process";import{log as s}from"@stacksjs/cli";import{notification as r}from"@stacksjs/config";import{err as p}from"@stacksjs/error-handling";import{ExitCode as u}from"@stacksjs/types";import*as i from"@stacksjs/chat";import*as a from"@stacksjs/email";import*as k from"@stacksjs/push";import*as n from"@stacksjs/sms";function c(t="slack"){return i[t]}function l(t="mailtrap"){return a[t]}function x(t="twilio"){return n[t]}function y(t="email",f="mailtrap"){if(!r.default)return s.error("No default notification type set in config/notification.ts"),m.exit(u.InvalidArgument);let e=t||r.default,o=f||r.default;switch(e){case"email":return l(o);case"chat":return c(o);case"sms":return x(o);default:return p(`Type ${e} not supported`)}}function j(){return y()}export{x as useSMS,y as useNotification,l as useEmail,c as useChat,j as notification};
+import{log as Y}from"@stacksjs/cli";import{notification as A}from"@stacksjs/config";import{mail as M}from"@stacksjs/email";import*as $ from"@stacksjs/chat";import{log as C}from"@stacksjs/cli";import{db as R}from"@stacksjs/database";var U={async send(x){let z=new Date().toISOString(),F=await R.insertInto("notifications").values({user_id:x.userId,type:x.type,data:JSON.stringify(x.data),read_at:null,created_at:z,updated_at:z}).execute(),K=Number(F?.[0]?.insertId??F?.insertId??F?.lastInsertRowid??F?.lastInsertId??0);return C.info(`Database notification sent to user ${x.userId}: ${x.type}`),{id:K,user_id:x.userId,type:x.type,data:JSON.stringify(x.data),read_at:null,created_at:z,updated_at:z}},async getUserNotifications(x){return await R.selectFrom("notifications").selectAll().where("user_id","=",x).orderBy("created_at","desc").execute()},async getUnreadNotifications(x){return await R.selectFrom("notifications").selectAll().where("user_id","=",x).where("read_at","is",null).orderBy("created_at","desc").execute()},async markAsRead(x){await R.updateTable("notifications").set({read_at:new Date().toISOString()}).where("id","=",x).execute()},async markAllAsRead(x){await R.updateTable("notifications").set({read_at:new Date().toISOString()}).where("user_id","=",x).where("read_at","is",null).execute()},async unreadCount(x){let z=await R.selectFrom("notifications").select(R.fn.countAll().as("count")).where("user_id","=",x).where("read_at","is",null).executeTakeFirst();return Number(z?.count??0)},async deleteNotification(x){await R.deleteFrom("notifications").where("id","=",x).execute()},async deleteAllNotifications(x){await R.deleteFrom("notifications").where("user_id","=",x).execute()}};import*as g from"@stacksjs/email";import*as v from"@stacksjs/push";import*as H from"@stacksjs/sms";import{log as E}from"@stacksjs/cli";import{db as _}from"@stacksjs/database";var V="notification_preferences";async function W(x,z){let G=new Map;try{let F=_.selectFrom(V).select(["channel","enabled","category"]).where("user_id","=",x);if(z!==void 0)F=F.where("category","=",z);let K=await F.execute();for(let Q of K)G.set(Q.channel,Q.enabled===!0||Q.enabled===1)}catch(F){E.debug?.(`[notifications] preferences lookup failed (table missing?): ${F.message}`)}return G}async function q(x,z,G,F){let K=new Date().toISOString(),Q=F??null,J=_,O=await J.selectFrom(V).select(["id"]).where("user_id","=",x).where("channel","=",z).where("category",Q===null?"is":"=",Q).executeTakeFirst();if(O?.id){await J.updateTable(V).set({enabled:G,updated_at:K}).where("id","=",O.id).execute();return}await J.insertInto(V).values({user_id:x,channel:z,enabled:G,category:Q,created_at:K,updated_at:K}).execute()}async function j(x,z){for(let G of z)await q(x,G.channel,G.enabled,G.category)}async function X(x,z,G){let F=await W(x,G);if(G!==void 0){let K=await W(x,void 0);for(let[Q,J]of K)if(!F.has(Q))F.set(Q,J)}return z.filter((K)=>{let Q=F.get(K);return Q===void 0?!0:Q===!0})}var D=A;function L(x){return $[x||"slack"]}function T(x){if(x)try{return M.use(x)}catch(z){Y.warn(`[notifications] email driver '${x}' not registered \u2014 falling back to default mail singleton (${z.message})`)}return M}function m(x){return H[x||"twilio"]}function N(){return U}function S(x,z){let G=x||D?.default||"email",F=z;switch(G){case"email":return T(F);case"chat":return L(F);case"sms":return m(F);case"database":return N();default:throw Error(`Notification type "${G}" is not supported`)}}async function Gx(x,z,G=["email"],F={}){let K=G;if(x.userId&&!F.ignorePreferences)try{K=await X(x.userId,G,F.category)}catch(J){Y.warn(`[notify] preferences filter failed, sending all channels: ${J.message}`)}return(await Promise.allSettled(K.map(async(J)=>{switch(J){case"email":{if(!x.email)throw Error("[notify] email channel requires recipient.email");await T().send({to:x.email,subject:z.subject,text:z.body,html:`<p>${P(z.body)}</p>`});break}case"sms":{let O=m();if(O&&typeof O==="object"&&"send"in O){if(!x.phone)throw Error("[notify] sms channel requires recipient.phone");await O.send({to:x.phone,body:z.body})}break}case"chat":{let O=L();if(O&&typeof O==="object"&&"send"in O)await O.send({body:z.body});break}case"database":{if(!x.userId)throw Error("[notify] database channel requires recipient.userId");await U.send({userId:x.userId,type:z.subject||"notification",data:{body:z.body,...z.data}});break}case"push":throw Error("[notify] push channel is filtered by preferences but not yet wired into a default driver");default:throw Error(`Unsupported notification channel: ${J}`)}}))).map((J,O)=>{let Z=K[O];if(J.status==="rejected"){let B=J.reason instanceof Error?J.reason.message:String(J.reason);Y.warn(`[notify] ${Z} channel failed: ${B}`)}return{channel:Z,success:J.status==="fulfilled",error:J.status==="rejected"?J.reason:void 0}})}function Jx(){return S()}function P(x){return String(x??"").replace(/[&<>"']/g,(z)=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"})[z])}export{m as useSMS,S as useNotification,T as useEmail,N as useDatabase,L as useChat,q as setNotificationPreference,Gx as notify,Jx as notification,W as getNotificationPreferences,X as filterChannelsByPreferences,j as bulkSetPreferences,U as DatabaseNotificationDriver};

package/dist/src/drivers/database.d.ts

@@ -0,0 +1,40 @@
+export declare function useDatabase(): typeof DatabaseNotificationDriver;
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   send: () => unknown,
+ *   getUserNotifications: () => unknown,
+ *   getUnreadNotifications: () => unknown,
+ *   markAsRead: () => unknown,
+ *   markAllAsRead: () => unknown,
+ *   unreadCount: () => unknown,
+ *   deleteNotification: () => unknown,
+ *   deleteAllNotifications: () => unknown
+ * }
+ * ```
+ */
+export declare const DatabaseNotificationDriver: {
+  send: (options: CreateNotificationOptions) => Promise<DatabaseNotification>;
+  getUserNotifications: (userId: number) => Promise<DatabaseNotification[]>;
+  getUnreadNotifications: (userId: number) => Promise<DatabaseNotification[]>;
+  markAsRead: (id: number) => Promise<void>;
+  markAllAsRead: (userId: number) => Promise<void>;
+  unreadCount: (userId: number) => Promise<number>;
+  deleteNotification: (id: number) => Promise<void>;
+  deleteAllNotifications: (userId: number) => Promise<void>
+};
+export declare interface DatabaseNotification {
+  id: number
+  user_id: number
+  type: string
+  data: string
+  read_at: string | null
+  created_at: string
+  updated_at: string | null
+}
+export declare interface CreateNotificationOptions {
+  userId: number
+  type: string
+  data: Record<string, any>
+}

package/dist/src/index.d.ts

@@ -0,0 +1,87 @@
+import { chat, email, sms } from './drivers';
+import { DatabaseNotificationDriver } from './drivers/database';
+import { filterChannelsByPreferences } from './preferences';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+export type { CreateNotificationOptions, DatabaseNotification } from './drivers/database';
+export type { NotificationPreferenceRow, PreferenceChannel } from './preferences';
+export declare function useChat(driver?: string): typeof chat[keyof typeof chat];
+/**
+ * Return the email transport — by default the @stacksjs/email Mail
+ * singleton, which lazy-resolves its driver from `config.email.default`
+ * (so `MAIL_MAILER=log` in dev / `ses` in prod just works). Pass an
+ * explicit driver name to scope to a specific transport — useful in
+ * tests that want to assert against `LogEmailDriver` specifically without
+ * touching the global config.
+ *
+ * Earlier this function returned the *driver namespace* (e.g.
+ * `{ SESDriver, default }`), which has no `send`. The `'send' in driver`
+ * guard in `notify()` was always false, so the email channel silently
+ * no-op'd for every booking confirmation, host alert, etc.
+ */
+export declare function useEmail(driver?: string): EmailTransport;
+export declare function useSMS(driver?: string): typeof sms[keyof typeof sms];
+export declare function useDatabase(): typeof DatabaseNotificationDriver;
+export declare function useNotification(typeParam?: string, driverParam?: string): typeof chat[keyof typeof chat] | typeof email[keyof typeof email] | typeof sms[keyof typeof sms] | typeof DatabaseNotificationDriver;
+/**
+ * Send a notification through multiple channels simultaneously.
+ * Uses Promise.allSettled so one channel failure doesn't block others.
+ *
+ * When `recipient.userId` is set and `options.ignorePreferences` is not
+ * `true`, the channel list is first filtered through the user's
+ * `notification_preferences` rows — any channel they've explicitly
+ * disabled is silently skipped. Channels with no preference recorded fall
+ * through as enabled (default-allow), so introducing this feature doesn't
+ * regress notifications for users who haven't visited the preferences UI.
+ *
+ * For transactional notifications that must always go out (password
+ * resets, security alerts, billing failures), pass
+ * `{ ignorePreferences: true }`.
+ *
+ * @example
+ * ```ts
+ * // respects user preferences
+ * await notify({ userId: 7, email: 'a@x' }, { body: 'New message' }, ['email', 'sms'])
+ *
+ * // bypasses preferences (security alert)
+ * await notify({ userId: 7, email: 'a@x' }, { body: 'New login' }, ['email'], { ignorePreferences: true })
+ *
+ * // category-specific opt-out
+ * await notify({ userId: 7, email: 'a@x' }, { body: 'Sale!' }, ['email'], { category: 'marketing' })
+ * ```
+ */
+export declare function notify(recipient: NotificationRecipient, payload: NotificationPayload, channels?: NotificationChannel[], options?: NotifyOptions): Promise<NotifyResult[]>;
+export declare function notification(): ReturnType<typeof useNotification>;
+/** Optional flags accepted by {@link notify}. */
+export declare interface NotifyOptions {
+  ignorePreferences?: boolean
+  category?: string
+}
+/** Minimal transport contract used by `notify()` — anything that exposes a
+ *  `send(EmailMessage)` returning an `EmailResult` works (the @stacksjs/email
+ *  Mail singleton, a per-test LogEmailDriver, a custom mock, etc.). */
+export declare interface EmailTransport {
+  send: (message: EmailMessage) => Promise<EmailResult>
+}
+export declare interface NotificationPayload {
+  subject?: string
+  body: string
+  data?: Record<string, unknown>
+}
+export declare interface NotificationRecipient {
+  email?: string
+  phone?: string
+  userId?: number
+}
+export declare interface NotifyResult {
+  channel: NotificationChannel
+  success: boolean
+  error?: Error
+}
+export type NotificationChannel = 'email' | 'sms' | 'chat' | 'database' | 'push';
+export { DatabaseNotificationDriver } from './drivers/database';
+export {
+  bulkSetPreferences,
+  filterChannelsByPreferences,
+  getNotificationPreferences,
+  setNotificationPreference,
+} from './preferences';

package/dist/src/preferences.d.ts

@@ -0,0 +1,106 @@
+import type { NotificationChannel } from './index';
+/**
+ * Load all notification preferences for a user as a Map keyed by channel.
+ * Returns `Map<channel, enabled>` — channels with no row recorded are
+ * absent from the Map (callers should treat absent = enabled by default).
+ *
+ * If the `notification_preferences` table doesn't exist yet (apps that
+ * haven't applied the migration) this returns an empty Map and logs a
+ * one-line debug message rather than throwing — the user-facing notify()
+ * flow shouldn't 500 because of an opt-in feature.
+ *
+ * @example
+ * ```ts
+ * const prefs = await getNotificationPreferences(user.id)
+ * if (prefs.get('email') === false) console.log('user opted out of email')
+ * ```
+ */
+export declare function getNotificationPreferences(userId: number, category?: string): Promise<Map<PreferenceChannel, boolean>>;
+/**
+ * Upsert a single preference row for `(user_id, channel, category)`.
+ * The combination is treated as the natural key — calling this twice with
+ * the same triple just toggles `enabled` on the existing row.
+ *
+ * @example
+ * ```ts
+ * // user opts out of marketing emails
+ * await setNotificationPreference(user.id, 'email', false, 'marketing')
+ * // ...later, opts back in
+ * await setNotificationPreference(user.id, 'email', true, 'marketing')
+ * ```
+ */
+export declare function setNotificationPreference(userId: number, channel: PreferenceChannel, enabled: boolean, category?: string): Promise<void>;
+/**
+ * Bulk upsert preferences for a user — convenient for "save preferences"
+ * forms that submit the user's full opt-in/out matrix in one POST.
+ *
+ * Iterates one upsert per entry rather than one mega-query because the
+ * underlying conflict logic is keyed on `(user_id, channel, category)`
+ * and a single SQL statement can't express that across N rows portably.
+ *
+ * @example
+ * ```ts
+ * await bulkSetPreferences(user.id, [
+ *   { channel: 'email', enabled: false, category: 'marketing' },
+ *   { channel: 'sms',   enabled: true },
+ *   { channel: 'push',  enabled: false },
+ * ])
+ * ```
+ */
+export declare function bulkSetPreferences(userId: number, prefs: Array<{ channel: PreferenceChannel, enabled: boolean, category?: string }>): Promise<void>;
+/**
+ * Filter a list of channels through a user's preferences.
+ *
+ * Returns the subset the user is opted *in* for. Channels with no row
+ * recorded fall through as enabled (default-allow) so that introducing
+ * the preferences feature doesn't suddenly break notifications for users
+ * who never visited the preferences page.
+ *
+ * @example
+ * ```ts
+ * const allowed = await filterChannelsByPreferences(user.id, ['email', 'sms', 'push'])
+ * // -> ['email', 'push']  (user disabled sms)
+ * ```
+ */
+export declare function filterChannelsByPreferences<T extends PreferenceChannel>(userId: number, channels: T[], category?: string): Promise<T[]>;
+/**
+ * `notification_preferences` table — user-level opt-out per channel
+ * (and optionally per category, e.g. `marketing` vs `system`).
+ *
+ * The migration is intentionally NOT shipped here — apps maintain their
+ * own migration directory and column conventions. Generate the migration
+ * yourself; the schema below is what the runtime expects.
+ *
+ * ```sql
+ * CREATE TABLE notification_preferences (
+ *   id           INTEGER PRIMARY KEY AUTOINCREMENT,
+ *   user_id      INTEGER NOT NULL,
+ *   channel      TEXT    NOT NULL,                  -- email | sms | chat | database | push
+ *   enabled      INTEGER NOT NULL DEFAULT 1,        -- boolean (0/1)
+ *   category     TEXT,                              -- optional, e.g. 'marketing'
+ *   created_at   TEXT    NOT NULL,
+ *   updated_at   TEXT    NOT NULL,
+ *   UNIQUE (user_id, channel, category)
+ * );
+ *
+ * CREATE INDEX idx_notification_preferences_user
+ *   ON notification_preferences (user_id);
+ * ```
+ *
+ * Postgres / MySQL equivalents: use `BOOLEAN` for `enabled`, `BIGINT` for
+ * IDs, and `TIMESTAMP` for the timestamp columns. The `UNIQUE (user_id,
+ * channel, category)` constraint is what makes the upsert below safe; if
+ * your DB doesn't allow `NULL` to participate in `UNIQUE`, treat
+ * `category IS NULL` as a sentinel "global" category instead.
+ */
+export declare interface NotificationPreferenceRow {
+  id: number
+  user_id: number
+  channel: NotificationChannel | 'push'
+  enabled: boolean | 0 | 1
+  category?: string | null
+  created_at: string
+  updated_at: string
+}
+/** All channels that can be filtered through preferences. */
+export type PreferenceChannel = NotificationChannel | 'push';

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/notifications",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.26",
   "description": "The Stacks notifications integration.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/notifications#readme",
@@ -31,29 +33,35 @@
   ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/chat": "0.70.22",
-    "@stacksjs/cli": "0.70.22",
-    "@stacksjs/config": "0.70.22",
-    "@stacksjs/development": "0.70.22",
-    "@stacksjs/email": "0.70.22",
-    "@stacksjs/error-handling": "0.70.22",
-    "@stacksjs/push": "0.70.22",
-    "@stacksjs/sms": "0.70.22",
-    "@stacksjs/types": "0.70.22"
+    "@stacksjs/chat": "0.70.23",
+    "@stacksjs/cli": "0.70.23",
+    "@stacksjs/config": "0.70.23",
+    "better-dx": "^0.2.12",
+    "@stacksjs/email": "0.70.23",
+    "@stacksjs/error-handling": "0.70.23",
+    "@stacksjs/push": "0.70.23",
+    "@stacksjs/sms": "0.70.23",
+    "@stacksjs/types": "0.70.23"
   }
 }

package/dist/chat.d.ts

@@ -1 +0,0 @@
-export * as chat from '@stacksjs/chat'

package/dist/config.d.ts

@@ -1,3 +0,0 @@
-export default {
-  purgeCSS: {},
-};

package/dist/email.d.ts

@@ -1 +0,0 @@
-export * as email from '@stacksjs/email'

package/dist/index.d.ts

@@ -1,5 +0,0 @@
-export declare function useChat(driver): any;
-export declare function useEmail(driver): any;
-export declare function useSMS(driver): any;
-export declare function useNotification(typeParam, driverParam): any;
-export declare function notification(): any;

package/dist/push.d.ts

@@ -1 +0,0 @@
-export * as push from '@stacksjs/push'

package/dist/sms.d.ts

@@ -1 +0,0 @@
-export * as sms from '@stacksjs/sms'

package/dist/tailwind.config.d.ts

@@ -1,34 +0,0 @@
-export default {
-  theme: {
-    screens: {
-      sm: '480px',
-      md: '768px',
-      lg: '976px',
-      xl: '1440px',
-    },
-    colors: {
-      'blue': '#1fb6ff',
-      'purple': '#7e5bef',
-      'pink': '#ff49db',
-      'orange': '#ff7849',
-      'green': '#13ce66',
-      'yellow': '#ffc82c',
-      'gray-dark': '#273444',
-      'gray': '#8492a6',
-      'gray-light': '#d3dce6',
-    },
-    fontFamily: {
-      sans: ['Graphik', 'sans-serif'],
-      serif: ['Merriweather', 'serif'],
-    },
-    extend: {
-      spacing: {
-        128: '32rem',
-        144: '36rem',
-      },
-      borderRadius: {
-        '4xl': '2rem',
-      },
-    },
-  },
-};