@rebasepro/client 0.9.1-canary.ff338b5 → 0.10.0

package/dist/realtime-channel.d.ts

@@ -32,6 +32,58 @@ export interface PresenceDiff {
 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 {
@@ -51,7 +103,56 @@ export declare class RebaseRealtimeChannel {
     private trackedState;
     private heartbeat;
     private joined;
-    constructor(name: string, transport: ChannelTransport);
+    /** 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.
      *
@@ -74,6 +175,22 @@ export declare class RebaseRealtimeChannel {
     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.
      *
@@ -93,10 +210,34 @@ export declare class RebaseRealtimeChannel {
     /** 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/websocket.d.ts

@@ -114,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>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.9.1-canary.ff338b5",
+  "version": "0.10.0",
   "description": "HTTP SDK client for the Rebase custom backend",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -29,9 +29,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@rebasepro/common": "0.9.1-canary.ff338b5",
-    "@rebasepro/types": "0.9.1-canary.ff338b5",
-    "@rebasepro/utils": "0.9.1-canary.ff338b5"
+    "@rebasepro/utils": "0.10.0",
+    "@rebasepro/types": "0.10.0",
+    "@rebasepro/common": "0.10.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

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/index.ts

@@ -10,7 +10,7 @@ import { createFunctionsClient } from "./functions";
 import { createStorage } from "./storage";
 import { ClientStorageSourceRegistry } from "./storage-registry";
 import { RebaseWebSocketClient } from "./websocket";
-import { RebaseRealtimeChannel } from "./realtime-channel";
+import { RebaseRealtimeChannel, type ChannelOptions } from "./realtime-channel";
 import {
     DEFAULT_STORAGE_SOURCE_KEY,
     InsertOf,
@@ -78,7 +78,15 @@ export type { FunctionInvokeOptions, FunctionsClient } from "./functions";
 // 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 type {
+    PresenceState,
+    PresenceDiff,
+    BroadcastEvent,
+    ChannelTransport,
+    ChannelOptions,
+    ChannelHistoryEntry,
+    ChannelHistoryResult
+} from "./realtime-channel";
 
 export interface CreateRebaseClientOptions extends RebaseClientConfig {
     auth?: CreateAuthOptions;
@@ -157,8 +165,11 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
          * Join a broadcast/presence channel. Repeated calls with the same name
          * return the same channel object. Throws only when the client was
          * created with `realtime: false`.
+         *
+         * Pass `{ history: true }` to have the channel replay what it missed on
+         * join and on every reconnect, for channels the server retains.
          */
-        channel: (name: string) => RebaseRealtimeChannel;
+        channel: (name: string, options?: ChannelOptions) => RebaseRealtimeChannel;
     };
     /**
      * Release the realtime socket and its reconnect timer.
@@ -458,7 +469,7 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
              * own membership — and `leave()` from one would otherwise silently
              * cut off the others.
              */
-            channel: (name: string): RebaseRealtimeChannel => {
+            channel: (name: string, options?: ChannelOptions): RebaseRealtimeChannel => {
                 // Only `realtime: false` gets here — a hard opt-out, so this
                 // stays an error. Being merely *unconnected* does not: the
                 // socket opens on the first channel operation, which is the
@@ -470,8 +481,15 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
                 }
                 let existing = realtimeChannels.get(name);
                 if (!existing) {
-                    existing = new RebaseRealtimeChannel(name, ws);
+                    existing = new RebaseRealtimeChannel(name, ws, options);
                     realtimeChannels.set(name, existing);
+                } else if (options?.history) {
+                    // Same object by name, so options on a later call have no
+                    // new channel to apply to. Asking for history upgrades the
+                    // one that exists rather than being quietly ignored — but
+                    // never the reverse, so a caller that omits the option
+                    // cannot switch it off under one that asked for it.
+                    existing.enableHistory();
                 }
                 return existing;
             }

package/src/realtime-channel.test.ts

@@ -5,6 +5,7 @@ import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals
  */
 import {
     RebaseRealtimeChannel,
+    type BroadcastEvent,
     type ChannelTransport,
     type PresenceState
 } from "./realtime-channel";
@@ -100,6 +101,211 @@ describe("RebaseRealtimeChannel", () => {
                 payload: { channel: "doc:42", event: "saved", payload: { version: 3 } }
             });
         });
+
+        it("carries the catch-up cursor inside the envelope", async () => {
+            // Same failure mode as the rest: `payload?.sinceSeq` read flat is
+            // undefined, which the server would treat as "replay from zero" —
+            // a client asking to resume would silently get the whole history
+            // back and re-apply every operation it had already applied.
+            const retained = new RebaseRealtimeChannel("doc:42", fake.transport, { history: true });
+            await retained.join();
+
+            const request = fake.sent.find((m) => m.type === "channel_history");
+            expect(request).toMatchObject({
+                type: "channel_history",
+                payload: { channel: "doc:42", sinceSeq: 0 }
+            });
+            expect(request).not.toHaveProperty("sinceSeq");
+        });
+    });
+
+    describe("history", () => {
+        /**
+         * A joined channel that asks for catch-up.
+         *
+         * `settle` answers the join-time history request the way a server does.
+         * Without it the channel is legitimately still catching up, and holds
+         * live messages back — which is the behaviour one test below asserts on
+         * purpose.
+         */
+        async function retainedChannel({ settle = true } = {}) {
+            const c = new RebaseRealtimeChannel("doc:42", fake.transport, { history: true });
+            const received: BroadcastEvent[] = [];
+            c.onBroadcast((e) => received.push(e));
+            await c.join();
+            // `onBroadcast` already started a join, so the `await` above returns
+            // on the second (idempotent) call while the first is still working
+            // through its sends. Let it finish, or the history request has not
+            // been made yet and there is nothing for `settle` to answer.
+            await jest.advanceTimersByTimeAsync(0);
+            if (settle) {
+                fake.push({ type: "channel_history", channel: "doc:42", retained: true, messages: [] });
+            }
+            return { channel: c, received };
+        }
+
+        it("asks for history on join, and only when asked to", async () => {
+            await channel.join();
+            expect(fake.types()).not.toContain("channel_history");
+
+            fake.sent.length = 0;
+            const { channel: retained } = await retainedChannel();
+            expect(fake.types()).toContain("channel_history");
+            expect(retained.sequence).toBe(0);
+        });
+
+        it("tracks the sequence of live messages", async () => {
+            const { channel: retained, received } = await retainedChannel();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 }, seq: 1 });
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 2 }, seq: 2 });
+
+            expect(received.map((e) => e.seq)).toEqual([1, 2]);
+            expect(retained.sequence).toBe(2);
+        });
+
+        it("delivers replayed messages through the same handlers, marked as replay", async () => {
+            const { channel: retained, received } = await retainedChannel();
+
+            fake.push({
+                type: "channel_history",
+                channel: "doc:42",
+                retained: true,
+                latestSeq: 2,
+                messages: [
+                    { seq: 1, event: "op", payload: { n: 1 } },
+                    { seq: 2, event: "op", payload: { n: 2 } }
+                ]
+            });
+
+            expect(received.map((e) => e.payload)).toEqual([{ n: 1 }, { n: 2 }]);
+            expect(received.every((e) => e.replayed)).toBe(true);
+            expect(retained.sequence).toBe(2);
+        });
+
+        it("never re-delivers a message it already saw", async () => {
+            // Catch-up ranges overlap with what arrived live — the server
+            // cannot know exactly what landed before the socket dropped. The
+            // watermark is what makes replaying an overlap harmless.
+            const { received } = await retainedChannel();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 }, seq: 1 });
+            fake.push({
+                type: "channel_history",
+                channel: "doc:42",
+                retained: true,
+                messages: [
+                    { seq: 1, event: "op", payload: { n: 1 } },
+                    { seq: 2, event: "op", payload: { n: 2 } }
+                ]
+            });
+
+            expect(received.map((e) => e.payload)).toEqual([{ n: 1 }, { n: 2 }]);
+        });
+
+        it("holds live messages back until the catch-up lands, then orders them", async () => {
+            // The subtle one. A live message arriving mid-catch-up would
+            // otherwise be delivered first AND advance the watermark past the
+            // older messages still in flight — which the catch-up response
+            // would then discard as already-seen. Those messages would be lost
+            // silently, which is precisely the failure history exists to fix.
+            const { channel: retained, received } = await retainedChannel({ settle: false });
+
+            // seq 5 arrives while the replay of 1..4 is still on the wire.
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 5 }, seq: 5 });
+            expect(received).toHaveLength(0);
+
+            fake.push({
+                type: "channel_history",
+                channel: "doc:42",
+                retained: true,
+                messages: [
+                    { seq: 3, event: "op", payload: { n: 3 } },
+                    { seq: 4, event: "op", payload: { n: 4 } }
+                ]
+            });
+
+            expect(received.map((e) => e.seq)).toEqual([3, 4, 5]);
+            expect(retained.sequence).toBe(5);
+        });
+
+        it("leaves unsequenced channels completely untouched", async () => {
+            // An ephemeral channel retains nothing, so its broadcasts carry no
+            // seq. They must not be buffered, deduped or reordered.
+            const received: BroadcastEvent[] = [];
+            channel.onBroadcast((e) => received.push(e));
+            await channel.join();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "cursor", payload: { x: 1 } });
+            fake.push({ type: "broadcast", channel: "doc:42", event: "cursor", payload: { x: 2 } });
+
+            expect(received.map((e) => e.payload)).toEqual([{ x: 1 }, { x: 2 }]);
+            expect(received.every((e) => e.seq === undefined)).toBe(true);
+            expect(channel.sequence).toBe(0);
+        });
+
+        it("resumes from the last sequence on reconnect", async () => {
+            const { channel: retained } = await retainedChannel();
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 }, seq: 7 });
+            fake.sent.length = 0;
+
+            fake.reconnect();
+            await jest.advanceTimersByTimeAsync(0);
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state", "channel_history"]);
+            expect(fake.sent.at(-1)).toMatchObject({ payload: { channel: "doc:42", sinceSeq: 7 } });
+            expect(retained.sequence).toBe(7);
+        });
+
+        it("stops holding messages back if the catch-up never arrives", async () => {
+            // Buffering is only safe because the wait is bounded. A reply that
+            // never comes would otherwise leave the channel silently swallowing
+            // every edit from then on — worse than the problem replay solves.
+            const { received } = await retainedChannel({ settle: false });
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 }, seq: 1 });
+            expect(received).toHaveLength(0);
+
+            await jest.advanceTimersByTimeAsync(11_000);
+
+            expect(received.map((e) => e.payload)).toEqual([{ n: 1 }]);
+        });
+
+        it("reports a channel that keeps no history, rather than an empty one", async () => {
+            const { channel: retained } = await retainedChannel();
+
+            const pending = retained.history();
+            await jest.advanceTimersByTimeAsync(0);
+            fake.push({ type: "channel_history", channel: "doc:42", retained: false, messages: [] });
+
+            // The distinction matters: `retained: false` tells a client its
+            // reconnect strategy has to be a full resync.
+            await expect(pending).resolves.toEqual({
+                messages: [], retained: false, latestSeq: undefined
+            });
+        });
+
+        it("upgrades an existing channel when history is asked for later", async () => {
+            // The client hands back the same object per name, so a later
+            // `channel(name, { history: true })` has nothing new to configure.
+            await channel.join();
+            fake.sent.length = 0;
+
+            channel.enableHistory();
+            await jest.advanceTimersByTimeAsync(0);
+
+            expect(fake.types()).toContain("channel_history");
+        });
+
+        it("forgets its position on leave, so a rejoin does not skip the past", async () => {
+            const { channel: retained } = await retainedChannel();
+            fake.push({ type: "broadcast", channel: "doc:42", event: "op", payload: {}, seq: 9 });
+            expect(retained.sequence).toBe(9);
+
+            await retained.leave();
+
+            expect(retained.sequence).toBe(0);
+        });
     });
 
     describe("joining", () => {