@reatomized/convex 0.1.1 → 0.3.0

package/README.md

@@ -55,6 +55,66 @@ gets its own connection. The socket opens on first use in a context.
 There are no React hooks. Read the atoms through your Reatom view binding, such
 as `@reatom/react` or `@reatom/jsx`.
 
+## Auth
+
+`reatomAuthState(convex, provider)` does what convex/react's
+`ConvexProviderWithAuth` and `useConvexAuth` do. An auth library reports whether
+it is loading and who is signed in, `reatomAuthState` sends that session's
+token, and its `status` turns `authenticated` once the server accepts the token.
+`status` is `loading`, `unauthenticated`, `authenticated` or `rejected`;
+`isLoading`, `isAuthenticated` and `isRefreshing` are atoms too. The client
+follows the provider while one of these atoms has a subscriber, so subscribe to
+one at the root of the app.
+
+Two entry points build the provider from an auth library:
+
+```ts
+// Convex Auth (@convex-dev/auth)
+import { reatomConvexAuthProvider } from "@reatomized/convex/convex-auth";
+
+const convexAuth = reatomConvexAuthProvider(convex);
+const auth = reatomAuthState(convex, convexAuth);
+await convexAuth.signIn("password", { email, password, flow: "signIn" });
+await convexAuth.signIn("github"); // navigates to GitHub
+await convexAuth.signOut();
+```
+
+`reatomConvexAuthProvider` implements the client side of `@convex-dev/auth`,
+whose own client is a React provider. It uses the same storage keys, so sessions
+carry over from `@convex-dev/auth/react`. On start it signs in with a `code`
+from the URL, and it refreshes the token once across tabs.
+`completeSignIn(code)` runs that exchange for an app that reads the URL itself;
+its `error` atom holds a failed exchange either way.
+
+```ts
+// Better Auth with @convex-dev/better-auth
+import { reatomBetterAuthProvider } from "@reatomized/convex/better-auth";
+import {
+  convexClient,
+  crossDomainClient,
+} from "@convex-dev/better-auth/client/plugins";
+import { createAuthClient } from "better-auth/client";
+
+const authClient = createAuthClient({
+  baseURL: import.meta.env.VITE_CONVEX_SITE_URL,
+  plugins: [convexClient(), crossDomainClient()],
+});
+const auth = reatomAuthState(convex, reatomBetterAuthProvider(authClient));
+await authClient.signIn.email({ email, password });
+```
+
+Better Auth's client works without a framework, so you sign in through it;
+`reatomBetterAuthProvider` follows its session store, fetches Convex tokens, and
+trades the `ott` one-time token from a cross-domain OAuth redirect for the
+session. Its `data` atom is the store's session and user, typed by your client,
+and `completeSignIn(ott)` is the one-time token trade with an `error` atom.
+Neither entry point adds dependencies.
+
+For another library, pass any object with `isLoading` and `session` atoms and a
+`fetchToken` function. `session` should change when the identity does, such as a
+user or organization id. Pass an atom of providers to switch libraries at
+runtime.
+
 ## Node
 
 With `@reatom/core@1001.3.0` loaded, Node never exits on its own, so a script

package/dist/browser/reatom/auth_state.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Joins an auth library's session with the server's answer about its token,
+ * like convex/react's `ConvexProviderWithAuth`: the library says who is signed
+ * in, the client sends that session's token, and only a token the server
+ * accepted counts as authenticated.
+ */
+import { type AtomLike, type Computed } from "@reatom/core";
+import type { AuthTokenFetcher } from "./auth.js";
+import type { ReatomConvexClient } from "./client.js";
+/**
+ * The part of an auth library the client needs. `@reatomized/convex/convex-auth`
+ * and `@reatomized/convex/better-auth` return one; for another library, build
+ * it from that library's session.
+ *
+ * @public
+ */
+export type AuthProvider = {
+    /** The library is still restoring or completing its session. */
+    readonly isLoading: AtomLike<boolean, []>;
+    /**
+     * The signed-in session, `null` without one. Its value only needs to
+     * identify the session: when it changes, for example to another user or
+     * organization, the client sends a new token.
+     */
+    readonly session: AtomLike<string | null, []>;
+    readonly fetchToken: AuthTokenFetcher;
+};
+/**
+ * `rejected` means the library has a session but the server refused its
+ * token, for example because convex/auth.config.ts doesn't list the issuer.
+ *
+ * @public
+ */
+export type AuthStatus = "loading" | "unauthenticated" | "authenticated" | "rejected";
+/** @public */
+export type ReatomAuthState = {
+    readonly status: Computed<AuthStatus>;
+    readonly isLoading: Computed<boolean>;
+    /** The server accepted the current session's token. */
+    readonly isAuthenticated: Computed<boolean>;
+    /** The server rejected an accepted token and a replacement is being fetched. */
+    readonly isRefreshing: Computed<boolean>;
+};
+/**
+ * Keeps the client's auth in step with `provider` while any of the returned
+ * atoms has a subscriber. Pass an atom of providers to switch libraries at
+ * runtime. Call `convex.setAuth` and `convex.clearAuth` only through this
+ * state once it is in use.
+ *
+ * ```ts
+ * const auth = reatomAuthState(convex, reatomConvexAuthProvider(convex));
+ * const notes = computed(() =>
+ *   auth.isAuthenticated() ? convex.query(api.notes.mine, {}).data() : [],
+ * );
+ * ```
+ *
+ * @public
+ */
+export declare function reatomAuthState(convex: ReatomConvexClient, provider: AuthProvider | AtomLike<AuthProvider, []>, name?: string): ReatomAuthState;

package/dist/browser/reatom/auth_state.js

@@ -0,0 +1,62 @@
+/**
+ * Joins an auth library's session with the server's answer about its token,
+ * like convex/react's `ConvexProviderWithAuth`: the library says who is signed
+ * in, the client sends that session's token, and only a token the server
+ * accepted counts as authenticated.
+ */
+import { atom, computed, effect, peek, withConnectHook, } from "@reatom/core";
+/**
+ * Keeps the client's auth in step with `provider` while any of the returned
+ * atoms has a subscriber. Pass an atom of providers to switch libraries at
+ * runtime. Call `convex.setAuth` and `convex.clearAuth` only through this
+ * state once it is in use.
+ *
+ * ```ts
+ * const auth = reatomAuthState(convex, reatomConvexAuthProvider(convex));
+ * const notes = computed(() =>
+ *   auth.isAuthenticated() ? convex.query(api.notes.mine, {}).data() : [],
+ * );
+ * ```
+ *
+ * @public
+ */
+export function reatomAuthState(convex, provider, name = `${convex.name}.authState`) {
+    const current = typeof provider === "function" ? provider : () => provider;
+    // The provider and session whose token the client holds. Until it is the
+    // current one, the server's answer is about an earlier session.
+    const applied = atom(null, `${name}._applied`);
+    const sync = () => effect(() => {
+        const source = current();
+        const session = source.isLoading() ? null : source.session();
+        const last = peek(applied);
+        if (last?.provider === source && last.session === session)
+            return;
+        if (session !== null)
+            convex.setAuth(source.fetchToken);
+        else if (last)
+            convex.clearAuth();
+        applied.set(session === null ? null : { provider: source, session });
+    }, `${name}._sync`).unsubscribe;
+    const status = computed(() => {
+        const source = current();
+        if (source.isLoading())
+            return "loading";
+        const session = source.session();
+        if (session === null)
+            return "unauthenticated";
+        const last = applied();
+        if (last?.provider !== source || last.session !== session)
+            return "loading";
+        const accepted = convex.isAuthenticated();
+        if (accepted === null)
+            return "loading";
+        return accepted ? "authenticated" : "rejected";
+    }, `${name}.status`).extend(withConnectHook(sync));
+    const isAuthenticated = computed(() => status() === "authenticated", `${name}.isAuthenticated`);
+    return {
+        status,
+        isLoading: computed(() => status() === "loading", `${name}.isLoading`),
+        isAuthenticated,
+        isRefreshing: computed(() => isAuthenticated() && convex.isRefreshingAuth(), `${name}.isRefreshing`),
+    };
+}

package/dist/browser/reatom/better_auth.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The `@reatomized/convex/better-auth` entry: a better-auth session for
+ * `reatomAuthState`, like `@convex-dev/better-auth/react`'s
+ * `ConvexBetterAuthProvider`. Sign in and out through the better-auth client
+ * itself; its session store tells this provider.
+ */
+import { type Action, type AsyncExt, type AtomLike, type Computed } from "@reatom/core";
+import type { AuthProvider } from "./auth_state.js";
+export type { AuthProvider } from "./auth_state.js";
+type SessionState = {
+    data: {
+        session?: {
+            id: string;
+        } | null | undefined;
+    } | null;
+    isPending: boolean;
+};
+type SessionData<Client extends BetterAuthClient> = ReturnType<Client["useSession"]["get"]>["data"];
+/**
+ * What the provider uses of a client from better-auth's `createAuthClient`
+ * (`better-auth/client`) with `@convex-dev/better-auth`'s `convexClient()`
+ * plugin, and `crossDomainClient()` when the Convex site is another origin.
+ *
+ * @public
+ */
+export type BetterAuthClient = {
+    /** A nanostores store of the session. */
+    useSession: {
+        get(): SessionState;
+        subscribe(listener: (value: SessionState) => void): () => void;
+    };
+    convex: {
+        token(options: {
+            fetchOptions: {
+                throw: false;
+            };
+        }): Promise<{
+            data?: {
+                token?: string | null | undefined;
+            } | null | undefined;
+        }>;
+    };
+    getSession(options?: {
+        fetchOptions?: {
+            headers?: Record<string, string>;
+        };
+    }): Promise<unknown>;
+    crossDomain?: {
+        oneTimeToken: {
+            verify(args: {
+                token: string;
+            }): Promise<{
+                data?: {
+                    session?: {
+                        token: string;
+                    } | null | undefined;
+                } | null | undefined;
+                error?: {
+                    message?: string | undefined;
+                } | null | undefined;
+            }>;
+        };
+    };
+    updateSession?(): void;
+};
+/** @public */
+export type BetterAuthOptions = {
+    /** A Convex token from server rendering, used until the session loads. */
+    initialToken?: string | null;
+    /**
+     * Whether an `ott` query param on start is a one-time token to sign in with;
+     * `true` by default. Only `crossDomainClient()` sends one.
+     */
+    shouldHandleOneTimeToken?: boolean;
+    /** Drops `ott` from the address; `history.replaceState` by default. */
+    replaceURL?: (url: URL) => void | Promise<void>;
+};
+/** @public */
+export type ReatomBetterAuth<Data = SessionState["data"]> = AuthProvider & {
+    /** The session store's data: the session and user, `null` when signed out. */
+    readonly data: Computed<Data>;
+    /** The last Convex token, `null` without one. */
+    readonly token: AtomLike<string | null, []>;
+    /**
+     * Trades the one-time token a cross-domain OAuth redirect comes back with
+     * for the session. Runs on start for an `ott` in the URL; call it when the
+     * app takes the token from the URL itself. Its `error` holds a failed trade.
+     */
+    readonly completeSignIn: Action<[oneTimeToken: string], Promise<void>> & AsyncExt<[oneTimeToken: string], void>;
+};
+/**
+ * With `crossDomainClient()`, an OAuth sign-in comes back with a one-time
+ * token in the `ott` query param; the provider trades it for the session.
+ *
+ * ```ts
+ * const authClient = createAuthClient({
+ *   baseURL: import.meta.env.VITE_CONVEX_SITE_URL,
+ *   plugins: [convexClient(), crossDomainClient()],
+ * });
+ * const auth = reatomAuthState(convex, reatomBetterAuthProvider(authClient));
+ * await authClient.signIn.email({ email, password });
+ * ```
+ *
+ * @public
+ */
+export declare function reatomBetterAuthProvider<Client extends BetterAuthClient>(authClient: Client, options?: BetterAuthOptions, name?: string): ReatomBetterAuth<SessionData<Client>>;

package/dist/browser/reatom/better_auth.js

@@ -0,0 +1,110 @@
+/**
+ * The `@reatomized/convex/better-auth` entry: a better-auth session for
+ * `reatomAuthState`, like `@convex-dev/better-auth/react`'s
+ * `ConvexBetterAuthProvider`. Sign in and out through the better-auth client
+ * itself; its session store tells this provider.
+ */
+import { action, atom, computed, peek, withAsync, withConnectHook, wrap, } from "@reatom/core";
+/**
+ * With `crossDomainClient()`, an OAuth sign-in comes back with a one-time
+ * token in the `ott` query param; the provider trades it for the session.
+ *
+ * ```ts
+ * const authClient = createAuthClient({
+ *   baseURL: import.meta.env.VITE_CONVEX_SITE_URL,
+ *   plugins: [convexClient(), crossDomainClient()],
+ * });
+ * const auth = reatomAuthState(convex, reatomBetterAuthProvider(authClient));
+ * await authClient.signIn.email({ email, password });
+ * ```
+ *
+ * @public
+ */
+export function reatomBetterAuthProvider(authClient, options = {}, name = "betterAuth") {
+    const token = atom(options.initialToken ?? null, `${name}.token`);
+    // Boxed, so the atom holds the request rather than its result.
+    const pending = atom(null, `${name}._pending`);
+    const state = atom(() => authClient.useSession.get(), `${name}.sessionState`).extend(withConnectHook((target) => {
+        void start();
+        return authClient.useSession.subscribe(wrap((value) => {
+            const previous = peek(target).data?.session?.id;
+            target.set(value);
+            if (value.isPending)
+                return;
+            // The cached token belongs to the previous session, or to none.
+            const id = value.data?.session?.id;
+            if (!id || (previous && id !== previous))
+                token.set(null);
+        }));
+    }));
+    const completeSignIn = action(async (oneTimeToken) => {
+        // better-auth's client answers every property, so a missing plugin shows
+        // up as a failed request rather than an undefined `crossDomain`.
+        const result = await wrap(authClient.crossDomain.oneTimeToken.verify({ token: oneTimeToken }));
+        const session = result.data?.session;
+        if (!session)
+            throw new Error(result.error?.message ?? "Invalid one-time token");
+        await wrap(authClient.getSession({
+            fetchOptions: { headers: { Authorization: `Bearer ${session.token}` } },
+        }));
+        authClient.updateSession?.();
+    }, `${name}.completeSignIn`).extend(withAsync());
+    const started = atom(false, `${name}._started`);
+    const start = action(async () => {
+        if (peek(started))
+            return;
+        started.set(true);
+        if (options.shouldHandleOneTimeToken === false ||
+            typeof location === "undefined")
+            return;
+        const url = new URL(location.href);
+        const ott = url.searchParams.get("ott");
+        if (!ott)
+            return;
+        url.searchParams.delete("ott");
+        await wrap((options.replaceURL ??
+            ((next) => history.replaceState({}, "", next)))(url));
+        try {
+            await wrap(completeSignIn(ott));
+        }
+        catch {
+            // Kept in `completeSignIn.error()`.
+        }
+    }, `${name}._start`);
+    const fetchToken = action(async ({ forceRefreshToken }) => {
+        const cached = token();
+        if (cached && !forceRefreshToken)
+            return cached;
+        const inFlight = peek(pending);
+        if (inFlight && !forceRefreshToken)
+            return await wrap(inFlight.request);
+        const request = authClient.convex
+            .token({ fetchOptions: { throw: false } })
+            .then(({ data }) => data?.token || null, () => null);
+        const box = { request };
+        pending.set(box);
+        try {
+            const value = await wrap(request);
+            token.set(value);
+            return value;
+        }
+        finally {
+            if (peek(pending) === box)
+                pending.set(null);
+        }
+    }, `${name}.fetchToken`);
+    return {
+        isLoading: computed(() => (state().isPending && token() === null) || !completeSignIn.ready(), `${name}.isLoading`),
+        data: computed(() => state().data, `${name}.data`),
+        // A token from server rendering stands in until the session loads.
+        session: computed(() => {
+            const id = state().data?.session?.id;
+            if (id)
+                return id;
+            return token() === null ? null : "initialToken";
+        }, `${name}.session`),
+        fetchToken,
+        token,
+        completeSignIn,
+    };
+}

package/dist/browser/reatom/convex_auth.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The `@reatomized/convex/convex-auth` entry: the client side of Convex Auth
+ * (`@convex-dev/auth`), whose own client ships only as a React provider.
+ *
+ * The `auth:signIn` action returns a JWT and a refresh token, trades a refresh
+ * token for a new pair, and for OAuth returns the provider's URL and a
+ * verifier; the backend sends the browser back with a `code` that, with the
+ * verifier, signs in. `auth:signOut` ends the server session. Storage keys and
+ * formats are `@convex-dev/auth/react`'s, so its sessions carry over.
+ */
+import { type Action, type AsyncExt, type AtomLike } from "@reatom/core";
+import type { Value } from "convex/values";
+import type { AuthProvider } from "./auth_state.js";
+import type { ReatomConvexClient } from "./client.js";
+export type { AuthProvider } from "./auth_state.js";
+/**
+ * `localStorage`, `sessionStorage`, or an async store such as React Native's
+ * AsyncStorage.
+ *
+ * @public
+ */
+export type ConvexAuthStorage = {
+    getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+};
+/** @public */
+export type ConvexAuthOptions = {
+    /** `localStorage` by default. */
+    storage?: ConvexAuthStorage;
+    /** Separates the keys of several deployments; the client's URL by default. */
+    storageNamespace?: string;
+    /**
+     * Whether a `code` query param on start is a Convex Auth sign-in code;
+     * `true` by default. Turn it off for pages where another library uses `code`.
+     */
+    shouldHandleCode?: boolean | (() => boolean);
+    /** Drops `code` from the address; `history.replaceState` by default. */
+    replaceURL?: (relativeUrl: string) => void | Promise<void>;
+    /** Sends the browser to an OAuth provider; `location.assign` by default. */
+    navigate?: (url: URL) => void | Promise<void>;
+};
+/** @public */
+export type ConvexAuthSignInResult = {
+    /** Tokens were issued and the session is starting. */
+    signingIn: boolean;
+    /** The OAuth provider's URL, after navigating to it. */
+    redirect?: URL;
+};
+/** @public */
+export type ReatomConvexAuth = AuthProvider & {
+    /** The current JWT, `null` when signed out. */
+    readonly token: AtomLike<string | null, []>;
+    /** A refresh token is being exchanged. */
+    readonly isRefreshingToken: AtomLike<boolean, []>;
+    /**
+     * Calls `auth:signIn`. `provider` is a provider id from convex/auth.ts, such
+     * as `"password"` or `"github"`; `params` are its fields, such as `email`,
+     * `password` and `flow`.
+     */
+    readonly signIn: Action<[
+        provider?: string | undefined,
+        params?: FormData | Record<string, Value> | undefined
+    ], Promise<ConvexAuthSignInResult>>;
+    /**
+     * Signs in with the `code` the backend sends the browser back with after
+     * OAuth; `true` when tokens were issued. Runs on start for a `code` in the
+     * URL; call it when the app takes the code from the URL itself. Its `error`
+     * holds a failed exchange.
+     */
+    readonly completeSignIn: Action<[code: string], Promise<boolean>> & AsyncExt<[code: string], boolean>;
+    /** Ends the session locally, even when `auth:signOut` fails. */
+    readonly signOut: Action<[], Promise<void>>;
+};
+/**
+ * A Convex Auth session for `reatomAuthState`. It restores the stored
+ * session, signs in with a `code` in the URL, follows other tabs, and runs one
+ * refresh token exchange at a time across tabs.
+ *
+ * ```ts
+ * const convexAuth = reatomConvexAuthProvider(convex);
+ * const auth = reatomAuthState(convex, convexAuth);
+ * await convexAuth.signIn("password", { email, password, flow: "signIn" });
+ * ```
+ *
+ * @public
+ */
+export declare function reatomConvexAuthProvider(convex: ReatomConvexClient, options?: ConvexAuthOptions, name?: string): ReatomConvexAuth;

package/dist/browser/reatom/convex_auth.js

@@ -0,0 +1,233 @@
+/**
+ * The `@reatomized/convex/convex-auth` entry: the client side of Convex Auth
+ * (`@convex-dev/auth`), whose own client ships only as a React provider.
+ *
+ * The `auth:signIn` action returns a JWT and a refresh token, trades a refresh
+ * token for a new pair, and for OAuth returns the provider's URL and a
+ * verifier; the backend sends the browser back with a `code` that, with the
+ * verifier, signs in. `auth:signOut` ends the server session. Storage keys and
+ * formats are `@convex-dev/auth/react`'s, so its sessions carry over.
+ */
+import { action, atom, computed, peek, withAsync, withConnectHook, wrap, } from "@reatom/core";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { jwtDecode } from "../../vendor/jwt-decode/index.js";
+const JWT_KEY = "__convexAuthJWT";
+const REFRESH_TOKEN_KEY = "__convexAuthRefreshToken";
+const VERIFIER_KEY = "__convexAuthOAuthVerifier";
+// Retry delays for a code or refresh token exchange that hits a network error.
+const RETRY_BACKOFF = [500, 2000];
+const RETRY_JITTER = 100;
+const signInRef = makeFunctionReference("auth:signIn");
+const signOutRef = makeFunctionReference("auth:signOut");
+/**
+ * A Convex Auth session for `reatomAuthState`. It restores the stored
+ * session, signs in with a `code` in the URL, follows other tabs, and runs one
+ * refresh token exchange at a time across tabs.
+ *
+ * ```ts
+ * const convexAuth = reatomConvexAuthProvider(convex);
+ * const auth = reatomAuthState(convex, convexAuth);
+ * await convexAuth.signIn("password", { email, password, flow: "signIn" });
+ * ```
+ *
+ * @public
+ */
+export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.name}.convexAuth`) {
+    const namespace = (options.storageNamespace ?? convex.url).replace(/[^a-zA-Z0-9]/g, "");
+    const key = (base) => `${base}_${namespace}`;
+    const storage = () => {
+        const value = options.storage ??
+            (typeof localStorage === "undefined" ? undefined : localStorage);
+        if (!value)
+            throw new Error("`localStorage` is not available, pass `storage` to reatomConvexAuthProvider");
+        return value;
+    };
+    const read = (base) => wrap(storage().getItem(key(base)));
+    const write = (base, value) => wrap(value === null
+        ? storage().removeItem(key(base))
+        : storage().setItem(key(base), value));
+    const token = atom(null, `${name}.token`).extend(withConnectHook(() => {
+        void start();
+        const stopFollowing = followStorage();
+        const stopWarning = warnOnUnload();
+        return () => {
+            stopFollowing?.();
+            stopWarning?.();
+        };
+    }));
+    const restoring = atom(true, `${name}._restoring`).extend(withConnectHook(() => {
+        void start();
+    }));
+    const isRefreshingToken = atom(false, `${name}.isRefreshingToken`);
+    const started = atom(false, `${name}._started`);
+    // `sub` is `userId|sessionId`, so a refreshed token keeps the session.
+    const session = computed(() => {
+        const value = token();
+        if (value === null)
+            return null;
+        try {
+            const { sub } = jwtDecode(value);
+            return sub ?? value;
+        }
+        catch {
+            return value;
+        }
+    }, `${name}.session`);
+    const apply = (value) => {
+        token.set(value);
+        restoring.set(false);
+    };
+    const store = async (tokens) => {
+        await write(JWT_KEY, tokens?.token ?? null);
+        await write(REFRESH_TOKEN_KEY, tokens?.refreshToken ?? null);
+        apply(tokens?.token ?? null);
+    };
+    // Over HTTP: the client asks for a fresh token while its socket is paused
+    // or stopped for auth.
+    const exchange = async (args) => {
+        for (let retry = 0;; retry++) {
+            try {
+                return await wrap(new ConvexHttpClient(convex.url, { logger: false }).action(signInRef, args));
+            }
+            catch (error) {
+                // fetch rejects with a TypeError when the request doesn't go through.
+                if (!(error instanceof TypeError) || retry >= RETRY_BACKOFF.length)
+                    throw error;
+                const delay = RETRY_BACKOFF[retry] + RETRY_JITTER * Math.random();
+                await wrap(new Promise((resolve) => setTimeout(resolve, delay)));
+            }
+        }
+    };
+    const signIn = action(async (provider, params) => {
+        const fields = params instanceof FormData
+            ? Object.fromEntries(Array.from(params.entries(), ([field, value]) => [
+                field,
+                typeof value === "string" ? value : value.name,
+            ]))
+            : (params ?? {});
+        const verifier = (await read(VERIFIER_KEY)) ?? undefined;
+        await write(VERIFIER_KEY, null);
+        const result = await wrap(convex.action(signInRef, { provider, params: fields, verifier }));
+        if (result.redirect !== undefined) {
+            const url = new URL(result.redirect);
+            await write(VERIFIER_KEY, result.verifier ?? null);
+            await wrap((options.navigate ?? ((target) => location.assign(target)))(url));
+            return { signingIn: false, redirect: url };
+        }
+        if (result.tokens !== undefined) {
+            await wrap(store(result.tokens));
+            return { signingIn: result.tokens !== null };
+        }
+        return { signingIn: false };
+    }, `${name}.signIn`);
+    const completeSignIn = action(async (code) => {
+        const { signingIn } = await wrap(signIn(undefined, { code }));
+        return signingIn;
+    }, `${name}.completeSignIn`).extend(withAsync());
+    const isLoading = computed(() => restoring() || !completeSignIn.ready(), `${name}.isLoading`);
+    const signOut = action(async () => {
+        try {
+            await wrap(convex.action(signOutRef, {}));
+        }
+        catch {
+            // Usually the session has already ended on the server.
+        }
+        await wrap(store(null));
+    }, `${name}.signOut`);
+    const refresh = async (before) => {
+        // Another tab refreshed while this one waited for the lock.
+        if (peek(token) !== before)
+            return peek(token);
+        const refreshToken = (await read(REFRESH_TOKEN_KEY)) ?? null;
+        if (refreshToken === null)
+            return null;
+        isRefreshingToken.set(true);
+        try {
+            const { tokens } = await wrap(exchange({ refreshToken }));
+            await wrap(store(tokens ?? null));
+        }
+        finally {
+            isRefreshingToken.set(false);
+        }
+        return peek(token);
+    };
+    const fetchToken = action(async ({ forceRefreshToken }) => {
+        const before = token();
+        if (!forceRefreshToken)
+            return before;
+        return await wrap(exclusive(key(REFRESH_TOKEN_KEY), wrap(() => refresh(before))));
+    }, `${name}.fetchToken`);
+    const start = action(async () => {
+        if (peek(started))
+            return;
+        started.set(true);
+        const handleCode = typeof options.shouldHandleCode === "function"
+            ? options.shouldHandleCode()
+            : (options.shouldHandleCode ?? true);
+        const url = typeof location === "undefined" ? undefined : new URL(location.href);
+        const code = url?.searchParams.get("code");
+        if (url && code && handleCode) {
+            url.searchParams.delete("code");
+            await wrap((options.replaceURL ??
+                ((relative) => history.replaceState({}, "", relative)))(url.pathname + url.search + url.hash));
+            try {
+                await wrap(completeSignIn(code));
+            }
+            catch {
+                // Kept in `completeSignIn.error()`.
+            }
+            finally {
+                restoring.set(false);
+            }
+            return;
+        }
+        apply((await read(JWT_KEY)) ?? null);
+    }, `${name}._start`);
+    // Follows the token other tabs or frames write to the same storage.
+    const followStorage = () => {
+        if (typeof window === "undefined")
+            return undefined;
+        const listener = wrap((event) => {
+            if (event.storageArea !== storage() || event.key !== key(JWT_KEY))
+                return;
+            // Each key comes as its own event; the refresh token stays in storage.
+            apply(event.newValue);
+        });
+        window.addEventListener("storage", listener);
+        return () => window.removeEventListener("storage", listener);
+    };
+    // Leaving during a refresh token exchange can lose the new pair.
+    const warnOnUnload = () => {
+        if (typeof window === "undefined")
+            return undefined;
+        const listener = wrap((event) => {
+            if (!peek(isRefreshingToken))
+                return;
+            event.preventDefault();
+            event.returnValue = true;
+        });
+        window.addEventListener("beforeunload", listener);
+        return () => window.removeEventListener("beforeunload", listener);
+    };
+    return {
+        isLoading,
+        session,
+        fetchToken,
+        token,
+        isRefreshingToken,
+        signIn,
+        completeSignIn,
+        signOut,
+    };
+}
+const queues = new Map();
+/** Runs `callback` alone among the tabs, or among callers in this one. */
+function exclusive(lock, callback) {
+    if (typeof navigator !== "undefined" && navigator.locks)
+        return navigator.locks.request(lock, callback);
+    const previous = queues.get(lock) ?? Promise.resolve();
+    const next = previous.then(callback, callback);
+    queues.set(lock, next.catch(() => { }));
+    return next;
+}

package/dist/browser/reatom/index.d.ts

@@ -1,6 +1,8 @@
 export { reatomConvexClient } from "./client.js";
 export type { BaseConvexClientOptions as ReatomConvexClientOptions, ConnectionState, MutationOptions, QueryModification, QueryStatus, ReatomConvexClient, ReatomQuery, ReatomQueryOptions, Transition, } from "./client.js";
 export type { AuthTokenFetcher } from "./auth.js";
+export { reatomAuthState } from "./auth_state.js";
+export type { AuthProvider, AuthStatus, ReatomAuthState, } from "./auth_state.js";
 export type { PaginatedQueryState, ReatomPaginatedQuery } from "./paginated.js";
 export type { SocketState } from "./socket.js";
 export type { OptimisticLocalStore } from "convex/browser";

package/dist/browser/reatom/index.js

@@ -1,2 +1,3 @@
 // The entry point of the @reatomized/convex package, built by scripts/build.mjs.
 export { reatomConvexClient } from "./client.js";
+export { reatomAuthState } from "./auth_state.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reatomized/convex",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "A Convex sync client with its state in Reatom atoms",
   "keywords": [
     "convex",
@@ -25,6 +25,14 @@
       "types": "./dist/browser/reatom/index.d.ts",
       "default": "./dist/browser/reatom/index.js"
     },
+    "./convex-auth": {
+      "types": "./dist/browser/reatom/convex_auth.d.ts",
+      "default": "./dist/browser/reatom/convex_auth.js"
+    },
+    "./better-auth": {
+      "types": "./dist/browser/reatom/better_auth.d.ts",
+      "default": "./dist/browser/reatom/better_auth.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [