@stacksjs/notifications 0.70.88 → 0.70.91

package/dist/drivers/broadcast.d.ts

@@ -0,0 +1,24 @@
+/** @defaultValue `{ send: () => Promise<unknown> }` */
+export declare const BroadcastNotificationDriver: {
+  /**
+   * Emit the notification over the realtime channel. Resolves with
+   * `delivered: false` (and a reason) when no realtime server is
+   * available rather than throwing — fire-and-forget is the right shape
+   * for a notification channel that ships transports best-effort.
+   */
+  send: (options: BroadcastNotificationOptions) => Promise<BroadcastNotificationResult>
+};
+/** Options accepted by the broadcast driver. */
+export declare interface BroadcastNotificationOptions {
+  channel?: string
+  userId?: number
+  event?: string
+  data?: Record<string, unknown>
+  private?: boolean
+}
+export declare interface BroadcastNotificationResult {
+  delivered: boolean
+  channel: string
+  event: string
+  reason?: string
+}

package/dist/drivers/chat.d.ts

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

package/dist/drivers/database.d.ts

@@ -0,0 +1,50 @@
+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>
+};
+// `./database-schema.d.ts` augments `@stacksjs/database`'s
+// `DatabaseSchema` with the `notifications` + `notification_preferences`
+// tables so the chain calls below type-check without per-call `as any`
+// (Notif-3 follow-up to #1923 / #1937).
+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, unknown>
+}
+/** Shape of a row-insert result across the supported drivers. */
+declare interface InsertResultLike {
+  insertId?: number | bigint
+  lastInsertRowid?: number | bigint
+  lastInsertId?: number | bigint
+}

package/dist/drivers/email.d.ts

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

package/dist/drivers/index.d.ts

@@ -0,0 +1,6 @@
+export * from './broadcast';
+export * from './chat';
+export * from './database';
+export * from './email';
+export * from './push';
+export * from './sms';

package/dist/drivers/push.d.ts

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

package/dist/drivers/sms.d.ts

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

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { BroadcastNotificationDriver } from './drivers/broadcast';
+import { chat, email, push, sms } from './drivers/index';
+import { DatabaseNotificationDriver } from './drivers/database';
+import { filterChannelsByPreferences } from './preferences';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+export type { BroadcastNotificationOptions, BroadcastNotificationResult } from './drivers/broadcast';
+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];
+/**
+ * Push transport — returns the `@stacksjs/push` namespace whose
+ * `send(to, notification, options)` dispatches to Expo or FCM based on
+ * `options.driver`. `notify()` calls it with the driver omitted so the
+ * push package's own default kicks in (`expo`). Apps that need to
+ * force FCM can call `push.send(...)` directly with `{ driver: 'fcm' }`.
+ *
+ * Previously the `'push'` switch arm in `notify()` threw a hardcoded
+ * "not yet wired into a default driver" error even though both drivers
+ * exist (stacksjs/stacks#1874 F-1) — this helper is the missing link.
+ */
+export declare function usePush(): typeof push;
+export declare function useDatabase(): typeof DatabaseNotificationDriver;
+/**
+ * Broadcast transport — returns the `BroadcastNotificationDriver` which
+ * fans out a notification payload over the realtime WebSocket layer
+ * (`@stacksjs/realtime` `emit()`). See {@link BroadcastNotificationDriver}
+ * for channel-naming rules. stacksjs/stacks#669.
+ */
+export declare function useBroadcast(): typeof BroadcastNotificationDriver;
+export declare function useNotification(typeParam?: string, driverParam?: string): ReturnType<typeof useEmail> | ReturnType<typeof useChat> | ReturnType<typeof useSMS> | typeof DatabaseNotificationDriver;
+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
+  pushTokens?: string | string[]
+  broadcastChannel?: string
+}
+export declare interface NotifyResult {
+  channel: NotificationChannel
+  success: boolean
+  error?: Error
+}
+export type NotificationChannel = 'email' | 'sms' | 'chat' | 'database' | 'push' | 'broadcast';
+export { BroadcastNotificationDriver } from './drivers/broadcast';
+export { DatabaseNotificationDriver } from './drivers/database';
+export {
+  bulkSetPreferences,
+  filterChannelsByPreferences,
+  getNotificationPreferences,
+  setNotificationPreference,
+} from './preferences';

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+var P=import.meta.require;import{log as _}from"@stacksjs/cli";import{notification as k}from"@stacksjs/config";import{mail as T}from"@stacksjs/email";import{log as q}from"@stacksjs/cli";var V={async send(z){let F=z.event??"notification",J=z.channel;if(!J)J=z.userId!==void 0?`private-user-${z.userId}`:"notifications";try{let G=await import("@stacksjs/realtime").catch(()=>null),K=G?.emit,O=G?.getServer;if(!K||!O)return{delivered:!1,channel:J,event:F,reason:"@stacksjs/realtime is not available"};if(!O())return{delivered:!1,channel:J,event:F,reason:"realtime server not running"};let Q=z.private??z.userId!==void 0;return K(J,F,z.data,{private:Q}),q.info(`[notifications] broadcast to '${J}' (${F})`),{delivered:!0,channel:J,event:F}}catch(G){let K=G instanceof Error?G.message:String(G);return q.warn(`[notifications] broadcast failed: ${K}`),{delivered:!1,channel:J,event:F,reason:K}}}};import*as x from"@stacksjs/chat";import{log as D}from"@stacksjs/cli";import{db as U}from"@stacksjs/database";var W={async send(z){let F=new Date().toISOString(),G=await U.insertInto("notifications").values({user_id:z.userId,type:z.type,data:JSON.stringify(z.data),read_at:null,created_at:F,updated_at:F}).execute(),K=Array.isArray(G)?G[0]:G,O=Number(K?.insertId??K?.lastInsertRowid??K?.lastInsertId??0);return D.info(`Database notification sent to user ${z.userId}: ${z.type}`),{id:O,user_id:z.userId,type:z.type,data:JSON.stringify(z.data),read_at:null,created_at:F,updated_at:F}},async getUserNotifications(z){return await U.selectFrom("notifications").selectAll().where("user_id","=",z).orderBy("created_at","desc").execute()},async getUnreadNotifications(z){return await U.selectFrom("notifications").selectAll().where("user_id","=",z).where("read_at","is",null).orderBy("created_at","desc").execute()},async markAsRead(z){await U.updateTable("notifications").set({read_at:new Date().toISOString()}).where("id","=",z).execute()},async markAllAsRead(z){await U.updateTable("notifications").set({read_at:new Date().toISOString()}).where("user_id","=",z).where("read_at","is",null).execute()},async unreadCount(z){let F=await U.selectFrom("notifications").select(U.fn.countAll().as("count")).where("user_id","=",z).where("read_at","is",null).executeTakeFirst();return Number(F?.count??0)},async deleteNotification(z){await U.deleteFrom("notifications").where("id","=",z).execute()},async deleteAllNotifications(z){await U.deleteFrom("notifications").where("user_id","=",z).execute()}};import*as M from"@stacksjs/push";import*as A from"@stacksjs/sms";import{log as S}from"@stacksjs/cli";import{db as X}from"@stacksjs/database";var Y="notification_preferences";async function $(z,F){let J=new Map;try{let G=X.selectFrom(Y).select(["channel","enabled","category"]).where("user_id","=",z);if(F!==void 0)G=G.where("category","=",F);let K=await G.execute();for(let O of K)J.set(O.channel,O.enabled===!0||O.enabled===1)}catch(G){S.debug?.(`[notifications] preferences lookup failed (table missing?): ${G.message}`)}return J}async function L(z,F,J,G){let K=new Date().toISOString(),O=G??null,Q=await X.selectFrom(Y).select(["id"]).where("user_id","=",z).where("channel","=",F).where("category",O===null?"is":"=",O).executeTakeFirst();if(Q?.id){await X.updateTable(Y).set({enabled:J,updated_at:K}).where("id","=",Q.id).execute();return}await X.insertInto(Y).values({user_id:z,channel:F,enabled:J,category:O,created_at:K,updated_at:K}).execute()}async function w(z,F){for(let J of F)await L(z,J.channel,J.enabled,J.category)}async function H(z,F,J){let G=await $(z,J);if(J!==void 0){let K=await $(z,void 0);for(let[O,Q]of K)if(!G.has(O))G.set(O,Q)}return F.filter((K)=>{let O=G.get(K);return O===void 0?!0:O===!0})}var m=k;function E(z){return x[z||"slack"]}function B(z){if(z)try{return T.use(z)}catch(F){_.warn(`[notifications] email driver '${z}' not registered \u2014 falling back to default mail singleton (${F.message})`)}return T}function j(z){return A[z||"twilio"]}function I(){return M}function g(){return W}function Kz(){return V}function b(z,F){let J=z||m?.default||"email",G=F;switch(J){case"email":return B(G);case"chat":return E(G);case"sms":return j(G);case"database":return g();default:throw Error(`Notification type "${J}" is not supported`)}}function C(z){return!!z&&typeof z==="object"&&"send"in z&&typeof z.send==="function"}async function Oz(z,F,J=["email"],G={}){let K=J;if(z.userId&&!G.ignorePreferences)try{K=await H(z.userId,J,G.category)}catch(Q){_.warn(`[notify] preferences filter failed, sending all channels: ${Q.message}`)}return(await Promise.allSettled(K.map(async(Q)=>{switch(Q){case"email":{if(!z.email)throw Error("[notify] email channel requires recipient.email");await B().send({to:z.email,subject:F.subject??"",text:F.body,html:`<p>${f(F.body)}</p>`});break}case"sms":{if(!z.phone)throw Error("[notify] sms channel requires recipient.phone");let R=j();if(!C(R))throw Error("[notify] sms channel is not configured: no usable SMS driver with a send() method");await R.send({to:z.phone,body:F.body});break}case"chat":{let R=E();if(!C(R))throw Error("[notify] chat channel is not configured: no usable chat driver with a send() method");await R.send({body:F.body});break}case"database":{if(!z.userId)throw Error("[notify] database channel requires recipient.userId");await W.send({userId:z.userId,type:F.subject||"notification",data:{body:F.body,...F.data}});break}case"push":{if(!z.pushTokens||Array.isArray(z.pushTokens)&&z.pushTokens.length===0)throw Error("[notify] push channel requires recipient.pushTokens");await I().send(z.pushTokens,{title:F.subject,body:F.body,data:F.data});break}case"broadcast":{await V.send({channel:z.broadcastChannel,userId:z.userId,event:F.subject??"notification",data:{body:F.body,...F.data}});break}default:throw Error(`Unsupported notification channel: ${Q}`)}}))).map((Q,R)=>{let Z=K[R];if(!Z)throw Error(`Missing notification channel for result ${R}`);if(Q.status==="rejected"){let N=Q.reason instanceof Error?Q.reason.message:String(Q.reason);_.warn(`[notify] ${Z} channel failed: ${N}`)}return{channel:Z,success:Q.status==="fulfilled",error:Q.status==="rejected"?Q.reason:void 0}})}function Qz(){return b()}function f(z){return String(z??"").replace(/[&<>"']/g,(F)=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"})[F])}export{j as useSMS,I as usePush,b as useNotification,B as useEmail,g as useDatabase,E as useChat,Kz as useBroadcast,L as setNotificationPreference,Oz as notify,Qz as notification,$ as getNotificationPreferences,H as filterChannelsByPreferences,w as bulkSetPreferences,W as DatabaseNotificationDriver,V as BroadcastNotificationDriver};

package/dist/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

@@ -2,7 +2,7 @@
   "name": "@stacksjs/notifications",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "The Stacks notifications integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -59,14 +59,14 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/chat": "0.70.88",
-    "@stacksjs/cli": "0.70.88",
-    "@stacksjs/config": "0.70.88",
+    "@stacksjs/chat": "0.70.91",
+    "@stacksjs/cli": "0.70.91",
+    "@stacksjs/config": "0.70.91",
     "better-dx": "^0.2.16",
-    "@stacksjs/email": "0.70.88",
-    "@stacksjs/error-handling": "0.70.88",
-    "@stacksjs/push": "0.70.88",
-    "@stacksjs/sms": "0.70.88",
-    "@stacksjs/types": "0.70.88"
+    "@stacksjs/email": "0.70.91",
+    "@stacksjs/error-handling": "0.70.91",
+    "@stacksjs/push": "0.70.91",
+    "@stacksjs/sms": "0.70.91",
+    "@stacksjs/types": "0.70.91"
   }
 }