From e998366abab1e10a3e9d0191c8919f3eafbe19ed Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Fri, 28 Mar 2025 17:55:01 +0200 Subject: [PATCH] chore(js-sdk): improve the TSDocs of auth methods in JS SDK (#12033) --- packages/core/js-sdk/src/auth/index.ts | 112 +++++++++++++++++++------ 1 file changed, 88 insertions(+), 24 deletions(-) diff --git a/packages/core/js-sdk/src/auth/index.ts b/packages/core/js-sdk/src/auth/index.ts index 720ed3ed2b..a6c6378876 100644 --- a/packages/core/js-sdk/src/auth/index.ts +++ b/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 - * set. + * If the authentication was successful, subsequent requests using the SDK will automatically have the necessary authentication headers / session + * 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() - * .then((token) => { - * console.log(token) - * }) + * const token = await sdk.auth.refresh() + * + * // 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. - * It sends a request to the [Delete Authentication Session API route](https://docs.medusajs.com/api/admin#auth_deletesession). - * + * This method logs out the currently authenticated user based on your JS SDK authentication configurations. + * + * 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() - * .then(() => { - * // user is logged out - * }) + * await sdk.auth.logout() + * + * // user is now logged out + * // you can't send any requests that require authentication */ logout = async () => { if (this.config?.auth?.type === "session") {