chore(js-sdk): improve the TSDocs of auth methods in JS SDK (#12033)

packages/core/js-sdk/src/auth/index.ts

@@ -14,6 +14,12 @@ export class Auth {
   /**
    * This method is used to retrieve a registration JWT token for a user, customer, or custom actor type. It sends a request to the
    * [Retrieve Registration Token API route](https://docs.medusajs.com/api/store#auth_postactor_typeauth_provider_register).
+   * 
+   * Then, it stores the returned token and passes it in the header of subsequent requests. So, you can call the
+   * [store.customer.create](https://docs.medusajs.com/resources/references/js-sdk/store/customer#create) method,
+   * for example, after calling this method.
+   * 
+   * Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
    *
    * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
    * @param method - The authentication provider to use. For example, `emailpass` or `google`.
@@ -24,15 +30,19 @@ export class Auth {
    * @tags auth
    *
    * @example
-   * sdk.auth.register(
+   * await sdk.auth.register(
    *   "customer",
    *   "emailpass",
    *   {
    *     email: "customer@gmail.com",
    *     password: "supersecret"
    *   }
-   * ).then((token) => {
+   * )
-   *   console.log(token)
+   * 
+   * // all subsequent requests will use the token in the header
+   * const { customer } = await sdk.store.customer.create({
+   *   email: "customer@gmail.com",
+   *   password: "supersecret"
    * })
    */
   register = async (
@@ -56,12 +66,33 @@ export class Auth {
   /**
    * This method retrieves the JWT authenticated token for an admin user, customer, or custom
    * actor type. It sends a request to the [Authenticate API Route](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_provider).
+   * 
+   * ### Third-Party Authentication
+   * 
+   * If the API route returns a `location` property, it means that the authentication requires additional steps,
+   * typically in a third-party service. The `location` property is returned so that you
+   * can redirect the user to the appropriate page.
+   * 
+   * :::note
+   * 
+   * For an example of implementing third-party authentication, refer to the
+   * [Third-Party Login in Storefront](https://docs.medusajs.com/resources/storefront-development/customers/third-party-login) guide.
+   * 
+   * :::
+   * 
+   * ### Session Authentication
    *
    * If the `auth.type` of the SDK is set to `session`, this method will also send a request to the
    * [Set Authentication Session API route](https://docs.medusajs.com/api/admin#auth_postsession).
+   * 
+   * Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
+   * 
+   * ### Automatic Authentication
    *
-   * Subsequent requests using the SDK will automatically have the necessary authentication headers / session
+   * If the authentication was successful, subsequent requests using the SDK will automatically have the necessary authentication headers / session
-   * set.
+   * set, based on your JS SDK authentication configurations.
+   * 
+   * Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
    *
    * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
    * @param method - The authentication provider to use. For example, `emailpass` or `google`.
@@ -72,16 +103,25 @@ export class Auth {
    * @tags auth
    *
    * @example
-   * sdk.auth.login(
+   * const result = await sdk.auth.login(
    *   "customer",
    *   "emailpass",
    *   {
    *     email: "customer@gmail.com",
    *     password: "supersecret"
    *   }
-   * ).then((token) => {
+   * )
-   *   console.log(token)
+   * 
-   * })
+   * if (typeof result !== "string") {
+   *   alert("Authentication requires additional steps")
+   *   // replace with the redirect logic of your application
+   *   window.location.href = result.location
+   *   return
+   * }
+   * 
+   * // customer is now authenticated
+   * // all subsequent requests will use the token in the header
+   * const { customer } = await sdk.store.customer.retrieve()
    */
   login = async (
     actor: string,
@@ -110,6 +150,12 @@ export class Auth {
   /**
    * This method is used to validate an Oauth callback from a third-party service, such as Google, for an admin user, customer, or custom actor types.
    * It sends a request to the [Validate Authentication Callback](https://docs.medusajs.com/api/admin#auth_postactor_typeauth_providercallback).
+   * 
+   * The method stores the returned token and passes it in the header of subsequent requests. So, you can call the
+   * [store.customer.create](https://docs.medusajs.com/resources/references/js-sdk/store/customer#create) or {@link refresh} methods,
+   * for example, after calling this method.
+   * 
+   * Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
    *
    * @param actor - The actor type. For example, `user` for admin user, or `customer` for customer.
    * @param method - The authentication provider to use. For example, `google`.
@@ -120,17 +166,20 @@ export class Auth {
    * @tags auth
    *
    * @example
-   * sdk.auth.callback(
+   * await sdk.auth.callback(
    *   "customer",
    *   "google",
    *   {
    *     code: "123",
    *     state: "456"
    *   }
-   * ).then((token) => {
+   * )
-   *   console.log(token)
-   * })
    *
+   * // all subsequent requests will use the token in the header
+   * const { customer } = await sdk.store.customer.create({
+   *   email: "customer@gmail.com",
+   *   password: "supersecret"
+   * })
    *
    * @privateRemarks
    * The callback expects all query parameters from the Oauth callback to be passed to
@@ -156,16 +205,25 @@ export class Auth {
   /**
    * This method refreshes a JWT authentication token, which is useful after validating the Oauth callback
    * with {@link callback}. It sends a request to the [Refresh Authentication Token API route](https://docs.medusajs.com/api/admin#auth_postadminauthtokenrefresh).
+   * 
+   * The method stores the returned token and passes it in the header of subsequent requests. So, you can call other
+   * methods that require authentication after calling this method.
+   * 
+   * Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
+   * 
+   * For an example of implementing third-party authentication, refer to the
+   * [Third-Party Login in Storefront](https://docs.medusajs.com/resources/storefront-development/customers/third-party-login) guide.
+   * 
    *
    * @returns The refreshed JWT authentication token.
    *
    * @tags auth
    *
    * @example
-   * sdk.auth.refresh()
+   * const token = await sdk.auth.refresh()
-   * .then((token) => {
+   * 
-   *   console.log(token)
+   * // all subsequent requests will use the token in the header
-   * })
+   * const { customer } = await sdk.store.customer.retrieve()
    */
   refresh = async () => {
     const { token } = await this.client.fetch<{ token: string }>(
@@ -182,16 +240,22 @@ export class Auth {
   }
 
   /**
-   * This method deletes the authentication session of the currently logged-in user to log them out.
+   * This method logs out the currently authenticated user based on your JS SDK authentication configurations.
-   * It sends a request to the [Delete Authentication Session API route](https://docs.medusajs.com/api/admin#auth_deletesession).
+   * 
-   *
+   * If the `auth.type` of the SDK is set to `session`, this method will also send a request to the
+   * [Delete Authentication Session API route](https://docs.medusajs.com/api/admin#auth_deletesession).
+   * 
+   * The method also clears any stored tokens or sessions, based on your JS SDK authentication configurations.
+   * 
+   * Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
+   * 
    * @tags auth
    *
    * @example
-   * sdk.auth.logout()
+   * await sdk.auth.logout()
-   * .then(() => {
+   * 
-   *   // user is logged out
+   * // user is now logged out
-   * })
+   * // you can't send any requests that require authentication
    */
   logout = async () => {
     if (this.config?.auth?.type === "session") {