@arkstack/realtime 0.17.22 → 0.17.24

package/README.md

@@ -44,6 +44,28 @@ unsubscribe();
 await realtime.disconnect();
 ```
 
+### Client events
+
+Pusher private and presence channels can send ephemeral client events (often
+called whispers). Subscribe to the channel before sending an event:
+
+```ts
+const stopTyping = await realtime.listenForWhisper(
+  'private-room.7',
+  'typing',
+  ({ userId }) => console.log(`${userId} is typing`),
+);
+
+await realtime.whisper('private-room.7', 'typing', { userId: user.id });
+stopTyping();
+```
+
+The `client-` prefix is added automatically. Pusher sends client events over its
+private/presence channel. Firebase uses Realtime Database to publish the same
+ephemeral events across connected clients. Use `listen(channel, event, handler)`
+and `trigger(channel, event, payload)` when you need the lower-level APIs with
+exact event names.
+
 Each `notification` matches the payload broadcast by the server:
 
 ```ts
@@ -115,10 +137,16 @@ const realtime = createRealtime({
     projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
     appId: import.meta.env.VITE_FIREBASE_APP_ID,
     messagingSenderId: import.meta.env.VITE_FIREBASE_SENDER_ID,
+    databaseURL: import.meta.env.VITE_FIREBASE_DATABASE_URL,
   },
 });
 ```
 
+Firebase client events are written below `arkstack/client-events` in Realtime
+Database and removed immediately after publishing. Configure Firebase Security
+Rules for the channels your authenticated clients may read and write. Override
+the root with `firebase.clientEventsPath` when needed.
+
 ## Custom transport
 
 Provide `transportFactory` to bridge any backend (a raw WebSocket, SSE, a test double, …):
@@ -146,6 +174,9 @@ const realtime = createRealtime({ transportFactory: () => transport });
 
 - `createRealtime(config)` — create a `RealtimeClient`. Config: `transport` (`'pusher'` | `'firebase'`), `event` (default `notification`), `channelPrefix` (default `user.`), `pusher`/`firebase` credentials, or a custom `transportFactory`.
 - `client.subscribe(channel, handler)` / `client.forUser(userId, handler)` — subscribe; returns an unsubscribe function.
+- `client.listen(channel, event, handler)` — listen for an arbitrary event.
+- `client.listenForWhisper(channel, event, handler)` / `client.whisper(channel, event, payload)` — receive and send Pusher client events.
+- `client.trigger(channel, event, payload)` — emit an exact event name through a transport that supports it.
 - `client.channelFor(userId)` — the per-user channel name.
 - `client.disconnect()` — tear down the transport connection.
 - `@arkstack/realtime/react` — `useNotifications(client, channel, { limit? })` → `{ notifications, latest, clear }`.

package/dist/{RealtimeClient-BlV9xSHd.d.ts → RealtimeClient-CpYmOGZa.d.ts}

@@ -17,6 +17,8 @@ interface RealtimeNotification {
 }
 type RealtimeTransportName = 'pusher' | 'firebase';
 type NotificationHandler = (notification: RealtimeNotification) => void;
+/** Handles an arbitrary realtime event payload. */
+type RealtimeEventHandler<Payload = unknown> = (payload: Payload) => void;
 /** A live subscription to one channel; call `unsubscribe()` to stop listening. */
 interface RealtimeSubscription {
   channel: string;
@@ -28,7 +30,25 @@ interface RealtimeSubscription {
  * supplied via {@link RealtimeConfig.transportFactory} for custom backends/tests.
  */
 interface RealtimeTransport {
-  subscribe(channel: string, event: string, handler: NotificationHandler): RealtimeSubscription | Promise<RealtimeSubscription>;
+  /**
+   * Subscribe to a realtime channel
+   *
+   * @param channel
+   * @param event
+   * @param handler
+   */
+  subscribe(channel: string, event: string, handler: RealtimeEventHandler): RealtimeSubscription | Promise<RealtimeSubscription>;
+  /**
+   * Emit an event from the connected client, when supported by the transport.
+   *
+   * @param channel
+   * @param event
+   * @param payload
+   */
+  trigger?(channel: string, event: string, payload: unknown): void | Promise<void>;
+  /**
+   * Disconnect from a connected realtime channel
+   */
   disconnect(): void | Promise<void>;
 }
 interface PusherClientConfig {
@@ -58,6 +78,10 @@ interface FirebaseClientConfig {
   projectId: string;
   appId: string;
   messagingSenderId: string;
+  /** Realtime Database URL. Uses the Firebase project's default database when omitted. */
+  databaseURL?: string;
+  /** Root path used for ephemeral client events (default `arkstack/client-events`). */
+  clientEventsPath?: string;
   /** Web push VAPID key used when requesting a messaging token. */
   vapidKey?: string;
 }
@@ -85,7 +109,12 @@ declare class RealtimeClient {
   private readonly event;
   private readonly channelPrefix;
   constructor(config?: RealtimeConfig);
-  /** The channel name a given user's notifications are broadcast on. */
+  /**
+   * The channel name a given user's notifications are broadcast on.
+   *
+   * @param userId
+   * @returns
+   */
   channelFor(userId: string | number): string;
   private transport;
   private resolveTransport;
@@ -96,6 +125,41 @@ declare class RealtimeClient {
    * @param handler  Called with each incoming notification.
    */
   subscribe(channel: string, handler: NotificationHandler): Promise<() => void>;
+  /**
+   * Listen for an arbitrary event on a channel.
+   *
+   * @param channel
+   * @param event
+   * @param handler
+   * @returns
+   */
+  listen<Payload = unknown>(channel: string, event: string, handler: RealtimeEventHandler<Payload>): Promise<() => void>;
+  /**
+   * Listen for a client event (`client-{event}`).
+   *
+   * @param channel
+   * @param event
+   * @param handler
+   * @returns
+   */
+  listenForWhisper<Payload = unknown>(channel: string, event: string, handler: RealtimeEventHandler<Payload>): Promise<() => void>;
+  /**
+   * Emit a client event (`client-{event}`) on a subscribed channel.
+   *
+   * @param channel
+   * @param event
+   * @param payload
+   */
+  whisper<Payload = unknown>(channel: string, event: string, payload: Payload): Promise<void>;
+  /**
+   * Emit an event through a transport that supports client-originated events.
+   *
+   * @param channel
+   * @param event
+   * @param payload
+   */
+  trigger<Payload = unknown>(channel: string, event: string, payload: Payload): Promise<void>;
+  private clientEventName;
   /**
    * Subscribe to a user's channel (`{channelPrefix}{userId}`).
    *
@@ -106,7 +170,7 @@ declare class RealtimeClient {
   /** Tear down the underlying transport connection. */
   disconnect(): Promise<void>;
 }
-/** Create a {@link RealtimeClient}. */
+/** Create a new {@link RealtimeClient}. */
 declare const createRealtime: (config?: RealtimeConfig) => RealtimeClient;
 //#endregion
-export { PusherClientConfig as a, RealtimeSubscription as c, NotificationHandler as i, RealtimeTransport as l, createRealtime as n, RealtimeConfig as o, FirebaseClientConfig as r, RealtimeNotification as s, RealtimeClient as t, RealtimeTransportName as u };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as PusherClientConfig, c as RealtimeSubscription, i as NotificationHandler, l as RealtimeTransport, n as createRealtime, o as RealtimeConfig, r as FirebaseClientConfig, s as RealtimeNotification, t as RealtimeClient, u as RealtimeTransportName } from "./RealtimeClient-BlV9xSHd.js";
+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-CpYmOGZa.js";
 //#region src/transports/pusher.d.ts
 /**
  * Realtime transport backed by [pusher-js](https://github.com/pusher/pusher-js).
@@ -20,4 +20,4 @@ declare const createPusherTransport: (config: PusherClientConfig) => Promise<Rea
  */
 declare const createFirebaseTransport: (config: FirebaseClientConfig) => Promise<RealtimeTransport>;
 //#endregion
-export { type FirebaseClientConfig, type NotificationHandler, type PusherClientConfig, RealtimeClient, type RealtimeConfig, type RealtimeNotification, type RealtimeSubscription, type RealtimeTransport, type RealtimeTransportName, createFirebaseTransport, createPusherTransport, createRealtime };
+export { type FirebaseClientConfig, type NotificationHandler, type PusherClientConfig, RealtimeClient, type RealtimeConfig, type RealtimeEventHandler, type RealtimeNotification, type RealtimeSubscription, type RealtimeTransport, type RealtimeTransportName, createFirebaseTransport, createPusherTransport, createRealtime };

package/dist/index.js

@@ -26,7 +26,12 @@ var RealtimeClient = class {
 		this.event = config.event ?? "notification";
 		this.channelPrefix = config.channelPrefix ?? "user.";
 	}
-	/** The channel name a given user's notifications are broadcast on. */
+	/**
+	* The channel name a given user's notifications are broadcast on.
+	* 
+	* @param userId 
+	* @returns 
+	*/
 	channelFor(userId) {
 		return `${this.channelPrefix}${userId}`;
 	}
@@ -52,10 +57,57 @@ var RealtimeClient = class {
 	* @param handler  Called with each incoming notification.
 	*/
 	async subscribe(channel, handler) {
-		const subscription = await (await this.transport()).subscribe(channel, this.event, handler);
+		return await this.listen(channel, this.event, handler);
+	}
+	/**
+	* Listen for an arbitrary event on a channel.
+	*
+	* @param channel
+	* @param event
+	* @param handler
+	* @returns
+	*/
+	async listen(channel, event, handler) {
+		const subscription = await (await this.transport()).subscribe(channel, event, handler);
 		return () => subscription.unsubscribe();
 	}
 	/**
+	* Listen for a client event (`client-{event}`).
+	*
+	* @param channel
+	* @param event
+	* @param handler
+	* @returns
+	*/
+	async listenForWhisper(channel, event, handler) {
+		return await this.listen(channel, this.clientEventName(event), handler);
+	}
+	/**
+	* Emit a client event (`client-{event}`) on a subscribed channel.
+	*
+	* @param channel
+	* @param event
+	* @param payload
+	*/
+	async whisper(channel, event, payload) {
+		await this.trigger(channel, this.clientEventName(event), payload);
+	}
+	/**
+	* Emit an event through a transport that supports client-originated events.
+	*
+	* @param channel
+	* @param event
+	* @param payload
+	*/
+	async trigger(channel, event, payload) {
+		const transport = await this.transport();
+		if (!transport.trigger) throw new Error("Realtime: the configured transport does not support client events");
+		await transport.trigger(channel, event, payload);
+	}
+	clientEventName(event) {
+		return event.startsWith("client-") ? event : `client-${event}`;
+	}
+	/**
 	* Subscribe to a user's channel (`{channelPrefix}{userId}`).
 	*
 	* @param userId   The user id.
@@ -71,7 +123,7 @@ var RealtimeClient = class {
 		this.transportPromise = void 0;
 	}
 };
-/** Create a {@link RealtimeClient}. */
+/** Create a new {@link RealtimeClient}. */
 const createRealtime = (config = {}) => new RealtimeClient(config);
 //#endregion
 //#region src/transports/pusher.ts
@@ -94,20 +146,36 @@ const createPusherTransport = async (config) => {
 		authEndpoint: config.authEndpoint ?? `${config.apiBase}/realtime/auth`,
 		auth: config.auth
 	});
+	const channels = /* @__PURE__ */ new Map();
 	return {
 		subscribe(channel, event, handler) {
-			const subscription = client.subscribe(channel);
+			const active = channels.get(channel);
+			const subscription = active?.channel ?? client.subscribe(channel);
 			const listener = (data) => handler(data);
+			channels.set(channel, {
+				channel: subscription,
+				subscriptions: (active?.subscriptions ?? 0) + 1
+			});
 			subscription.bind(event, listener);
 			return {
 				channel,
 				unsubscribe() {
 					subscription.unbind(event, listener);
-					client.unsubscribe(channel);
+					const current = channels.get(channel);
+					if (!current || current.subscriptions <= 1) {
+						channels.delete(channel);
+						client.unsubscribe(channel);
+					} else current.subscriptions--;
 				}
 			};
 		},
+		trigger(channel, event, payload) {
+			const subscription = channels.get(channel)?.channel;
+			if (!subscription) throw new Error(`Realtime: subscribe to channel "${channel}" before triggering client events`);
+			if (!subscription.trigger(event, payload)) throw new Error(`Realtime: failed to trigger client event "${event}" on channel "${channel}"`);
+		},
 		disconnect() {
+			channels.clear();
 			client.disconnect();
 		}
 	};
@@ -115,6 +183,10 @@ const createPusherTransport = async (config) => {
 //#endregion
 //#region src/transports/firebase.ts
 var firebase_exports = /* @__PURE__ */ __exportAll({ createFirebaseTransport: () => createFirebaseTransport });
+const pathSegment = (value) => encodeURIComponent(value).replace(/\./g, "%2E");
+const isFirebaseClientEvent = (value) => {
+	return typeof value === "object" && value !== null && "sender" in value && "payload" in value;
+};
 /**
 * Realtime transport backed by [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/js/receive)
 * foreground messages. `firebase` is an optional peer dependency imported lazily.
@@ -123,30 +195,68 @@ var firebase_exports = /* @__PURE__ */ __exportAll({ createFirebaseTransport: ()
 * messages are matched by `event` and the JSON-encoded payload is parsed back.
 */
 const createFirebaseTransport = async (config) => {
-	const [appMod, messagingMod] = await Promise.all([import("firebase/app"), import("firebase/messaging")]).catch(() => {
+	const [appMod, messagingMod, databaseMod] = await Promise.all([
+		import("firebase/app"),
+		import("firebase/messaging"),
+		import("firebase/database")
+	]).catch(() => {
 		throw new Error("The \"firebase\" package is required for the Firebase transport. Install it with `npm i firebase`.");
 	});
 	const app = appMod.initializeApp({
 		apiKey: config.apiKey,
 		projectId: config.projectId,
 		appId: config.appId,
-		messagingSenderId: config.messagingSenderId
+		messagingSenderId: config.messagingSenderId,
+		databaseURL: config.databaseURL
 	});
 	const messaging = messagingMod.getMessaging(app);
 	const onMessage = messagingMod.onMessage;
+	const messageUnsubscribers = /* @__PURE__ */ new Set();
+	const databaseUnsubscribers = /* @__PURE__ */ new Set();
+	const databaseApi = databaseMod;
+	const database = databaseApi.getDatabase(app, config.databaseURL);
+	const clientEventsPath = config.clientEventsPath ?? "arkstack/client-events";
+	const clientId = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
+	const clientEventReference = (channel, event) => databaseApi.ref(database, `${clientEventsPath}/${pathSegment(channel)}/${pathSegment(event)}`);
 	return {
 		subscribe(channel, event, handler) {
+			const off = onMessage(messaging, (payload) => {
+				if (payload.data?.event !== event || !payload.data.payload) return;
+				try {
+					handler(JSON.parse(payload.data.payload));
+				} catch {}
+			});
+			messageUnsubscribers.add(off);
+			const offClientEvent = event.startsWith("client-") ? databaseApi.onChildAdded(clientEventReference(channel, event), (snapshot) => {
+				const clientEvent = snapshot.val();
+				if (isFirebaseClientEvent(clientEvent) && clientEvent.sender !== clientId) handler(clientEvent.payload);
+			}) : void 0;
+			if (offClientEvent) databaseUnsubscribers.add(offClientEvent);
 			return {
 				channel,
-				unsubscribe: onMessage(messaging, (payload) => {
-					if (payload.data?.event !== event || !payload.data.payload) return;
-					try {
-						handler(JSON.parse(payload.data.payload));
-					} catch {}
-				})
+				unsubscribe() {
+					off();
+					messageUnsubscribers.delete(off);
+					if (offClientEvent) {
+						offClientEvent();
+						databaseUnsubscribers.delete(offClientEvent);
+					}
+				}
 			};
 		},
-		disconnect() {}
+		async trigger(channel, event, payload) {
+			const eventReference = await databaseApi.push(clientEventReference(channel, event), {
+				sender: clientId,
+				payload
+			});
+			await databaseApi.remove(eventReference);
+		},
+		disconnect() {
+			messageUnsubscribers.forEach((off) => off());
+			messageUnsubscribers.clear();
+			databaseUnsubscribers.forEach((off) => off());
+			databaseUnsubscribers.clear();
+		}
 	};
 };
 //#endregion

package/dist/react/index.d.ts

@@ -1,4 +1,4 @@
-import { s as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-BlV9xSHd.js";
+import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CpYmOGZa.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 { s as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-BlV9xSHd.js";
+import { c as RealtimeNotification, t as RealtimeClient } from "../RealtimeClient-CpYmOGZa.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.17.22",
+  "version": "0.17.24",
   "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",