@arkstack/notifications 0.18.12 → 0.19.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { RequestException, config as config$1, env, getModel } from "@arkstack/common";
+import { RequestException, config, env, getModel } from "@arkstack/common";
 import { Job } from "@arkstack/jobs";
 import { mkdir, writeFile } from "node:fs/promises";
 import path, { join } from "node:path";
@@ -34,7 +34,7 @@ var SendNotification = class extends Job {
 //#region src/config.ts
 const configure = (key, defaultValue) => {
 	try {
-		return config$1(`notifications.${key}`, defaultValue);
+		return config(`notifications.${key}`, defaultValue);
 	} catch {
 		return defaultValue;
 	}
@@ -77,18 +77,17 @@ var UserNotificationCenter = class {
 		return getModel("UserNotification");
 	}
 	/**
-	* Create a database notification then broadcast it using the configured realtime driver
-	* 
-	* @param user 
-	* @param payload 
+	* 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 async send(user, payload, channel = []) {
-		return await Notification.realtime().store().channel(this.resolvePushTokens(user.pushTokens ?? channel)).meta(payload.meta).type(payload.type).subject(payload.title).action(payload.actionText, payload.actionLink).send(payload.description, payload.title, void 0, payload);
-	}
-	static resolvePushTokens(pushTokens) {
-		if (!pushTokens) return [];
-		if (Array.isArray(pushTokens)) return pushTokens.map((e) => typeof e === "string" ? e : e.token);
-		return [typeof pushTokens === "string" ? pushTokens : pushTokens.token];
+	static async send(user, payload, devices) {
+		const notification = Notification.realtime().store().recipient(user).meta(payload.meta).type(payload.type).subject(payload.title).action(payload.actionText, payload.actionLink);
+		if (devices?.length) notification.devices(devices);
+		return await notification.send(payload.description, payload.title, void 0, payload);
 	}
 	/**
 	* Create a database notification
@@ -204,9 +203,11 @@ var DbNotification = class extends NotificationContract {
 	* Broadcast the notification using the default realtime driver.
 	* 
 	* @param realtime Set to false to disable realtime broadcast
+	* @returns
 	*/
 	broadcast(realtime = true) {
 		this.realtime = realtime;
+		return this;
 	}
 	async create(user, payload) {
 		getModel("UserNotification");
@@ -423,7 +424,7 @@ var MailNotification = class extends NotificationContract {
 	*/
 	async send(message, subject, recipient, data) {
 		const mergedData = {
-			app_name: config$1("app.name", "Arkstack"),
+			app_name: config("app.name", "Arkstack"),
 			...this.mergeData(data)
 		};
 		const resolvedSubject = interpolate(subject ?? this.subjectLine ?? "", mergedData);
@@ -499,6 +500,206 @@ var MailNotification = class extends NotificationContract {
 	}
 };
 //#endregion
+//#region src/drivers/realtime/firebaseAdmin.ts
+/**
+* Initialize, or reuse, a named Firebase Admin app.
+*
+* Credentials come from the service account file at `admin_sdk_path` when it
+* exists, otherwise from the inline `project_id` / `client_email` / `private_key`.
+*
+* @param options
+* @param suffix   Distinguishes apps that need different init options.
+* @param extra    Extra `initializeApp` options, such as `databaseURL`.
+* @returns
+*/
+const firebaseAdminApp = async (options, suffix = "", extra = {}) => {
+	const app = await import("firebase-admin/app").catch(() => {
+		throw new Error("The \"firebase-admin\" package is required for the Firebase realtime transports. Install it with `npm i firebase-admin`.");
+	});
+	const adminsdk = path.join(process.cwd(), options.admin_sdk_path ?? env("FIREBASE_ADMINSDK", "firebase-adminsdk.json"));
+	let serviceAccount;
+	try {
+		if (existsSync(adminsdk)) serviceAccount = JSON.parse(readFileSync(adminsdk, { encoding: "utf-8" }));
+	} catch {}
+	const credential = app.cert(serviceAccount ?? {
+		projectId: options.project_id ?? env("FIREBASE_PROJECT_ID", ""),
+		clientEmail: options.client_email ?? env("FIREBASE_CLIENT_EMAIL", ""),
+		privateKey: (options.private_key ?? env("FIREBASE_PRIVATE_KEY", ""))?.replace(/\\n/g, "\n")
+	});
+	const name = String(options.app_name ?? env("FIREBASE_APP_NAME", "arkstack-realtime")).replaceAll(" ", "-").toLowerCase() + suffix;
+	return app.getApps().find((a) => a.name === name) ?? app.initializeApp({
+		credential,
+		...extra
+	}, name);
+};
+/**
+* The public web app settings a browser Firebase client is initialized with.
+*
+* @param options
+* @returns
+*/
+const firebaseWebConfig = (options) => ({
+	apiKey: options.web?.api_key ?? env("FIREBASE_API_KEY", ""),
+	authDomain: options.web?.auth_domain ?? env("FIREBASE_AUTH_DOMAIN", ""),
+	projectId: options.project_id ?? env("FIREBASE_PROJECT_ID", ""),
+	appId: options.web?.app_id ?? env("FIREBASE_APP_ID", ""),
+	messagingSenderId: options.web?.messaging_sender_id ?? env("FIREBASE_MESSAGING_SENDER_ID", ""),
+	vapidKey: options.web?.vapid_key ?? env("FIREBASE_VAPID_KEY", "")
+});
+//#endregion
+//#region src/drivers/realtime/FirebaseDatabaseRealtimeDriver.ts
+/** Characters Realtime Database keys cannot contain. */
+const FORBIDDEN_KEY = /[.#$[\]/]/;
+/**
+* Encode a channel name into a single Realtime Database key.
+*
+* @param channel
+* @returns
+*/
+const firebaseChannelKey = (channel) => encodeURIComponent(channel).replace(/\./g, "%2E");
+/**
+* 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.
+*/
+var FirebaseDatabaseRealtimeDriver = class {
+	options;
+	servicesPromise;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	get root() {
+		return this.options.root ?? "arkstack/channels";
+	}
+	get indexRoot() {
+		return `${this.root}-index`;
+	}
+	get grantsRoot() {
+		return this.options.grants_root ?? "arkstack/grants";
+	}
+	get databaseURL() {
+		return this.options.database_url ?? env("FIREBASE_DATABASE_URL", "");
+	}
+	services() {
+		const databaseSpecifier = "firebase-admin/database";
+		const authSpecifier = "firebase-admin/auth";
+		this.servicesPromise ??= (async () => {
+			const [instance, database, auth] = await Promise.all([
+				firebaseAdminApp(this.options, "-database", { databaseURL: this.databaseURL }),
+				import(databaseSpecifier),
+				import(authSpecifier)
+			]);
+			return {
+				database: database.getDatabase(instance),
+				auth: auth.getAuth(instance)
+			};
+		})();
+		return this.servicesPromise;
+	}
+	/**
+	* 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
+	*/
+	async broadcast(channel, event, payload, _delivery) {
+		const { database } = await this.services();
+		const channels = Array.isArray(channel) ? channel : [channel];
+		const at = { ".sv": "timestamp" };
+		const updates = {};
+		const keys = [];
+		for (const name of channels) {
+			const key = database.ref(this.root).push().key;
+			const channelKey = firebaseChannelKey(name);
+			updates[`${this.root}/${channelKey}/${key}`] = {
+				event,
+				payload,
+				at
+			};
+			updates[`${this.indexRoot}/${key}`] = {
+				channel: channelKey,
+				at
+			};
+			keys.push(key);
+		}
+		await database.ref().update(updates);
+		return keys;
+	}
+	/**
+	* Grant `uid` read access to an already authorized channel and mint the
+	* custom token the client signs in with.
+	*
+	* @param uid
+	* @param channel
+	* @returns
+	*/
+	async auth(uid, channel) {
+		if (!uid || FORBIDDEN_KEY.test(uid)) throw new Error(`Realtime: "${uid}" cannot be used as a Firebase uid`);
+		const { database, auth } = await this.services();
+		const expiresAt = Date.now() + (this.options.grant_ttl ?? 3600) * 1e3;
+		await database.ref().update({ [`${this.grantsRoot}/${uid}/${firebaseChannelKey(channel)}`]: expiresAt });
+		return {
+			token: await auth.createCustomToken(uid),
+			expires_at: expiresAt
+		};
+	}
+	/**
+	* 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.
+	*/
+	async prune(maxAgeSeconds, limit = 500) {
+		const { database } = await this.services();
+		const cutoff = Date.now() - maxAgeSeconds * 1e3;
+		const snapshot = await database.ref(this.indexRoot).orderByChild("at").endAt(cutoff).limitToFirst(limit).once("value");
+		const updates = {};
+		snapshot.forEach((child) => {
+			const entry = child.val();
+			if (child.key && entry?.channel) {
+				updates[`${this.root}/${entry.channel}/${child.key}`] = null;
+				updates[`${this.indexRoot}/${child.key}`] = null;
+			}
+		});
+		const deleted = Object.keys(updates).length / 2;
+		if (deleted > 0) await database.ref().update(updates);
+		return deleted;
+	}
+	/**
+	* Public settings a browser client needs to read channels.
+	*
+	* @returns
+	*/
+	clientConfig() {
+		return {
+			...firebaseWebConfig(this.options),
+			databaseURL: this.databaseURL,
+			root: this.root
+		};
+	}
+	/**
+	* Use `Broadcast.routes()`, which authorizes channels through the registry.
+	*
+	* @param _authEndpoint
+	* @param _middleware
+	* @param _channelPrefix
+	*/
+	async registerAuthRoute(_authEndpoint, _middleware, _channelPrefix) {}
+};
+//#endregion
 //#region src/drivers/realtime/FirebaseRealtimeDriver.ts
 /** FCM caps a multicast at 500 tokens per call. */
 const MULTICAST_LIMIT = 500;
@@ -525,24 +726,9 @@ var FirebaseRealtimeDriver = class {
 		this.options = options;
 	}
 	messaging() {
-		const appSpecifier = "firebase-admin/app";
-		const messagingSpecifier = "firebase-admin/messaging";
+		const specifier = "firebase-admin/messaging";
 		this.messagingPromise ??= (async () => {
-			const [app, messaging] = await Promise.all([import(appSpecifier), import(messagingSpecifier)]).catch(() => {
-				throw new Error("The \"firebase-admin\" package is required for the Firebase realtime transport. Install it with `npm i firebase-admin`.");
-			});
-			const adminsdk = path.join(process.cwd(), this.options.admin_sdk_path ?? env("FIREBASE_ADMINSDK", "firebase-adminsdk.json"));
-			let serviceAccount;
-			try {
-				if (existsSync(adminsdk)) serviceAccount = JSON.parse(readFileSync(adminsdk, { encoding: "utf-8" }));
-			} catch {}
-			const credential = app.cert(serviceAccount ?? {
-				projectId: this.options.project_id ?? env("FIREBASE_PROJECT_ID", ""),
-				clientEmail: this.options.client_email ?? env("FIREBASE_CLIENT_EMAIL", ""),
-				privateKey: (this.options.private_key ?? env("FIREBASE_PRIVATE_KEY", ""))?.replace(/\\n/g, "\n")
-			});
-			const name = String(this.options.app_name ?? env("FIREBASE_APP_NAME", "arkstack-realtime")).replaceAll(" ", "-").toLowerCase();
-			const instance = app.getApps().find((a) => a.name === name) ?? app.initializeApp({ credential }, name);
+			const [instance, messaging] = await Promise.all([firebaseAdminApp(this.options), import(specifier)]);
 			return messaging.getMessaging(instance);
 		})();
 		return this.messagingPromise;
@@ -674,6 +860,15 @@ var FirebaseRealtimeDriver = class {
 		return Object.keys(block).length > 0 ? { [key]: block } : {};
 	}
 	/**
+	* Public Firebase web settings for clients that receive messages or register
+	* device tokens.
+	*
+	* @returns
+	*/
+	clientConfig() {
+		return firebaseWebConfig(this.options);
+	}
+	/**
 	* Firebase channels do not require server-side authorization.
 	* 
 	* @param _socketId 
@@ -725,6 +920,74 @@ var FirebaseRealtimeDriver = class {
 	}
 };
 //#endregion
+//#region src/drivers/realtime/MemoryRealtimeDriver.ts
+const BUFFER_KEY = Symbol.for("arkstack.realtime.memory");
+/**
+* The recorded broadcasts. Kept on `globalThis` so code loaded through separate
+* module graphs (an app's routes and its tests, say) shares one buffer.
+*
+* @returns
+*/
+const buffer = () => {
+	const store = globalThis;
+	return store[BUFFER_KEY] ??= [];
+};
+/**
+* Records every broadcast in process instead of sending it, for tests and local
+* development. Read them with {@link MemoryRealtimeDriver.broadcasts}.
+*/
+var MemoryRealtimeDriver = class {
+	/**
+	* Every broadcast recorded since the last {@link clear}.
+	*
+	* @returns
+	*/
+	static broadcasts() {
+		return buffer();
+	}
+	/**
+	* Forget all recorded broadcasts.
+	*/
+	static clear() {
+		buffer().length = 0;
+	}
+	async broadcast(channel, event, payload, delivery) {
+		buffer().push({
+			channel,
+			event,
+			payload,
+			delivery
+		});
+	}
+	async auth(_socketId, channel) {
+		return { auth: `memory:${channel}` };
+	}
+	async registerAuthRoute() {}
+	clientConfig() {
+		return {};
+	}
+};
+//#endregion
+//#region src/drivers/realtime/PollingRealtimeDriver.ts
+/**
+* A transport that pushes nothing. Clients are told to poll on an interval
+* instead, so an app works without realtime infrastructure.
+*/
+var PollingRealtimeDriver = class {
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	async broadcast(_channel, _event, _payload, _delivery) {}
+	async auth() {
+		return {};
+	}
+	async registerAuthRoute() {}
+	clientConfig() {
+		return { interval: this.options.interval ?? 5e3 };
+	}
+};
+//#endregion
 //#region src/drivers/realtime/PusherRealtimeDriver.ts
 /**
 * Broadcasts notifications over [Pusher Channels](https://pusher.com/channels).
@@ -744,16 +1007,56 @@ var PusherRealtimeDriver = class PusherRealtimeDriver {
 			const mod = await import(specifier).catch(() => {
 				throw new Error("The \"pusher\" package is required for the Pusher realtime transport. Install it with `npm i pusher`.");
 			});
-			return new (mod.default ?? mod)({
+			const Pusher = mod.default ?? mod;
+			const { host, port } = this.server();
+			return new Pusher({
 				appId: this.options.app_id ?? env("PUSHER_APP_ID", ""),
-				key: this.options.key ?? env("PUSHER_KEY", ""),
+				key: this.key(),
 				secret: this.options.secret ?? env("PUSHER_SECRET", ""),
-				cluster: this.options.cluster ?? env("PUSHER_CLUSTER", "mt1"),
-				useTLS: this.options.use_tls ?? true
+				cluster: this.cluster(),
+				useTLS: this.useTLS(),
+				...host ? {
+					host,
+					port: port ? String(port) : void 0
+				} : {}
 			});
 		})();
 		return this.clientPromise;
 	}
+	key() {
+		return this.options.key ?? env("PUSHER_KEY", "");
+	}
+	cluster() {
+		return this.options.cluster ?? env("PUSHER_CLUSTER", "mt1");
+	}
+	useTLS() {
+		return this.options.use_tls ?? true;
+	}
+	server() {
+		return {
+			host: this.options.host ?? (env("PUSHER_HOST", "") || void 0),
+			port: this.options.port ?? (Number(env("PUSHER_PORT", 0)) || void 0)
+		};
+	}
+	/**
+	* Public settings a `pusher-js` client needs, including the self-hosted
+	* server address when `host` is set.
+	*
+	* @returns
+	*/
+	clientConfig() {
+		const { host, port } = this.server();
+		return {
+			key: this.key(),
+			cluster: this.cluster(),
+			forceTLS: this.useTLS(),
+			...host ? {
+				wsHost: host,
+				wsPort: port,
+				wssPort: port
+			} : {}
+		};
+	}
 	/**
 	* `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
@@ -797,28 +1100,257 @@ var PusherRealtimeDriver = class PusherRealtimeDriver {
 	* @param channelPrefix 
 	*/
 	async registerAuthRoute(authEndpoint = "/realtime/auth", middleware, channelPrefix) {
-		const client = await this.client();
-		for (const [name, path] of Object.entries({
-			express: "@arkstack/driver-express",
-			h3: "@arkstack/driver-express"
-		})) {
-			const midsPath = `${path}/middlewares`;
-			try {
-				const { Router } = await import(path);
-				const { auth } = await import(midsPath);
-				const middlewares = new Set(Array.isArray(middleware) ? middleware.concat(auth) : [middleware, auth]);
-				Router.post(authEndpoint, ({ clearRequest, req }) => {
-					const channel = clearRequest.input("channel_name");
-					const socketId = clearRequest.input("socket_id");
-					const expected = channelPrefix ?? `${config("notifications.drivers.realtime.channel_prefix", "user.")}${req.user?.id ?? clearRequest.user?.id}`;
-					RequestException.abortIf(channel !== expected, "Channel access denied", 403);
-					return client.authorizeChannel(socketId, channel);
-				}).middleware(Array.from(middlewares));
-				break;
-			} catch (e) {
-				console.error(`Failed to register auth route for ${name}: ${e instanceof Error ? e.message : e}`);
+		for (const path of ["@arkstack/driver-express", "@arkstack/driver-h3"]) try {
+			const { Router } = await import(path);
+			const { auth } = await import(`${path}/middlewares`);
+			Router.post(authEndpoint, async ({ clearRequest, req }) => {
+				const user = req?.user ?? clearRequest.user;
+				const channel = clearRequest.input("channel_name");
+				const socketId = clearRequest.input("socket_id");
+				const allowed = channelPrefix ? channel === channelPrefix : await Broadcast.authorize(user, channel);
+				RequestException.abortIf(!allowed, "Channel access denied", 403);
+				return new Response(JSON.stringify(await this.auth(socketId, channel)), {
+					status: 200,
+					headers: { "content-type": "application/json" }
+				});
+			}).middleware([middleware ?? []].flat().concat(auth));
+			return;
+		} catch (e) {
+			console.error(`Failed to register auth route for ${path}: ${e instanceof Error ? e.message : e}`);
+		}
+	}
+};
+//#endregion
+//#region src/Broadcast.ts
+/**
+* The server side of realtime: builds transports from config, broadcasts
+* arbitrary events, and authorizes channel subscriptions against registered
+* channel rules for every transport.
+*/
+var Broadcast = class {
+	static rules = [];
+	static settings() {
+		return configure("drivers.realtime", {}) ?? {};
+	}
+	/**
+	* The configured streaming transport name.
+	*
+	* @returns
+	*/
+	static transport() {
+		return this.settings().transport ?? "pusher";
+	}
+	/**
+	* The prefix of the per-user notification channel.
+	*
+	* @returns
+	*/
+	static channelPrefix() {
+		return this.settings().channel_prefix ?? "user.";
+	}
+	/**
+	* 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(pattern, authorizer) {
+		const keys = [];
+		const source = pattern.split(/(\{[^}]+\})/).map((part) => {
+			const key = /^\{([^}]+)\}$/.exec(part)?.[1];
+			if (key) {
+				keys.push(key);
+				return "([^.]+)";
 			}
+			return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		}).join("");
+		this.rules = this.rules.filter((rule) => rule.pattern !== pattern);
+		this.rules.push({
+			pattern,
+			regex: new RegExp(`^${source}$`),
+			keys,
+			authorizer
+		});
+		return this;
+	}
+	/**
+	* Remove every registered channel rule.
+	*/
+	static forgetChannels() {
+		this.rules = [];
+	}
+	/**
+	* 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 async authorize(subject, channel) {
+		for (const rule of this.rules) {
+			const match = rule.regex.exec(channel);
+			if (match) {
+				const params = Object.fromEntries(rule.keys.map((key, index) => [key, match[index + 1]]));
+				return Boolean(await rule.authorizer(subject, params));
+			}
+		}
+		const id = subject?.id;
+		return id !== void 0 && id !== null && channel === `${this.channelPrefix()}${id}`;
+	}
+	/**
+	* Build a transport. Uses the configured `driverFactory` when there is one,
+	* otherwise the named or configured built-in.
+	*
+	* @param options
+	* @returns
+	*/
+	static driver(options = {}) {
+		const factory = options.driverFactory ?? this.settings().driverFactory;
+		if (factory) return factory();
+		const transport = options.transport ?? this.transport();
+		return this.make(transport, options[transport]);
+	}
+	/**
+	* Build a named built-in transport from its `transports.*` config.
+	*
+	* @param transport
+	* @param overrides
+	* @returns
+	*/
+	static make(transport, overrides = {}) {
+		const config = {
+			...configure(`transports.${transport}`, {}),
+			...overrides
+		};
+		switch (transport) {
+			case "firebase": return new FirebaseRealtimeDriver(config);
+			case "firebase-database": return new FirebaseDatabaseRealtimeDriver(config);
+			case "polling": return new PollingRealtimeDriver(config);
+			case "memory": return new MemoryRealtimeDriver();
+			case "pusher": return new PusherRealtimeDriver(config);
+			default: throw new Error(`Realtime: unknown transport "${transport}"`);
+		}
+	}
+	/**
+	* Broadcast an arbitrary event on one or more channels over the configured
+	* transport.
+	*
+	* @param channel
+	* @param event
+	* @param payload
+	* @param delivery
+	* @returns
+	*/
+	static async broadcast(channel, event, payload, delivery) {
+		if (Array.isArray(channel) && channel.length === 0) return;
+		return await this.driver().broadcast(channel, event, payload, delivery);
+	}
+	/**
+	* 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() {
+		const { push } = this.settings();
+		return push === "firebase" || push === void 0 && this.transport() === "firebase" ? this.make("firebase") : null;
+	}
+	/**
+	* A user's device tokens, from the configured `push_tokens` resolver or the
+	* user's `pushTokens` property.
+	*
+	* @param user
+	* @returns
+	*/
+	static async pushTokens(user) {
+		const resolver = this.settings().push_tokens;
+		const tokens = resolver ? await resolver(user) : user?.pushTokens;
+		if (!tokens) return [];
+		return (Array.isArray(tokens) ? tokens : [tokens]).map((token) => typeof token === "string" ? token : token?.token).filter((token) => !!token);
+	}
+	/**
+	* 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 async push(tokens, event, payload, delivery) {
+		const driver = this.pushDriver();
+		if (!driver || tokens.length === 0) return null;
+		return await driver.broadcast(tokens, event, payload, delivery);
+	}
+	/**
+	* 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 async handleAuth(subject, request, options = {}) {
+		const channel = request.channel_name;
+		RequestException.abortIf(!channel, "Missing channel_name", 422);
+		RequestException.abortIf(!await this.authorize(subject, channel), "Channel access denied", 403);
+		const driver = options.driver ?? this.driver();
+		if (driver instanceof FirebaseDatabaseRealtimeDriver) return await driver.auth(options.uid ?? String(subject?.id ?? ""), channel);
+		RequestException.abortIf(driver instanceof PusherRealtimeDriver && !request.socket_id, "Missing socket_id", 422);
+		return await driver.auth(request.socket_id ?? "", channel);
+	}
+	/**
+	* Public settings a `@arkstack/realtime` client is created from.
+	*
+	* @returns
+	*/
+	static clientConfig() {
+		const transport = this.transport();
+		const settings = this.settings();
+		const config = {
+			transport,
+			event: settings.event ?? "notification",
+			channelPrefix: this.channelPrefix()
+		};
+		config[transport] = this.driver().clientConfig?.() ?? {};
+		if (settings.push === "firebase" && transport !== "firebase") config.firebase = this.make("firebase").clientConfig?.() ?? {};
+		return config;
+	}
+	/**
+	* Register `POST {prefix}/auth` and `GET {prefix}/config`, both behind the
+	* framework `auth` middleware.
+	*
+	* @param options
+	*/
+	static async routes(options = {}) {
+		const prefix = options.prefix ?? "/realtime";
+		for (const path of ["@arkstack/driver-express", "@arkstack/driver-h3"]) try {
+			const { Router } = await import(path);
+			const { auth } = await import(`${path}/middlewares`);
+			const middleware = [options.middleware ?? []].flat().concat(auth);
+			Router.post(`${prefix}/auth`, async ({ clearRequest, req }) => {
+				const result = await this.handleAuth(req?.user ?? clearRequest.user, {
+					socket_id: clearRequest.input("socket_id"),
+					channel_name: clearRequest.input("channel_name")
+				});
+				return new Response(JSON.stringify(result ?? {}), {
+					status: 200,
+					headers: { "content-type": "application/json" }
+				});
+			}).middleware(middleware);
+			Router.get(`${prefix}/config`, () => this.clientConfig()).middleware(middleware);
+			return;
+		} catch {
+			continue;
 		}
+		throw new Error("Realtime: no supported HTTP driver is installed to register routes on");
 	}
 };
 //#endregion
@@ -842,29 +1374,22 @@ var RealtimeNotification = class extends NotificationContract {
 	shouldStore;
 	tagName;
 	isRetraction = false;
+	shouldPush;
+	deviceTokens;
 	deliveryOptions;
 	payload = {};
 	constructor(options = {}) {
 		super();
 		const driverConfig = configure("drivers.realtime", {});
-		const transport = options.transport ?? driverConfig?.transport ?? "pusher";
-		const transportConfig = configure(`transports.${transport}`, {});
 		this.channelName = options.channel;
 		this.eventName = options.event ?? driverConfig?.event ?? "notification";
-		this.channelPrefix = driverConfig?.channel_prefix ?? "user.";
+		this.channelPrefix = Broadcast.channelPrefix();
 		this.shouldStore = options.store ?? driverConfig?.store ?? false;
 		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({
-			...transportConfig,
-			...options.pusher
-		});
+		this.driver = Broadcast.driver(options);
 	}
 	from(_) {
 		return this;
@@ -881,14 +1406,7 @@ var RealtimeNotification = class extends NotificationContract {
 	* @returns 
 	*/
 	transport(transport, options) {
-		const transportConfig = configure(`transports.${transport}`, {});
-		this.driver = transport === "firebase" ? new FirebaseRealtimeDriver({
-			...transportConfig,
-			...options
-		}) : new PusherRealtimeDriver({
-			...transportConfig,
-			...options
-		});
+		this.driver = Broadcast.make(transport, options);
 		return this;
 	}
 	/**
@@ -1043,6 +1561,35 @@ var RealtimeNotification = class extends NotificationContract {
 		this.isRetraction = retract;
 		return 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 = true) {
+		this.shouldPush = push;
+		return this;
+	}
+	/**
+	* Push to these device tokens instead of the recipient's own.
+	*
+	* @param tokens
+	* @returns
+	*/
+	devices(tokens) {
+		this.deviceTokens = tokens;
+		this.shouldPush ??= true;
+		return this;
+	}
+	async resolveDevices() {
+		if (this.shouldPush === false) return [];
+		if (this.deviceTokens) return this.deviceTokens;
+		if (this.user) return await Broadcast.pushTokens(this.user);
+		return [];
+	}
 	resolveChannel() {
 		if (this.channelName !== void 0) return this.channelName;
 		if (this.user) return `${this.channelPrefix}${this.user.id}`;
@@ -1083,11 +1630,14 @@ var RealtimeNotification = class extends NotificationContract {
 			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, this.deliveryOptions);
+		const devices = await this.resolveDevices();
+		const push = await Broadcast.push(devices, this.eventName, payload, this.deliveryOptions);
 		return {
 			channel,
 			event: this.eventName,
 			payload,
-			stored
+			stored,
+			...push ? { push } : {}
 		};
 	}
 };
@@ -1284,4 +1834,4 @@ var UserNotification = class extends Model {
 	casts = { meta: "json" };
 };
 //#endregion
-export { AfricasTalkingSmsDriver, DbNotification, FirebaseRealtimeDriver, MailNotification, Notification, NotificationContract, PusherRealtimeDriver, RealtimeNotification, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, interpolate };
+export { AfricasTalkingSmsDriver, Broadcast, DbNotification, FirebaseDatabaseRealtimeDriver, FirebaseRealtimeDriver, MailNotification, MemoryRealtimeDriver, Notification, NotificationContract, PollingRealtimeDriver, PusherRealtimeDriver, RealtimeNotification, SmsNotification, TwilioSmsDriver, UserNotification, UserNotificationCenter, configure, firebaseChannelKey, interpolate };