docs(types): Add JSDoc comments (#6994)

Author: dstaley

.changeset/khaki-beers-argue.md

@@ -0,0 +1,2 @@
+---
+---

packages/types/src/signInFuture.ts

@@ -5,84 +5,164 @@ import type { OAuthStrategy, Web3Strategy } from './strategies';
 import type { VerificationResource } from './verification';
 
 export interface SignInFutureCreateParams {
+  /**
+   * The authentication identifier for the sign-in. This can be the value of the user's email address, phone number,
+   * username, or Web3 wallet address.
+   */
   identifier?: string;
+  /**
+   * The first factor verification strategy to use in the sign-in flow. Depends on the `identifier` value. Each
+   * authentication identifier supports different verification strategies.
+   */
   strategy?: OAuthStrategy | 'saml' | 'enterprise_sso';
+  /**
+   * The full URL or path that the OAuth provider should redirect to after successful authorization on their part.
+   */
   redirectUrl?: string;
+  /**
+   * The URL that the user will be redirected to, after successful authorization from the OAuth provider and
+   * Clerk sign-in.
+   */
   actionCompleteRedirectUrl?: string;
+  /**
+   * When set to `true`, the `SignIn` will attempt to retrieve information from the active `SignUp` instance and use it
+   * to complete the sign-in process. This is useful when you want to seamlessly transition a user from a sign-up
+   * attempt to a sign-in attempt.
+   */
   transfer?: boolean;
+  /**
+   * The [ticket _or token_](https://clerk.com/docs/guides/development/custom-flows/authentication/application-invitations)
+   * generated from the Backend API. **Required** if `strategy` is set to `'ticket'`.
+   */
   ticket?: string;
 }
 
-export type SignInFuturePasswordParams =
+export type SignInFuturePasswordParams = {
+  /**
+   * The user's password. Only supported if
+   * [password](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#password) is enabled.
+   */
+  password: string;
+} & (
   | {
-      password: string;
+      /**
+       * The authentication identifier for the sign-in. This can be the value of the user's email address, phone number,
+       * username, or Web3 wallet address.
+       */
       identifier: string;
       emailAddress?: never;
       phoneNumber?: never;
     }
   | {
-      password: string;
+      /**
+       * The user's email address. Only supported if [Email address](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email)
+       * is enabled.
+       */
       emailAddress: string;
       identifier?: never;
       phoneNumber?: never;
     }
   | {
-      password: string;
+      /**
+       * The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164). Only supported if
+       * [phone number](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#phone) is enabled.
+       */
       phoneNumber: string;
       identifier?: never;
       emailAddress?: never;
     }
   | {
-      password: string;
       phoneNumber?: never;
       identifier?: never;
       emailAddress?: never;
-    };
+    }
+);
 
 export type SignInFutureEmailCodeSendParams =
   | {
+      /**
+       * The user's email address. Only supported if [Email address](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email)
+       * is enabled.
+       */
       emailAddress?: string;
       emailAddressId?: never;
     }
   | {
+      /**
+       * The ID for the user's email address that will receive an email with the one-time authentication code.
+       */
       emailAddressId?: string;
       emailAddress?: never;
     };
 
-export type SignInFutureEmailLinkSendParams =
+export type SignInFutureEmailLinkSendParams = {
+  /**
+   * The full URL that the user will be redirected to when they visit the email link.
+   */
+  verificationUrl: string;
+} & (
   | {
+      /**
+       * The user's email address. Only supported if [Email address](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email)
+       * is enabled.
+       */
       emailAddress?: string;
-      verificationUrl: string;
       emailAddressId?: never;
     }
   | {
+      /**
+       * The ID for the user's email address that will receive an email with the email link.
+       */
       emailAddressId?: string;
-      verificationUrl: string;
       emailAddress?: never;
-    };
+    }
+);
 
 export interface SignInFutureEmailCodeVerifyParams {
+  /**
+   * The one-time code that was sent to the user.
+   */
   code: string;
 }
 
 export interface SignInFutureResetPasswordSubmitParams {
+  /**
+   * The new password for the user.
+   */
   password: string;
+  /**
+   * If `true`, signs the user out of all other authenticated sessions.
+   */
   signOutOfOtherSessions?: boolean;
 }
 
-export type SignInFuturePhoneCodeSendParams =
+export type SignInFuturePhoneCodeSendParams = {
+  /**
+   * The mechanism to use to send the code to the provided phone number. Defaults to `'sms'`.
+   */
+  channel?: PhoneCodeChannel;
+} & (
   | {
+      /**
+       * The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164). Only supported if
+       * [phone number](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#phone) is enabled.
+       */
       phoneNumber?: string;
-      channel?: PhoneCodeChannel;
       phoneNumberId?: never;
     }
   | {
+      /**
+       * The ID for the user's phone number that will receive a message with the one-time authentication code.
+       */
       phoneNumberId: string;
-      channel?: PhoneCodeChannel;
       phoneNumber?: never;
-    };
+    }
+);
 
 export interface SignInFuturePhoneCodeVerifyParams {
+  /**
+   * The one-time code that was sent to the user.
+   */
   code: string;
 }
 
@@ -100,22 +180,38 @@ export interface SignInFutureSSOParams {
 }
 
 export interface SignInFutureMFAPhoneCodeVerifyParams {
+  /**
+   * The one-time code that was sent to the user as part of the `signIn.mfa.sendPhoneCode()` method.
+   */
   code: string;
 }
 
 export interface SignInFutureTOTPVerifyParams {
+  /**
+   * The TOTP generated by the user's authenticator app.
+   */
   code: string;
 }
 
 export interface SignInFutureBackupCodeVerifyParams {
+  /**
+   * The backup code that was provided to the user when they set up two-step authentication.
+   */
   code: string;
 }
 
 export interface SignInFutureTicketParams {
+  /**
+   * The [ticket _or token_](https://clerk.com/docs/guides/development/custom-flows/authentication/application-invitations)
+   * generated from the Backend API.
+   */
   ticket: string;
 }
 
 export interface SignInFutureWeb3Params {
+  /**
+   * The verification strategy to validate the user's sign-in request.
+   */
   strategy: Web3Strategy;
 }
 
@@ -124,7 +220,9 @@ export interface SignInFutureFinalizeParams {
 }
 
 /**
- * The current active `SignIn` instance, for use in custom flows.
+ * The `SignInFuture` class holds the state of the current sign-in and provides helper methods to navigate and complete
+ * the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification,
+ * and the creation of a new session.
  */
 export interface SignInFutureResource {
   /**
@@ -133,18 +231,19 @@ export interface SignInFutureResource {
   readonly id?: string;
 
   /**
-   * The list of first-factor strategies that are available for the current sign-in attempt.
+   * Array of the first factors that are supported in the current sign-in. Each factor contains information about the
+   * verification strategy that can be used.
    */
   readonly supportedFirstFactors: SignInFirstFactor[];
 
   /**
-   * The list of second-factor strategies that are available for the current sign-in attempt.
+   * Array of the second factors that are supported in the current sign-in. Each factor contains information about the
+   * verification strategy that can be used. This property is populated only when the first factor is verified.
    */
   readonly supportedSecondFactors: SignInSecondFactor[];
 
   /**
-   * The status of the current sign-in attempt as a string (for example, `'needs_identifier'`, `'needs_first_factor'`,
-   * `'complete'`, etc.)
+   * The current status of the sign-in.
    */
   readonly status: SignInStatus;
 
@@ -156,31 +255,50 @@ export interface SignInFutureResource {
 
   readonly existingSession?: { sessionId: string };
 
+  /**
+   * The state of the verification process for the selected first factor. Initially, this property contains an empty
+   * verification object, since there is no first factor selected.
+   */
   readonly firstFactorVerification: VerificationResource;
 
   /**
-   * The second-factor verification for the current sign-in attempt.
+   * The state of the verification process for the selected second factor. Initially, this property contains an empty
+   * verification object, since there is no second factor selected.
    */
   readonly secondFactorVerification: VerificationResource;
 
   /**
-   * The identifier for the current sign-in attempt.
+   * The authentication identifier value for the current sign-in. `null` if the `strategy` is `'oauth_<provider>'`
+   * or `'enterprise_sso'`.
    */
   readonly identifier: string | null;
 
   /**
-   * The created session ID for the current sign-in attempt.
+   * The identifier of the session that was created upon completion of the current sign-in. The value of this property
+   * is `null` if the sign-in status is not `'complete'`.
    */
   readonly createdSessionId: string | null;
 
   /**
-   * The user data for the current sign-in attempt.
+   * An object containing information about the user of the current sign-in. This property is populated only once an
+   * identifier is given to the `SignIn` object through `signIn.create()` or another method that populates the
+   * `identifier` property.
    */
   readonly userData: UserData;
 
   /**
-   * Used to supply an identifier for the sign-in attempt. Calling this method will populate data on the sign-in
-   * attempt, such as `signIn.resource.supportedFirstFactors`.
+   * Creates a new `SignIn` instance initialized with the provided parameters. The instance maintains the sign-in
+   * lifecycle state through its `status` property, which updates as the authentication flow progresses.
+   *
+   * What you must pass to `params` depends on which [sign-in options](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options)
+   * you have enabled in your app's settings in the Clerk Dashboard.
+   *
+   * You can complete the sign-in process in one step if you supply the required fields to `create()`. Otherwise,
+   * Clerk's sign-in process provides great flexibility and allows users to easily create multi-step sign-in flows.
+   *
+   * > [!WARNING]
+   * > Once the sign-in process is complete, call the `signIn.finalize()` method to set the newly created session as
+   * > the active session.
    */
   create: (params: SignInFutureCreateParams) => Promise<{ error: unknown }>;