@rebasepro/client 0.9.1-canary.97e305f → 0.9.1-canary.a639738

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export type { CreateBackupsOptions } from "./backups";
 export type { ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, CreateApiKeysOptions, UpdateApiKeyRequest } from "./api-keys";
 export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 export { RebaseWebSocketClient } from "./websocket";
+export { RebaseRealtimeChannel } from "./realtime-channel";
+export type { PresenceState, PresenceDiff, BroadcastEvent, ChannelTransport } from "./realtime-channel";
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
     admin?: CreateAdminOptions;

package/dist/index.es.js

@@ -1405,6 +1405,20 @@ function extractMessageError(message) {
 	};
 }
 /**
+* Broadcast and presence frames.
+*
+* Fire-and-forget (the server sends no response envelope), and exempt from the
+* client-side auth gate — a public channel is usable without an account.
+*/
+var CHANNEL_MESSAGE_TYPES = new Set([
+	"join_channel",
+	"leave_channel",
+	"broadcast",
+	"presence_track",
+	"presence_untrack",
+	"presence_state"
+]);
+/**
 * Low-level realtime WebSocket client.
 *
 * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
@@ -1419,6 +1433,36 @@ var RebaseWebSocketClient = class {
 	getAuthToken;
 	subscriptions = /* @__PURE__ */ new Map();
 	listeners = /* @__PURE__ */ new Map();
+	/** Channel-name → handlers, for broadcast and presence frames. */
+	channelHandlers = /* @__PURE__ */ new Map();
+	/** Set by `close()`. Blocks any later operation from silently redialling. */
+	closedByCaller = false;
+	/**
+	* Whether a socket exists at all (open or still opening).
+	*
+	* Lets callers distinguish "authenticate the live socket" from "there is
+	* nothing to authenticate yet", without that question forcing a dial.
+	*/
+	get hasSocket() {
+		return this.ws !== null;
+	}
+	/** So the "no WebSocket in this environment" warning is said once, not per call. */
+	warnedNoWebSocket = false;
+	/** Subscribe to broadcast/presence frames for one channel. */
+	onChannelMessage(channel, handler) {
+		if (!this.channelHandlers.has(channel)) this.channelHandlers.set(channel, /* @__PURE__ */ new Set());
+		this.channelHandlers.get(channel).add(handler);
+		return () => {
+			const handlers = this.channelHandlers.get(channel);
+			if (!handlers) return;
+			handlers.delete(handler);
+			if (handlers.size === 0) this.channelHandlers.delete(channel);
+		};
+	}
+	/** Notified after the socket comes back, so channels can re-join. */
+	onReconnect(handler) {
+		return this.on("reconnect", handler);
+	}
 	on(event, cb) {
 		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
 		this.listeners.get(event).add(cb);
@@ -1449,8 +1493,25 @@ var RebaseWebSocketClient = class {
 		this.getAuthToken = config.getAuthToken;
 		this.onUnauthorized = config.onUnauthorized;
 		this.WebSocketConstructor = config.WebSocket || (typeof WebSocket !== "undefined" ? WebSocket : void 0);
-		if (!this.WebSocketConstructor) console.warn("WebSocket is not defined in this environment. Realtime subscriptions will not work unless you provide a WebSocket implementation in the config.");
-		else this.initWebSocket();
+	}
+	/**
+	* Open the socket if it is not open (or opening) already.
+	*
+	* Idempotent, synchronous, and safe to call on every operation that needs a
+	* live socket — `initWebSocket` already no-ops on an open socket and is
+	* re-entrant, since the reconnect path has always called it.
+	*/
+	ensureConnected() {
+		if (this.closedByCaller) return;
+		if (!this.WebSocketConstructor) {
+			if (!this.warnedNoWebSocket) {
+				this.warnedNoWebSocket = true;
+				console.warn("WebSocket is not defined in this environment. Realtime subscriptions will not work unless you provide a WebSocket implementation in the config.");
+			}
+			return;
+		}
+		if (this.ws || this.reconnectTimeout) return;
+		this.initWebSocket();
 	}
 	/**
 	* Authenticate the WebSocket connection
@@ -1500,7 +1561,16 @@ var RebaseWebSocketClient = class {
 			});
 		}
 	}
-	disconnect() {
+	/**
+	* Drop the socket.
+	*
+	* `permanent` distinguishes the two callers. Signing out drops the socket
+	* but the client stays usable — a later subscribe should reconnect
+	* anonymously. `client.close()` is the caller saying they are done, and
+	* must not be undone by a stray queued frame.
+	*/
+	disconnect(permanent = false) {
+		if (permanent) this.closedByCaller = true;
 		this.isAuthenticated = false;
 		this.authPromise = null;
 		if (this.reconnectTimeout) {
@@ -1685,6 +1755,15 @@ var RebaseWebSocketClient = class {
 			}
 			return;
 		}
+		if (typeof message.channel === "string" && (type === "broadcast" || type === "presence_state" || type === "presence_diff")) {
+			const handlers = this.channelHandlers.get(message.channel);
+			if (handlers) for (const handler of [...handlers]) try {
+				handler(message);
+			} catch (error) {
+				console.error("Error in channel handler:", error);
+			}
+			return;
+		}
 		if (subscriptionId && type === "collection_update") {
 			const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
 			if (subscriptionKey) {
@@ -1873,21 +1952,28 @@ var RebaseWebSocketClient = class {
 			throw error;
 		}
 	}
+	/**
+	* Public because `RebaseRealtimeChannel` sends channel frames through it.
+	* Not part of the stable surface — prefer `client.realtime.channel(name)`.
+	*/
 	sendMessage(message) {
 		const queuedMsg = message;
 		if (queuedMsg._queuedResolve && queuedMsg._queuedReject) return this.doSendMessage(message, queuedMsg._queuedResolve, queuedMsg._queuedReject);
-		if (!this.isConnected || !this.ws) return new Promise((resolve, reject) => {
-			const queueable = message;
-			queueable._queuedResolve = resolve;
-			queueable._queuedReject = reject;
-			this.messageQueue.push(message);
-		});
+		if (!this.isConnected || !this.ws) {
+			this.ensureConnected();
+			return new Promise((resolve, reject) => {
+				const queueable = message;
+				queueable._queuedResolve = resolve;
+				queueable._queuedReject = reject;
+				this.messageQueue.push(message);
+			});
+		}
 		return new Promise((resolve, reject) => {
 			this.doSendMessage(message, resolve, reject);
 		});
 	}
 	async doSendMessage(message, resolve, reject) {
-		if (message.type !== "AUTHENTICATE" && this.getAuthToken && !this.isAuthenticated) try {
+		if (message.type !== "AUTHENTICATE" && !CHANNEL_MESSAGE_TYPES.has(message.type) && this.getAuthToken && !this.isAuthenticated) try {
 			await this.ensureAuthenticated();
 		} catch (error) {
 			reject(new RebaseApiError$1(error instanceof Error ? error.message : "Authentication required"));
@@ -1895,17 +1981,7 @@ var RebaseWebSocketClient = class {
 		}
 		const requestId = message.requestId || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		message.requestId = requestId;
-		const expectsResponse = ![
-			"subscribe_collection",
-			"subscribe_one",
-			"unsubscribe",
-			"join_channel",
-			"leave_channel",
-			"broadcast",
-			"presence_track",
-			"presence_untrack",
-			"presence_state"
-		].includes(message.type);
+		const expectsResponse = !(message.type === "subscribe_collection" || message.type === "subscribe_one" || message.type === "unsubscribe" || CHANNEL_MESSAGE_TYPES.has(message.type));
 		if (expectsResponse && !this.pendingRequests.has(requestId)) {
 			const timeoutHandle = setTimeout(() => {
 				if (this.pendingRequests.has(requestId)) {
@@ -2134,6 +2210,7 @@ var RebaseWebSocketClient = class {
 		});
 	}
 	listenCollection(props, onUpdate, onError) {
+		this.ensureConnected();
 		const subscriptionKey = this.createCollectionSubscriptionKey(props);
 		const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		const existingSubscription = this.collectionSubscriptions.get(subscriptionKey);
@@ -2195,6 +2272,7 @@ var RebaseWebSocketClient = class {
 		};
 	}
 	listenOne(props, onUpdate, onError) {
+		this.ensureConnected();
 		const subscriptionKey = this.createSingleSubscriptionKey(props);
 		const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 		const existingSubscription = this.singleSubscriptions.get(subscriptionKey);
@@ -2453,6 +2531,190 @@ var RebaseWebSocketClient = class {
 	}
 };
 //#endregion
+//#region src/realtime-channel.ts
+/**
+* Re-send presence comfortably inside the server's 30s expiry.
+*
+* Two-thirds of the window: one lost heartbeat still leaves time for the next
+* before the entry is reaped, so a single dropped frame is not a disappearance.
+*/
+var PRESENCE_HEARTBEAT_MS = 2e4;
+var RebaseRealtimeChannel = class {
+	name;
+	transport;
+	presenceHandlers = /* @__PURE__ */ new Set();
+	broadcastHandlers = /* @__PURE__ */ new Set();
+	unsubscribers = [];
+	/** Last known roster, kept so handlers always get a full picture. */
+	presences = {};
+	/** What this client last tracked, replayed on reconnect and heartbeat. */
+	trackedState = null;
+	heartbeat = null;
+	joined = false;
+	constructor(name, transport) {
+		this.name = name;
+		this.transport = transport;
+	}
+	/**
+	* Join the channel and ask for the current roster.
+	*
+	* Called automatically by `track`, `broadcast`, `onPresence` and
+	* `onBroadcast`; calling it directly is only needed to start receiving
+	* before there is anything to send.
+	*/
+	async join() {
+		if (this.joined) return;
+		this.joined = true;
+		this.unsubscribers.push(this.transport.onChannelMessage(this.name, (message) => this.handle(message)));
+		this.unsubscribers.push(this.transport.onReconnect(() => {
+			this.rejoin();
+		}));
+		await this.transport.sendMessage({
+			type: "join_channel",
+			channel: this.name
+		});
+		await this.transport.sendMessage({
+			type: "presence_state",
+			channel: this.name
+		});
+	}
+	async rejoin() {
+		try {
+			await this.transport.sendMessage({
+				type: "join_channel",
+				channel: this.name
+			});
+			await this.transport.sendMessage({
+				type: "presence_state",
+				channel: this.name
+			});
+			if (this.trackedState) await this.transport.sendMessage({
+				type: "presence_track",
+				channel: this.name,
+				state: this.trackedState
+			});
+		} catch {}
+	}
+	/**
+	* Publish this client's presence state, and keep publishing it.
+	*
+	* Calling `track` again replaces the state (and restarts the heartbeat),
+	* which is how you update e.g. a cursor position.
+	*/
+	async track(state) {
+		await this.join();
+		this.trackedState = state;
+		await this.transport.sendMessage({
+			type: "presence_track",
+			channel: this.name,
+			state
+		});
+		if (!this.heartbeat) {
+			this.heartbeat = setInterval(() => {
+				if (!this.trackedState) return;
+				this.transport.sendMessage({
+					type: "presence_track",
+					channel: this.name,
+					state: this.trackedState
+				}).catch(() => {});
+			}, PRESENCE_HEARTBEAT_MS);
+			this.heartbeat.unref?.();
+		}
+	}
+	/** Stop publishing presence, without leaving the channel. */
+	async untrack() {
+		this.stopHeartbeat();
+		this.trackedState = null;
+		if (this.joined) await this.transport.sendMessage({
+			type: "presence_untrack",
+			channel: this.name
+		});
+	}
+	/**
+	* Observe the roster. The handler fires immediately with what is already
+	* known, then on every change.
+	*/
+	onPresence(handler) {
+		this.presenceHandlers.add(handler);
+		this.join();
+		if (Object.keys(this.presences).length > 0) handler({ ...this.presences });
+		return () => this.presenceHandlers.delete(handler);
+	}
+	/** Send a broadcast. The sender does not receive its own message. */
+	async broadcast(event, payload) {
+		await this.join();
+		await this.transport.sendMessage({
+			type: "broadcast",
+			channel: this.name,
+			event,
+			payload
+		});
+	}
+	onBroadcast(eventOrHandler, maybeHandler) {
+		const wrapped = typeof eventOrHandler === "string" ? (e) => {
+			if (e.event === eventOrHandler) maybeHandler(e.payload);
+		} : eventOrHandler;
+		this.broadcastHandlers.add(wrapped);
+		this.join();
+		return () => this.broadcastHandlers.delete(wrapped);
+	}
+	/** Leave the channel and release every listener and timer. */
+	async leave() {
+		this.stopHeartbeat();
+		this.trackedState = null;
+		this.presences = {};
+		this.presenceHandlers.clear();
+		this.broadcastHandlers.clear();
+		for (const off of this.unsubscribers) off();
+		this.unsubscribers = [];
+		if (this.joined) {
+			this.joined = false;
+			await this.transport.sendMessage({
+				type: "leave_channel",
+				channel: this.name
+			});
+		}
+	}
+	stopHeartbeat() {
+		if (this.heartbeat) {
+			clearInterval(this.heartbeat);
+			this.heartbeat = null;
+		}
+	}
+	/** Fold an incoming frame into the roster and fan it out. */
+	handle(message) {
+		switch (message.type) {
+			case "presence_state":
+				this.presences = message.presences ?? {};
+				this.emitPresence();
+				break;
+			case "presence_diff": {
+				const joins = message.joins ?? {};
+				const leaves = message.leaves ?? {};
+				for (const [id, state] of Object.entries(joins)) this.presences[id] = state;
+				for (const id of Object.keys(leaves)) delete this.presences[id];
+				this.emitPresence({
+					joins,
+					leaves
+				});
+				break;
+			}
+			case "broadcast": {
+				const event = {
+					event: message.event,
+					payload: message.payload
+				};
+				for (const handler of this.broadcastHandlers) handler(event);
+				break;
+			}
+		}
+	}
+	emitPresence(diff) {
+		const snapshot = { ...this.presences };
+		for (const handler of this.presenceHandlers) handler(snapshot, diff);
+	}
+};
+//#endregion
 //#region src/index.ts
 /**
 * Derive a WebSocket URL from an HTTP base URL.
@@ -2503,6 +2765,8 @@ function createRebaseClient(options) {
 	};
 	const resolvedWsUrl = options.realtime !== false ? options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl) : void 0;
 	let ws;
+	/** One channel object per name — see `realtime.channel`. */
+	const realtimeChannels = /* @__PURE__ */ new Map();
 	if (resolvedWsUrl) {
 		ws = new RebaseWebSocketClient({
 			websocketUrl: resolvedWsUrl,
@@ -2526,7 +2790,7 @@ function createRebaseClient(options) {
 			if (!ws) return;
 			if (event === "SIGNED_OUT") ws.disconnect();
 			else if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
-				if (session?.accessToken) ws.authenticate(session.accessToken).catch(console.warn);
+				if (session?.accessToken && ws.hasSocket) ws.authenticate(session.accessToken).catch(console.warn);
 			}
 		});
 	}
@@ -2613,6 +2877,24 @@ function createRebaseClient(options) {
 		createStorageSource,
 		fetchStorageSources,
 		ws,
+		realtime: { 
+		/**
+		* Join a broadcast/presence channel.
+		*
+		* Repeated calls with the same name return the same channel, so
+		* separate components can attach handlers without each opening its
+		* own membership — and `leave()` from one would otherwise silently
+		* cut off the others.
+		*/
+channel: (name) => {
+			if (!ws) throw new RebaseClientError("Realtime is disabled on this client (realtime: false), so channels are unavailable.");
+			let existing = realtimeChannels.get(name);
+			if (!existing) {
+				existing = new RebaseRealtimeChannel(name, ws);
+				realtimeChannels.set(name, existing);
+			}
+			return existing;
+		} },
 		/**
 		* Release the realtime socket and its reconnect timer.
 		*
@@ -2621,7 +2903,9 @@ function createRebaseClient(options) {
 		* was never started, and safe to call twice.
 		*/
 		close: () => {
-			ws?.disconnect();
+			for (const channel of realtimeChannels.values()) channel.leave();
+			realtimeChannels.clear();
+			ws?.disconnect(true);
 		},
 		setToken: transport.setToken,
 		setAuthTokenGetter: transport.setAuthTokenGetter,
@@ -2641,6 +2925,6 @@ function createRebaseClient(options) {
 	};
 }
 //#endregion
-export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, or };
+export { QueryBuilder, RebaseApiError, RebaseClientError, RebaseRealtimeChannel, RebaseWebSocketClient, and, cond, createBackups, createCookieStorage, createMemoryStorage, createRebaseClient, or };
 
 //# sourceMappingURL=index.es.js.map