@account-kit/signer 4.0.0-alpha.1 → 4.0.0-alpha.11

package/dist/types/index.d.ts

@@ -1,9 +1,10 @@
-export type * from "./signer.js";
-export { AlchemyWebSigner } from "./signer.js";
-export type * from "./types.js";
-export { AlchemySignerStatus } from "./types.js";
+export { BaseAlchemySigner } from "./base.js";
 export { BaseSignerClient } from "./client/base.js";
 export { AlchemySignerWebClient } from "./client/index.js";
 export type * from "./client/types.js";
 export { DEFAULT_SESSION_MS } from "./session/manager.js";
+export type * from "./signer.js";
+export { AlchemyWebSigner } from "./signer.js";
+export type * from "./types.js";
+export { AlchemySignerStatus } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,aAAa,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,mBAAmB,mBAAmB,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,mBAAmB,mBAAmB,CAAC;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,mBAAmB,aAAa,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,mBAAmB,YAAY,CAAC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/types/signer.d.ts

@@ -10,6 +10,10 @@ export type AuthParams = {
     type: "email";
     bundle: string;
     orgId?: string;
+} | {
+    type: "passkey";
+    email: string;
+    creationOpts?: CredentialCreationOptionOverrides;
 } | {
     type: "passkey";
     createNew: false;
@@ -48,9 +52,6 @@ export declare const AlchemySignerParamsSchema: z.ZodObject<{
         }>, z.ZodObject<{
             rpcUrl: z.ZodString;
             apiKey: z.ZodOptional<z.ZodNever>;
-            /**
-             * A SmartAccountSigner that can be used with any SmartContractAccount
-             */
             jwt: z.ZodOptional<z.ZodNever>;
         }, "strip", z.ZodTypeAny, {
             rpcUrl: string;
@@ -264,6 +265,27 @@ export type AlchemySignerParams = z.input<typeof AlchemySignerParamsSchema>;
  * A SmartAccountSigner that can be used with any SmartContractAccount
  */
 export declare class AlchemyWebSigner extends BaseAlchemySigner<AlchemySignerWebClient> {
-    constructor(params_: AlchemySignerParams);
+    /**
+     * Initializes an instance with the provided Alchemy signer parameters after parsing them with a schema.
+     *
+     * @example
+     * ```ts
+     * import { AlchemyWebSigner } from "@account-kit/signer";
+     *
+     * const signer = new AlchemyWebSigner({
+     *  client: {
+     *    connection: {
+     *      rpcUrl: "/api/rpc",
+     *    },
+     *    iframeConfig: {
+     *      iframeContainerId: "alchemy-signer-iframe-container",
+     *    },
+     *  },
+     * });
+     * ```
+     *
+     * @param {AlchemySignerParams} params The parameters for the Alchemy signer, including the client and session configuration
+     */
+    constructor(params: AlchemySignerParams);
 }
 //# sourceMappingURL=signer.d.ts.map

package/dist/types/signer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAEL,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,mBAAmB,CAAC;AAG3E,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,eAAe,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;CAClB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,iCAAiC,CAAC;CAClD,CAAC;AAEN,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAYtC;;eAEG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EANC,CAAC;AAEL,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB,CAAC,sBAAsB,CAAC;gBACjE,OAAO,EAAE,mBAAmB;CAezC"}
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAEL,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,mBAAmB,CAAC;AAG3E,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,eAAe,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,iCAAiC,CAAC;CAClD,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;CAClB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,iCAAiC,CAAC;CAClD,CAAC;AAEN,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQlC,CAAC;AAEL,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB,CAAC,sBAAsB,CAAC;IAC7E;;;;;;;;;;;;;;;;;;;;OAoBG;gBACS,MAAM,EAAE,mBAAmB;CAexC"}

package/dist/types/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "4.0.0-alpha.1";
+export declare const VERSION = "4.0.0-alpha.11";
 //# sourceMappingURL=version.d.ts.map

package/dist/types/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,OAAO,kBAAkB,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,OAAO,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@account-kit/signer",
-  "version": "4.0.0-alpha.1",
+  "version": "4.0.0-alpha.11",
   "description": "Core interfaces and clients for interfacing with the Alchemy Signer API",
   "author": "Alchemy",
   "license": "MIT",
@@ -34,6 +34,7 @@
     "build:cjs": "tsc --project tsconfig.build.json --module commonjs --outDir ./dist/cjs --removeComments --verbatimModuleSyntax false && echo > ./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
     "build:esm": "tsc --project tsconfig.build.json --module es2020 --outDir ./dist/esm --removeComments && echo > ./dist/esm/package.json '{\"type\":\"module\"}'",
     "build:types": "tsc --project tsconfig.build.json --module esnext --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
+    "docs:gen": "npx ak-docgen generate --in ./src/index.ts --out ../../site/pages/reference/account-kit/signer",
     "clean": "rm -rf ./dist",
     "test": "vitest --passWithNoTests",
     "test:run": "vitest run --passWithNoTests",
@@ -46,10 +47,10 @@
     "tailwindcss": "^3.4.3",
     "typescript": "^5.0.4",
     "typescript-template": "*",
-    "vitest": "^0.31.0"
+    "vitest": "^2.0.4"
   },
   "dependencies": {
-    "@aa-sdk/core": "^4.0.0-alpha.1",
+    "@aa-sdk/core": "^4.0.0-alpha.11",
     "@turnkey/http": "^2.6.2",
     "@turnkey/iframe-stamper": "^1.0.0",
     "@turnkey/viem": "^0.4.8",
@@ -75,5 +76,5 @@
     "url": "https://github.com/alchemyplatform/aa-sdk/issues"
   },
   "homepage": "https://github.com/alchemyplatform/aa-sdk#readme",
-  "gitHead": "cb4bf5f8a9aa8fdff1610130821b69ff806e79e6"
+  "gitHead": "7dde8daa73a0bee97f3c0068d7e4818669db9a26"
 }

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()) {
@@ -336,8 +570,22 @@ export abstract class BaseAlchemySigner<TClient extends BaseSignerClient>
     args: Extract<AuthParams, { type: "passkey" }>
   ) => {
     let user: User;
-    if (args.createNew) {
-      const result = await this.inner.createAccount(args);
+    const shouldCreateNew = async () => {
+      if ("email" in args) {
+        const existingUser = await this.getUser(args.email);
+        return existingUser == null;
+      }
+
+      return args.createNew;
+    };
+
+    if (await shouldCreateNew()) {
+      const result = await this.inner.createAccount(
+        args as Extract<
+          AuthParams,
+          { type: "passkey" } & ({ email: string } | { createNew: true })
+        >
+      );
       // account creation for passkeys returns the whoami response so we don't have to
       // call it again after signup
       user = {

package/src/client/base.ts

@@ -1,5 +1,5 @@
-import { type ConnectionConfig, ConnectionConfigSchema } from "@aa-sdk/core";
-import { TurnkeyClient } from "@turnkey/http";
+import { ConnectionConfigSchema, type ConnectionConfig } from "@aa-sdk/core";
+import { TurnkeyClient, type TSignedRequest } from "@turnkey/http";
 import EventEmitter from "eventemitter3";
 import type { Hex } from "viem";
 import { NotAuthenticatedError } from "../errors.js";
@@ -71,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";
@@ -120,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,
@@ -133,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();
@@ -166,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;
@@ -200,6 +227,31 @@ export abstract class BaseSignerClient<TExportWalletParams = unknown> {
     return this.user;
   };
 
+  /**
+   * Generates a stamped whoami request for the current user. This request can then be used to call /signer/v1/whoami to get the user information.
+   * This is useful if you want to get the user information in a different context like a server. You can pass the stamped request to the server
+   * and then call our API to get the user information. Using this stamp is the most trusted way to get the user information since a stamp can only
+   * belong to the user who created it.
+   *
+   * @returns {Promise<TSignedRequest>} a promise that resolves to the "whoami" information for the logged in user
+   * @throws {Error} if no organization ID is provided
+   */
+  public stampWhoami = async (): Promise<TSignedRequest> => {
+    if (!this.user) {
+      throw new Error("User must be authenticated to stamp a whoami request");
+    }
+
+    return await this.turnkeyClient.stampGetWhoami({
+      organizationId: this.user.orgId,
+    });
+  };
+
+  /**
+   * 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 });
   };
@@ -209,10 +261,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();
     }
@@ -236,10 +288,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>
@@ -356,6 +421,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"]>