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

package/src/client/index.ts

@@ -40,6 +40,29 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
   private webauthnStamper: WebauthnStamper;
   iframeContainerId: string;
 
+  /**
+   * Initializes a new instance with the given parameters, setting up the connection, iframe configuration, and WebAuthn stamper.
+   *
+   * @example
+   * ```ts
+   * import { AlchemySignerWebClient } from "@account-kit/signer";
+   *
+   * const client = new AlchemySignerWebClient({
+   *  connection: {
+   *    apiKey: "your-api-key",
+   *  },
+   *  iframeConfig: {
+   *   iframeContainerId: "signer-iframe-container",
+   *  },
+   * });
+   * ```
+   *
+   * @param {AlchemySignerClientParams} params the parameters required to initialize the client
+   * @param {ConnectionConfig} params.connection The connection details needed to connect to the service
+   * @param {{ iframeElementId?: string; iframeContainerId: string }} params.iframeConfig The configuration details for setting up the iframe stamper
+   * @param {string} params.rpId The relying party ID, defaulting to the current hostname if not provided
+   * @param {string} params.rootOrgId The root organization ID
+   */
   constructor(params: AlchemySignerClientParams) {
     const { connection, iframeConfig, rpId, rootOrgId } =
       AlchemySignerClientParamsSchema.parse(params);
@@ -64,7 +87,29 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     });
   }
 
-  public createAccount = async (params: CreateAccountParams) => {
+  /**
+   * Authenticates the user by either email or passkey account creation flow. Emits events during the process.
+   *
+   * @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.createAccount({ type: "email", email: "you@mail.com" });
+   * ```
+   *
+   * @param {CreateAccountParams} params The parameters for creating an account, including the type (email or passkey) and additional details.
+   * @returns {Promise<SignupResponse>} A promise that resolves with the response object containing the account creation result.
+   */
+  createAccount = async (params: CreateAccountParams) => {
     this.eventEmitter.emit("authenticating");
     if (params.type === "email") {
       const { email, expirationSeconds } = params;
@@ -83,7 +128,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     // Passkey account creation flow
     const { attestation, challenge } = await this.getWebAuthnAttestation(
       params.creationOpts,
-      { username: params.username }
+      { username: "email" in params ? params.email : params.username }
     );
 
     const result = await this.request("/v1/signup", {
@@ -91,6 +136,7 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
         challenge: base64UrlEncode(challenge),
         attestation,
       },
+      email: "email" in params ? params.email : undefined,
     });
 
     this.user = {
@@ -105,6 +151,29 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     return result;
   };
 
+  /**
+   * Begin authenticating a user with their email and an expiration time for the authentication request. Initializes the iframe stamper to get the target public key.
+   * This method sends an email to the user to complete their login
+   *
+   * @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.initEmailAuth({ email: "you@mail.com" });
+   * ```
+   *
+   * @param {Omit<EmailAuthParams, "targetPublicKey">} params The parameters for email authentication, excluding the target public key
+   * @returns {Promise<any>} The response from the authentication request
+   */
   public initEmailAuth = async (
     params: Omit<EmailAuthParams, "targetPublicKey">
   ) => {
@@ -120,6 +189,28 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     });
   };
 
+  /**
+   * Completes email auth for the user by injecting a credential bundle and retrieving the user information based on the provided organization ID. Emits events during the process.
+   *
+   * @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.completeEmailAuth({ orgId: "user-org-id", bundle: "bundle-from-email" });
+   * ```
+   *
+   * @param {{ bundle: string; orgId: string }} config The configuration object for the authentication function containing the credential bundle to inject and the organization id associated with the user
+   * @returns {Promise<User>} A promise that resolves to the authenticated user information
+   */
   public completeEmailAuth = async ({
     bundle,
     orgId,
@@ -142,6 +233,28 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     return user;
   };
 
+  /**
+   * Asynchronously handles the authentication process using WebAuthn Stamper. If a user is provided, sets the user and returns it. Otherwise, retrieves the current user and initializes the WebAuthn stamper.
+   *
+   * @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.lookupUserWithPasskey();
+   * ```
+   *
+   * @param {User} [user] An optional user object to authenticate
+   * @returns {Promise<User>} A promise that resolves to the authenticated user object
+   */
   public lookupUserWithPasskey = async (user: User | undefined = undefined) => {
     this.eventEmitter.emit("authenticating");
     await this.initWebauthnStamper(user);
@@ -157,6 +270,33 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     return result;
   };
 
+  /**
+   * Initiates the export of a wallet by creating an iframe stamper and calling the appropriate export function.
+   * The export can be based on a seed phrase or a private key.
+   *
+   * @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.exportWallet({
+   *  iframeContainerId: "export-iframe-container",
+   * });
+   * ```
+   *
+   * @param {ExportWalletParams} config The parameters for exporting the wallet
+   * @param {string} config.iframeContainerId The ID of the container element that will hold the iframe stamper
+   * @param {string} [config.iframeElementId] Optional ID for the iframe element
+   * @returns {Promise<void>} A promise that resolves when the export process is complete
+   */
   public exportWallet = async ({
     iframeContainerId,
     iframeElementId = "turnkey-export-iframe",
@@ -181,6 +321,25 @@ export class AlchemySignerWebClient extends BaseSignerClient<ExportWalletParams>
     });
   };
 
+  /**
+   * Asynchronous function that clears the user and resets the iframe stamper.
+   *
+   * @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.disconnect();
+   * ```
+   */
   public disconnect = async () => {
     this.user = undefined;
     this.iframeStamper.clear();

package/src/client/types.ts

@@ -28,6 +28,11 @@ export type CreateAccountParams =
       expirationSeconds?: number;
       redirectParams?: URLSearchParams;
     }
+  | {
+      type: "passkey";
+      email: string;
+      creationOpts?: CredentialCreationOptionOverrides;
+    }
   | {
       type: "passkey";
       username: string;

package/src/index.ts

@@ -1,10 +1,9 @@
-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";

package/src/signer.ts

@@ -10,6 +10,11 @@ import { SessionManagerParamsSchema } from "./session/manager.js";
 export type AuthParams =
   | { type: "email"; email: string; redirectParams?: URLSearchParams }
   | { type: "email"; bundle: string; orgId?: string }
+  | {
+      type: "passkey";
+      email: string;
+      creationOpts?: CredentialCreationOptionOverrides;
+    }
   | {
       type: "passkey";
       createNew: false;
@@ -37,15 +42,36 @@ export type AlchemySignerParams = z.input<typeof AlchemySignerParamsSchema>;
  * A SmartAccountSigner that can be used with any SmartContractAccount
  */
 export class AlchemyWebSigner extends BaseAlchemySigner<AlchemySignerWebClient> {
-  constructor(params_: AlchemySignerParams) {
-    const { sessionConfig, ...params } =
-      AlchemySignerParamsSchema.parse(params_);
+  /**
+   * 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) {
+    const { sessionConfig, ...params_ } =
+      AlchemySignerParamsSchema.parse(params);
 
     let client: AlchemySignerWebClient;
-    if ("connection" in params.client) {
-      client = new AlchemySignerWebClient(params.client);
+    if ("connection" in params_.client) {
+      client = new AlchemySignerWebClient(params_.client);
     } else {
-      client = params.client;
+      client = params_.client;
     }
     super({
       client,

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.0.0-alpha.1";
+export const VERSION = "4.0.0-alpha.11";