@arkstack/realtime 0.19.2 → 0.19.3

package/README.md

@@ -24,7 +24,7 @@ pnpm add firebase    # Firebase transport
 Create a client and subscribe to a user's channel. `subscribe`/`forUser` resolve to an unsubscribe function.
 
 ```ts
-import { createRealtime } from '@arkstack/realtime';
+import { createRealtime } from '@arkstack/realtime'
 
 const realtime = createRealtime({
   transport: 'pusher',
@@ -33,15 +33,15 @@ const realtime = createRealtime({
     cluster: 'mt1',
     authEndpoint: '/broadcasting/auth',
   },
-});
+})
 
 const unsubscribe = await realtime.forUser(user.id, (notification) => {
-  console.log(notification.title, notification.description);
-});
+  console.log(notification.title, notification.description)
+})
 
 // later
-unsubscribe();
-await realtime.disconnect();
+unsubscribe()
+await realtime.disconnect()
 ```
 
 ### Client events
@@ -50,14 +50,12 @@ 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`),
-);
+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();
+await realtime.whisper('private-room.7', 'typing', { userId: user.id })
+stopTyping()
 ```
 
 The `client-` prefix is added automatically. Pusher sends client events over its
@@ -70,35 +68,31 @@ Each `notification` matches the payload broadcast by the server:
 
 ```ts
 interface RealtimeNotification {
-  id: string;
-  type: string | null;
-  title: string;
-  description: string;
-  actionText?: string | null;
-  actionLink?: string | null;
-  meta?: Record<string, unknown> | null;
-  read_at: string | null;
-  created_at: string;
+  id: string
+  type: string | null
+  title: string
+  description: string
+  actionText?: string | null
+  actionLink?: string | null
+  meta?: Record<string, unknown> | null
+  read_at: string | null
+  created_at: string
 }
 ```
 
 ## React
 
 ```tsx
-import { useNotifications } from '@arkstack/realtime/react';
+import { useNotifications } from '@arkstack/realtime/react'
 
 function Bell({ realtime, userId }) {
-  const { notifications, latest, clear } = useNotifications(
-    realtime,
-    realtime.channelFor(userId),
-    { limit: 20 },
-  );
+  const { notifications, latest, clear } = useNotifications(realtime, realtime.channelFor(userId), { limit: 20 })
 
   return (
     <span onClick={clear}>
       {notifications.length} · {latest?.title}
     </span>
-  );
+  )
 }
 ```
 
@@ -108,9 +102,9 @@ The hook accumulates notifications (newest first), caps them at `limit`, and uns
 
 ```vue
 <script setup>
-import { useNotifications } from '@arkstack/realtime/vue';
+import { useNotifications } from "@arkstack/realtime/vue";
 
-const props = defineProps(['realtime', 'userId']);
+const props = defineProps(["realtime", "userId"]);
 const { notifications, latest, clear } = useNotifications(
   props.realtime,
   props.realtime.channelFor(props.userId),
@@ -139,7 +133,7 @@ const realtime = createRealtime({
     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
@@ -152,22 +146,22 @@ the root with `firebase.clientEventsPath` when needed.
 Provide `transportFactory` to bridge any backend (a raw WebSocket, SSE, a test double, …):
 
 ```ts
-import { createRealtime, type RealtimeTransport } from '@arkstack/realtime';
+import { createRealtime, type RealtimeTransport } from '@arkstack/realtime'
 
 const transport: RealtimeTransport = {
   subscribe(channel, event, handler) {
-    const socket = new WebSocket(`wss://example.test/${channel}`);
+    const socket = new WebSocket(`wss://example.test/${channel}`)
     socket.addEventListener('message', (e) => {
-      const { event: name, payload } = JSON.parse(e.data);
-      if (name === event) handler(payload);
-    });
+      const { event: name, payload } = JSON.parse(e.data)
+      if (name === event) handler(payload)
+    })
 
-    return { channel, unsubscribe: () => socket.close() };
+    return { channel, unsubscribe: () => socket.close() }
   },
   disconnect() {},
-};
+}
 
-const realtime = createRealtime({ transportFactory: () => transport });
+const realtime = createRealtime({ transportFactory: () => transport })
 ```
 
 ## API

package/dist/{RealtimeClient-CAoMUUkc.d.ts → RealtimeClient-C3_ppuiI.d.ts}

@@ -149,6 +149,12 @@ interface PollingClientConfig {
   /** How often, in milliseconds, {@link RealtimeClient.onPoll} handlers run (default 5000). */
   interval?: number;
 }
+/**
+ * Loads an SDK module (`pusher-js`, `firebase/app`, …) by package specifier.
+ * Supply one where bare imports cannot resolve, e.g. a plain `<script>` page
+ * that loads the SDKs from a CDN.
+ */
+type ModuleImporter = (specifier: string) => Promise<unknown>;
 interface RealtimeConfig {
   transport?: RealtimeTransportName;
   /** Event name broadcasts are published under (default `notification`). */
@@ -159,6 +165,8 @@ interface RealtimeConfig {
   firebase?: FirebaseClientConfig;
   'firebase-database'?: FirebaseDatabaseClientConfig;
   polling?: PollingClientConfig;
+  /** Loads the transport SDKs. Defaults to a dynamic `import()`. */
+  importModule?: ModuleImporter;
   /** Inject a transport directly — bypasses the built-ins (tests, custom backends). */
   transportFactory?: () => RealtimeTransport | Promise<RealtimeTransport>;
 }
@@ -264,4 +272,4 @@ declare class RealtimeClient {
 /** Create a new {@link RealtimeClient}. */
 declare const createRealtime: (config?: RealtimeConfig) => RealtimeClient;
 //#endregion
-export { FirebaseDatabaseClientConfig as a, PusherClientConfig as c, RealtimeNotification as d, RealtimeSubscription as f, FirebaseClientConfig as i, RealtimeConfig as l, RealtimeTransportName as m, createRealtime as n, NotificationHandler as o, RealtimeTransport as p, DeviceTokenOptions as r, PollingClientConfig as s, RealtimeClient as t, RealtimeEventHandler as u };
+export { FirebaseDatabaseClientConfig as a, PollingClientConfig as c, RealtimeEventHandler as d, RealtimeNotification as f, RealtimeTransportName as h, FirebaseClientConfig as i, PusherClientConfig as l, RealtimeTransport as m, createRealtime as n, ModuleImporter as o, RealtimeSubscription as p, DeviceTokenOptions as r, NotificationHandler as s, RealtimeClient as t, RealtimeConfig as u };

package/dist/importer-0BugD5WV.js

@@ -0,0 +1,14 @@
+//#region src/importer.ts
+/**
+* Load an optional SDK by its package specifier. Non-literal so bundlers leave
+* SDKs the app does not use out of the bundle.
+*
+* @param specifier
+* @returns
+*/
+const defaultImporter = (specifier) => import(
+	/* @vite-ignore */
+	specifier
+);
+//#endregion
+export { defaultImporter as t };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as FirebaseDatabaseClientConfig, c as PusherClientConfig, d as RealtimeNotification, f as RealtimeSubscription, i as FirebaseClientConfig, l as RealtimeConfig, m as RealtimeTransportName, n as createRealtime, o as NotificationHandler, p as RealtimeTransport, r as DeviceTokenOptions, s as PollingClientConfig, t as RealtimeClient, u as RealtimeEventHandler } from "./RealtimeClient-CAoMUUkc.js";
+import { a as FirebaseDatabaseClientConfig, c as PollingClientConfig, d as RealtimeEventHandler, f as RealtimeNotification, h as RealtimeTransportName, i as FirebaseClientConfig, l as PusherClientConfig, m as RealtimeTransport, n as createRealtime, o as ModuleImporter, p as RealtimeSubscription, r as DeviceTokenOptions, s as NotificationHandler, t as RealtimeClient, u as RealtimeConfig } from "./RealtimeClient-C3_ppuiI.js";
 //#region src/transports/pusher.d.ts
 /**
  * Realtime transport backed by [pusher-js](https://github.com/pusher/pusher-js).
@@ -6,9 +6,10 @@ import { a as FirebaseDatabaseClientConfig, c as PusherClientConfig, d as Realti
  * it in when they use the Pusher transport.
  *
  * @param config
+ * @param importModule  Loads `pusher-js`.
  * @returns
  */
-declare const createPusherTransport: (config: PusherClientConfig) => Promise<RealtimeTransport>;
+declare const createPusherTransport: (config: PusherClientConfig, importModule?: ModuleImporter) => Promise<RealtimeTransport>;
 //#endregion
 //#region src/transports/firebase.d.ts
 /**
@@ -18,7 +19,7 @@ declare const createPusherTransport: (config: PusherClientConfig) => Promise<Rea
  * FCM delivers to the device (not per-channel), so the channel is informational;
  * messages are matched by `event` and the JSON-encoded payload is parsed back.
  */
-declare const createFirebaseTransport: (config: FirebaseClientConfig) => Promise<RealtimeTransport>;
+declare const createFirebaseTransport: (config: FirebaseClientConfig, importModule?: ModuleImporter) => Promise<RealtimeTransport>;
 //#endregion
 //#region src/transports/firebase-database.d.ts
 /**
@@ -30,9 +31,10 @@ declare const createFirebaseTransport: (config: FirebaseClientConfig) => Promise
  * written after the transport connected are delivered.
  *
  * @param config
+ * @param importModule  Loads the `firebase` SDK modules.
  * @returns
  */
-declare const createFirebaseDatabaseTransport: (config: FirebaseDatabaseClientConfig) => Promise<RealtimeTransport>;
+declare const createFirebaseDatabaseTransport: (config: FirebaseDatabaseClientConfig, importModule?: ModuleImporter) => Promise<RealtimeTransport>;
 //#endregion
 //#region src/transports/polling.d.ts
 /**
@@ -94,8 +96,9 @@ declare const supersede: (list: RealtimeNotification[], incoming: RealtimeNotifi
  *
  * @param config
  * @param options
+ * @param importModule  Loads the `firebase` SDK modules.
  * @returns
  */
-declare const requestDeviceToken: (config: FirebaseClientConfig, options?: DeviceTokenOptions) => Promise<string | null>;
+declare const requestDeviceToken: (config: FirebaseClientConfig, options?: DeviceTokenOptions, importModule?: ModuleImporter) => Promise<string | null>;
 //#endregion
-export { type DeviceTokenOptions, 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, requestDeviceToken, supersede };
+export { type DeviceTokenOptions, type FirebaseClientConfig, type FirebaseDatabaseClientConfig, type ModuleImporter, 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, requestDeviceToken, supersede };

package/dist/index.js

@@ -1,4 +1,5 @@
-import { i as __exportAll, r as requestDeviceToken, t as issueDeviceToken } from "./push-TmPMqRUR.js";
+import { i as __exportAll, r as requestDeviceToken, t as issueDeviceToken } from "./push-ucsxjX92.js";
+import { t as defaultImporter } from "./importer-0BugD5WV.js";
 import { t as supersede } from "./supersede-T1ch4wJF.js";
 //#region src/RealtimeClient.ts
 /**
@@ -18,9 +19,9 @@ var RealtimeClient = class {
 	}
 	/**
 	* The channel name a given user's notifications are broadcast on.
-	* 
-	* @param userId 
-	* @returns 
+	*
+	* @param userId
+	* @returns
 	*/
 	channelFor(userId) {
 		return `${this.channelPrefix}${userId}`;
@@ -34,11 +35,11 @@ var RealtimeClient = class {
 		switch (this.transportName) {
 			case "firebase": {
 				const { createFirebaseTransport } = await Promise.resolve().then(() => firebase_exports);
-				return await createFirebaseTransport(this.required("firebase"));
+				return await createFirebaseTransport(this.required("firebase"), this.config.importModule);
 			}
 			case "firebase-database": {
 				const { createFirebaseDatabaseTransport } = await Promise.resolve().then(() => firebase_database_exports);
-				return await createFirebaseDatabaseTransport(this.required("firebase-database"));
+				return await createFirebaseDatabaseTransport(this.required("firebase-database"), this.config.importModule);
 			}
 			case "polling": {
 				const { createPollingTransport } = await Promise.resolve().then(() => polling_exports);
@@ -50,7 +51,7 @@ var RealtimeClient = class {
 			}
 			default: {
 				const { createPusherTransport } = await Promise.resolve().then(() => pusher_exports);
-				return await createPusherTransport(this.required("pusher"));
+				return await createPusherTransport(this.required("pusher"), this.config.importModule);
 			}
 		}
 	}
@@ -159,8 +160,8 @@ var RealtimeClient = class {
 		const transport = await this.transport();
 		if (transport.deviceToken) return await transport.deviceToken(options);
 		if (!this.config.firebase) return null;
-		const { requestDeviceToken } = await import("./push-TmPMqRUR.js").then((n) => n.n);
-		return await requestDeviceToken(this.config.firebase, options);
+		const { requestDeviceToken } = await import("./push-ucsxjX92.js").then((n) => n.n);
+		return await requestDeviceToken(this.config.firebase, options, this.config.importModule);
 	}
 	/** Tear down the underlying transport connection. */
 	async disconnect() {
@@ -177,13 +178,14 @@ var pusher_exports = /* @__PURE__ */ __exportAll({ createPusherTransport: () =>
 /**
 * Realtime transport backed by [pusher-js](https://github.com/pusher/pusher-js).
 * The SDK is an optional peer dependency imported lazily, so consumers only pull
-* it in when they use the Pusher transport. 
-* 
-* @param config 
-* @returns 
+* it in when they use the Pusher transport.
+*
+* @param config
+* @param importModule  Loads `pusher-js`.
+* @returns
 */
-const createPusherTransport = async (config) => {
-	const mod = await import("pusher-js").catch(() => {
+const createPusherTransport = async (config, importModule = defaultImporter) => {
+	const mod = await importModule("pusher-js").catch(() => {
 		throw new Error("The \"pusher-js\" package is required for the Pusher transport. Install it with `npm i pusher-js`.");
 	});
 	const client = new (mod.default ?? mod)(config.key, {
@@ -246,11 +248,11 @@ const isFirebaseClientEvent = (value) => {
 * FCM delivers to the device (not per-channel), so the channel is informational;
 * messages are matched by `event` and the JSON-encoded payload is parsed back.
 */
-const createFirebaseTransport = async (config) => {
+const createFirebaseTransport = async (config, importModule = defaultImporter) => {
 	const [appMod, messagingMod, databaseMod] = await Promise.all([
-		import("firebase/app"),
-		import("firebase/messaging"),
-		import("firebase/database")
+		importModule("firebase/app"),
+		importModule("firebase/messaging"),
+		importModule("firebase/database")
 	]).catch(() => {
 		throw new Error("The \"firebase\" package is required for the Firebase transport. Install it with `npm i firebase`.");
 	});
@@ -348,13 +350,14 @@ const tokenUid = (token) => {
 * written after the transport connected are delivered.
 *
 * @param config
+* @param importModule  Loads the `firebase` SDK modules.
 * @returns
 */
-const createFirebaseDatabaseTransport = async (config) => {
+const createFirebaseDatabaseTransport = async (config, importModule = defaultImporter) => {
 	const [appMod, authMod, databaseMod] = await Promise.all([
-		import("firebase/app"),
-		import("firebase/auth"),
-		import("firebase/database")
+		importModule("firebase/app"),
+		importModule("firebase/auth"),
+		importModule("firebase/database")
 	]).catch(() => {
 		throw new Error("The \"firebase\" package is required for the Firebase database transport. Install it with `npm i firebase`.");
 	});

package/dist/{push-TmPMqRUR.js → push-ucsxjX92.js}

@@ -1,3 +1,4 @@
+import { t as defaultImporter } from "./importer-0BugD5WV.js";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -65,10 +66,11 @@ const issueDeviceToken = async (messagingMod, messaging, config, options = {}) =
 *
 * @param config
 * @param options
+* @param importModule  Loads the `firebase` SDK modules.
 * @returns
 */
-const requestDeviceToken = async (config, options = {}) => {
-	const [appMod, messagingMod] = await Promise.all([import("firebase/app"), import("firebase/messaging")]).catch(() => {
+const requestDeviceToken = async (config, options = {}, importModule = defaultImporter) => {
+	const [appMod, messagingMod] = await Promise.all([importModule("firebase/app"), importModule("firebase/messaging")]).catch(() => {
 		throw new Error("The \"firebase\" package is required for device tokens. Install it with `npm i firebase`.");
 	});
 	const app = appMod.getApps().find((existing) => existing.name === APP_NAME) ?? appMod.initializeApp(webConfig(config), APP_NAME);

package/dist/react/index.d.ts

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

package/dist/react/index.js

@@ -24,7 +24,9 @@ function useNotifications(client, channel, options = {}) {
 		client.subscribe(channel, push).then((off) => {
 			if (cancelled) off();
 			else unsubscribe = off;
-		}).catch(() => {/** surfaced by the caller's own error handling */});
+		}).catch(() => {
+			/** surfaced by the caller's own error handling */
+		});
 		return () => {
 			cancelled = true;
 			unsubscribe?.();

package/dist/vue/index.d.ts

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

package/dist/vue/index.js

@@ -25,7 +25,9 @@ function useNotifications(client, channel, options = {}) {
 	client.subscribe(channel, push).then((off) => {
 		if (cancelled) off();
 		else unsubscribe = off;
-	}).catch(() => {/** surfaced by the caller's own error handling */});
+	}).catch(() => {
+		/** surfaced by the caller's own error handling */
+	});
 	const stop = () => {
 		cancelled = true;
 		unsubscribe?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/realtime",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "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",