docs: update recipes and tutorials to support locks and idempotency (#14151)

www/apps/resources/app/examples/guides/custom-item-price/page.mdx

@@ -375,36 +375,50 @@ The workflow you'll implement in this section has the following steps:
         type: "step",
         name: "useQueryGraphStep (Retrieve Variant)",
         description: "Retrieve the variant's details using Query",
-        depth: 1,
+        depth: 2,
         link: "/references/helper-steps/useQueryGraphStep"
       },
       {
         type: "step",
         name: "getVariantMetalPricesStep",
         description: "Retrieve the variant's price using the third-party service.",
-        depth: 1,
+        depth: 3,
         link: "#getvariantmetalpricesstep"
       },
+      {
+        type: "step",
+        name: "acquireLockStep",
+        description: "Acquire a lock on the cart to prevent concurrent modifications.",
+        depth: 4,
+        link: "/references/medusa-workflows/steps/acquireLockStep",
+      },
       {
         type: "step",
         name: "addToCartWorkflow",
         description: "Add the item with the custom price to the cart.",
-        depth: 1,
+        depth: 5,
         link: "/references/medusa-workflows/addToCartWorkflow"
       },
       {
         type: "step",
         name: "useQueryGraphStep (Retrieve Cart)",
         description: "Retrieve the updated cart's details using Query.",
-        depth: 1,
+        depth: 6,
         link: "/references/helper-steps/useQueryGraphStep"
       },
+      {
+        type: "step",
+        name: "releaseLockStep",
+        description: "Release the lock on the cart.",
+        depth: 7,
+        link: "/references/medusa-workflows/steps/releaseLockStep",
+      }
     ]
   }}
   hideLegend
 />
 
-`useQueryGraphStep` and `addToCartWorkflow` are available through Medusa's core workflows package. You'll only implement the `getVariantMetalPricesStep`.
+You'll only implement the `getVariantMetalPricesStep`. Medusa provides the other steps out-of-the-box.
 
 ### getVariantMetalPricesStep
 
@@ -519,7 +533,7 @@ Create the file `src/workflows/add-custom-to-cart.ts` with the following content
 
 export const workflowHighlights = [
   ["17", "useQueryGraphStep", "Retrieve the cart's details."],
-  ["23", "useQueryGraphStep", "Retrieve the variant's details."],
+  ["26", "useQueryGraphStep", "Retrieve the variant's details."],
 ]
 
 ```ts title="src/workflows/add-custom-to-cart.ts" highlights={workflowHighlights}
@@ -543,6 +557,9 @@ export const addCustomToCartWorkflow = createWorkflow(
       entity: "cart",
       filters: { id: cart_id },
       fields: ["id", "currency_code"],
+      options: {
+        throwIfKeyNotFound: true,
+      },
     })
 
     const { data: variants } = useQueryGraphStep({
@@ -607,7 +624,10 @@ Next, you'll add the item with the custom price to the cart. First, add the foll
 
 ```ts title="src/workflows/add-custom-to-cart.ts"
 import { transform } from "@medusajs/framework/workflows-sdk"
-import { addToCartWorkflow } from "@medusajs/medusa/core-flows"
+import { 
+  acquireLockStep, 
+  addToCartWorkflow, 
+} from "@medusajs/medusa/core-flows"
 ```
 
 Then, replace the `TODO` in the workflow with the following:
@@ -623,6 +643,12 @@ const itemToAdd = transform({
   }]
 })
 
+acquireLockStep({
+  key: cart_id,
+  timeout: 2,
+  ttl: 10,
+})
+
 addToCartWorkflow.runAsStep({
   input: {
     items: itemToAdd,
@@ -633,7 +659,9 @@ addToCartWorkflow.runAsStep({
 // TODO retrieve and return cart
 ```
 
-You prepare the item to add to the cart using `transform` from the Workflows SDK. It allows you to manipulate and create variables in a workflow. After that, you use Medusa's `addToCartWorkflow` to add the item with the custom price to the cart.
+You prepare the item to add to the cart using `transform` from the Workflows SDK. It allows you to manipulate and create variables in a workflow.
+
+After that, you use Medusa's `acquireLockStep` to acquire a lock on the cart, and `addToCartWorkflow` to add the item with the custom price to the cart.
 
 <Note title="Tip">
 
@@ -645,6 +673,9 @@ Lastly, you'll retrieve the cart's details again and return them. Add the follow
 
 ```ts title="src/workflows/add-custom-to-cart.ts"
 import { WorkflowResponse } from "@medusajs/framework/workflows-sdk"
+import { 
+  releaseLockStep,
+} from "@medusajs/medusa/core-flows"
 ```
 
 And replace the last `TODO` in the workflow with the following:
@@ -656,12 +687,18 @@ const { data: updatedCarts } = useQueryGraphStep({
   fields: ["id", "items.*"],
 }).config({ name: "refetch-cart" })
 
+releaseLockStep({
+  key: cart_id,
+})
+
 return new WorkflowResponse({
   cart: updatedCarts[0],
 })
 ```
 
-In the code above, you retrieve the updated cart's details using the `useQueryGraphStep` helper step. To return data from the workflow, you create and return a `WorkflowResponse` instance. It accepts as a parameter the data to return, which is the updated cart.
+In the code above, you retrieve the updated cart's details using the `useQueryGraphStep` helper step. Then, you release the lock on the cart with the `releaseLockStep`.
+
+To return data from the workflow, you create and return a `WorkflowResponse` instance. It accepts as a parameter the data to return, which is the updated cart.
 
 In the next step, you'll use the workflow in a custom route to add an item with a custom price to the cart.