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

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 {
@@ -35,6 +35,7 @@ export declare class RebaseWebSocketClient {
     private isConnected;
     private messageQueue;
     private requestTimeoutMs;
+    private subscriptionTimeoutMs;
     private reconnectTimeout;
     private isAuthenticated;
     private authPromise;
@@ -92,6 +93,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 +115,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.0fce67c",
   "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/utils": "0.9.1-canary.0fce67c",
+    "@rebasepro/common": "0.9.1-canary.0fce67c",
+    "@rebasepro/types": "0.9.1-canary.0fce67c"
   },
   "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,6 +3,7 @@ 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";
@@ -59,6 +60,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,7 +73,7 @@ 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";
 
@@ -135,14 +138,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 +200,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,7 +247,13 @@ 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;
     if (resolvedWsUrl) {
@@ -395,6 +415,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         auth,
         admin,
         cron,
+        backups,
         apiKeys,
         functions,
         storage,
@@ -402,6 +423,16 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         createStorageSource,
         fetchStorageSources,
         ws,
+        /**
+         * 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: () => {
+            ws?.disconnect();
+        },
         setToken: transport.setToken,
         setAuthTokenGetter: transport.setAuthTokenGetter,
         setOnUnauthorized: transport.setOnUnauthorized,

package/src/realtime-optout.test.ts

@@ -0,0 +1,119 @@
+import { jest } from "@jest/globals";
+import { createRebaseClient } from "./index";
+
+/**
+ * A WebSocket stand-in that records construction. The real socket keeps the Node
+ * event loop alive, which is what makes a one-shot script hang; here we only
+ * need to know whether one would have been opened at all.
+ */
+function trackingWebSocket() {
+    const opened: string[] = [];
+    const closed: string[] = [];
+
+    class FakeWebSocket {
+        static readonly OPEN = 1;
+        readyState = 0;
+        onopen: (() => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        onmessage: (() => void) | null = null;
+
+        constructor(public url: string) {
+            opened.push(url);
+        }
+
+        close() {
+            closed.push(this.url);
+        }
+
+        send() { /* no-op */ }
+    }
+
+    return { FakeWebSocket: FakeWebSocket as unknown as typeof WebSocket, opened, closed };
+}
+
+describe("realtime opt-out", () => {
+    const original = globalThis.WebSocket;
+
+    afterEach(() => {
+        globalThis.WebSocket = original;
+        jest.restoreAllMocks();
+    });
+
+    it("opens the socket by default", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+
+        expect(opened).toHaveLength(1);
+    });
+
+    it("opens no socket when realtime is disabled", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            realtime: false
+        });
+
+        // The socket is what keeps a CLI / cron / ETL process alive past its work.
+        expect(opened).toHaveLength(0);
+        expect(client.ws).toBeUndefined();
+    });
+
+    it("opens no socket when realtime is disabled even if a websocketUrl is given", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            websocketUrl: "ws://localhost:3000",
+            realtime: false
+        });
+
+        expect(opened).toHaveLength(0);
+    });
+
+    it("close() releases the socket", () => {
+        const { FakeWebSocket, opened, closed } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        expect(opened).toHaveLength(1);
+
+        client.close();
+
+        expect(closed).toHaveLength(1);
+    });
+
+    it("close() is safe when realtime was never started, and when called twice", () => {
+        const { FakeWebSocket } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const offline = createRebaseClient({ baseUrl: "http://localhost:3000/api", realtime: false });
+        expect(() => offline.close()).not.toThrow();
+
+        const live = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        live.close();
+        expect(() => live.close()).not.toThrow();
+    });
+
+    it("leaves listen() absent so callers can feature-detect, and says why via the query builder", () => {
+        const { FakeWebSocket } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            realtime: false
+        });
+
+        // `listen` stays undefined rather than becoming a throwing stub: the
+        // optional type is what makes `if (client.listen)` work and what makes
+        // TypeScript reject a bare call.
+        expect(client.collection("posts").listen).toBeUndefined();
+        expect(() => client.data.posts.include("author").listen(() => { /* noop */ }))
+            .toThrow(/realtime: false/);
+    });
+});