@rebasepro/client 0.13.0 → 0.13.1-canary.g06dbe5b

package/src/query-contract.types.ts

@@ -0,0 +1,206 @@
+/**
+ * Compile-time assertions about the query surface.
+ *
+ * ## Read this before adding a `.test.ts` for a type
+ *
+ * These assertions are **not** in a test file, on purpose. In this repo a jest
+ * test cannot check a type at all:
+ *
+ * - `ts-jest` is configured transpile-only. Verified: a test containing
+ *   `const n: number = "nope"` passes. `@ts-expect-error` in a `.test.ts` is
+ *   therefore inert — it asserts nothing and never fails.
+ * - `tsconfig.typecheck.json` — the gate CI runs as `pnpm run typecheck` —
+ *   covers every package's `src` directory but **excludes every `*.test.ts`**.
+ *
+ * So a type assertion written as a test is checked by nothing, twice over. This
+ * file is a plain module under `src`, which is exactly what the gate does read.
+ * It is imported by nothing and emits no runtime code.
+ *
+ * ## What went wrong that this exists to prevent
+ *
+ * `_score` was accepted by the runtime, documented in the SDK docs and skills,
+ * and rejected by `orderBy`'s type, which was `keyof M`. On a project with a
+ * generated SDK — where `M` is a concrete row type — the documented call was a
+ * compile error. Nothing in this repo noticed; a downstream application did.
+ */
+import type { FindParams, FindResult, SDKQueryBuilderInterface, WhereFilterOp } from "@rebasepro/types";
+
+/**
+ * A row shaped the way a **generated** SDK shapes one: a type alias with a
+ * finite key set.
+ *
+ * This detail is the whole test. An `interface … extends Record<string,
+ * unknown>` also satisfies the constraint, but its index signature makes
+ * `keyof M` collapse to `string` — so every assertion below would pass no
+ * matter what `orderBy` accepted, typos included. That is how the first draft
+ * of this file was written, and every `@ts-expect-error` in it reported
+ * "unused directive": the fixture proved nothing.
+ *
+ * A generated row type has no index signature, which is exactly why a real
+ * project caught what this repo did not.
+ */
+type ContractRow = {
+    id: string;
+    title: string;
+    created_at: string;
+    /** An `array` property, which codegen emits as `Array<X>`. */
+    tags: string[];
+    age: number;
+    deleted_at: string | null;
+};
+
+/** A to-many relation, which codegen emits as `Array<TargetRow>`. */
+type TagRow = { id: string; label: string };
+type PostRow = { id: string; title: string; tags: TagRow[] };
+
+// ── orderBy accepts relevance, and still rejects nonsense ───────────────────
+
+/** The documented relevance sort must compile. */
+export const orderByScore: FindParams<ContractRow> = {
+    searchString: "auditor",
+    orderBy: ["_score", "desc"]
+};
+
+/** An ordinary column must keep compiling. */
+export const orderByColumn: FindParams<ContractRow> = { orderBy: ["created_at", "desc"] };
+
+/**
+ * A column that does not exist must still be refused. Widening `orderBy` to
+ * `string` would have fixed the `_score` error and silently given up this,
+ * turning every typo into an unsorted 200 in production.
+ */
+// @ts-expect-error - "nope" is neither a column of ContractRow nor computed
+export const orderByTypo: FindParams<ContractRow> = { orderBy: ["nope", "desc"] };
+
+// ── the fluent builder agrees with FindParams ──────────────────────────────
+
+export const fluentScore = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.search("auditor").orderBy("_score", "desc");
+
+export const fluentColumn = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.orderBy("created_at", "asc");
+
+export const fluentTypo = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - the fluent signature must reject what FindParams rejects
+    qb.orderBy("_scoer", "desc");
+
+/** Vector search must be reachable from the builder, and chain. */
+export const fluentVector = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.vectorSearch("embedding", [0.1, 0.2], { threshold: 0.3 }).limit(10);
+
+// ── the operator decides what the value is ─────────────────────────────────
+
+/**
+ * `array-contains` takes an **element** of the column, not the column.
+ *
+ * This was the second `_score`: documented in `docs/sdk/querying.md`, accepted
+ * by the runtime, and a compile error on a generated SDK — because
+ * `WhereValue<T> = T | T[] | null` was one value type for all sixteen
+ * operators, so on `tags: string[]` it wanted a `string[]`. The spelling that
+ * did compile, `["featured"]`, builds `@> ARRAY[$1]` with the whole array bound
+ * as the single element and matches nothing, forever, with no error anywhere.
+ */
+export const fluentArrayContains = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("tags", "array-contains", "featured");
+
+export const fluentArrayContainsWrapped = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - the column is not one of its own elements
+    qb.where("tags", "array-contains", ["featured"]);
+
+/**
+ * Same defect, and the case the relation compiler was specifically built for:
+ * a to-many relation is emitted as `Array<TargetRow>`, and the compiler answers
+ * `array-contains` on it by comparing **ids**. So the id must be accepted even
+ * though it is not the element type.
+ */
+export const fluentRelationContains = (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) =>
+    qb.where("tags", "array-contains", tagId);
+
+export const fluentRelationIn = (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) =>
+    qb.where("tags", "in", tagIds);
+
+export const fluentRelationTypo = (qb: SDKQueryBuilderInterface<PostRow>) =>
+    // @ts-expect-error - neither a `TagRow` nor a `TagRow["id"]`
+    qb.where("tags", "array-contains", 42);
+
+/** The list operators take a list of elements — or one, read as a one-element list. */
+export const fluentInList = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("tags", "in", ["featured", "new"]);
+
+export const fluentInScalar = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("title", "in", "hello");
+
+export const fluentInNested = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - a list of lists is not a list of elements
+    qb.where("tags", "in", [["featured"]]);
+
+/** A comparison takes one value. `eq(column, ["a","b"])` is not a query anyone meant. */
+export const fluentEqArray = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    // @ts-expect-error - `==` compares against a value, not a list
+    qb.where("title", "==", ["a", "b"]);
+
+/**
+ * A pattern is a string on every column type. The driver casts, so refusing
+ * `"%3%"` on a numeric column was the type being stricter than the runtime.
+ */
+export const fluentLikeOnNumber = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("age", "like", "%3%");
+
+/** The null operators ignore their value; `null` is the conventional spelling. */
+export const fluentIsNull = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("deleted_at", "is-null", null);
+
+/**
+ * A caller holding an unnarrowed operator — a dynamic filter UI — must keep
+ * compiling. `WhereValueFor` distributes over the operator, so this is the
+ * union of every branch rather than a `never`.
+ */
+export const fluentDynamicOp = (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) =>
+    qb.where("title", op, "anything");
+
+/** Two conditions on one column: the shape the Mongo compiler used to drop. */
+export const fluentRange = (qb: SDKQueryBuilderInterface<ContractRow>) =>
+    qb.where("age", ">=", 18).where("age", "<", 65);
+
+/** The object form must accept exactly what the fluent form accepts. */
+export const paramsArrayContains: FindParams<ContractRow> = {
+    where: { tags: ["array-contains", "featured"] }
+};
+
+/** …and the array-of-tuples form the builder produces from two `.where()` calls. */
+export const paramsRange: FindParams<ContractRow> = {
+    where: { age: [[">=", 18], ["<", 65]] }
+};
+
+// ── what a query computes is readable off the row ──────────────────────────
+
+/**
+ * Sorting by relevance and then being unable to read it was the other half of
+ * the same bug — the e2e cast around it, which should have been the tell.
+ */
+export const readComputed = (result: FindResult<ContractRow>) => {
+    const row = result.data[0];
+    const score: number | undefined = row._score;
+    const distance: number | undefined = row._distance;
+    const title: string = row.title;
+    return { score, distance, title };
+};
+
+/** Widening the row must not have turned it into `any`. */
+export const readUnknown = (result: FindResult<ContractRow>) =>
+    // @ts-expect-error - `nope` is neither a column nor computed
+    result.data[0].nope;
+
+/**
+ * A result row must stay assignable to `Record<string, unknown>`.
+ *
+ * Widening the row to `M & QueryComputedFields` broke this in seven places in
+ * one downstream app, because `QueryComputedFields` was first written as an
+ * `interface`: TypeScript grants an implicit index signature to a type alias
+ * and withholds it from an interface, so the intersection stopped overlapping
+ * with `Record<string, unknown>` and every `as Record<string, unknown>` cast
+ * became an error. Nothing in this repo casts a row that way, which is why
+ * nothing here noticed.
+ */
+export const rowStaysIndexable = (result: FindResult<ContractRow>) =>
+    result.data.map(row => row as Record<string, unknown>);

package/src/realtime-error-surfacing.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals";
+
+/**
+ * Server errors about channel frames used to be discarded by the client.
+ *
+ * Channel messages are fire-and-forget by design: the SDK deliberately
+ * registers no `pendingRequests` waiter for them, because their answers come
+ * back addressed by channel rather than in a response envelope. The consequence
+ * was that an `ERROR` frame — `RATE_LIMITED`, `CHANNEL_FORBIDDEN`,
+ * `CHANNEL_HISTORY_WRITE_FAILED` — matched no waiter, no channel and no
+ * subscription, fell through every branch of `handleWebSocketMessage`, and was
+ * dropped. `await channel.broadcast(...)` resolved as if it had been sent.
+ */
+function fakeSocket() {
+    const sockets: FakeWS[] = [];
+
+    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) {
+            sockets.push(this);
+            setTimeout(() => this.onopen?.(), 0);
+        }
+
+        send() { /* nothing here needs the outgoing frames */ }
+        close() { /* noop */ }
+    }
+
+    const instance = () => sockets[sockets.length - 1];
+
+    return {
+        FakeWS: FakeWS as unknown as typeof WebSocket,
+        deliver: (frame: unknown) => instance()?.onmessage?.({ data: JSON.stringify(frame) })
+    };
+}
+
+describe("unmatched realtime error frames", () => {
+    let warn: any;
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+        warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        warn.mockRestore();
+        jest.useRealTimers();
+    });
+
+    const connect = async () => {
+        const { RebaseWebSocketClient } = await import("./websocket");
+        const { FakeWS, deliver } = fakeSocket();
+        const client = new RebaseWebSocketClient({
+            websocketUrl: "ws://localhost:3000",
+            WebSocket: FakeWS
+        });
+        client.ensureConnected();
+        await jest.advanceTimersByTimeAsync(1);
+        return { client, deliver };
+    };
+
+    it("surfaces a channel rate-limit refusal that matches no waiter", async () => {
+        const { deliver } = await connect();
+
+        deliver({
+            type: "ERROR",
+            requestId: "req-the-client-never-registered",
+            payload: { error: { message: "Too many channel messages. Please slow down.", code: "RATE_LIMITED" } }
+        });
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(String(warn.mock.calls[0][0])).toContain("RATE_LIMITED");
+        expect(String(warn.mock.calls[0][0])).toContain("Too many channel messages");
+    });
+
+    it("surfaces a refused channel action", async () => {
+        const { deliver } = await connect();
+
+        // What the server now sends for a broadcast into a channel the sender
+        // never joined — `sendError` addresses it by neither requestId nor
+        // channel, so nothing else in the client will ever see it.
+        deliver({
+            type: "error",
+            payload: { error: { message: "Refused broadcast on channel \"doc:42\"", code: "CHANNEL_FORBIDDEN" } },
+            error: "Refused broadcast on channel \"doc:42\""
+        });
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(String(warn.mock.calls[0][0])).toContain("CHANNEL_FORBIDDEN");
+    });
+
+    it("stays quiet for frames that are not errors", async () => {
+        const { deliver } = await connect();
+
+        deliver({ type: "broadcast", channel: "doc:42", event: "op", payload: { n: 1 } });
+        deliver({ type: "presence_state", channel: "doc:42", presences: {} });
+
+        expect(warn).not.toHaveBeenCalled();
+    });
+});

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

@@ -5,7 +5,8 @@ import {
     SDKCollectionClient,
     SDKQueryBuilderInterface,
     WhereFilterOp,
-    WhereValue
+    WhereValueFor,
+    type ComputedSortField
 } from "@rebasepro/types";
 
 /**
@@ -36,7 +37,7 @@ export class SDKQueryBuilder<M extends Record<string, unknown> = Record<string,
      * @example
      * client.data.users.where('age', '>=', 18).find()
      */
-    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where<K extends keyof M & string, Op extends WhereFilterOp>(column: K, operator: Op, value: WhereValueFor<Op, M[K]>): this;
     where(logicalCondition: LogicalCondition): this;
     where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown): this {
         if (typeof columnOrCondition === "object" && columnOrCondition !== null && "type" in columnOrCondition) {
@@ -72,7 +73,7 @@ export class SDKQueryBuilder<M extends Record<string, unknown> = Record<string,
     /**
      * Order the results by a specific column.
      */
-    orderBy(column: keyof M & string, direction: "asc" | "desc" = "asc"): this {
+    orderBy(column: (keyof M & string) | ComputedSortField, direction: "asc" | "desc" = "asc"): this {
         this.params.orderBy = [column, direction];
         return this;
     }
@@ -95,9 +96,60 @@ export class SDKQueryBuilder<M extends Record<string, unknown> = Record<string,
 
     /**
      * Set a free-text search string if supported by the backend.
+     *
+     * By default this is a substring match across the collection's top-level
+     * string properties. A Postgres collection that declares a `search` block
+     * gets ranked full-text matching over the fields it named instead, and each
+     * row comes back with a `_score` you can sort on:
+     *
+     * ```ts
+     * client.data.talents.search("auditor iso 14001").orderBy("_score", "desc").find()
+     * ```
+     *
+     * Pass `{ explain: true }` to have each row report which of the declared
+     * fields matched, with a highlighted snippet, on `_matches`:
+     *
+     * ```ts
+     * const { data } = await client.data.talents.search("iso 14001", { explain: true }).find();
+     * data[0]._matches
+     * // [{ field: "questionnaire.certifications", snippet: "<mark>ISO</mark> <mark>14001</mark> Lead Auditor" }]
+     * ```
      */
-    search(searchString: string): this {
+    search(searchString: string, options?: { explain?: boolean }): this {
         this.params.searchString = searchString;
+        if (options?.explain !== undefined) this.params.searchExplain = options.explain;
+        return this;
+    }
+
+    /**
+     * Order rows by nearest-neighbour distance to `vector`.
+     *
+     * The server has supported this from the REST layer since vectors landed;
+     * this is the SDK reaching it. Results come back closest-first with a
+     * `_distance` on each row, and any `where` / `orderBy` on the same query is
+     * a filter applied before the ordering — distance decides the order.
+     *
+     * You supply the query vector. Rebase stores and searches embeddings; it
+     * does not produce them, so this is where whatever model you already use
+     * for the stored vectors gets called.
+     *
+     * @param property - Name of the `vector` property to compare against.
+     * @param vector - The query embedding. Its length must match the property's
+     *                 declared `dimensions`, or the server answers 400.
+     * @example
+     * client.data.docs.vectorSearch("embedding", queryVector, { threshold: 0.35 }).limit(10).find()
+     */
+    vectorSearch(
+        property: string,
+        vector: number[],
+        options?: { distance?: "cosine" | "l2" | "inner_product"; threshold?: number }
+    ): this {
+        this.params.vectorSearch = {
+            property,
+            vector,
+            ...(options?.distance !== undefined && { distance: options.distance }),
+            ...(options?.threshold !== undefined && { threshold: options.threshold })
+        };
         return this;
     }
 

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();
+    });
+});