@robelest/convex-auth 0.0.3-preview → 0.0.3-preview.3

package/src/client/index.ts

@@ -1,10 +1,22 @@
 import { ConvexHttpClient } from "convex/browser";
-import { Value } from "convex/values";
+import { ConvexError, Value } from "convex/values";
+
+// Re-export error utilities so consumers can import from `@robelest/convex-auth/client`.
+export {
+  isAuthError,
+  parseAuthError,
+  AUTH_ERRORS,
+  type AuthErrorCode,
+} from "../server/errors.js";
 
 /**
  * Structural interface for any Convex client.
- * Satisfied by both `ConvexClient` (`convex/browser`) and
- * `ConvexReactClient` (`convex/react`).
+ * Satisfied by `ConvexClient` (`convex/browser`),
+ * `ConvexReactClient` (`convex/react`), and similar transports.
+ *
+ * `clearAuth` is present on `ConvexReactClient` and `BaseConvexClient`
+ * but not on the simplified `ConvexClient`. When available we call it
+ * during sign-out for a clean deauthentication.
  */
 interface ConvexTransport {
   action(action: any, args: any): Promise<any>;
@@ -14,7 +26,7 @@ interface ConvexTransport {
     }) => Promise<string | null | undefined>,
     onChange?: (isAuthenticated: boolean) => void,
   ): void;
-  clearAuth(): void;
+  clearAuth?(): void;
 }
 
 /** Pluggable key-value storage (defaults to `localStorage`). */
@@ -31,17 +43,32 @@ type AuthSession = {
   refreshToken: string;
 };
 
-type SignInResult = {
+/**
+ * Result of a `signIn` call.
+ *
+ * - `signingIn: true` — credentials were accepted and the user is authenticated.
+ * - `redirect` — OAuth flow initiated; redirect the user to `redirect.toString()`.
+ * - `totpRequired` — credentials valid but 2FA is needed; call `auth.totp.verify()`.
+ * - `verifier` — opaque string for multi-step flows (TOTP, passkey).
+ */
+export type SignInResult = {
+  /** `true` when sign-in completed and the user is authenticated. */
   signingIn: boolean;
+  /** OAuth redirect URL. Present when the provider requires a browser redirect. */
   redirect?: URL;
+  /** `true` when the account has TOTP enabled and a code is required. */
   totpRequired?: boolean;
+  /** Opaque verifier for multi-step flows (pass to `totp.verify` or passkey phase 2). */
   verifier?: string;
 };
 
 /** Reactive auth state snapshot returned by `auth.state` and `auth.onChange`. */
 export type AuthState = {
+  /** `true` during initial hydration before the first token is resolved. */
   isLoading: boolean;
+  /** `true` when a valid JWT exists (user is signed in). */
   isAuthenticated: boolean;
+  /** The raw JWT string, or `null` when not authenticated. */
   token: string | null;
 };
 
@@ -110,14 +137,17 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
 /**
  * Create a framework-agnostic auth client.
  *
+ * Returns an object with `signIn`, `signOut`, `onChange`, `state`,
+ * `passkey`, and `totp` — everything needed for client-side auth.
+ *
  * ### SPA mode (default)
  *
  * ```ts
- * import { ConvexClient } from 'convex/browser'
- * import { client } from '\@robelest/convex-auth/client'
+ * import { ConvexClient } from 'convex/browser';
+ * import { client } from '@robelest/convex-auth/client';
  *
- * const convex = new ConvexClient(CONVEX_URL)
- * const auth = client({ convex })
+ * const convex = new ConvexClient(CONVEX_URL);
+ * const auth = client({ convex });
  * ```
  *
  * ### SSR / proxy mode
@@ -126,13 +156,16 @@ function resolveUrl(convex: ConvexTransport, explicit?: string): string {
  * const auth = client({
  *   convex,
  *   proxy: '/api/auth',
- *   initialToken: tokenFromServer, // read from httpOnly cookie during SSR
- * })
+ *   token: tokenFromServer, // JWT read from httpOnly cookie during SSR
+ * });
  * ```
  *
  * In proxy mode all auth operations go through the proxy URL.
  * Tokens are stored in httpOnly cookies server-side — the client
- * only holds the JWT in memory.
+ * holds the JWT in memory only.
+ *
+ * @param options - Client configuration. See {@link ClientOptions}.
+ * @returns Auth client with `signIn`, `signOut`, `onChange`, `state`, `passkey`, and `totp`.
  */
 export function client(options: ClientOptions) {
   const { convex, proxy } = options;
@@ -266,9 +299,19 @@ export function client(options: ClientOptions) {
       body: JSON.stringify(body),
     });
     if (!response.ok) {
-      const error = await response.json().catch(() => ({}));
+      const errorBody = await response.json().catch(() => ({} as Record<string, unknown>));
+      // Reconstruct ConvexError when the proxy forwards structured auth error data.
+      if (
+        typeof errorBody === "object" &&
+        errorBody !== null &&
+        "authError" in errorBody &&
+        typeof (errorBody as Record<string, unknown>).authError === "object"
+      ) {
+        throw new ConvexError((errorBody as Record<string, unknown>).authError as Value);
+      }
       throw new Error(
-        (error as any).error ?? `Proxy request failed: ${response.status}`,
+        (errorBody as Record<string, unknown>).error as string ??
+          `Proxy request failed: ${response.status}`,
       );
     }
     return response.json();
@@ -319,6 +362,33 @@ export function client(options: ClientOptions) {
   // signIn
   // ---------------------------------------------------------------------------
 
+  /**
+   * Sign in with a provider.
+   *
+   * @param provider - Provider ID (e.g. `"email"`, `"password"`, `"google"`).
+   *   Omit when exchanging an OAuth code (the code carries the provider info).
+   * @param args - Provider-specific arguments. Pass a `Record<string, Value>`
+   *   or `FormData`. Common fields: `email`, `password`, `code`, `redirectTo`.
+   * @returns A {@link SignInResult} indicating the outcome.
+   *
+   * @example Email magic link
+   * ```ts
+   * await auth.signIn('email', { email: 'user@example.com' });
+   * ```
+   *
+   * @example Password
+   * ```ts
+   * const result = await auth.signIn('password', { email, password, flow: 'signIn' });
+   * if (result.totpRequired) {
+   *   await auth.totp.verify({ code: totpCode, verifier: result.verifier! });
+   * }
+   * ```
+   *
+   * @example OAuth (triggers redirect)
+   * ```ts
+   * await auth.signIn('google'); // redirects to Google
+   * ```
+   */
   const signIn = async (
     provider?: string,
     args?: FormData | Record<string, Value>,
@@ -397,6 +467,13 @@ export function client(options: ClientOptions) {
   // signOut
   // ---------------------------------------------------------------------------
 
+  /**
+   * Sign out the current user.
+   *
+   * Invalidates the server session and clears local token state.
+   * Errors are silently caught — calling `signOut` on an already
+   * signed-out user is a no-op.
+   */
   const signOut = async () => {
     if (proxy) {
       try {
@@ -405,6 +482,7 @@ export function client(options: ClientOptions) {
         // Already signed out is fine.
       }
       await setToken({ shouldStore: false, tokens: null });
+      if (convex.clearAuth) convex.clearAuth();
       return;
     }
 
@@ -415,6 +493,7 @@ export function client(options: ClientOptions) {
       // Already signed out is fine.
     }
     await setToken({ shouldStore: true, tokens: null });
+    if (convex.clearAuth) convex.clearAuth();
   };
 
   // ---------------------------------------------------------------------------
@@ -509,12 +588,15 @@ export function client(options: ClientOptions) {
   // ---------------------------------------------------------------------------
 
   /**
-   * Subscribe to auth state changes. Immediately invokes the callback
-   * with the current state and returns an unsubscribe function.
+   * Subscribe to auth state changes. Invokes the callback immediately
+   * with the current state, then again on every state transition.
    *
    * ```ts
-   * const unsub = auth.onChange(setState)
+   * const unsub = auth.onChange(setState);
    * ```
+   *
+   * @param cb - Callback receiving the latest {@link AuthState}.
+   * @returns An unsubscribe function.
    */
   const onChange = (cb: (state: AuthState) => void): (() => void) => {
     cb(snapshot);
@@ -1040,8 +1122,11 @@ export function client(options: ClientOptions) {
     get state(): AuthState {
       return snapshot;
     },
+    /** Sign in with a provider. See {@link SignInResult} for return shape. */
     signIn,
+    /** Sign out and clear all token state. */
     signOut,
+    /** Subscribe to auth state changes. Returns an unsubscribe function. */
     onChange,
     /** Passkey (WebAuthn) authentication helpers. */
     passkey,

package/src/component/_generated/api.ts

@@ -9,7 +9,7 @@
  */
 
 import type * as index from "../index.js";
-import type * as portalBridge from "../portalBridge.js";
+import type * as bridge from "../bridge.js";
 import type * as public_ from "../public.js";
 
 import type {
@@ -21,7 +21,7 @@ import { anyApi, componentsGeneric } from "convex/server";
 
 const fullApi: ApiFromModules<{
   index: typeof index;
-  portalBridge: typeof portalBridge;
+  bridge: typeof bridge;
   public: typeof public_;
 }> = anyApi as any;
 

package/src/component/_generated/component.ts

@@ -23,7 +23,7 @@ import type { FunctionReference } from "convex/server";
  */
 export type ComponentApi<Name extends string | undefined = string | undefined> =
   {
-    portalBridge: {
+    bridge: {
       gcOldAssets: FunctionReference<
         "mutation",
         "internal",

package/src/component/{portalBridge.ts → bridge.ts}

@@ -4,11 +4,11 @@
  * The auth component uses self-hosting as a sub-component for serving
  * portal static assets. These functions expose the self-hosting API
  * as internal queries/mutations within the auth component, so the
- * app layer can call them via `ctx.runQuery(components.auth.portalBridge.getByPath, ...)`.
+ * app layer can call them via `ctx.runQuery(components.auth.bridge.getByPath, ...)`.
  */
 
 import { v } from "convex/values";
-import { query, mutation, internalMutation } from "./_generated/server.js";
+import { query, mutation } from "./_generated/server.js";
 import { components } from "./_generated/api.js";
 
 // ============================================================================

package/src/component/index.ts

@@ -9,13 +9,19 @@
  */
 
 export {
+  /**
+   * The low-level factory function used internally by the `Auth` class.
+   * Re-exported as `AuthFactory` to avoid naming conflicts with the
+   * `Auth` class (the recommended public API). Prefer `new Auth(...)`.
+   */
   Auth as AuthFactory,
   Tokens,
   Doc,
   SignInAction,
   SignOutAction,
 } from "../server/implementation/index.js";
-export { Auth, Portal } from "../server/convex-auth.js";
+export { Auth, Portal, AuthCtx } from "../server/auth.js";
+export type { AuthCtxConfig, InferAuth, UserDoc } from "../server/auth.js";
 export type {
   ConvexAuthConfig,
   AuthProviderConfig,
@@ -31,5 +37,7 @@ export type {
   KeyScope,
   ScopeChecker,
   KeyRecord,
+  HttpKeyContext,
+  CorsConfig,
 } from "../server/types.js";
-export type { GenericDoc } from "../server/convex_types.js";
+export type { GenericDoc } from "../server/types.js";

package/src/component/public.ts

@@ -588,6 +588,7 @@ export const groupCreate = mutation({
   args: {
     name: v.string(),
     slug: v.optional(v.string()),
+    type: v.optional(v.string()),
     parentGroupId: v.optional(v.id("group")),
     extend: v.optional(v.any()),
   },
@@ -605,12 +606,32 @@ export const groupGet = query({
 });
 
 /**
- * List groups. When `parentGroupId` is provided, returns children of that
- * group. When omitted, returns all root-level groups (groups with no parent).
+ * List groups. Supports filtering by `type`, `parentGroupId`, or both.
+ *
+ * - Both provided → compound index `typeAndParentGroupId`
+ * - Only `type` → `type` index
+ * - Only `parentGroupId` (or neither) → `parentGroupId` index (original behaviour)
  */
 export const groupList = query({
-  args: { parentGroupId: v.optional(v.id("group")) },
-  handler: async (ctx, { parentGroupId }) => {
+  args: {
+    type: v.optional(v.string()),
+    parentGroupId: v.optional(v.id("group")),
+  },
+  handler: async (ctx, { type, parentGroupId }) => {
+    if (type !== undefined && parentGroupId !== undefined) {
+      return await ctx.db
+        .query("group")
+        .withIndex("typeAndParentGroupId", (q) =>
+          q.eq("type", type).eq("parentGroupId", parentGroupId),
+        )
+        .collect();
+    }
+    if (type !== undefined) {
+      return await ctx.db
+        .query("group")
+        .withIndex("type", (q) => q.eq("type", type))
+        .collect();
+    }
     return await ctx.db
       .query("group")
       .withIndex("parentGroupId", (q) => q.eq("parentGroupId", parentGroupId))

package/src/component/schema.ts

@@ -168,11 +168,14 @@ export default defineSchema({
   group: defineTable({
     name: v.string(),
     slug: v.optional(v.string()),
+    type: v.optional(v.string()),
     parentGroupId: v.optional(v.id("group")),
     extend: v.optional(v.any()),
   })
     .index("slug", ["slug"])
-    .index("parentGroupId", ["parentGroupId"]),
+    .index("parentGroupId", ["parentGroupId"])
+    .index("type", ["type"])
+    .index("typeAndParentGroupId", ["type", "parentGroupId"]),
 
   /**
    * Group membership. Links a user to a group with an application-defined

package/src/providers/anonymous.ts

@@ -56,6 +56,9 @@ export interface AnonymousConfig<DataModel extends GenericDataModel> {
  * An anonymous authentication provider.
  *
  * This provider doesn't require any user-provided information.
+ *
+ * @param config - Optional overrides (custom ID, profile, etc.).
+ * @returns A `ConvexCredentialsConfig` to include in your `providers` array.
  */
 export default function anonymous<DataModel extends GenericDataModel>(
   config: AnonymousConfig<DataModel> = {},

package/src/providers/credentials.ts

@@ -94,6 +94,9 @@ export interface CredentialsUserConfig<
 /**
  * The Credentials provider allows you to handle signing in with arbitrary credentials,
  * such as a username and password, domain, or two factor authentication or hardware device (e.g. YubiKey U2F / FIDO).
+ *
+ * @param config - Credential-specific options (authorize callback, profile, etc.).
+ * @returns A `ConvexCredentialsConfig` to include in your `providers` array.
  */
 export default function credentials<DataModel extends GenericDataModel>(
   config: CredentialsUserConfig<DataModel>,

package/src/providers/email.ts

@@ -30,6 +30,9 @@ import { EmailConfig, EmailUserConfig } from "../server/types.js";
  * ```
  *
  * Make sure the token has high enough entropy to be secure.
+ *
+ * @param config - Email provider options including `sendVerificationRequest`.
+ * @returns An `EmailConfig` to include in your `providers` array.
  */
 export default function email<DataModel extends GenericDataModel>(
   config: EmailUserConfig<DataModel> &

package/src/providers/passkey.ts

@@ -1,3 +1,9 @@
+/**
+ * Passkey (WebAuthn) authentication provider.
+ *
+ * @module
+ */
+
 import { PasskeyProviderConfig } from "../server/types.js";
 
 /**
@@ -15,7 +21,8 @@ import { PasskeyProviderConfig } from "../server/types.js";
  * });
  * ```
  *
- * @param config Optional configuration for the relying party and credential options.
+ * @param config - Optional relying party and credential options.
+ * @returns A `PasskeyProviderConfig` to include in your `providers` array.
  */
 export default function passkey(
   config?: Partial<PasskeyProviderConfig["options"]>,

package/src/providers/password.ts

@@ -105,6 +105,9 @@ export interface PasswordConfig<DataModel extends GenericDataModel> {
  *
  * Email verification is not required unless you pass
  * an email provider to the `verify` option.
+ *
+ * @param config - Password options (custom ID, crypto, verify, profile, etc.).
+ * @returns A `ConvexCredentialsConfig` to include in your `providers` array.
  */
 export default function password<DataModel extends GenericDataModel>(
   config: PasswordConfig<DataModel> = {},

package/src/providers/phone.ts

@@ -19,6 +19,9 @@ import { PhoneConfig, PhoneUserConfig } from "../server/types.js";
  * When you use this function to create your config, it
  * checks that there is a `phone` field during token verification
  * that matches the `phone` used during the initial `signIn` call.
+ *
+ * @param config - Phone provider options including `sendVerificationRequest`.
+ * @returns A `PhoneConfig` to include in your `providers` array.
  */
 export default function phone<DataModel extends GenericDataModel>(
   config: PhoneUserConfig & Pick<PhoneConfig, "sendVerificationRequest">,

package/src/providers/totp.ts

@@ -1,3 +1,9 @@
+/**
+ * TOTP (Time-based One-Time Password) two-factor authentication provider.
+ *
+ * @module
+ */
+
 import { TotpProviderConfig } from "../server/types.js";
 
 /**
@@ -10,6 +16,9 @@ import { TotpProviderConfig } from "../server/types.js";
  *   providers: [TOTP({ issuer: "My App" })],
  * });
  * ```
+ *
+ * @param config - TOTP options: issuer name, digit count, and period.
+ * @returns A `TotpProviderConfig` to include in your `providers` array.
  */
 export default function totp(
   config?: Partial<TotpProviderConfig["options"]>,