chore(docs): Generated References (automated) (#12154)

Generated the following references: - `api_key` - `auth` - `cart` - `cart_models` - `core_flows` - `currency` - `customer` - `event` - `file_service` - `fulfillment` - `fulfillment_provider` - `inventory_next` - `js_sdk` - `locking` - `medusa` - `modules` - `modules_sdk` - `notification_service` - `order` - `payment` - `payment_provider` - `pricing` - `product` - `promotion` - `region` - `sales_channel` - `stock_location_next` - `store` - `tax` - `types` - `user` - `utils` - `workflows` Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com> Co-authored-by: Shahed Nasser <27354907+shahednasser@users.noreply.github.com>
2025-04-11 11:15:08 +00:00
1 parent df5d410be2
commit 94e98190ff
@@ -15,18 +15,28 @@ This documentation provides a reference to the `sdk.auth.callback` method used t
 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 [refresh](../js_sdk.auth.Auth.refresh/page.mdx) methods,
+for example, after calling this method.
+
+Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
+
 ## Example

 ```ts
-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"
 })
 ```

@@ -15,25 +15,55 @@ This documentation provides a reference to the `sdk.auth.login` method used to s
 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).

-Subsequent requests using the SDK will automatically have the necessary authentication headers / session
-set.
+Learn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.
+
+### Automatic Authentication
+
+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.

 ## Example

 ```ts
-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()
 ```

 ## Parameters
@@ -12,18 +12,24 @@ import { TypeList } from "docs-ui"

 This documentation provides a reference to the `sdk.auth.logout` method used to send requests to Medusa's Authentication API routes. It can be used for admin users, customers, or custom actor types.

-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.

 ## Example

 ```ts
-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
 ```

 ## Returns

-<TypeList types={[{"name":"Promise","type":"Promise&#60;void&#62;","optional":false,"defaultValue":"","description":"This method deletes the authentication session of the currently logged-in user to log them out.\nIt sends a request to the [Delete Authentication Session API route](https://docs.medusajs.com/api/admin#auth\\_deletesession).","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="logout"/>
+<TypeList types={[{"name":"Promise","type":"Promise&#60;void&#62;","optional":false,"defaultValue":"","description":"This method logs out the currently authenticated user based on your JS SDK authentication configurations.\n\nIf the `auth.type` of the SDK is set to `session`, this method will also send a request to the\n[Delete Authentication Session API route](https://docs.medusajs.com/api/admin#auth\\_deletesession).\n\nThe method also clears any stored tokens or sessions, based on your JS SDK authentication configurations.\n\nLearn more in the [JS SDK Authentication](https://docs.medusajs.com/resources/js-sdk/auth/overview) guide.","expandable":false,"children":[]}]} expandUrl="https://docs.medusajs.com/learn/fundamentals/data-models/manage-relationships#retrieve-records-of-relation" sectionTitle="logout"/>
@@ -15,13 +15,21 @@ This documentation provides a reference to the `sdk.auth.refresh` method used to
 This method refreshes a JWT authentication token, which is useful after validating the Oauth callback
 with [callback](../js_sdk.auth.Auth.callback/page.mdx). 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.
+
 ## Example

 ```ts
-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()
 ```

 ## Returns
@@ -15,18 +15,28 @@ This documentation provides a reference to the `sdk.auth.register` method used t
 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.
+
 ## Example

 ```ts
-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"
 })
 ```