use-convex 1.2.0 → 2.0.0

package/dist/runtime/auth/oauth.js

@@ -0,0 +1,170 @@
+import { getFunctionName, makeFunctionReference } from "convex/server";
+export const OAUTH_CODE_PARAM = "convexAuthCode";
+export const OAUTH_ERROR_PARAM = "convexAuthError";
+export const OAUTH_SETUP_ID = "oauth";
+export const OAUTH_ACTIONS_KEY = "actions";
+export const OAUTH_FLOW_ERROR_KEY = "flowError";
+const OAUTH_FLOW_STORAGE_KEY = "flow";
+const RETRY_BACKOFF = [500, 2e3];
+function isNetworkError(error) {
+  return error instanceof TypeError && /network|failed to fetch|load failed/i.test(error.message);
+}
+async function retryOnNetworkError(fn) {
+  for (const backoff of RETRY_BACKOFF) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (!isNetworkError(error)) {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, backoff + 100 * Math.random()));
+    }
+  }
+  return await fn();
+}
+function callbackFlowError(param) {
+  switch (param) {
+    case "access_denied":
+      return { error: "ACCESS_DENIED" };
+    case "expired":
+      return { error: "EXPIRED" };
+    default:
+      return { error: "OTHER_ERROR", cause: param };
+  }
+}
+function currentHref() {
+  if (typeof window === "undefined" || window.location === void 0) {
+    return null;
+  }
+  return window.location.href;
+}
+async function takePendingFlow(storage) {
+  const raw = await storage.get(OAUTH_FLOW_STORAGE_KEY);
+  await storage.remove(OAUTH_FLOW_STORAGE_KEY);
+  if (raw === null || raw === void 0) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.providerName !== "string" || typeof parsed.state !== "string" || typeof parsed.completeSignIn !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function dropPendingFlow(storage) {
+  try {
+    await storage.remove(OAUTH_FLOW_STORAGE_KEY);
+  } catch {
+  }
+}
+export function convexOAuth(options = {}) {
+  const setup = (ctx) => {
+    const { values, signInApi, convex, replaceUrl } = ctx;
+    const flowStorage = options.flowStorage;
+    const suffix = (options.namespace ?? "").replace(/[^a-z0-9]/gi, "");
+    const flowKey = (key) => `__convexAuthOAuth_${key}_${suffix}`;
+    const storage = flowStorage ? {
+      get: (key) => flowStorage.getItem(flowKey(key)),
+      set: (key, value) => flowStorage.setItem(flowKey(key), value),
+      remove: (key) => flowStorage.removeItem(flowKey(key))
+    } : ctx.storage;
+    const client = ctx.client;
+    const setFlowError = (flowError) => {
+      values.set(OAUTH_FLOW_ERROR_KEY, flowError);
+    };
+    const redeem = async (code) => {
+      try {
+        const pending = await takePendingFlow(storage);
+        if (pending === null) {
+          return { status: "error", userError: { error: "INVALID_FLOW" } };
+        }
+        const completeSignIn = makeFunctionReference(pending.completeSignIn);
+        const result = await retryOnNetworkError(
+          () => signInApi.mutation(completeSignIn, { code, state: pending.state })
+        );
+        if (result.status === "error") {
+          return { status: "error", userError: { error: "EXPIRED" } };
+        }
+        await client.setSession(result.tokens);
+        return { status: "complete" };
+      } catch (cause) {
+        return { status: "error", userError: { error: "OTHER_ERROR", cause } };
+      }
+    };
+    const handleCallback = () => {
+      const href = currentHref();
+      if (href === null) {
+        return;
+      }
+      const url = new URL(href);
+      const code = url.searchParams.get(OAUTH_CODE_PARAM);
+      const errorParam = url.searchParams.get(OAUTH_ERROR_PARAM);
+      if (code === null && errorParam === null) {
+        return;
+      }
+      url.searchParams.delete(OAUTH_CODE_PARAM);
+      url.searchParams.delete(OAUTH_ERROR_PARAM);
+      replaceUrl(url.toString());
+      if (errorParam !== null) {
+        void dropPendingFlow(storage);
+        setFlowError(callbackFlowError(errorParam));
+        return;
+      }
+      if (code === null) {
+        return;
+      }
+      void client.withSignInPending(async () => {
+        const result = await redeem(code);
+        if (result.status === "error") {
+          setFlowError(result.userError);
+        }
+      });
+    };
+    const signIn = async (refs, options2) => {
+      const code = options2?.code;
+      if (code !== void 0) {
+        setFlowError(null);
+        return await client.withSignInPending(() => redeem(code));
+      }
+      const href = currentHref();
+      const redirectTo = options2?.redirectTo ?? href;
+      if (redirectTo === null) {
+        throw new Error("`redirectTo` is required where there is no current page URL.");
+      }
+      setFlowError(null);
+      try {
+        const { redirect, state } = await convex.mutation(
+          refs.startSignIn,
+          {
+            redirectTo
+          }
+        );
+        await storage.set(
+          OAUTH_FLOW_STORAGE_KEY,
+          JSON.stringify({
+            providerName: refs.providerName,
+            state,
+            completeSignIn: getFunctionName(refs.completeSignIn)
+          })
+        );
+        const url = new URL(redirect);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+          throw new Error("OAuth redirect must be http(s)");
+        }
+        if (href !== null) {
+          window.location.href = url.toString();
+        }
+        return { status: "redirect", redirect: url };
+      } catch (cause) {
+        return { status: "error", userError: { error: "OTHER_ERROR", cause } };
+      }
+    };
+    values.set(OAUTH_ACTIONS_KEY, { signIn });
+    setFlowError(null);
+    return { onInit: handleCallback };
+  };
+  return { id: OAUTH_SETUP_ID, setup };
+}

package/dist/runtime/auth/sessionRoutes.d.ts

@@ -0,0 +1,37 @@
+/** Client side of the Nitro Convex Auth routes (SSR mode). */
+export type AuthSessionResponse = {
+    tokens: {
+        accessToken: string;
+        userId: string;
+    } | null;
+};
+/**
+ * POST to the SSR refresh / sign-out route.
+ *
+ * Accepts a 2xx `{ tokens }` body, and the documented 401 `{ tokens: null }`
+ * for a dead session. Anything else (a proxy's HTML 502, a 403 origin
+ * refusal, a malformed body) throws, so a temporary outage is not mistaken
+ * for "signed out" and the stored session is kept for the next attempt.
+ */
+export declare function postAuth(route: string): Promise<AuthSessionResponse>;
+type TokenFetcher = (args: {
+    forceRefreshToken: boolean;
+}) => Promise<string | null | undefined>;
+/**
+ * Wrap a token fetcher so it never rejects.
+ *
+ * `ConvexClient` does not catch a throwing fetcher: a refresh that fails
+ * during an outage would leave the socket paused with no further refresh
+ * scheduled. Instead, retry with capped exponential backoff until the
+ * refresh gives a real answer (a token, or `null` for "no session"), and
+ * stop early once the session is gone locally (e.g. the user signed out).
+ */
+export declare function retryingTokenFetcher(fetchToken: TokenFetcher, options: {
+    hasSession: () => boolean;
+    onRetry?: (error: unknown, delayMs: number) => void;
+    sleep?: (ms: number) => Promise<void>;
+    maxDelayMs?: number;
+}): (args: {
+    forceRefreshToken: boolean;
+}) => Promise<string | null>;
+export {};

package/dist/runtime/auth/sessionRoutes.js

@@ -0,0 +1,41 @@
+function isSessionResponse(body) {
+  if (typeof body !== "object" || body === null || !("tokens" in body)) {
+    return false;
+  }
+  const tokens = body.tokens;
+  return tokens === null || typeof tokens === "object" && typeof tokens.accessToken === "string" && typeof tokens.userId === "string";
+}
+export async function postAuth(route) {
+  const res = await fetch(route, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: "{}",
+    credentials: "same-origin"
+  });
+  const body = await res.json().catch(() => void 0);
+  if (isSessionResponse(body) && (res.ok || res.status === 401 && body.tokens === null)) {
+    return body;
+  }
+  throw new Error(`[use-convex] ${route} failed with ${res.status}`);
+}
+export function retryingTokenFetcher(fetchToken, options) {
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const maxDelayMs = options.maxDelayMs ?? 3e4;
+  return async (args) => {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await fetchToken(args) ?? null;
+      } catch (error) {
+        if (!options.hasSession()) {
+          return null;
+        }
+        const delayMs = Math.min(1e3 * 2 ** attempt, maxDelayMs);
+        options.onRetry?.(error, delayMs);
+        await sleep(delayMs);
+        if (!options.hasSession()) {
+          return null;
+        }
+      }
+    }
+  };
+}

package/dist/runtime/composables/useAuth.d.ts

@@ -1,60 +1,93 @@
+import type { FunctionArgs, FunctionReference, FunctionReturnType } from 'convex/server';
 import { type ComputedRef, type Ref } from 'vue';
-export type AuthTokens = {
-    token: string;
-    refreshToken: string;
+import { type UseConvexAuthReturn } from './useConvexAuth.js';
+import { type OAuthCompleteResult, type OAuthFlowError, type OAuthProviderRefs, type OAuthSignInOptions, type OAuthStartResult } from '../auth/oauth.js';
+export type { OAuthCompleteResult, OAuthFlowError, OAuthProviderRefs, OAuthSignInOptions, OAuthStartResult, } from '../auth/oauth.js';
+/** The session a method's sign-in returns (`TokenBundle` / `SlimTokenBundle`). */
+export type ConvexAuthSession = {
+    accessToken: string;
+    userId: string;
+    refreshToken?: string;
+    refreshTokenExpiresAt?: number;
 };
-export type SignInResult = {
-    signingIn: boolean;
-    redirect?: URL;
+/**
+ * The shared sign-in envelope every Convex Auth v2 sign-in function returns,
+ * widened with the `OTHER_ERROR` arm for thrown errors.
+ */
+export type ConvexSignInResult<Result> = Result | {
+    status: 'error';
+    userError: {
+        error: 'OTHER_ERROR';
+        cause: unknown;
+    };
 };
-export interface UseAuthReturn {
-    isLoading: ComputedRef<boolean>;
-    isAuthenticated: ComputedRef<boolean>;
-    isRefreshing: ComputedRef<boolean>;
-    /**
-     * JWT cookie is present. Use with `isAuthenticated` to keep an SSR-gated
-     * shell mounted while Convex confirms — do not live-subscribe on this alone.
-     */
-    hasSsrSession: ComputedRef<boolean>;
-    /**
-     * Mount the signed-in shell when the SSR cookie is present **or** Convex
-     * has confirmed auth. Prefer this over `isAuthenticated` alone.
-     * Live subscriptions must still gate on `isAuthenticated`.
-     */
-    showAuthedUi: ComputedRef<boolean>;
-    error: Ref<string | null>;
-    pending: Ref<boolean>;
-    signIn: typeof signIn;
-    signOut: typeof signOut;
+export interface UseAuthReturn extends UseConvexAuthReturn {
+    /** Current access token (JWT), or null. Short-lived — don't persist it. */
+    token: ComputedRef<string | null>;
+    /** Adopt a session returned by a method's sign-in function. */
+    setSession: (session: ConvexAuthSession) => Promise<void>;
+    /** Revoke the session on the server and clear it locally. */
+    signOut: () => Promise<void>;
 }
 /**
- * First-party Convex Auth session state + actions.
- *
- * Only auto-imported when `convex.auth.provider === 'convex-auth'`.
- * Wire-up happens in `plugin.auth.client` — call `signIn` / `signOut` from forms.
+ * Convex Auth v2 session state and actions (React `useAuthActions` +
+ * `useConvexAuth` parity): `isLoading`, `isAuthenticated`, `isRefreshing`,
+ * `hasSsrSession`, `showAuthedUi`, `token`, `setSession`, `signOut`. Sign in with {@link useConvexSignIn} or
+ * {@link useOAuthSignIn}.
  */
 export declare function useAuth(): UseAuthReturn;
+/** Revoke the current Convex Auth session and clear it locally. */
+export declare function signOut(): Promise<void>;
+/**
+ * Run any Convex Auth v2 sign-in function (username/email + password
+ * sign-in or sign-up, anonymous, …) and adopt the session it returns.
+ *
+ * In SSR mode the call goes through the Nitro auth proxy, so the function
+ * must be listed in `convex.auth.signIn`.
+ *
+ * @example
+ * ```ts
+ * const { run: signIn, pending } = useConvexSignIn(api.auth.signInWithUsernamePassword)
+ * const result = await signIn({ username, password })
+ * if (result.status === 'error') showError(result.userError)
+ * ```
+ */
+export declare function useConvexSignIn<Fn extends FunctionReference<'mutation' | 'action', 'public'>>(fn: Fn, options?: {
+    /**
+     * `FunctionReference` kinds are type-only, so say when the sign-in
+     * function is an action. Convex Auth's built-in methods use mutations.
+     * @default 'mutation'
+     */
+    kind?: 'mutation' | 'action';
+}): {
+    run: (args: FunctionArgs<Fn>) => Promise<ConvexSignInResult<FunctionReturnType<Fn>>>;
+    pending: Readonly<Ref<boolean>>;
+};
 /**
- * Sign in with a Convex Auth provider (password, OAuth, OTP, …).
- * Mirrors `@convex-dev/auth/react` `useAuthActions().signIn`.
+ * OAuth state not tied to one provider: `flowError` explains why the last
+ * redirect-back failed, on whichever page the provider returned to.
  */
-export declare function signIn(provider?: string, params?: FormData | Record<string, string>): Promise<SignInResult>;
+export declare function useOAuth(): {
+    flowError: Readonly<Ref<OAuthFlowError | null>>;
+};
 /**
- * Sign out and clear local tokens + SSR JWT cookie.
+ * Start a provider's OAuth flow (navigates to the provider), or finish one
+ * started elsewhere with `{ code }`.
+ *
+ * @example
+ * ```ts
+ * const { signIn } = useOAuthSignIn({
+ *   providerName: 'github',
+ *   startSignIn: api.auth.startSignInWithGithub,
+ *   completeSignIn: api.auth.completeSignInWithGithub,
+ * })
+ * ```
  */
-export declare function signOut(): Promise<void>;
-/** @internal */
-export declare function hydrateAuthFromStorage(): void;
-/** @internal */
-export declare function getAuthToken({ forceRefreshToken, }: {
-    forceRefreshToken: boolean;
-}): Promise<string | null>;
-/** @internal */
-export declare function hasPendingOAuthCallback(): boolean;
-/** @internal */
-export declare function consumeOAuthCodeFromUrl(): Promise<boolean>;
-/** @internal */
-export declare function useAuthProviderState(): {
-    isLoading: ComputedRef<boolean>;
-    hasSession: ComputedRef<boolean>;
+export declare function useOAuthSignIn(refs: OAuthProviderRefs): {
+    signIn: {
+        (options: OAuthSignInOptions & {
+            code: string;
+        }): Promise<OAuthCompleteResult>;
+        (options?: Omit<OAuthSignInOptions, 'code'>): Promise<OAuthStartResult>;
+    };
 };