@rebasepro/client 0.8.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/sdk_query_builder.d.ts

@@ -0,0 +1,63 @@
+import { FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValue } from "@rebasepro/types";
+/**
+ * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
+ * Entity-wrapped results (`FindResponse<M>`).
+ *
+ * @example
+ * const { data } = await rebase.data.posts
+ *     .where("status", "==", "published")
+ *     .orderBy("created_at", "desc")
+ *     .limit(10)
+ *     .find();
+ *
+ * console.log(data[0].title); // flat access
+ */
+export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements SDKQueryBuilderInterface<M> {
+    private collection;
+    private params;
+    constructor(collection: SDKCollectionClient<M>);
+    /**
+     * Add a filter condition to your query.
+     * @example
+     * client.data.users.where('age', '>=', 18).find()
+     */
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
+    /**
+     * Order the results by a specific column.
+     */
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    /**
+     * Limit the number of results returned.
+     */
+    limit(count: number): this;
+    /**
+     * Skip the first N results.
+     */
+    offset(count: number): this;
+    /**
+     * Set a free-text search string if supported by the backend.
+     */
+    search(searchString: string): this;
+    /**
+     * Include related entities in the response.
+     * Relations will be populated with full data instead of just IDs.
+     *
+     * @param relations - Relation names to include, or "*" for all.
+     * @example
+     * client.data.posts.include("tags", "author").find()
+     */
+    include(...relations: string[]): this;
+    /**
+     * Execute the find query and return the results as flat rows.
+     */
+    find(): Promise<FindResult<M>>;
+    /**
+     * Count the records matching this query.
+     */
+    count(): Promise<number>;
+    /**
+     * Listen to realtime updates matching this query.
+     */
+    listen(onUpdate: (data: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+}

package/dist/transport.d.ts

@@ -1,23 +1,53 @@
 import { FindParams as TypesFindParams, FindResponse as TypesFindResponse } from "@rebasepro/types";
+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.
  */
 export type FindParams = TypesFindParams;
 export type FindResponse<T> = TypesFindResponse<T extends Record<string, unknown> ? T : Record<string, unknown>>;
-export declare class RebaseApiError extends Error {
-    status: number;
-    code?: string;
-    details?: unknown;
-    constructor(status: number, message: string, code?: string, details?: unknown);
-}
 export declare function buildQueryString(params?: FindParams): string;
 export interface Transport {
     request: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;

package/dist/websocket.d.ts

@@ -1,4 +1,4 @@
-import { DeleteEntityProps, Entity, EntityCollection, FetchCollectionProps, FetchEntityProps, SaveEntityProps, TableMetadata, BranchInfo } from "@rebasepro/types";
+import { DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, SaveProps, TableMetadata, BranchInfo } from "@rebasepro/types";
 export interface RebaseWebSocketConfig {
     websocketUrl: string;
     /** Optional auth token getter for WebSocket authentication */
@@ -8,21 +8,31 @@ export interface RebaseWebSocketConfig {
     /** Callback to handle unauthorized requests or token expiration (refreshes auth session) */
     onUnauthorized?: () => Promise<boolean>;
 }
-export declare class ApiError extends Error {
-    code?: string;
-    error?: string;
-    constructor(message: string, error?: string, code?: string);
-}
+/**
+ * Low-level realtime WebSocket client.
+ *
+ * @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-postgres` driver
+ * instantiates it directly; its surface may change without a major bump.
+ */
 export declare class RebaseWebSocketClient {
     private websocketUrl;
     private ws;
     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;
-    private entitySubscriptions;
+    private singleSubscriptions;
     private backendToCollectionKey;
     private backendToEntityKey;
     private pendingRequests;
@@ -31,6 +41,7 @@ export declare class RebaseWebSocketClient {
     private isConnected;
     private messageQueue;
     private requestTimeoutMs;
+    private subscriptionTimeoutMs;
     private reconnectTimeout;
     private isAuthenticated;
     private authPromise;
@@ -53,19 +64,23 @@ export declare class RebaseWebSocketClient {
     private isAuthError;
     private handleAuthFailure;
     /**
-     * Shared logic for re-subscribing a collection or entity subscription
+     * Shared logic for re-subscribing a collection or row subscription
      * after an auth error is resolved by refreshing credentials.
      */
     private resubscribeAfterAuthRefresh;
     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<Entity<M>[]>;
-    fetchEntity<M extends Record<string, unknown>>(props: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
-    saveEntity<M extends Record<string, unknown>>(props: SaveEntityProps<M>): Promise<Entity<M>>;
-    deleteEntity<M extends Record<string, unknown>>(props: DeleteEntityProps<M>): Promise<void>;
+    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>;
+    save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
+    delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
     executeSql(sql: string, options?: {
         database?: string;
         role?: string;
@@ -73,8 +88,8 @@ export declare class RebaseWebSocketClient {
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
     fetchCurrentDatabase(): Promise<string | undefined>;
-    checkUniqueField(path: string, name: string, value: unknown, entityId?: string, collection?: EntityCollection): Promise<boolean>;
-    countEntities<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
+    checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
+    count<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
     fetchUnmappedTables(mappedPaths?: string[]): Promise<string[]>;
     fetchTableMetadata(tableName: string): Promise<TableMetadata>;
     createBranch(name: string, options?: {
@@ -89,14 +104,69 @@ export declare class RebaseWebSocketClient {
     private deepEqual;
     private normalizeForComparison;
     /**
-     * Merge incoming entities with cached data, preserving cached references
-     * for entities whose values haven't changed. This avoids unnecessary
-     * React re-renders when the server refetches all entities but most
+     * 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
+     * React re-renders when the server refetches all rows but most
      * haven't actually changed.
      */
-    private mergeEntities;
-    listenCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>, onUpdate: (entities: Entity[]) => void, onError?: (error: Error) => void): () => void;
-    listenEntity<M extends Record<string, unknown>>(props: FetchEntityProps<M>, onUpdate: (entity: Entity | null) => void, onError?: (error: Error) => void): () => void;
+    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
@@ -104,5 +174,5 @@ export declare class RebaseWebSocketClient {
      */
     private resubscribeAll;
     private createCollectionSubscriptionKey;
-    private createEntitySubscriptionKey;
+    private createSingleSubscriptionKey;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.8.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/common": "0.8.0",
-    "@rebasepro/types": "0.8.0",
-    "@rebasepro/utils": "0.8.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. */