@reatomized/convex 0.2.0 → 0.3.0

package/README.md

@@ -83,6 +83,8 @@ await convexAuth.signOut();
 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
@@ -104,7 +106,9 @@ 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. Neither entry point adds dependencies.
+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

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

@@ -4,17 +4,18 @@
  * `ConvexBetterAuthProvider`. Sign in and out through the better-auth client
  * itself; its session store tells this provider.
  */
-import { type AtomLike } from "@reatom/core";
+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;
+        } | 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()`
@@ -35,8 +36,8 @@ export type BetterAuthClient = {
             };
         }): Promise<{
             data?: {
-                token?: string | null;
-            } | null;
+                token?: string | null | undefined;
+            } | null | undefined;
         }>;
     };
     getSession(options?: {
@@ -52,8 +53,11 @@ export type BetterAuthClient = {
                 data?: {
                     session?: {
                         token: string;
-                    } | null;
-                } | null;
+                    } | null | undefined;
+                } | null | undefined;
+                error?: {
+                    message?: string | undefined;
+                } | null | undefined;
             }>;
         };
     };
@@ -63,13 +67,26 @@ export type BetterAuthClient = {
 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 = AuthProvider & {
+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
@@ -86,4 +103,4 @@ export type ReatomBetterAuth = AuthProvider & {
  *
  * @public
  */
-export declare function reatomBetterAuthProvider(authClient: BetterAuthClient, options?: BetterAuthOptions, name?: string): ReatomBetterAuth;
+export declare function reatomBetterAuthProvider<Client extends BetterAuthClient>(authClient: Client, options?: BetterAuthOptions, name?: string): ReatomBetterAuth<SessionData<Client>>;

package/dist/browser/reatom/better_auth.js

@@ -4,7 +4,7 @@
  * `ConvexBetterAuthProvider`. Sign in and out through the better-auth client
  * itself; its session store tells this provider.
  */
-import { action, atom, computed, peek, withConnectHook, wrap, } from "@reatom/core";
+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.
@@ -25,15 +25,37 @@ export function reatomBetterAuthProvider(authClient, options = {}, name = "bette
     // 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 verifyOneTimeToken();
+        void start();
         return authClient.useSession.subscribe(wrap((value) => {
+            const previous = peek(target).data?.session?.id;
             target.set(value);
-            if (!value.data && !value.isPending)
+            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 verifyOneTimeToken = action(async () => {
-        if (typeof location === "undefined" || !authClient.crossDomain)
+    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");
@@ -42,15 +64,13 @@ export function reatomBetterAuthProvider(authClient, options = {}, name = "bette
         url.searchParams.delete("ott");
         await wrap((options.replaceURL ??
             ((next) => history.replaceState({}, "", next)))(url));
-        const result = await wrap(authClient.crossDomain.oneTimeToken.verify({ token: ott }));
-        const session = result.data?.session;
-        if (!session)
-            return;
-        await wrap(authClient.getSession({
-            fetchOptions: { headers: { Authorization: `Bearer ${session.token}` } },
-        }));
-        authClient.updateSession?.();
-    }, `${name}._verifyOneTimeToken`);
+        try {
+            await wrap(completeSignIn(ott));
+        }
+        catch {
+            // Kept in `completeSignIn.error()`.
+        }
+    }, `${name}._start`);
     const fetchToken = action(async ({ forceRefreshToken }) => {
         const cached = token();
         if (cached && !forceRefreshToken)
@@ -74,7 +94,8 @@ export function reatomBetterAuthProvider(authClient, options = {}, name = "bette
         }
     }, `${name}.fetchToken`);
     return {
-        isLoading: computed(() => state().isPending && token() === null, `${name}.isLoading`),
+        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;
@@ -84,5 +105,6 @@ export function reatomBetterAuthProvider(authClient, options = {}, name = "bette
         }, `${name}.session`),
         fetchToken,
         token,
+        completeSignIn,
     };
 }

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

@@ -8,7 +8,7 @@
  * 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 AtomLike } from "@reatom/core";
+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";
@@ -62,6 +62,13 @@ export type ReatomConvexAuth = AuthProvider & {
         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>>;
 };

package/dist/browser/reatom/convex_auth.js

@@ -8,7 +8,7 @@
  * 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, withConnectHook, wrap, } from "@reatom/core";
+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";
@@ -56,7 +56,7 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
             stopWarning?.();
         };
     }));
-    const isLoading = atom(true, `${name}.isLoading`).extend(withConnectHook(() => {
+    const restoring = atom(true, `${name}._restoring`).extend(withConnectHook(() => {
         void start();
     }));
     const isRefreshingToken = atom(false, `${name}.isRefreshingToken`);
@@ -76,7 +76,7 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
     }, `${name}.session`);
     const apply = (value) => {
         token.set(value);
-        isLoading.set(false);
+        restoring.set(false);
     };
     const store = async (tokens) => {
         await write(JWT_KEY, tokens?.token ?? null);
@@ -121,6 +121,11 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
         }
         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, {}));
@@ -167,10 +172,13 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
             await wrap((options.replaceURL ??
                 ((relative) => history.replaceState({}, "", relative)))(url.pathname + url.search + url.hash));
             try {
-                await wrap(signIn(undefined, { code }));
+                await wrap(completeSignIn(code));
+            }
+            catch {
+                // Kept in `completeSignIn.error()`.
             }
             finally {
-                isLoading.set(false);
+                restoring.set(false);
             }
             return;
         }
@@ -209,6 +217,7 @@ export function reatomConvexAuthProvider(convex, options = {}, name = `${convex.
         token,
         isRefreshingToken,
         signIn,
+        completeSignIn,
         signOut,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reatomized/convex",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A Convex sync client with its state in Reatom atoms",
   "keywords": [
     "convex",