@rebasepro/client 0.13.0 → 0.13.1-canary.g06dbe5b

package/dist/offline-connectivity.d.ts

@@ -12,6 +12,13 @@
  */
 /** The request never reached the server, so nothing was decided by it. */
 export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Is the server still answering an earlier attempt of this same write?
+ *
+ * The only correct response is to ask again — which is exactly what the
+ * server's own message says, and exactly what this SDK used not to do.
+ */
+export declare function isIdempotencyInProgressError(error: unknown): boolean;
 /** Is this failure worth another attempt later? */
 export declare function isRetryableError(error: unknown): boolean;
 /**
@@ -24,6 +31,11 @@ export declare function isRetryableError(error: unknown): boolean;
  * The queue uses this to recognise its own earlier attempt. A create whose
  * response was lost is replayed, and for a row carrying an id the SDK generated
  * the server can only be rejecting it because the first attempt actually landed.
+ *
+ * Which is why the status alone cannot decide it: `IDEMPOTENCY_KEY_IN_PROGRESS`
+ * is a 409 that means the opposite — the row may not exist at all. Read as a
+ * duplicate, the queue looked for a row that was never written, found nothing,
+ * concluded there was nothing left to do and deleted the write from the queue.
  */
 export declare function isDuplicateKeyError(error: unknown): boolean;
 export interface ConnectivityOptions {

package/dist/offline-query.d.ts

@@ -1,7 +1,14 @@
 import { FilterValues, FindResult, LogicalCondition, FilterCondition, OrderByTuple, WhereFilterOp } from "@rebasepro/types";
 import { FindParams } from "./transport";
-/** The server's page size when the caller does not ask for one. */
-export declare const DEFAULT_PAGE_SIZE = 20;
+/**
+ * The server's page size when the caller does not ask for one.
+ *
+ * Re-exported rather than redeclared. This was its own `= 20` — a third
+ * constant of this name in the workspace, next to `@rebasepro/common`'s 200 and
+ * the 50 the REST layer actually applies — and a local copy of a number that
+ * belongs to another process is a number that goes stale silently.
+ */
+export { DEFAULT_LIST_LIMIT as DEFAULT_PAGE_SIZE } from "@rebasepro/types";
 /**
  * Three-way compare with SQL's type coercion but not its collation. Returns
  * `undefined` when the two values are not ordered relative to each other,
@@ -33,7 +40,15 @@ export declare function matchesParams(row: Record<string, unknown>, params?: Fin
  * not shuffle rows between pages.
  */
 export declare function sortRows<M extends Record<string, unknown>>(rows: M[], orderBy?: OrderByTuple): M[];
-/** Resolve `page`/`offset`/`limit` the way the server does. */
+/**
+ * Resolve `page`/`offset`/`limit` the way the server does.
+ *
+ * It did not: this defaulted an absent limit to 20 while `/api/data` pages by
+ * 50, so the same `observe()` answered with 20 rows from the local database and
+ * 50 from the network — a list that changed length depending on which side
+ * answered, with `page` striding differently on each. Delegated now, so the
+ * sentence above is true by construction rather than by agreement.
+ */
 export declare function resolvePagination(params?: FindParams): {
     limit: number;
     offset: number;
@@ -45,7 +60,48 @@ export declare function resolvePagination(params?: FindParams): {
  * `include` pulls in rows from other collections that this evaluator never
  * sees, and `searchString` is only approximated — both make the local answer a
  * best effort rather than an equivalent one.
+ *
+ * **Ordering comparisons are refused, and that is the interesting one.**
+ * `compareValues` falls back to an `Intl.Collator` for operands it cannot read
+ * as numbers or instants. PostgreSQL orders text by the *database's* collation,
+ * which is a property of the server this process has never been told: under the
+ * C collation `'apple' < 'Banana'` is false, under `en_US.UTF-8` it is true,
+ * and the collator says true. So `["<", "Banana"]` selects a different set here
+ * than it does there — silently, and in whichever direction the deployment
+ * happens to have been created.
+ *
+ * The refusal covers *every* ordering comparison rather than only the ones with
+ * a string operand, because the operand type does not settle it: a numeric
+ * bound against a text column (`["<", 10]` on a `varchar`) also reaches the
+ * collator, and nothing in `params` says what the column holds. Conservative on
+ * purpose — the cost is that a query combining an ordering filter with
+ * *unsynced local writes* stops placing those writes optimistically, which is a
+ * degraded answer rather than a wrong one. Claiming exactness we do not have is
+ * the other way round.
+ *
+ * This says nothing about ordering *results*; that is a separate claim with a
+ * separate answer, because a sort changes which rows come first and not which
+ * rows match. See {@link isLocallySortable}.
  */
 export declare function isExactlyEvaluable(params?: FindParams): boolean;
+/**
+ * Would sorting `rows` locally reproduce the order the server would have sent?
+ *
+ * Asked of the rows rather than of the query, because unlike a filter this one
+ * *is* decidable from the data in hand: {@link compareValues} reaches the
+ * collator only when it cannot read both operands as numbers, and `toComparable`
+ * has already turned dates and relations into numbers and ids by then. If every
+ * value on the sort column normalises to a number, the collator is unreachable
+ * and the local order is the server's order.
+ *
+ * A text column is therefore refused — see {@link isExactlyEvaluable} for why
+ * the two cannot be made to agree — and so is a column this page happens to see
+ * only as strings, which is the same thing from here.
+ *
+ * Nulls are fine either way: they are ordered by an explicit rule (last
+ * ascending, first descending) that matches Postgres and never reaches the
+ * comparator.
+ */
+export declare function isLocallySortable(rows: readonly Record<string, unknown>[], orderBy?: OrderByTuple): boolean;
 /** Run a full query — filter, sort, paginate — over a set of rows. */
 export declare function runLocalQuery<M extends Record<string, unknown>>(rows: M[], params?: FindParams): FindResult<M>;

package/dist/offline-store.d.ts

@@ -48,9 +48,16 @@ export interface PendingMutation {
     /** Unique, lexicographically sortable identity — also the queue key suffix. */
     mutationId: string;
     collection: string;
-    type: "create" | "createMany" | "update" | "delete";
+    type: "create" | "createMany" | "update" | "updateMany" | "delete" | "deleteMany";
     /** Target row id for update/delete, and the (client-generated) id of an offline create. */
     id?: string | number;
+    /** Target row ids for `deleteMany`. */
+    ids?: (string | number)[];
+    /** `{ id, data }` entries for `updateMany`. */
+    updates?: {
+        id: string | number;
+        data: Record<string, unknown>;
+    }[];
     /**
      * True when the SDK minted this create's id itself. Only such creates may
      * cancel out against a later offline delete: a freshly generated UUID

package/dist/query-contract.types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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[];
+};
+/** The documented relevance sort must compile. */
+export declare const orderByScore: FindParams<ContractRow>;
+/** An ordinary column must keep compiling. */
+export declare const orderByColumn: FindParams<ContractRow>;
+/**
+ * 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.
+ */
+export declare const orderByTypo: FindParams<ContractRow>;
+export declare const fluentScore: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentColumn: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentTypo: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** Vector search must be reachable from the builder, and chain. */
+export declare const fluentVector: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * `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 declare const fluentArrayContains: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentArrayContainsWrapped: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * 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 declare const fluentRelationContains: (qb: SDKQueryBuilderInterface<PostRow>, tagId: string) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationIn: (qb: SDKQueryBuilderInterface<PostRow>, tagIds: string[]) => SDKQueryBuilderInterface<PostRow>;
+export declare const fluentRelationTypo: (qb: SDKQueryBuilderInterface<PostRow>) => SDKQueryBuilderInterface<PostRow>;
+/** The list operators take a list of elements — or one, read as a one-element list. */
+export declare const fluentInList: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentInScalar: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+export declare const fluentInNested: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** A comparison takes one value. `eq(column, ["a","b"])` is not a query anyone meant. */
+export declare const fluentEqArray: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * 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 declare const fluentLikeOnNumber: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** The null operators ignore their value; `null` is the conventional spelling. */
+export declare const fluentIsNull: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/**
+ * 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 declare const fluentDynamicOp: (qb: SDKQueryBuilderInterface<ContractRow>, op: WhereFilterOp) => SDKQueryBuilderInterface<ContractRow>;
+/** Two conditions on one column: the shape the Mongo compiler used to drop. */
+export declare const fluentRange: (qb: SDKQueryBuilderInterface<ContractRow>) => SDKQueryBuilderInterface<ContractRow>;
+/** The object form must accept exactly what the fluent form accepts. */
+export declare const paramsArrayContains: FindParams<ContractRow>;
+/** …and the array-of-tuples form the builder produces from two `.where()` calls. */
+export declare const paramsRange: FindParams<ContractRow>;
+/**
+ * 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 declare const readComputed: (result: FindResult<ContractRow>) => {
+    score: number | undefined;
+    distance: number | undefined;
+    title: string;
+};
+/** Widening the row must not have turned it into `any`. */
+export declare const readUnknown: (result: FindResult<ContractRow>) => any;
+/**
+ * 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 declare const rowStaysIndexable: (result: FindResult<ContractRow>) => Record<string, unknown>[];
+export {};

package/dist/sdk_query_builder.d.ts

@@ -1,4 +1,4 @@
-import { FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValue } from "@rebasepro/types";
+import { FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValueFor, type ComputedSortField } from "@rebasepro/types";
 /**
  * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
  * Entity-wrapped results (`FindResponse<M>`).
@@ -21,12 +21,12 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
      * @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;
     /**
      * Order the results by a specific column.
      */
-    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    orderBy(column: (keyof M & string) | ComputedSortField, direction?: "asc" | "desc"): this;
     /**
      * Limit the number of results returned.
      */
@@ -37,8 +37,50 @@ export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<
     offset(count: number): this;
     /**
      * 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, options?: {
+        explain?: boolean;
+    }): 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()
      */
-    search(searchString: string): this;
+    vectorSearch(property: string, vector: number[], options?: {
+        distance?: "cosine" | "l2" | "inner_product";
+        threshold?: number;
+    }): this;
     /**
      * Include related entities in the response.
      * Relations will be populated with full data instead of just IDs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/client",
   "type": "module",
-  "version": "0.13.0",
+  "version": "0.13.1-canary.g06dbe5b",
   "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.13.0",
-    "@rebasepro/utils": "0.13.0",
-    "@rebasepro/types": "0.13.0"
+    "@rebasepro/common": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/types": "0.13.1-canary.g06dbe5b",
+    "@rebasepro/utils": "0.13.1-canary.g06dbe5b"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/auth-listener-errors.test.ts

@@ -0,0 +1,57 @@
+import { jest } from "@jest/globals";
+import { createAuth } from "./auth";
+import type { Transport } from "./transport";
+
+/**
+ * What happens to an error thrown by the app's own auth listener.
+ *
+ * `emit` isolates listeners from each other, which is right — one bad handler
+ * must not stop the rest from being told about a sign-in. It also discarded the
+ * error entirely, which is not: the throw came from the *caller's* code, and it
+ * vanished with nothing in the console, so a broken `onAuthStateChange` handler
+ * looked like an event that never fired.
+ *
+ * The socket in this same package already reports these
+ * ("Error in channel handler:"). This was the one listener loop that did not.
+ */
+function transport(): Transport {
+    return {
+        request: jest.fn<any>().mockResolvedValue({}),
+        setToken: jest.fn(),
+        setAuthTokenGetter: jest.fn(),
+        setOnUnauthorized: jest.fn(),
+        baseUrl: "http://localhost:3000",
+        apiPath: "/api",
+        fetchFn: globalThis.fetch,
+        getHeaders: () => ({}),
+        resolveToken: jest.fn<any>().mockResolvedValue(null)
+    } as unknown as Transport;
+}
+
+describe("auth state listeners", () => {
+    let error: ReturnType<typeof jest.spyOn>;
+
+    beforeEach(() => { error = jest.spyOn(console, "error").mockImplementation(() => { /* quiet */ }); });
+    afterEach(() => error.mockRestore());
+
+    it("keeps telling the other listeners when one throws", () => {
+        const auth = createAuth(transport());
+        const second = jest.fn();
+
+        auth.onAuthStateChange(() => { throw new Error("handler blew up"); });
+        auth.onAuthStateChange(second);
+        auth.signOut();
+
+        expect(second).toHaveBeenCalled();
+    });
+
+    it("reports the throw instead of discarding it", () => {
+        const auth = createAuth(transport());
+        auth.onAuthStateChange(() => { throw new Error("handler blew up"); });
+
+        auth.signOut();
+
+        const said = error.mock.calls.map((c: unknown[]) => c.map(String).join(" ")).join("\n");
+        expect(said).toMatch(/handler blew up/);
+    });
+});

package/src/auth-refresh-overflow.test.ts

@@ -0,0 +1,89 @@
+import { jest } from "@jest/globals";
+import { createAuth, createMemoryStorage } from "./auth";
+import type { Transport } from "./transport";
+
+/**
+ * How far ahead the token refresh is allowed to be scheduled.
+ *
+ * `scheduleRefresh` computes `(expiresAt - REFRESH_BUFFER_MS) - Date.now()` and
+ * hands it to `setTimeout`, with a floor for the past and no ceiling. Node and
+ * every browser store that delay in a **32-bit signed integer**: hand them more
+ * than 2,147,483,647 ms — about 24.8 days — and the timer does not wait, it
+ * clamps to 1 ms and fires immediately.
+ *
+ * `auth.accessExpiresIn` is configurable and defaults to `"1h"`, so this is
+ * dormant on a default deployment. Set it to `"30d"` — an ordinary choice for an
+ * internal tool or a kiosk — and every signed-in browser refreshes at once,
+ * receives a token expiring another 30 days out, schedules again, overflows
+ * again: a hot loop against `/auth/refresh`, one per open tab.
+ *
+ * A floor without a ceiling is the tell. Someone already knew the input was
+ * untrusted and bounded one side of it. (Class 23.)
+ */
+const MAX_DELAY = 2_147_483_647;
+
+function transport(): Transport {
+    return {
+        request: jest.fn<any>().mockResolvedValue({}),
+        setToken: jest.fn(),
+        setAuthTokenGetter: jest.fn(),
+        setOnUnauthorized: jest.fn(),
+        baseUrl: "http://localhost:3000",
+        apiPath: "/api",
+        fetchFn: jest.fn<any>().mockResolvedValue({ ok: true, status: 200, json: async () => ({}) }),
+        getHeaders: () => ({}),
+        resolveToken: jest.fn<any>().mockResolvedValue(null)
+    } as unknown as Transport;
+}
+
+/** Storage already holding a session expiring `days` from now. */
+function storageWithSession(days: number) {
+    const storage = createMemoryStorage();
+    storage.setItem("rebase_auth", JSON.stringify({
+        accessToken: "at",
+        refreshToken: "rt",
+        expiresAt: Date.now() + days * 24 * 60 * 60 * 1000,
+        user: { uid: "u1" }
+    }));
+    return storage;
+}
+
+describe("scheduled token refresh", () => {
+    let delays: number[];
+    let realSetTimeout: typeof setTimeout;
+
+    beforeEach(() => {
+        delays = [];
+        realSetTimeout = globalThis.setTimeout;
+        globalThis.setTimeout = ((fn: () => void, ms?: number) => {
+            if (typeof ms === "number") delays.push(ms);
+            return realSetTimeout(() => { /* never run in this test */ }, 0);
+        }) as unknown as typeof setTimeout;
+    });
+
+    afterEach(() => { globalThis.setTimeout = realSetTimeout; });
+
+    it("schedules a normal one-hour token in the ordinary way", () => {
+        createAuth(transport(), { storage: storageWithSession(1 / 24) });
+
+        const scheduled = delays.filter(d => d > 1000);
+        expect(scheduled.length).toBeGreaterThan(0);
+        expect(Math.max(...scheduled)).toBeLessThanOrEqual(MAX_DELAY);
+    });
+
+    it("never asks setTimeout for a delay it cannot hold", () => {
+        // 30 days: 2,592,000,000 ms, past the 32-bit ceiling.
+        createAuth(transport(), { storage: storageWithSession(30) });
+
+        for (const d of delays) expect(d).toBeLessThanOrEqual(MAX_DELAY);
+    });
+
+    it("does not schedule a refresh for one millisecond from now", () => {
+        // The symptom of the overflow: the clamp makes it immediate, and the
+        // refresh that follows schedules another one just as far out.
+        createAuth(transport(), { storage: storageWithSession(90) });
+
+        const immediate = delays.filter(d => d > 0 && d < 1000);
+        expect(immediate).toEqual([]);
+    });
+});

package/src/auth.ts

@@ -89,6 +89,11 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
 
     const STORAGE_KEY = "rebase_auth";
     const REFRESH_BUFFER_MS = 120000;
+    /**
+     * The largest delay `setTimeout` can hold — 2^31 - 1 ms, about 24.8 days.
+     * Anything larger is silently clamped to 1ms by Node and every browser.
+     */
+    const MAX_TIMER_DELAY_MS = 2_147_483_647;
     // Auto-refresh resilience: retry transient failures with exponential backoff
     // (1s, 2s, 4s, … capped) before giving up and signing out.
     const MAX_REFRESH_RETRIES = 5;
@@ -129,7 +134,16 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
 
     function emit(event: AuthChangeEvent, session: RebaseSession | null) {
         for (const fn of listeners) {
-            try { fn(event, session); } catch (e) { /* ignore */ }
+            try {
+                fn(event, session);
+            } catch (e) {
+                // Isolated so one bad handler cannot stop the rest being told —
+                // but reported, because the throw came from the caller's own
+                // code and discarding it made a broken `onAuthStateChange`
+                // handler look like an event that never fired. The socket in
+                // this package already reports handler errors this way.
+                console.error("Error in auth state change listener:", e);
+            }
         }
     }
 
@@ -260,6 +274,21 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
             return;
         }
 
+        // `setTimeout` holds its delay in a 32-bit signed integer. Past
+        // ~24.8 days it does not wait — it clamps to 1ms and fires at once. The
+        // refresh would then land, receive a token expiring just as far out,
+        // schedule again and overflow again: a hot loop against
+        // `/auth/refresh`, one per open tab.
+        //
+        // `auth.accessExpiresIn` is configurable and defaults to "1h", so this
+        // is dormant on a default deployment and immediate on `"30d"` — an
+        // ordinary setting for an internal tool. Re-arm instead of refreshing:
+        // sleep the maximum, then work out again how long is left.
+        if (delay > MAX_TIMER_DELAY_MS) {
+            refreshTimeout = setTimeout(() => scheduleRefresh(expiresAt), MAX_TIMER_DELAY_MS);
+            return;
+        }
+
         refreshTimeout = setTimeout(() => { void attemptScheduledRefresh(0); }, delay);
     }