docs: general fixes and enhancements

.github/workflows/docs-test.yml

@@ -6,7 +6,7 @@ on:
 
 jobs:
   docs-test:
-    if: ${{ startsWith(github.ref, 'docs/') }}
+    if: ${{ startsWith(github.head_ref, 'docs/') }}
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
@@ -42,7 +42,7 @@ jobs:
         run: yarn build:docs
 
   vale-docs:
-    if: ${{ startsWith(github.ref, 'docs/') }}
+    if: ${{ startsWith(github.head_ref, 'docs/') }}
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
@@ -73,7 +73,7 @@ jobs:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ github.token }}
 
   vale-ui:
-    if: ${{ startsWith(github.ref, 'docs/') }}
+    if: ${{ startsWith(github.head_ref, 'docs/') }}
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
@@ -104,7 +104,7 @@ jobs:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ github.token }}
 
   vale-api:
-    if: ${{ startsWith(github.ref, 'docs/') }}
+    if: ${{ startsWith(github.head_ref, 'docs/') }}
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
@@ -135,7 +135,7 @@ jobs:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ github.token }}
 
   content-eslint:
-    if: ${{ startsWith(github.ref, 'docs/') }}
+    if: ${{ startsWith(github.head_ref, 'docs/') }}
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs
@@ -157,7 +157,7 @@ jobs:
         run: yarn lint:content
 
   code-docs-eslint:
-    if: ${{ startsWith(github.ref, 'docs/') }}
+    if: ${{ startsWith(github.head_ref, 'docs/') }}
     runs-on: ubuntu-latest
     steps:
       - name: Cancel Previous Runs

www/apps/docs/.env.sample

@@ -6,4 +6,5 @@ ALGOLIA_APP_ID=
 AI_ASSISTANT_URL=
 AI_API_ASSISTANT_TOKEN=
 AI_WEBSITE_ID=
-AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
+AI_API_ASSISTANT_RECAPTCHA_SITE_KEY=
+CLOUDINARY_CLOUD_NAME=

www/apps/docs/content/modules/carts-and-checkout/backend/add-payment-provider.md

@@ -35,11 +35,12 @@ The Payment Processor is also required to implement the following methods:
 2. `retrievePayment`: Used to retrieve payment session data, which can be retrieved from a third-party provider.
 3. `getPaymentStatus`: Used to get the status of a Payment or Payment Session.
 4. `updatePayment`: Used to update the Payment Session whenever the cart and its related data are updated.
-5. `deletePayment`: Used to perform any action necessary before a Payment Session is deleted. For example, you can cancel the payment with the third-party provider.
-6. `authorizePayment`: Used to authorize the payment amount of the cart before the order or swap is created.
-7. `capturePayment`: Used to capture the payment amount of an order or swap.
-8. `refundPayment`: Used to refund a payment amount of an order or swap.
-9. `cancelPayment`: Used to perform any necessary action with the third-party payment provider when an order or swap is canceled.
+5. `updatePaymentData`: Used to update the `data` of a payment session.
+6. `deletePayment`: Used to perform any action necessary before a Payment Session is deleted. For example, you can cancel the payment with the third-party provider.
+7. `authorizePayment`: Used to authorize the payment amount of the cart before the order or swap is created.
+8. `capturePayment`: Used to capture the payment amount of an order or swap.
+9. `refundPayment`: Used to refund a payment amount of an order or swap.
+10. `cancelPayment`: Used to perform any necessary action with the third-party payment provider when an order or swap is canceled.
 
 :::note
 
@@ -130,6 +131,15 @@ class MyPaymentProcessor extends AbstractPaymentProcessor {
   > {
     throw new Error("Method not implemented.")
   }
+  async updatePaymentData(
+    sessionId: string,
+    data: Record<string, unknown>
+  ): Promise<
+    Record<string, unknown> | 
+    PaymentProcessorError
+  > {
+    throw new Error("Method not implemented.");
+  }
 }
 
 export default MyPaymentProcessor
@@ -346,7 +356,7 @@ class MyPaymentService extends AbstractPaymentProcessor {
 
 ### updatePayment
 
-This method is used to perform any necessary updates on the payment. This method is called whenever the cart or any of its related data is updated. For example, when a [line item is added to the cart](https://docs.medusajs.com/api/store#carts_postcartscartlineitems) or when a [shipping method is selected](https://docs.medusajs.com/api/store#carts_postcartscartshippingmethod).
+This method is used to update the payment session when the payment amount changes. It's called whenever the cart or any of its related data is updated. For example, when a [line item is added to the cart](https://docs.medusajs.com/api/store#carts_postcartscartlineitems) or when a [shipping method is selected](https://docs.medusajs.com/api/store#carts_postcartscartshippingmethod).
 
 :::tip
 
@@ -413,6 +423,41 @@ class MyPaymentService extends AbstractPaymentProcessor {
 }
 ```
 
+### updatePaymentData
+
+This method is used to update the `data` field of a payment session. It's called when a request is sent to the [Update Payment Session API Route](https://docs.medusajs.com/api/store#carts_postcartscartpaymentsessionupdate), or when the `CartService`'s `updatePaymentSession` is used.
+
+This method can also be used to update the data in the third-party payment provider, if necessary.
+
+The method accepts the following parameters:
+
+1. `sessionId`: A string that indicates the ID of the payment session.
+2. `data`: An object containing the data to be updated.
+
+The method returns the data to store in the `data` field of the payment session. You can keep the data as-is, or make changes to it by communicating with the third-party provider.
+
+An example of a minimal implementation of `updatePaymentData` that returns the `data` field as-is:
+
+```ts
+import { 
+  PaymentProcessorError
+} from "@medusajs/medusa"
+// ...
+
+class MyPaymentService extends AbstractPaymentProcessor {
+  // ...
+  async updatePaymentData(
+    sessionId: string,
+    data: Record<string, unknown>
+  ): Promise<
+    Record<string, unknown> | 
+    PaymentProcessorError
+  > {
+    return data
+  }
+}
+```
+
 ### deletePayment
 
 This method is used to perform any actions necessary before a Payment Session is deleted. The Payment Session is deleted in one of the following cases:

www/apps/docs/content/modules/overview.mdx

@@ -126,24 +126,41 @@ Medusa's products configuration allows managing products of different types incl
 
 
   </LargeCard>
-</LargeCardList>
 
+  <LargeCard
+    Icon={Icons['currency-dollar-solid']}
+    title='Price Lists'
+    action={{
+      label: 'Learn more',
+      href: '/modules/price-lists/overview'
+    }}
+  >
+
+  - Override product prices or offer sales using price lists.
+  - Set special conditions for price lists such as specific customer groups.
+  - Override the price selection strategy used to show customers the best prices.
+  - Bulk-edit prices in a price list when managing them using the Medusa Admin.
 
-<LargeCard
-  Icon={Icons['currency-dollar-solid']}
-  title='Price Lists and Discounts'
-  action={{
-    label: 'Learn more',
-    href: '/modules/price-lists/overview'
-  }}
->
 
-- Create discounts and deals with advanced conditions and rules such as minimum cart quantity or specific products.
-- Offer free shipping, fixed discount, or percentage discount.
-- Override product prices using price lists and set special conditions such as specific customer groups.
+  </LargeCard>
+
+  <LargeCard
+    Icon={Icons['receipt-percent']}
+    title='Discounts'
+    action={{
+      label: 'Learn more',
+      href: '/modules/discounts/overview'
+    }}
+  >
 
+  - Create discounts and deals with advanced conditions and rules such as minimum cart quantity or specific products.
+  - Offer free shipping, fixed discount, or percentage discount to your customers.
+  - Set start and end dates for your discounts to ensure they run for a specified period of time
 
-</LargeCard>
+
+  </LargeCard>
+
+</LargeCardList>
 
 ### Ready Configurations for International Selling
 
@@ -152,13 +169,14 @@ Medusa's multi-region setup and sales channels allow businesses to sell internat
 <LargeCardList colSize={6}>
   <LargeCard
     Icon={Icons['globe-europe-solid']}
-    title='Multi-Region'
+    title='Region and Currencies'
     action={{
       label: 'Learn more',
       href: '/modules/regions-and-currencies/overview'
     }}
   >
 
+  - Support multi-region and multi-currencies in your store.
   - Create an unlimited number of regions, each associated with a currency and at least one country.
   - Manage each region’s settings including payment processors, shipping options, and more.
   - Set prices for products and shipping options specific to a currency or a region.

www/apps/docs/content/plugins/file-service/s3.mdx

@@ -118,22 +118,25 @@ const plugins = [
         access_key_id: process.env.S3_ACCESS_KEY_ID,
         secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
         cache_control: process.env.S3_CACHE_CONTROL,
+        // optional
         download_file_duration:
           process.env.S3_DOWNLOAD_FILE_DURATION,
+        prefix: process.env.S3_PREFIX
     },
   },
 ]
 ```
 
 Where:
 
-1. `s3_url` (required) is the URL to your bucket. It’s in the form `https://<BUCKET_NAME>.s3.<REGION>.amazonaws.com`, where `<BUCKET_NAME>` is the name of the bucket and the `<REGION>` is the region the bucket is created in. If you’re not sure which region, on your bucket’s page on S3 click on Properties. You can then find the region under AWS Region. Make sure to only copy the code (for example, `us-east-1`).
-2. `bucket` (required) is the name of the bucket you created.
-3. `region` (required) is the region code of your bucket. For example, `us-east-1`.
-4. `access_key_id` (required) is the Access Key ID that you created for your user.
-5. `secret_access_key` (required) is the Secret Access Key that you created for your user.
-6. `cache_control` (default: `max-age=31536000`) is the value for caching the objects in a web browser or CDN network. For example: cache object for 10 hours, `max-age=36000`
-7. `download_file_duration` (optional) is the expiry duration for a download URL. For example, you can set the value to ``3600`` if you want the download URL to expire in 1 hour.
+1. `s3_url` (required) is a string indicating the URL to your bucket. It’s in the form `https://<BUCKET_NAME>.s3.<REGION>.amazonaws.com`, where `<BUCKET_NAME>` is the name of the bucket and the `<REGION>` is the region the bucket is created in. If you’re not sure which region, on your bucket’s page on S3 click on Properties. You can then find the region under AWS Region. Make sure to only copy the code (for example, `us-east-1`).
+2. `bucket` (required) is a string indicating the name of the bucket you created.
+3. `region` (required) is a string indicating the region code of your bucket. For example, `us-east-1`.
+4. `access_key_id` (required) is a string indicating the Access Key ID that you created for your user.
+5. `secret_access_key` (required) is a string indicating the Secret Access Key that you created for your user.
+6. `cache_control` (default: `max-age=31536000`) is a string indicating the value for caching the objects in a web browser or CDN network. For example: cache object for 10 hours, `max-age=36000`
+7. `download_file_duration` (optional) is a string indicating the expiry duration for a download URL. For example, you can set the value to ``3600`` if you want the download URL to expire in 1 hour.
+8. `prefix` (optional) is a string indicating a prefix to apply on stored file names.
 
 Make sure to also set these values in your environment variables as well:
 
@@ -145,6 +148,7 @@ S3_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
 S3_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
 S3_CACHE_CONTROL=<YOUR_CACHE_CONTROL>
 S3_DOWNLOAD_FILE_DURATION=<YOUR_DOWNLOAD_FILE_DURATION_AMOUNT>
+S3_PREFIX=<YOUR_BUCKET_PREFIX>
 ```
 
 

www/apps/docs/content/plugins/payment/paypal.md

@@ -192,7 +192,7 @@ function Paypal() {
       const response = await client
         .carts
         .setPaymentSession(cart.id, {
-          "processor_id": "paypal",
+          "provider_id": "paypal",
         })
 
       if (!response.cart) {

www/apps/docs/content/plugins/payment/stripe.mdx

@@ -284,7 +284,7 @@ client.carts.createPaymentSessions(cart.id)
     // check if stripe is selected
     const isStripeAvailable = cart.payment_sessions?.some(
       (session) => (
-        session.processor_id === "stripe"
+        session.provider_id === "stripe"
       )
     )
     if (!isStripeAvailable) {
@@ -293,7 +293,7 @@ client.carts.createPaymentSessions(cart.id)
 
     // select stripe payment session
     client.carts.setPaymentSession(cart.id, {
-      processor_id: "stripe",
+      provider_id: "stripe",
     }).then(({ cart }) => {
       setClientSecret(cart.payment_session.data.client_secret)
     })

www/apps/docs/content/user-guide.mdx

@@ -9,13 +9,7 @@ import UiIcon from '@site/src/components/UiIcon';
 
 This user guide is intended to help users learn how they can use the Medusa admin to perform different operational and ecommerce tasks.
 
-:::tip
-
-If you don’t have a Medusa admin yet, you can check [the live demo](https://demo.medusajs.com/)!
-
-:::
-
-![Medusa Admin Overview](https://res.cloudinary.com/dza7lstvk/image/upload/v1673455647/Medusa%20Docs/User%20Guide/Screenshot_2023-01-11_at_6.46.06_PM_sirvel.png)
+![Medusa Admin Overview](https://res.cloudinary.com/dza7lstvk/image/upload/v1697793701/Medusa%20Docs/User%20Guide/Screenshot_2023-10-20_at_12.21.19_PM_lqcurg.png)
 
 ## Accessing the Medusa Admin
 
@@ -35,7 +29,7 @@ After you log into your Medusa admin, you can see a sidebar menu, a search bar a
 
 The sidebar menu includes the main navigation of your Medusa admin. You can use it to navigate between different pages, such as Products or Orders pages.
 
-![Sidebar Menu](https://res.cloudinary.com/dza7lstvk/image/upload/v1673455798/Medusa%20Docs/User%20Guide/Screenshot_2023-01-11_at_6.49.48_PM_bj2bik.png)
+![Sidebar Menu](https://res.cloudinary.com/dza7lstvk/image/upload/v1697793775/Medusa%20Docs/User%20Guide/Screenshot_2023-10-20_at_12.22.43_PM_shbr0e.png)
 
 ### Search Bar
 
@@ -51,7 +45,7 @@ Mac OS: <kbd>⌘</kbd> + <kbd>K</kbd>
 
 :::
 
-![Search Window](https://res.cloudinary.com/dza7lstvk/image/upload/v1667923987/Medusa%20Docs/User%20Guide/z9a1NLK_ojyfn0.png)
+![Search Window](https://res.cloudinary.com/dza7lstvk/image/upload/v1697793970/Medusa%20Docs/User%20Guide/Screenshot_2023-10-20_at_12.26.00_PM_e8sney.png)
 
 You can select a result with your mouse. Alternatively, use the up and down arrows on your keyboard to navigate between the results, then choosing a result by hitting the Enter key.
 
@@ -71,10 +65,10 @@ Learn how to change the language in [this guide](./user-guide/users/profile.md#c
 
 At the top left in the sidebar, you’ll find an avatar icon. By clicking this icon, you’ll see a dropdown. You can use this dropdown to access settings or sign out.
 
-![Quick Actions Dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1673455879/Medusa%20Docs/User%20Guide/Screenshot_2023-01-11_at_6.50.52_PM_tfduvw.png)
+![Quick Actions Dropdown](https://res.cloudinary.com/dza7lstvk/image/upload/v1697794317/Medusa%20Docs/User%20Guide/Screenshot_2023-10-20_at_12.31.37_PM_wioczx.png)
 
 ### Need Help
 
 At the top right, you’ll find a <UiIcon lightIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999071/Medusa%20Docs/UI%20Icons/CrABja9_lwomxs.png" darkIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999095/Medusa%20Docs/UI%20Icons/cgeX2hP_b1vkwy.png" alt="question mark" /> icon. When you click on this icon, a form will pop up. You can use this form to send the Medusa team a message asking for help. The Medusa team usually responds in a few hours on business days.
 
-![Get Help Form](https://res.cloudinary.com/dza7lstvk/image/upload/v1667924070/Medusa%20Docs/User%20Guide/8Fpa0gr_sjovih.png)
+![Get Help Form](https://res.cloudinary.com/dza7lstvk/image/upload/v1697794650/Medusa%20Docs/User%20Guide/Screenshot_2023-10-20_at_12.37.19_PM_vbatec.png)

www/apps/docs/content/user-guide/tips/lists.mdx

@@ -78,7 +78,7 @@ Clearing filters does not delete saved quick filters. You can still apply them b
 
 You can search for items in a list by clicking the <UiIcon lightIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999227/Medusa%20Docs/UI%20Icons/k0U0wpO_pizpfd.png" darkIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999249/Medusa%20Docs/UI%20Icons/IdKjFak_ultvmh.png" alt="magnifier" /> icon at the top right of the list.
 
-![Search items in a list](https://res.cloudinary.com/dza7lstvk/image/upload/v1667998849/Medusa%20Docs/User%20Guide/Z09rbmQ_jgi4ti.png)
+![Search items in a list](https://res.cloudinary.com/dza7lstvk/image/upload/v1697794886/Medusa%20Docs/User%20Guide/Screenshot_2023-10-20_at_12.41.11_PM_xkmbno.png)
 
 ---
 

www/apps/docs/src/components/LearningPath/Steps/index.tsx

@@ -60,16 +60,14 @@ const LearningPathSteps: React.FC<LearningPathStepsProps> = ({ ...rest }) => {
                 </div>
               </div>
             )}
-            {index < currentStep && (
-              <Link
-                href={step.path}
-                className={clsx("absolute top-0 left-0 w-full h-full")}
-                onClick={(e) => {
-                  e.preventDefault()
-                  goToStep(index)
-                }}
-              />
-            )}
+            <Link
+              href={step.path}
+              className={clsx("absolute top-0 left-0 w-full h-full")}
+              onClick={(e) => {
+                e.preventDefault()
+                goToStep(index)
+              }}
+            />
           </div>
         ))}
       </div>

www/apps/docs/src/components/LearningPath/index.tsx

@@ -5,6 +5,7 @@ import { getLearningPath } from "../../utils/learning-paths"
 import { useLearningPath } from "../../providers/LearningPath"
 import { Button, useNotifications } from "docs-ui"
 import { CircleMiniSolid } from "@medusajs/icons"
+import Link from "@docusaurus/Link"
 
 type LearningPathProps = {
   pathName: string
@@ -67,7 +68,7 @@ const LearningPath: React.FC<LearningPathProps> = ({
       {path.steps.map((step, index) => (
         <div
           className={clsx(
-            "flex items-center p-1 gap-1",
+            "flex items-center p-1 gap-1 relative",
             index !== path.steps.length - 1 &&
               "border-0 border-b border-solid border-medusa-border-base"
           )}
@@ -81,6 +82,10 @@ const LearningPath: React.FC<LearningPathProps> = ({
           >
             {step.title}
           </span>
+          <Link
+            href={step.path}
+            className={clsx("absolute top-0 left-0 w-full h-full")}
+          />
         </div>
       ))}
     </div>