@account-kit/signer 4.6.1 → 4.8.0

package/src/base.ts

@@ -35,6 +35,7 @@ import {
   type ErrorInfo,
 } from "./types.js";
 import { assertNever } from "./utils/typeAssertions.js";
+import type { SessionManagerEvents } from "./session/types";
 
 export interface BaseAlchemySignerParams<TClient extends BaseSignerClient> {
   client: TClient;
@@ -46,6 +47,7 @@ type AlchemySignerStore = {
   user: User | null;
   status: AlchemySignerStatus;
   error: ErrorInfo | null;
+  otpId?: string;
   isNewUser?: boolean;
 };
 
@@ -238,6 +240,8 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
             return this.authenticateWithOauth(params);
           case "oauthReturn":
             return this.handleOauthReturn(params);
+          case "otp":
+            return this.authenticateWithOtp(params);
           default:
             assertNever(type, `Unknown auth type: ${type}`);
         }
@@ -296,6 +300,12 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
         break;
       case "oauthReturn":
         break;
+      case "otp":
+        SignerLogger.trackEvent({
+          name: "signer_authnticate",
+          data: { authType: "otp" },
+        });
+        break;
       default:
         assertNever(type, `Unknown auth type: ${type}`);
     }
@@ -673,26 +683,30 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   ): Promise<User> => {
     if ("email" in params) {
       const existingUser = await this.getUser(params.email);
-      const expirationSeconds = Math.floor(
-        this.sessionManager.expirationTimeMs / 1000
-      );
+      const expirationSeconds = this.getExpirationSeconds();
 
-      const { orgId } = existingUser
+      const { orgId, otpId } = existingUser
         ? await this.inner.initEmailAuth({
             email: params.email,
+            emailMode: params.emailMode,
             expirationSeconds,
             redirectParams: params.redirectParams,
           })
         : await this.inner.createAccount({
             type: "email",
             email: params.email,
+            emailMode: params.emailMode,
             expirationSeconds,
             redirectParams: params.redirectParams,
           });
 
-      this.sessionManager.setTemporarySession({ orgId });
+      this.sessionManager.setTemporarySession({
+        orgId,
+        isNewUser: !existingUser,
+      });
       this.store.setState({
         status: AlchemySignerStatus.AWAITING_EMAIL_AUTH,
+        otpId,
         error: null,
       });
 
@@ -774,9 +788,7 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   ): Promise<User> => {
     const params: OauthParams = {
       ...args,
-      expirationSeconds: Math.floor(
-        this.sessionManager.expirationTimeMs / 1000
-      ),
+      expirationSeconds: this.getExpirationSeconds(),
     };
     if (params.mode === "redirect") {
       return this.inner.oauthWithRedirect(params);
@@ -785,6 +797,42 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     }
   };
 
+  private authenticateWithOtp = async (
+    args: Extract<AuthParams, { type: "otp" }>
+  ): Promise<User> => {
+    const tempSession = this.sessionManager.getTemporarySession();
+    const { orgId, isNewUser } = tempSession ?? {};
+    const { otpId } = this.store.getState();
+    if (!orgId) {
+      throw new Error("orgId not found in session");
+    }
+    if (!otpId) {
+      throw new Error("otpId not found in session");
+    }
+    const { bundle } = await this.inner.submitOtpCode({
+      orgId,
+      otpId,
+      otpCode: args.otpCode,
+      expirationSeconds: this.getExpirationSeconds(),
+    });
+    const user = await this.inner.completeAuthWithBundle({
+      bundle,
+      orgId,
+      connectedEventName: "connectedOtp",
+      authenticatingType: "otp",
+    });
+
+    this.emitNewUserEvent(isNewUser);
+    if (tempSession) {
+      this.sessionManager.setTemporarySession({
+        ...tempSession,
+        isNewUser: false,
+      });
+    }
+
+    return user;
+  };
+
   private handleOauthReturn = ({
     bundle,
     orgId,
@@ -804,30 +852,39 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     return user;
   };
 
-  private registerListeners = () => {
-    this.sessionManager.on("connected", (session) => {
-      this.store.setState({
-        user: session.user,
-        status: AlchemySignerStatus.CONNECTED,
-        error: null,
-      });
-    });
+  private getExpirationSeconds = () =>
+    Math.floor(this.sessionManager.expirationTimeMs / 1000);
 
-    this.sessionManager.on("disconnected", () => {
-      this.store.setState({
-        user: null,
-        status: AlchemySignerStatus.DISCONNECTED,
-      });
-    });
+  private registerListeners = () => {
+    // Declare listeners in an object to typecheck that every event type is
+    // handled.
+    const listeners: SessionManagerEvents = {
+      connected: (session) => {
+        this.store.setState({
+          user: session.user,
+          status: AlchemySignerStatus.CONNECTED,
+          error: null,
+        });
+      },
+      disconnected: () => {
+        this.store.setState({
+          user: null,
+          status: AlchemySignerStatus.DISCONNECTED,
+        });
+      },
+      initialized: () => {
+        this.store.setState((state) => ({
+          status: state.user
+            ? AlchemySignerStatus.CONNECTED
+            : AlchemySignerStatus.DISCONNECTED,
+          ...(state.user ? { error: null } : undefined),
+        }));
+      },
+    };
 
-    this.sessionManager.on("initialized", () => {
-      this.store.setState((state) => ({
-        status: state.user
-          ? AlchemySignerStatus.CONNECTED
-          : AlchemySignerStatus.DISCONNECTED,
-        ...(state.user ? { error: null } : undefined),
-      }));
-    });
+    for (const [event, listener] of Object.entries(listeners)) {
+      this.sessionManager.on(event as keyof SessionManagerEvents, listener);
+    }
 
     this.inner.on("authenticating", ({ type }) => {
       const status = (() => {
@@ -838,6 +895,9 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
             return AlchemySignerStatus.AUTHENTICATING_PASSKEY;
           case "oauth":
             return AlchemySignerStatus.AUTHENTICATING_OAUTH;
+          case "otp":
+          case "otpVerify":
+            return AlchemySignerStatus.AWAITING_OTP_AUTH;
           default:
             assertNever(type, "unhandled authenticating type");
         }

package/src/client/base.ts

@@ -15,6 +15,7 @@ import type {
   GetWebAuthnAttestationResult,
   OauthConfig,
   OauthParams,
+  OtpParams,
   SignerBody,
   SignerResponse,
   SignerRoutes,
@@ -126,7 +127,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
 
   public abstract initEmailAuth(
     params: Omit<EmailAuthParams, "targetPublicKey">
-  ): Promise<{ orgId: string }>;
+  ): Promise<{ orgId: string; otpId?: string }>;
 
   public abstract completeAuthWithBundle(params: {
     bundle: string;
@@ -144,6 +145,10 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     args: Extract<OauthParams, { mode: "popup" }>
   ): Promise<User>;
 
+  public abstract submitOtpCode(
+    args: Omit<OtpParams, "targetPublicKey">
+  ): Promise<{ bundle: string }>;
+
   public abstract disconnect(): Promise<void>;
 
   public abstract exportWallet(params: TExportWalletParams): Promise<boolean>;

package/src/client/index.ts

@@ -18,6 +18,7 @@ import type {
   ExportWalletParams,
   OauthConfig,
   OauthParams,
+  OtpParams,
   User,
 } from "./types.js";
 
@@ -138,12 +139,13 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
    */
   public override createAccount = async (params: CreateAccountParams) => {
     if (params.type === "email") {
-      this.eventEmitter.emit("authenticating", { type: "email" });
-      const { email, expirationSeconds } = params;
+      this.eventEmitter.emit("authenticating", { type: "otp" });
+      const { email, emailMode, expirationSeconds } = params;
       const publicKey = await this.initIframeStamper();
 
       const response = await this.request("/v1/signup", {
         email,
+        emailMode,
         targetPublicKey: publicKey,
         expirationSeconds,
         redirectParams: params.redirectParams?.toString(),
@@ -205,18 +207,57 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
   public override initEmailAuth = async (
     params: Omit<EmailAuthParams, "targetPublicKey">
   ) => {
-    this.eventEmitter.emit("authenticating", { type: "email" });
-    const { email, expirationSeconds } = params;
+    this.eventEmitter.emit("authenticating", { type: "otp" });
+    const { email, emailMode, expirationSeconds } = params;
     const publicKey = await this.initIframeStamper();
 
     return this.request("/v1/auth", {
       email,
+      emailMode,
       targetPublicKey: publicKey,
       expirationSeconds,
       redirectParams: params.redirectParams?.toString(),
     });
   };
 
+  /**
+   * Authenticates using an OTP code which was previously received via email.
+   *
+   * @example
+   * ```ts
+   * import { AlchemySignerWebClient } from "@account-kit/signer";
+   *
+   * const client = new AlchemySignerWebClient({
+   *  connection: {
+   *    apiKey: "your-api-key",
+   *  },
+   *  iframeConfig: {
+   *   iframeContainerId: "signer-iframe-container",
+   *  },
+   * });
+   *
+   * const account = await client.submitOtpCode({
+   *   orgId: "user-org-id",
+   *   otpId: "opt-returned-from-initEmailAuth",
+   *   otpCode: "otp-code-from-email",
+   * });
+   * ```
+   *
+   * @param {Omit<OtpParams, "targetPublicKey">} args The parameters for the OTP request, excluding the target public key.
+   * @returns {Promise<{ bundle: string }>} A promise that resolves to an object containing the credential bundle.
+   */
+  public override async submitOtpCode(
+    args: Omit<OtpParams, "targetPublicKey">
+  ): Promise<{ bundle: string }> {
+    this.eventEmitter.emit("authenticating", { type: "otpVerify" });
+    const targetPublicKey = await this.initIframeStamper();
+    const { credentialBundle } = await this.request("/v1/otp", {
+      ...args,
+      targetPublicKey,
+    });
+    return { bundle: credentialBundle };
+  }
+
   /**
    * Completes auth for the user by injecting a credential bundle and retrieving
    * the user information based on the provided organization ID. Emits events

package/src/client/types.ts

@@ -28,6 +28,7 @@ export type CreateAccountParams =
   | {
       type: "email";
       email: string;
+      emailMode?: EmailType;
       expirationSeconds?: number;
       redirectParams?: URLSearchParams;
     }
@@ -42,8 +43,11 @@ export type CreateAccountParams =
       creationOpts?: CredentialCreationOptionOverrides;
     };
 
+export type EmailType = "magicLink" | "otp";
+
 export type EmailAuthParams = {
   email: string;
+  emailMode?: EmailType;
   expirationSeconds?: number;
   targetPublicKey: string;
   redirectParams?: URLSearchParams;
@@ -53,10 +57,19 @@ export type OauthParams = Extract<AuthParams, { type: "oauth" }> & {
   expirationSeconds?: number;
 };
 
+export type OtpParams = {
+  orgId: string;
+  otpId: string;
+  otpCode: string;
+  targetPublicKey: string;
+  expirationSeconds?: number;
+};
+
 export type SignupResponse = {
   orgId: string;
   userId?: string;
   address?: Address;
+  otpId?: string;
 };
 
 export type OauthConfig = {
@@ -107,6 +120,7 @@ export type SignerEndpoints = [
     Body: Omit<EmailAuthParams, "redirectParams"> & { redirectParams?: string };
     Response: {
       orgId: string;
+      otpId?: string;
     };
   },
   {
@@ -133,11 +147,16 @@ export type SignerEndpoints = [
       nonce: string;
     };
     Response: OauthConfig;
+  },
+  {
+    Route: "/v1/otp";
+    Body: OtpParams;
+    Response: { credentialBundle: string };
   }
 ];
 
 export type AuthenticatingEventMetadata = {
-  type: "email" | "passkey" | "oauth";
+  type: "email" | "passkey" | "oauth" | "otp" | "otpVerify";
 };
 
 export type AlchemySignerClientEvents = {
@@ -147,6 +166,7 @@ export type AlchemySignerClientEvents = {
   connectedEmail(user: User, bundle: string): void;
   connectedPasskey(user: User): void;
   connectedOauth(user: User, bundle: string): void;
+  connectedOtp(user: User, bundle: string): void;
   disconnected(): void;
 };
 

package/src/metrics.ts

@@ -6,7 +6,12 @@ export type SignerEventsSchema = [
     EventName: "signer_authnticate";
     EventData:
       | {
-          authType: "email" | "passkey_anon" | "passkey_email" | "oauthReturn";
+          authType:
+            | "email"
+            | "passkey_anon"
+            | "passkey_email"
+            | "otp"
+            | "oauthReturn";
           provider?: never;
         }
       | { authType: "oauth"; provider: string };

package/src/session/manager.ts

@@ -7,7 +7,11 @@ import {
 } from "zustand/middleware";
 import { createStore, type Mutate, type StoreApi } from "zustand/vanilla";
 import type { BaseSignerClient } from "../client/base";
-import type { User } from "../client/types";
+import type {
+  AlchemySignerClientEvent,
+  AlchemySignerClientEvents,
+  User,
+} from "../client/types";
 import { assertNever } from "../utils/typeAssertions.js";
 import type { Session, SessionManagerEvents } from "./types";
 
@@ -39,6 +43,8 @@ type Store = Mutate<
   [["zustand/subscribeWithSelector", never], ["zustand/persist", SessionState]]
 >;
 
+type TemporarySession = { orgId: string; isNewUser?: boolean };
+
 export class SessionManager {
   private sessionKey: string;
   private client: BaseSignerClient;
@@ -85,11 +91,18 @@ export class SessionManager {
 
     switch (existingSession.type) {
       case "email":
-      case "oauth": {
-        const connectedEventName =
-          existingSession.type === "email"
-            ? "connectedEmail"
-            : "connectedOauth";
+      case "oauth":
+      case "otp": {
+        const connectedEventName = (() => {
+          switch (existingSession.type) {
+            case "email":
+              return "connectedEmail";
+            case "oauth":
+              return "connectedOauth";
+            case "otp":
+              return "connectedOtp";
+          }
+        })();
         const result = await this.client
           .completeAuthWithBundle({
             bundle: existingSession.bundle,
@@ -133,7 +146,7 @@ export class SessionManager {
     }
   };
 
-  public setTemporarySession = (session: { orgId: string }) => {
+  public setTemporarySession = (session: TemporarySession) => {
     // temporary session must be placed in localStorage so that it can be accessed across tabs
     localStorage.setItem(
       `${this.sessionKey}:temporary`,
@@ -141,7 +154,7 @@ export class SessionManager {
     );
   };
 
-  public getTemporarySession = (): { orgId: string } | null => {
+  public getTemporarySession = (): TemporarySession | null => {
     // temporary session must be placed in localStorage so that it can be accessed across tabs
     const sessionStr = localStorage.getItem(`${this.sessionKey}:temporary`);
 
@@ -187,7 +200,10 @@ export class SessionManager {
 
   private setSession = (
     session_:
-      | Omit<Extract<Session, { type: "email" | "oauth" }>, "expirationDateMs">
+      | Omit<
+          Extract<Session, { type: "email" | "oauth" | "otp" }>,
+          "expirationDateMs"
+        >
       | Omit<Extract<Session, { type: "passkey" }>, "expirationDateMs">
   ) => {
     const session = {
@@ -230,28 +246,45 @@ export class SessionManager {
       }
     );
 
-    this.client.on("disconnected", () => this.clearSession());
-
-    this.client.on("connectedEmail", (user, bundle) =>
-      this.setSessionWithUserAndBundle({ type: "email", user, bundle })
-    );
+    // Helper type to ensure that a listener is either defined or explicitly
+    // omitted for every event type.
+    type Listeners = {
+      [K in keyof AlchemySignerClientEvents]:
+        | AlchemySignerClientEvents[K]
+        | undefined;
+    };
 
-    this.client.on("connectedPasskey", (user) => {
-      const existingSession = this.getSession();
-      if (
-        existingSession != null &&
-        existingSession.type === "passkey" &&
-        existingSession.user.userId === user.userId
-      ) {
-        return;
-      }
+    const listeners: Listeners = {
+      connected: undefined,
+      newUserSignup: undefined,
+      authenticating: undefined,
+      connectedEmail: (user, bundle) =>
+        this.setSessionWithUserAndBundle({ type: "email", user, bundle }),
+      connectedPasskey: (user) => {
+        const existingSession = this.getSession();
+        if (
+          existingSession != null &&
+          existingSession.type === "passkey" &&
+          existingSession.user.userId === user.userId
+        ) {
+          return;
+        }
 
-      this.setSession({ type: "passkey", user });
-    });
+        this.setSession({ type: "passkey", user });
+      },
+      connectedOauth: (user, bundle) =>
+        this.setSessionWithUserAndBundle({ type: "oauth", user, bundle }),
+      connectedOtp: (user, bundle) => {
+        this.setSessionWithUserAndBundle({ type: "otp", user, bundle });
+      },
+      disconnected: () => this.clearSession(),
+    };
 
-    this.client.on("connectedOauth", (user, bundle) =>
-      this.setSessionWithUserAndBundle({ type: "oauth", user, bundle })
-    );
+    for (const [event, listener] of Object.entries(listeners)) {
+      if (listener) {
+        this.client.on(event as AlchemySignerClientEvent, listener);
+      }
+    }
 
     // sync local state if persisted state has changed from another tab
     // only do this in the browser
@@ -295,7 +328,7 @@ export class SessionManager {
     user,
     bundle,
   }: {
-    type: "email" | "oauth";
+    type: "email" | "oauth" | "otp";
     user: User;
     bundle: string;
   }) => {

package/src/session/types.ts

@@ -2,7 +2,7 @@ import type { User } from "../client/types";
 
 export type Session =
   | {
-      type: "email" | "oauth";
+      type: "email" | "oauth" | "otp";
       bundle: string;
       expirationDateMs: number;
       user: User;

package/src/signer.ts

@@ -8,7 +8,12 @@ import type { CredentialCreationOptionOverrides } from "./client/types.js";
 import { SessionManagerParamsSchema } from "./session/manager.js";
 
 export type AuthParams =
-  | { type: "email"; email: string; redirectParams?: URLSearchParams }
+  | {
+      type: "email";
+      email: string;
+      emailMode?: "magicLink" | "otp";
+      redirectParams?: URLSearchParams;
+    }
   | { type: "email"; bundle: string; orgId?: string; isNewUser?: boolean }
   | {
       type: "passkey";
@@ -37,6 +42,10 @@ export type AuthParams =
       orgId: string;
       idToken: string;
       isNewUser?: boolean;
+    }
+  | {
+      type: "otp";
+      otpCode: string;
     };
 
 export type OauthProviderConfig =

package/src/types.ts

@@ -18,6 +18,7 @@ export enum AlchemySignerStatus {
   AUTHENTICATING_EMAIL = "AUTHENTICATING_EMAIL",
   AUTHENTICATING_OAUTH = "AUTHENTICATING_OAUTH",
   AWAITING_EMAIL_AUTH = "AWAITING_EMAIL_AUTH",
+  AWAITING_OTP_AUTH = "AWAITING_OTP_AUTH",
 }
 
 export interface ErrorInfo {

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is autogenerated by inject-version.ts. Any changes will be
 // overwritten on commit!
-export const VERSION = "4.6.1";
+export const VERSION = "4.8.0";