@rebasepro/client 0.9.1-canary.fd3754b → 0.10.0

package/dist/realtime-channel.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 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;
+    /**
+     * Per-channel sequence number, present only on retained channels.
+     *
+     * Monotonically increasing and dense, so a consumer that remembers the last
+     * one it applied can tell the server exactly where to resume from.
+     */
+    seq?: number;
+    /**
+     * True when this arrived through catch-up rather than live.
+     *
+     * Handlers do not have to care — replayed messages are delivered to the
+     * same `onBroadcast` handlers, in sequence order, so an operation stream
+     * needs no second code path. It is exposed for consumers that want to,
+     * for example, skip an animation while fast-forwarding.
+     */
+    replayed?: boolean;
+}
+/** One retained message, as returned by {@link RebaseRealtimeChannel.history}. */
+export interface ChannelHistoryEntry {
+    seq: number;
+    event: string;
+    payload: unknown;
+    senderId?: string;
+    at?: string;
+}
+/** The answer to a catch-up request. */
+export interface ChannelHistoryResult {
+    messages: ChannelHistoryEntry[];
+    /**
+     * Whether the server retains anything for this channel.
+     *
+     * False means there is no retention rule configured for it, so the empty
+     * list means "never keeps history" rather than "you missed nothing" — a
+     * client that needs to converge has to fall back to a full resync.
+     */
+    retained: boolean;
+    /** Highest sequence the server holds, even if this batch was capped. */
+    latestSeq?: number;
+}
+/** Options for a channel handle. */
+export interface ChannelOptions {
+    /**
+     * Ask the server to replay what this client missed, on join and on every
+     * reconnect.
+     *
+     * Only meaningful for a channel the *server* has a retention rule for —
+     * retention is configured on the backend, since a channel is created by
+     * whoever names it and a client-chosen history depth would let any visitor
+     * commit the backend to unbounded storage. On a channel with no rule the
+     * server answers `retained: false` and this is inert.
+     */
+    history?: boolean;
+}
+/** 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;
+    /** Whether this handle asks the server to replay missed messages. */
+    private wantsHistory;
+    /**
+     * Highest sequence number delivered to handlers so far.
+     *
+     * This is the resume point sent as `sinceSeq`, and the watermark that makes
+     * replay idempotent: catch-up ranges overlap with what arrived live, and
+     * anything at or below this has already been seen.
+     */
+    private lastSeq;
+    /**
+     * Live messages that arrived while a catch-up was in flight.
+     *
+     * Without this they would be delivered ahead of the older messages being
+     * fetched, and — worse — would advance {@link lastSeq} past them, so the
+     * catch-up response would then be discarded as already-seen and those
+     * messages would be lost for good. Held here and flushed, in order, once
+     * the replay lands.
+     */
+    private pendingLive;
+    private catchUpInFlight;
+    /**
+     * Deadline for a catch-up response.
+     *
+     * Buffering live messages is only safe because the wait is bounded. A
+     * catch-up frame that never arrives — a server that dropped it, a socket
+     * that died between request and reply — would otherwise leave the channel
+     * silently holding every subsequent edit forever, which is a worse failure
+     * than the one replay was added to fix.
+     */
+    private catchUpTimeout;
+    /**
+     * Callers of {@link history} awaiting the next `channel_history` frame.
+     *
+     * These frames are addressed by channel rather than by request id, so they
+     * are matched in arrival order. Requests on one channel are serialized by
+     * the socket, so FIFO is the right correlation here.
+     */
+    private historyWaiters;
+    constructor(name: string, transport: ChannelTransport, options?: ChannelOptions);
+    /**
+     * Turn on catch-up for a handle that was created without it.
+     *
+     * The client hands back the same channel object for a given name, so a
+     * later `channel(name, { history: true })` has no new object to configure —
+     * it upgrades this one instead. Idempotent, and never downgrades: one
+     * caller asking for history must not be switched off by another that did
+     * not ask.
+     */
+    enableHistory(): void;
+    /**
+     * 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.
+     */
+    /**
+     * Send a channel message.
+     *
+     * Every channel message is read by the server out of a `payload` envelope
+     * (`payload?.channel`, `payload?.state`, `payload?.event`). Sending those
+     * fields flat does not error: `payload?.channel` simply reads as
+     * `undefined`, so the client is registered into channel `undefined` with
+     * empty state, and the echo comes back with no `channel` for
+     * `onChannelMessage` to match — presence and broadcast both go quiet with
+     * nothing logged. Funnelled through one place so a new message type cannot
+     * reintroduce that.
+     */
+    private send;
+    join(): Promise<void>;
+    private rejoin;
+    /**
+     * Ask the server for everything after {@link lastSeq}.
+     *
+     * Live messages are buffered from here until the answer arrives — see
+     * {@link pendingLive}.
+     */
+    private requestHistory;
+    /**
+     * Give up waiting for a catch-up and release what was held back.
+     *
+     * The buffered messages are still the freshest thing this client has, so
+     * they are delivered rather than dropped. Callers of {@link history} are
+     * answered with `retained: false` — accurate in the sense that matters:
+     * this client has no history to work from and has to resync.
+     */
+    private abandonCatchUp;
+    /**
+     * 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;
+    /**
+     * The last sequence number this channel has delivered.
+     *
+     * Zero on a channel that retains nothing. Persist it if you want catch-up
+     * to survive a page reload as well as a reconnect, and pass it back via
+     * {@link history}.
+     */
+    get sequence(): number;
+    /**
+     * Fetch retained messages explicitly, instead of waiting for join or
+     * reconnect to do it.
+     *
+     * Defaults to resuming from {@link sequence}. Messages are delivered to
+     * `onBroadcast` handlers as usual — the returned value is for callers that
+     * want to inspect the batch, or to learn from `retained` that the channel
+     * keeps no history at all.
+     */
+    history(options?: {
+        sinceSeq?: number;
+        limit?: number;
+    }): Promise<ChannelHistoryResult>;
+    /** 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;
+    /** Deliver everything held back during a catch-up, in sequence order. */
+    private flushPendingLive;
+    private deliver;
+    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

@@ -23,6 +23,23 @@ export declare class RebaseWebSocketClient {
     getAuthToken?: () => Promise<string | null>;
     private subscriptions;
     private listeners;
+    /** Channel-name → handlers, for broadcast and presence frames. */
+    private channelHandlers;
+    /** Set by `close()`. Blocks any later operation from silently redialling. */
+    private closedByCaller;
+    /**
+     * 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(): boolean;
+    /** So the "no WebSocket in this environment" warning is said once, not per call. */
+    private warnedNoWebSocket;
+    /** 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 +52,7 @@ export declare class RebaseWebSocketClient {
     private isConnected;
     private messageQueue;
     private requestTimeoutMs;
+    private subscriptionTimeoutMs;
     private reconnectTimeout;
     private isAuthenticated;
     private authPromise;
@@ -42,6 +60,14 @@ export declare class RebaseWebSocketClient {
     onUnauthorized?: () => Promise<boolean>;
     private refreshInProgress;
     constructor(config: RebaseWebSocketConfig);
+    /**
+     * 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(): void;
     /**
      * Authenticate the WebSocket connection
      */
@@ -50,7 +76,15 @@ export declare class RebaseWebSocketClient {
      * Set the auth token getter function
      */
     setAuthTokenGetter(getAuthToken: () => Promise<string | null>): void;
-    disconnect(): void;
+    /**
+     * 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?: boolean): void;
     private initWebSocket;
     private processMessageQueue;
     private attemptReconnect;
@@ -64,7 +98,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>;
@@ -76,6 +114,7 @@ export declare class RebaseWebSocketClient {
     }): Promise<Record<string, unknown>[]>;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
+    fetchApplicationRoles(): Promise<string[]>;
     fetchCurrentDatabase(): Promise<string | undefined>;
     checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
     count<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
@@ -92,6 +131,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 +153,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.1-canary.fd3754b",
+  "version": "0.10.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -13,37 +13,38 @@
     "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/common": "0.9.1-canary.fd3754b",
-    "@rebasepro/types": "0.9.1-canary.fd3754b",
-    "@rebasepro/utils": "0.9.1-canary.fd3754b"
+    "@rebasepro/utils": "0.10.0",
+    "@rebasepro/types": "0.10.0",
+    "@rebasepro/common": "0.10.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.9.3",
+    "@types/ws": "^8.18.1",
     "cross-env": "^10.1.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11",
     "tsd": "^0.33.0",
     "typescript": "^6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "ws": "^8.21.0"
   },
   "files": [
     "dist",
@@ -75,7 +76,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/auth.ts

@@ -516,6 +516,37 @@ newPassword })
         });
     }
 
+    /**
+     * Link an OAuth provider to the **currently signed-in** account.
+     *
+     * Use this when `signIn*` failed with `EMAIL_NOT_VERIFIED` — an account
+     * with that email already exists under a different sign-in method — or to
+     * attach a provider whose email differs from the account's.
+     *
+     * The payload is the same one the provider's sign-in method takes, e.g.
+     * `linkProvider("google", { idToken })`.
+     *
+     * Unlike sign-in, this does not require the provider to have verified the
+     * email, and the emails need not match: the active session already proves
+     * account ownership.
+     *
+     * Throws `IDENTITY_ALREADY_LINKED` (409) if that provider identity is
+     * attached to a different user. Succeeds idempotently (`alreadyLinked:
+     * true`) if it is already attached to the current one.
+     */
+    async function linkProvider(
+        providerId: string,
+        payload: Record<string, unknown>
+    ) {
+        return transport.request<{ success: boolean; provider: string; alreadyLinked: boolean; }>(
+            authPath + "/link/" + providerId,
+            {
+                method: "POST",
+                body: JSON.stringify(payload)
+            }
+        );
+    }
+
     async function sendVerificationEmail() {
         return transport.request<{ success: boolean; message: string; }>(authPath + "/send-verification", {
             method: "POST"
@@ -666,6 +697,7 @@ refreshToken: session.refreshToken };
         resetPasswordForEmail,
         resetPassword,
         changePassword,
+        linkProvider,
         sendVerificationEmail,
         verifyEmail,
         sendMagicLink,

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",