@rebasepro/client 0.9.0 → 0.9.1-canary.0de22e0

package/src/index.ts

@@ -3,12 +3,14 @@ import { RebaseClientError } from "./errors";
 import { createAuth, CreateAuthOptions } from "./auth";
 import { createAdmin, CreateAdminOptions } from "./admin";
 import { createCron, CreateCronOptions } from "./cron";
+import { createBackups } from "./backups";
 import { createApiKeys, CreateApiKeysOptions } from "./api-keys";
 import { CollectionClient, createCollectionClient } from "./collection";
 import { createFunctionsClient } from "./functions";
 import { createStorage } from "./storage";
 import { ClientStorageSourceRegistry } from "./storage-registry";
 import { RebaseWebSocketClient } from "./websocket";
+import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel";
 import {
     DEFAULT_STORAGE_SOURCE_KEY,
     InsertOf,
@@ -59,6 +61,8 @@ export type { RebaseUser, RebaseTokens } from "./auth";
 export type { CreateAdminOptions } from "./admin";
 export type { AdminUser } from "./admin";
 export type { CreateCronOptions } from "./cron";
+export { createBackups } from "./backups";
+export type { CreateBackupsOptions } from "./backups";
 export type {
     ApiKeyMasked,
     ApiKeyPermission,
@@ -70,9 +74,19 @@ export type {
 export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 
 // Realtime: the WebSocket client class is internal to `createRebaseClient()`,
-// but re-exported (see @internal on the class) because the `client-postgresql`
+// but re-exported (see @internal on the class) because the `client-postgres`
 // driver constructs it directly. Not a stable app-facing API.
 export { RebaseWebSocketClient } from "./websocket";
+export { RebaseRealtimeChannel } from "./realtime-channel";
+export type {
+    PresenceState,
+    PresenceDiff,
+    BroadcastEvent,
+    ChannelTransport,
+    ChannelOptions,
+    ChannelHistoryEntry,
+    ChannelHistoryResult
+} from "./realtime-channel";
 
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
@@ -135,14 +149,42 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
     auth: ReturnType<typeof createAuth>;
     admin: ReturnType<typeof createAdmin>;
     cron: ReturnType<typeof createCron>;
+    backups: ReturnType<typeof createBackups>;
     apiKeys: ReturnType<typeof createApiKeys>;
     functions: ReturnType<typeof createFunctionsClient>;
     ws?: RebaseWebSocketClient;
+    /**
+     * Broadcast and presence channels.
+     *
+     * Was missing from this type while present on the returned object, which
+     * made `client.realtime.channel(...)` a type error and forced every adopter
+     * to cast around the feature before they could reach it.
+     */
+    realtime: {
+        /**
+         * Join a broadcast/presence channel. Repeated calls with the same name
+         * return the same channel object. Throws only when the client was
+         * created with `realtime: false`.
+         *
+         * Pass `{ history: true }` to have the channel replay what it missed on
+         * join and on every reconnect, for channels the server retains.
+         */
+        channel: (name: string, options?: ChannelOptions) => RebaseRealtimeChannel;
+    };
+    /**
+     * Release the realtime socket and its reconnect timer.
+     *
+     * An open socket keeps the Node event loop alive, so a script that does not
+     * call this will not exit on its own. Safe when realtime was never started
+     * (`realtime: false`), and safe to call twice.
+     */
+    close: () => void;
     storage: StorageSource;
     storageRegistry: StorageSourceRegistry;
     createStorageSource: (storageId: string) => StorageSource;
     fetchStorageSources: () => Promise<StorageSourceDefinition[]>;
     call: <T = unknown>(endpoint: string, payload?: unknown) => Promise<T>;
+    collection: <M extends Record<string, unknown> = Record<string, unknown>>(slug: string) => CollectionClient<M>;
     data: TypedDataLayer<DB>;
 };
 
@@ -187,6 +229,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
     const auth = createAuth(transport, options.auth);
     const admin = createAdmin(transport, options.admin);
     const cron = createCron(transport, options.cron);
+    const backups = createBackups(transport);
     const apiKeys = createApiKeys(transport, options.apiKeys);
     const storage = createStorage(transport);
     const functions = createFunctionsClient(transport);
@@ -233,9 +276,17 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         return storageSourcesPromise;
     };
 
-    const resolvedWsUrl = options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl);
+    // Opting out has to happen before the URL is derived: `deriveWebSocketUrl`
+    // always produces one, so a truthy check alone can never leave the socket
+    // closed.
+    const realtimeEnabled = options.realtime !== false;
+    const resolvedWsUrl = realtimeEnabled
+        ? (options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl))
+        : undefined;
 
     let ws: RebaseWebSocketClient | undefined;
+    /** One channel object per name — see `realtime.channel`. */
+    const realtimeChannels = new Map<string, RebaseRealtimeChannel>();
     if (resolvedWsUrl) {
         const wsOnUnauthorized = options.onUnauthorized || (async () => {
             try {
@@ -263,9 +314,15 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         auth.onAuthStateChange((event, session) => {
             if (!ws) return;
             if (event === "SIGNED_OUT") {
+                // Not permanent: the client stays usable, and a later subscribe
+                // should reconnect anonymously.
                 ws.disconnect();
             } else if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
-                if (session?.accessToken) {
+                // Only re-authenticate a socket that already exists. Signing in
+                // is not a request for realtime, and dialling here would undo
+                // lazy connect for every app with a login. A socket opened
+                // later authenticates itself from `getAuthToken` on open.
+                if (session?.accessToken && ws.hasSocket) {
                     ws.authenticate(session.accessToken).catch(console.warn);
                 }
             }
@@ -395,6 +452,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         auth,
         admin,
         cron,
+        backups,
         apiKeys,
         functions,
         storage,
@@ -402,6 +460,57 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         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: string, options?: ChannelOptions): RebaseRealtimeChannel => {
+                // Only `realtime: false` gets here — a hard opt-out, so this
+                // stays an error. Being merely *unconnected* does not: the
+                // socket opens on the first channel operation, which is the
+                // whole point of asking for a channel before you use one.
+                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, options);
+                    realtimeChannels.set(name, existing);
+                } else if (options?.history) {
+                    // Same object by name, so options on a later call have no
+                    // new channel to apply to. Asking for history upgrades the
+                    // one that exists rather than being quietly ignored — but
+                    // never the reverse, so a caller that omits the option
+                    // cannot switch it off under one that asked for it.
+                    existing.enableHistory();
+                }
+                return existing;
+            }
+        },
+        /**
+         * Release the realtime socket and its reconnect timer.
+         *
+         * Until this returns, the open socket keeps the Node event loop alive
+         * and the process will not exit on its own. Safe to call when realtime
+         * was never started, and safe to call twice.
+         */
+        close: () => {
+            // Channels hold presence heartbeat timers, which would otherwise
+            // keep firing (and keep a Node process alive) after the socket
+            // they publish over is gone.
+            for (const channel of realtimeChannels.values()) void channel.leave();
+            realtimeChannels.clear();
+            // Permanent: nothing queued afterwards may redial and keep the
+            // event loop alive, which is the reason this method exists.
+            ws?.disconnect(true);
+        },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
         setOnUnauthorized: transport.setOnUnauthorized,