@stacksjs/notifications 0.70.86 → 0.70.88

package/package.json

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

package/dist/drivers/broadcast.d.ts

@@ -1,24 +0,0 @@
-/** @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

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

package/dist/drivers/database.d.ts

@@ -1,50 +0,0 @@
-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

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

package/dist/drivers/index.d.ts

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

package/dist/drivers/push.d.ts

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

package/dist/drivers/sms.d.ts

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

package/dist/index.d.ts

@@ -1,84 +0,0 @@
-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

@@ -1,2 +0,0 @@
-// @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

@@ -1,106 +0,0 @@
-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';