@robelest/convex-auth 0.0.4-preview.0 → 0.0.4-preview.10

package/README.md

@@ -6,6 +6,7 @@ Component-first authentication for [Convex](https://convex.dev). One component,
 
 - **Class-based API** — `new Auth(components.auth, { providers })` gives you everything.
 - **OAuth via Arctic** — 50+ providers through [Arctic](https://arcticjs.dev), zero-dependency OAuth 2.0.
+- **Fluent Convex builders (recommended)** — cleaner auth-aware API handling with middleware and explicit `.public()` / `.internal()` exports.
 - **Password, passkeys, TOTP, magic links, OTP, phone, anonymous** — all built in.
 - **Device Authorization (RFC 8628)** — authenticate CLIs, smart TVs, and IoT devices.
 - **API keys** — scoped permissions, SHA-256 hashed storage, optional rate limiting.
@@ -16,13 +17,16 @@ Component-first authentication for [Convex](https://convex.dev). One component,
 ## Install
 
 ```bash
-npm install @robelest/convex-auth
+bun add @robelest/convex-auth
 ```
 
+> Renamed package: if you are migrating from earlier previews, replace
+> `@convex-dev/auth` with `@robelest/convex-auth` in imports and CLI commands.
+
 ## Quick Start
 
 ```bash
-npx @robelest/convex-auth
+bunx @robelest/convex-auth
 ```
 
 The interactive CLI sets up your Convex component, auth config, and HTTP routes in under a minute.
@@ -66,6 +70,33 @@ auth.http.add(http);
 export default http;
 ```
 
+## Recommended Convex API Handling (`fluent-convex`)
+
+For new projects, we recommend `fluent-convex` for auth middleware composition and cleaner API exports.
+
+```ts
+// convex/functions.ts
+import { createBuilder } from "fluent-convex";
+import { WithZod } from "fluent-convex/zod";
+import type { DataModel } from "./_generated/dataModel";
+import { auth } from "./auth";
+
+const convex = createBuilder<DataModel>();
+
+const withRequiredAuth = convex.createMiddleware<any, { auth: any }>(
+  async (ctx, next) => {
+    const userId = await auth.user.require(ctx);
+    const user = await auth.user.get(ctx, userId);
+    return next({ ...ctx, auth: { ...ctx.auth, userId, user } });
+  },
+);
+
+export const query = convex.query().use(withRequiredAuth).extend(WithZod);
+export const mutation = convex.mutation().use(withRequiredAuth).extend(WithZod);
+```
+
+`AuthCtx` from `@robelest/convex-auth/component` remains supported if your project already uses `convex-helpers`.
+
 ## Providers
 
 | Provider | Import |

package/dist/client/index.d.ts

@@ -27,19 +27,19 @@ interface Storage {
 /**
  * Device code response returned when signing in with the `"device"` provider.
  *
- * The device displays the `userCode` (or `verificationUriComplete`) and
+ * The device displays the `userCode` (or `verification_uri_complete`) and
  * polls via `auth.device.poll()` until the user authorizes.
  */
 type DeviceCodeResult = {
   /** High-entropy device code used for polling (keep secret). */deviceCode: string; /** Short human-readable code the user enters (e.g. "WDJB-MJHT"). */
   userCode: string; /** Base verification URL (e.g. "https://myapp.com/device"). */
-  verificationUri: string; /** Verification URL with user code pre-filled as `?code=XXXX-XXXX`. */
-  verificationUriComplete: string; /** Lifetime of the codes in seconds. */
+  verification_uri: string; /** Verification URL with user code pre-filled as `?code=XXXX-XXXX`. */
+  verification_uri_complete: string; /** Lifetime of the codes in seconds. */
   expiresIn: number; /** Minimum polling interval in seconds. */
   interval: number;
 };
 /**
- * Result of a `signIn` call.
+ * Result of a `sign_in` call.
  *
  * - `signingIn: true` — credentials were accepted and the user is authenticated.
  * - `redirect` — OAuth flow initiated; redirect the user to `redirect.toString()`.
@@ -54,9 +54,10 @@ type SignInResult = {
   deviceCode?: DeviceCodeResult; /** 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`. */
+/** Reactive auth state snapshot returned by `auth.state` and `auth.on_change`. */
 type AuthState = {
-  /** `true` during initial hydration before the first token is resolved. */isLoading: boolean; /** `true` when a valid JWT exists (user is signed in). */
+  /** High-level auth phase for deterministic UI state handling. */phase: "loading" | "handshake" | "authenticated" | "unauthenticated"; /** `true` during initial hydration before the first token is resolved. */
+  isLoading: boolean; /** `true` only after Convex confirms authentication with the backend. */
   isAuthenticated: boolean; /** The raw JWT string, or `null` when not authenticated. */
   token: string | null;
 };
@@ -72,21 +73,21 @@ type ClientOptions = {
    * Key-value storage for persisting tokens.
    *
    * - Defaults to `localStorage` in SPA mode.
-   * - Defaults to `null` (in-memory only) when `proxy` is set,
+   * - Defaults to `null` (in-memory only) when `proxy_path` is set,
    *   since httpOnly cookies handle persistence.
    */
   storage?: Storage | null; /** Override how the URL bar is updated after OAuth code exchange. */
-  replaceURL?: (relativeUrl: string) => void | Promise<void>;
+  replace_url?: (relative_url: string) => void | Promise<void>;
   /**
    * SSR proxy endpoint (e.g. `"/api/auth"`).
    *
-   * When set, `signIn`/`signOut`/token refresh POST to this URL
+   * When set, `sign_in`/`sign_out`/token refresh POST to this URL
    * (with `credentials: "include"`) instead of calling Convex directly.
    * The server handles httpOnly cookies for token persistence.
    *
-   * Pair with {@link ClientOptions.token} for flash-free SSR hydration.
+   * Pair with {@link ClientOptions.token_seed} for flash-free SSR hydration.
    */
-  proxy?: string;
+  proxy_path?: string;
   /**
    * JWT from server-side hydration.
    *
@@ -94,12 +95,12 @@ type ClientOptions = {
    * and passes it to the client during SSR. This avoids a loading
    * flash on first render — the client is immediately authenticated.
    */
-  token?: string | null;
+  token_seed?: string | null;
 };
 /**
  * Create a framework-agnostic auth client.
  *
- * Returns an object with `signIn`, `signOut`, `onChange`, `state`,
+ * Returns an object with `sign_in`, `sign_out`, `on_change`, `state`,
  * `passkey`, and `totp` — everything needed for client-side auth.
  *
  * ### SPA mode (default)
@@ -117,8 +118,8 @@ type ClientOptions = {
  * ```ts
  * const auth = client({
  *   convex,
- *   proxy: '/api/auth',
- *   token: tokenFromServer, // JWT read from httpOnly cookie during SSR
+ *   proxy_path: '/api/auth',
+ *   token_seed: tokenFromServer, // JWT read from httpOnly cookie during SSR
  * });
  * ```
  *
@@ -127,13 +128,13 @@ type ClientOptions = {
  * holds the JWT in memory only.
  *
  * @param options - Client configuration. See {@link ClientOptions}.
- * @returns Auth client with `signIn`, `signOut`, `onChange`, `state`, `passkey`, and `totp`.
+ * @returns Auth client with `sign_in`, `sign_out`, `on_change`, `state`, `passkey`, and `totp`.
  */
 declare function client(options: ClientOptions): {
   /** Current auth state snapshot. */readonly state: AuthState; /** Sign in with a provider. See {@link SignInResult} for return shape. */
-  signIn: (provider?: string, args?: FormData | Record<string, Value>) => Promise<SignInResult>; /** Sign out and clear all token state. */
-  signOut: () => Promise<void>; /** Subscribe to auth state changes. Returns an unsubscribe function. */
-  onChange: (cb: (state: AuthState) => void) => (() => void); /** Passkey (WebAuthn) authentication helpers. */
+  sign_in: (provider?: string, args?: FormData | Record<string, Value>) => Promise<SignInResult>; /** Sign out and clear all token state. */
+  sign_out: () => Promise<void>; /** Subscribe to auth state changes. Returns an unsubscribe function. */
+  on_change: (cb: (state: AuthState) => void) => (() => void); /** Passkey (WebAuthn) authentication helpers. */
   passkey: {
     /**
      * Check if WebAuthn passkeys are supported in the current environment.
@@ -245,8 +246,8 @@ declare function client(options: ClientOptions): {
      *
      * Called after a credentials sign-in returns `totpRequired: true`.
      *
-     * ```ts
-     * const result = await auth.signIn("password", { email, password });
+      * ```ts
+      * const result = await auth.sign_in("password", { email, password });
      * if (result.totpRequired) {
      *   await auth.totp.verify({ code: "123456", verifier: result.verifier! });
      * }
@@ -261,19 +262,19 @@ declare function client(options: ClientOptions): {
     /**
      * Poll for device authorization status.
      *
-     * The device calls this repeatedly (respecting `interval`) after
-     * initiating a device flow via `signIn("device")`. Returns when
+      * The device calls this repeatedly (respecting `interval`) after
+      * initiating a device flow via `sign_in("device")`. Returns when
      * the user authorizes, or throws on timeout/denial.
      *
-     * ```ts
-     * const result = await auth.signIn("device");
+      * ```ts
+      * const result = await auth.sign_in("device");
      * const { deviceCode } = result;
      * // Display deviceCode.userCode to the user, then poll:
      * await auth.device.poll(deviceCode);
      * // User is now signed in
      * ```
-     *
-     * @param code - The {@link DeviceCodeResult} from `signIn("device")`.
+      *
+      * @param code - The {@link DeviceCodeResult} from `sign_in("device")`.
      * @returns Resolves when the device is authorized and tokens are stored.
      * @throws When the code expires, is denied, or polling encounters an error.
      */
@@ -292,7 +293,8 @@ declare function client(options: ClientOptions): {
      * @param userCode - The user code entered by the user (e.g. "WDJB-MJHT").
      */
     verify: (userCode: string) => Promise<void>;
-  };
+  }; /** Remove global listeners when disposing this client instance. */
+  destroy: () => void;
 };
 //#endregion
 export { AUTH_ERRORS, type AuthErrorCode, AuthState, ClientOptions, DeviceCodeResult, SignInResult, Storage, client, isAuthError, parseAuthError };

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/client/index.ts"],"mappings":";;;;;;AAS0B;;;;;;;UAWhB,eAAA;EACR,MAAA,CAAO,MAAA,OAAa,IAAA,QAAY,OAAA;EAChC,OAAA,CACE,UAAA,GAAa,IAAA;IACX,iBAAA;EAAA,MACI,OAAA,6BACN,QAAA,IAAY,eAAA;EAEd,SAAA;AAAA;;UAIe,OAAA;EACf,OAAA,CACE,GAAA,uCAC6B,OAAA;EAC/B,OAAA,CAAQ,GAAA,UAAa,KAAA,kBAAuB,OAAA;EAC5C,UAAA,CAAW,GAAA,kBAAqB,OAAA;AAAA;;;;;;;KActB,gBAAA;EAjBR,+DAmBF,UAAA,UAjBA;EAmBA,QAAA,UAnBqB;EAqBrB,eAAA,UApBA;EAsBA,uBAAA,UAtBgC;EAwBhC,SAAA,UAxBuC;EA0BvC,QAAA;AAAA;;;;;;;;;;KAYU,YAAA;EAAA,mEAEV,SAAA;EAEA,QAAA,GAAW,GAAA,EAFX;EAIA,YAAA,YAFW;EAIX,UAAA,GAAa,gBAAA,EAAb;EAEA,QAAA;AAAA;;KAIU,SAAA;EAAA,0EAEV,SAAA;EAEA,eAAA,WAFA;EAIA,KAAA;AAAA;;KAIU,aAAA;EAAA,iEAEV,MAAA,EAAQ,eAAA;;;;;EAKR,GAAA;EAUoD;;;;;;;EAFpD,OAAA,GAAU,OAAA,SAEmC;EAA7C,UAAA,IAAc,WAAA,oBAA+B,OAAA;EAkB7C;;;AA2DF;;;;;;EAnEE,KAAA;EAmSoB;;;;;;;EA3RpB,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2Dc,MAAA,CAAO,OAAA,EAAS,aAAA;EAkkBxB,mDAqfS,SAAA;8BAx1BI,IAAA,GACV,QAAA,GAAW,MAAA,SAAe,KAAA,MAChC,OAAA,CAAQ,YAAA,GAoWE;gCAkJA;kBAlSU,KAAA,EAAO,SAAA;;IAmSjB;;;;IAoHe;;;;;;;;;+BAlTK,OAAA;IAiV7B;;;;;;;;;;;;;;;;;;;;;;MA3SE,IAAA;MACA,KAAA;MACA,QAAA;MACA,eAAA;IAAA,MAED,OAAA,CAAQ,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAkJA,KAAA;MAAgB,QAAA;IAAA,MACxB,OAAA,CAAQ,YAAA;EAAA;;;;;;;;;;;;;;MAoHA,IAAA;MAAe,WAAA;IAAA,MACvB,OAAA;MAAU,GAAA;MAAa,MAAA;MAAgB,QAAA;MAAkB,MAAA;IAAA;;;;;;;;;MA4B1D,IAAA;MACA,QAAA;MACA,MAAA;IAAA,MACE,OAAA;;;;;;;;;;;;;;MA8CmB,IAAA;MAAc,QAAA;IAAA,MAAqB,OAAA;EAAA;;;;;;;;;;;;;;;;;;;;;iBAsDvC,gBAAA,KAAmB,OAAA;;;;;;;;;;;;;;kCAiFJ,OAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/client/index.ts"],"mappings":";;;;;;AAU0B;;;;;;;UAWhB,eAAA;EACR,MAAA,CAAO,MAAA,OAAa,IAAA,QAAY,OAAA;EAChC,OAAA,CACE,UAAA,GAAa,IAAA;IACX,iBAAA;EAAA,MACI,OAAA,6BACN,QAAA,IAAY,eAAA;EAEd,SAAA;AAAA;;UAIe,OAAA;EACf,OAAA,CACE,GAAA,uCAC6B,OAAA;EAC/B,OAAA,CAAQ,GAAA,UAAa,KAAA,kBAAuB,OAAA;EAC5C,UAAA,CAAW,GAAA,kBAAqB,OAAA;AAAA;;;;;;;KActB,gBAAA;EAjBR,+DAmBF,UAAA,UAjBA;EAmBA,QAAA,UAnBqB;EAqBrB,gBAAA,UApBA;EAsBA,yBAAA,UAtBgC;EAwBhC,SAAA,UAxBuC;EA0BvC,QAAA;AAAA;;;;;;;;;;KAYU,YAAA;EAAA,mEAEV,SAAA;EAEA,QAAA,GAAW,GAAA,EAFX;EAIA,YAAA,YAFW;EAIX,UAAA,GAAa,gBAAA,EAAb;EAEA,QAAA;AAAA;;KAIU,SAAA;EAAA,iEAEV,KAAA;EAEA,SAAA,WAFA;EAIA,eAAA;EAEA,KAAA;AAAA;;KAIU,aAAA;EAAa,iEAEvB,MAAA,EAAQ,eAAA;EAAA;;;;EAKR,GAAA;EALA;;;;;;;EAaA,OAAA,GAAU,OAAA,SAYV;EAVA,WAAA,IAAe,YAAA,oBAAgC,OAAA;EAkBrC;;AAoGZ;;;;;;;EA5GE,UAAA;EAmnBW;;;;;;;EA3mBX,UAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoGc,MAAA,CAAO,OAAA,EAAS,aAAA;EAi7BxB,mDAwgBS,SAAA,EAtgBV;+BA9ac,IAAA,GACV,QAAA,GAAW,MAAA,SAAe,KAAA,MAChC,OAAA,CAAQ,YAAA;iCAkkBkB;mBAzTL,KAAA,EAAO,SAAA,4BA0T1B;;;;;;;;;;;;;;;+BAlM4B,OAAA;;;;;;;;;;;;;;;;;;;;;;;MAsC3B,IAAA;MACA,KAAA;MACA,QAAA;MACA,eAAA;IAAA,MAED,OAAA,CAAQ,YAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAsJA,KAAA;MAAgB,QAAA;IAAA,MACxB,OAAA,CAAQ,YAAA;EAAA;;;;;;;;;;;;;;MAwHA,IAAA;MAAe,WAAA;IAAA,MACvB,OAAA;MAAU,GAAA;MAAa,MAAA;MAAgB,QAAA;MAAkB,MAAA;IAAA;;;;;;;;;MA4B1D,IAAA;MACA,QAAA;MACA,MAAA;IAAA,MACE,OAAA;;;;;;;;;;;;;;MAkDmB,IAAA;MAAc,QAAA;IAAA,MAAqB,OAAA;EAAA;;;;;;;;;;;;;;;;;;;;;iBA0DvC,gBAAA,KAAmB,OAAA;;;;;;;;;;;;;;kCAqFJ,OAAA;EAAA"}