@rebasepro/client 0.13.0 → 0.13.1-canary.g18cfeb7

package/src/offline.test.ts

@@ -16,7 +16,7 @@ type Row = Record<string, unknown>;
 function createFakeServer() {
     const state = { online: true };
     const tables = new Map<string, Map<string, Row>>();
-    const log: { collection: string; op: string; id?: unknown; upsert?: boolean }[] = [];
+    const log: { collection: string; op: string; id?: unknown; ids?: unknown[]; upsert?: boolean }[] = [];
 
     function table(slug: string): Map<string, Row> {
         if (!tables.has(slug)) tables.set(slug, new Map());
@@ -67,11 +67,30 @@ function createFakeServer() {
                 table(slug).set(String(id), row);
                 return row;
             },
+            async updateMany(updates: { id: string | number; data: Partial<Row> }[]) {
+                assertOnline();
+                log.push({ collection: slug, op: "updateMany", ids: updates.map(u => u.id) });
+                return updates.map(({ id, data }) => {
+                    const existing = table(slug).get(String(id));
+                    if (!existing) throw new RebaseApiError("Not found", { status: 404 });
+                    const row = { ...existing, ...data };
+                    table(slug).set(String(id), row);
+                    return row;
+                });
+            },
             async delete(id: string | number) {
                 assertOnline();
                 log.push({ collection: slug, op: "delete", id });
                 table(slug).delete(String(id));
             },
+            async deleteMany(ids: (string | number)[]) {
+                assertOnline();
+                log.push({ collection: slug, op: "deleteMany", ids });
+                for (const id of ids) {
+                    if (!table(slug).has(String(id))) throw new RebaseApiError("Not found", { status: 404 });
+                }
+                for (const id of ids) table(slug).delete(String(id));
+            },
             async count(_params?: FindParams) {
                 assertOnline();
                 return table(slug).size;
@@ -503,6 +522,100 @@ describe("OfflineManager", () => {
         });
     });
 
+    describe("updateMany / deleteMany", () => {
+        it("queues a bulk update offline, overlays it, and replays it once", async () => {
+            const server = createFakeServer();
+            const { manager, wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.create({ title: "a" });
+            await posts.create({ title: "b" });
+            const seeded = (await posts.find()).data;
+
+            server.state.online = false;
+            const updated = await posts.updateMany(
+                seeded.map((r) => ({ id: r.id as string, data: { title: `${r.title}!` } }))
+            );
+            expect(updated.map((r) => r.title)).toEqual(["a!", "b!"]);
+
+            // The overlay is what a UI renders while the write is queued.
+            const overlaid = await posts.find();
+            expect(overlaid.data.map((r) => r.title).sort()).toEqual(["a!", "b!"]);
+
+            server.state.online = true;
+            await manager.sync();
+            const bulk = server.log.filter((e) => e.op === "updateMany");
+            expect(bulk).toHaveLength(1);
+            expect([...server.table("posts").values()].map((r) => r.title).sort()).toEqual(["a!", "b!"]);
+        });
+
+        it("queues a bulk delete offline, hides the rows, and replays it once", async () => {
+            const server = createFakeServer();
+            const { manager, wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.create({ title: "a" });
+            await posts.create({ title: "b" });
+            await posts.create({ title: "c" });
+            const seeded = (await posts.find()).data;
+
+            server.state.online = false;
+            await posts.deleteMany(seeded.slice(0, 2).map((r) => r.id as string));
+
+            const overlaid = await posts.find();
+            expect(overlaid.data.map((r) => r.title)).toEqual(["c"]);
+
+            server.state.online = true;
+            await manager.sync();
+            const bulk = server.log.filter((e) => e.op === "deleteMany");
+            expect(bulk).toHaveLength(1);
+            expect([...server.table("posts").values()].map((r) => r.title)).toEqual(["c"]);
+        });
+
+        it("queues a bulk update whose rows have writes still pending", async () => {
+            // Splitting the batch — some rows now, some later — would break the
+            // one guarantee a batch makes, and would reorder a write against a
+            // row whose own create has not landed yet.
+            const server = createFakeServer();
+            const { manager, wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.find();
+
+            server.state.online = false;
+            const created = await posts.create({ title: "fresh" });
+            await posts.updateMany([{ id: created.id as string, data: { title: "edited" } }]);
+
+            server.state.online = true;
+            await manager.sync();
+
+            // The create ran first, then the batch — order preserved.
+            expect(server.log.map((e) => e.op)).toEqual(["create", "updateMany"]);
+            expect([...server.table("posts").values()][0].title).toBe("edited");
+        });
+
+        it("goes straight to the server when online", async () => {
+            const server = createFakeServer();
+            const { wrap } = createManager(server);
+            const posts = wrap("posts");
+            const a = await posts.create({ title: "a" });
+
+            await posts.updateMany([{ id: a.id as string, data: { title: "A" } }]);
+            expect(server.table("posts").get(String(a.id))!.title).toBe("A");
+
+            await posts.deleteMany([a.id as string]);
+            expect(server.table("posts").size).toBe(0);
+        });
+
+        it("treats empty input as a no-op that touches neither queue nor server", async () => {
+            const server = createFakeServer();
+            const { wrap } = createManager(server);
+            const posts = wrap("posts");
+            await posts.find();
+
+            expect(await posts.updateMany([])).toEqual([]);
+            await posts.deleteMany([]);
+            expect(server.log.filter((e) => e.op.endsWith("Many"))).toHaveLength(0);
+        });
+    });
+
     describe("concurrency", () => {
         it("gives concurrent offline writes distinct, ordered mutation ids", async () => {
             const server = createFakeServer();

package/src/offline.ts

@@ -1,5 +1,5 @@
 import { buildQueryString, FindParams, RebaseApiError } from "./transport";
-import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue } from "@rebasepro/types";
+import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue, WriteOptions } from "@rebasepro/types";
 import { collectAllPages, paginateFind } from "@rebasepro/common";
 import { CollectionClient, LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
 import { SDKQueryBuilder } from "./sdk_query_builder";
@@ -15,6 +15,7 @@ import {
 import {
     isExactlyEvaluable,
     matchesParams,
+    resolvePagination,
     runLocalQuery,
     sortRows
 } from "./offline-query";
@@ -545,6 +546,83 @@ export class OfflineManager {
                 return rows;
             },
 
+            updateMany: async (updates: { id: string | number; data: Partial<M> }[], options?: WriteOptions) => {
+                await this.ensureCollection(slug);
+                if (!Array.isArray(updates)) {
+                    throw new TypeError("updateMany expects an array of { id, data } entries.");
+                }
+                if (updates.length === 0) return [];
+                // Any row in the batch with a write already queued sends the
+                // whole batch to the queue. Splitting it — some rows now, some
+                // later — would break the one guarantee a batch makes, that its
+                // rows land together, and would reorder writes against a row
+                // whose own create has not landed yet.
+                const anyPending = updates.some((u) => this.hasPending(slug, u.id));
+                if (this.connectivity.shouldAttempt() && !anyPending) {
+                    try {
+                        const rows = await inner.updateMany(updates, options);
+                        this.connectivity.markSuccess();
+                        await this.ingest(slug, rows);
+                        this.notifyCollection(slug);
+                        return rows;
+                    } catch (error) {
+                        if (!isNetworkError(error)) throw error;
+                        this.connectivity.markFailure();
+                    }
+                }
+                const rollback: Record<string, AnyRow | null> = {};
+                const optimistic: M[] = [];
+                for (const { id, data } of updates) {
+                    const base = this.rawLocalRow(slug, id);
+                    rollback[String(id)] = base ?? null;
+                    optimistic.push({ ...(base ?? {}), ...(data as AnyRow), id } as unknown as M);
+                }
+                await this.enqueue({
+                    collection: slug,
+                    type: "updateMany",
+                    updates: updates.map((u) => ({ id: u.id,
+data: u.data as AnyRow })),
+                    rollback: { rows: rollback }
+                });
+                for (const row of optimistic) this.setLocalRow(slug, row.id as string | number, row);
+                this.notifyCollection(slug);
+                return optimistic;
+            },
+
+            deleteMany: async (ids: (string | number)[], options?: WriteOptions) => {
+                await this.ensureCollection(slug);
+                if (!Array.isArray(ids)) {
+                    throw new TypeError("deleteMany expects an array of ids.");
+                }
+                if (ids.length === 0) return;
+                const anyPending = ids.some((id) => this.hasPending(slug, id));
+                if (this.connectivity.shouldAttempt() && !anyPending) {
+                    try {
+                        await inner.deleteMany(ids, options);
+                        this.connectivity.markSuccess();
+                        for (const id of ids) this.removeLocalRow(slug, id, true);
+                        this.notifyCollection(slug);
+                        this.scheduleRefresh(slug);
+                        return;
+                    } catch (error) {
+                        if (!isNetworkError(error)) throw error;
+                        this.connectivity.markFailure();
+                    }
+                }
+                const rollback: Record<string, AnyRow | null> = {};
+                for (const id of ids) {
+                    rollback[String(id)] = this.rawLocalRow(slug, id) ?? null;
+                }
+                await this.enqueue({
+                    collection: slug,
+                    type: "deleteMany",
+                    ids,
+                    rollback: { rows: rollback }
+                });
+                for (const id of ids) this.removeLocalRow(slug, id, false);
+                this.notifyCollection(slug);
+            },
+
             update: async (id: string | number, data: Partial<M>) => {
                 await this.ensureCollection(slug);
                 // Never overtake a write already queued for this row. The
@@ -942,7 +1020,7 @@ export class OfflineManager {
         if (!state) {
             return {
                 data: [],
-                meta: { total: 0, limit: params?.limit ?? 20, offset: params?.offset ?? 0, hasMore: false },
+                meta: { ...resolvePagination(params), total: 0, hasMore: false },
                 fromCache: true,
                 hasPendingWrites: false,
                 partial: true
@@ -996,9 +1074,18 @@ export class OfflineManager {
                 rows.push(entry.row as M);
                 added++;
             }
-            if (added > 0 && params?.orderBy) sortRows(rows, params.orderBy);
         }
 
+        // Order is part of the query, not a detail of how the rows were
+        // obtained. This used to sort only when a locally-created row had been
+        // injected — every other read handed back cache order, which is
+        // insertion order, and a caller that asked for `orderBy` got whatever
+        // the store happened to hold. In the admin that is the collection's
+        // `sort` being silently ignored on every list backed by this overlay:
+        // the query carries it, the server honours it, and the answer served
+        // from here did not.
+        if (params?.orderBy) sortRows(rows, params.orderBy);
+
         const total = Math.max(rows.length, snapshot.total - removed + added);
         return {
             data: rows,
@@ -1150,12 +1237,13 @@ export class OfflineManager {
     }
 
     private recordSnapshot(slug: string, params: FindParams | undefined, result: FindResult<AnyRow>): QuerySnapshot {
-        const meta = result.meta ?? { total: result.data?.length ?? 0, limit: 20, offset: 0, hasMore: false };
+        const window = resolvePagination(params);
+        const meta = result.meta ?? { total: result.data?.length ?? 0, ...window, hasMore: false };
         const snapshot: QuerySnapshot = {
             ids: (result.data ?? []).map((row) => row.id as string | number).filter((id) => id !== undefined),
             total: meta.total ?? result.data?.length ?? 0,
-            limit: meta.limit ?? params?.limit ?? 20,
-            offset: meta.offset ?? params?.offset ?? 0,
+            limit: meta.limit ?? window.limit,
+            offset: meta.offset ?? window.offset,
             hasMore: meta.hasMore ?? false
         };
         const state = this.collectionState(slug);
@@ -1466,13 +1554,39 @@ export class OfflineManager {
             await this.adoptServerRow(op, op.id, row);
         } else if (op.type === "createMany") {
             const queued = (op.data as AnyRow[]) ?? [];
-            const rows = await inner.createMany(queued, op.upsert ? { upsert: true } : undefined);
+            // The mutation id names this batch, exactly as it names a single
+            // `create` above — and it matters more here. Without it, a batch
+            // whose ACK went missing replays as a second genuine import and
+            // duplicates every row it holds, not one. `upsert` masked that for
+            // the callers who set it; nothing covered the ones who did not.
+            const rows = await inner.createMany(queued, {
+                ...(op.upsert ? { upsert: true } : {}),
+                idempotencyKey: op.mutationId
+            });
             for (let i = 0; i < rows.length; i++) {
                 await this.adoptServerRow(op, queued[i]?.id as string | number | undefined, rows[i]);
             }
+        } else if (op.type === "updateMany") {
+            const queued = op.updates ?? [];
+            // Keyed like every other replay: an update re-applied in full is
+            // naturally idempotent, but one interleaved with another writer's is
+            // not, and a lost ACK would otherwise re-apply a stale batch over
+            // newer data.
+            const rows = await inner.updateMany(
+                queued.map(u => ({ id: u.id,
+data: u.data as AnyRow })),
+                { idempotencyKey: op.mutationId }
+            );
+            for (let i = 0; i < rows.length; i++) {
+                await this.ingestReplaced(op, queued[i].id, rows[i]);
+            }
         } else if (op.type === "update") {
             const row = await inner.update(op.id!, op.data as AnyRow);
             await this.ingestReplaced(op, op.id!, row);
+        } else if (op.type === "deleteMany") {
+            const ids = op.ids ?? [];
+            await inner.deleteMany(ids, { idempotencyKey: op.mutationId });
+            for (const id of ids) this.removeLocalRow(op.collection, id, true);
         } else if (op.type === "delete") {
             await inner.delete(op.id!);
             this.removeLocalRow(op.collection, op.id!, true);

package/src/realtime-optout.test.ts

@@ -50,7 +50,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        createRebaseClient({ baseUrl: "http://localhost:3000" });
 
         expect(opened).toHaveLength(0);
     });
@@ -59,7 +59,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
 
         // Asking for the channel is not using it.
         const channel = client.realtime.channel("doc:1");
@@ -73,7 +73,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         expect(opened).toHaveLength(0);
 
         client.collection("posts").listen!(undefined, () => { /* noop */ });
@@ -85,7 +85,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
 
         client.collection("posts").listen!(undefined, () => { /* noop */ });
         client.collection("authors").listen!(undefined, () => { /* noop */ });
@@ -102,7 +102,7 @@ describe("realtime opt-out", () => {
         const warn = jest.spyOn(console, "warn").mockImplementation(() => { /* capture */ });
         const debug = jest.spyOn(console, "debug").mockImplementation(() => { /* capture */ });
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         void client.realtime.channel("doc:1"); // obtained, never used
 
         expect(opened).toHaveLength(0);
@@ -118,7 +118,7 @@ describe("realtime opt-out", () => {
         delete globalThis.WebSocket;
         const warn = jest.spyOn(console, "warn").mockImplementation(() => { /* capture */ });
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         expect(warn).not.toHaveBeenCalled();
 
         void client.realtime.channel("doc:1").join();
@@ -134,7 +134,7 @@ describe("realtime opt-out", () => {
         globalThis.WebSocket = FakeWebSocket;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             realtime: false
         });
 
@@ -148,7 +148,7 @@ describe("realtime opt-out", () => {
         globalThis.WebSocket = FakeWebSocket;
 
         createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             websocketUrl: "ws://localhost:3000",
             realtime: false
         });
@@ -160,7 +160,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened, closed } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         client.collection("posts").listen!(undefined, () => { /* noop */ });
         expect(opened).toHaveLength(1);
 
@@ -176,7 +176,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         client.collection("posts").listen!(undefined, () => { /* noop */ });
         expect(opened).toHaveLength(1);
 
@@ -190,10 +190,10 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const offline = createRebaseClient({ baseUrl: "http://localhost:3000/api", realtime: false });
+        const offline = createRebaseClient({ baseUrl: "http://localhost:3000", realtime: false });
         expect(() => offline.close()).not.toThrow();
 
-        const live = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const live = createRebaseClient({ baseUrl: "http://localhost:3000" });
         live.close();
         expect(() => live.close()).not.toThrow();
     });
@@ -205,7 +205,7 @@ describe("realtime opt-out", () => {
         globalThis.WebSocket = FakeWebSocket;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             realtime: false
         });
 
@@ -244,7 +244,7 @@ isAnonymous: false }
         })) as unknown as typeof globalThis.fetch;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             fetch: fetchMock
         });
 
@@ -265,7 +265,7 @@ isAnonymous: false }
         globalThis.WebSocket = FakeWebSocket;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             realtime: false
         });
 

package/src/realtime-subscription-key.test.ts

@@ -0,0 +1,92 @@
+import { jest } from "@jest/globals";
+import { RebaseWebSocketClient } from "./websocket";
+import { or, cond } from "@rebasepro/common";
+
+/**
+ * Two subscriptions are the same subscription only when they ask for the same
+ * rows. The key that decides this was built from a hand-listed subset of the
+ * props, so any field left off it made two different queries collide — and the
+ * second listener was handed the first one's rows, which is worse than not
+ * subscribing at all.
+ */
+
+function fakeSocket() {
+    const sent: Record<string, unknown>[] = [];
+
+    class FakeWS {
+        static readonly OPEN = 1;
+        readyState = 1;
+        onopen: (() => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        onmessage: ((event: { data: string }) => void) | null = null;
+
+        constructor(public url: string) {
+            setTimeout(() => this.onopen?.(), 0);
+        }
+
+        send(raw: string) {
+            const message = JSON.parse(raw) as Record<string, unknown>;
+            sent.push(message);
+            if (message.type === "AUTHENTICATE") {
+                setTimeout(() => this.onmessage?.({
+                    data: JSON.stringify({ type: "AUTH_SUCCESS", requestId: message.requestId })
+                }), 0);
+            }
+        }
+
+        close() { /* noop */ }
+    }
+
+    return { FakeWS: FakeWS as unknown as typeof WebSocket, sent };
+}
+
+function subscribeFrames(sent: Record<string, unknown>[]) {
+    return sent.filter((m) => m.type === "subscribe_collection");
+}
+
+describe("collection subscription identity", () => {
+    beforeEach(() => jest.useFakeTimers());
+    afterEach(() => jest.useRealTimers());
+
+    async function twoSubscriptions(
+        a: Record<string, unknown>,
+        b: Record<string, unknown>
+    ) {
+        const { FakeWS, sent } = fakeSocket();
+        const client = new RebaseWebSocketClient({
+            websocketUrl: "ws://localhost:1234",
+            WebSocket: FakeWS,
+            getAuthToken: async () => "token"
+        });
+        client.listenCollection({ path: "posts", ...a } as never, () => {});
+        client.listenCollection({ path: "posts", ...b } as never, () => {});
+        await jest.advanceTimersByTimeAsync(50);
+        return subscribeFrames(sent);
+    }
+
+    it("treats different offsets as different subscriptions", async () => {
+        // Page one and page two of the same live list. Sharing a subscription
+        // here shows page one's rows on page two.
+        const frames = await twoSubscriptions({ limit: 10, offset: 0 }, { limit: 10, offset: 10 });
+        expect(frames).toHaveLength(2);
+    });
+
+    it("treats different logical groups as different subscriptions", async () => {
+        const frames = await twoSubscriptions(
+            { logical: or(cond("status", "==", "draft")) },
+            { logical: or(cond("status", "==", "published")) }
+        );
+        expect(frames).toHaveLength(2);
+    });
+
+    it("still shares one subscription for genuinely identical queries", async () => {
+        // The de-duplication itself is the point of the key: two components
+        // watching the same list must not open two server subscriptions.
+        const frames = await twoSubscriptions(
+            { limit: 10, offset: 10, logical: or(cond("status", "==", "draft")) },
+            { limit: 10, offset: 10, logical: or(cond("status", "==", "draft")) }
+        );
+        expect(frames).toHaveLength(1);
+    });
+});

package/src/transport-baseurl.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from "@jest/globals";
+import { describe, it, expect, afterEach, jest } from "@jest/globals";
 import { createTransport } from "./transport";
 
 /**
@@ -51,3 +51,51 @@ describe("transport baseUrl resolution", () => {
         expect(createTransport({}).baseUrl).toBe("");
     });
 });
+
+describe("baseUrl that already contains the apiPath", () => {
+    /**
+     * The docblock on `baseUrl` says this "silently builds `/api/api/…` and
+     * every request 404s" — a failure mode understood well enough to be written
+     * down, and still left to be discovered at runtime. This package's own
+     * tests configured it that way a dozen times over, which is about as clear
+     * a signal as a trap gets.
+     */
+    it("warns rather than silently building /api/api", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({ baseUrl: "http://localhost:3000/api" });
+
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("/api/api"));
+        warn.mockRestore();
+    });
+
+    it("warns for a custom apiPath too, and tolerates a trailing slash", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({ baseUrl: "https://api.example.com/v2/", apiPath: "/v2" });
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        warn.mockRestore();
+    });
+
+    it("says nothing about a baseUrl that merely ends in a similar word", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({ baseUrl: "https://rapid.example.com" });
+        createTransport({ baseUrl: "https://example.com/myapi" });
+        createTransport({ baseUrl: "https://example.com" });
+
+        expect(warn).not.toHaveBeenCalled();
+        warn.mockRestore();
+    });
+});
+
+describe("storageUrlOrigin that already contains the apiPath", () => {
+    it("warns, because storage composes it the same way baseUrl is composed", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({
+            baseUrl: "https://example.com",
+            storageUrlOrigin: "https://files.example.com/api"
+        });
+
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("storageUrlOrigin"));
+        warn.mockRestore();
+    });
+});

package/src/transport.ts

@@ -259,6 +259,28 @@ function resolveBaseUrl(configured?: string): string {
 export function createTransport(config: RebaseClientConfig, environment?: TransportEnvironment): Transport {
     const fetchFn = config.fetch || globalThis.fetch;
     const apiPath = config.apiPath || "/api";
+
+    // `apiPath` is appended to `baseUrl`, so a `baseUrl` that already ends in it
+    // builds `/api/api/…` and every request 404s. That was documented on
+    // `baseUrl` and left to be discovered at runtime — including by this
+    // package's own tests, which configured it that way a dozen times. A 404 on
+    // every call looks like a server that is down, not like a doubled path.
+    // `storageUrlOrigin` is checked alongside it because `storage.ts` composes
+    // it the same way — `${storageUrlOrigin ?? baseUrl}${apiPath}` — and its own
+    // docblock carries the same "no path" caveat.
+    for (const field of ["baseUrl", "storageUrlOrigin"] as const) {
+        const value = config[field];
+        if (!value || !apiPath) continue;
+        const trimmed = value.replace(/\/+$/, "");
+        if (!trimmed.endsWith(apiPath)) continue;
+        console.warn(
+            `[Rebase] ${field} ${JSON.stringify(value)} already ends with the API path ` +
+            `${JSON.stringify(apiPath)}, which is appended to it — requests will go to ` +
+            `${trimmed}${apiPath}/… and 404. Pass the origin only ` +
+            `(${JSON.stringify(trimmed.slice(0, trimmed.length - apiPath.length) || "/")}), or set ` +
+            "`apiPath` if the server really does mount the API one level deeper."
+        );
+    }
     let token = config.token;
     let tokenGetter: (() => Promise<string | null>) | undefined;
     let onUnauthorizedHandler = config.onUnauthorized;