docs: added docs for reset password (#9306)

- Added to docs on implementing auth flows using the module and API routes how to update a user's password
- Added guide on how to send a notification when a password token is generated
- Added a guide on implementing reset password flow in storefront
- Added OAS for the `/update` and `/reset-password` routes + generated specs for the API reference

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_register.ts

@@ -22,6 +22,9 @@
  *         type: object
  *         title: input
  *         description: The input data necessary for authentication. For example, for email-pass authentication, pass `email` and `password` properties.
+ *         example:
+ *           email: "admin@medusa-test.com"
+ *           password: "supersecret"
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_reset-password.ts

@@ -0,0 +1,60 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}/reset-password
+ * operationId: PostActor_typeAuth_providerResetPassword
+ * summary: Generate Reset Password Token for Admin User
+ * x-sidebar-summary: Generate Reset Password Token
+ * description: >
+ *   Generate a reset password token for an admin user. This API route emits the `` event, passing it the token as a payload. You can listen to that event and send the user a notification. The notification should have a URL that accepts a `token` query parameter.
+ * 
+ * 
+ *    Use the generated token to update the user's password using the Reset Password API route.
+ * externalDocs:
+ *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#generate-reset-password-token-route
+ *   description: Learn more about this API route.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         type: object
+ *         title: identifier
+ *         description: The user's identifier for the selected auth provider. For example, for the `emailpass` auth provider, the value is the user's email.
+ *         example: "admin@medusa-test.com"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/user/emailpass/reset-password' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "identifier": "admin@medusa-test.com"
+ *       }'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "201":
+ *     description: OK
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ * x-workflow: generateResetPasswordTokenWorkflow
+ * 
+*/
+

www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_update.ts

@@ -0,0 +1,76 @@
+/**
+ * @oas [post] /auth/user/{auth_provider}/update
+ * operationId: PostActor_typeAuth_providerUpdate
+ * summary: Reset an Admin User's Password
+ * x-sidebar-summary: Reset Password
+ * description: Reset a user's password. Generate the reset password token first using the Get Reset Password Token API route.
+ * externalDocs:
+ *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#reset-password-route
+ *   description: Learn more about this API route.
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ *   - name: token
+ *     in: query
+ *     description: The reset password token received using the Get Reset Password API route.
+ *     required: true
+ *     schema:
+ *       type: string
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         type: object
+ *         title: input
+ *         description: The input data necessary for authentication. For example, for email-pass authentication, pass `email` and `password` properties.
+ *         example:
+ *           email: "admin@medusa-test.com"
+ *           password: "supersecret"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/user/emailpass/update?token=123' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "admin@medusa-test.com",
+ *         "password": "supersecret"
+ *       }'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           required:
+ *             - success
+ *           description: Details on the reset password's status.
+ *           properties:
+ *             success:
+ *               type: boolean
+ *               title: success
+ *               description: Whether the password was reset successfully.
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider].ts

@@ -9,8 +9,8 @@
  *   When used with a third-party provider, such as Google, the request returns a `location` property. You redirect to the
  *   specified URL in your storefront to continue authentication with the third-party service.
  * externalDocs:
- *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#types-of-authentication-flows
- *   description: Learn about different authentication flows.
+ *   url: https://docs.medusajs.com/v2/storefront-development/customers/login#1-using-a-jwt-token
+ *   description: "Storefront development: How to login as a customer"
  * x-authenticated: false
  * parameters:
  *   - name: auth_provider

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_callback.ts

@@ -12,8 +12,8 @@
  *   You can decode the JWT token using libraries like [react-jwt](https://www.npmjs.com/package/react-jwt) in the storefront. If the decoded data doesn't 
  *   have an `actor_id` property, then you must register the customer using the Create Customer API route passing the token in the request's Authorization header.
  * externalDocs:
- *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow
- *   description: Learn about third-party authentication flow.
+ *   url: https://docs.medusajs.com/v2/storefront-development/customers/third-party-login
+ *   description: "Storefront development: Implement third-party (social) login."
  * x-authenticated: false
  * parameters:
  *   - name: auth_provider

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_register.ts

@@ -4,8 +4,8 @@
  * summary: Retrieve Registration JWT Token
  * description: This API route retrieves a registration JWT token of a customer that hasn't been registered yet. The token is used in the header of requests that create a customer.
  * externalDocs:
- *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#1-basic-authentication-flow
- *   description: Learn about the basic authentication flow.
+ *   url: https://docs.medusajs.com/v2/storefront-development/customers/register
+ *   description: "Storefront development: How to register a customer"
  * x-authenticated: false
  * parameters:
  *   - name: auth_provider
@@ -22,6 +22,9 @@
  *         type: object
  *         title: input
  *         description: The input data necessary for authentication. For example, for email-pass authentication, pass `email` and `password` properties.
+ *         example:
+ *           email: "customer@gmail.com"
+ *           password: "supersecret"
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_reset-password.ts

@@ -0,0 +1,60 @@
+/**
+ * @oas [post] /auth/customer/{auth_provider}/reset-password
+ * operationId: PostActor_typeAuth_providerResetPassword
+ * summary: Generate Reset Password Token for Customer
+ * x-sidebar-summary: Generate Reset Password Token
+ * description: >
+ *   Generate a reset password token for a customer. This API route emits the `auth.password_reset` event, passing it the token as a payload. You can listen to that event and send the user a notification. The notification should have a URL that accepts a `token` query parameter.
+ * 
+ * 
+ *    Use the generated token to update the user's password using the Reset Password API route.
+ * externalDocs:
+ *   url: https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#1-request-reset-password-page
+ *   description: "Storefront development: How to create the request reset password page."
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         type: object
+ *         title: identifier
+ *         description: The customer's identifier for the selected auth provider. For example, for the `emailpass` auth provider, the value is the customer's email.
+ *         example: "customer@gmail.com"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/customer/emailpass/reset-password' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "identifier": "customer@gmail.com"
+ *       }'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "201":
+ *     description: OK
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ * x-workflow: generateResetPasswordTokenWorkflow
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_update.ts

@@ -0,0 +1,76 @@
+/**
+ * @oas [post] /auth/customer/{auth_provider}/update
+ * operationId: PostActor_typeAuth_providerUpdate
+ * summary: Reset a Customer's Password
+ * x-sidebar-summary: Reset Password
+ * description: Reset a customer's password. Generate the reset password token first using the Get Reset Password Token API route.
+ * externalDocs:
+ *   url: https://docs.medusajs.com/v2/resources/storefront-development/customers/reset-password#2-reset-password-page
+ *   description: "Storefront development: How to create the reset password page."
+ * x-authenticated: false
+ * parameters:
+ *   - name: auth_provider
+ *     in: path
+ *     description: The provider used for authentication.
+ *     required: true
+ *     schema:
+ *       type: string
+ *       example: "emailpass"
+ *   - name: token
+ *     in: query
+ *     description: The reset password token received using the Get Reset Password API route.
+ *     required: true
+ *     schema:
+ *       type: string
+ * requestBody:
+ *   content:
+ *     application/json:
+ *       schema:
+ *         type: object
+ *         title: input
+ *         description: The input data necessary for authentication with the specified auth provider. For example, for email-pass authentication, pass `email` and `password` properties.
+ *         example:
+ *           email: "customer@gmail.com"
+ *           password: "supersecret"
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/customer/emailpass/update?token=123' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "customer@gmail.com",
+ *         "password": "supersecret"
+ *       }'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           required:
+ *             - success
+ *           description: Details on the reset password's status.
+ *           properties:
+ *             success:
+ *               type: boolean
+ *               title: success
+ *               description: Whether the password was reset successfully.
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ * 
+*/
+

www/utils/generated/oas-output/operations/store/post_auth_session.ts

@@ -4,6 +4,9 @@
  * summary: Set Authentication Session
  * description: Set the cookie session ID of a customer. The customer must be previously authenticated with the `/auth/customer/{provider}` API route first,
  *   as the JWT token is required in the header of the request.
+ * externalDocs:
+ *   url: https://docs.medusajs.com/v2/storefront-development/customers/login#2-using-a-cookie-session
+ *   description: "Storefront development: How to login as a customer"
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: Shell

www/utils/generated/oas-output/operations/store/post_auth_token_refresh.ts

@@ -4,8 +4,8 @@
  * summary: Refresh Authentication Token
  * description: Refresh the authentication token of a customer. This is useful after authenticating a customer with a third-party service to ensure the token holds the new user's details, or when you don't want customers to re-login every day.
  * externalDocs:
- *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#2-third-party-service-authenticate-flow
- *   description: Learn about third-party authentication flow.
+ *   url: https://docs.medusajs.com/v2/storefront-development/customers/third-party-login
+ *   description: "Storefront development: Implement third-party (social) login."
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: Shell