@robelest/convex-auth 0.0.4-preview.2 → 0.0.4-preview.21

package/src/providers/credentials.ts

@@ -14,16 +14,19 @@
  * @module
  */
 
-import {
+import { GenericDataModel } from "convex/server";
+import { GenericId, Value } from "convex/values";
+
+import type {
   AuthProviderConfig,
   ConvexCredentialsConfig,
   GenericActionCtxWithAuthConfig,
-} from "@robelest/convex-auth/component";
-import { GenericDataModel } from "convex/server";
-import { GenericId, Value } from "convex/values";
+} from "../server/types";
 
 /**
  * Configuration for the Credentials provider.
+ *
+ * @typeParam DataModel - The Convex data model.
  */
 export interface CredentialsConfig<
   DataModel extends GenericDataModel = GenericDataModel,
@@ -39,8 +42,8 @@ export interface CredentialsConfig<
     credentials: Partial<Record<string, Value | undefined>>,
     ctx: GenericActionCtxWithAuthConfig<DataModel>,
   ) => Promise<{
-    userId: GenericId<"user">;
-    sessionId?: GenericId<"session">;
+    userId: GenericId<"User">;
+    sessionId?: GenericId<"Session">;
   } | null>;
   /**
    * Provide hashing and verification functions for account secrets.
@@ -62,6 +65,8 @@ export interface CredentialsConfig<
  * This is the escape hatch for fully custom auth logic. For email/password
  * flows, use the `Password` class instead.
  *
+ * @typeParam DataModel - The Convex data model.
+ *
  * @example
  * ```ts
  * import { Credentials } from "@robelest/convex-auth/providers";
@@ -74,7 +79,9 @@ export interface CredentialsConfig<
  * })
  * ```
  */
-export class Credentials<DataModel extends GenericDataModel = GenericDataModel> {
+export class Credentials<
+  DataModel extends GenericDataModel = GenericDataModel,
+> {
   readonly id: string;
   readonly type = "credentials" as const;
   readonly config: CredentialsConfig<DataModel>;
@@ -93,18 +100,3 @@ export class Credentials<DataModel extends GenericDataModel = GenericDataModel>
     } as ConvexCredentialsConfig;
   }
 }
-
-// Keep the old factory function as default export for backward compatibility
-// during the transition. New code should use `new Credentials(...)`.
-
-/** @deprecated Use `new Credentials(config)` instead. */
-export default function credentials<DataModel extends GenericDataModel>(
-  config: CredentialsConfig<DataModel>,
-): ConvexCredentialsConfig {
-  return new Credentials(config)._toMaterialized();
-}
-
-// Re-export the old type name for backward compat
-export type CredentialsUserConfig<
-  DataModel extends GenericDataModel = GenericDataModel,
-> = CredentialsConfig<DataModel>;

package/src/providers/device.ts

@@ -53,9 +53,11 @@ const DEFAULT_CHARSET = "BCDFGHJKLMNPQRSTVWXZ";
  *
  * @example
  * ```ts
+ * import { createAuth } from "@robelest/convex-auth/component";
  * import { Device } from "@robelest/convex-auth/providers";
+ * import { components } from "./_generated/api";
  *
- * const auth = new Auth(components.auth, {
+ * const auth = createAuth(components.auth, {
  *   providers: [new Device()],
  * });
  * ```
@@ -83,16 +85,3 @@ export class Device {
     };
   }
 }
-
-// ============================================================================
-// Backward-compatible default export
-// ============================================================================
-
-/**
- * @deprecated Use `new Device(config)` instead.
- */
-export default function device(
-  config?: DeviceConfig,
-): DeviceProviderConfig {
-  return new Device(config)._toMaterialized();
-}

package/src/providers/email.ts

@@ -1,63 +1,99 @@
 /**
- * Simplifies creating custom email providers, such as for sending OTPs.
+ * Email (magic link / OTP) authentication provider.
  *
  * @module
  */
 
-import { GenericDataModel } from "convex/server";
-import { EmailConfig, EmailUserConfig } from "../server/types";
+import { defaultMagicLinkEmail } from "../server/templates";
+import type { EmailConfig } from "../server/types";
 
 /**
- * Email providers send a token to the user's email address
- * for sign-in.
+ * User-facing configuration for the {@link Email} provider.
  *
- * When you use this function to create your config, by default it
- * checks that there is an `email` field during token verification
- * that matches the `email` used during the initial `signIn` call.
+ * Use this to wire your email delivery service into Convex Auth's magic-link
+ * or OTP flow.
+ */
+export interface EmailProviderConfig {
+  /** Sender address (e.g. "My App <noreply@example.com>"). */
+  from: string;
+  /** Send the verification email. Receives the Convex action context. */
+  send: (
+    ctx: any,
+    opts: { from: string; to: string; subject: string; html: string },
+  ) => Promise<void>;
+  /** Override to generate a custom verification token. */
+  generateVerificationToken?: () => Promise<string>;
+  /** Provider ID override. Defaults to "email". */
+  id?: string;
+  /** Token expiration in seconds. Defaults to 86400 (24 hours). */
+  maxAge?: number;
+}
+
+/**
+ * Email provider for magic-link or one-time-code sign-in.
  *
- * If you want the "magic link behavior", where only the token is needed,
- * you can override the `authorize` method to skip the check:
+ * Sends verification emails through your `send()` implementation and converts
+ * the result into Convex Auth's internal email-provider runtime shape.
  *
+ * @example
  * ```ts
- * import email from "@robelest/convex-auth/providers/email";
- * import { Auth } from "@robelest/convex-auth/component";
+ * import { Email } from "@robelest/convex-auth/providers";
  *
- * export const { auth, signIn, signOut, store } = Auth({
- *   providers: [
- *     email({ authorize: undefined }),
- *   ],
+ * const email = new Email({
+ *   from: "My App <noreply@example.com>",
+ *   send: async (_ctx, { to, subject, html }) => {
+ *     await resend.emails.send({ from: "noreply@example.com", to, subject, html });
+ *   },
  * });
  * ```
- *
- * 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> &
-    Pick<EmailConfig, "sendVerificationRequest">,
-): EmailConfig<DataModel> {
-  return {
-    id: "email",
-    type: "email",
-    name: "Email",
-    from: "Auth.js <no-reply@authjs.dev>",
-    maxAge: 60 * 60, // 1 hour
-    authorize: async (params, account) => {
-      if (typeof params.email !== "string") {
-        throw new Error(
-          "Token verification requires an `email` in params of `signIn`.",
-        );
-      }
-      if (account.providerAccountId !== params.email) {
-        throw new Error(
-          "Short verification code requires a matching `email` " +
-            "in params of `signIn`.",
-        );
-      }
-    },
-    sendVerificationRequest: config.sendVerificationRequest,
-    options: config,
-  };
+export class Email {
+  readonly id: string;
+  readonly type = "email" as const;
+
+  /**
+   * Create an email provider instance.
+   *
+   * @param config - Email transport and provider settings.
+   * @throws {Error} When `config.from` is empty or whitespace-only.
+   */
+  constructor(public readonly config: EmailProviderConfig) {
+    const from = config.from.trim();
+    if (from.length === 0) {
+      throw new Error(
+        "Email provider requires a non-empty `from` address " +
+          '(for example, `"My App <noreply@example.com>"`).',
+      );
+    }
+    this.id = config.id ?? "email";
+  }
+
+  /** @internal */
+  _toMaterialized(): EmailConfig {
+    const from = this.config.from.trim();
+    const { send } = this.config;
+    const { generateVerificationToken } = this.config;
+    return {
+      id: this.id,
+      type: "email",
+      name: "Email",
+      from,
+      maxAge: this.config.maxAge ?? 60 * 60 * 24,
+      authorize: undefined,
+      sendVerificationRequest: async ({ identifier, url }, ctx) => {
+        if (!ctx) {
+          throw new Error("Email provider requires a Convex action context.");
+        }
+        const { host } = new URL(url);
+        await send(ctx, {
+          from,
+          to: identifier,
+          subject: `Sign in to ${host}`,
+          html: defaultMagicLinkEmail(url, host),
+        });
+      },
+      generateVerificationToken,
+      options: { from } as any,
+    };
+  }
 }

package/src/providers/index.ts

@@ -22,3 +22,10 @@ export { Credentials } from "./credentials";
 export type { CredentialsConfig } from "./credentials";
 export { Device } from "./device";
 export type { DeviceConfig } from "./device";
+export { SSO } from "./sso";
+export { Email } from "./email";
+export type { EmailProviderConfig } from "./email";
+export type { EmailConfig } from "../server/types";
+export { Phone } from "./phone";
+export type { PhoneProviderConfig } from "./phone";
+export type { PhoneConfig } from "../server/types";

package/src/providers/oauth.ts

@@ -14,6 +14,7 @@
  */
 
 import type { OAuth2Tokens } from "arctic";
+
 import type { OAuthProfile } from "../server/types";
 
 /**
@@ -90,8 +91,7 @@ export function OAuth(
     );
   }
 
-  const id =
-    config?.id ?? provider.constructor?.name?.toLowerCase() ?? "oauth";
+  const id = config?.id ?? provider.constructor?.name?.toLowerCase() ?? "oauth";
 
   return {
     _tag: OAUTH_PROVIDER_TAG,
@@ -105,7 +105,9 @@ export function OAuth(
 /**
  * Type guard to check if a provider config is an OAuth provider.
  */
-export function isOAuthProvider(value: unknown): value is OAuthProviderInstance {
+export function isOAuthProvider(
+  value: unknown,
+): value is OAuthProviderInstance {
   return (
     typeof value === "object" &&
     value !== null &&

package/src/providers/passkey.ts

@@ -75,16 +75,3 @@ export class Passkey {
     };
   }
 }
-
-// ============================================================================
-// Backward-compatible default export
-// ============================================================================
-
-/**
- * @deprecated Use `new Passkey(config)` instead.
- */
-export default function passkey(
-  config?: PasskeyConfig,
-): PasskeyProviderConfig {
-  return new Passkey(config)._toMaterialized();
-}