@stacksjs/notifications 0.70.44 → 0.70.53

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

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

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

@@ -0,0 +1,33 @@
+/**
+ * @defaultValue
+ * ```ts
+ * {
+ *   send: (options?: BroadcastNotificationOptions): Promise<BroadcastNotificationResult> {
+ *     const event) => Promise<(null)
+ *       const emit = (mod as { emit?: (channel: string, event: string, data?: unknown, options?: { private?: boolean })) => any>
+ * }
+ * ```
+ */
+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/src/drivers/database.d.ts

@@ -24,6 +24,10 @@ export declare const DatabaseNotificationDriver: {
   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
@@ -36,5 +40,5 @@ export declare interface DatabaseNotification {
 export declare interface CreateNotificationOptions {
   userId: number
   type: string
-  data: Record<string, any>
+  data: Record<string, unknown>
 }

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

@@ -1,3 +1,4 @@
+export * from './broadcast';
 export * from './chat';
 export * from './database';
 export * from './email';

package/dist/src/index.d.ts

@@ -1,7 +1,9 @@
-import { chat, email, sms } from './drivers/index';
+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];
@@ -20,35 +22,27 @@ export declare function useChat(driver?: string): typeof chat[keyof typeof chat]
  */
 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'])
+ * 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' }`.
  *
- * // 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' })
- * ```
+ * 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): typeof chat[keyof typeof chat] | typeof email[keyof typeof email] | typeof sms[keyof typeof sms] | 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}. */
@@ -71,13 +65,16 @@ 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';
+export type NotificationChannel = 'email' | 'sms' | 'chat' | 'database' | 'push' | 'broadcast';
+export { BroadcastNotificationDriver } from './drivers/broadcast';
 export { DatabaseNotificationDriver } from './drivers/database';
 export {
   bulkSetPreferences,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/notifications",
   "type": "module",
-  "version": "0.70.44",
+  "version": "0.70.53",
   "description": "The Stacks notifications integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -54,14 +54,14 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@stacksjs/chat": "^0.70.44",
-    "@stacksjs/cli": "^0.70.44",
-    "@stacksjs/config": "^0.70.44",
+    "@stacksjs/chat": "0.70.53",
+    "@stacksjs/cli": "0.70.53",
+    "@stacksjs/config": "0.70.53",
     "better-dx": "^0.2.12",
-    "@stacksjs/email": "^0.70.44",
-    "@stacksjs/error-handling": "^0.70.44",
-    "@stacksjs/push": "^0.70.44",
-    "@stacksjs/sms": "^0.70.44",
-    "@stacksjs/types": "^0.70.44"
+    "@stacksjs/email": "0.70.53",
+    "@stacksjs/error-handling": "0.70.53",
+    "@stacksjs/push": "0.70.53",
+    "@stacksjs/sms": "0.70.53",
+    "@stacksjs/types": "0.70.53"
   }
 }