@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/review/guides/compute-aggregate-ratings.mdx

@@ -0,0 +1,57 @@
+---
+title: "Compute aggregate ratings"
+sidebarTitle: "Aggregate ratings"
+description: "Compute average ratings for products and sellers from server code."
+---
+
+In this guide, you'll learn how to compute average ratings for products and
+sellers from your own server code. This is useful when surfacing a rating on a
+storefront page or in a custom API route.
+
+The Review module service computes averages on demand instead of storing a
+denormalized column, so the numbers always reflect the current set of reviews.
+Resolve the service from the container to use its rating helpers.
+
+## Average for one target
+
+`getAvgRating` returns the average rating for a single product or seller:
+
+```ts title="src/api/custom/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { MercurModules } from "@mercurjs/types"
+
+export async function GET(req: MedusaRequest, res: MedusaResponse) {
+  const reviewModuleService = req.scope.resolve(MercurModules.REVIEW)
+
+  const rating = await reviewModuleService.getAvgRating("seller", "sel_123")
+
+  res.json({ rating })
+}
+```
+
+The first argument is the target type (`"product"` or `"seller"`), the second is
+its id. The method returns `null` when the target has no reviews yet.
+
+## Ratings for a list
+
+For list views, `getProductsWithRating` and `getSellersWithRating` return records
+with their average rating joined in, so you don't fan out a call per row:
+
+```ts
+const reviewModuleService = container.resolve(MercurModules.REVIEW)
+
+const sellers = await reviewModuleService.getSellersWithRating([
+  "id",
+  "name",
+])
+// => [{ id, name, rating }, ...]
+```
+
+Pass the fields you want selected from the target table; each returned record
+gains a `rating` field with the average.
+
+<Tip>
+  These helpers average across a target's linked reviews. Combine them with your
+  own `status` filter if you only want `published` reviews to count toward the
+  public number.
+</Tip>

package/content/platform/review/guides/create-a-review.mdx

@@ -0,0 +1,55 @@
+---
+title: "Create a review"
+sidebarTitle: "Create a review"
+description: "Create a review programmatically with createReviewWorkflow."
+---
+
+In this guide, you'll learn how to create a review from your own server code. This
+is useful in a custom storefront route, an import script, or a seed.
+
+Mercur exposes a `createReviewWorkflow` that validates the submission, creates the
+`Review` record, and links it to its target, order, and customer in one step. 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 { createReviewWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createReviewWorkflow(req.scope).run({
+    input: {
+      order_id: "order_123",
+      reference: "product",
+      reference_id: "prod_123",
+      rating: 5,
+      customer_note: "Exactly as described.",
+      customer_id: "cus_123",
+    },
+  })
+
+  res.status(201).json({ review: result })
+}
+```
+
+The `reference` field selects the target: pass `"product"` with a product id, or
+`"seller"` with a seller id, in `reference_id`.
+
+<Note>
+  The workflow validates that the `order_id` belongs to `customer_id` and that
+  the customer hasn't already reviewed the same target on that order. Either
+  check failing raises an error and no review is created.
+</Note>
+
+## Statuses on creation
+
+A new review is created as `pending` and stays hidden until it's moderated. See
+[Moderate a review](/platform/review/guides/moderate-a-review) to publish or
+reject it.
+
+<Tip>
+  A single order can back several reviews, one per distinct target. Create the
+  product review and the seller review as two separate calls with different
+  `reference` / `reference_id` values.
+</Tip>

package/content/platform/review/guides/moderate-a-review.mdx

@@ -0,0 +1,58 @@
+---
+title: "Moderate a review"
+sidebarTitle: "Moderate a review"
+description: "Publish, reject, and delete reviews from server code."
+---
+
+In this guide, you'll learn how to moderate reviews from your own server code.
+Moderation is a change to the review's `status`; removal is a soft delete that
+can be undone.
+
+## Publish or reject
+
+Move a `pending` review to `published` or `rejected` with `updateReviewWorkflow`,
+setting the `status` field:
+
+```ts title="src/api/custom/moderate/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { updateReviewWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  await updateReviewWorkflow(req.scope).run({
+    input: {
+      id: req.params.id,
+      status: "published",
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+`updateReviewWorkflow` also accepts `rating`, `customer_note`, and `seller_note`,
+so the same workflow is used for any correction to a review. It captures the
+previous values for compensation, so a failure downstream rolls the record back.
+
+## Delete a review
+
+Remove a review with `deleteReviewWorkflow`. This is a **soft delete**. The row
+is retained and restored automatically if the workflow is rolled back:
+
+```ts
+import { deleteReviewWorkflow } from "@mercurjs/core/workflows"
+
+await deleteReviewWorkflow(container).run({ input: "rev_123" })
+```
+
+<Warning>
+  A soft-deleted review stops counting toward aggregate ratings, but its row (and
+  its links) are kept. Use a hard delete through the service only if you need the
+  record gone permanently.
+</Warning>
+
+## React to moderation
+
+To run your own side effects when a review is published or rejected, wrap
+`updateReviewWorkflow` in a route that also runs your follow-up logic, or add a
+hook. See the [Events reference](/platform/review/reference/events) for the
+current state of review-domain events.

package/content/platform/review/guides/respond-to-a-review.mdx

@@ -0,0 +1,61 @@
+---
+title: "Respond to a review"
+sidebarTitle: "Respond to a review"
+description: "Attach a store's public response with respondReviewWorkflow."
+---
+
+In this guide, you'll learn how to attach a store's response to a review from your
+own server code. A response is a single public note the store adds to a review it
+received.
+
+## Run the workflow
+
+`respondReviewWorkflow` writes the `seller_note` on an existing review:
+
+```ts title="src/api/custom/respond/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { respondReviewWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  await respondReviewWorkflow(req.scope).run({
+    input: {
+      id: req.params.id,
+      seller_note: "Thanks for the feedback, glad it arrived quickly!",
+    },
+  })
+
+  res.sendStatus(200)
+}
+```
+
+<Note>
+  A store can respond **once**. The workflow throws if the review already has a
+  `seller_note`, and it throws `NOT_FOUND` if the review id doesn't exist. It
+  captures the previous value so a rollback clears the response again.
+</Note>
+
+## Clearing a response
+
+The respond flow won't overwrite an existing note. To replace a response, first
+clear it with `updateReviewWorkflow`, then respond again:
+
+```ts
+import {
+  updateReviewWorkflow,
+  respondReviewWorkflow,
+} from "@mercurjs/core/workflows"
+
+await updateReviewWorkflow(container).run({
+  input: { id: "rev_123", seller_note: null },
+})
+
+await respondReviewWorkflow(container).run({
+  input: { id: "rev_123", seller_note: "Updated response." },
+})
+```
+
+<Tip>
+  Responding never changes the review's `status`. A store can respond to a
+  `pending` review, but the response only becomes public once the review is
+  [published](/platform/review/guides/moderate-a-review).
+</Tip>

package/content/platform/review/overview.mdx

@@ -0,0 +1,87 @@
+---
+title: "Review"
+sidebarTitle: "Overview"
+description: "Collect, moderate, and surface customer ratings for products and sellers."
+---
+
+Use Mercur to let customers rate the products they bought and the stores they
+bought from.
+
+The Review domain captures a single rating model that points at either a product
+or a seller. It ties each review back to the order that earned it, and it moves
+through a moderation lifecycle before it goes public. Stores can respond to their
+reviews, and aggregate ratings roll up onto public seller and product pages. All
+of it is exposed directly through the Admin, Vendor, and Store APIs.
+
+<Note>
+  **One model, two targets.** A single `Review` entity (id prefix `rev`) covers
+  both product and seller reviews. A `reference` discriminator decides which one
+  a given review is about. There is no separate product-review or seller-review
+  table.
+</Note>
+
+## Key features
+
+- **Product & seller reviews:** one rating model, discriminated by a `reference` field.
+- **Order-backed:** every review is linked to the order that earned it, with one review per target per order.
+- **Moderation lifecycle:** reviews start `pending` and are moderated to `published` or `rejected`.
+- **Store responses:** a store can attach a single public response to each of its reviews.
+- **Aggregate ratings:** average ratings computed per product and per seller for storefront display.
+- **Customer notes:** an optional free-text note alongside the numeric rating.
+
+## Get started
+
+Learn how the domain fits together.
+
+<CardGroup cols={2}>
+  <Card title="The review model" icon="star" href="/platform/review/concepts/the-review-model">
+    The single review entity, its rating, notes, and status.
+  </Card>
+  <Card title="Product vs seller reviews" icon="tags" href="/platform/review/concepts/product-vs-seller-reviews">
+    The reference discriminator and the links that anchor each review.
+  </Card>
+  <Card title="Ratings & moderation" icon="gauge" href="/platform/review/concepts/ratings-and-moderation">
+    The status lifecycle, store responses, and aggregate ratings.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against the Review domain in your own code.
+
+<CardGroup cols={2}>
+  <Card title="Create a review" icon="plus" href="/platform/review/guides/create-a-review">
+    Run `createReviewWorkflow` from a route or script.
+  </Card>
+  <Card title="Moderate a review" icon="gavel" href="/platform/review/guides/moderate-a-review">
+    Publish, reject, and delete reviews in code.
+  </Card>
+  <Card title="Respond to a review" icon="reply" href="/platform/review/guides/respond-to-a-review">
+    Attach a store's response with `respondReviewWorkflow`.
+  </Card>
+  <Card title="Aggregate ratings" icon="calculator" href="/platform/review/guides/compute-aggregate-ratings">
+    Compute average ratings for products and sellers.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, links, workflows, service methods, and events for the Review domain.
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/review/reference/data-models">
+    The `Review` entity and its fields.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/review/reference/links">
+    How reviews link to products, sellers, orders, and customers.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/review/reference/workflows">
+    Create, update, respond, and delete workflows.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/review/reference/service">
+    Module service methods, including aggregate-rating helpers.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/review/reference/events">
+    Running side effects as reviews change.
+  </Card>
+</CardGroup>

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

@@ -0,0 +1,36 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data models owned by the Review domain."
+---
+
+The Review domain is owned by the **Review module**. This reference lists its
+data model and fields.
+
+## Review
+
+Table `review`, id prefix `rev`. A customer's rating of a single product or
+seller.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key |
+| `display_id` | serial | Human-readable auto-incrementing number |
+| `reference` | enum | `product` or `seller`, the review's target type |
+| `rating` | integer | The numeric score |
+| `customer_note` | text | Nullable, searchable. The customer's note |
+| `seller_note` | text | Nullable, searchable. The store's single response |
+| `status` | enum | `pending`, `published`, or `rejected`; default `pending` |
+| `created_at` | dateTime | Set on creation |
+| `updated_at` | dateTime | Updated on change |
+| `deleted_at` | dateTime | Nullable; set by soft delete |
+
+The target record itself is not a column on this model. It's resolved through a
+module link chosen by the `reference` value. See the
+[Links reference](/platform/review/reference/links).
+
+<Note>
+  The `review` table is indexed on `deleted_at` for soft-delete filtering.
+  Deleting a review through the workflow is a soft delete. The row is retained
+  and can be restored.
+</Note>

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

@@ -0,0 +1,61 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Running side effects as reviews are created, moderated, and answered."
+---
+
+The Review workflows handle validation, links, moderation, and compensation. They
+do **not** currently emit their own domain events. There is no `review.created`
+or `review.published` event to subscribe to today.
+
+To run side effects when a review changes, wrap the review workflows in your own
+route or workflow and run the follow-up logic there, or emit your own event and
+subscribe to it.
+
+## Emit your own event
+
+Emit an event alongside the workflow, then handle it in a subscriber:
+
+```ts title="src/api/custom/route.ts"
+import { Modules } from "@medusajs/framework/utils"
+import { createReviewWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req, res) {
+  const { result } = await createReviewWorkflow(req.scope).run({
+    input: req.body,
+  })
+
+  const eventBus = req.scope.resolve(Modules.EVENT_BUS)
+  await eventBus.emit({ name: "review.created", data: { id: result.id } })
+
+  res.status(201).json({ review: result })
+}
+```
+
+```ts title="src/subscribers/review-created.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function reviewCreatedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const reviewId = event.data.id
+  // ...notify the store, update a search index, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "review.created",
+}
+```
+
+<Note>
+  Because the module ships no events of its own, the event name in the example
+  above is one **you** define. Keep it consistent across the emit site and the
+  subscriber.
+</Note>
+
+## React without an event
+
+For side effects that must run transactionally with the review change, add a step
+to your own workflow that wraps the review workflow, rather than relying on an
+event. Events are handled asynchronously and outside the workflow's compensation.

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

@@ -0,0 +1,43 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Review domain links to products, sellers, orders, and customers."
+---
+
+Modules in Mercur never reference each other directly. They connect through
+**module links**. A review carries no foreign keys to its target on the model
+itself. Instead, four links anchor each review to the rest of the marketplace.
+Once a link is defined, you retrieve related records with `query.graph` using the
+link alias.
+
+```ts
+const { data: reviews } = await query.graph({
+  entity: "review",
+  fields: ["id", "rating", "product.*", "seller.*"],
+})
+```
+
+## Targets
+
+| Linked module | Relationship |
+| --- | --- |
+| **Product** | A product has many reviews (`product_product_review_review`). Written when `reference` is `product`. |
+| **Seller** | A seller has many reviews (`seller_seller_review_review`). Written when `reference` is `seller`. |
+
+A review is linked to **either** a product or a seller, never both. The
+`reference` field on the review decides which link is created.
+
+## Provenance
+
+| Linked module | Relationship |
+| --- | --- |
+| **Order** | Each review is linked to the order that earned it (`order_order_review_review`). |
+| **Customer** | Each review is linked to the customer who wrote it (`customer_customer_review_review`). |
+
+These two links are written for every review and back the validation that a
+customer can review a target only once per order.
+
+<Note>
+  All four links are list links (`isList: true`) on the owning side. A product,
+  seller, order, or customer has many reviews.
+</Note>

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

@@ -0,0 +1,54 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Review module service: CRUD methods and aggregate-rating helpers."
+---
+
+The Review module exposes a service you can resolve from the Medusa container to
+read and write records directly, without going through a workflow. Use it inside
+custom services, subscribers, scheduled jobs, or route handlers.
+
+```ts
+import { MercurModules } from "@mercurjs/types"
+
+const reviewModuleService = container.resolve(MercurModules.REVIEW)
+
+const [reviews, count] = await reviewModuleService.listAndCountReviews({
+  status: "published",
+})
+```
+
+## Generated methods
+
+The `Review` model gets a standard set of auto-generated methods:
+
+| Method | Description |
+| --- | --- |
+| `createReviews(data)` | Create one or more reviews |
+| `retrieveReview(id, config?)` | Retrieve a review by id |
+| `listReviews(filters?, config?)` | List reviews matching filters |
+| `listAndCountReviews(filters?, config?)` | List reviews with a total count |
+| `updateReviews(data)` | Update one or more reviews |
+| `deleteReviews(ids)` | Delete one or more reviews |
+| `softDeleteReviews(ids)` | Soft-delete reviews (restorable) |
+| `restoreReviews(ids)` | Restore soft-deleted reviews |
+
+## Aggregate-rating methods
+
+The service adds three helpers that compute average ratings on demand:
+
+| Method | Description |
+| --- | --- |
+| `getAvgRating(type, id)` | Average rating for one `"product"` or `"seller"`; `null` when it has no reviews |
+| `getProductsWithRating(fields)` | Product records with an average `rating` joined in |
+| `getSellersWithRating(fields)` | Seller records with an average `rating` joined in |
+
+See [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings)
+for usage.
+
+<Warning>
+  Prefer [workflows](/platform/review/reference/workflows) for anything with side
+  effects (creation with its validation and links, responses, moderation). The
+  service writes records directly and does **not** run the create-flow validation
+  or manage the target/order/customer links.
+</Warning>

package/content/platform/review/reference/workflows.mdx

@@ -0,0 +1,31 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Review workflows for creating, moderating, responding, and deleting."
+---
+
+This reference lists the workflows for the Review domain. Import them from
+`@mercurjs/core/workflows` and run them against the Medusa container.
+
+## Review workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `createReviewWorkflow` | `{ order_id, reference, reference_id, rating, customer_note?, customer_id }` | Validate and create a review, linking it to its target, order, and customer |
+| `updateReviewWorkflow` | `{ id, rating?, customer_note?, seller_note?, status? }` | Update a review, including moderating its `status` |
+| `respondReviewWorkflow` | `{ id, seller_note }` | Attach a store's single response to a review |
+| `deleteReviewWorkflow` | `id` | Soft-delete a review (restorable on rollback) |
+
+Each workflow supports compensation: `createReviewWorkflow` deletes the review it
+created on failure, `updateReviewWorkflow` and `respondReviewWorkflow` restore the
+previous values, and `deleteReviewWorkflow` restores the soft-deleted row.
+
+<Note>
+  `createReviewWorkflow` validates that the order belongs to the customer and
+  that the target hasn't already been reviewed on that order. `respondReviewWorkflow`
+  refuses to overwrite an existing response.
+</Note>
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/review/reference/service). To run side effects when
+a review changes, see the [Event reference](/platform/review/reference/events).

package/content/platform/store/concepts/lifecycle.mdx

@@ -0,0 +1,62 @@
+---
+title: "Lifecycle"
+sidebarTitle: "Lifecycle"
+description: "Store statuses, transitions, scheduled closures, and premium."
+---
+
+This page covers the store account lifecycle and the states a store moves through.
+
+## Status
+
+A store's state lives in the `status` field of the `Seller` model, typed by the
+`SellerStatus` enum. A store moves through four statuses.
+
+```
+                ┌───────────────────┐
+                │  pending_approval  │
+                └─────────┬─────────┘
+                          │ approve
+                          ▼
+   ┌───────────┐     ┌────────┐
+   │ suspended  │◄───►│  open   │
+   └───────────┘     └───┬────┘
+                         │ terminate
+                         ▼
+                  ┌────────────┐
+                  │ terminated  │
+                  └────────────┘
+```
+
+| Status | Meaning |
+| --- | --- |
+| `pending_approval` | Registered, waiting for operator review. |
+| `open` | Active. Can list offers, take orders, and collect payouts. |
+| `suspended` | Temporarily frozen. Offers stay listed but cannot be purchased. |
+| `terminated` | Permanently closed. This status is irreversible. |
+
+Only the operator can change a store's status. Each transition runs through a
+dedicated workflow: `approveSellerWorkflow`, `suspendSellerWorkflow`,
+`unsuspendSellerWorkflow`, and `terminateSellerWorkflow`.
+
+<Note>
+  Termination is irreversible. All orders and payouts must be resolved before a
+  store can be terminated.
+</Note>
+
+## Scheduled closures
+
+A store can schedule a temporary closure with the `closed_from` and `closed_to`
+fields without changing its status. During the window, the storefront shows as
+unavailable and no new orders are accepted. The account stays `open` and resumes
+on its own once `closed_to` passes.
+
+<Tip>
+  A closure overlays the current status. It is not a status of its own, and it
+  does not affect the transition rules.
+</Tip>
+
+## Premium
+
+The `is_premium` boolean is set only by the operator. Stores cannot designate
+themselves as premium. The storefront uses the flag for featured placement,
+badges, and curation priority.

package/content/platform/store/concepts/store-entity.mdx

@@ -0,0 +1,53 @@
+---
+title: "The store entity"
+sidebarTitle: "The store"
+description: "The seller record, its business identity, and its satellite data."
+---
+
+This page covers the store record and the data models that make up its business
+identity.
+
+## Store
+
+A store is the marketplace vendor. It owns offers, orders, and payouts, and it
+holds the profile shown to customers on the storefront. A store is represented by
+the `Seller` data model (table `seller`, id prefix `sel`).
+
+```ts
+const { result } = await createSellersWorkflow(container).run({
+  input: {
+    sellers: [
+      {
+        name: "Acme Supplies",
+        email: "team@acme.com",
+        currency_code: "usd",
+      },
+    ],
+  },
+})
+```
+
+<Tip>
+  A store settles in exactly one currency, set by `currency_code`. A seller who
+  needs to trade in several currencies creates a separate store for each one, and
+  each store operates independently.
+</Tip>
+
+## Professional details
+
+A store can carry professional details: a corporate name, a registration number,
+and a tax id. These are represented by the `ProfessionalDetails` data model. When
+this record is present, the store is a registered business. When it is absent,
+the store is an individual seller.
+
+## Addresses and payment details
+
+A store keeps its addresses as `SellerAddress` records, one each for a warehouse,
+return, or business address. The bank details used to settle payouts live on a
+`PaymentDetails` record. Both are satellite records of the store, and fulfillment
+and payout settlement read from them.
+
+<Note>
+  `ProfessionalDetails`, `SellerAddress`, and `PaymentDetails` are one-to-one with
+  the store and are deleted along with it.
+</Note>