@arkstack/notifications 0.18.12 → 0.19.0

package/dist/index.d.ts

@@ -8,6 +8,83 @@ import { User as User$1 } from "@arkstack/auth";
 import { Attachment } from "nodemailer/lib/mailer/index.js";
 import { PhoneNumber } from "@kanun-hq/plugin-phone";
 import { ArkormCollection, LengthAwarePaginator } from "arkormx";
+//#region src/drivers/realtime/FirebaseDatabaseRealtimeDriver.d.ts
+/**
+ * Encode a channel name into a single Realtime Database key.
+ *
+ * @param channel
+ * @returns
+ */
+declare const firebaseChannelKey: (channel: string) => string;
+/**
+ * Broadcasts over [Firebase Realtime Database](https://firebase.google.com/docs/database).
+ *
+ * Each event is written to `{root}/{channel}/{key}` as `{ event, payload, at }`,
+ * and indexed under `{index_root}/{key}` so {@link prune} can clear old events in
+ * bounded batches. Clients sign in with a custom token from {@link auth}, which
+ * also writes a time-limited grant to `{grants_root}/{uid}/{channel}` that the
+ * database security rules check before allowing a read.
+ *
+ * `firebase-admin` is an optional peer dependency, imported lazily.
+ */
+declare class FirebaseDatabaseRealtimeDriver implements RealtimeDriver {
+  private options;
+  private servicesPromise?;
+  constructor(options?: FirebaseDatabaseTransportConfig);
+  private get root();
+  private get indexRoot();
+  private get grantsRoot();
+  private get databaseURL();
+  private services;
+  /**
+   * Write the event to every channel in one multi-path update.
+   *
+   * `delivery` is accepted for contract parity and ignored.
+   *
+   * @param channel
+   * @param event
+   * @param payload
+   * @param _delivery
+   * @returns
+   */
+  broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, _delivery?: RealtimeDeliveryOptions): Promise<string[]>;
+  /**
+   * Grant `uid` read access to an already authorized channel and mint the
+   * custom token the client signs in with.
+   *
+   * @param uid
+   * @param channel
+   * @returns
+   */
+  auth(uid: string, channel: string): Promise<{
+    token: string;
+    expires_at: number;
+  }>;
+  /**
+   * Delete events older than `maxAgeSeconds`, at most `limit` per call. Call it
+   * from a scheduled job until it returns 0.
+   *
+   * @param maxAgeSeconds
+   * @param limit
+   * @returns The number of events deleted.
+   */
+  prune(maxAgeSeconds: number, limit?: number): Promise<number>;
+  /**
+   * Public settings a browser client needs to read channels.
+   *
+   * @returns
+   */
+  clientConfig(): Record<string, unknown>;
+  /**
+   * Use `Broadcast.routes()`, which authorizes channels through the registry.
+   *
+   * @param _authEndpoint
+   * @param _middleware
+   * @param _channelPrefix
+   */
+  registerAuthRoute(_authEndpoint?: string, _middleware?: unknown | unknown[], _channelPrefix?: string): Promise<void>;
+}
+//#endregion
 //#region src/drivers/realtime/FirebaseRealtimeDriver.d.ts
 /**
  * The outcome of a token multicast: totals plus the tokens FCM rejected as dead.
@@ -88,6 +165,13 @@ declare class FirebaseRealtimeDriver implements RealtimeDriver {
    * @returns
    */
   private headerBlock;
+  /**
+   * Public Firebase web settings for clients that receive messages or register
+   * device tokens.
+   *
+   * @returns
+   */
+  clientConfig(): Record<string, unknown>;
   /**
    * Firebase channels do not require server-side authorization.
    *
@@ -120,6 +204,53 @@ declare class FirebaseRealtimeDriver implements RealtimeDriver {
   private multicast;
 }
 //#endregion
+//#region src/drivers/realtime/MemoryRealtimeDriver.d.ts
+/**
+ * A broadcast recorded by {@link MemoryRealtimeDriver}.
+ */
+interface RecordedBroadcast {
+  channel: string | string[];
+  event: string;
+  payload: RealtimeBroadcastPayload;
+  delivery?: RealtimeDeliveryOptions;
+}
+/**
+ * Records every broadcast in process instead of sending it, for tests and local
+ * development. Read them with {@link MemoryRealtimeDriver.broadcasts}.
+ */
+declare class MemoryRealtimeDriver implements RealtimeDriver {
+  /**
+   * Every broadcast recorded since the last {@link clear}.
+   *
+   * @returns
+   */
+  static broadcasts(): RecordedBroadcast[];
+  /**
+   * Forget all recorded broadcasts.
+   */
+  static clear(): void;
+  broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, delivery?: RealtimeDeliveryOptions): Promise<void>;
+  auth(_socketId: string, channel: string): Promise<{
+    auth: string;
+  }>;
+  registerAuthRoute(): Promise<void>;
+  clientConfig(): Record<string, unknown>;
+}
+//#endregion
+//#region src/drivers/realtime/PollingRealtimeDriver.d.ts
+/**
+ * A transport that pushes nothing. Clients are told to poll on an interval
+ * instead, so an app works without realtime infrastructure.
+ */
+declare class PollingRealtimeDriver implements RealtimeDriver {
+  private options;
+  constructor(options?: PollingTransportConfig);
+  broadcast(_channel: string | string[], _event: string, _payload: RealtimeBroadcastPayload, _delivery?: RealtimeDeliveryOptions): Promise<void>;
+  auth(): Promise<Record<string, never>>;
+  registerAuthRoute(): Promise<void>;
+  clientConfig(): Record<string, unknown>;
+}
+//#endregion
 //#region src/drivers/realtime/PusherRealtimeDriver.d.ts
 /** The slice of the `pusher` server SDK this driver uses. */
 interface PusherClient {
@@ -146,6 +277,17 @@ declare class PusherRealtimeDriver implements RealtimeDriver {
   private clientPromise?;
   constructor(options?: PusherTransportConfig);
   private client;
+  private key;
+  private cluster;
+  private useTLS;
+  private server;
+  /**
+   * Public settings a `pusher-js` client needs, including the self-hosted
+   * server address when `host` is set.
+   *
+   * @returns
+   */
+  clientConfig(): Record<string, unknown>;
   /**
    * `delivery` is accepted for contract parity and ignored: Pusher pushes over a
    * connection the client already holds open, so there is no dozing radio to
@@ -200,10 +342,18 @@ declare class PusherRealtimeDriver implements RealtimeDriver {
  */
 interface RealtimeDriver {
   broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, delivery?: RealtimeDeliveryOptions): Promise<unknown>;
+  /**
+   * Sign or grant access to an already authorized channel. `socketId` is the
+   * Pusher socket id, or the subscriber's uid for transports without sockets.
+   */
   auth(socketId: string, channel: string, data?: unknown): unknown | Promise<unknown>;
   registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string): Promise<void>;
+  /**
+   * Public connection settings a browser client needs. Must never include secrets.
+   */
+  clientConfig?(): Record<string, unknown>;
 }
-type RealtimeNotificationDriver<T extends RealtimeDriverName> = T extends 'firebase' ? FirebaseRealtimeDriver : T extends 'pusher' ? PusherRealtimeDriver : RealtimeDriver;
+type RealtimeNotificationDriver<T extends RealtimeDriverName> = T extends 'firebase' ? FirebaseRealtimeDriver : T extends 'firebase-database' ? FirebaseDatabaseRealtimeDriver : T extends 'polling' ? PollingRealtimeDriver : T extends 'memory' ? MemoryRealtimeDriver : T extends 'pusher' ? PusherRealtimeDriver : RealtimeDriver;
 //#endregion
 //#region src/Contracts/UserNotification.d.ts
 declare abstract class UserNotification extends Model {
@@ -229,7 +379,20 @@ type MailRecipientAddress = Record<string, string>;
 type MailRecipient = string | MailRecipientAddress | Array<string | MailRecipientAddress>;
 type NotificationData = Record<string, unknown>;
 type SmsDriverName = 'africastalking' | 'twilio';
-type RealtimeDriverName = 'pusher' | 'firebase';
+/**
+ * Realtime transports.
+ *
+ * - `pusher`: Pusher Channels, or any Pusher-protocol server such as soketi.
+ * - `firebase`: Firebase Cloud Messaging; delivers to devices, not channels.
+ * - `firebase-database`: Firebase Realtime Database channels.
+ * - `polling`: no push; clients are told to poll on an interval.
+ * - `memory`: records broadcasts in process, for tests.
+ */
+type RealtimeDriverName = 'pusher' | 'firebase' | 'firebase-database' | 'polling' | 'memory';
+/**
+ * Transports that can deliver to device registration tokens.
+ */
+type PushDriverName = 'firebase';
 type NotificationChannel = 'mail' | 'sms' | 'db' | 'realtime';
 interface Transport<T = any, D extends TransportOptions = TransportOptions> {
   mailer?: Transporter<T, D> | undefined;
@@ -282,6 +445,11 @@ type PusherTransportConfig = {
   secret?: string;
   cluster?: string;
   use_tls?: boolean;
+  /**
+   * A self-hosted Pusher-protocol server (e.g. soketi). Overrides `cluster` addressing.
+   */
+  host?: string;
+  port?: number;
 };
 type FirebaseTransportConfig = {
   project_id?: string;
@@ -291,6 +459,40 @@ type FirebaseTransportConfig = {
   admin_sdk_path?: string;
   /** Delivery options applied to every send on this transport. */
   delivery?: RealtimeDeliveryOptions;
+  web?: FirebaseWebConfig;
+};
+/**
+ * Public Firebase web app settings handed to browser clients. Never secret.
+ */
+type FirebaseWebConfig = {
+  api_key?: string;
+  auth_domain?: string;
+  app_id?: string;
+  messaging_sender_id?: string;
+  /** Web push VAPID key clients use to request a messaging token. */
+  vapid_key?: string;
+};
+type FirebaseDatabaseTransportConfig = Omit<FirebaseTransportConfig, 'delivery'> & {
+  database_url?: string;
+  /**
+   * Database path that holds channel events (default `arkstack/channels`).
+   */
+  root?: string;
+  /**
+   * Database path that holds per-user channel grants (default `arkstack/grants`).
+   */
+  grants_root?: string;
+  /**
+   * How long, in seconds, a channel grant stays valid (default 3600).
+   */
+  grant_ttl?: number;
+  web?: FirebaseWebConfig;
+};
+type PollingTransportConfig = {
+  /**
+   * How often, in milliseconds, clients should poll (default 5000).
+   */
+  interval?: number;
 };
 /**
  * Per-send delivery hints for push transports.
@@ -358,6 +560,9 @@ type RealtimeDriverOptions<T extends RealtimeDriverName = RealtimeDriverName> =
   driverFactory?: () => RealtimeDriver;
   pusher?: PusherTransportConfig;
   firebase?: FirebaseTransportConfig;
+  'firebase-database'?: FirebaseDatabaseTransportConfig;
+  polling?: PollingTransportConfig;
+  memory?: Record<string, never>;
 };
 /** The notification payload delivered to realtime clients. */
 type RealtimeNotificationPayload = {
@@ -395,12 +600,52 @@ type RealtimeNotificationPayload = {
  * `listen()`, which has always accepted arbitrary events.
  */
 type RealtimeBroadcastPayload = RealtimeNotificationPayload | Record<string, unknown>;
+/**
+ * The outcome of a device push: totals plus the tokens to prune.
+ */
+type PushResult = {
+  successCount: number;
+  failureCount: number;
+  invalidTokens: string[];
+};
 /** The result of a realtime broadcast (plus the stored record when `store` is on). */
 type RealtimeBroadcastResult = {
   channel: string | string[];
   event: string;
   payload: RealtimeNotificationPayload;
   stored?: UserNotification;
+  /** Present when the notification was also pushed to the recipient's devices. */
+  push?: PushResult;
+};
+/**
+ A device registration token, or a record carrying one.
+ */
+type PushTokenLike = string | {
+  token: string;
+};
+/**
+ Decides whether a subject (usually the authenticated user) may join a channel.
+ */
+type ChannelAuthorizer<Subject = any> = (subject: Subject, params: Record<string, string>) => boolean | Promise<boolean>;
+/**
+ * The body a realtime client posts to the channel auth endpoint.
+ */
+type ChannelAuthRequest = {
+  socket_id?: string;
+  channel_name?: string;
+};
+/**
+ * Public connection settings a `@arkstack/realtime` client is created from.
+ */
+type RealtimeClientConfig = {
+  transport: RealtimeDriverName;
+  event: string;
+  channelPrefix: string;
+  pusher?: Record<string, unknown>;
+  firebase?: Record<string, unknown>;
+  'firebase-database'?: Record<string, unknown>;
+  polling?: Record<string, unknown>;
+  memory?: Record<string, unknown>;
 };
 type DbNotificationType = 'transaction' | 'pocket' | 'family' | 'security' | 'promo' | 'bill' | 'goal' | string;
 type DbNotificationPayload = {
@@ -438,6 +683,17 @@ interface NotificationConfig<T = any> {
     };
     realtime?: {
       transport?: RealtimeDriverName;
+      /**
+       * Also push notifications sent to a user to their registered devices
+       * over this transport. When unset, on only if `transport` is `firebase`;
+       * `false` turns it off.
+       */
+      push?: PushDriverName | false;
+      /**
+       * Resolve a user's device tokens for `push`. Defaults to reading
+       * `user.pushTokens`.
+       */
+      push_tokens?: (user: any) => PushTokenLike[] | Promise<PushTokenLike[]>;
       /** Prefix for the per-user channel/topic (default `user.`). */
       channel_prefix?: string;
       /** Event name clients subscribe to (default `notification`). */
@@ -509,8 +765,10 @@ interface NotificationConfig<T = any> {
       secret: string;
       cluster: string;
       use_tls?: boolean;
+      host?: string;
+      port?: number;
     };
-    firebase?: {
+    firebase?: ({
       project_id: string;
       client_email: string;
       private_key: string;
@@ -518,7 +776,12 @@ interface NotificationConfig<T = any> {
     } | {
       app_name?: string;
       admin_sdk_path: string;
+    }) & {
+      delivery?: RealtimeDeliveryOptions;
+      web?: FirebaseWebConfig;
     };
+    'firebase-database'?: FirebaseDatabaseTransportConfig;
+    polling?: PollingTransportConfig;
   };
   queue?: {
     name?: string;
@@ -576,8 +839,9 @@ declare class DbNotification extends NotificationContract<UserNotification> {
    * Broadcast the notification using the default realtime driver.
    *
    * @param realtime Set to false to disable realtime broadcast
+   * @returns
    */
-  broadcast(realtime?: boolean): void;
+  broadcast(realtime?: boolean): this;
   create(user: User, payload: DbNotificationPayload): Promise<UserNotification>;
   /**
    * Send the database notification
@@ -700,6 +964,8 @@ declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriver
   private shouldStore;
   private tagName?;
   private isRetraction;
+  private shouldPush?;
+  private deviceTokens?;
   private deliveryOptions;
   private payload;
   constructor(options?: RealtimeDriverOptions<T>);
@@ -824,6 +1090,23 @@ declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriver
    * @returns
    */
   retract(retract?: boolean): this;
+  /**
+   * Also push this notification to the recipient's devices over the
+   * `drivers.realtime.push` transport. On by default for a `User` recipient
+   * when push is configured; pass `false` to skip it for this send.
+   *
+   * @param push
+   * @returns
+   */
+  push(push?: boolean): this;
+  /**
+   * Push to these device tokens instead of the recipient's own.
+   *
+   * @param tokens
+   * @returns
+   */
+  devices(tokens: string[]): this;
+  private resolveDevices;
   private resolveChannel;
   /**
    * Send a realtime notification using the default realtime driver
@@ -941,17 +1224,150 @@ declare class Notification<D extends keyof DriverMap = keyof DriverMap> {
   private static createDriver;
 }
 //#endregion
+//#region src/Broadcast.d.ts
+type BroadcastRouteOptions = {
+  /** Route prefix (default `/realtime`). */
+  prefix?: string;
+  /** Extra middleware run before the framework `auth` middleware. */
+  middleware?: unknown | unknown[];
+};
+/**
+ * The server side of realtime: builds transports from config, broadcasts
+ * arbitrary events, and authorizes channel subscriptions against registered
+ * channel rules for every transport.
+ */
+declare class Broadcast {
+  private static rules;
+  private static settings;
+  /**
+   * The configured streaming transport name.
+   *
+   * @returns
+   */
+  static transport(): RealtimeDriverName;
+  /**
+   * The prefix of the per-user notification channel.
+   *
+   * @returns
+   */
+  static channelPrefix(): string;
+  /**
+   * Register who may subscribe to channels matching `pattern`. `{name}`
+   * placeholders match one dot-free segment and are passed to the authorizer.
+   * A later registration of the same pattern replaces the earlier one.
+   *
+   * @param pattern  e.g. `private-team.{teamId}`
+   * @param authorizer
+   * @returns
+   */
+  static channel<Subject = any>(pattern: string, authorizer: ChannelAuthorizer<Subject>): typeof Broadcast;
+  /**
+   * Remove every registered channel rule.
+   */
+  static forgetChannels(): void;
+  /**
+   * Whether `subject` may subscribe to `channel`. The first matching rule
+   * decides. The per-user notification channel is allowed for its own user
+   * unless a rule overrides it. Unmatched channels are denied.
+   *
+   * @param subject
+   * @param channel
+   * @returns
+   */
+  static authorize(subject: unknown, channel: string): Promise<boolean>;
+  /**
+   * Build a transport. Uses the configured `driverFactory` when there is one,
+   * otherwise the named or configured built-in.
+   *
+   * @param options
+   * @returns
+   */
+  static driver(options?: RealtimeDriverOptions): RealtimeDriver;
+  /**
+   * Build a named built-in transport from its `transports.*` config.
+   *
+   * @param transport
+   * @param overrides
+   * @returns
+   */
+  static make(transport: RealtimeDriverName, overrides?: Record<string, unknown>): RealtimeDriver;
+  /**
+   * Broadcast an arbitrary event on one or more channels over the configured
+   * transport.
+   *
+   * @param channel
+   * @param event
+   * @param payload
+   * @param delivery
+   * @returns
+   */
+  static broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, delivery?: RealtimeDeliveryOptions): Promise<unknown>;
+  /**
+   * The device push transport, or null when push is off. When `push` is unset,
+   * apps streaming over `firebase` keep pushing to devices as they always have.
+   *
+   * @returns
+   */
+  static pushDriver(): FirebaseRealtimeDriver | null;
+  /**
+   * A user's device tokens, from the configured `push_tokens` resolver or the
+   * user's `pushTokens` property.
+   *
+   * @param user
+   * @returns
+   */
+  static pushTokens(user: unknown): Promise<string[]>;
+  /**
+   * Push an event to device tokens over the push transport. Returns null when
+   * push is off or there are no tokens.
+   *
+   * @param tokens
+   * @param event
+   * @param payload
+   * @param delivery
+   * @returns
+   */
+  static push(tokens: string[], event: string, payload: RealtimeBroadcastPayload, delivery?: RealtimeDeliveryOptions): Promise<PushResult | null>;
+  /**
+   * Authorize `subject` for the requested channel and return what the active
+   * transport needs: a Pusher signature, a Firebase custom token, or nothing.
+   *
+   * @param subject  Usually the authenticated user.
+   * @param request  The client's `socket_id` and `channel_name`.
+   * @param options  `uid` overrides the Firebase uid (defaults to `subject.id`).
+   * @returns
+   */
+  static handleAuth(subject: unknown, request: ChannelAuthRequest, options?: {
+    uid?: string;
+    driver?: RealtimeDriver;
+  }): Promise<unknown>;
+  /**
+   * Public settings a `@arkstack/realtime` client is created from.
+   *
+   * @returns
+   */
+  static clientConfig(): RealtimeClientConfig;
+  /**
+   * Register `POST {prefix}/auth` and `GET {prefix}/config`, both behind the
+   * framework `auth` middleware.
+   *
+   * @param options
+   */
+  static routes(options?: BroadcastRouteOptions): Promise<void>;
+}
+//#endregion
 //#region src/UserNotificationCenter.d.ts
 declare class UserNotificationCenter {
   private static getModel;
   /**
-   * Create a database notification then broadcast it using the configured realtime driver
+   * Store a notification, broadcast it on the user's channel, and push it to
+   * their devices when `drivers.realtime.push` is configured.
    *
    * @param user
    * @param payload
+   * @param devices  Push to these tokens instead of the user's own.
    */
-  static send(user: User, payload: DbNotificationPayload, channel?: string[]): Promise<RealtimeBroadcastResult>;
-  private static resolvePushTokens;
+  static send(user: User, payload: DbNotificationPayload, devices?: string[]): Promise<RealtimeBroadcastResult>;
   /**
    * Create a database notification
    *
@@ -999,4 +1415,4 @@ declare const configure: <T extends DotPath<NotificationConfig>>(key: T, default
 //#region src/utils/template.d.ts
 declare const interpolate: (value: string, data?: NotificationData) => string;
 //#endregion
-export { AfricasTalkingSmsDriver, DbNotification, DbNotificationPayload, DbNotificationType, DriverResult, FirebaseMulticastResult, FirebaseRealtimeDriver, FirebaseTransportConfig, MailDriverOptions, MailNotification, MailNotificationOptions, MailRecipient, MailRecipientAddress, MergedTransportConfig, Notification, NotificationChannel, NotificationConfig, NotificationContract, NotificationData, NotificationDriverMap, NotificationRecipient, PusherRealtimeDriver, PusherTransportConfig, RealtimeBroadcastPayload, RealtimeBroadcastResult, RealtimeDeliveryOptions, RealtimeDriver, RealtimeDriverName, RealtimeDriverOptions, RealtimeNotification, RealtimeNotificationDriver, RealtimeNotificationPayload, SmsDriverName, SmsDriverOptions, SmsNotification, Transport, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };
+export { AfricasTalkingSmsDriver, Broadcast, BroadcastRouteOptions, ChannelAuthRequest, ChannelAuthorizer, DbNotification, DbNotificationPayload, DbNotificationType, DriverResult, FirebaseDatabaseRealtimeDriver, FirebaseDatabaseTransportConfig, FirebaseMulticastResult, FirebaseRealtimeDriver, FirebaseTransportConfig, FirebaseWebConfig, MailDriverOptions, MailNotification, MailNotificationOptions, MailRecipient, MailRecipientAddress, MemoryRealtimeDriver, MergedTransportConfig, Notification, NotificationChannel, NotificationConfig, NotificationContract, NotificationData, NotificationDriverMap, NotificationRecipient, PollingRealtimeDriver, PollingTransportConfig, PushDriverName, PushResult, PushTokenLike, PusherRealtimeDriver, PusherTransportConfig, RealtimeBroadcastPayload, RealtimeBroadcastResult, RealtimeClientConfig, RealtimeDeliveryOptions, RealtimeDriver, RealtimeDriverName, RealtimeDriverOptions, RealtimeNotification, RealtimeNotificationDriver, RealtimeNotificationPayload, RecordedBroadcast, SmsDriverName, SmsDriverOptions, SmsNotification, Transport, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, firebaseChannelKey, interpolate };