asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Shahed Nasser
2025-03-28 17:55:01 +02:00
committed by GitHub
parent 79cfc1a69e
commit e998366aba
1 changed files with 88 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
packages/core/js-sdk/src/auth/index.ts
View File

@@ -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") {