docs: update auth docs + add new storefront guides (#9020)

* docs: update auth docs + add new storefront guides * lint content * fix vale error * add callback response schema * Update www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx Co-authored-by: Stevche Radevski <sradevski@live.com> * Update www/apps/resources/app/commerce-modules/auth/auth-providers/github/page.mdx Co-authored-by: Stevche Radevski <sradevski@live.com> * Update www/apps/resources/app/commerce-modules/auth/authentication-route/page.mdx Co-authored-by: Stevche Radevski <sradevski@live.com> * address PR comments * replace google -> github * better explanation for refresh token --------- Co-authored-by: Stevche Radevski <sradevski@live.com>
2024-09-06 15:26:10 +03:00
parent cf3c25addf
commit a28c911c24
29 changed files with 1477 additions and 316 deletions
--- a/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider].ts
+++ b/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider].ts
@@ -2,7 +2,15 @@
 * @oas [post] /auth/user/{auth_provider}
 * operationId: PostActor_typeAuth_provider
 * summary: Authenticate User
- * description: Authenticate an admin user and receive the JWT token to be used in the header of subsequent requests.
+ * description: >
+ *   Authenticate a user and receive the JWT token to be used in the header of subsequent requests.
+ * 
+ * 
+ *   When used with a third-party provider, such as Google, the request returns a `location` property. You redirect to the
+ *   specified URL in your frontend 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.
 * x-authenticated: false
 * parameters:
 *   - name: auth_provider
@@ -12,10 +20,31 @@
 *     schema:
 *       type: string
 *       example: "emailpass"
+ * 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.
 * x-codeSamples:
 *   - lang: Shell
- *     label: cURL
- *     source: curl -X POST '{backend_url}/auth/user/{auth_provider}'
+ *     label: EmailPass Provider
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/user/emailpass' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "admin@medusa-test.com",
+ *         "password": "supersecret"
+ *       }'
+ *   - lang: Shell
+ *     label: Google Provider
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/user/google'
+ *   - lang: Shell
+ *     label: GitHub Provider
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/user/github'
 * tags:
 *   - Auth
 * responses:
@@ -24,7 +53,9 @@
 *     content:
 *       application/json:
 *         schema:
- *           $ref: "#/components/schemas/AuthResponse"
+ *           oneOf:
+ *             - $ref: "#/components/schemas/AuthResponse"
+ *             - $ref: "#/components/schemas/AuthCallbackResponse"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_callback.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_callback.ts
@@ -2,8 +2,18 @@
 * @oas [post] /auth/user/{auth_provider}/callback
 * operationId: PostActor_typeAuth_providerCallback
 * summary: Validate Authentication Callback
- * description: Third-party authentication providers, such as Google, require an API route to call once authentication with the third-party provider is finished.
- *   This API route validates callback for admin users logged-in with third-party providers.
+ * description: >
+ *   This API route is used by your dashboard or frontend application when a third-party provider redirects to it after authentication. 
+ * 
+ * 
+ *   It validates the authentication with the third-party provider and, if successful, returns an authentication token.
+ * 
+ *   
+ *   You can decode the JWT token using libraries like [react-jwt](https://www.npmjs.com/package/react-jwt) in the frontend. If the decoded data doesn't 
+ *   have an `actor_id` property, then you must create a user, typically using the Accept Invite 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.
 * x-authenticated: false
 * parameters:
 *   - name: auth_provider
@@ -15,8 +25,11 @@
 *       example: "google"
 * x-codeSamples:
 *   - lang: Shell
- *     label: cURL
- *     source: curl -X POST '{backend_url}/auth/user/{auth_provider}/callback'
+ *     label: Google Provider
+ *     source: curl -X POST '{backend_url}/auth/user/google/callback?code=123'
+ *   - lang: Shell
+ *     label: GitHub Provider
+ *     source: curl -X POST '{backend_url}/auth/user/github/callback?code=123'
 * tags:
 *   - Auth
 * responses:
--- a/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_register.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_auth_[actor_type]_[auth_provider]_register.ts
@@ -2,8 +2,10 @@
 * @oas [post] /auth/user/{auth_provider}/register
 * operationId: PostActor_typeAuth_provider_register
 * summary: Retrieve Registration JWT Token
- * description: A registration JWT token is used in the header of requests that create a user, such as the accept invitation request.
- *   This API route retrieves the JWT token of a user that hasn't been registered yet.
+ * description: This API route retrieves a registration JWT token of a user that hasn't been registered yet. The token is used in the header of requests that create a user, such as the Accept Invite API route.
+ * externalDocs:
+ *   url: https://docs.medusajs.com/v2/resources/commerce-modules/auth/authentication-route#1-basic-authentication-flow
+ *   description: Learn about the basic authentication flow.
 * x-authenticated: false
 * parameters:
 *   - name: auth_provider
@@ -13,10 +15,23 @@
 *     schema:
 *       type: string
 *       example: "emailpass"
+ * 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.
 * x-codeSamples:
 *   - lang: Shell
 *     label: cURL
- *     source: curl -X POST '{backend_url}/auth/user/{auth_provider}/register'
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/user/emailpass/register' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "admin@medusa-test.com",
+ *         "password": "supersecret"
+ *       }'
 * tags:
 *   - Auth
 * responses:
--- a/www/utils/generated/oas-output/operations/admin/post_auth_token_refresh.ts
+++ b/www/utils/generated/oas-output/operations/admin/post_auth_token_refresh.ts
@@ -0,0 +1,38 @@
+/**
+ * @oas [post] /auth/token/refresh
+ * operationId: PostAdminAuthTokenRefresh
+ * summary: Refresh Authentication Token
+ * description: Refresh the authentication token of a user. This is useful after authenticating a user with a third-party service to ensure the token holds the new user's details, or when you don't want users 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.
+ * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/token/refresh' \
+ *       -H 'Authorization: Bearer {token}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+
--- a/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider].ts
+++ b/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider].ts
@@ -2,7 +2,15 @@
 * @oas [post] /auth/customer/{auth_provider}
 * operationId: PostActor_typeAuth_provider
 * summary: Authenticate Customer
- * description: Authenticate a customer and receive the JWT token to be used in the header of subsequent requests.
+ * description: >
+ *   Authenticate a customer and receive the JWT token to be used in the header of subsequent requests.
+ * 
+ * 
+ *   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.
 * x-authenticated: false
 * parameters:
 *   - name: auth_provider
@@ -12,10 +20,31 @@
 *     schema:
 *       type: string
 *       example: "emailpass"
+ * 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.
 * x-codeSamples:
 *   - lang: Shell
- *     label: cURL
- *     source: curl -X POST '{backend_url}/auth/customer/{auth_provider}'
+ *     label: EmailPass Provider
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/customer/emailpass' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "customer@gmail.com",
+ *         "password": "supersecret"
+ *       }'
+ *   - lang: Shell
+ *     label: Google Provider
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/customer/google'
+ *   - lang: Shell
+ *     label: GitHub Provider
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/customer/github'
 * tags:
 *   - Auth
 * responses:
@@ -24,7 +53,9 @@
 *     content:
 *       application/json:
 *         schema:
- *           $ref: "#/components/schemas/AuthResponse"
+ *           oneOf:
+ *             - $ref: "#/components/schemas/AuthResponse"
+ *             - $ref: "#/components/schemas/AuthCallbackResponse"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_callback.ts
+++ b/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_callback.ts
@@ -2,8 +2,18 @@
 * @oas [post] /auth/customer/{auth_provider}/callback
 * operationId: PostActor_typeAuth_providerCallback
 * summary: Validate Authentication Callback
- * description: Third-party authentication providers, such as Google, require an API route to call once authentication with the third-party provider is finished.
- *   This API route validates callback for customers logged-in with third-party providers.
+ * description: >
+ *   This API route is used by your storefront or frontend application when a third-party provider redirects to it after authentication. 
+ * 
+ * 
+ *   It validates the authentication with the third-party provider and, if successful, returns an authentication token.
+ * 
+ *   
+ *   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.
 * x-authenticated: false
 * parameters:
 *   - name: auth_provider
@@ -15,8 +25,11 @@
 *       example: "google"
 * x-codeSamples:
 *   - lang: Shell
- *     label: cURL
- *     source: curl -X POST '{backend_url}/auth/customer/{auth_provider}/callback'
+ *     label: Google Provider
+ *     source: curl -X POST '{backend_url}/auth/customer/google/callback?code=123'
+ *   - lang: Shell
+ *     label: GitHub Provider
+ *     source: curl -X POST '{backend_url}/auth/customer/github/callback?code=123'
 * tags:
 *   - Auth
 * responses:
--- a/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_register.ts
+++ b/www/utils/generated/oas-output/operations/store/post_auth_[actor_type]_[auth_provider]_register.ts
@@ -2,8 +2,10 @@
 * @oas [post] /auth/customer/{auth_provider}/register
 * operationId: PostActor_typeAuth_provider_register
 * summary: Retrieve Registration JWT Token
- * description: A registration JWT token is used in the header of requests that create a customer.
- *   This API route retrieves the JWT token of a customer that hasn't been registered yet.
+ * 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.
 * x-authenticated: false
 * parameters:
 *   - name: auth_provider
@@ -13,10 +15,23 @@
 *     schema:
 *       type: string
 *       example: "emailpass"
+ * 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.
 * x-codeSamples:
 *   - lang: Shell
 *     label: cURL
- *     source: curl -X POST '{backend_url}/auth/customer/{auth_provider}/register'
+ *     source:  |-
+ *       curl -X POST '{backend_url}/auth/customer/emailpass/register' \
+ *       -H 'Content-Type: application/json' \
+ *       --data-raw '{
+ *         "email": "customer@gmail.com",
+ *         "password": "supersecret"
+ *       }'
 * tags:
 *   - Auth
 * responses:
--- a/www/utils/generated/oas-output/operations/store/post_auth_token_refresh.ts
+++ b/www/utils/generated/oas-output/operations/store/post_auth_token_refresh.ts
@@ -0,0 +1,38 @@
+/**
+ * @oas [post] /auth/token/refresh
+ * operationId: PostAdminAuthTokenRefresh
+ * 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.
+ * x-authenticated: true
+ * x-codeSamples:
+ *   - lang: Shell
+ *     label: cURL
+ *     source: curl -X POST '{backend_url}/auth/token/refresh' \
+ *       -H 'Authorization: Bearer {token}'
+ * tags:
+ *   - Auth
+ * responses:
+ *   "200":
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           $ref: "#/components/schemas/AuthResponse"
+ *   "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"
+ * 
+*/
+
--- a/www/utils/generated/oas-output/schemas/AuthCallbackResponse.ts
+++ b/www/utils/generated/oas-output/schemas/AuthCallbackResponse.ts
@@ -0,0 +1,14 @@
+/**
+ * @schema AuthCallbackResponse
+ * type: object
+ * description: The authentication's details.
+ * x-schemaName: AuthCallbackResponse
+ * required:
+ *   - location
+ * properties:
+ *   token:
+ *     type: string
+ *     title: location
+ *     description: The location to redirect the user to for further authentication with the third-party provider.
+*/
+