@arkstack/notifications 0.18.6 → 0.18.8

package/dist/index.d.ts

@@ -8,6 +8,203 @@ 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/FirebaseRealtimeDriver.d.ts
+/**
+ * The outcome of a token multicast: totals plus the tokens FCM rejected as dead.
+ */
+interface FirebaseMulticastResult {
+  successCount: number;
+  failureCount: number;
+  /**
+   * Tokens FCM reported as unregistered/invalid — delete these from your store.
+   */
+  invalidTokens: string[];
+}
+/**
+ * Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging).
+ * A single channel maps to an FCM topic; an array of channels is treated as
+ * device registration tokens and delivered via a multicast send (chunked to
+ * FCM's 500-token limit), returning the tokens that should be pruned.
+ *
+ * `firebase-admin` is an optional peer dependency, imported lazily so the
+ * package installs without it; it is only required when this transport is used.
+ * FCM data values must be strings, so the payload is JSON-encoded.
+ */
+declare class FirebaseRealtimeDriver implements RealtimeDriver {
+  private options;
+  private messagingPromise?;
+  constructor(options?: FirebaseTransportConfig);
+  private messaging;
+  broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, delivery?: RealtimeDeliveryOptions): Promise<string | FirebaseMulticastResult>;
+  /**
+   * Translate transport-agnostic delivery hints into FCM's platform blocks.
+   *
+   * Per-send options win over the transport defaults, and the raw `android` /
+   * `apns` / `webpush` escape hatches are merged last so a caller can always
+   * override what this derives.
+   *
+   * `priority` always maps to Android and Web Push. Whether it maps to APNs
+   * depends on the message rather than on the platform: Apple requires a
+   * background push to be priority 5 or 1, and a data-only message — what this
+   * driver sends by default — arrives on iOS as exactly that. So the header is
+   * derived only once the message is demonstrably a *visible* push, which a
+   * caller declares through the `apns` escape hatch. Guessing otherwise would
+   * mean sending APNs something it is documented to reject.
+   *
+   * @param delivery
+   * @returns
+   */
+  private overridesFor;
+  /**
+   * Whether the caller has built a push iOS will actually display.
+   *
+   * Apple allows `apns-priority: 10` only on a push that shows the user
+   * something; a background push must be 5 or 1. A data-only message is a
+   * background push, so this is false for the default this driver sends, and
+   * true once a caller has declared an alert through the `apns` escape hatch —
+   * by push type, or by supplying an alert payload.
+   *
+   * @param apns
+   * @returns
+   */
+  private isVisiblePush;
+  /**
+   * Fold a caller's raw override over the derived settings, dropping the block
+   * entirely when neither contributed anything.
+   *
+   * @param key
+   * @param derived
+   * @param override
+   * @returns
+   */
+  private flatBlock;
+  /**
+   * As `flatBlock`, but for the platforms whose settings live under `headers` —
+   * merged key by key, so an override adding one header keeps the rest.
+   *
+   * @param key
+   * @param derived
+   * @param override
+   * @returns
+   */
+  private headerBlock;
+  /**
+   * Firebase channels do not require server-side authorization.
+   *
+   * @param _socketId
+   * @param _channel
+   * @param _data
+   */
+  auth(_socketId: string, _channel: string, _data?: unknown): Promise<void>;
+  /**
+   * Firebase does not require an authorization route.
+   *
+   * @param _authEndpoint
+   * @param _middleware
+   * @param _channelPrefix
+   * @param _config
+   */
+  static registerAuthRoute(_authEndpoint?: string, _middleware?: unknown | unknown[], _channelPrefix?: string, _config?: FirebaseTransportConfig): Promise<void>;
+  /**
+   * Firebase does not require an authorization route.
+   *
+   * @param _authEndpoint
+   * @param _middleware
+   * @param _channelPrefix
+   */
+  registerAuthRoute(_authEndpoint?: string, _middleware?: unknown | unknown[], _channelPrefix?: string): Promise<void>;
+  /**
+   * Send to many device tokens at once, chunked to FCM's 500-token limit, and
+   * collect the tokens FCM rejects as dead so the caller can prune them.
+   */
+  private multicast;
+}
+//#endregion
+//#region src/drivers/realtime/PusherRealtimeDriver.d.ts
+/** The slice of the `pusher` server SDK this driver uses. */
+interface PusherClient {
+  trigger(channel: string | string[], event: string, data: unknown): Promise<unknown>;
+  authorizeChannel(socketId: string, channel: string, data?: {
+    user_id: string;
+    user_info?: {
+      [key: string]: any;
+    };
+  }): {
+    auth: string;
+    channel_data?: string;
+    shared_secret?: string;
+  };
+}
+/**
+ * Broadcasts notifications over [Pusher Channels](https://pusher.com/channels).
+ *
+ * The `pusher` server SDK is an optional peer dependency, imported lazily so the
+ * package installs without it; it is only required when this transport is used.
+ */
+declare class PusherRealtimeDriver implements RealtimeDriver {
+  private options;
+  private clientPromise?;
+  constructor(options?: PusherTransportConfig);
+  private client;
+  /**
+   * `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
+   * wake and no per-message priority, TTL or collapse key to set.
+   *
+   * @param channel
+   * @param event
+   * @param payload
+   * @param _delivery
+   * @returns
+   */
+  broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, _delivery?: RealtimeDeliveryOptions): Promise<unknown>;
+  /**
+   * Authourize a pusher channel
+   *
+   * @param socketId
+   * @param channel
+   * @returns
+   */
+  auth(socketId: string, channel: string, data?: Parameters<PusherClient['authorizeChannel']>[2]): Promise<ReturnType<PusherClient['authorizeChannel']>>;
+  /**
+   * Register a realtime autorization route
+   *
+   * @param authEndpoint
+   * @param middleware
+   * @param config
+   * @param channelPrefix
+   */
+  static registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string, config?: PusherTransportConfig): Promise<void>;
+  /**
+   * Register a realtime autorization route
+   *
+   * @param authEndpoint
+   * @param middleware
+   * @param channelPrefix
+   */
+  registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string): Promise<void>;
+}
+//#endregion
+//#region src/Contracts/RealtimeDriver.d.ts
+/**
+ * A realtime transport (Pusher, Firebase, …) broadcasts a notification payload
+ * to a channel/topic that connected clients subscribe to.
+ *
+ * `channel` may be an array: for Pusher it fans out to multiple channels, and
+ * for Firebase it is treated as a list of device registration tokens delivered
+ * via a multicast send.
+ *
+ * `delivery` carries transport-level hints — priority, TTL, collapse key. It is
+ * optional so existing implementations stay source-compatible, and transports
+ * without a notion of priority (Pusher) are free to ignore it.
+ */
+interface RealtimeDriver {
+  broadcast(channel: string | string[], event: string, payload: RealtimeBroadcastPayload, delivery?: RealtimeDeliveryOptions): Promise<unknown>;
+  auth(socketId: string, channel: string, data?: unknown): unknown | Promise<unknown>;
+  registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string): Promise<void>;
+}
+type RealtimeNotificationDriver<T extends RealtimeDriverName> = T extends 'firebase' ? FirebaseRealtimeDriver : T extends 'pusher' ? PusherRealtimeDriver : RealtimeDriver;
+//#endregion
 //#region src/Contracts/UserNotification.d.ts
 declare abstract class UserNotification extends Model {
   [key: string]: any;
@@ -92,6 +289,53 @@ type FirebaseTransportConfig = {
   private_key?: string;
   app_name?: string;
   admin_sdk_path?: string;
+  /** Delivery options applied to every send on this transport. */
+  delivery?: RealtimeDeliveryOptions;
+};
+/**
+ * Per-send delivery hints for push transports.
+ *
+ * FCM defaults a data message to normal priority, which Doze and App Standby are
+ * free to defer until the next maintenance window — exactly the state a phone is
+ * in when something time-critical — an approval someone is waiting on, an alert
+ * about to go stale — needs to wake it.
+ * `priority: 'high'` is what exempts the message.
+ *
+ * Only the Firebase transport acts on these; Pusher holds an open connection and
+ * has no equivalent, so it ignores them.
+ */
+type RealtimeDeliveryOptions = {
+  /**
+   * `high` wakes a dozing device (FCM `android.priority`, APNs priority 10).
+   * Defaults to `normal`. Budgeted by FCM — reserve it for messages a user is
+   * actually waiting on.
+   */
+  priority?: 'normal' | 'high';
+  /**
+   * How long, in **seconds**, the message stays worth delivering. FCM's own
+   * default is four weeks; anything time-critical wants far less, so a stale
+   * signal expires instead of surfacing long after the moment it described has
+   * passed. `0` asks for now-or-never.
+   */
+  ttl?: number;
+  /**
+   * Supersede an undelivered message with the same key rather than stacking a
+   * second one — e.g. the id of whatever is being signalled, so a retry replaces
+   * the message it repeats.
+   */
+  collapseKey?: string;
+  /**
+   * Merged over the derived `android` block; escape hatch for anything unmapped.
+   */
+  android?: Record<string, unknown>;
+  /**
+   * Merged over the derived `apns` block; escape hatch for anything unmapped.
+   */
+  apns?: Record<string, unknown>;
+  /**
+   * Merged over the derived `webpush` block; escape hatch for anything unmapped.
+   */
+  webpush?: Record<string, unknown>;
 };
 type RealtimeDriverOptions<T extends RealtimeDriverName = RealtimeDriverName> = {
   transport?: T;
@@ -101,6 +345,17 @@ type RealtimeDriverOptions<T extends RealtimeDriverName = RealtimeDriverName> =
   event?: string;
   /** Also persist the notification to the database (requires a User recipient). */
   store?: boolean;
+  /** Delivery hints (priority, TTL, collapse key) for push transports. */
+  delivery?: RealtimeDeliveryOptions;
+  /**
+   * Build the driver yourself, bypassing the built-ins. Anything satisfying
+   * {@link RealtimeDriver} works — a transport this package does not ship (APNs
+   * or PushKit, say), or a fake in a test. Supplying this ignores `transport`.
+   *
+   * Called synchronously; do connection setup lazily inside the driver, as the
+   * bundled ones do, so constructing a notification never blocks on a network.
+   */
+  driverFactory?: () => RealtimeDriver;
   pusher?: PusherTransportConfig;
   firebase?: FirebaseTransportConfig;
 };
@@ -113,9 +368,33 @@ type RealtimeNotificationPayload = {
   actionText?: string | null;
   actionLink?: string | null;
   meta?: NotificationData | null;
+  /**
+   * Stable identity for what this notification is *about* — an order, an
+   * incident, an approval. A later notification carrying the same tag supersedes
+   * this one rather than stacking beside it, so a client can replace what it
+   * already showed. Unbounded and client-side; unrelated to the transport's
+   * `collapseKey`, which is a queue slot with a much smaller budget.
+   */
+  tag?: string | null;
+  /**
+   * Marks this message as an instruction to *remove* the notification carrying
+   * `tag`, rather than as a notification to display. Absent means display.
+   *
+   * Prefer superseding with replacement content where there is any: a retraction
+   * has nothing to show, so it must travel as a silent push, and silent pushes
+   * are the ones platforms throttle hardest.
+   */
+  retracted?: boolean;
   read_at: string | null;
   created_at: string;
 };
+/**
+ * What a transport will carry. Notifications are the common case and what the
+ * builder produces, but a channel is just a channel — an application can push its
+ * own event shapes over the same one and pick them up with the client's
+ * `listen()`, which has always accepted arbitrary events.
+ */
+type RealtimeBroadcastPayload = RealtimeNotificationPayload | Record<string, unknown>;
 /** The result of a realtime broadcast (plus the stored record when `store` is on). */
 type RealtimeBroadcastResult = {
   channel: string | string[];
@@ -158,13 +437,17 @@ interface NotificationConfig<T = any> {
       table: string;
     };
     realtime?: {
-      transport: RealtimeDriverName;
+      transport?: RealtimeDriverName;
       /** Prefix for the per-user channel/topic (default `user.`). */
       channel_prefix?: string;
       /** Event name clients subscribe to (default `notification`). */
       event?: string;
       /** Persist broadcasts to the database by default. */
       store?: boolean;
+      /** Delivery hints applied to every broadcast unless overridden per-send. */
+      delivery?: RealtimeDeliveryOptions;
+      /** Build the driver yourself for every realtime notification. */
+      driverFactory?: () => RealtimeDriver;
     };
   };
   transports: {
@@ -295,7 +578,7 @@ declare class DbNotification extends NotificationContract<UserNotification> {
    * @param realtime Set to false to disable realtime broadcast
    */
   broadcast(realtime?: boolean): void;
-  create(user: User, payload: DbNotificationPayload): Promise<import("arkormx").Model<string | import("arkormx").ModelQuerySchemaLike | Record<string, unknown>, Record<string, unknown>>>;
+  create(user: User, payload: DbNotificationPayload): Promise<UserNotification>;
   /**
    * Send the database notification
    *
@@ -305,7 +588,7 @@ declare class DbNotification extends NotificationContract<UserNotification> {
    * @param data
    * @returns
    */
-  send(message: string, subject?: string, _recipient?: NotificationRecipient, data?: NotificationData): Promise<import("arkormx").Model<string | import("arkormx").ModelQuerySchemaLike | Record<string, unknown>, Record<string, unknown>>>;
+  send(message: string, subject?: string, _recipient?: NotificationRecipient, data?: NotificationData): Promise<UserNotification>;
 }
 //#endregion
 //#region src/drivers/MailNotification.d.ts
@@ -397,136 +680,6 @@ declare class MailNotification extends NotificationContract {
   private normalizeRecipient;
 }
 //#endregion
-//#region src/drivers/realtime/FirebaseRealtimeDriver.d.ts
-/**
- * The outcome of a token multicast: totals plus the tokens FCM rejected as dead.
- */
-interface FirebaseMulticastResult {
-  successCount: number;
-  failureCount: number;
-  /**
-   * Tokens FCM reported as unregistered/invalid — delete these from your store.
-   */
-  invalidTokens: string[];
-}
-/**
- * Broadcasts notifications over [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging).
- * A single channel maps to an FCM topic; an array of channels is treated as
- * device registration tokens and delivered via a multicast send (chunked to
- * FCM's 500-token limit), returning the tokens that should be pruned.
- *
- * `firebase-admin` is an optional peer dependency, imported lazily so the
- * package installs without it; it is only required when this transport is used.
- * FCM data values must be strings, so the payload is JSON-encoded.
- */
-declare class FirebaseRealtimeDriver implements RealtimeDriver {
-  private options;
-  private messagingPromise?;
-  constructor(options?: FirebaseTransportConfig);
-  private messaging;
-  broadcast(channel: string | string[], event: string, payload: RealtimeNotificationPayload): Promise<string | FirebaseMulticastResult>;
-  /**
-   * Firebase channels do not require server-side authorization.
-   *
-   * @param _socketId
-   * @param _channel
-   * @param _data
-   */
-  auth(_socketId: string, _channel: string, _data?: unknown): Promise<void>;
-  /**
-   * Firebase does not require an authorization route.
-   *
-   * @param _authEndpoint
-   * @param _middleware
-   * @param _channelPrefix
-   * @param _config
-   */
-  static registerAuthRoute(_authEndpoint?: string, _middleware?: unknown | unknown[], _channelPrefix?: string, _config?: FirebaseTransportConfig): Promise<void>;
-  /**
-   * Firebase does not require an authorization route.
-   *
-   * @param _authEndpoint
-   * @param _middleware
-   * @param _channelPrefix
-   */
-  registerAuthRoute(_authEndpoint?: string, _middleware?: unknown | unknown[], _channelPrefix?: string): Promise<void>;
-  /**
-   * Send to many device tokens at once, chunked to FCM's 500-token limit, and
-   * collect the tokens FCM rejects as dead so the caller can prune them.
-   */
-  private multicast;
-}
-//#endregion
-//#region src/drivers/realtime/PusherRealtimeDriver.d.ts
-/** The slice of the `pusher` server SDK this driver uses. */
-interface PusherClient {
-  trigger(channel: string | string[], event: string, data: unknown): Promise<unknown>;
-  authorizeChannel(socketId: string, channel: string, data?: {
-    user_id: string;
-    user_info?: {
-      [key: string]: any;
-    };
-  }): {
-    auth: string;
-    channel_data?: string;
-    shared_secret?: string;
-  };
-}
-/**
- * Broadcasts notifications over [Pusher Channels](https://pusher.com/channels).
- *
- * The `pusher` server SDK is an optional peer dependency, imported lazily so the
- * package installs without it; it is only required when this transport is used.
- */
-declare class PusherRealtimeDriver implements RealtimeDriver {
-  private options;
-  private clientPromise?;
-  constructor(options?: PusherTransportConfig);
-  private client;
-  broadcast(channel: string | string[], event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
-  /**
-   * Authourize a pusher channel
-   *
-   * @param socketId
-   * @param channel
-   * @returns
-   */
-  auth(socketId: string, channel: string, data?: Parameters<PusherClient['authorizeChannel']>[2]): Promise<ReturnType<PusherClient['authorizeChannel']>>;
-  /**
-   * Register a realtime autorization route
-   *
-   * @param authEndpoint
-   * @param middleware
-   * @param config
-   * @param channelPrefix
-   */
-  static registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string, config?: PusherTransportConfig): Promise<void>;
-  /**
-   * Register a realtime autorization route
-   *
-   * @param authEndpoint
-   * @param middleware
-   * @param channelPrefix
-   */
-  registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string): Promise<void>;
-}
-//#endregion
-//#region src/Contracts/RealtimeDriver.d.ts
-/**
- * A realtime transport (Pusher, Firebase, …) broadcasts a notification payload
- * to a channel/topic that connected clients subscribe to.
- *
- * `channel` may be an array: for Pusher it fans out to multiple channels, and
- * for Firebase it is treated as a list of device registration tokens delivered
- * via a multicast send.
- */
-interface RealtimeDriver {
-  broadcast(channel: string | string[], event: string, payload: RealtimeNotificationPayload): Promise<unknown>;
-  auth(socketId: string, channel: string, data?: unknown): unknown | Promise<unknown>;
-  registerAuthRoute(authEndpoint?: string, middleware?: unknown | unknown[], channelPrefix?: string): Promise<void>;
-}
-type RealtimeNotificationDriver<T extends RealtimeDriverName> = T extends 'firebase' ? FirebaseRealtimeDriver : T extends 'pusher' ? PusherRealtimeDriver : RealtimeDriver;
-//#endregion
 //#region src/drivers/RealtimeNotification.d.ts
 /**
  * Broadcasts a notification to connected clients over a realtime transport
@@ -535,7 +688,9 @@ type RealtimeNotificationDriver<T extends RealtimeDriverName> = T extends 'fireb
  */
 declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriverName> extends NotificationContract<RealtimeBroadcastResult> {
   /**
-   * The underlying transport; assignable so tests can inject a fake.
+   * The underlying transport. Assignable, and configurable up front through
+   * `driverFactory`, so a transport this package does not ship — or a fake in a
+   * test — can stand in for the built-ins.
    */
   driver: RealtimeNotificationDriver<T>;
   private user?;
@@ -543,6 +698,9 @@ declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriver
   private eventName;
   private channelPrefix;
   private shouldStore;
+  private tagName?;
+  private isRetraction;
+  private deliveryOptions;
   private payload;
   constructor(options?: RealtimeDriverOptions<T>);
   from(_: string): this;
@@ -590,6 +748,82 @@ declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriver
   type(type?: DbNotificationType | null): this;
   action(text?: string | null, link?: string | null): this;
   meta(meta?: NotificationData | null): this;
+  /**
+   * How hard the transport should work to deliver this message.
+   *
+   * FCM sends a data message at normal priority by default, and Doze and App
+   * Standby may hold a normal-priority message until the next maintenance
+   * window — which is precisely the state a phone is in when something needs to
+   * wake it. `high` is what exempts the message.
+   *
+   * FCM budgets high-priority sends, so reserve it for messages the user is
+   * actually waiting on. Pusher ignores this.
+   *
+   * @param priority
+   * @returns
+   */
+  priority(priority?: 'normal' | 'high'): this;
+  /**
+   * How long, in seconds, this message is still worth delivering.
+   *
+   * FCM keeps a message for four weeks by default. Anything time-critical wants
+   * far less — a signal that arrives after the moment has passed is worse than
+   * one that never arrives — so pair a short TTL with `priority('high')`. `0`
+   * means deliver now or drop it.
+   *
+   * @param seconds
+   * @returns
+   */
+  ttl(seconds: number): this;
+  /**
+   * Supersede an earlier undelivered message instead of stacking beside it.
+   * Key it by the thing being signalled — an approval id, say — so a repeat replaces
+   * the message it repeats.
+   *
+   * @param key
+   * @returns
+   */
+  collapseKey(key: string): this;
+  /**
+   * Merge raw delivery options, including the per-platform `android` / `apns` /
+   * `webpush` escape hatches for anything the helpers above do not cover.
+   *
+   * @param delivery
+   * @returns
+   */
+  delivery(delivery: RealtimeDeliveryOptions): this;
+  /**
+   * Give this notification a stable identity, so a later one can supersede it.
+   *
+   * Tag by the thing the notification is *about* — `order:42`, `incident:7` —
+   * not by the message. A client that already showed a notification with this
+   * tag replaces it in place instead of stacking a second one beside it.
+   *
+   * This is a client-side identity and is deliberately **not** wired to
+   * `collapseKey`: a collapse key is a transport queue slot, and FCM keeps only
+   * four per device, so auto-deriving one per tag would quietly evict others.
+   * When you want both — supersede what is queued *and* what was displayed —
+   * set both to the same value.
+   *
+   * @param tag
+   * @returns
+   */
+  tag(tag: string): this;
+  /**
+   * Send an instruction to remove the notification carrying this tag, rather
+   * than a notification to display. Nothing is persisted, even under `store()`.
+   *
+   * Reach for this only when there is genuinely nothing left to say. Where the
+   * outcome has its own content — an approval answered elsewhere, a check that
+   * went from failing to passing — supersede it by sending that content under
+   * the same `tag()`. A replacement travels as an ordinary notification, while a
+   * retraction has nothing to display and so must travel silently, which is
+   * exactly what Doze, App Standby and iOS throttle hardest.
+   *
+   * @param retract
+   * @returns
+   */
+  retract(retract?: boolean): this;
   private resolveChannel;
   /**
    * Send a realtime notification using the default realtime driver
@@ -600,7 +834,7 @@ declare class RealtimeNotification<T extends RealtimeDriverName = RealtimeDriver
    * @param data
    * @returns
    */
-  send(message: string, subject?: string, _recipient?: NotificationRecipient, data?: NotificationData): Promise<RealtimeBroadcastResult>;
+  send(message?: string, subject?: string, _recipient?: NotificationRecipient, data?: NotificationData): Promise<RealtimeBroadcastResult>;
 }
 //#endregion
 //#region src/drivers/sms/AfricasTalkingSmsDriver.d.ts
@@ -724,8 +958,8 @@ declare class UserNotificationCenter {
    * @param user
    * @param payload
    */
-  static create(user: User, payload: DbNotificationPayload): Promise<import("arkormx").Model<string | import("arkormx").ModelQuerySchemaLike | Record<string, unknown>, Record<string, unknown>>>;
-  static forUser(user: User): Promise<ArkormCollection<import("arkormx").Model<string | import("arkormx").ModelQuerySchemaLike | Record<string, unknown>, Record<string, unknown>>, import("arkormx").Model<string | import("arkormx").ModelQuerySchemaLike | Record<string, unknown>, Record<string, unknown>>[]>>;
+  static create(user: User, payload: DbNotificationPayload): Promise<UserNotification>;
+  static forUser(user: User): Promise<ArkormCollection<UserNotification, UserNotification[]>>;
   /**
    * Fetch all the users unread messages
    *
@@ -765,4 +999,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, RealtimeBroadcastResult, RealtimeDriver, RealtimeDriverName, RealtimeDriverOptions, RealtimeNotification, RealtimeNotificationDriver, RealtimeNotificationPayload, SmsDriverName, SmsDriverOptions, SmsNotification, Transport, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };
+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 };

package/dist/index.js

@@ -1,5 +1,5 @@
-import { Job } from "@arkstack/jobs";
 import { RequestException, config as config$1, env, getModel } from "@arkstack/common";
+import { Job } from "@arkstack/jobs";
 import { mkdir, writeFile } from "node:fs/promises";
 import path, { join } from "node:path";
 import nodemailer from "nodemailer";
@@ -74,7 +74,7 @@ var NotificationContract = class {
 //#region src/UserNotificationCenter.ts
 var UserNotificationCenter = class {
 	static async getModel() {
-		return await getModel("UserNotification");
+		return getModel("UserNotification");
 	}
 	/**
 	* Create a database notification then broadcast it using the configured realtime driver
@@ -209,7 +209,7 @@ var DbNotification = class extends NotificationContract {
 		this.realtime = realtime;
 	}
 	async create(user, payload) {
-		await getModel("UserNotification");
+		getModel("UserNotification");
 		if (this.realtime) return await UserNotificationCenter.send(user, payload);
 		return await UserNotificationCenter.create(user, payload);
 	}
@@ -547,20 +547,133 @@ var FirebaseRealtimeDriver = class {
 		})();
 		return this.messagingPromise;
 	}
-	async broadcast(channel, event, payload) {
+	async broadcast(channel, event, payload, delivery) {
 		const messaging = await this.messaging();
 		const data = {
 			event,
 			payload: JSON.stringify(payload)
 		};
-		if (Array.isArray(channel)) return await this.multicast(messaging, channel, data);
+		const overrides = this.overridesFor(delivery);
+		if (Array.isArray(channel)) return await this.multicast(messaging, channel, data, overrides);
 		const topic = channel.replace(/[^a-zA-Z0-9-_.~%]/g, "_");
 		return await messaging.send({
 			topic,
-			data
+			data,
+			...overrides
 		});
 	}
 	/**
+	* Translate transport-agnostic delivery hints into FCM's platform blocks.
+	*
+	* Per-send options win over the transport defaults, and the raw `android` /
+	* `apns` / `webpush` escape hatches are merged last so a caller can always
+	* override what this derives.
+	*
+	* `priority` always maps to Android and Web Push. Whether it maps to APNs
+	* depends on the message rather than on the platform: Apple requires a
+	* background push to be priority 5 or 1, and a data-only message — what this
+	* driver sends by default — arrives on iOS as exactly that. So the header is
+	* derived only once the message is demonstrably a *visible* push, which a
+	* caller declares through the `apns` escape hatch. Guessing otherwise would
+	* mean sending APNs something it is documented to reject.
+	* 
+	* @param delivery 
+	* @returns 
+	*/
+	overridesFor(delivery) {
+		const base = this.options.delivery ?? {};
+		const merged = {
+			...base,
+			...delivery,
+			android: {
+				...base.android,
+				...delivery?.android
+			},
+			apns: {
+				...base.apns,
+				...delivery?.apns
+			},
+			webpush: {
+				...base.webpush,
+				...delivery?.webpush
+			}
+		};
+		const android = {};
+		const apnsHeaders = {};
+		const webpushHeaders = {};
+		if (merged.priority) {
+			android.priority = merged.priority;
+			webpushHeaders.Urgency = merged.priority;
+			if (this.isVisiblePush(merged.apns)) apnsHeaders["apns-priority"] = merged.priority === "high" ? "10" : "5";
+		}
+		if (merged.collapseKey) {
+			android.collapseKey = merged.collapseKey;
+			apnsHeaders["apns-collapse-id"] = merged.collapseKey;
+		}
+		if (typeof merged.ttl === "number") {
+			android.ttl = merged.ttl * 1e3;
+			apnsHeaders["apns-expiration"] = merged.ttl === 0 ? "0" : String(Math.floor(Date.now() / 1e3) + merged.ttl);
+			webpushHeaders.TTL = String(merged.ttl);
+		}
+		return {
+			...this.flatBlock("android", android, merged.android),
+			...this.headerBlock("apns", apnsHeaders, merged.apns),
+			...this.headerBlock("webpush", webpushHeaders, merged.webpush)
+		};
+	}
+	/**
+	* Whether the caller has built a push iOS will actually display.
+	*
+	* Apple allows `apns-priority: 10` only on a push that shows the user
+	* something; a background push must be 5 or 1. A data-only message is a
+	* background push, so this is false for the default this driver sends, and
+	* true once a caller has declared an alert through the `apns` escape hatch —
+	* by push type, or by supplying an alert payload.
+	*
+	* @param apns
+	* @returns
+	*/
+	isVisiblePush(apns) {
+		const headers = apns?.headers;
+		const aps = (apns?.payload)?.aps;
+		return headers?.["apns-push-type"] === "alert" || aps?.alert !== void 0;
+	}
+	/**
+	* Fold a caller's raw override over the derived settings, dropping the block
+	* entirely when neither contributed anything.
+	* 
+	* @param key 
+	* @param derived 
+	* @param override 
+	* @returns 
+	*/
+	flatBlock(key, derived, override) {
+		const block = {
+			...derived,
+			...override
+		};
+		return Object.keys(block).length > 0 ? { [key]: block } : {};
+	}
+	/**
+	* As `flatBlock`, but for the platforms whose settings live under `headers` —
+	* merged key by key, so an override adding one header keeps the rest.
+	* 
+	* @param key 
+	* @param derived 
+	* @param override 
+	* @returns 
+	*/
+	headerBlock(key, derived, override) {
+		const { headers: overrideHeaders, ...rest } = override ?? {};
+		const headers = {
+			...derived,
+			...overrideHeaders
+		};
+		const block = { ...rest };
+		if (Object.keys(headers).length > 0) block.headers = headers;
+		return Object.keys(block).length > 0 ? { [key]: block } : {};
+	}
+	/**
 	* Firebase channels do not require server-side authorization.
 	* 
 	* @param _socketId 
@@ -589,7 +702,7 @@ var FirebaseRealtimeDriver = class {
 	* Send to many device tokens at once, chunked to FCM's 500-token limit, and
 	* collect the tokens FCM rejects as dead so the caller can prune them.
 	*/
-	async multicast(messaging, tokens, data) {
+	async multicast(messaging, tokens, data, overrides = {}) {
 		const result = {
 			successCount: 0,
 			failureCount: 0,
@@ -599,7 +712,8 @@ var FirebaseRealtimeDriver = class {
 			const batch = tokens.slice(i, i + MULTICAST_LIMIT);
 			const response = await messaging.sendEachForMulticast({
 				tokens: batch,
-				data
+				data,
+				...overrides
 			});
 			result.successCount += response.successCount;
 			result.failureCount += response.failureCount;
@@ -640,7 +754,18 @@ var PusherRealtimeDriver = class PusherRealtimeDriver {
 		})();
 		return this.clientPromise;
 	}
-	async broadcast(channel, event, payload) {
+	/**
+	* `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
+	* wake and no per-message priority, TTL or collapse key to set.
+	* 
+	* @param channel 
+	* @param event 
+	* @param payload 
+	* @param _delivery 
+	* @returns 
+	*/
+	async broadcast(channel, event, payload, _delivery) {
 		return await (await this.client()).trigger(channel, event, payload);
 	}
 	/**
@@ -704,8 +829,10 @@ var PusherRealtimeDriver = class PusherRealtimeDriver {
 * when `store` is enabled, is also persisted so the client can load history.
 */
 var RealtimeNotification = class extends NotificationContract {
-	/** 
-	* The underlying transport; assignable so tests can inject a fake. 
+	/**
+	* The underlying transport. Assignable, and configurable up front through
+	* `driverFactory`, so a transport this package does not ship — or a fake in a
+	* test — can stand in for the built-ins.
 	*/
 	driver;
 	user;
@@ -713,6 +840,9 @@ var RealtimeNotification = class extends NotificationContract {
 	eventName;
 	channelPrefix;
 	shouldStore;
+	tagName;
+	isRetraction = false;
+	deliveryOptions;
 	payload = {};
 	constructor(options = {}) {
 		super();
@@ -723,7 +853,12 @@ var RealtimeNotification = class extends NotificationContract {
 		this.eventName = options.event ?? driverConfig?.event ?? "notification";
 		this.channelPrefix = driverConfig?.channel_prefix ?? "user.";
 		this.shouldStore = options.store ?? driverConfig?.store ?? false;
-		this.driver = transport === "firebase" ? new FirebaseRealtimeDriver({
+		this.deliveryOptions = {
+			...driverConfig?.delivery,
+			...options.delivery
+		};
+		const factory = options.driverFactory ?? driverConfig?.driverFactory;
+		this.driver = factory ? factory() : transport === "firebase" ? new FirebaseRealtimeDriver({
 			...transportConfig,
 			...options.firebase
 		}) : new PusherRealtimeDriver({
@@ -811,6 +946,103 @@ var RealtimeNotification = class extends NotificationContract {
 		this.payload.meta = meta;
 		return this;
 	}
+	/**
+	* How hard the transport should work to deliver this message.
+	*
+	* FCM sends a data message at normal priority by default, and Doze and App
+	* Standby may hold a normal-priority message until the next maintenance
+	* window — which is precisely the state a phone is in when something needs to
+	* wake it. `high` is what exempts the message.
+	*
+	* FCM budgets high-priority sends, so reserve it for messages the user is
+	* actually waiting on. Pusher ignores this.
+	*
+	* @param priority
+	* @returns
+	*/
+	priority(priority = "high") {
+		this.deliveryOptions.priority = priority;
+		return this;
+	}
+	/**
+	* How long, in seconds, this message is still worth delivering.
+	*
+	* FCM keeps a message for four weeks by default. Anything time-critical wants
+	* far less — a signal that arrives after the moment has passed is worse than
+	* one that never arrives — so pair a short TTL with `priority('high')`. `0`
+	* means deliver now or drop it.
+	*
+	* @param seconds
+	* @returns
+	*/
+	ttl(seconds) {
+		this.deliveryOptions.ttl = seconds;
+		return this;
+	}
+	/**
+	* Supersede an earlier undelivered message instead of stacking beside it.
+	* Key it by the thing being signalled — an approval id, say — so a repeat replaces
+	* the message it repeats.
+	*
+	* @param key
+	* @returns
+	*/
+	collapseKey(key) {
+		this.deliveryOptions.collapseKey = key;
+		return this;
+	}
+	/**
+	* Merge raw delivery options, including the per-platform `android` / `apns` /
+	* `webpush` escape hatches for anything the helpers above do not cover.
+	*
+	* @param delivery
+	* @returns
+	*/
+	delivery(delivery) {
+		this.deliveryOptions = {
+			...this.deliveryOptions,
+			...delivery
+		};
+		return this;
+	}
+	/**
+	* Give this notification a stable identity, so a later one can supersede it.
+	*
+	* Tag by the thing the notification is *about* — `order:42`, `incident:7` —
+	* not by the message. A client that already showed a notification with this
+	* tag replaces it in place instead of stacking a second one beside it.
+	*
+	* This is a client-side identity and is deliberately **not** wired to
+	* `collapseKey`: a collapse key is a transport queue slot, and FCM keeps only
+	* four per device, so auto-deriving one per tag would quietly evict others.
+	* When you want both — supersede what is queued *and* what was displayed —
+	* set both to the same value.
+	*
+	* @param tag
+	* @returns
+	*/
+	tag(tag) {
+		this.tagName = tag;
+		return this;
+	}
+	/**
+	* Send an instruction to remove the notification carrying this tag, rather
+	* than a notification to display. Nothing is persisted, even under `store()`.
+	*
+	* Reach for this only when there is genuinely nothing left to say. Where the
+	* outcome has its own content — an approval answered elsewhere, a check that
+	* went from failing to passing — supersede it by sending that content under
+	* the same `tag()`. A replacement travels as an ordinary notification, while a
+	* retraction has nothing to display and so must travel silently, which is
+	* exactly what Doze, App Standby and iOS throttle hardest.
+	*
+	* @param retract
+	* @returns
+	*/
+	retract(retract = true) {
+		this.isRetraction = retract;
+		return this;
+	}
 	resolveChannel() {
 		if (this.channelName !== void 0) return this.channelName;
 		if (this.user) return `${this.channelPrefix}${this.user.id}`;
@@ -825,7 +1057,7 @@ var RealtimeNotification = class extends NotificationContract {
 	* @param data 
 	* @returns 
 	*/
-	async send(message, subject, _recipient, data) {
+	async send(message = "", subject, _recipient, data) {
 		const channel = this.resolveChannel();
 		const mergedData = this.mergeData(data);
 		const base = {
@@ -836,7 +1068,7 @@ var RealtimeNotification = class extends NotificationContract {
 			actionLink: this.payload.actionLink ?? null,
 			meta: this.payload.meta ?? null
 		};
-		const stored = this.shouldStore && this.user ? await UserNotificationCenter.create(this.user, base) : void 0;
+		const stored = this.shouldStore && this.user && !this.isRetraction ? await UserNotificationCenter.create(this.user, base) : void 0;
 		const payload = {
 			id: stored ? String(stored.id) : randomUUID(),
 			type: base.type ?? null,
@@ -845,10 +1077,12 @@ var RealtimeNotification = class extends NotificationContract {
 			actionText: base.actionText ?? null,
 			actionLink: base.actionLink ?? null,
 			meta: base.meta ?? null,
+			...this.tagName !== void 0 ? { tag: this.tagName } : {},
+			...this.isRetraction ? { retracted: true } : {},
 			read_at: stored?.readAt ? new Date(stored.readAt).toISOString() : null,
 			created_at: stored?.createdAt ? new Date(stored.createdAt).toISOString() : (/* @__PURE__ */ new Date()).toISOString()
 		};
-		if (channel && channel.length > 0) await this.driver.broadcast(channel, this.eventName, payload);
+		if (channel && channel.length > 0) await this.driver.broadcast(channel, this.eventName, payload, this.deliveryOptions);
 		return {
 			channel,
 			event: this.eventName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/notifications",
-  "version": "0.18.6",
+  "version": "0.18.8",
   "type": "module",
   "description": "Framework-agnostic notification module for Arkstack and Nodejs, providing support for multi-channel notification delivery.",
   "homepage": "https://arkstack.toneflix.net/guide/notifications",
@@ -34,17 +34,17 @@
     "africastalking": "^0.8.0",
     "nodemailer": "^9.0.3",
     "twilio": "^6.0.2",
-    "@arkstack/common": "^0.18.6"
+    "@arkstack/common": "^0.18.8"
   },
   "peerDependencies": {
     "@kanun-hq/plugin-phone": "^0.1.8",
     "firebase-admin": "^13.0.0",
     "pusher": "^5.2.0",
-    "@arkstack/contract": "^0.18.6",
-    "@arkstack/database": "^0.18.6",
-    "@arkstack/driver-express": "^0.18.6",
-    "@arkstack/driver-h3": "^0.18.6",
-    "@arkstack/jobs": "^0.18.6"
+    "@arkstack/database": "^0.18.8",
+    "@arkstack/driver-express": "^0.18.8",
+    "@arkstack/driver-h3": "^0.18.8",
+    "@arkstack/contract": "^0.18.8",
+    "@arkstack/jobs": "^0.18.8"
   },
   "peerDependenciesMeta": {
     "@arkstack/driver-express": {