@rebasepro/client 0.11.1-canary.gfd39654 → 0.12.0

package/dist/realtime-channel.d.ts

@@ -49,14 +49,14 @@ export interface BroadcastEvent {
      */
     replayed?: boolean;
 }
-/** One retained message, as returned by {@link RebaseRealtimeChannel.history}. */
-export interface ChannelHistoryEntry {
-    seq: number;
-    event: string;
-    payload: unknown;
-    senderId?: string;
-    at?: string;
-}
+/**
+ * One retained message, as returned by {@link RebaseRealtimeChannel.history}.
+ *
+ * Re-exported rather than re-declared: the copy that used to live here had
+ * drifted `at` to optional, while the server always sends it.
+ */
+export type { ChannelHistoryEntry } from "@rebasepro/types";
+import type { ChannelHistoryEntry } from "@rebasepro/types";
 /** The answer to a catch-up request. */
 export interface ChannelHistoryResult {
     messages: ChannelHistoryEntry[];

package/dist/transport.d.ts

@@ -56,7 +56,41 @@ export interface RebaseClientConfig {
      * `client.close()` when shutting down.
      */
     realtime?: boolean;
+    /**
+     * "Yes, I meant to be anonymous."
+     *
+     * Off-browser, a client with no credential can only ever call as an
+     * anonymous user, and row-level security answers it with whatever is
+     * public — usually nothing. That is almost always a mistake in a script or
+     * cron job, so the SDK warns once on the first request (see
+     * {@link ANONYMOUS_SERVER_CLIENT_WARNING}). Anonymous is a legitimate
+     * choice for public reads, though; set this to `true` to say so and
+     * silence the warning.
+     *
+     * Has no effect in the browser, where anonymous-before-sign-in is normal
+     * and nothing is ever warned about.
+     */
+    anonymous?: boolean;
 }
+/**
+ * Facts about the surrounding client that the transport cannot read off its own
+ * config, but needs in order to decide whether a request is *meaningfully*
+ * credential-less.
+ */
+export interface TransportEnvironment {
+    /**
+     * The credential reaches the server without an `Authorization` header —
+     * i.e. `auth.authFlowMode: "cookie"`, where the refresh token lives in an
+     * httpOnly cookie. Such a client looks tokenless to the transport but is
+     * not anonymous, so it must never trip the guard.
+     */
+    credentialOutOfBand?: boolean;
+}
+/**
+ * Emitted once per client. Kept as a constant so the wording is testable and
+ * greppable — this is the string a user will paste into a search.
+ */
+export declare const ANONYMOUS_SERVER_CLIENT_WARNING: string;
 /**
  * Re-export from `@rebasepro/types` for backward compatibility.
  *
@@ -81,4 +115,4 @@ export interface Transport {
     getHeaders: (init?: RequestInit) => Record<string, string>;
     resolveToken: () => Promise<string | null>;
 }
-export declare function createTransport(config: RebaseClientConfig): Transport;
+export declare function createTransport(config: RebaseClientConfig, environment?: TransportEnvironment): Transport;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.11.1-canary.gfd39654",
+  "version": "0.12.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.11.1-canary.gfd39654",
-    "@rebasepro/types": "0.11.1-canary.gfd39654",
-    "@rebasepro/utils": "0.11.1-canary.gfd39654"
+    "@rebasepro/common": "0.12.0",
+    "@rebasepro/types": "0.12.0",
+    "@rebasepro/utils": "0.12.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/anonymous-client-guard.test.ts

@@ -0,0 +1,190 @@
+import { afterEach, beforeEach, describe, expect, it, jest } from "@jest/globals";
+import { ANONYMOUS_SERVER_CLIENT_WARNING, createTransport } from "./transport";
+import { createRebaseClient } from "./index";
+
+/**
+ * A client built off-browser with no credential is silently anonymous: RLS
+ * answers it with whatever is public, which is usually nothing. A `scrape-jobs`
+ * script hit this twice. These pin the *narrowness* of the guard as much as the
+ * guard itself — a warning that fires on legitimate anonymous clients (browser
+ * before sign-in, public reads) is noise that teaches people to ignore warnings.
+ */
+
+type MockFetch = jest.Mock<(input: RequestInfo | URL, init?: RequestInit) => Promise<Partial<Response>>>;
+
+const okFetch = (): MockFetch => {
+    const fetchMock = jest.fn() as MockFetch;
+    fetchMock.mockResolvedValue({
+        ok: true,
+        status: 200,
+        text: async () => JSON.stringify({ data: [] })
+    });
+    return fetchMock;
+};
+
+const setWindow = (defined: boolean) => {
+    if (!defined) { delete (globalThis as never as { window?: unknown }).window; return; }
+    (globalThis as never as { window: unknown }).window = { location: { origin: "https://app.example.com", href: "https://app.example.com/" } };
+};
+
+const setDocument = (defined: boolean) => {
+    if (!defined) { delete (globalThis as never as { document?: unknown }).document; return; }
+    (globalThis as never as { document: unknown }).document = { cookie: "" };
+};
+
+let warn: jest.SpiedFunction<typeof console.warn>;
+
+beforeEach(() => {
+    warn = jest.spyOn(console, "warn").mockImplementation(() => undefined);
+});
+
+afterEach(() => {
+    warn.mockRestore();
+    setWindow(false);
+    setDocument(false);
+});
+
+const anonymousWarnings = () => warn.mock.calls.filter(([first]) => first === ANONYMOUS_SERVER_CLIENT_WARNING);
+
+describe("anonymous server client guard", () => {
+    it("warns when a Node-side client has no credential at all", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(1);
+        expect(anonymousWarnings()[0][0]).toContain("anonymous: true");
+    });
+
+    it("warns once per client, not once per request", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+
+        await transport.request("/data/jobs");
+        await transport.request("/data/jobs");
+        await transport.request("/data/other");
+
+        expect(anonymousWarnings()).toHaveLength(1);
+    });
+
+    it("warns per client, so a second offending client is still reported", async () => {
+        const a = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+        const b = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+
+        await a.request("/data/jobs");
+        await b.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(2);
+    });
+
+    it("stays silent in a browser, where anonymous-before-sign-in is normal", async () => {
+        setWindow(true);
+        const transport = createTransport({ fetch: okFetch() as typeof globalThis.fetch });
+
+        await transport.request("/data/posts");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent when only `document` is defined, so an SSR/test shim is not mistaken for Node", async () => {
+        setDocument(true);
+        const transport = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+
+        await transport.request("/data/posts");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent when a token was passed", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", token: "service-key", fetch: okFetch() as typeof globalThis.fetch });
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent when the token arrives after construction (the reason this is checked at first request)", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+        transport.setToken("service-key");
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent when an auth token getter is installed", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+        transport.setAuthTokenGetter(async () => "fetched-token");
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent for a token getter that has nothing yet — the credential path exists", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch });
+        transport.setAuthTokenGetter(async () => null);
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent for the cookie auth flow, where the credential is not a header", async () => {
+        const transport = createTransport(
+            { baseUrl: "http://localhost:3001", fetch: okFetch() as typeof globalThis.fetch },
+            { credentialOutOfBand: true }
+        );
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent when the caller opted in with `anonymous: true`", async () => {
+        const transport = createTransport({ baseUrl: "http://localhost:3001", anonymous: true, fetch: okFetch() as typeof globalThis.fetch });
+
+        await transport.request("/data/jobs");
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+});
+
+describe("anonymous server client guard, through createRebaseClient", () => {
+    it("warns for a credential-less client built in a script", async () => {
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3001",
+            realtime: false,
+            fetch: okFetch() as typeof globalThis.fetch
+        });
+
+        await client.collection("jobs").find();
+
+        expect(anonymousWarnings()).toHaveLength(1);
+    });
+
+    it("stays silent when `auth.authFlowMode` is cookie", async () => {
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3001",
+            realtime: false,
+            fetch: okFetch() as typeof globalThis.fetch,
+            auth: { authFlowMode: "cookie", persistSession: false }
+        });
+
+        await client.collection("jobs").find();
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+
+    it("stays silent when the caller opted in with `anonymous: true`", async () => {
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3001",
+            realtime: false,
+            anonymous: true,
+            fetch: okFetch() as typeof globalThis.fetch
+        });
+
+        await client.collection("jobs").find();
+
+        expect(anonymousWarnings()).toHaveLength(0);
+    });
+});

package/src/api-keys.ts

@@ -1,50 +1,27 @@
 import type { Transport } from "./transport";
 
-// 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. */
-export interface ApiKeyPermission {
-    collection: string;
-    operations: ("read" | "write" | "delete")[];
-}
-
-/** An API key with the secret portion masked (returned by list / get / update). */
-export interface ApiKeyMasked {
-    id: string;
-    name: string;
-    key_prefix: string;
-    permissions: ApiKeyPermission[];
-    admin: boolean;
-    rate_limit: number | null;
-    created_by: string;
-    created_at: string;
-    updated_at: string;
-    last_used_at: string | null;
-    expires_at: string | null;
-    revoked_at: string | null;
-}
-
-/** An API key including the full secret (returned only on creation). */
-export interface ApiKeyWithSecret extends ApiKeyMasked {
-    key: string;
-}
-
-/** Payload for creating a new API key. */
-export interface CreateApiKeyRequest {
-    name: string;
-    permissions: ApiKeyPermission[];
-    rate_limit?: number | null;
-    expires_at?: string | null;
-}
+/**
+ * These were re-declared here, under a comment saying they lived in the server
+ * package rather than in `@rebasepro/types`. That stopped being true, and the
+ * copy drifted: it never gained `admin`, the flag that grants a key the `admin`
+ * role — admin routes plus the RLS `default_admin` policies — so the SDK could
+ * describe every kind of key except a privileged one, and
+ * `createKey({ …, admin: true })` was an excess-property error.
+ */
+export type {
+    ApiKeyPermission,
+    ApiKeyMasked,
+    ApiKeyWithSecret,
+    CreateApiKeyRequest,
+    UpdateApiKeyRequest
+} from "@rebasepro/types";
 
-/** Payload for updating an existing API key. */
-export interface UpdateApiKeyRequest {
-    name?: string;
-    permissions?: ApiKeyPermission[];
-    rate_limit?: number | null;
-    expires_at?: string | null;
-}
+import type {
+    ApiKeyMasked,
+    ApiKeyWithSecret,
+    CreateApiKeyRequest,
+    UpdateApiKeyRequest
+} from "@rebasepro/types";
 
 /** Options for the `createApiKeys` factory. */
 export interface CreateApiKeysOptions {

package/src/collection.test.ts

@@ -144,7 +144,7 @@ hasMore: false }
             // Flat row access — no .values wrapper
             expect(result.data[0].id).toBe("1");
             expect((result.data[0] as Record<string, unknown>).name).toBe("Product A");
-            // No path field — that's CMS leakage
+            // No path field — that's admin leakage
             expect((result.data[0] as Record<string, unknown>).path).toBeUndefined();
             expect(result.meta.total).toBe(1);
         });

package/src/collection.ts

@@ -1,7 +1,9 @@
 import { buildQueryString, FindParams, RebaseApiError, Transport } from "./transport";
 import { RebaseWebSocketClient } from "./websocket";
 import {
+    FindAllParams,
     FindResult,
+    IterateParams,
     LogicalCondition,
     SDKCollectionClient,
     SDKQueryBuilderInterface,
@@ -9,6 +11,7 @@ import {
     WhereValue,
     WriteOptions
 } from "@rebasepro/types";
+import { collectAllPages, paginateFind } from "@rebasepro/common";
 
 import { SDKQueryBuilder } from "./sdk_query_builder";
 
@@ -113,6 +116,17 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             };
         },
 
+        // The pagination engine lives in `@rebasepro/common`, shared with the
+        // in-process accessor: `iterate()` has to mean the same thing whichever
+        // transport the caller happens to be holding.
+        iterate(params?: IterateParams<M>) {
+            return paginateFind<M>((p) => client.find(p), params, slug);
+        },
+
+        findAll(params?: FindAllParams<M>) {
+            return collectAllPages<M>((p) => client.find(p), params, slug);
+        },
+
         async findById(id: string | number) {
             try {
                 const raw = await transport.request<Record<string, unknown>>(`${basePath}/${encodeURIComponent(String(id))}`, { method: "GET" });

package/src/functions.ts

@@ -33,14 +33,8 @@ export interface FunctionsClient {
     ): Promise<T>;
 }
 
-export interface FunctionInvokeOptions {
-    /** HTTP method — defaults to `"POST"`. */
-    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-    /** Sub-path appended after the function name, e.g. `"status/123"`. */
-    path?: string;
-    /** Extra headers merged into the request (auth is still injected automatically). */
-    headers?: Record<string, string>;
-}
+export type { FunctionInvokeOptions } from "@rebasepro/types";
+import type { FunctionInvokeOptions } from "@rebasepro/types";
 
 /**
  * Create a `FunctionsClient` backed by the given transport.

package/src/index.ts

@@ -48,6 +48,12 @@ export type { RebaseClientConfig, FindParams, FindResponse } from "./transport";
 export type { CollectionClient } from "./collection";
 export type { FindResult, SDKCollectionClient, SDKQueryBuilderInterface, PaginationMeta } from "@rebasepro/types";
 
+// Pagination: `iterate()` / `findAll()` parameter types and the error a walk
+// throws instead of quietly returning a truncated answer.
+export type { IterateParams, FindAllParams, PageWalkOptions, CursorSpec } from "@rebasepro/types";
+export { RebasePaginationError } from "@rebasepro/common";
+export type { PaginationErrorCode } from "@rebasepro/common";
+
 // Logical-condition helpers for `.where(or(...), and(...))`.
 export { QueryBuilder, or, and, cond } from "@rebasepro/common";
 
@@ -257,7 +263,10 @@ function deriveWebSocketUrl(baseUrl?: string): string {
 }
 
 export function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): CreateRebaseClientResult<DB> {
-    const transport = createTransport(options);
+    // `credentialOutOfBand`: in cookie auth mode the credential is an httpOnly
+    // cookie, so a tokenless transport is not an anonymous client and must not
+    // trip the server-side anonymous guard (see `RebaseClientConfig.anonymous`).
+    const transport = createTransport(options, { credentialOutOfBand: options.auth?.authFlowMode === "cookie" });
     const auth = createAuth(transport, options.auth);
     const admin = createAdmin(transport, options.admin);
     const cron = createCron(transport, options.cron);

package/src/offline-idb-store.test.ts

@@ -155,7 +155,40 @@ describe("row codec round-trip", () => {
     });
 });
 
+/**
+ * Empty the shared queue between the manager tests.
+ *
+ * `IDB_NAME` is a hardcoded `"rebase-offline"`, so every
+ * `new IndexedDBOfflineStore()` in this file opens the *same* database. The
+ * `IndexedDBOfflineStore` block above shares it deliberately — each of its
+ * tests uses its own key prefix, and one of them exists to prove that
+ * isolation holds. The two `OfflineManager` blocks below do not: a manager
+ * queues under no prefix, so without this they inherit each other's pending
+ * writes.
+ *
+ * CI failed both manager tests on 2026-07-28 with exactly the symptoms this
+ * coupling would produce — "replays them from a fresh one" asserted
+ * `flushed: 1` and got `2`, and the cross-tab read came back empty. It has not
+ * been reproduced locally (14 runs, including randomized order), so treat this
+ * as removing a real coupling rather than as a confirmed diagnosis: if CI fails
+ * here again, the shared queue is no longer the explanation and the next place
+ * to look is timing inside the manager itself.
+ */
+async function clearOfflineQueue(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+        const request = indexedDB.deleteDatabase("rebase-offline");
+        request.onsuccess = () => resolve();
+        request.onerror = () => reject(request.error);
+        // A still-open connection blocks the delete; the manager tests each
+        // build their own stores, so resolving here keeps a stray one from
+        // hanging the suite rather than failing it.
+        request.onblocked = () => resolve();
+    });
+}
+
 describe("two tabs over one database", () => {
+    beforeEach(clearOfflineQueue);
+
     /** BroadcastChannel delivery is asynchronous; give it a macrotask or two. */
     const settle = async () => {
         for (let i = 0; i < 3; i++) await new Promise((resolve) => setTimeout(resolve, 0));
@@ -240,6 +273,8 @@ describe("two tabs over one database", () => {
 });
 
 describe("OfflineManager over IndexedDB", () => {
+    beforeEach(clearOfflineQueue);
+
     it("queues offline writes in one manager and replays them from a fresh one", async () => {
         const table = new Map<string, Record<string, unknown>>();
         const state = { online: true };

package/src/offline-integration.test.ts

@@ -8,6 +8,11 @@ import { MemoryOfflineStore } from "./offline-store";
  * offline.test.ts covers the manager against fakes, not this plumbing.
  */
 describe("createRebaseClient({ offline })", () => {
+    // Tokenless clients in a Node environment, on purpose — that is what the
+    // anonymous-server-client guard warns about (covered by
+    // src/anonymous-client-guard.test.ts). Here it is only noise.
+    beforeEach(() => { jest.spyOn(console, "warn").mockImplementation(() => undefined); });
+
     function jsonResponse(body: unknown): Response {
         return new Response(JSON.stringify(body), {
             status: 200,

package/src/offline.ts

@@ -1,5 +1,6 @@
 import { buildQueryString, FindParams, RebaseApiError } from "./transport";
-import { FindResult, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue } from "@rebasepro/types";
+import { FindAllParams, FindResult, IterateParams, LogicalCondition, SDKCollectionClient, WhereFilterOp, WhereValue } from "@rebasepro/types";
+import { collectAllPages, paginateFind } from "@rebasepro/common";
 import { CollectionClient, LiveResult, ObserveOptions, RowSnapshotMeta } from "./collection";
 import { SDKQueryBuilder } from "./sdk_query_builder";
 import { dehydrateRow, hydrateRow } from "./offline-codec";
@@ -437,6 +438,13 @@ export class OfflineManager {
                 return { data: answer.data, meta: answer.meta };
             },
 
+            // Paginates the *wrapped* find, so a walk started offline is served
+            // page by page out of the local database exactly as it would be
+            // from the server, and rejoins the network mid-walk if it returns.
+            iterate: (params?: IterateParams<M>) => paginateFind<M>((p) => wrapped.find(p), params, slug),
+
+            findAll: (params?: FindAllParams<M>) => collectAllPages<M>((p) => wrapped.find(p), params, slug),
+
             findById: async (id: string | number) => {
                 await this.ensureCollection(slug);
                 if (this.connectivity.shouldAttempt()) {

package/src/realtime-channel.ts

@@ -53,14 +53,14 @@ export interface BroadcastEvent {
     replayed?: boolean;
 }
 
-/** One retained message, as returned by {@link RebaseRealtimeChannel.history}. */
-export interface ChannelHistoryEntry {
-    seq: number;
-    event: string;
-    payload: unknown;
-    senderId?: string;
-    at?: string;
-}
+/**
+ * One retained message, as returned by {@link RebaseRealtimeChannel.history}.
+ *
+ * Re-exported rather than re-declared: the copy that used to live here had
+ * drifted `at` to optional, while the server always sends it.
+ */
+export type { ChannelHistoryEntry } from "@rebasepro/types";
+import type { ChannelHistoryEntry } from "@rebasepro/types";
 
 /** The answer to a catch-up request. */
 export interface ChannelHistoryResult {

package/src/transport.ts

@@ -63,8 +63,65 @@ export interface RebaseClientConfig {
      * `client.close()` when shutting down.
      */
     realtime?: boolean;
+    /**
+     * "Yes, I meant to be anonymous."
+     *
+     * Off-browser, a client with no credential can only ever call as an
+     * anonymous user, and row-level security answers it with whatever is
+     * public — usually nothing. That is almost always a mistake in a script or
+     * cron job, so the SDK warns once on the first request (see
+     * {@link ANONYMOUS_SERVER_CLIENT_WARNING}). Anonymous is a legitimate
+     * choice for public reads, though; set this to `true` to say so and
+     * silence the warning.
+     *
+     * Has no effect in the browser, where anonymous-before-sign-in is normal
+     * and nothing is ever warned about.
+     */
+    anonymous?: boolean;
+}
+
+/**
+ * Facts about the surrounding client that the transport cannot read off its own
+ * config, but needs in order to decide whether a request is *meaningfully*
+ * credential-less.
+ */
+export interface TransportEnvironment {
+    /**
+     * The credential reaches the server without an `Authorization` header —
+     * i.e. `auth.authFlowMode: "cookie"`, where the refresh token lives in an
+     * httpOnly cookie. Such a client looks tokenless to the transport but is
+     * not anonymous, so it must never trip the guard.
+     */
+    credentialOutOfBand?: boolean;
 }
 
+/**
+ * True when there is no browser to have signed a user in — a Node script, a
+ * cron job, an edge worker.
+ *
+ * Anonymous is an ordinary, correct state in a browser: before sign-in, on a
+ * marketing page, for public reads. Warning there would be noise that teaches
+ * people to ignore warnings, so the guard is off entirely. This uses the same
+ * `typeof window` test as {@link resolveBaseUrl}, and additionally treats a
+ * defined `document` as a browser so an SSR shim or test harness that installs
+ * only one of the two is still excluded.
+ */
+function isServerLikeEnvironment(): boolean {
+    return typeof window === "undefined" && typeof document === "undefined";
+}
+
+/**
+ * Emitted once per client. Kept as a constant so the wording is testable and
+ * greppable — this is the string a user will paste into a search.
+ */
+export const ANONYMOUS_SERVER_CLIENT_WARNING =
+    "[rebase] This client was created outside a browser with no credential — no `token`, no auth token getter, "
+    + "and no cookie auth flow — so every request runs as an anonymous caller. Row-level security will return only "
+    + "publicly readable rows, which is usually nothing and occasionally the wrong thing. "
+    + "Inside a cron or function handler, use the `client` you were handed instead of building a new one: its data "
+    + "plane is already admin-scoped. In a standalone script or job, pass the service key as `token`. "
+    + "If you really do want anonymous access, pass `anonymous: true` to silence this.";
+
 /**
  * Re-export from `@rebasepro/types` for backward compatibility.
  *
@@ -156,12 +213,32 @@ function resolveBaseUrl(configured?: string): string {
     return "";
 }
 
-export function createTransport(config: RebaseClientConfig): Transport {
+export function createTransport(config: RebaseClientConfig, environment?: TransportEnvironment): Transport {
     const fetchFn = config.fetch || globalThis.fetch;
     const apiPath = config.apiPath || "/api";
     let token = config.token;
     let tokenGetter: (() => Promise<string | null>) | undefined;
     let onUnauthorizedHandler = config.onUnauthorized;
+    /** Once per client, never per request — log spam is its own bug. */
+    let anonymousWarningIssued = false;
+
+    /**
+     * Warn a server-side caller that it built a client that can only ever be
+     * anonymous. Deliberately checked at the *first request* rather than at
+     * construction: `setToken()` / `setAuthTokenGetter()` and a server-side
+     * `auth.signIn…()` (which calls `transport.setToken`) all land after the
+     * constructor, and warning at construction would fire on every one of them.
+     */
+    function warnIfAnonymousServerClient(activeToken: string | undefined): void {
+        if (anonymousWarningIssued) return;
+        if (activeToken) return;                          // a credential is being sent
+        if (tokenGetter) return;                          // a credential is being fetched per request
+        if (config.anonymous) return;                     // "yes, I meant this"
+        if (environment?.credentialOutOfBand) return;     // cookie auth flow — credential is not a header
+        if (!isServerLikeEnvironment()) return;           // browsers are legitimately anonymous
+        anonymousWarningIssued = true;
+        console.warn(ANONYMOUS_SERVER_CLIENT_WARNING);
+    }
 
     function getHeaders(activeToken: string | undefined, init?: RequestInit) {
         return {
@@ -186,6 +263,8 @@ export function createTransport(config: RebaseClientConfig): Transport {
             }
         }
 
+        warnIfAnonymousServerClient(activeToken);
+
         const headers = getHeaders(activeToken, init);
 
         // If passing FormData, we MUST let fetch set the boundary, so remove Content-Type