@account-kit/signer 4.0.0-alpha.0 → 4.0.0-alpha.10

package/src/base.ts

@@ -44,6 +44,10 @@ type InternalStore = Mutate<
   [["zustand/subscribeWithSelector", never]]
 >;
 
+/**
+ * Base abstract class for Alchemy Signer, providing authentication and session management for smart accounts.
+ * Implements the `SmartAccountAuthenticator` interface and handles various signer events.
+ */
 export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   implements SmartAccountAuthenticator<AuthParams, User, TClient>
 {
@@ -52,6 +56,15 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   private sessionManager: SessionManager;
   private store: InternalStore;
 
+  /**
+   * Initializes an instance with the provided client and session configuration.
+   * This function sets up the internal store, initializes the session manager,
+   * registers listeners and initializes the session manager to manage session state.
+   *
+   * @param {BaseAlchemySignerParams<TClient>} param0 Object containing the client and session configuration
+   * @param {TClient} param0.client The client instance to be used internally
+   * @param {SessionConfig} param0.sessionConfig Configuration for managing sessions
+   */
   constructor({ client, sessionConfig }: BaseAlchemySignerParams<TClient>) {
     this.inner = client;
     this.store = createStore(
@@ -88,9 +101,9 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   /**
    * Allows you to subscribe to events emitted by the signer
    *
-   * @param event the event to subscribe to
-   * @param listener the function to run when the event is emitted
-   * @returns a function to remove the listener
+   * @param {AlchemySignerEvent} event the event to subscribe to
+   * @param {AlchemySignerEvents[AlchemySignerEvent]} listener the function to run when the event is emitted
+   * @returns {() => void} a function to remove the listener
    */
   on = <E extends AlchemySignerEvent>(
     event: E,
@@ -132,8 +145,29 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   /**
    * Authenticate a user with either an email or a passkey and create a session for that user
    *
-   * @param params - undefined if passkey login, otherwise an object with email and bundle to resolve
-   * @returns the user that was authenticated
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const result = await signer.authenticate({
+   *  type: "email",
+   *  email: "foo@mail.com",
+   * });
+   * ```
+   *
+   * @param {AuthParams} params - undefined if passkey login, otherwise an object with email and bundle to resolve
+   * @returns {Promise<User>} the user that was authenticated
    */
   authenticate: (params: AuthParams) => Promise<User> = async (params) => {
     if (params.type === "email") {
@@ -144,7 +178,27 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   };
 
   /**
-   * NOTE: right now this only clears the session locally.
+   * Clear a user session and log them out
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * await signer.disconnect();
+   * ```
+   *
+   * @returns {Promise<void>} a promise that resolves when the user is logged out
    */
   disconnect: () => Promise<void> = async () => {
     await this.inner.disconnect();
@@ -155,10 +209,29 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * If a user has an ongoing session, it will use that session and
    * try to authenticate
    *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * // throws if not logged in
+   * const user = await signer.getAuthDetails();
+   * ```
+   *
    * @throws if there is no user logged in
-   * @returns the current user
+   * @returns {Promise<User>} the current user
    */
-  getAuthDetails: () => Promise<User> = async () => {
+  getAuthDetails = async (): Promise<User> => {
     const sessionUser = await this.sessionManager.getSessionUser();
     if (sessionUser != null) {
       return sessionUser;
@@ -167,12 +240,41 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     return this.inner.whoami();
   };
 
+  /**
+   * Retrieves the address of the current user by calling the `whoami` method on `this.inner`.
+   *
+   * @returns {Promise<string>} A promise that resolves to the address of the current user.
+   */
   getAddress: () => Promise<`0x${string}`> = async () => {
     const { address } = await this.inner.whoami();
 
     return address;
   };
 
+  /**
+   * Signs a raw message after hashing it.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const signature = await signer.signMessage("Hello, world!");
+   * ```
+   *
+   * @param {string} msg the message to be hashed and then signed
+   * @returns {Promise<string>} a promise that resolves to the signed message
+   */
   signMessage: (msg: SignableMessage) => Promise<`0x${string}`> = async (
     msg
   ) => {
@@ -181,6 +283,35 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     return this.inner.signRawMessage(messageHash);
   };
 
+  /**
+   * Signs a typed message by first hashing it and then signing the hashed message using the `signRawMessage` method.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const signature = await signer.signTypedData({
+   *  domain: {},
+   *  types: {},
+   *  primaryType: "",
+   *  message: {},
+   * });
+   * ```
+   *
+   * @param {TypedDataDefinition<TTypedData, TPrimaryType>} params The parameters for the typed message to be hashed and signed
+   * @returns {Promise<any>} A promise that resolves to the signed message
+   */
   signTypedData: <
     const TTypedData extends TypedData | { [key: string]: unknown },
     TPrimaryType extends keyof TTypedData | "EIP712Domain" = keyof TTypedData
@@ -192,6 +323,36 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     return this.inner.signRawMessage(messageHash);
   };
 
+  /**
+   * Serializes a transaction, signs it with a raw message, and then returns the serialized transaction with the signature.
+   *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const tx = await signer.signTransaction({
+   *  to: "0x1234",
+   *  value: "0x1234",
+   *  data: "0x1234",
+   * });
+   * ```
+   *
+   * @param {Transaction} tx the transaction to be serialized and signed
+   * @param {{serializer?: SerializeTransactionFn}} args options for serialization
+   * @param {() => Hex} [args.serializer] an optional serializer function. If not provided, the default `serializeTransaction` function will be used
+   * @returns {Promise<string>} a promise that resolves to the serialized transaction with the signature
+   */
   signTransaction: CustomSource["signTransaction"] = async (tx, args) => {
     const serializeFn = args?.serializer ?? serializeTransaction;
     const serializedTx = serializeFn(tx);
@@ -211,8 +372,26 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   /**
    * Unauthenticated call to look up a user's organizationId by email
    *
-   * @param email the email to lookup
-   * @returns the organization id for the user if they exist
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const result = await signer.getUser("foo@mail.com");
+   * ```
+   *
+   * @param {string} email the email to lookup
+   * @returns {Promise<{orgId: string}>} the organization id for the user if they exist
    */
   getUser: (email: string) => Promise<{ orgId: string } | null> = async (
     email
@@ -231,8 +410,26 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
   /**
    * Adds a passkey to the user's account
    *
-   * @param params optional parameters for the passkey creation
-   * @returns an array of the authenticator ids added to the user
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const result = await signer.addPasskey()
+   * ```
+   *
+   * @param {CredentialCreationOptions | undefined} params optional parameters for the passkey creation
+   * @returns {Promise<string[]>} an array of the authenticator ids added to the user
    */
   addPasskey: (params?: CredentialCreationOptions) => Promise<string[]> =
     async (params) => {
@@ -244,8 +441,27 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * If the user is authenticated with an Email, this will return a seed phrase
    * If the user is authenticated with a Passkey, this will return a private key
    *
-   * @param params export wallet parameters
-   * @returns true if the wallet was exported successfully
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * // the params passed to this are different based on the specific signer
+   * const result = signer.exportWallet()
+   * ```
+   *
+   * @param {unknown} params export wallet parameters
+   * @returns {boolean} true if the wallet was exported successfully
    */
   exportWallet: (
     params: Parameters<(typeof this.inner)["exportWallet"]>[0]
@@ -257,10 +473,28 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
    * This method lets you adapt your AlchemySigner to a viem LocalAccount, which
    * will let you use the signer as an EOA directly.
    *
+   * @example
+   * ```ts
+   * import { AlchemyWebSigner } from "@account-kit/signer";
+   *
+   * const signer = new AlchemyWebSigner({
+   *  client: {
+   *    connection: {
+   *      rpcUrl: "/api/rpc",
+   *    },
+   *    iframeConfig: {
+   *      iframeContainerId: "alchemy-signer-iframe-container",
+   *    },
+   *  },
+   * });
+   *
+   * const account = signer.toViemAccount();
+   * ```
+   *
    * @throws if your signer is not authenticated
-   * @returns a LocalAccount object that can be used with viem's wallet client
+   * @returns {LocalAccount} a LocalAccount object that can be used with viem's wallet client
    */
-  toViemAccount: () => LocalAccount = () => {
+  toViemAccount = (): LocalAccount => {
     // if we want this method to be synchronous, then we need to do this check here
     // otherwise we can use the sessionManager to get the user
     if (!this.inner.getUser()) {

package/src/client/base.ts

@@ -30,6 +30,9 @@ export type ExportWalletStamper = TurnkeyClient["stamper"] & {
   publicKey(): string | null;
 };
 
+/**
+ * Base class for all Alchemy Signer clients
+ */
 export abstract class BaseSignerClient<TExportWalletParams = unknown> {
   private _user: User | undefined;
   private connectionConfig: ConnectionConfig;
@@ -37,6 +40,11 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
   protected rootOrg: string;
   protected eventEmitter: EventEmitter<AlchemySignerClientEvents>;
 
+  /**
+   * Create a new instance of the Alchemy Signer client
+   *
+   * @param {BaseSignerClientParams} params the parameters required to create the client
+   */
   constructor(params: BaseSignerClientParams) {
     const { stamper, connection, rootOrgId } = params;
 
@@ -63,10 +71,23 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     this._user = user;
   }
 
+  /**
+   * Sets the stamper of the TurnkeyClient.
+   *
+   * @param {TurnkeyClient["stamper"]} stamper the stamper function to set for the TurnkeyClient
+   */
   protected setStamper(stamper: TurnkeyClient["stamper"]) {
     this.turnkeyClient.stamper = stamper;
   }
 
+  /**
+   * Exports wallet credentials based on the specified type, either as a SEED_PHRASE or PRIVATE_KEY.
+   *
+   * @param {object} params The parameters for exporting the wallet
+   * @param {ExportWalletStamper} params.exportStamper The stamper used for exporting the wallet
+   * @param {"SEED_PHRASE" | "PRIVATE_KEY"} params.exportAs Specifies the format for exporting the wallet, either as a SEED_PHRASE or PRIVATE_KEY
+   * @returns {Promise<boolean>} A promise that resolves to true if the export is successful
+   */
   protected exportWalletInner(params: {
     exportStamper: ExportWalletStamper;
     exportAs: "SEED_PHRASE" | "PRIVATE_KEY";
@@ -112,9 +133,9 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
   /**
    * Listen to events emitted by the client
    *
-   * @param event the event you want to listen to
-   * @param listener the callback function to execute when an event is fired
-   * @returns a function that will remove the listener when called
+   * @param {AlchemySignerClientEvent} event the event you want to listen to
+   * @param {AlchemySignerClientEvents[AlchemySignerClientEvent]} listener the callback function to execute when an event is fired
+   * @returns {() => void} a function that will remove the listener when called
    */
   public on = <E extends AlchemySignerClientEvent>(
     event: E,
@@ -125,6 +146,13 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     return () => this.eventEmitter.removeListener(event, listener as any);
   };
 
+  /**
+   * Handles the creation of authenticators using WebAuthn attestation and the provided options. Requires the user to be authenticated.
+   *
+   * @param {CredentialCreationOptions} options The options used to create the WebAuthn attestation
+   * @returns {Promise<string[]>} A promise that resolves to an array of authenticator IDs
+   * @throws {NotAuthenticatedError} If the user is not authenticated
+   */
   public addPasskey = async (options: CredentialCreationOptions) => {
     if (!this.user) {
       throw new NotAuthenticatedError();
@@ -158,6 +186,13 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     return authenticatorIds;
   };
 
+  /**
+   * Retrieves the current user or fetches the user information if not already available.
+   *
+   * @param {string} [orgId] optional organization ID, defaults to the user's organization ID
+   * @returns {Promise<User>} A promise that resolves to the user object
+   * @throws {Error} if no organization ID is provided when there is no current user
+   */
   public whoami = async (orgId = this.user?.orgId): Promise<User> => {
     if (this.user) {
       return this.user;
@@ -192,6 +227,12 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     return this.user;
   };
 
+  /**
+   * Looks up information based on an email address.
+   *
+   * @param {string} email the email address to look up
+   * @returns {Promise<any>} the result of the lookup request
+   */
   public lookupUserByEmail = async (email: string) => {
     return this.request("/v1/lookup", { email });
   };
@@ -201,10 +242,10 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
    * For SignMessage or SignTypedData, the caller should hash the message before calling this method and pass
    * that result here.
    *
-   * @param msg the hex representation of the bytes to sign
-   * @returns the signature over the raw hex
+   * @param {Hex} msg the hex representation of the bytes to sign
+   * @returns {Promise<Hex>} the signature over the raw hex
    */
-  public signRawMessage = async (msg: Hex) => {
+  public signRawMessage = async (msg: Hex): Promise<Hex> => {
     if (!this.user) {
       throw new NotAuthenticatedError();
     }
@@ -228,10 +269,23 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     return signature;
   };
 
+  /**
+   * Returns the current user or null if no user is set.
+   *
+   * @returns {User | null} the current user object or null if no user is available
+   */
   public getUser = (): User | null => {
     return this.user ?? null;
   };
 
+  /**
+   * Sends a POST request to the given signer route with the specified body and returns the response.
+   * Not intended to be used directly, use the specific methods instead on the client instead.
+   *
+   * @param {SignerRoutes} route The route to which the request should be sent
+   * @param {SignerBody<R>} body The request body containing the data to be sent
+   * @returns {Promise<SignerResponse<R>>} A promise that resolves to the response from the signer
+   */
   public request = async <R extends SignerRoutes>(
     route: R,
     body: SignerBody<R>
@@ -348,6 +402,7 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     return result;
   };
 
+  // eslint-disable-next-line eslint-rules/require-jsdoc-on-reexported-functions
   protected pollActivityCompletion = async <
     T extends keyof Awaited<
       ReturnType<(typeof this.turnkeyClient)["getActivity"]>