@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/catalog/concepts/product-seller-allowlist.mdx

@@ -0,0 +1,48 @@
+---
+title: "The store allowlist"
+sidebarTitle: "The allowlist"
+description: "The product_seller link that controls which stores may sell a master product."
+---
+
+In this document, you'll learn how Mercur controls which stores are allowed to
+sell a shared master product.
+
+## Product seller
+
+Since the catalog is shared, Mercur needs a way to say *which* stores may sell a
+given master product. That's the **product–seller allowlist**: a many-to-many
+link between Medusa's `Product` and Mercur's `Seller`, stored in the
+`product_seller` table.
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "sellers.id", "sellers.name"],
+  filters: { id: "prod_123" },
+})
+```
+
+A store appears in a product's `sellers` list only if it has been allowlisted.
+Being on the allowlist is what lets a store create an
+[offer](/platform/offer/overview) against the master product. Without it, the
+store cannot list that product for sale.
+
+<Note>
+  The allowlist link is created automatically for the submitting store when a
+  product is created with `seller_ids`, and managed afterwards with
+  `linkSellersToProductWorkflow`. See
+  [Allowlist stores](/platform/catalog/guides/allowlist-stores).
+</Note>
+
+## Category allowlist
+
+Product categories carry the same pattern through the `category_seller` link. It
+is a many-to-many association between `ProductCategory` and `Seller` that scopes
+which categories a store is associated with. Manage it with
+`linkSellersToProductCategoryWorkflow`.
+
+<Tip>
+  The allowlist governs the **right to sell**, not the sale itself. A store on
+  the allowlist still has to create an offer to actually list the product.
+  Allowlisting alone doesn't put anything on the storefront.
+</Tip>

package/content/platform/catalog/concepts/status-lifecycle.mdx

@@ -0,0 +1,58 @@
+---
+title: "Status lifecycle"
+sidebarTitle: "Status lifecycle"
+description: "How a master product moves from draft to proposed, published, or rejected."
+---
+
+In this document, you'll learn about the product status lifecycle and how a
+submission becomes a live catalog product.
+
+## Status
+
+A product's state is held in the `status` field of the `Product` model, typed by
+Medusa's `ProductStatus` enum. A master product moves through four statuses:
+
+```
+   ┌────────┐   submit    ┌──────────┐   approve   ┌────────────┐
+   │ draft   │ ──────────►│ proposed  │ ──────────►│ published  │
+   └────────┘             └────┬─────┘             └────────────┘
+                               │ reject
+                               ▼
+                         ┌────────────┐
+                         │ rejected   │
+                         └────────────┘
+```
+
+| Status | Meaning |
+| --- | --- |
+| `draft` | Work in progress, not yet submitted for review |
+| `proposed` | Submitted, awaiting operator review |
+| `published` | Approved and live in the shared catalog, sellable via offers |
+| `rejected` | Turned down during review |
+
+<Note>
+  Vendor-created products default to **`proposed`**. A store submits a product
+  for review rather than publishing it directly. An operator (or a low-risk
+  auto-confirm rule) is what promotes it to `published`.
+</Note>
+
+## Transitions
+
+Each review transition has a dedicated Mercur workflow so the audit trail,
+events, and side effects run consistently:
+
+| Workflow | Transition |
+| --- | --- |
+| `confirmProductsWorkflow` | `proposed` → `published` |
+| `rejectProductWorkflow` | `proposed` → `rejected` |
+| `requestProductChangeWorkflow` | stays `proposed`, asks the submitter for a revision |
+
+Every transition validates that the product is currently `proposed` before it
+runs, and records an immutable `STATUS_CHANGE` (or `CHANGE_REQUESTED`) action in
+the product-change pipeline for a full history of who reviewed what.
+
+<Tip>
+  Reviewing a product doesn't touch offers. Publishing makes the master product
+  sellable, but each store still lists it independently through its own
+  [offer](/platform/offer/overview).
+</Tip>

package/content/platform/catalog/concepts/variants-categories-collections.mdx

@@ -0,0 +1,49 @@
+---
+title: "Variants, categories & collections"
+sidebarTitle: "Variants & categories"
+description: "The native Medusa Product structure the shared catalog is built on."
+---
+
+In this document, you'll learn about the structural models that organize the
+shared catalog, all of them native to Medusa's Product module.
+
+## Product variant
+
+A variant is a purchasable configuration of a master product, represented by the
+`ProductVariant` data model (table `product_variant`, id prefix `variant`).
+Variants are generated from a product's options, including Mercur attributes
+marked as variant axes, and hold the SKU-level structure of the catalog entry.
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "variants.id", "variants.title", "options.*"],
+  filters: { id: "prod_123" },
+})
+```
+
+<Note>
+  Offer-based inventory and pricing live on the [offer](/platform/offer/overview),
+  not the variant. The variant defines the shared catalog structure. Each store's
+  stock and price come from its own offer.
+</Note>
+
+## Categories & collections
+
+Products are organized with Medusa's native grouping models:
+
+| Model | Purpose |
+| --- | --- |
+| `ProductCategory` | Hierarchical, nestable classification (id prefix `pcat`) |
+| `ProductCollection` | Flat, curated grouping (id prefix `pcol`) |
+| `ProductTag` | Free-form labels for filtering |
+| `ProductType` | A single type classification per product |
+
+Assign products to a category with `assignProductsToCategoryWorkflow`, which
+keeps each product in exactly one category at a time.
+
+<Tip>
+  Categories participate in the marketplace layer too: the `category_seller`
+  link scopes which stores a category is associated with, mirroring the product
+  [allowlist](/platform/catalog/concepts/product-seller-allowlist).
+</Tip>

package/content/platform/catalog/guides/allowlist-stores.mdx

@@ -0,0 +1,59 @@
+---
+title: "Allowlist stores"
+sidebarTitle: "Allowlist stores"
+description: "Grant and revoke a store's right to sell a master product from server code."
+---
+
+In this guide, you'll learn how to control which stores may sell a shared master
+product by managing the `product_seller` allowlist from your own server code.
+
+A store can only create an [offer](/platform/offer/overview) against a master
+product if it's on that product's allowlist. Mercur exposes
+`linkSellersToProductWorkflow` to add and remove stores in a single call.
+
+## Add and remove stores
+
+```ts title="src/api/custom/allowlist/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { linkSellersToProductWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  await linkSellersToProductWorkflow(req.scope).run({
+    input: {
+      id: req.params.id, // product id
+      add: ["sel_123", "sel_456"],
+      remove: ["sel_789"],
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+<Note>
+  `add` and `remove` are both optional. Pass either or both. Adding a store
+  that's already allowlisted is idempotent. Removing a store revokes its right
+  to sell the product going forward.
+</Note>
+
+## Allowlist a category
+
+Categories use the same shape through `linkSellersToProductCategoryWorkflow`,
+scoping which stores a category is associated with:
+
+```ts
+import { linkSellersToProductCategoryWorkflow } from "@mercurjs/core/workflows"
+
+await linkSellersToProductCategoryWorkflow(container).run({
+  input: {
+    id: "pcat_123",
+    add: ["sel_123"],
+  },
+})
+```
+
+<Tip>
+  Allowlisting grants the **right to sell**, not the listing itself. After a
+  store is allowlisted, it still has to create an offer for the product to
+  appear on its storefront.
+</Tip>

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

@@ -0,0 +1,70 @@
+---
+title: "Create a master product"
+sidebarTitle: "Create a master product"
+description: "Create a master product programmatically with createProductsWorkflow."
+---
+
+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.
+
+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.
+
+## Run the workflow
+
+```ts title="src/api/custom/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createProductsWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createProductsWorkflow(req.scope).run({
+    input: {
+      products: [
+        {
+          title: "Aeron Chair",
+          status: "proposed",
+          seller_ids: ["sel_123"],
+        },
+      ],
+      created_by: req.auth_context.actor_id,
+    },
+  })
+
+  res.status(201).json({ product: result[0] })
+}
+```
+
+<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>
+
+## Default status
+
+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).
+
+## Attach custom data
+
+The workflow accepts an `additional_data` payload passed to its hooks, letting
+you persist marketplace-specific data alongside the product without forking the
+workflow.
+
+```ts
+await createProductsWorkflow(req.scope).run({
+  input: {
+    products: [{ title: "Aeron Chair", seller_ids: ["sel_123"] }],
+    created_by: "usr_123",
+    additional_data: { source: "supplier-feed" },
+  },
+})
+```

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

@@ -0,0 +1,79 @@
+---
+title: "Publish or reject a product"
+sidebarTitle: "Publish or reject"
+description: "Move a proposed master product to published or rejected from server code."
+---
+
+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.
+
+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.
+
+## Publish a product
+
+Move one or more `proposed` products to `published` with
+`confirmProductsWorkflow`:
+
+```ts title="src/api/custom/publish/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+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",
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+## Reject a product
+
+```ts
+import { rejectProductWorkflow } from "@mercurjs/core/workflows"
+
+await rejectProductWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    message: "Images don't match the description",
+    actor_id: "usr_123",
+  },
+})
+```
+
+## Request a revision
+
+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"
+
+await requestProductChangeWorkflow(container).run({
+  input: {
+    product_id: "prod_123",
+    message: "Please add a size variant",
+    actor_id: "usr_123",
+  },
+})
+```
+
+<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>
+
+## React to review outcomes
+
+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.

package/content/platform/catalog/overview.mdx

@@ -0,0 +1,90 @@
+---
+title: "Catalog"
+sidebarTitle: "Overview"
+description: "Master products, variants, categories, and the store allowlist that governs who may sell what."
+---
+
+Use Mercur to govern one shared product catalog and control which stores are
+allowed to sell what.
+
+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).
+
+<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).
+</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.
+
+## Get started
+
+Learn how the domain fits 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.
+  </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.
+  </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.
+  </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.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Catalog domain in your own 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.
+  </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.
+  </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.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, workflows, service methods, and events for the Catalog domain.
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/catalog/reference/data-models">
+    The `Product`, `ProductVariant`, `ProductCategory`, and the `product_seller` table.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/catalog/reference/links">
+    How the catalog links to sellers, offers, attributes, and media.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/catalog/reference/workflows">
+    Mercur's product create, review, and allowlist workflows.
+  </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.
+  </Card>
+</CardGroup>

package/content/platform/catalog/reference/data-models.mdx

@@ -0,0 +1,66 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The Medusa Product models the catalog is built on, plus Mercur's marketplace layer."
+---
+
+The Catalog domain is owned by **Medusa's Product module**, with a marketplace
+layer added by Mercur. This reference lists the models at the Mercur-relevant
+level. It doesn't restate every Medusa product field. For the full module, see
+the [Medusa Product module](https://docs.medusajs.com/resources/commerce-modules/product).
+
+## Product
+
+Table `product`, id prefix `prod`. The shared master product, not owned by any
+store. The marketplace-relevant fields:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `title` | text | Searchable |
+| `handle` | text | Unique |
+| `subtitle` / `description` | text | Nullable |
+| `status` | enum | `ProductStatus`: `draft` / `proposed` / `published` / `rejected`, default `draft` |
+| `thumbnail` | text | Nullable |
+| `metadata` | json | Nullable |
+
+Relations used by the marketplace: `variants`, `options`, `categories`,
+`collection`, `tags`, `type`, `images` (native Medusa), plus Mercur's `sellers`
+(the allowlist), `offers`, `scoped_attributes`, and `changes` (audit history).
+
+## product_seller
+
+The **allowlist**: a many-to-many link table between `Product` and `Seller`
+controlling which stores may sell a master product.
+
+| Column | References |
+| --- | --- |
+| `product_id` | `product.id` |
+| `seller_id` | `seller.id` |
+
+A store on this table can create an [offer](/platform/offer/overview) against the
+product; a store not on it cannot.
+
+## ProductVariant
+
+Table `product_variant`, id prefix `variant`. A purchasable configuration of a
+master product, generated from its options and variant-axis attributes. Holds the
+SKU-level catalog structure. Offer-scoped price and inventory live on the offer,
+not here.
+
+## ProductCategory
+
+Table `product_category`, id prefix `pcat`. Hierarchical, nestable
+classification. Participates in the marketplace layer through the
+`category_seller` allowlist and the `media_images` link.
+
+## ProductCollection
+
+Table `product_collection`, id prefix `pcol`. Flat, curated grouping of products,
+with a `media_images` link for collection artwork.
+
+<Note>
+  `ProductTag` and `ProductType` round out the native grouping models: free-form
+  labels and a single type classification per product, respectively. They carry
+  no Mercur-specific columns.
+</Note>

package/content/platform/catalog/reference/events.mdx

@@ -0,0 +1,41 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Events emitted by the Catalog domain, for subscribers and side effects."
+---
+
+The Catalog domain emits events as products are created and reviewed. Subscribe
+to them to run side effects instead of polling, such as sending notifications,
+syncing external systems, or reindexing search.
+
+```ts title="src/subscribers/product-published.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function productPublishedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const productId = event.data.id
+  // ...reindex search, notify the seller, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "product.published",
+}
+```
+
+## Product events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `product.created` | A master product is created | `{ id }` |
+| `product.published` | A proposed product is approved (`→ published`) | `{ id, internal_note? }` |
+| `product.rejected` | A proposed product is rejected | `{ id, message? }` |
+| `product.change-requested` | A revision is requested on a proposed product | `{ id, message?, actor_id? }` |
+
+<Note>
+  These are the marketplace lifecycle events emitted by Mercur's product
+  workflows. Medusa's Product module also emits its own native events (e.g.
+  `product.updated`, `product-variant.created`) for lower-level changes. See the
+  [Medusa events reference](https://docs.medusajs.com/resources/events-reference).
+</Note>

package/content/platform/catalog/reference/links.mdx

@@ -0,0 +1,44 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the catalog links to sellers, offers, attributes, and media."
+---
+
+Modules in Mercur never reference each other directly. They connect through
+**module links**. The Catalog (Medusa's `Product` module) is wired into the
+marketplace layer with a set of links defined in Mercur core. Once a link is
+defined, you retrieve related records with `query.graph` using the link alias.
+
+```ts
+const { data: products } = await query.graph({
+  entity: "product",
+  fields: ["id", "title", "sellers.*", "offers.*", "changes.*"],
+})
+```
+
+## Marketplace
+
+| Linked module | Relationship |
+| --- | --- |
+| **Seller** | Many-to-many allowlist (`product_seller`) that controls which stores may sell a master product. Categories carry the same via `category_seller`. |
+| **Offer** | A product has many offers (`offer.product_id`, read-only). Offers are how a store sells against the master product. |
+| **Product change** | A product has many change records (`product.changes`, read-only): the immutable submission and review audit trail. |
+
+## Attributes
+
+| Linked module | Relationship |
+| --- | --- |
+| **Product attribute** | Product-scoped attributes resolve under `product.scoped_attributes` (read-only). Categories link attributes through `product_category_attribute`. |
+
+## Media
+
+| Linked module | Relationship |
+| --- | --- |
+| **Media** | Categories and collections link their artwork through the `media_images` alias (a `MediaImage` list). |
+
+<Note>
+  Read-only links (Offer, Product change, scoped attributes) are resolved from
+  the field on the owning record and can't be written through the link itself.
+  The `media_images` alias is deliberately **not** the bare `images` alias. That
+  would shadow the native `Product.images` relation and break product queries.
+</Note>

package/content/platform/catalog/reference/service.mdx

@@ -0,0 +1,52 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "Medusa's Product module service: methods for working with records directly."
+---
+
+The catalog is backed by **Medusa's Product module**, not a Mercur-specific one.
+Resolve its service from the container with the `Modules.PRODUCT` key to read and
+write products, variants, categories, and collections directly, without going
+through a workflow. Use it inside custom services, subscribers, or scheduled jobs.
+
+```ts
+import { Modules } from "@medusajs/framework/utils"
+
+const productModuleService = container.resolve(Modules.PRODUCT)
+
+const [products, count] = await productModuleService.listAndCountProducts({
+  status: "published",
+})
+```
+
+<Note>
+  Because this is Medusa's own module, the service key is `Modules.PRODUCT` from
+  `@medusajs/framework/utils`, **not** a `MercurModules` key. Mercur adds its
+  marketplace behavior (allowlist, review lifecycle, audit trail) as
+  [workflows](/platform/catalog/reference/workflows) layered on top of this
+  service.
+</Note>
+
+## Generated methods
+
+Each data model gets a standard set of auto-generated methods. For `Product`:
+
+| Method | Description |
+| --- | --- |
+| `createProducts(data)` | Create one or more products |
+| `retrieveProduct(id, config?)` | Retrieve a product by id |
+| `listProducts(filters?, config?)` | List products matching filters |
+| `listAndCountProducts(filters?, config?)` | List products with a total count |
+| `updateProducts(data)` | Update one or more products |
+| `deleteProducts(ids)` | Delete one or more products |
+
+The same set exists for every model in the module, such as `ProductVariant`,
+`ProductCategory`, `ProductCollection`, `ProductTag`, and `ProductType` (e.g.
+`createProductVariants`, `listProductCategories`, `updateProductCollections`).
+
+<Warning>
+  Prefer [workflows](/platform/catalog/reference/workflows) for anything with
+  side effects, such as submissions, review transitions, and allowlist changes. The
+  service writes records directly and does **not** run the marketplace layer,
+  emit Mercur's product events, or record the audit trail.
+</Warning>