@robelest/convex-auth 0.0.4-preview.29 → 0.0.4-preview.31

package/dist/client/core/types.d.ts

@@ -1,4 +1,4 @@
-import { ConvexError, Value } from "convex/values";
+import { Value } from "convex/values";
 import { FunctionReference } from "convex/server";
 
 //#region src/client/core/types.d.ts
@@ -22,9 +22,6 @@ interface ConvexTransport {
 interface ActionTransport {
   action(action: unknown, args: unknown): Promise<unknown>;
 }
-type SignInApiRef = {
-  signIn: AuthApiRefs["signIn"];
-};
 /** Pluggable key-value storage supplied by the host runtime. */
 interface Storage {
   getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
@@ -35,7 +32,10 @@ interface Storage {
 interface LocationRuntime {
   get(): URL | null;
   replace(relativeUrl: string): void | Promise<void>;
-  redirect(url: URL): void | Promise<void>;
+}
+/** Platform-specific OAuth launch primitive. */
+interface OAuthRuntime {
+  open(url: URL): void | Promise<void>;
 }
 /** Cross-context synchronization hooks, such as browser storage events. */
 interface SyncRuntime {
@@ -59,6 +59,7 @@ interface ClientRuntime {
   environment?: "client" | "server";
   storage?: Storage | null;
   location?: LocationRuntime;
+  oauth?: OAuthRuntime;
   sync?: SyncRuntime;
   mutex?: MutexRuntime;
   proxy?: ProxyRuntime;
@@ -69,56 +70,21 @@ interface ClientAdapters {
   totp?: TotpClient;
   device?: DeviceClient;
 }
-interface ClientAdapterDeps {
-  proxy: string | undefined;
-  convex: ConvexTransport;
-  requireApiRefs: () => SignInApiRef;
-  proxyFetch: (body: Record<string, unknown>) => Promise<unknown>;
-  setTokenAndMaybeWait: (args: {
-    shouldStore: true;
-    tokens: AuthSession | null;
-    waitForHandshake: boolean;
-    context: {
-      provider?: string;
-      flow: string;
-    };
-  } | {
-    shouldStore: false;
-    tokens: {
-      token: string;
-    } | null;
-    waitForHandshake: boolean;
-    context: {
-      provider?: string;
-      flow: string;
-    };
-  }) => Promise<boolean>;
-}
-interface ClientAdapterFactories {
-  passkey?: (deps: ClientAdapterDeps) => PasskeyClient;
-}
-type AuthSession = {
-  token: string;
-  refreshToken: string;
-};
 /**
- * Device code response returned when signing in with the `"device"` provider.
- *
- * The device displays the `userCode` (or `verificationUriComplete`) and
- * polls via `auth.device.poll()` until the user authorizes.
+ * Device authorization payload returned from the `deviceCode` sign-in flow.
  */
 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. */
-  expiresIn: number; /** Minimum polling interval in seconds. */
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  verificationUriComplete: string;
+  expiresIn: number;
   interval: number;
 };
 /**
  * Result of a `signIn` call.
  *
- * - `kind: "signedIn"` — credentials were accepted and the user is authenticated.
+ * - `kind: "signedIn"` — credentials were accepted and a client session is now available.
  * - `kind: "redirect"` — OAuth flow initiated; redirect the user to `redirect.toString()`.
  * - `kind: "totpRequired"` — credentials valid but 2FA is needed; call `auth.totp.verify()`.
  * - `kind: "deviceCode"` — device flow initiated; display the code and poll via `auth.device.poll()`.
@@ -163,7 +129,22 @@ type AuthState = {
 type AuthApiRefs<HasPasskey extends boolean = boolean, HasTotp extends boolean = boolean, HasDevice extends boolean = boolean> = {
   signIn: FunctionReference<"action", "public", Record<string, Value>, unknown>;
   signOut: FunctionReference<"action", "public", Record<string, Value>, unknown>;
-  store: FunctionReference<"mutation", "public", Record<string, Value>, unknown>;
+};
+/**
+ * Optional hints for {@link PasskeyClient.register}.
+ */
+type PasskeyRegisterOptions = {
+  /** Human-readable label for this credential (e.g. `"MacBook Pro"`). */name?: string; /** Email hint stored with the credential. */
+  email?: string; /** WebAuthn `user.name` override. */
+  userName?: string; /** WebAuthn `user.displayName` override. */
+  userDisplayName?: string;
+};
+/**
+ * Optional hints for {@link PasskeyClient.signIn}.
+ */
+type PasskeySignInOptions = {
+  /** Email hint to filter discoverable credentials. */email?: string; /** Set to `true` for conditional UI (autofill) mode. */
+  autofill?: boolean;
 };
 /**
  * Passkey (WebAuthn) client-side helpers.
@@ -193,7 +174,7 @@ interface PasskeyClient {
    * @example
    * ```ts
    * if (await auth.passkey.isAutofillSupported()) {
-   *   await auth.passkey.authenticate({ autofill: true });
+   *   await auth.passkey.signIn({ autofill: true });
    * }
    * ```
    */
@@ -208,29 +189,54 @@ interface PasskeyClient {
    * @param opts.email - Email hint for discoverable credentials.
    * @param opts.userName - WebAuthn `user.name` override.
    * @param opts.userDisplayName - WebAuthn `user.displayName` override.
-   * @returns A {@link SignInResult} — typically `{ kind: "signedIn" }` on success.
+    * @returns A {@link SignInResult} — typically `{ kind: "signedIn" }` once a client session is available.
    *
    * @example
    * ```ts
    * const result = await auth.passkey.register({ name: "My laptop" });
    * ```
    */
-  register(opts?: Record<string, unknown>): Promise<SignInResult>;
+  register(opts?: PasskeyRegisterOptions): Promise<SignInResult>;
   /**
-   * Authenticate with an existing passkey and complete the WebAuthn ceremony.
+   * Sign in with an existing passkey and complete the WebAuthn ceremony.
    *
-   * @param opts - Optional authentication hints.
+   * @param opts - Optional sign-in hints.
    * @param opts.email - Email hint to filter discoverable credentials.
    * @param opts.autofill - Set to `true` for conditional UI (autofill) mode.
-   * @returns A {@link SignInResult} — typically `{ kind: "signedIn" }` on success.
+   * @returns A {@link SignInResult} — typically `{ kind: "signedIn" }` once a client session is available.
    *
    * @example
    * ```ts
-   * const result = await auth.passkey.authenticate();
+   * const result = await auth.passkey.signIn();
    * ```
    */
-  authenticate(opts?: Record<string, unknown>): Promise<SignInResult>;
+  signIn(opts?: PasskeySignInOptions): Promise<SignInResult>;
 }
+/**
+ * Optional hints for {@link TotpClient.setup}.
+ */
+type TotpSetupOptions = {
+  /** Issuer name shown in the authenticator app. */name?: string; /** Account label shown in the authenticator app. */
+  accountName?: string;
+};
+/** Result of {@link TotpClient.setup}. */
+type TotpSetupResult = {
+  /** `otpauth://` URL — render as a QR code. */uri: string; /** Raw base32-encoded shared secret. */
+  secret: string; /** Verifier token to pass to {@link TotpClient.confirm}. */
+  verifier: string; /** Factor ID to pass to {@link TotpClient.confirm}. */
+  totpId: string;
+};
+/** Params for {@link TotpClient.confirm}. */
+type TotpConfirmParams = {
+  /** Six-digit OTP from the authenticator app. */code: string; /** Verifier token from {@link TotpSetupResult.verifier}. */
+  verifier: string; /** Factor ID from {@link TotpSetupResult.totpId}. */
+  totpId: string;
+};
+/** Params for {@link TotpClient.verify}. */
+type TotpVerifyParams = {
+  /** Six-digit OTP from the authenticator app. */code: string; /** Verifier token from a `totpRequired` sign-in result. */
+  verifier: string;
+};
 /**
  * TOTP two-factor authentication client-side helpers.
  *
@@ -256,7 +262,7 @@ interface TotpClient {
    * await auth.totp.confirm({ code: userCode, verifier, totpId });
    * ```
    */
-  setup(opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+  setup(opts?: TotpSetupOptions): Promise<TotpSetupResult>;
   /**
    * Confirm a newly created TOTP factor with the first authenticator code.
    *
@@ -272,7 +278,7 @@ interface TotpClient {
    * await auth.totp.confirm({ code: "123456", verifier, totpId });
    * ```
    */
-  confirm(opts: Record<string, unknown>): Promise<void>;
+  confirm(opts: TotpConfirmParams): Promise<void>;
   /**
    * Complete a sign-in that is waiting on TOTP verification.
    *
@@ -290,8 +296,16 @@ interface TotpClient {
    * }
    * ```
    */
-  verify(opts: Record<string, unknown>): Promise<void>;
+  verify(opts: TotpVerifyParams): Promise<void>;
 }
+/** Params for {@link DeviceClient.poll}. */
+type DevicePollParams = {
+  code: DeviceCodeResult;
+};
+/** Params for {@link DeviceClient.verify}. */
+type DeviceVerifyParams = {
+  code: string;
+};
 /**
  * Device authorization (RFC 8628) client-side helpers.
  *
@@ -319,9 +333,7 @@ interface DeviceClient {
    * }
    * ```
    */
-  poll(opts: {
-    code: DeviceCodeResult;
-  }): Promise<void>;
+  poll(opts: DevicePollParams): Promise<void>;
   /**
    * Approve a device flow from the verification page using the displayed user code.
    *
@@ -337,9 +349,7 @@ interface DeviceClient {
    * await auth.device.verify({ code: "WDJB-MJHT" });
    * ```
    */
-  verify(opts: {
-    code: string;
-  }): Promise<void>;
+  verify(opts: DeviceVerifyParams): Promise<void>;
 }
 /**
  * Extract capability flags from an AuthApiRefs type.
@@ -377,6 +387,88 @@ interface PendingInvite {
     token: string;
   }>;
 }
+/**
+ * Discriminated union of params for the password provider's flows.
+ *
+ * Each branch maps to one of the five password flows: `signUp`, `signIn`,
+ * `reset`, `verify`, `change`. Selecting a `flow` literal narrows the
+ * accepted params automatically.
+ */
+type PasswordParams = {
+  flow: "signUp";
+  email: string;
+  password: string;
+  redirectTo?: string;
+} | {
+  flow: "signIn";
+  email: string;
+  password: string;
+  redirectTo?: string;
+} | {
+  flow: "reset";
+  email: string;
+  redirectTo?: string;
+} | {
+  flow: "verify";
+  email: string;
+  code: string; /** When set, completes a `reset` flow by updating the password. Otherwise confirms email. */
+  newPassword?: string;
+  redirectTo?: string;
+} | {
+  flow: "change";
+  email: string;
+  currentPassword: string;
+  newPassword: string;
+  redirectTo?: string;
+};
+/** Params for the email (magic link) provider's initiation step. */
+type EmailInitiateParams = {
+  email: string;
+  redirectTo?: string;
+};
+/**
+ * Params for completing a code-based flow (no provider). Used to finalise
+ * email magic-link sign-ins and password-reset OTPs when the verification
+ * call is made without re-specifying the originating provider.
+ */
+type CodeCompletionParams = {
+  code: string;
+  redirectTo?: string;
+};
+/** Params for the `sso` provider — requires a connection ID. */
+type SsoParams = {
+  connectionId: string;
+  redirectTo?: string;
+};
+/** Params for the anonymous provider. Empty / `redirectTo` only. */
+type AnonymousParams = {
+  redirectTo?: string;
+};
+/** Default params shape for OAuth-style providers (google, github, etc.). */
+type OAuthSignInParams = {
+  redirectTo?: string;
+};
+/**
+ * Params for `signIn("passkey", ...)`. Direct passkey flows are typically
+ * triggered through `auth.passkey.register()` / `auth.passkey.signIn()`
+ * — this overload is for advanced callers that bypass the helper.
+ */
+type PasskeySignInParams = {
+  redirectTo?: string;
+};
+/**
+ * Public signature for `auth.signIn`. The provider literal discriminates the
+ * params shape via {@link ParamsForProvider}, and the params slot is
+ * automatically optional when the resolved type permits `undefined`.
+ *
+ * @example
+ * ```ts
+ * auth.signIn("password", { flow: "signIn", email, password });
+ * auth.signIn("password", { flow: "change", email, currentPassword, newPassword });
+ * auth.signIn("anonymous"); // params optional
+ * ```
+ */
+type SignInOverloads = <P extends string | undefined>(provider: P, ...args: SignInArgs<P>) => Promise<SignInResult>;
 /** Base auth client — always present. */
 interface AuthClientBase {
   /**
@@ -384,6 +476,8 @@ interface AuthClientBase {
    * @readonly
    */
   readonly state: AuthState;
+  /** Restore initial auth state for the current runtime. */
+  initialize: () => Promise<void>;
   /** SSR-safe query-param reader. */
   param: (name: string) => string | null;
   /**
@@ -391,8 +485,12 @@ interface AuthClientBase {
    * @readonly
    */
   readonly invite: PendingInvite | null;
+  /** Complete an OAuth callback using a URL or authorization code. */
+  completeOAuth: (input: URL | string | {
+    code: string;
+  }) => Promise<OAuthCompletionResult>;
   /** Start a sign-in flow for a provider. */
-  signIn: (provider: string, params?: Record<string, unknown>) => Promise<SignInResult>;
+  signIn: SignInOverloads;
   /** Sign out and clear local auth state. */
   signOut: () => Promise<void>;
   /** Subscribe to auth state changes. Returns an unsubscribe function. */
@@ -404,8 +502,8 @@ interface AuthClientBase {
  * Framework-agnostic auth client return type.
  *
  * Conditionally includes `totp` and `device` helpers based on the
- * capabilities in the `AuthApiRefs` type. Browser-only `passkey` helpers are
- * added by {@link BrowserAuthClient}.
+ * capabilities in the `AuthApiRefs` type. Platform-specific `passkey` helpers
+ * are added by {@link PlatformAuthClient}.
  *
  * @typeParam Api - An AuthApiRefs type that determines which factor helpers are included.
  */
@@ -422,9 +520,11 @@ type AuthClient<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs
  *
  * @typeParam Api - An AuthApiRefs type that determines which factor helpers are included.
  */
-type BrowserAuthClient<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs> = AuthClient<Api> & (InferCaps<Api>["passkey"] extends true ? {
+type PlatformAuthClient<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs> = AuthClient<Api> & (InferCaps<Api>["passkey"] extends true ? {
   passkey: PasskeyClient;
 } : {});
+/** @deprecated Use `PlatformAuthClient`. */
+type BrowserAuthClient<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs> = PlatformAuthClient<Api>;
 /**
  * Options for {@link client}.
  *
@@ -451,8 +551,7 @@ type ClientOptions<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiR
    *
    * Defaults to `runtime.storage` when provided, otherwise `null`.
    */
-  storage?: Storage | null; /** Override how OAuth code cleanup updates the current URL. */
-  replaceUrl?: (relativeUrl: string) => void | Promise<void>;
+  storage?: Storage | null;
   /**
    * Proxy endpoint used instead of direct Convex auth calls.
    * When set, provide `runtime.proxy` and omit direct `api`/`httpClient`
@@ -462,6 +561,12 @@ type ClientOptions<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiR
   tokenSeed?: string | null; /** SSR-safe URL source for reading query parameters. */
   location?: URL | (() => URL | null);
 };
+type OAuthCompletionResult = {
+  handled: false;
+} | {
+  handled: true;
+  cleanupUrl: URL | null;
+};
 //#endregion
-export { AuthApiRefs, AuthClient, AuthState, BrowserAuthClient, ClientOptions, ClientRuntime, DeviceClient, DeviceCodeResult, PasskeyClient, PendingInvite, SignInResult, Storage, TotpClient };
+export { AnonymousParams, AuthApiRefs, AuthClient, AuthState, BrowserAuthClient, ClientOptions, ClientRuntime, CodeCompletionParams, DeviceClient, DeviceCodeResult, DevicePollParams, DeviceVerifyParams, EmailInitiateParams, OAuthCompletionResult, OAuthSignInParams, PasskeyClient, PasskeyRegisterOptions, PasskeySignInOptions, PasskeySignInParams, PasswordParams, PendingInvite, PlatformAuthClient, SignInOverloads, SignInResult, SsoParams, Storage, TotpClient, TotpConfirmParams, TotpSetupOptions, TotpSetupResult, TotpVerifyParams };
 //# sourceMappingURL=types.d.ts.map

package/dist/client/core/types.js

@@ -1,4 +1,10 @@
 //#region src/client/core/types.ts
+/**
+* Create a deferred promise that can be resolved or rejected externally.
+*
+* @returns A deferred object containing the promise and control methods.
+* @internal
+*/
 function createDeferred() {
 	let resolve;
 	let reject;

package/dist/client/factors/device.js

@@ -45,10 +45,10 @@ function createDeviceClient(deps) {
 					throw error;
 				}
 				if (pollResult === null) continue;
-				if (isSignedInResult(pollResult) && pollResult.tokens) {
+				if (isSignedInResult(pollResult) && pollResult.session) {
 					if (proxy) await setTokenAndMaybeWait({
 						shouldStore: false,
-						tokens: pollResult.tokens === null ? null : { token: pollResult.tokens.token },
+						tokens: pollResult.session === null ? null : { token: pollResult.session.token },
 						waitForHandshake: true,
 						context: {
 							provider: "device",
@@ -57,7 +57,7 @@ function createDeviceClient(deps) {
 					});
 					else await setTokenAndMaybeWait({
 						shouldStore: true,
-						tokens: pollResult.tokens ?? null,
+						tokens: pollResult.session ?? null,
 						waitForHandshake: true,
 						context: {
 							provider: "device",

package/dist/client/factors/totp.js

@@ -43,7 +43,7 @@ function createTotpClient(deps) {
 		},
 		confirm: async (opts) => {
 			const params = {
-				flow: "confirm",
+				flow: "verify",
 				code: opts.code,
 				totpId: opts.totpId
 			};
@@ -56,9 +56,9 @@ function createTotpClient(deps) {
 						verifier: opts.verifier
 					}
 				});
-				if (isSignedInResult(result$1) && result$1.tokens) await setTokenAndMaybeWait({
+				if (isSignedInResult(result$1) && result$1.session) await setTokenAndMaybeWait({
 					shouldStore: false,
-					tokens: result$1.tokens === null ? null : { token: result$1.tokens.token },
+					tokens: result$1.session === null ? null : { token: result$1.session.token },
 					waitForHandshake: true,
 					context: {
 						provider: "totp",
@@ -72,9 +72,9 @@ function createTotpClient(deps) {
 				params,
 				verifier: opts.verifier
 			});
-			if (isSignedInResult(result) && result.tokens) await setTokenAndMaybeWait({
+			if (isSignedInResult(result) && result.session) await setTokenAndMaybeWait({
 				shouldStore: true,
-				tokens: result.tokens ?? null,
+				tokens: result.session ?? null,
 				waitForHandshake: true,
 				context: {
 					provider: "totp",
@@ -96,9 +96,9 @@ function createTotpClient(deps) {
 						verifier: opts.verifier
 					}
 				});
-				if (isSignedInResult(result$1) && result$1.tokens) await setTokenAndMaybeWait({
+				if (isSignedInResult(result$1) && result$1.session) await setTokenAndMaybeWait({
 					shouldStore: false,
-					tokens: result$1.tokens === null ? null : { token: result$1.tokens.token },
+					tokens: result$1.session === null ? null : { token: result$1.session.token },
 					waitForHandshake: true,
 					context: {
 						provider: "totp",
@@ -112,9 +112,9 @@ function createTotpClient(deps) {
 				params,
 				verifier: opts.verifier
 			});
-			if (isSignedInResult(result) && result.tokens) await setTokenAndMaybeWait({
+			if (isSignedInResult(result) && result.session) await setTokenAndMaybeWait({
 				shouldStore: true,
-				tokens: result.tokens ?? null,
+				tokens: result.session ?? null,
 				waitForHandshake: true,
 				context: {
 					provider: "totp",

package/dist/client/index.d.ts

@@ -1,12 +1,13 @@
-import { AuthApiRefs, AuthClient, AuthState, BrowserAuthClient, ClientOptions, ClientRuntime, DeviceClient, DeviceCodeResult, PasskeyClient, PendingInvite, SignInResult, Storage, TotpClient } from "./core/types.js";
+import { AnonymousParams, AuthApiRefs, AuthClient, AuthState, BrowserAuthClient, ClientOptions, ClientRuntime, CodeCompletionParams, DeviceClient, DeviceCodeResult, DevicePollParams, DeviceVerifyParams, EmailInitiateParams, OAuthCompletionResult, OAuthSignInParams, PasskeyClient, PasskeyRegisterOptions, PasskeySignInOptions, PasskeySignInParams, PasswordParams, PendingInvite, PlatformAuthClient, SignInOverloads, SignInResult, SsoParams, Storage, TotpClient, TotpConfirmParams, TotpSetupOptions, TotpSetupResult, TotpVerifyParams } from "./core/types.js";
 
 //#region src/client/index.d.ts
 /**
  * Create a framework-agnostic auth client.
  *
  * Returns an object with `signIn`, `signOut`, `onChange`, `state`, and any
- * factor helpers enabled by your configured providers. Browser-specific
- * passkey support is added by the `@robelest/convex-auth/browser` entrypoint.
+ * factor helpers enabled by your configured providers. Platform-specific
+ * passkey support is added by higher-level entrypoints such as
+ * `@robelest/convex-auth/browser`.
  *
  * ### SPA mode (default)
  *
@@ -43,5 +44,5 @@ import { AuthApiRefs, AuthClient, AuthState, BrowserAuthClient, ClientOptions, C
  */
 declare function client<Api extends AuthApiRefs<boolean, boolean, boolean> = AuthApiRefs>(options: ClientOptions<Api>): AuthClient<Api>;
 //#endregion
-export { type AuthApiRefs, type AuthClient, type AuthState, type BrowserAuthClient, type ClientOptions, type ClientRuntime, type DeviceClient, type DeviceCodeResult, type PasskeyClient, type PendingInvite, type SignInResult, type Storage, type TotpClient, client };
+export { type AnonymousParams, type AuthApiRefs, type AuthClient, type AuthState, type BrowserAuthClient, type ClientOptions, type ClientRuntime, type CodeCompletionParams, type DeviceClient, type DeviceCodeResult, type DevicePollParams, type DeviceVerifyParams, type EmailInitiateParams, type OAuthCompletionResult, type OAuthSignInParams, type PasskeyClient, type PasskeyRegisterOptions, type PasskeySignInOptions, type PasskeySignInParams, type PasswordParams, type PendingInvite, type PlatformAuthClient, type SignInOverloads, type SignInResult, type SsoParams, type Storage, type TotpClient, type TotpConfirmParams, type TotpSetupOptions, type TotpSetupResult, type TotpVerifyParams, client };
 //# sourceMappingURL=index.d.ts.map