@rebasepro/client 0.9.0 → 0.9.1-canary.09aaf62

package/dist/realtime-channel.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Broadcast channels and presence, as an SDK surface.
+ *
+ * The realtime engine has supported `join_channel`, `broadcast`,
+ * `presence_track`, `presence_untrack` and `presence_state` for a while, but
+ * the client only recognised those types well enough to send them
+ * fire-and-forget: there were no methods to call and no way to receive channel
+ * or broadcast events, since `on()` handles only connect / disconnect /
+ * reconnect / error. Anything wanting presence therefore opened a *second*
+ * socket and reimplemented the AUTHENTICATE → AUTH_SUCCESS handshake, the
+ * reconnect backoff, and the presence heartbeat — a couple of hundred lines
+ * per app, all of it duplicating this package.
+ *
+ * Two protocol details this hides, because both are easy to get wrong and
+ * neither is discoverable from the message list:
+ *
+ *  - **A joining client is told only about its own join.** The `presence_diff`
+ *    it receives after `presence_track` contains just itself. The existing
+ *    roster arrives only in response to an explicit `presence_state` request,
+ *    so `join()` sends one.
+ *  - **Presence expires after 30s** (`PRESENCE_TIMEOUT_MS` server-side). A
+ *    client that tracks once and goes quiet silently vanishes from everyone
+ *    else's roster while still sitting in the document, so `track()` starts a
+ *    heartbeat and `leave()` stops it.
+ */
+/** Presence state keyed by the server's client id. */
+export type PresenceState = Record<string, Record<string, unknown>>;
+export interface PresenceDiff {
+    joins: PresenceState;
+    leaves: PresenceState;
+}
+export interface BroadcastEvent {
+    event: string;
+    payload: unknown;
+}
+/** The socket operations a channel needs; satisfied by RebaseWebSocketClient. */
+export interface ChannelTransport {
+    sendMessage(message: Record<string, unknown>): Promise<unknown>;
+    onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void;
+    onReconnect(handler: () => void): () => void;
+}
+export declare class RebaseRealtimeChannel {
+    readonly name: string;
+    private transport;
+    private presenceHandlers;
+    private broadcastHandlers;
+    private unsubscribers;
+    /** Last known roster, kept so handlers always get a full picture. */
+    private presences;
+    /** What this client last tracked, replayed on reconnect and heartbeat. */
+    private trackedState;
+    private heartbeat;
+    private joined;
+    constructor(name: string, transport: ChannelTransport);
+    /**
+     * 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.
+     */
+    join(): Promise<void>;
+    private rejoin;
+    /**
+     * 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.
+     */
+    track(state: Record<string, unknown>): Promise<void>;
+    /** Stop publishing presence, without leaving the channel. */
+    untrack(): Promise<void>;
+    /**
+     * Observe the roster. The handler fires immediately with what is already
+     * known, then on every change.
+     */
+    onPresence(handler: (state: PresenceState, diff?: PresenceDiff) => void): () => void;
+    /** Send a broadcast. The sender does not receive its own message. */
+    broadcast(event: string, payload: unknown): Promise<void>;
+    /** Observe broadcasts. Pass an event name to filter. */
+    onBroadcast(handler: (event: BroadcastEvent) => void): () => void;
+    onBroadcast(event: string, handler: (payload: unknown) => void): () => void;
+    /** Leave the channel and release every listener and timer. */
+    leave(): Promise<void>;
+    private stopHeartbeat;
+    /** Fold an incoming frame into the roster and fan it out. */
+    private handle;
+    private emitPresence;
+}

package/dist/transport.d.ts

@@ -2,12 +2,46 @@ import { FindParams as TypesFindParams, FindResponse as TypesFindResponse } from
 export { RebaseApiError } from "@rebasepro/types";
 export type { RebaseErrorInit } from "@rebasepro/types";
 export interface RebaseClientConfig {
+    /**
+     * Origin of the Rebase server — scheme, host and port **only**.
+     *
+     * {@link apiPath} is appended to this, so do not include it here:
+     * `"http://localhost:3001"` is correct, while `"http://localhost:3001/api"`
+     * silently builds `/api/api/…` and every request 404s. Omit entirely for
+     * same-origin requests from the browser.
+     */
     baseUrl?: string;
+    /**
+     * Bearer token sent as `Authorization` on every request.
+     *
+     * In the browser this is the signed-in user's access token, so row-level
+     * security applies. Server-side callers — scripts, cron jobs, ETL — pass the
+     * service key instead, which resolves to `{ uid: "service", roles: ["admin"] }`
+     * and **bypasses RLS**: there is no user to constrain those queries, so scope
+     * them explicitly.
+     */
     token?: string;
+    /**
+     * Path the API is mounted under, appended to {@link baseUrl}.
+     * Defaults to `"/api"`; override only if the server mounts it elsewhere.
+     */
     apiPath?: string;
     fetch?: typeof globalThis.fetch;
     onUnauthorized?: () => Promise<boolean>;
     websocketUrl?: string;
+    /**
+     * Open the realtime WebSocket. **Defaults to `true`.**
+     *
+     * The socket connects as soon as the client is constructed and keeps the
+     * Node event loop alive, so a one-shot script (CLI, cron job, ETL) will not
+     * exit on its own. Set this to `false` for any process that reads or writes
+     * and then terminates — `.listen()` and `.listenById()` then throw instead
+     * of silently doing nothing.
+     *
+     * Long-lived processes that do want realtime can instead call
+     * `client.close()` when shutting down.
+     */
+    realtime?: boolean;
 }
 /**
  * Re-export from `@rebasepro/types` for backward compatibility.

package/dist/websocket.d.ts

@@ -14,7 +14,7 @@ export interface RebaseWebSocketConfig {
  * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
  * manages this internally (exposed as `client.ws`, typed by the minimal
  * `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
- * package root only because the `@rebasepro/client-postgresql` driver
+ * package root only because the `@rebasepro/client-postgres` driver
  * instantiates it directly; its surface may change without a major bump.
  */
 export declare class RebaseWebSocketClient {
@@ -23,6 +23,12 @@ export declare class RebaseWebSocketClient {
     getAuthToken?: () => Promise<string | null>;
     private subscriptions;
     private listeners;
+    /** Channel-name → handlers, for broadcast and presence frames. */
+    private channelHandlers;
+    /** Subscribe to broadcast/presence frames for one channel. */
+    onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void;
+    /** Notified after the socket comes back, so channels can re-join. */
+    onReconnect(handler: () => void): () => void;
     on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => boolean;
     private emit;
     private collectionSubscriptions;
@@ -35,6 +41,7 @@ export declare class RebaseWebSocketClient {
     private isConnected;
     private messageQueue;
     private requestTimeoutMs;
+    private subscriptionTimeoutMs;
     private reconnectTimeout;
     private isAuthenticated;
     private authPromise;
@@ -64,7 +71,11 @@ export declare class RebaseWebSocketClient {
     private handleWebSocketMessage;
     private ensureAuthenticated;
     reauthenticate(): Promise<void>;
-    private sendMessage;
+    /**
+     * Public because `RebaseRealtimeChannel` sends channel frames through it.
+     * Not part of the stable surface — prefer `client.realtime.channel(name)`.
+     */
+    sendMessage(message: Record<string, unknown>): Promise<unknown>;
     private doSendMessage;
     fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
     fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
@@ -92,6 +103,19 @@ export declare class RebaseWebSocketClient {
      */
     private deepEqual;
     private normalizeForComparison;
+    /**
+     * The address of a row, for matching it against another copy of itself.
+     *
+     * A row is exactly its columns and carries no address, so it is derived
+     * from the key columns the server named — including the ordinary case where
+     * that key is `id`, which the server reports like any other.
+     *
+     * Undefined when there are no keys, which means the server could not
+     * resolve any: such rows genuinely cannot be recognised, and guessing at a
+     * column called `id` would be inventing an identity for a table that has
+     * none.
+     */
+    private rowAddress;
     /**
      * Merge incoming rows with cached data, preserving cached references
      * for rows whose values haven't changed. This avoids unnecessary
@@ -101,6 +125,48 @@ export declare class RebaseWebSocketClient {
     private mergeRows;
     listenCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>, onUpdate: (rows: Record<string, unknown>[]) => void, onError?: (error: Error) => void): () => void;
     listenOne<M extends Record<string, unknown>>(props: FetchOneProps<M>, onUpdate: (row: Record<string, unknown> | null) => void, onError?: (error: Error) => void): () => void;
+    /**
+     * Send a `subscribe_collection` for an already-registered subscription and
+     * arm its watchdog.
+     *
+     * Every path that registers a collection subscription goes through here, so
+     * that a subscribe which never lands — a rejected send, or a server that
+     * never answers — always ends up in `failCollectionSubscription` rather than
+     * leaving the entry parked with `isInitialDataReceived === false` forever.
+     */
+    private sendCollectionSubscribe;
+    /** The `listenOne` counterpart of {@link sendCollectionSubscribe}. */
+    private sendEntitySubscribe;
+    /**
+     * Report a subscribe failure to every listener and drop the registration.
+     *
+     * Dropping it is the point: the callbacks stay live (their components are
+     * still mounted and have been told), but the next `listenCollection` for
+     * these params finds no entry and issues a fresh subscribe instead of
+     * silently attaching to a dead one.
+     */
+    private failCollectionSubscription;
+    /** The `listenOne` counterpart of {@link failCollectionSubscription}. */
+    private failEntitySubscription;
+    /**
+     * Stop the watchdogs without failing anything — used when the socket drops,
+     * since the reconnect path re-subscribes everything anyway and a watchdog
+     * firing mid-reconnect would tear down healthy subscriptions.
+     */
+    private suspendSubscribeWatchdogs;
+    /**
+     * Arm watchdogs for subscribes that were requested while offline and have
+     * just been flushed to the socket. Their timers were deliberately not set at
+     * request time, so without this they would have no timeout at all.
+     */
+    private armPendingSubscribeWatchdogs;
+    private sendCollectionSubscribeWatchdog;
+    private sendEntitySubscribeWatchdog;
+    /**
+     * Fail every subscription that never received data. Called when reconnection
+     * is given up on, so views surface an error instead of spinning forever.
+     */
+    private failAllPendingSubscriptions;
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.9.0",
+  "version": "0.9.1-canary.09aaf62",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -13,26 +13,25 @@
     "url": "https://github.com/rebasepro/rebase.git",
     "directory": "packages/client"
   },
-  "main": "./dist/index.umd.cjs",
+  "main": "./dist/index.es.js",
   "module": "./dist/index.es.js",
   "types": "./dist/index.d.ts",
   "source": "src/index.ts",
   "engines": {
-    "node": ">=14"
+    "node": ">=20"
   },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "development": "./dist/index.es.js",
-      "import": "./dist/index.es.js",
-      "require": "./dist/index.umd.cjs"
+      "import": "./dist/index.es.js"
     },
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/types": "0.9.0",
-    "@rebasepro/utils": "0.9.0",
-    "@rebasepro/common": "0.9.0"
+    "@rebasepro/common": "0.9.1-canary.09aaf62",
+    "@rebasepro/utils": "0.9.1-canary.09aaf62",
+    "@rebasepro/types": "0.9.1-canary.09aaf62"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
@@ -75,7 +74,7 @@
   },
   "scripts": {
     "watch": "vite build --watch",
-    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests --forceExit",
     "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f"

package/src/admin.ts

@@ -54,7 +54,7 @@ export function createAdmin(transport: Transport, options?: CreateAdminOptions)
     }
 
     async function resetPassword(userId: string, options?: { password?: string }) {
-        return transport.request<{ user: AdminUser; temporaryPassword?: string; invitationSent?: boolean }>(
+        return transport.request<{ user: AdminUser; temporaryPassword?: string; invitationSent?: boolean; emailDeliveryFailed?: boolean }>(
             adminPath + "/users/" + encodeURIComponent(userId) + "/reset-password",
             {
                 method: "POST",

package/src/api-keys.ts

@@ -1,6 +1,6 @@
 import type { Transport } from "./transport";
 
-// Re-define the types locally since they live in server-core, not in @rebasepro/types.
+// Re-define the types locally since they live in server, not in @rebasepro/types.
 // These match the server-side types exactly.
 
 /** A single permission entry scoping an API key to a collection and its allowed operations. */

package/src/backups.ts

@@ -0,0 +1,40 @@
+import { Transport } from "./transport";
+import type { BackupInfo, BackupDestinationKind } from "@rebasepro/types";
+
+export interface CreateBackupsOptions {
+    backupsPath?: string;
+}
+
+export function createBackups(transport: Transport, options?: CreateBackupsOptions) {
+    const backupsPath = options?.backupsPath || "/admin/backups";
+
+    async function list(): Promise<{
+        backups: BackupInfo[];
+        destinationKind: BackupDestinationKind;
+        configured: boolean;
+    }> {
+        return transport.request(backupsPath, { method: "GET" });
+    }
+
+    /**
+     * Download a backup's bytes. Uses an authenticated fetch (not the JSON
+     * transport) so the octet-stream response comes back as a Blob.
+     */
+    async function download(key: string): Promise<Blob> {
+        const token = await transport.resolveToken();
+        // Mirror transport.request's URL construction (baseUrl + apiPath + path)
+        // — this endpoint returns an octet-stream, so we fetch it directly
+        // instead of going through the JSON transport.
+        const url = `${transport.baseUrl}${transport.apiPath}${backupsPath}/download?key=${encodeURIComponent(key)}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: token ? { Authorization: `Bearer ${token}` } : {}
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to download backup (${res.status})`);
+        }
+        return res.blob();
+    }
+
+    return { list, download };
+}

package/src/collection.ts

@@ -70,6 +70,22 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             return raw as M;
         },
 
+        async createMany(data: Partial<M>[], options?: { upsert?: boolean }) {
+            if (!Array.isArray(data)) {
+                throw new TypeError("createMany expects an array of records.");
+            }
+            if (data.length === 0) return [];
+
+            const raw = await transport.request<{ data: Record<string, unknown>[] }>(`${basePath}/bulk`, {
+                method: "POST",
+                body: JSON.stringify({
+                    rows: data,
+                    ...(options?.upsert ? { upsert: true } : {})
+                })
+            });
+            return (raw.data || []) as M[];
+        },
+
         async update(id: string | number, data: Partial<M>) {
             const raw = await transport.request<Record<string, unknown>>(`${basePath}/${encodeURIComponent(String(id))}`, {
                 method: "PUT",

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 } 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,11 @@ 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 } from "./realtime-channel";
 
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
@@ -135,14 +141,24 @@ 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;
+    /**
+     * 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 +203,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 +250,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 {
@@ -395,6 +420,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         auth,
         admin,
         cron,
+        backups,
         apiKeys,
         functions,
         storage,
@@ -402,6 +428,44 @@ 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): RebaseRealtimeChannel => {
+                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.
+         *
+         * 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();
+            ws?.disconnect();
+        },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
         setOnUnauthorized: transport.setOnUnauthorized,