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

package/src/index.ts

@@ -1,36 +1,84 @@
 import { createTransport, RebaseClientConfig } from "./transport";
+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,
     RebaseClient,
-    RebaseData,
+    RebaseSdkData,
+    RowOf,
     StorageSource,
     StorageSourceDefinition,
-    StorageSourceRegistry
+    StorageSourceRegistry,
+    UpdateOf
 } from "@rebasepro/types";
 import { toSnakeCase } from "@rebasepro/utils";
 
-export * from "./transport";
-export * from "./auth";
-export * from "./admin";
-export * from "./cron";
-export * from "./api-keys";
-export * from "./collection";
-export * from "./query_builder";
-export * from "./websocket";
-export * from "./storage";
-export * from "./storage-registry";
-export * from "./reviver";
-export * from "./functions";
-export type { Entity, FindResponse } from "@rebasepro/types";
+// ─── Public API surface ──────────────────────────────────────────────────────
+//
+// This barrel is the public API of `@rebasepro/client`. It is an explicit,
+// curated list — NOT `export *` — so that adding an export to a module below
+// does not silently republish it to app developers. Internal factories
+// (`createTransport`, `createAuth`, `createCollectionClient`, …), the raw
+// `Transport`, the storage-source registry impl, the JSON reviver, and the
+// concrete `SDKQueryBuilder` class are intentionally NOT re-exported: they are
+// implementation details of `createRebaseClient()` and have no external
+// consumers. App developers reach them through the client instance, never by
+// importing the factory. To add something to the public surface, add it here
+// deliberately.
+
+// Errors — the single error type thrown by SDK HTTP calls, plus the
+// data-proxy's unknown-collection error.
+export { RebaseApiError } from "./transport";
+export { RebaseClientError } from "./errors";
+
+// Query + collection types (annotate SDK results; construct via the fluent API).
+export type { RebaseClientConfig, FindParams, FindResponse } from "./transport";
+export type { CollectionClient } from "./collection";
+export type { FindResult, SDKCollectionClient, SDKQueryBuilderInterface, PaginationMeta } from "@rebasepro/types";
+
+// Logical-condition helpers for `.where(or(...), and(...))`.
+export { QueryBuilder, or, and, cond } from "@rebasepro/common";
+
+// Auth: session/token types, config, and the pluggable storage strategies.
+export { createCookieStorage, createMemoryStorage } from "./auth";
+export type { AuthConfig, AuthStorage, CookieStorageOptions, CreateAuthOptions } from "./auth";
+export type { RebaseSession, AuthTokens, AuthChangeEvent, DeviceSession } from "@rebasepro/types";
+/** @deprecated Import `User` / `AuthTokens` from `@rebasepro/types` instead. */
+export type { RebaseUser, RebaseTokens } from "./auth";
+
+// Control-plane client option/DTO types (the client instance exposes the impls).
+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,
+    ApiKeyWithSecret,
+    CreateApiKeyRequest,
+    CreateApiKeysOptions,
+    UpdateApiKeyRequest
+} from "./api-keys";
+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-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;
@@ -62,17 +110,21 @@ type KebabToCamelCase<S extends string> =
     ? `${T}${Capitalize<KebabToCamelCase<U>>}`
     : S;
 
+// Resolve a generated `Database` entry from a (kebab-case) slug literal,
+// or `unknown` when the slug isn't in the schema — the extractors below
+// then fall back to the open row / partial shapes.
+type DBEntry<DB, S extends string> =
+    KebabToCamelCase<S> extends keyof DB ? DB[KebabToCamelCase<S>] : unknown;
+
 type TypedDataLayer<DB> = {
     collection<S extends string>(slug: S): CollectionClient<
-        KebabToCamelCase<S> extends keyof DB
-            ? (DB[KebabToCamelCase<S>] extends { Row: infer R extends Record<string, unknown> } ? R : Record<string, unknown>)
-            : Record<string, unknown>
+        RowOf<DBEntry<DB, S>>,
+        InsertOf<DBEntry<DB, S>>,
+        UpdateOf<DBEntry<DB, S>>
     >;
 } & {
-    [K in keyof DB]: CollectionClient<
-        DB[K] extends { Row: infer R extends Record<string, unknown> } ? R : Record<string, unknown>
-    >;
-} & RebaseData;
+    [K in keyof DB]: CollectionClient<RowOf<DB[K]>, InsertOf<DB[K]>, UpdateOf<DB[K]>>;
+} & RebaseSdkData;
 
 /**
  * The return type of `createRebaseClient<DB>()`.
@@ -81,7 +133,7 @@ type TypedDataLayer<DB> = {
  * capabilities populated and the `data` layer narrowed to provide
  * typed collection accessors when a `DB` schema generic is supplied.
  */
-export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<RebaseClient, "data"> & {
+export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<RebaseClient<DB>, "data" | "email"> & {
     setToken: (token: string | null) => void;
     setAuthTokenGetter: (getter: () => Promise<string | null>) => void;
     setOnUnauthorized: (handler: () => Promise<boolean>) => void;
@@ -89,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>;
 };
 
@@ -141,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);
@@ -187,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 {
@@ -241,7 +312,62 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         });
     }
 
+    /**
+     * Suggest the closest known collection key for a mistyped accessor.
+     * Uses edit-distance-1 and prefix matching — no external dependency.
+     */
+    function suggestCollection(prop: string, knownKeys: string[]): string | undefined {
+        // Prefix match (e.g. "prod" → "products")
+        const prefixMatch = knownKeys.find(k => k.startsWith(prop) || prop.startsWith(k));
+        if (prefixMatch) return prefixMatch;
+
+        // Edit-distance-1: deletions, insertions, substitutions, transpositions
+        for (const key of knownKeys) {
+            if (Math.abs(key.length - prop.length) > 1) continue;
+            let diffs = 0;
+            const longer = key.length >= prop.length ? key : prop;
+            const shorter = key.length >= prop.length ? prop : key;
+            if (longer.length === shorter.length) {
+                // Same length: allow 1 substitution or 1 transposition
+                for (let i = 0; i < longer.length; i++) {
+                    if (longer[i] !== shorter[i]) {
+                        // Check for transposition
+                        if (
+                            i + 1 < longer.length &&
+                            longer[i] === shorter[i + 1] &&
+                            longer[i + 1] === shorter[i]
+                        ) {
+                            diffs++;
+                            i++; // skip next char (already accounted for)
+                            if (diffs > 1) break;
+                            continue;
+                        }
+                        diffs++;
+                    }
+                    if (diffs > 1) break;
+                }
+            } else {
+                // Length differs by 1: allow 1 insertion/deletion
+                let li = 0;
+                let si = 0;
+                while (li < longer.length) {
+                    if (si < shorter.length && longer[li] === shorter[si]) {
+                        si++;
+                    } else {
+                        diffs++;
+                    }
+                    li++;
+                    if (diffs > 1) break;
+                }
+            }
+            if (diffs <= 1) return key;
+        }
+
+        return undefined;
+    }
+
     const collectionClients = new Map<string, CollectionClient<Record<string, unknown>>>();
+    let untypedWarned = false;
 
     function collection(slug: string): CollectionClient<Record<string, unknown>> {
         if (!collectionClients.has(slug)) {
@@ -259,11 +385,30 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             }
             if (typeof prop === "symbol") return undefined;
             if (typeof prop === "string" && prop !== "then" && prop !== "toJSON" && prop !== "$$typeof") {
-                if (options.collections && prop in options.collections) {
-                    return collection(options.collections[prop]);
+                if (options.collections) {
+                    if (prop in options.collections) {
+                        return collection(options.collections[prop]);
+                    }
+                    // Strict mode: the developer supplied a typed dictionary,
+                    // so we know the full set of valid accessors.
+                    const knownKeys = Object.keys(options.collections);
+                    const suggestion = suggestCollection(prop, knownKeys);
+                    const knownList = knownKeys.join(", ");
+                    let msg = `Unknown collection accessor "${prop}". Known collections: ${knownList}.`;
+                    if (suggestion) msg += ` Did you mean "${suggestion}"?`;
+                    msg += ` Use data.collection("<slug>") for dynamic slugs.`;
+                    throw new RebaseClientError(msg);
                 }
-                // Convert camelCase property names to snake_case slugs.
+                // Untyped fallback: convert camelCase property names to snake_case slugs.
                 // e.g. `companyMembers` → `company_members`
+                if (!untypedWarned) {
+                    untypedWarned = true;
+                    console.warn(
+                        `[Rebase] Untyped data access detected (client.data.${prop}). ` +
+                        `Collection names are resolved via snake_case conversion, which may cause silent 404s at request time. ` +
+                        `Pass a \`collections\` dictionary to createRebaseClient() or use the generated SDK for type-safe access.`
+                    );
+                }
                 const slug = toSnakeCase(prop);
                 return collection(slug);
             }
@@ -275,6 +420,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         auth,
         admin,
         cron,
+        backups,
         apiKeys,
         functions,
         storage,
@@ -282,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,
@@ -297,7 +481,6 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
             return res.data ?? (res as T);
         },
         data: dataProxy,
-        email: undefined
     } as unknown as CreateRebaseClientResult<DB>;
 
     return target;

package/src/realtime-channel.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals";
+/**
+ * The channel surface, and specifically the two protocol details it exists to
+ * hide: the roster is not pushed on join, and presence expires after 30s.
+ */
+import {
+    RebaseRealtimeChannel,
+    type ChannelTransport,
+    type PresenceState
+} from "./realtime-channel";
+
+/** Stand-in socket that records what was sent and can push frames back. */
+function fakeTransport() {
+    const sent: Record<string, unknown>[] = [];
+    let channelHandler: ((m: Record<string, unknown>) => void) | undefined;
+    let reconnectHandler: (() => void) | undefined;
+
+    const transport: ChannelTransport = {
+        sendMessage: async (message) => { sent.push(message); return undefined; },
+        onChannelMessage: (_channel, handler) => {
+            channelHandler = handler;
+            return () => { channelHandler = undefined; };
+        },
+        onReconnect: (handler) => {
+            reconnectHandler = handler;
+            return () => { reconnectHandler = undefined; };
+        }
+    };
+
+    return {
+        transport,
+        sent,
+        types: () => sent.map((m) => m.type),
+        push: (message: Record<string, unknown>) => channelHandler?.(message),
+        reconnect: () => reconnectHandler?.(),
+        hasChannelHandler: () => channelHandler !== undefined
+    };
+}
+
+describe("RebaseRealtimeChannel", () => {
+    let fake: ReturnType<typeof fakeTransport>;
+    let channel: RebaseRealtimeChannel;
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+        fake = fakeTransport();
+        channel = new RebaseRealtimeChannel("doc:42", fake.transport);
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    describe("joining", () => {
+        it("asks for the roster, because joining does not push it", async () => {
+            // A joining client's presence_diff contains only itself, so
+            // without this request the channel believes it is alone until
+            // somebody else happens to move.
+            await channel.join();
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state"]);
+        });
+
+        it("joins only once across repeated calls", async () => {
+            await channel.join();
+            await channel.join();
+            await channel.broadcast("ping", {});
+
+            expect(fake.types().filter((t) => t === "join_channel")).toHaveLength(1);
+        });
+    });
+
+    describe("presence", () => {
+        it("reports the roster from a presence_state frame", async () => {
+            const seen: PresenceState[] = [];
+            channel.onPresence((state) => seen.push(state));
+            await channel.join();
+
+            fake.push({ type: "presence_state", channel: "doc:42", presences: { a: { name: "Ana" } } });
+
+            expect(seen.at(-1)).toEqual({ a: { name: "Ana" } });
+        });
+
+        it("maintains the roster across diffs so callers never reassemble it", async () => {
+            const seen: PresenceState[] = [];
+            channel.onPresence((state) => seen.push(state));
+            await channel.join();
+
+            fake.push({ type: "presence_state", channel: "doc:42", presences: { a: { name: "Ana" } } });
+            fake.push({ type: "presence_diff", channel: "doc:42", joins: { b: { name: "Bo" } }, leaves: {} });
+
+            expect(seen.at(-1)).toEqual({ a: { name: "Ana" }, b: { name: "Bo" } });
+
+            fake.push({ type: "presence_diff", channel: "doc:42", joins: {}, leaves: { a: { name: "Ana" } } });
+
+            expect(seen.at(-1)).toEqual({ b: { name: "Bo" } });
+        });
+
+        it("passes the diff alongside the full state", async () => {
+            let lastDiff: unknown;
+            channel.onPresence((_state, diff) => { lastDiff = diff; });
+            await channel.join();
+
+            fake.push({ type: "presence_diff", channel: "doc:42", joins: { b: { x: 1 } }, leaves: {} });
+
+            expect(lastDiff).toEqual({ joins: { b: { x: 1 } }, leaves: {} });
+        });
+
+        it("re-sends presence on a timer, because it expires after 30s", async () => {
+            // Server-side PRESENCE_TIMEOUT_MS is 30s. A client that tracks once
+            // and goes quiet vanishes from everyone else's roster while still
+            // sitting in the document.
+            await channel.track({ cursor: 1 });
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(1);
+
+            await jest.advanceTimersByTimeAsync(21_000);
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(2);
+
+            await jest.advanceTimersByTimeAsync(21_000);
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(3);
+        });
+
+        it("heartbeats within the expiry window", async () => {
+            await channel.track({ cursor: 1 });
+            const before = fake.types().filter((t) => t === "presence_track").length;
+
+            // One beat must land comfortably before 30s, and with enough margin
+            // that a single dropped frame is not a disappearance.
+            await jest.advanceTimersByTimeAsync(25_000);
+
+            expect(fake.types().filter((t) => t === "presence_track").length).toBeGreaterThan(before);
+        });
+
+        it("heartbeats the latest state after a re-track", async () => {
+            await channel.track({ cursor: 1 });
+            await channel.track({ cursor: 99 });
+
+            await jest.advanceTimersByTimeAsync(21_000);
+
+            const beats = fake.sent.filter((m) => m.type === "presence_track");
+            expect(beats.at(-1)).toMatchObject({ state: { cursor: 99 } });
+        });
+
+        it("stops the heartbeat on untrack", async () => {
+            await channel.track({ cursor: 1 });
+            await channel.untrack();
+            const after = fake.types().filter((t) => t === "presence_track").length;
+
+            await jest.advanceTimersByTimeAsync(60_000);
+
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(after);
+        });
+    });
+
+    describe("broadcast", () => {
+        it("delivers events to a handler", async () => {
+            const received: unknown[] = [];
+            channel.onBroadcast((e) => received.push(e));
+            await channel.join();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "edit", payload: { at: 3 } });
+
+            expect(received).toEqual([{ event: "edit", payload: { at: 3 } }]);
+        });
+
+        it("filters by event name when one is given", async () => {
+            const received: unknown[] = [];
+            channel.onBroadcast("edit", (payload) => received.push(payload));
+            await channel.join();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "other", payload: { no: true } });
+            fake.push({ type: "broadcast", channel: "doc:42", event: "edit", payload: { yes: true } });
+
+            expect(received).toEqual([{ yes: true }]);
+        });
+
+        it("stops delivering after the returned unsubscribe", async () => {
+            const received: unknown[] = [];
+            const off = channel.onBroadcast((e) => received.push(e));
+            await channel.join();
+            off();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "edit", payload: {} });
+
+            expect(received).toEqual([]);
+        });
+    });
+
+    describe("reconnect", () => {
+        it("re-joins, re-requests the roster and re-tracks", async () => {
+            // A reconnect drops server-side membership and presence. Nothing
+            // else notices: the socket returns and the client just stops
+            // receiving.
+            await channel.track({ cursor: 7 });
+            fake.sent.length = 0;
+
+            fake.reconnect();
+            await jest.advanceTimersByTimeAsync(0);
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state", "presence_track"]);
+            expect(fake.sent.at(-1)).toMatchObject({ state: { cursor: 7 } });
+        });
+
+        it("does not re-track when the client never tracked", async () => {
+            await channel.join();
+            fake.sent.length = 0;
+
+            fake.reconnect();
+            await jest.advanceTimersByTimeAsync(0);
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state"]);
+        });
+    });
+
+    describe("leave", () => {
+        it("releases the socket handler, the timer and the listeners", async () => {
+            const received: unknown[] = [];
+            channel.onBroadcast((e) => received.push(e));
+            await channel.track({ cursor: 1 });
+
+            await channel.leave();
+
+            expect(fake.types().at(-1)).toBe("leave_channel");
+            expect(fake.hasChannelHandler()).toBe(false);
+
+            const beats = fake.types().filter((t) => t === "presence_track").length;
+            await jest.advanceTimersByTimeAsync(60_000);
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(beats);
+        });
+
+        it("can rejoin after leaving", async () => {
+            await channel.join();
+            await channel.leave();
+            fake.sent.length = 0;
+
+            await channel.join();
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state"]);
+        });
+    });
+});