@mercurjs/docs 2.3.8-canary.3 → 2.3.8-canary.4

package/content/platform/product-edit/guides/confirm-or-decline-a-change.mdx

@@ -1,76 +1,124 @@
 ---
-title: "Confirm or decline a change"
+title: "Confirm, decline, or cancel a product change"
 sidebarTitle: "Confirm or decline"
-description: "Resolve a pending product change from server code."
+description: "Resolve a pending product change from server code and react to the result."
 ---
 
-In this guide, you'll learn how to resolve a pending change from your own server
-code. Each resolution has a dedicated workflow so the side effects (applying
-actions, events, compensation) run consistently.
+Resolve a pending product change from your own code, for example in a custom review tool or an automated approval rule. Each resolution has its own workflow, so the status update, the product write, and the event always happen together.
+
+## Before you begin
+
+You need the following in place:
+
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A change in `pending` status. Changes stay `pending` only while the `product_request` feature flag is on, the default
+
+## Review and resolve a change
+
+Find the pending change, then confirm or decline it.
+
+<Steps>
+  <Step title="Find pending changes">
+    List the pending changes on a product with their actions, so a reviewer can see what each one does.
+
+    ```ts
+    const query = container.resolve("query")
+
+    const { data: changes } = await query.graph({
+      entity: "product_change",
+      fields: ["id", "created_by", "external_note", "actions.*"],
+      filters: {
+        product_id: "prod_01JD8Q1234567",
+        status: "pending",
+      },
+    })
+    ```
+
+    Each action’s `details` holds the proposed value and the previous one, as described in [Change actions](/platform/product-edit/concepts/change-actions).
+  </Step>
+  <Step title="Confirm the change">
+    `confirmProductChangeWorkflow` sets the changes to `confirmed`, applies their actions to the product, and emits `product-change.confirmed`.
+
+    ```ts title="src/api/admin/custom/changes/[id]/confirm/route.ts"
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest,
+      res: MedusaResponse
+    ) {
+      await confirmProductChangeWorkflow(req.scope).run({
+        input: {
+          ids: [req.params.id],
+          confirmed_by: req.auth_context.actor_id,
+        },
+      })
+
+      res.json({ id: req.params.id, status: "confirmed" })
+    }
+    ```
+
+    The input takes an `ids` array. Pass `internal_note` or `external_note` to overwrite the change’s notes as you confirm it.
+  </Step>
+  <Step title="Or decline it">
+    `rejectProductChangeWorkflow` sets one change to `declined` and leaves the product untouched. Give the seller a reason in `declined_reason`.
+
+    ```ts
+    import { rejectProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+    await rejectProductChangeWorkflow(container).run({
+      input: {
+        id: "prodch_01JD8Q1234567",
+        declined_by: "user_01JD8Q1234567",
+        declined_reason: "Photos don't meet the image guidelines",
+      },
+    })
+    ```
+
+    The workflow emits `product-change.declined` with the change id.
+  </Step>
+</Steps>
 
-## Confirm a change
-
-`confirmProductChangeWorkflow` marks the changes `confirmed`, applies their
-pending actions to the product, and emits `product-change.confirmed`.
-
-```ts title="src/api/custom/confirm/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { confirmProductChangeWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  await confirmProductChangeWorkflow(req.scope).run({
-    input: {
-      ids: [req.params.id],
-      confirmed_by: req.auth_context?.actor_id,
-    },
-  })
-
-  res.sendStatus(200)
-}
-```
-
-<Note>
-  Confirmation only applies actions that aren't already `applied`, so re-running
-  it never writes the same edit twice.
-</Note>
-
-## Decline a change
+## Cancel a change
 
-`rejectProductChangeWorkflow` moves a `pending` change to `declined` without
-touching the product, and emits `product-change.declined`.
+Cancel a change when it should be withdrawn rather than judged, for example when a seller retracts their own edit. Canceling frees the author to stage a new change on the product.
 
 ```ts
-import { rejectProductChangeWorkflow } from "@mercurjs/core/workflows"
+import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
 
-await rejectProductChangeWorkflow(container).run({
+await cancelProductChangeWorkflow(container).run({
   input: {
-    id: "prodch_123",
-    declined_by: "user_123",
-    declined_reason: "Images don't meet guidelines",
+    id: "prodch_01JD8Q1234567",
+    canceled_by: "sel_01JD8Q1234567",
   },
 })
 ```
 
-## Cancel a change
+The workflow sets `canceled_by` and `canceled_at`, then emits `product-change.canceled`.
 
-When the change should be withdrawn rather than judged (for example the vendor
-retracting their own submission), use `cancelProductChangeWorkflow`:
+## Confirm several changes at once
 
-```ts
-import { cancelProductChangeWorkflow } from "@mercurjs/core/workflows"
+`confirmProductChangeWorkflow` loads every id in `ids` before it writes anything. If one id doesn’t exist, it throws a `NOT_FOUND` error. If one change isn’t `pending`, it throws `NOT_ALLOWED`, and none of the changes are confirmed.
 
-await cancelProductChangeWorkflow(container).run({
-  input: { id: "prodch_123", canceled_by: "user_123" },
-})
-```
+## Handle a failed apply
+
+Applying actions runs Medusa’s product workflows inside the confirm workflow. If one of them fails, for example because a variant was already deleted, the workflow compensates: it restores the change to `pending` and clears `confirmed_by` and `confirmed_at`. Fix the cause, then confirm again.
+
+## Run your own logic on a resolution
+
+Each resolution workflow has a hook that receives the change ids and the `additional_data` you passed in:
+
+- **`confirmProductChangeWorkflow`**: `productChangeConfirmed`, with `{ ids, additional_data }`
+- **`rejectProductChangeWorkflow`**: `productChangeRejected`, with `{ id, additional_data }`
+- **`cancelProductChangeWorkflow`**: `productChangeCanceled`, with `{ id, additional_data }`
 
-<Warning>
-  Confirm, decline, and cancel all require the change to be `pending`. Resolving
-  an already-resolved change fails validation. A change is resolved exactly once.
-</Warning>
+Use a hook when your logic must succeed or fail together with the resolution. For side effects that can run later, such as an email to the seller, subscribe to the events listed in the [Events reference](/platform/product-edit/reference/events).
 
-## React to resolutions
+## Next steps
 
-To run your own side effects when a change resolves, subscribe to the events
-these workflows emit rather than polling. See the
-[Event reference](/platform/product-edit/reference/events).
+- [Send a proposed product back for a revision](/platform/product-edit/guides/request-a-revision)
+- [How actions apply on confirm](/platform/product-edit/concepts/change-actions#how-actions-apply)
+- [Workflow inputs and hooks](/platform/product-edit/reference/workflows)

package/content/platform/product-edit/guides/edit-a-product.mdx

@@ -1,74 +1,154 @@
 ---
-title: "Edit a product"
+title: "Stage a product edit from server code"
 sidebarTitle: "Edit a product"
-description: "Stage a product change from server code with the edit workflows."
+description: "Route a product edit through the review pipeline from a custom API route, a script, or a bulk tool."
 ---
 
-In this guide, you'll learn how to route a product edit through the change
-pipeline from your own server code, such as a custom API route or a bulk tool.
+Stage a product edit as a `ProductChange` instead of writing to the product, so it goes through the same review as an edit from the Vendor panel. Use this when you build your own edit surface, such as a bulk editor or an import.
 
-Instead of writing to a product directly, you stage a `ProductChange`. Mercur
-exposes high-level edit workflows that diff your update against the current
-product and stage only the fields that actually changed.
+## Before you begin
 
-## Update product fields
+You need the following in place:
 
-`productEditUpdateProductWorkflow` diffs the `update` payload against the product
-and stages an `UPDATE` action per changed field.
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A product id, and the id of the actor making the edit, such as a seller id (`sel_…`)
 
-```ts title="src/api/custom/edit/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+## Stage a field edit
+
+`productEditUpdateProductWorkflow` compares your update with the product and stages one action per field that differs.
+
+<Steps>
+  <Step title="Create the route">
+    Add a route under `/admin` so Medusa authenticates the caller, and pass the update to the workflow. The workflow returns the staged change.
+
+    ```ts title="src/api/admin/custom/products/[id]/edit/route.ts" {13-19}
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+
+    type Body = { title?: string; material?: string }
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest<Body>,
+      res: MedusaResponse
+    ) {
+      const { result } = await productEditUpdateProductWorkflow(req.scope).run({
+        input: {
+          product_id: req.params.id,
+          created_by: req.auth_context.actor_id,
+          update: req.body,
+        },
+      })
+
+      res.status(202).json({ product_change: result })
+    }
+    ```
+
+    The route answers `202` because the edit isn’t on the product yet. With the default `product_request` flag on, `result.status` is `pending`.
+  </Step>
+  <Step title="Handle an open change">
+    If the same `created_by` already has a `pending` change on the product, the workflow throws a `NOT_ALLOWED` error before it stages anything. Medusa’s error handler turns it into a `400` response. Cancel the open change with `cancelProductChangeWorkflow`, or wait for an operator to resolve it.
+  </Step>
+  <Step title="Read the staged actions">
+    Load the change with its actions to show the seller what’s waiting for review.
+
+    ```ts
+    const query = req.scope.resolve("query")
+
+    const { data: [change] } = await query.graph({
+      entity: "product_change",
+      fields: ["id", "status", "actions.action", "actions.details"],
+      filters: { id: result.id },
+    })
+    ```
+
+    Each `UPDATE` action carries `field`, `value`, and `previous_value` in `details`.
+  </Step>
+</Steps>
+
+If no field differs, the workflow still stages a change, with no actions. Compare the input yourself first when an empty change would confuse your reviewers.
+
+## Stage variant and attribute edits
+
+Variants and attributes have their own edit workflows, with the same pending check. `productEditUpdateVariantsWorkflow` takes a list of typed operations:
+
+```ts
+import { productEditUpdateVariantsWorkflow } from "@mercurjs/core/workflows"
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await productEditUpdateProductWorkflow(req.scope).run({
-    input: {
-      product_id: req.params.id,
-      created_by: req.auth_context?.actor_id,
-      update: { title: "Updated title", material: "Cotton" },
-    },
-  })
-
-  res.status(201).json({ product_change: result })
-}
+await productEditUpdateVariantsWorkflow(container).run({
+  input: {
+    product_id: "prod_01JD8Q1234567",
+    created_by: "sel_01JD8Q1234567",
+    operations: [
+      {
+        type: "update",
+        variant_id: "variant_01JD8Q1234567",
+        fields: { sku: "LINEN-M" },
+      },
+      { type: "remove", variant_id: "variant_01JD8Q1234568" },
+    ],
+  },
+})
 ```
 
-<Note>
-  If a product already has a `pending` change, staging another one is rejected.
-  Only one active change per product is allowed. Resolve or cancel the open
-  change first.
-</Note>
+Each operation becomes a `VARIANT_ADD`, `VARIANT_UPDATE`, or `VARIANT_REMOVE` action. An update whose fields all match the current variant stages nothing. For attributes, pass `add`, `remove`, and `update` arrays to `productEditUpdateAttributesWorkflow`, in the same shapes as the attribute batch.
 
 ## Stage actions directly
 
-For finer control (variants, attributes, mixed operations), stage the actions
-yourself with `stageProductChangeWorkflow`:
+For a mixed change, build the actions yourself and pass them to `stageProductChangeWorkflow`. It skips the diff and the pending check, so check for an open change first.
 
 ```ts
+import { ProductChangeActionType } from "@mercurjs/types"
 import { stageProductChangeWorkflow } from "@mercurjs/core/workflows"
 
 await stageProductChangeWorkflow(container).run({
   input: {
-    product_id: "prod_123",
-    created_by: "user_123",
+    product_id: "prod_01JD8Q1234567",
+    created_by: "sel_01JD8Q1234567",
+    external_note: "Spring catalog refresh",
     actions: [
-      { product_id: "prod_123", action: "UPDATE", details: { field: "subtitle", value: "New" } },
-      { product_id: "prod_123", action: "VARIANT_REMOVE", details: { variant_id: "variant_123" } },
+      {
+        product_id: "prod_01JD8Q1234567",
+        action: ProductChangeActionType.UPDATE,
+        details: { field: "subtitle", value: "Washed linen" },
+      },
     ],
   },
 })
 ```
 
-## Auto-confirm
+Every action needs its own `product_id`. The workflow fills in `product_change_id` for you.
+
+## Apply an edit without review
+
+Pass `auto_confirm: true` to `stageProductChangeWorkflow` or `productEditDeleteProductWorkflow` to confirm and apply the change in the same run. Use it for trusted sources, such as an operator tool. The change still lands in the trail as `confirmed`, and `product-change.confirmed` still fires.
+
+## Attach custom data with additional_data
+
+`productEditUpdateProductWorkflow` and `productEditUpdateAttributesWorkflow` accept `additional_data` and pass it to their `productChangeCreated` hook. Use the hook to store your own data on the change:
+
+```ts title="src/workflows/hooks/product-change-created.ts"
+import { productEditUpdateProductWorkflow } from "@mercurjs/core/workflows"
+import { MercurModules } from "@mercurjs/types"
+
+productEditUpdateProductWorkflow.hooks.productChangeCreated(
+  async ({ product_change, additional_data }, { container }) => {
+    const productEdit = container.resolve(MercurModules.PRODUCT_EDIT)
+
+    await productEdit.updateProductChanges({
+      id: product_change.id,
+      metadata: { ticket_id: additional_data?.ticket_id },
+    })
+  }
+)
+```
+
+The hook runs after staging and auto-confirm, so `product_change` is the record the workflow returns.
 
-Both workflows run auto-confirm after staging: with review off the change
-applies immediately, with review on it stays `pending`. Pass `auto_confirm: true`
-to `stageProductChangeWorkflow` to force immediate application regardless of the
-review setting.
+## Next steps
 
-<Tip>
-  Dedicated helpers exist for common shapes, such as
-  `productEditUpdateVariantsWorkflow`, `productEditUpdateAttributesWorkflow`, and
-  `productEditDeleteProductWorkflow`. Each stages the right action types for you.
-  See the [Workflows reference](/platform/product-edit/reference/workflows).
-</Tip>
+- [Confirm or decline the staged change](/platform/product-edit/guides/confirm-or-decline-a-change)
+- [Every action type and its `details`](/platform/product-edit/concepts/change-actions)
+- [Edit workflow inputs and hooks](/platform/product-edit/reference/workflows#edit-workflows)

package/content/platform/product-edit/guides/request-a-revision.mdx

@@ -1,54 +1,114 @@
 ---
-title: "Request a revision"
+title: "Send a proposed product back for a revision"
 sidebarTitle: "Request a revision"
-description: "Send a product submission back to the vendor from server code."
+description: "Ask a seller to rework a proposed product, record the request, and notify the seller."
 ---
 
-In this guide, you'll learn how to ask a vendor to rework a submission instead of
-approving or rejecting it outright.
+Ask a seller to rework a product they’ve proposed, instead of publishing or rejecting it. The request leaves the product `proposed`, adds a `CHANGE_REQUESTED` entry to its history, and emits an event you can use to notify the seller.
 
-A revision request doesn't mutate the product. It records a `CHANGE_REQUESTED`
-action in the audit trail carrying your message, and emits
-`product.change-requested` so the vendor is notified. The product stays with the
-vendor to revise and resubmit.
+## Before you begin
 
-## Run the workflow
+You need the following in place:
 
-`requestProductChangeWorkflow` validates that the product is in `proposed`,
-records the audit action, and emits the event.
+- A Mercur server with `@mercurjs/core` installed through `withMercur()`
+- A product with status `proposed`. The workflow fails for any other status
 
-```ts title="src/api/custom/request-revision/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+## Request and notify
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  await requestProductChangeWorkflow(req.scope).run({
-    input: {
-      product_id: req.params.id,
-      actor_id: req.auth_context?.actor_id,
-      message: "Please add a size guide and sharper photos.",
-    },
-  })
+Run the workflow from an admin route, then notify the seller from a subscriber.
 
-  res.sendStatus(200)
-}
+<Steps>
+  <Step title="Run the workflow">
+    `requestProductChangeWorkflow` checks the product status, records the audit change, and emits `product.change-requested`.
+
+    ```ts title="src/api/admin/custom/products/[id]/revise/route.ts"
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest<{ message: string }>,
+      res: MedusaResponse
+    ) {
+      await requestProductChangeWorkflow(req.scope).run({
+        input: {
+          product_id: req.params.id,
+          actor_id: req.auth_context.actor_id,
+          message: req.body.message,
+        },
+      })
+
+      res.json({ id: req.params.id })
+    }
+    ```
+
+    The message is optional. Without it, the action’s `details.message` is `null`.
+  </Step>
+  <Step title="Notify the seller">
+    Subscribe to `product.change-requested`. The payload carries the product id, not a change id, plus the message and the operator’s id.
+
+    ```ts title="src/subscribers/product-change-requested.ts"
+    import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+    type Payload = { id: string; message?: string; actor_id?: string }
+
+    export default async function handler({
+      event,
+      container,
+    }: SubscriberArgs<Payload>) {
+      const logger = container.resolve("logger")
+
+      logger.info(
+        `Revision requested on ${event.data.id}: ${event.data.message ?? ""}`
+      )
+    }
+
+    export const config: SubscriberConfig = {
+      event: "product.change-requested",
+    }
+    ```
+
+    Replace the log line with your notification, for example a call to Medusa’s Notification module.
+  </Step>
+</Steps>
+
+## Where the request is stored
+
+`requestProductChangeWorkflow` calls `recordProductAuditChangeWorkflow`, which stores the request as a change that starts out `confirmed`. The message is saved in two places:
+
+- **`details.message`**: on the `CHANGE_REQUESTED` action
+- **`external_note`**: on the change, where the seller-facing note lives
+
+Read every revision request on a product by querying its actions:
+
+```ts
+const { data: requests } = await query.graph({
+  entity: "product_change_action",
+  fields: ["details", "product_change.created_by", "created_at"],
+  filters: {
+    product_id: "prod_01JD8Q1234567",
+    action: "CHANGE_REQUESTED",
+  },
+})
 ```
 
-<Note>
-  The request is only valid while the product is `proposed`. The workflow
-  validates the product status first and fails otherwise.
-</Note>
+`product_change.created_by` is the operator who asked.
+
+## Publish or reject instead
+
+When the product is ready or can’t be fixed, resolve it with a product workflow instead. Both require the product to be `proposed`, and both record a confirmed `STATUS_CHANGE` audit change:
+
+- **`confirmProductsWorkflow`**: takes `product_ids`, sets them to `published`, and emits `product.published`
+- **`rejectProductWorkflow`**: takes `product_id` and an optional `message`, sets it to `rejected`, and emits `product.rejected`
+
+## Attach custom data with additional_data
 
-## Where the message goes
+`requestProductChangeWorkflow` passes `additional_data` to its `productChangeRequested` hook, along with `product_id` and `message`. Use it to store, for example, the checklist items the seller has to fix.
 
-The `message` is stored in two places for durability: the `CHANGE_REQUESTED`
-action's `details.message`, and the parent change's `external_note` (the
-vendor-facing note). Because the audit change is created already `confirmed`, the
-request is a permanent entry in the product's history.
+## Next steps
 
-<Tip>
-  Subscribe to `product.change-requested` to send the vendor a notification. The
-  payload includes the `id` (product), the `message`, and the `actor_id` of the
-  operator who asked. See the
-  [Event reference](/platform/product-edit/reference/events).
-</Tip>
+- [How audit changes fit the trail](/platform/product-edit/concepts/change-pipeline#audit-changes)
+- [Revision requests and statuses](/platform/product-edit/concepts/status-and-auto-confirm#revision-requests)
+- [Event payloads](/platform/product-edit/reference/events)