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

package/content/platform/catalog/guides/create-a-master-product.mdx

@@ -1,70 +1,146 @@
 ---
-title: "Create a master product"
+title: "Create a master product from server code"
 sidebarTitle: "Create a master product"
-description: "Create a master product programmatically with createProductsWorkflow."
+description: "Add a product to the shared catalog with Mercur's createProductsWorkflow, including attributes, variants, and an allowlist."
 ---
 
-In this guide, you'll learn how to add a product to the shared catalog from your
-own server code, for example in a seed script, a custom API route, or an import
-flow.
+Run `createProductsWorkflow` to add a product to the shared catalog from a custom route, a seed script, or an import job. It creates the product and its variants, attaches attributes, links any stores you name, and records the submission.
 
-Mercur exposes a `createProductsWorkflow` that creates the `Product` record,
-attaches attributes and variants, records the submission for audit, and
-optionally allowlists the submitting store. Run it from any place that has access
-to the Medusa container.
+## Before you begin
 
-## Run the workflow
+You need the following in place:
 
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createProductsWorkflow } from "@mercurjs/core/workflows"
+- A Mercur server with `@mercurjs/core` installed
+- The ids of any [attributes](/platform/attribute/overview) and stores you want to reference
+
+<Warning>
+  Import `createProductsWorkflow` from `@mercurjs/core/workflows`, not `@medusajs/medusa/core-flows`. Medusa's workflow has the same name but skips attributes, the allowlist, and the audit record.
+</Warning>
+
+## Create the product
+
+<Steps>
+  <Step title="Add a route that runs the workflow">
+    Create an admin route. The workflow returns the created `ProductDTO` objects in input order.
+
+    ```ts title="src/api/admin/supplier-products/route.ts"
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest,
+      res: MedusaResponse
+    ) {
+      const { result } = await createProductsWorkflow(req.scope).run({
+        input: {
+          products: [{ title: "Aeron Chair", status: "proposed" }],
+          created_by: req.auth_context.actor_id,
+        },
+      })
+
+      res.status(201).json({ product: result[0] })
+    }
+    ```
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createProductsWorkflow(req.scope).run({
-    input: {
-      products: [
+    `created_by` is required. Mercur stores it on the `PRODUCT_ADD` change as the submitter. Without a `status`, the product starts as `draft`.
+  </Step>
+  <Step title="Add attributes and variants">
+    Pass `attributes` instead of native `options`. A `multi_select` attribute with `is_variant_axis` becomes the option that variants bind to by title.
+
+    ```ts
+    const product = {
+      title: "Aeron Chair",
+      status: "proposed" as const,
+      attributes: [
         {
-          title: "Aeron Chair",
-          status: "proposed",
-          seller_ids: ["sel_123"],
+          id: "pattr_01JD8Q1234567",
+          value_ids: ["pattrval_01JD8Q1234567"],
         },
+        { title: "Size", is_variant_axis: true, values: ["B", "C"] },
       ],
-      created_by: req.auth_context.actor_id,
-    },
-  })
-
-  res.status(201).json({ product: result[0] })
-}
-```
+      variants: [
+        { title: "Size B", options: { Size: "B" } },
+        { title: "Size C", options: { Size: "C" } },
+      ],
+    }
+    ```
 
-<Note>
-  Passing `seller_ids` allowlists those stores for the product as it's created,
-  so the submitting store can immediately create an
-  [offer](/platform/offer/overview) against it. `created_by` records who
-  submitted the product for the audit trail.
-</Note>
+    The first entry attaches a global attribute with a chosen value. The second creates a product-scoped axis. New variants get `manage_inventory: false` unless you set it, since stock lives on [offers](/platform/offer/overview).
+  </Step>
+  <Step title="Restrict the product to stores">
+    Add `seller_ids` to a product to put those stores on its [allowlist](/platform/catalog/concepts/product-seller-allowlist).
 
-## Default status
+    ```ts
+    const product = {
+      title: "Aeron Chair",
+      seller_ids: ["sel_01JD8Q1234567", "sel_01JD8Q1234568"],
+    }
+    ```
 
-A product created without an explicit `status` follows the marketplace's review
-flow. Vendor-created products default to **`proposed`**, submitted for operator
-review rather than published outright. Set `status: "draft"` to keep a product
-private until it's ready, or `status: "published"` from a trusted operator flow
-to skip review. See the
-[status lifecycle](/platform/catalog/concepts/status-lifecycle).
+    Only these 2 stores can see and sell the product once it's published. Leave `seller_ids` out to open it to every store.
+  </Step>
+</Steps>
 
-## Attach custom data
+## Submit on behalf of a store
 
-The workflow accepts an `additional_data` payload passed to its hooks, letting
-you persist marketplace-specific data alongside the product without forking the
-workflow.
+Pass the store's seller id as `created_by` to make the product a submission from that store. That's what the vendor API does, and it's how Mercur lets a store see its own `draft` and `proposed` products.
 
 ```ts
-await createProductsWorkflow(req.scope).run({
+await createProductsWorkflow(container).run({
   input: {
-    products: [{ title: "Aeron Chair", seller_ids: ["sel_123"] }],
-    created_by: "usr_123",
-    additional_data: { source: "supplier-feed" },
+    products: [{ title: "Desk lamp", status: "proposed" }],
+    created_by: "sel_01JD8Q1234567",
   },
 })
 ```
+
+The product appears in that store's product list as a proposed submission, and stays hidden from other stores until it's published.
+
+## Validate input with the validate hook
+
+The workflow runs a `validate` hook before it creates anything. Throw from the handler to stop the run.
+
+```ts title="src/workflows/hooks/validate-products.ts"
+import { createProductsWorkflow } from "@mercurjs/core/workflows"
+import { MedusaError } from "@medusajs/framework/utils"
+
+createProductsWorkflow.hooks.validate(async ({ products }) => {
+  const missing = products.find((p) => !p.description)
+  if (missing) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      `Product "${missing.title}" needs a description`
+    )
+  }
+})
+```
+
+The hook receives the raw `input` and its `products` array, so you can check any field before Medusa writes rows.
+
+## Attach custom data with additional_data
+
+Pass `additional_data` to carry extra values through the run. Mercur forwards it to Medusa's product and variant workflows and to the `productsCreated` hook.
+
+```ts title="src/workflows/hooks/products-created.ts"
+import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+createProductsWorkflow.hooks.productsCreated(
+  async ({ products, additional_data }, { container }) => {
+    const logger = container.resolve("logger")
+    const source = additional_data?.source
+
+    logger.info(`Imported ${products.length} products from ${source}`)
+  }
+)
+```
+
+Call the workflow with `additional_data: { source: "supplier_feed" }` and the handler receives it next to the created products.
+
+## Next steps
+
+- [Publish or reject a product](/platform/catalog/guides/publish-or-reject-a-product) to review what you created
+- [Allowlist stores](/platform/catalog/guides/allowlist-stores) to change the store list later
+- [Create an offer](/platform/offer/guides/create-an-offer) so a store can sell the product

package/content/platform/catalog/guides/publish-or-reject-a-product.mdx

@@ -1,79 +1,144 @@
 ---
-title: "Publish or reject a product"
+title: "Publish or reject a proposed product"
 sidebarTitle: "Publish or reject"
-description: "Move a proposed master product to published or rejected from server code."
+description: "Review a store's product submission from server code: publish it, reject it, or ask for a revision."
 ---
 
-In this guide, you'll learn how to review a submitted product from your own
-server code. Each transition has a dedicated workflow so the audit trail, events,
-and side effects run consistently.
+Run Mercur's review workflows to decide on a `proposed` product from a custom route, a subscriber, or a scheduled job. Each one checks the status, records who reviewed the product, and emits an event.
 
-A product enters review as `proposed`. From there you can publish it, reject it,
-or ask the submitter for a revision. Every workflow validates that the product is
-currently `proposed` before it runs.
+## Before you begin
 
-## Publish a product
+You need the following in place:
 
-Move one or more `proposed` products to `published` with
-`confirmProductsWorkflow`:
+- A product in `proposed` status, such as a store submission
+- The id of the operator or system acting, for the audit record
 
-```ts title="src/api/custom/publish/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+The workflows fail with a `NOT_ALLOWED` error for any product that isn't `proposed`.
+
+## Review a product
+
+<Steps>
+  <Step title="Publish it">
+    `confirmProductsWorkflow` publishes one or more products in a single run. `internal_note` is stored on each audit record for operators.
+
+    ```ts title="src/api/admin/reviews/publish/route.ts"
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
+
+    type Body = { product_ids: string[] }
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest<Body>,
+      res: MedusaResponse
+    ) {
+      await confirmProductsWorkflow(req.scope).run({
+        input: {
+          product_ids: req.body.product_ids,
+          actor_id: req.auth_context.actor_id,
+          internal_note: "Checked against the supplier sheet",
+        },
+      })
+
+      res.json({ published: req.body.product_ids })
+    }
+    ```
+
+    If any product isn't `proposed`, the run fails and none of them change.
+  </Step>
+  <Step title="Or reject it">
+    `rejectProductWorkflow` handles one product. `message` is stored as the change's `external_note`, the note the store can read.
+
+    ```ts
+    import { rejectProductWorkflow } from "@mercurjs/core/workflows"
+
+    await rejectProductWorkflow(container).run({
+      input: {
+        product_id: "prod_01JD8Q1234567",
+        message: "Images don't match the description",
+        actor_id: "user_01JD8Q1234567",
+      },
+    })
+    ```
+
+    The product moves to `rejected` and leaves the store's product list.
+  </Step>
+  <Step title="Or ask for a revision">
+    `requestProductChangeWorkflow` keeps the product `proposed` and records a `CHANGE_REQUESTED` action with your message.
+
+    ```ts
+    import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+
+    await requestProductChangeWorkflow(container).run({
+      input: {
+        product_id: "prod_01JD8Q1234567",
+        message: "Add a size B variant",
+        actor_id: "user_01JD8Q1234567",
+      },
+    })
+    ```
+
+    The product stays in the review queue, and your message is stored as the change's `external_note`.
+  </Step>
+</Steps>
+
+## Run a review from a subscriber
+
+Review products automatically by running a workflow when they're created. This subscriber publishes products from one trusted store.
+
+```ts title="src/subscribers/auto-publish-trusted.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
 import { confirmProductsWorkflow } from "@mercurjs/core/workflows"
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  await confirmProductsWorkflow(req.scope).run({
-    input: {
-      product_ids: [req.params.id],
-      actor_id: req.auth_context.actor_id,
-      internal_note: "Looks good",
-    },
+export default async function autoPublish({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const query = container.resolve("query")
+  const { data: [action] } = await query.graph({
+    entity: "product_change_action",
+    fields: ["product_change.created_by"],
+    filters: { product_id: event.data.id, action: "PRODUCT_ADD" },
   })
+  if (action?.product_change?.created_by !== "sel_01JD8Q1234567") return
 
-  res.sendStatus(200)
+  await confirmProductsWorkflow(container).run({
+    input: { product_ids: [event.data.id], actor_id: "system" },
+  })
 }
+
+export const config: SubscriberConfig = { event: "product.created" }
 ```
 
-## Reject a product
+The handler reads the `PRODUCT_ADD` record to find the submitter, then publishes. `product.created` fires twice for each product created through Mercur's workflow, so the second run fails the `proposed` check. Catch that error, or check the status first.
 
-```ts
-import { rejectProductWorkflow } from "@mercurjs/core/workflows"
+## React to the outcome with hooks
 
-await rejectProductWorkflow(container).run({
-  input: {
-    product_id: "prod_123",
-    message: "Images don't match the description",
-    actor_id: "usr_123",
-  },
-})
-```
+Each review workflow exposes a hook that runs after the status change. Use it for side effects that must happen inside the same run.
 
-## Request a revision
+| Workflow | Hook | Hook input |
+| --- | --- | --- |
+| `confirmProductsWorkflow` | `productsConfirmed` | `product_ids`, `internal_note`, `additional_data` |
+| `rejectProductWorkflow` | `productRejected` | `product_id`, `message`, `additional_data` |
+| `requestProductChangeWorkflow` | `productChangeRequested` | `product_id`, `message`, `additional_data` |
 
-To send the submission back for changes without rejecting it, use
-`requestProductChangeWorkflow`. The product stays `proposed` and a
-`CHANGE_REQUESTED` action is recorded for the submitter to act on:
-
-```ts
-import { requestProductChangeWorkflow } from "@mercurjs/core/workflows"
+```ts title="src/workflows/hooks/product-rejected.ts"
+import { rejectProductWorkflow } from "@mercurjs/core/workflows"
 
-await requestProductChangeWorkflow(container).run({
-  input: {
-    product_id: "prod_123",
-    message: "Please add a size variant",
-    actor_id: "usr_123",
-  },
-})
+rejectProductWorkflow.hooks.productRejected(
+  async ({ product_id, message }, { container }) => {
+    const logger = container.resolve("logger")
+    logger.info(`Rejected ${product_id}: ${message ?? "no reason"}`)
+  }
+)
 ```
 
-<Warning>
-  These workflows require the product to be `proposed`. Running them against a
-  `draft`, `published`, or `rejected` product fails validation rather than
-  forcing the transition.
-</Warning>
+For work that can run later, subscribe to `product.published`, `product.rejected`, or `product.change-requested` instead.
 
-## React to review outcomes
+## Next steps
 
-To run your own side effects when a product is published or rejected, subscribe
-to the events these workflows emit rather than polling. See the
-[Event reference](/platform/catalog/reference/events) for the event names.
+- [Event reference](/platform/catalog/reference/events) for payloads
+- [Status lifecycle](/platform/catalog/concepts/status-lifecycle) for every transition
+- [Request a revision](/platform/product-edit/guides/request-a-revision) for edits to published products

package/content/platform/catalog/overview.mdx

@@ -1,90 +1,94 @@
 ---
 title: "Catalog"
 sidebarTitle: "Overview"
-description: "Master products, variants, categories, and the store allowlist that governs who may sell what."
+description: "Keep one shared product catalog, decide which stores may sell each product, and review what stores submit."
 ---
 
-Use Mercur to govern one shared product catalog and control which stores are
-allowed to sell what.
+Use Mercur to keep one product catalog for the whole marketplace and control which stores can sell each product.
 
-Master-data governance lives here. The Catalog domain keeps products as a single
-shared source of truth, controls access to it through an allowlist over who may
-sell each product, and holds every submission to an approval lifecycle before it
-goes live. On top of that governance layer it holds master products, variants,
-categories, collections, tags, and types. A store never owns a product. It sells
-against a shared master product through an [offer](/platform/offer/overview).
+The catalog is Medusa's Product module (`Modules.PRODUCT`) with a marketplace layer on top. Products, variants, categories, collections, tags, and types are native Medusa models. Mercur adds the `product_seller` allowlist, a review flow over the product `status`, an audit record for every submission, and its own product workflows. No store owns a product: a store sells a master product through an [offer](/platform/offer/overview) that carries its own SKU, price, and stock.
+
+<img className="block dark:hidden" src="/images/figures/catalog-overview-light.svg" alt="A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted." />
+<img className="hidden dark:block" src="/images/figures/catalog-overview-dark.svg" alt="A product_seller link table behind a Products list of the shared catalog: each master product shows its status, the stores on its allowlist, and its offer count, with the Linen shirt restricted to ACME highlighted." />
 
 <Note>
-  **Catalog = Medusa's Product module + Mercur's marketplace layer.** Products,
-  variants, categories, and collections are Medusa's native `Product` module.
-  Mercur adds the `product_seller` allowlist (which stores may sell a product),
-  the `draft` → `proposed` → `published` / `rejected` status lifecycle, and its
-  own product workflows. Products are **shared master products**, not
-  seller-owned, and a store sells one via an [offer](/platform/offer/overview).
+  There's no Mercur catalog module. Resolve the service with `Modules.PRODUCT` from `@medusajs/framework/utils`, and run Mercur's product workflows from `@mercurjs/core/workflows`. Mercur's `createProductsWorkflow` has the same name as Medusa's, so check the import path.
 </Note>
 
 ## Key features
 
-- **Shared master data:** products live in one catalog, not owned by any store. Creating a product adds it to the shared catalog.
-- **Allowlist access control:** the `product_seller` link governs which stores may sell a given master product.
-- **Approval governance:** a `draft` → `proposed` → `published` / `rejected` lifecycle, with vendor-created products defaulting to `proposed`.
-- **Attribution, not ownership:** the creator of an unreviewed submission is recorded for audit, but the product still belongs to the shared catalog.
-- **Native Medusa structure:** variants, categories, collections, tags, and types come straight from Medusa's Product module.
-- **Sold via offers:** a store lists a master product by creating an offer that carries its SKU, price, and inventory.
+The catalog layer covers how products enter the marketplace and who can sell them:
+
+- **Shared master products**: one `Product` record per item, sold by any number of stores through offers
+- **Store allowlist**: the `product_seller` link restricts a product to the stores on it; a product with no rows is open to every store
+- **Review flow**: vendor submissions start as `proposed` and an operator publishes or rejects them
+- **Submission audit**: every create and review step writes a confirmed `ProductChange` record with the actor who did it
+- **Attribute-driven variants**: products take Mercur attributes on create, and variant-axis attributes become the options variants bind to
+- **Native structure**: variants, categories, collections, tags, and types come straight from Medusa's Product module
+
+## How it works
+
+A product moves through the catalog in a fixed order:
+
+1. A store or an operator runs `createProductsWorkflow`. Vendor submissions default to `proposed`.
+2. The workflow records a `PRODUCT_ADD` change with the creator as `created_by`, and links any `seller_ids` to the product.
+3. An operator runs `confirmProductsWorkflow`, `rejectProductWorkflow`, or `requestProductChangeWorkflow` on the proposed product.
+4. Once `published`, the product shows in the Store API and to every store its allowlist permits.
+5. Each store that sells it creates an offer against one of its variants.
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how master products, the allowlist, and statuses fit together.
 
 <CardGroup cols={2}>
   <Card title="Master products" icon="box" href="/platform/catalog/concepts/master-products">
-    The shared catalog, why products aren't seller-owned, and submission attribution.
+    Why products belong to the catalog and how Mercur records who submitted them.
   </Card>
   <Card title="The store allowlist" icon="user-lock" href="/platform/catalog/concepts/product-seller-allowlist">
-    The `product_seller` link that controls who may sell a product.
+    How the `product_seller` link decides which stores see and sell a product.
   </Card>
   <Card title="Status lifecycle" icon="arrows-rotate" href="/platform/catalog/concepts/status-lifecycle">
-    Draft, proposed, published, and rejected, plus how products move between them.
+    The four statuses and the workflow behind each transition.
   </Card>
   <Card title="Variants & categories" icon="sitemap" href="/platform/catalog/concepts/variants-categories-collections">
-    Variants, categories, collections, tags, and types from Medusa's Product module.
+    The Medusa models that structure the catalog, and where Mercur extends them.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against the Catalog domain in your own code.
+Build against the catalog in your own server code.
 
 <CardGroup cols={2}>
   <Card title="Create a master product" icon="plus" href="/platform/catalog/guides/create-a-master-product">
-    Run `createProductsWorkflow` from a route or seed script.
+    Run `createProductsWorkflow` with attributes, variants, and an allowlist.
   </Card>
   <Card title="Allowlist stores" icon="user-plus" href="/platform/catalog/guides/allowlist-stores">
-    Grant and revoke a store's right to sell a product in code.
+    Restrict a product to chosen stores, or open it to all of them again.
   </Card>
   <Card title="Publish or reject" icon="gavel" href="/platform/catalog/guides/publish-or-reject-a-product">
-    Move a proposed product to published or rejected.
+    Review a proposed product from a route or a subscriber.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, workflows, service methods, and events for the Catalog domain.
+The data models, links, workflows, service methods, and events behind the catalog.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/catalog/reference/data-models">
-    The `Product`, `ProductVariant`, `ProductCategory`, and the `product_seller` table.
+    `Product`, `ProductVariant`, `ProductCategory`, and the other Product module models.
   </Card>
   <Card title="Links" icon="link" href="/platform/catalog/reference/links">
-    How the catalog links to sellers, offers, attributes, and media.
+    How products and categories link to stores, offers, attributes, changes, and media.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/catalog/reference/workflows">
-    Mercur's product create, review, and allowlist workflows.
+    Mercur's create, review, allowlist, and category workflows with their hooks.
   </Card>
   <Card title="Service" icon="gear" href="/platform/catalog/reference/service">
     Medusa's Product module service, resolved with `Modules.PRODUCT`.
   </Card>
   <Card title="Events" icon="bell" href="/platform/catalog/reference/events">
-    Events emitted as products are created and reviewed.
+    The events Mercur emits when products are created and reviewed.
   </Card>
 </CardGroup>