@rebasepro/client 0.8.0 → 0.9.0

package/dist/sdk_query_builder.d.ts

@@ -0,0 +1,63 @@
+import { FindResult, LogicalCondition, SDKCollectionClient, SDKQueryBuilderInterface, WhereFilterOp, WhereValue } from "@rebasepro/types";
+/**
+ * SDK Query Builder — returns flat rows (`FindResult<M>`) instead of
+ * Entity-wrapped results (`FindResponse<M>`).
+ *
+ * @example
+ * const { data } = await rebase.data.posts
+ *     .where("status", "==", "published")
+ *     .orderBy("created_at", "desc")
+ *     .limit(10)
+ *     .find();
+ *
+ * console.log(data[0].title); // flat access
+ */
+export declare class SDKQueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements SDKQueryBuilderInterface<M> {
+    private collection;
+    private params;
+    constructor(collection: SDKCollectionClient<M>);
+    /**
+     * Add a filter condition to your query.
+     * @example
+     * client.data.users.where('age', '>=', 18).find()
+     */
+    where<K extends keyof M & string>(column: K, operator: WhereFilterOp, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
+    /**
+     * Order the results by a specific column.
+     */
+    orderBy(column: keyof M & string, direction?: "asc" | "desc"): this;
+    /**
+     * Limit the number of results returned.
+     */
+    limit(count: number): this;
+    /**
+     * Skip the first N results.
+     */
+    offset(count: number): this;
+    /**
+     * Set a free-text search string if supported by the backend.
+     */
+    search(searchString: string): this;
+    /**
+     * Include related entities in the response.
+     * Relations will be populated with full data instead of just IDs.
+     *
+     * @param relations - Relation names to include, or "*" for all.
+     * @example
+     * client.data.posts.include("tags", "author").find()
+     */
+    include(...relations: string[]): this;
+    /**
+     * Execute the find query and return the results as flat rows.
+     */
+    find(): Promise<FindResult<M>>;
+    /**
+     * Count the records matching this query.
+     */
+    count(): Promise<number>;
+    /**
+     * Listen to realtime updates matching this query.
+     */
+    listen(onUpdate: (data: FindResult<M>) => void, onError?: (error: Error) => void): () => void;
+}

package/dist/transport.d.ts

@@ -1,4 +1,6 @@
 import { FindParams as TypesFindParams, FindResponse as TypesFindResponse } from "@rebasepro/types";
+export { RebaseApiError } from "@rebasepro/types";
+export type { RebaseErrorInit } from "@rebasepro/types";
 export interface RebaseClientConfig {
     baseUrl?: string;
     token?: string;
@@ -12,12 +14,6 @@ export interface RebaseClientConfig {
  */
 export type FindParams = TypesFindParams;
 export type FindResponse<T> = TypesFindResponse<T extends Record<string, unknown> ? T : Record<string, unknown>>;
-export declare class RebaseApiError extends Error {
-    status: number;
-    code?: string;
-    details?: unknown;
-    constructor(status: number, message: string, code?: string, details?: unknown);
-}
 export declare function buildQueryString(params?: FindParams): string;
 export interface Transport {
     request: <T = unknown>(path: string, init?: RequestInit) => Promise<T>;

package/dist/websocket.d.ts

@@ -1,4 +1,4 @@
-import { DeleteEntityProps, Entity, EntityCollection, FetchCollectionProps, FetchEntityProps, SaveEntityProps, TableMetadata, BranchInfo } from "@rebasepro/types";
+import { DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, SaveProps, TableMetadata, BranchInfo } from "@rebasepro/types";
 export interface RebaseWebSocketConfig {
     websocketUrl: string;
     /** Optional auth token getter for WebSocket authentication */
@@ -8,11 +8,15 @@ export interface RebaseWebSocketConfig {
     /** Callback to handle unauthorized requests or token expiration (refreshes auth session) */
     onUnauthorized?: () => Promise<boolean>;
 }
-export declare class ApiError extends Error {
-    code?: string;
-    error?: string;
-    constructor(message: string, error?: string, code?: string);
-}
+/**
+ * Low-level realtime WebSocket client.
+ *
+ * @internal Not a stable app-facing API. `createRebaseClient()` constructs and
+ * manages this internally (exposed as `client.ws`, typed by the minimal
+ * `RebaseWebSocket` contract in `@rebasepro/types`). It is re-exported from the
+ * package root only because the `@rebasepro/client-postgresql` driver
+ * instantiates it directly; its surface may change without a major bump.
+ */
 export declare class RebaseWebSocketClient {
     private websocketUrl;
     private ws;
@@ -22,7 +26,7 @@ export declare class RebaseWebSocketClient {
     on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void): () => boolean;
     private emit;
     private collectionSubscriptions;
-    private entitySubscriptions;
+    private singleSubscriptions;
     private backendToCollectionKey;
     private backendToEntityKey;
     private pendingRequests;
@@ -53,7 +57,7 @@ export declare class RebaseWebSocketClient {
     private isAuthError;
     private handleAuthFailure;
     /**
-     * Shared logic for re-subscribing a collection or entity subscription
+     * Shared logic for re-subscribing a collection or row subscription
      * after an auth error is resolved by refreshing credentials.
      */
     private resubscribeAfterAuthRefresh;
@@ -62,10 +66,10 @@ export declare class RebaseWebSocketClient {
     reauthenticate(): Promise<void>;
     private sendMessage;
     private doSendMessage;
-    fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Entity<M>[]>;
-    fetchEntity<M extends Record<string, unknown>>(props: FetchEntityProps<M>): Promise<Entity<M> | undefined>;
-    saveEntity<M extends Record<string, unknown>>(props: SaveEntityProps<M>): Promise<Entity<M>>;
-    deleteEntity<M extends Record<string, unknown>>(props: DeleteEntityProps<M>): Promise<void>;
+    fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
+    fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
+    save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
+    delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
     executeSql(sql: string, options?: {
         database?: string;
         role?: string;
@@ -73,8 +77,8 @@ export declare class RebaseWebSocketClient {
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
     fetchCurrentDatabase(): Promise<string | undefined>;
-    checkUniqueField(path: string, name: string, value: unknown, entityId?: string, collection?: EntityCollection): Promise<boolean>;
-    countEntities<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
+    checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
+    count<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
     fetchUnmappedTables(mappedPaths?: string[]): Promise<string[]>;
     fetchTableMetadata(tableName: string): Promise<TableMetadata>;
     createBranch(name: string, options?: {
@@ -89,14 +93,14 @@ export declare class RebaseWebSocketClient {
     private deepEqual;
     private normalizeForComparison;
     /**
-     * Merge incoming entities with cached data, preserving cached references
-     * for entities whose values haven't changed. This avoids unnecessary
-     * React re-renders when the server refetches all entities but most
+     * Merge incoming rows with cached data, preserving cached references
+     * for rows whose values haven't changed. This avoids unnecessary
+     * React re-renders when the server refetches all rows but most
      * haven't actually changed.
      */
-    private mergeEntities;
-    listenCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>, onUpdate: (entities: Entity[]) => void, onError?: (error: Error) => void): () => void;
-    listenEntity<M extends Record<string, unknown>>(props: FetchEntityProps<M>, onUpdate: (entity: Entity | null) => void, onError?: (error: Error) => void): () => void;
+    private mergeRows;
+    listenCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>, onUpdate: (rows: Record<string, unknown>[]) => void, onError?: (error: Error) => void): () => void;
+    listenOne<M extends Record<string, unknown>>(props: FetchOneProps<M>, onUpdate: (row: Record<string, unknown> | null) => void, onError?: (error: Error) => void): () => void;
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so
@@ -104,5 +108,5 @@ export declare class RebaseWebSocketClient {
      */
     private resubscribeAll;
     private createCollectionSubscriptionKey;
-    private createEntitySubscriptionKey;
+    private createSingleSubscriptionKey;
 }

package/package.json

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

package/src/auth.ts

@@ -1,32 +1,38 @@
 import { RebaseApiError, Transport } from "./transport";
-import { AuthChangeEvent } from "@rebasepro/types";
+import type { AuthChangeEvent, RebaseSession, AuthTokens, DeviceSession, User } from "@rebasepro/types";
 
+// Re-export canonical types so `import { RebaseSession } from "@rebasepro/client"` keeps working
+export type { RebaseSession, AuthTokens, AuthChangeEvent, DeviceSession } from "@rebasepro/types";
 
-export interface RebaseUser {
+/** @deprecated Use `User` from `@rebasepro/types` instead. */
+export type RebaseUser = User;
+/** @deprecated Use `AuthTokens` from `@rebasepro/types` instead. */
+export type RebaseTokens = AuthTokens;
+
+/** Minimal, non-sensitive user profile returned by {@link findUserByEmail}. */
+export interface PublicUserProfile {
     uid: string;
-    email: string | null;
     displayName: string | null;
     photoURL: string | null;
-    emailVerified?: boolean;
-    roles?: string[];
-    providerId: string;
-    isAnonymous: boolean;
-}
-
-export interface RebaseTokens {
-    accessToken: string;
-    refreshToken: string;
-    accessTokenExpiresAt: number;
 }
 
-export interface RebaseSession {
-    accessToken: string;
-    refreshToken: string;
-    expiresAt: number;
-    user: RebaseUser;
+/** Map a raw user object from an auth response (`/login`, `/refresh`, `/me`) to a `User`. */
+function mapRawUser(raw: Record<string, unknown>): User {
+    return {
+        uid: raw.uid as string,
+        email: (raw.email as string | null) ?? null,
+        displayName: (raw.displayName as string | null) ?? null,
+        photoURL: (raw.photoURL as string | null) ?? null,
+        providerId: (raw.providerId as string | undefined) ?? "password",
+        isAnonymous: (raw.isAnonymous as boolean | undefined) ?? false,
+        emailVerified: raw.emailVerified as boolean | undefined,
+        roles: raw.roles as string[] | undefined,
+        metadata: raw.metadata as Record<string, unknown> | undefined,
+    };
 }
 
-export type { AuthChangeEvent };
+/** Placeholder user, used only as a last resort when none can be resolved. */
+const EMPTY_USER: User = { uid: "", email: null, displayName: null, photoURL: null, providerId: "password", isAnonymous: false };
 
 
 export interface AuthConfig {
@@ -70,6 +76,12 @@ export interface CreateAuthOptions {
     authPath?: string;
     autoRefresh?: boolean;
     persistSession?: boolean;
+    /**
+     * Authentication flow mode.
+     * - 'json' (default): Tokens are sent/received in JSON bodies. Refresh token is stored in local storage.
+     * - 'cookie': Refresh token is sent/received via httpOnly cookies. Access token remains in memory.
+     */
+    authFlowMode?: "json" | "cookie";
 }
 
 export function createAuth(transport: Transport, options?: CreateAuthOptions) {
@@ -78,13 +90,28 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
     const authPath = opts.authPath || "/auth";
     const autoRefresh = opts.autoRefresh !== false;
     const persistSession = opts.persistSession !== false;
+    const authFlowMode = opts.authFlowMode || "json";
 
     const STORAGE_KEY = "rebase_auth";
     const REFRESH_BUFFER_MS = 120000;
+    // Auto-refresh resilience: retry transient failures with exponential backoff
+    // (1s, 2s, 4s, … capped) before giving up and signing out.
+    const MAX_REFRESH_RETRIES = 5;
+    const REFRESH_RETRY_BASE_MS = 1000;
+    const REFRESH_RETRY_MAX_MS = 30000;
 
     let currentSession: RebaseSession | null = null;
     const listeners = new Set<(event: AuthChangeEvent, session: RebaseSession | null) => void>();
     let refreshTimeout: ReturnType<typeof setTimeout> | null = null;
+    // De-dupe concurrent refreshes. On boot (esp. cookie mode + React StrictMode)
+    // multiple callers can trigger refresh at once; without this they race — the
+    // server rotates the refresh token twice and the browser can end up with a
+    // cookie the DB no longer matches. A single in-flight promise is shared.
+    let inFlightRefresh: Promise<RebaseSession> | null = null;
+    let resolveInitialized: (value: void | PromiseLike<void>) => void;
+    const isInitialized = new Promise<void>((resolve) => {
+        resolveInitialized = resolve;
+    });
 
     function authUrl(endpoint: string) {
         return transport.baseUrl + transport.apiPath + authPath + endpoint;
@@ -96,10 +123,12 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
 
     function throwApiError(status: number, body: { error?: { message?: string; code?: string; details?: unknown }; message?: string; code?: string; details?: unknown } | undefined, statusText: string): never {
         throw new RebaseApiError(
-            status,
             body?.error?.message || body?.message || statusText,
-            body?.error?.code || body?.code,
-            body?.error?.details || body?.details
+            {
+                status,
+                code: body?.error?.code || body?.code,
+                details: body?.error?.details || body?.details
+            }
         );
     }
 
@@ -110,7 +139,7 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
     }
 
     function saveSession(session: RebaseSession) {
-        if (!persistSession) return;
+        if (!persistSession || authFlowMode === "cookie") return;
         try {
             storage.setItem(STORAGE_KEY, JSON.stringify(session));
         } catch (e) { /* ignore */ }
@@ -130,6 +159,37 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
         return null;
     }
 
+    /**
+     * A refresh failure is only fatal if the refresh token itself is rejected
+     * (expired / invalid / forbidden). Network blips, timeouts, and 5xx (e.g. a
+     * backend restart mid-session) are transient and must NOT log the user out.
+     */
+    function isFatalRefreshError(err: unknown): boolean {
+        if (!(err instanceof RebaseApiError)) return false; // network/other → transient
+        if (err.code === "INVALID_TOKEN" || err.code === "TOKEN_EXPIRED") return true;
+        // 401/403 are auth failures; other statuses (incl. 5xx, 0) are transient.
+        return err.status === 401 || err.status === 403;
+    }
+
+    async function attemptScheduledRefresh(attempt: number) {
+        try {
+            await refreshSession();
+            // On success, refreshSession() re-schedules the next refresh itself.
+        } catch (err) {
+            if (isFatalRefreshError(err)) {
+                signOut();
+                return;
+            }
+            if (attempt >= MAX_REFRESH_RETRIES) {
+                signOut();
+                return;
+            }
+            // Transient failure — back off and retry rather than dropping the session.
+            const backoff = Math.min(REFRESH_RETRY_BASE_MS * 2 ** attempt, REFRESH_RETRY_MAX_MS);
+            refreshTimeout = setTimeout(() => { void attemptScheduledRefresh(attempt + 1); }, backoff);
+        }
+    }
+
     function scheduleRefresh(expiresAt: number) {
         if (refreshTimeout) clearTimeout(refreshTimeout);
         if (!autoRefresh) return;
@@ -137,25 +197,20 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
         const delay = (expiresAt - REFRESH_BUFFER_MS) - Date.now();
 
         if (delay <= 0) {
-            refreshSession().catch(() => signOut());
+            void attemptScheduledRefresh(0);
             return;
         }
 
-        refreshTimeout = setTimeout(async () => {
-            try {
-                await refreshSession();
-            } catch (e) {
-                signOut();
-            }
-        }, delay);
+        refreshTimeout = setTimeout(() => { void attemptScheduledRefresh(0); }, delay);
     }
 
-    function handleAuthResponse(data: { tokens: RebaseTokens, user: RebaseUser }, event?: AuthChangeEvent): RebaseSession {
+    function handleAuthResponse(data: { tokens: AuthTokens, user: Record<string, unknown> }, event?: AuthChangeEvent): RebaseSession {
+        const user: User = mapRawUser(data.user);
         const session: RebaseSession = {
             accessToken: data.tokens.accessToken,
-            refreshToken: data.tokens.refreshToken,
+            refreshToken: data.tokens.refreshToken || (currentSession?.refreshToken) || "",
             expiresAt: data.tokens.accessTokenExpiresAt,
-            user: data.user
+            user
         };
         currentSession = session;
         saveSession(session);
@@ -171,8 +226,9 @@ export function createAuth(transport: Transport, options?: CreateAuthOptions) {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ email,
-password })
-        });
+password }),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const body = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, body, res.statusText);
         const session = handleAuthResponse(body, "SIGNED_IN");
@@ -189,8 +245,9 @@ password };
         const res = await fetchFn(authUrl("/register"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(payload)
-        });
+            body: JSON.stringify(payload),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const body = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, body, res.statusText);
         const session = handleAuthResponse(body, "SIGNED_IN");
@@ -214,8 +271,9 @@ refreshToken: session.refreshToken };
         const res = await fetchFn(authUrl("/google"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(payload)
-        });
+            body: JSON.stringify(payload),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const responseBody = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, responseBody, res.statusText);
         const session = handleAuthResponse(responseBody, "SIGNED_IN");
@@ -230,8 +288,9 @@ refreshToken: session.refreshToken };
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ code,
-redirectUri })
-        });
+redirectUri }),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const body = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, body, res.statusText);
         const session = handleAuthResponse(body, "SIGNED_IN");
@@ -249,8 +308,9 @@ refreshToken: session.refreshToken };
         const res = await fetchFn(authUrl(`/${providerId}`), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(payload)
-        });
+            body: JSON.stringify(payload),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const body = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, body, res.statusText);
         const session = handleAuthResponse(body, "SIGNED_IN");
@@ -316,12 +376,13 @@ redirectUri });
     async function signOut() {
         const fetchFn = getFetch();
         try {
-            if (currentSession?.refreshToken) {
+            if (authFlowMode === "cookie" || currentSession?.refreshToken) {
                 await fetchFn(authUrl("/logout"), {
                     method: "POST",
                     headers: { "Content-Type": "application/json" },
-                    body: JSON.stringify({ refreshToken: currentSession.refreshToken })
-                });
+                    body: JSON.stringify({ refreshToken: currentSession?.refreshToken }),
+                    credentials: authFlowMode === "cookie" ? "include" : undefined
+                } as RequestInit);
             }
         } catch (e) { /* ignore */ }
         currentSession = null;
@@ -334,23 +395,52 @@ redirectUri });
         emit("SIGNED_OUT", null);
     }
 
-    async function refreshSession() {
-        if (!currentSession?.refreshToken) {
+    function refreshSession(): Promise<RebaseSession> {
+        // Share a single in-flight refresh across concurrent callers.
+        if (inFlightRefresh) return inFlightRefresh;
+        inFlightRefresh = doRefreshSession().finally(() => {
+            inFlightRefresh = null;
+        });
+        return inFlightRefresh;
+    }
+
+    async function doRefreshSession(): Promise<RebaseSession> {
+        if (authFlowMode !== "cookie" && !currentSession?.refreshToken) {
             throw new Error("No active session to refresh");
         }
         const fetchFn = getFetch();
         const res = await fetchFn(authUrl("/refresh"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ refreshToken: currentSession.refreshToken })
-        });
+            body: JSON.stringify({ refreshToken: currentSession?.refreshToken }),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const body = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, body, res.statusText);
+
+        const accessToken = body.tokens.accessToken;
+        transport.setToken(accessToken);
+
+        // Resolve the user, in order of preference:
+        //   1. the user returned by /refresh (modern backends include it),
+        //   2. the user already in memory,
+        //   3. a fetch of /me — required to restore a session from an httpOnly
+        //      cookie alone (cold start in cookie mode), where there is no
+        //      in-memory user and the backend didn't echo one.
+        let user = currentSession?.user;
+        if (body.user && typeof body.user.uid === "string") {
+            user = mapRawUser(body.user as Record<string, unknown>);
+        } else if (!user || !user.uid) {
+            try {
+                user = await getUser();
+            } catch { /* fall through to the empty stub below */ }
+        }
+
         const session: RebaseSession = {
-            accessToken: body.tokens.accessToken,
-            refreshToken: body.tokens.refreshToken,
+            accessToken,
+            refreshToken: body.tokens.refreshToken || currentSession?.refreshToken || "",
             expiresAt: body.tokens.accessTokenExpiresAt,
-            user: currentSession.user
+            user: user ?? EMPTY_USER
         };
         currentSession = session;
         saveSession(session);
@@ -361,12 +451,26 @@ redirectUri });
     }
 
     async function getUser() {
-        const data = await transport.request<{ user: RebaseUser }>(authPath + "/me", { method: "GET" });
+        const data = await transport.request<{ user: User }>(authPath + "/me", { method: "GET" });
+        return data.user;
+    }
+
+    /**
+     * Resolve an email to a minimal public profile (`uid`, `displayName`,
+     * `photoURL`) for invite-by-email flows. Returns `null` when no account
+     * matches. Requires the backend to opt in via `auth.allowUserLookup`;
+     * otherwise the endpoint is absent and this rejects.
+     */
+    async function findUserByEmail(email: string): Promise<PublicUserProfile | null> {
+        const data = await transport.request<{ user: PublicUserProfile | null }>(authPath + "/find-user", {
+            method: "POST",
+            body: JSON.stringify({ email })
+        });
         return data.user;
     }
 
     async function updateUser(updates: { displayName?: string, photoURL?: string }) {
-        const data = await transport.request<{ user: RebaseUser }>(authPath + "/me", {
+        const data = await transport.request<{ user: User }>(authPath + "/me", {
             method: "PATCH",
             body: JSON.stringify(updates)
         });
@@ -446,8 +550,9 @@ newPassword })
         const res = await fetchFn(authUrl("/magic-link/verify"), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ token })
-        });
+            body: JSON.stringify({ token }),
+            credentials: authFlowMode === "cookie" ? "include" : undefined
+        } as RequestInit);
         const body = await res.json().catch(() => ({}));
         if (!res.ok) throwApiError(res.status, body, res.statusText);
         const session = handleAuthResponse(body, "SIGNED_IN");
@@ -456,8 +561,8 @@ accessToken: session.accessToken,
 refreshToken: session.refreshToken };
     }
 
-    async function getSessions() {
-        const data = await transport.request<{ sessions: Record<string, unknown>[] }>(authPath + "/sessions", { method: "GET" });
+    async function getSessions(): Promise<DeviceSession[]> {
+        const data = await transport.request<{ sessions: DeviceSession[] }>(authPath + "/sessions", { method: "GET" });
         return data.sessions;
     }
 
@@ -504,20 +609,37 @@ refreshToken: session.refreshToken };
 
     if (persistSession) {
         const stored = loadStoredSession();
-        if (stored && stored.accessToken && stored.refreshToken) {
+        if (stored && stored.accessToken) {
             if (stored.expiresAt > Date.now()) {
                 currentSession = stored;
                 transport.setToken(stored.accessToken);
                 scheduleRefresh(stored.expiresAt);
-            } else if (stored.refreshToken) {
+                resolveInitialized!();
+            } else if (authFlowMode === "cookie" || stored.refreshToken) {
                 currentSession = stored;
-                refreshSession().catch(() => {
+                refreshSession().then(() => {
+                    resolveInitialized!();
+                }).catch(() => {
                     currentSession = null;
                     clearStoredSession();
                     transport.setToken(null);
+                    resolveInitialized!();
                 });
+            } else {
+                resolveInitialized!();
             }
+        } else if (authFlowMode === "cookie") {
+            // Silent refresh on boot to pick up httpOnly session
+            refreshSession().then(() => {
+                resolveInitialized!();
+            }).catch(() => {
+                resolveInitialized!();
+            });
+        } else {
+            resolveInitialized!();
         }
+    } else {
+        resolveInitialized!();
     }
 
     return {
@@ -539,6 +661,7 @@ refreshToken: session.refreshToken };
         signOut,
         refreshSession,
         getUser,
+        findUserByEmail,
         updateUser,
         resetPasswordForEmail,
         resetPassword,
@@ -552,7 +675,8 @@ refreshToken: session.refreshToken };
         revokeAllSessions,
         getAuthConfig,
         getSession,
-        onAuthStateChange
+        onAuthStateChange,
+        isInitialized: () => isInitialized
     };
 }