@arkstack/realtime 0.18.12 → 0.19.1

package/dist/{RealtimeClient-CzrWnLtj.d.ts → RealtimeClient-MI224djP.d.ts}

@@ -23,7 +23,16 @@ interface RealtimeNotification {
   read_at: string | null;
   created_at: string;
 }
-type RealtimeTransportName = 'pusher' | 'firebase';
+/**
+ * Client transports, matching the server's `drivers.realtime.transport`.
+ *
+ * - `pusher`: Pusher Channels, or a self-hosted Pusher-protocol server via `wsHost`.
+ * - `firebase`: Firebase Cloud Messaging foreground messages.
+ * - `firebase-database`: Firebase Realtime Database channels.
+ * - `polling`: nothing is pushed; use {@link RealtimeClient.onPoll} to refetch.
+ * - `memory`: an in-process bus, for tests.
+ */
+type RealtimeTransportName = 'pusher' | 'firebase' | 'firebase-database' | 'polling' | 'memory';
 type NotificationHandler = (notification: RealtimeNotification) => void;
 /** Handles an arbitrary realtime event payload. */
 type RealtimeEventHandler<Payload = unknown> = (payload: Payload) => void;
@@ -58,6 +67,16 @@ interface RealtimeTransport {
    * Disconnect from a connected realtime channel
    */
   disconnect(): void | Promise<void>;
+  /**
+   * This device's push registration token, when the transport can issue one.
+   */
+  deviceToken?(): Promise<string | null>;
+  /**
+   * Set by transports that push nothing; clients should poll this often instead.
+   */
+  polling?: {
+    interval: number;
+  };
 }
 interface PusherClientConfig {
   key: string;
@@ -80,6 +99,11 @@ interface PusherClientConfig {
     params?: Record<string, string>;
   };
   forceTLS?: boolean;
+  /** A self-hosted Pusher-protocol server such as soketi. */
+  wsHost?: string;
+  wsPort?: number;
+  wssPort?: number;
+  enabledTransports?: Array<'ws' | 'wss'>;
 }
 interface FirebaseClientConfig {
   apiKey: string;
@@ -93,6 +117,29 @@ interface FirebaseClientConfig {
   /** Web push VAPID key used when requesting a messaging token. */
   vapidKey?: string;
 }
+interface FirebaseDatabaseClientConfig {
+  apiKey: string;
+  projectId: string;
+  databaseURL: string;
+  appId?: string;
+  authDomain?: string;
+  /** Database path that holds channel events (default `arkstack/channels`). */
+  root?: string;
+  /**
+   * Your API's base URL; channels are authorized at `{apiBase}/realtime/auth`.
+   * Ignored when {@link authEndpoint} is set.
+   */
+  apiBase?: string;
+  /** Endpoint that grants channel access and returns a Firebase custom token. */
+  authEndpoint?: string;
+  auth?: {
+    headers?: Record<string, string>;
+  };
+}
+interface PollingClientConfig {
+  /** How often, in milliseconds, {@link RealtimeClient.onPoll} handlers run (default 5000). */
+  interval?: number;
+}
 interface RealtimeConfig {
   transport?: RealtimeTransportName;
   /** Event name broadcasts are published under (default `notification`). */
@@ -101,6 +148,8 @@ interface RealtimeConfig {
   channelPrefix?: string;
   pusher?: PusherClientConfig;
   firebase?: FirebaseClientConfig;
+  'firebase-database'?: FirebaseDatabaseClientConfig;
+  polling?: PollingClientConfig;
   /** Inject a transport directly — bypasses the built-ins (tests, custom backends). */
   transportFactory?: () => RealtimeTransport | Promise<RealtimeTransport>;
 }
@@ -126,6 +175,11 @@ declare class RealtimeClient {
   channelFor(userId: string | number): string;
   private transport;
   private resolveTransport;
+  private required;
+  /**
+   * The configured transport name.
+   */
+  get transportName(): RealtimeTransportName;
   /**
    * Subscribe to a channel. Returns a function that unsubscribes.
    *
@@ -175,10 +229,27 @@ declare class RealtimeClient {
    * @param handler  Called with each incoming notification.
    */
   forUser(userId: string | number, handler: NotificationHandler): Promise<() => void>;
+  /**
+   * Run `handler` on an interval while the transport is `polling`, so a view
+   * can refetch what it would otherwise receive live. Does nothing on push
+   * transports. Returns a function that stops it.
+   *
+   * @param handler
+   * @param interval  Overrides the transport's advertised interval, in milliseconds.
+   * @returns
+   */
+  onPoll(handler: () => void, interval?: number): Promise<() => void>;
+  /**
+   * This device's push registration token, for registering with your API.
+   * Null when the transport cannot issue one.
+   *
+   * @returns
+   */
+  deviceToken(): Promise<string | null>;
   /** Tear down the underlying transport connection. */
   disconnect(): Promise<void>;
 }
 /** Create a new {@link RealtimeClient}. */
 declare const createRealtime: (config?: RealtimeConfig) => RealtimeClient;
 //#endregion
-export { PusherClientConfig as a, RealtimeNotification as c, RealtimeTransportName as d, NotificationHandler as i, RealtimeSubscription as l, createRealtime as n, RealtimeConfig as o, FirebaseClientConfig as r, RealtimeEventHandler as s, RealtimeClient as t, RealtimeTransport as u };
+export { NotificationHandler as a, RealtimeConfig as c, RealtimeSubscription as d, RealtimeTransport as f, FirebaseDatabaseClientConfig as i, RealtimeEventHandler as l, createRealtime as n, PollingClientConfig as o, RealtimeTransportName as p, FirebaseClientConfig as r, PusherClientConfig as s, RealtimeClient as t, RealtimeNotification as u };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as PusherClientConfig, c as RealtimeNotification, d as RealtimeTransportName, i as NotificationHandler, l as RealtimeSubscription, n as createRealtime, o as RealtimeConfig, r as FirebaseClientConfig, s as RealtimeEventHandler, t as RealtimeClient, u as RealtimeTransport } from "./RealtimeClient-CzrWnLtj.js";
+import { a as NotificationHandler, c as RealtimeConfig, d as RealtimeSubscription, f as RealtimeTransport, i as FirebaseDatabaseClientConfig, l as RealtimeEventHandler, n as createRealtime, o as PollingClientConfig, p as RealtimeTransportName, r as FirebaseClientConfig, s as PusherClientConfig, t as RealtimeClient, u as RealtimeNotification } from "./RealtimeClient-MI224djP.js";
 //#region src/transports/pusher.d.ts
 /**
  * Realtime transport backed by [pusher-js](https://github.com/pusher/pusher-js).
@@ -20,6 +20,47 @@ declare const createPusherTransport: (config: PusherClientConfig) => Promise<Rea
  */
 declare const createFirebaseTransport: (config: FirebaseClientConfig) => Promise<RealtimeTransport>;
 //#endregion
+//#region src/transports/firebase-database.d.ts
+/**
+ * Realtime transport backed by [Firebase Realtime Database](https://firebase.google.com/docs/database/web/start).
+ * `firebase` is an optional peer dependency imported lazily.
+ *
+ * Each subscription first asks the API to authorize the channel, which grants
+ * this user read access and returns a custom token to sign in with. Only events
+ * written after the transport connected are delivered.
+ *
+ * @param config
+ * @returns
+ */
+declare const createFirebaseDatabaseTransport: (config: FirebaseDatabaseClientConfig) => Promise<RealtimeTransport>;
+//#endregion
+//#region src/transports/polling.d.ts
+/**
+ * A transport that receives nothing. Subscriptions are accepted and stay
+ * silent; use {@link RealtimeClient.onPoll} to refetch on the advertised interval.
+ *
+ * @param config
+ * @returns
+ */
+declare const createPollingTransport: (config?: PollingClientConfig) => RealtimeTransport;
+//#endregion
+//#region src/transports/memory.d.ts
+/**
+ * Deliver an event to every in-process subscriber of `channel`, as a server
+ * broadcast would.
+ *
+ * @param channel
+ * @param event
+ * @param payload
+ */
+declare const emitMemoryEvent: (channel: string, event: string, payload: unknown) => void;
+/**
+ * An in-process transport for tests. Feed it with {@link emitMemoryEvent}.
+ *
+ * @returns
+ */
+declare const createMemoryTransport: () => RealtimeTransport;
+//#endregion
 //#region src/supersede.d.ts
 /**
  * Fold an incoming notification into a list, honouring tag supersession.
@@ -46,4 +87,4 @@ declare const createFirebaseTransport: (config: FirebaseClientConfig) => Promise
  */
 declare const supersede: (list: RealtimeNotification[], incoming: RealtimeNotification, limit?: number) => RealtimeNotification[];
 //#endregion
-export { type FirebaseClientConfig, type NotificationHandler, type PusherClientConfig, RealtimeClient, type RealtimeConfig, type RealtimeEventHandler, type RealtimeNotification, type RealtimeSubscription, type RealtimeTransport, type RealtimeTransportName, createFirebaseTransport, createPusherTransport, createRealtime, supersede };
+export { type FirebaseClientConfig, type FirebaseDatabaseClientConfig, type NotificationHandler, type PollingClientConfig, type PusherClientConfig, RealtimeClient, type RealtimeConfig, type RealtimeEventHandler, type RealtimeNotification, type RealtimeSubscription, type RealtimeTransport, type RealtimeTransportName, createFirebaseDatabaseTransport, createFirebaseTransport, createMemoryTransport, createPollingTransport, createPusherTransport, createRealtime, emitMemoryEvent, supersede };

package/dist/index.js

@@ -42,14 +42,39 @@ var RealtimeClient = class {
 	}
 	async resolveTransport() {
 		if (this.config.transportFactory) return await this.config.transportFactory();
-		if (this.config.transport === "firebase") {
-			if (!this.config.firebase) throw new Error("Realtime: `firebase` config is required for the Firebase transport");
-			const { createFirebaseTransport } = await Promise.resolve().then(() => firebase_exports);
-			return await createFirebaseTransport(this.config.firebase);
+		switch (this.transportName) {
+			case "firebase": {
+				const { createFirebaseTransport } = await Promise.resolve().then(() => firebase_exports);
+				return await createFirebaseTransport(this.required("firebase"));
+			}
+			case "firebase-database": {
+				const { createFirebaseDatabaseTransport } = await Promise.resolve().then(() => firebase_database_exports);
+				return await createFirebaseDatabaseTransport(this.required("firebase-database"));
+			}
+			case "polling": {
+				const { createPollingTransport } = await Promise.resolve().then(() => polling_exports);
+				return createPollingTransport(this.config.polling);
+			}
+			case "memory": {
+				const { createMemoryTransport } = await Promise.resolve().then(() => memory_exports);
+				return createMemoryTransport();
+			}
+			default: {
+				const { createPusherTransport } = await Promise.resolve().then(() => pusher_exports);
+				return await createPusherTransport(this.required("pusher"));
+			}
 		}
-		if (!this.config.pusher) throw new Error("Realtime: `pusher` config is required for the Pusher transport");
-		const { createPusherTransport } = await Promise.resolve().then(() => pusher_exports);
-		return await createPusherTransport(this.config.pusher);
+	}
+	required(name) {
+		const config = this.config[name];
+		if (!config) throw new Error(`Realtime: \`${name}\` config is required for the ${name} transport`);
+		return config;
+	}
+	/**
+	* The configured transport name.
+	*/
+	get transportName() {
+		return this.config.transport ?? "pusher";
 	}
 	/**
 	* Subscribe to a channel. Returns a function that unsubscribes.
@@ -117,6 +142,30 @@ var RealtimeClient = class {
 	async forUser(userId, handler) {
 		return await this.subscribe(this.channelFor(userId), handler);
 	}
+	/**
+	* Run `handler` on an interval while the transport is `polling`, so a view
+	* can refetch what it would otherwise receive live. Does nothing on push
+	* transports. Returns a function that stops it.
+	*
+	* @param handler
+	* @param interval  Overrides the transport's advertised interval, in milliseconds.
+	* @returns
+	*/
+	async onPoll(handler, interval) {
+		const transport = await this.transport();
+		if (!transport.polling) return () => {};
+		const timer = setInterval(handler, interval ?? transport.polling.interval);
+		return () => clearInterval(timer);
+	}
+	/**
+	* This device's push registration token, for registering with your API.
+	* Null when the transport cannot issue one.
+	*
+	* @returns
+	*/
+	async deviceToken() {
+		return await (await this.transport()).deviceToken?.() ?? null;
+	}
 	/** Tear down the underlying transport connection. */
 	async disconnect() {
 		if (!this.transportPromise) return;
@@ -145,7 +194,13 @@ const createPusherTransport = async (config) => {
 		cluster: config.cluster ?? "mt1",
 		forceTLS: config.forceTLS ?? true,
 		authEndpoint: config.authEndpoint ?? `${config.apiBase}/realtime/auth`,
-		auth: config.auth
+		auth: config.auth,
+		...config.wsHost ? {
+			wsHost: config.wsHost,
+			wsPort: config.wsPort,
+			wssPort: config.wssPort ?? config.wsPort,
+			enabledTransports: config.enabledTransports ?? ["ws", "wss"]
+		} : {}
 	});
 	const channels = /* @__PURE__ */ new Map();
 	return {
@@ -252,6 +307,10 @@ const createFirebaseTransport = async (config) => {
 			});
 			await databaseApi.remove(eventReference);
 		},
+		async deviceToken() {
+			const getToken = messagingMod.getToken;
+			return await getToken(messaging, config.vapidKey ? { vapidKey: config.vapidKey } : void 0) || null;
+		},
 		disconnect() {
 			messageUnsubscribers.forEach((off) => off());
 			messageUnsubscribers.clear();
@@ -261,4 +320,192 @@ const createFirebaseTransport = async (config) => {
 	};
 };
 //#endregion
-export { RealtimeClient, createFirebaseTransport, createPusherTransport, createRealtime, supersede };
+//#region src/transports/firebase-database.ts
+var firebase_database_exports = /* @__PURE__ */ __exportAll({ createFirebaseDatabaseTransport: () => createFirebaseDatabaseTransport });
+const APP_NAME = "arkstack-realtime-database";
+/**
+* Encode a channel name into a single Realtime Database key, matching the server.
+*
+* @param channel
+* @returns
+*/
+const channelKey = (channel) => encodeURIComponent(channel).replace(/\./g, "%2E");
+/**
+* The `uid` claim of a Firebase custom token.
+*
+* @param token
+* @returns
+*/
+const tokenUid = (token) => {
+	try {
+		const segment = token.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
+		return JSON.parse(atob(segment)).uid ?? null;
+	} catch {
+		return null;
+	}
+};
+/**
+* Realtime transport backed by [Firebase Realtime Database](https://firebase.google.com/docs/database/web/start).
+* `firebase` is an optional peer dependency imported lazily.
+*
+* Each subscription first asks the API to authorize the channel, which grants
+* this user read access and returns a custom token to sign in with. Only events
+* written after the transport connected are delivered.
+*
+* @param config
+* @returns
+*/
+const createFirebaseDatabaseTransport = async (config) => {
+	const [appMod, authMod, databaseMod] = await Promise.all([
+		import("firebase/app"),
+		import("firebase/auth"),
+		import("firebase/database")
+	]).catch(() => {
+		throw new Error("The \"firebase\" package is required for the Firebase database transport. Install it with `npm i firebase`.");
+	});
+	const app = appMod.getApps().find((existing) => existing.name === APP_NAME) ?? appMod.initializeApp({
+		apiKey: config.apiKey,
+		authDomain: config.authDomain,
+		projectId: config.projectId,
+		appId: config.appId,
+		databaseURL: config.databaseURL
+	}, APP_NAME);
+	const auth = authMod.getAuth(app);
+	const database = databaseMod.getDatabase(app, config.databaseURL);
+	const root = config.root ?? "arkstack/channels";
+	const endpoint = config.authEndpoint ?? `${config.apiBase}/realtime/auth`;
+	const listeners = /* @__PURE__ */ new Set();
+	const offset = await new Promise((resolve) => {
+		databaseMod.onValue(databaseMod.ref(database, ".info/serverTimeOffset"), (snapshot) => resolve(Number(snapshot.val()) || 0), { onlyOnce: true });
+	});
+	const since = Date.now() + offset;
+	let signing = Promise.resolve();
+	const authorize = async (channel) => {
+		const response = await fetch(endpoint, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				accept: "application/json",
+				...config.auth?.headers
+			},
+			body: JSON.stringify({ channel_name: channel })
+		});
+		if (!response.ok) throw new Error(`Realtime: channel "${channel}" was not authorized (${response.status})`);
+		const { token } = await response.json();
+		signing = signing.then(async () => {
+			if (auth.currentUser?.uid !== tokenUid(token)) await authMod.signInWithCustomToken(auth, token);
+		});
+		await signing;
+	};
+	return {
+		async subscribe(channel, event, handler) {
+			await authorize(channel);
+			const off = databaseMod.onChildAdded(databaseMod.query(databaseMod.ref(database, `${root}/${channelKey(channel)}`), databaseMod.orderByChild("at"), databaseMod.startAt(since)), (snapshot) => {
+				const value = snapshot.val();
+				if (value?.event === event) handler(value.payload);
+			});
+			listeners.add(off);
+			return {
+				channel,
+				unsubscribe() {
+					off();
+					listeners.delete(off);
+				}
+			};
+		},
+		async disconnect() {
+			listeners.forEach((off) => off());
+			listeners.clear();
+			await authMod.signOut(auth);
+		}
+	};
+};
+//#endregion
+//#region src/transports/polling.ts
+var polling_exports = /* @__PURE__ */ __exportAll({ createPollingTransport: () => createPollingTransport });
+/**
+* A transport that receives nothing. Subscriptions are accepted and stay
+* silent; use {@link RealtimeClient.onPoll} to refetch on the advertised interval.
+*
+* @param config
+* @returns
+*/
+const createPollingTransport = (config = {}) => ({
+	polling: { interval: config.interval ?? 5e3 },
+	subscribe(channel) {
+		return {
+			channel,
+			unsubscribe() {}
+		};
+	},
+	disconnect() {}
+});
+//#endregion
+//#region src/transports/memory.ts
+var memory_exports = /* @__PURE__ */ __exportAll({
+	createMemoryTransport: () => createMemoryTransport,
+	emitMemoryEvent: () => emitMemoryEvent
+});
+const BUS_KEY = Symbol.for("arkstack.realtime.client-memory");
+/**
+* The in-process bus, kept on `globalThis` so every module copy shares it.
+*
+* @returns
+*/
+const bus = () => {
+	const store = globalThis;
+	return store[BUS_KEY] ??= /* @__PURE__ */ new Map();
+};
+/**
+* Deliver an event to every in-process subscriber of `channel`, as a server
+* broadcast would.
+*
+* @param channel
+* @param event
+* @param payload
+*/
+const emitMemoryEvent = (channel, event, payload) => {
+	bus().get(channel)?.forEach((listener) => {
+		if (listener.event === event) listener.handler(payload);
+	});
+};
+/**
+* An in-process transport for tests. Feed it with {@link emitMemoryEvent}.
+*
+* @returns
+*/
+const createMemoryTransport = () => {
+	const own = /* @__PURE__ */ new Set();
+	return {
+		subscribe(channel, event, handler) {
+			const listener = {
+				event,
+				handler
+			};
+			const listeners = bus().get(channel) ?? /* @__PURE__ */ new Set();
+			const entry = {
+				channel,
+				listener
+			};
+			listeners.add(listener);
+			bus().set(channel, listeners);
+			own.add(entry);
+			return {
+				channel,
+				unsubscribe() {
+					listeners.delete(listener);
+					own.delete(entry);
+				}
+			};
+		},
+		trigger(channel, event, payload) {
+			emitMemoryEvent(channel, event, payload);
+		},
+		disconnect() {
+			own.forEach(({ channel, listener }) => bus().get(channel)?.delete(listener));
+			own.clear();
+		}
+	};
+};
+//#endregion
+export { RealtimeClient, createFirebaseDatabaseTransport, createFirebaseTransport, createMemoryTransport, createPollingTransport, createPusherTransport, createRealtime, emitMemoryEvent, supersede };

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
-import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CzrWnLtj.js";
+import { t as RealtimeClient, u as RealtimeNotification } from "../RealtimeClient-MI224djP.js";
 //#region src/react/index.d.ts
 interface UseNotificationsOptions {
   /** Cap the number of retained notifications (newest kept). Default: unbounded. */

package/dist/vue/index.d.ts

@@ -1,4 +1,4 @@
-import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CzrWnLtj.js";
+import { t as RealtimeClient, u as RealtimeNotification } from "../RealtimeClient-MI224djP.js";
 import { ComputedRef, Ref } from "vue";
 //#region src/vue/index.d.ts
 interface UseNotificationsOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/realtime",
-  "version": "0.18.12",
+  "version": "0.19.1",
   "type": "module",
   "description": "Client for consuming Arkstack realtime notifications (Pusher/Firebase), with framework-agnostic core plus React and Vue bindings.",
   "homepage": "https://arkstack.toneflix.net/guide/notifications",