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

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

@@ -1,57 +1,82 @@
 ---
-title: "Compute aggregate ratings"
+title: "Show average ratings on your storefront"
 sidebarTitle: "Aggregate ratings"
-description: "Compute average ratings for products and sellers from server code."
+description: "Serve average ratings for products and stores from a custom route, with the service helpers or from published reviews only."
 ---
 
-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.
+Add a Store API route that returns a product’s or a store’s average rating, because core ships no public rating endpoint. You can call the Review module service’s rating helpers, which average every linked review, or compute the average from published reviews with `query.graph`.
 
-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.
+## Before you begin
 
-## Average for one target
+Pick the approach that matches what should count toward the number:
 
-`getAvgRating` returns the average rating for a single product or seller:
+- **Rating helpers**: one SQL query per call; counts `pending`, `rejected`, and soft deleted reviews too
+- **Published only**: loads the target’s reviews with `query.graph` and averages the `published` ones
 
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { MercurModules } from "@mercurjs/types"
+<Steps>
+  <Step title="Return a store's average from the service">
+    Resolve the service with `MercurModules.REVIEW` and call `getAvgRating`:
 
-export async function GET(req: MedusaRequest, res: MedusaResponse) {
-  const reviewModuleService = req.scope.resolve(MercurModules.REVIEW)
+    ```ts title="src/api/store/sellers/[id]/rating/route.ts"
+    import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { MercurModules } from "@mercurjs/types"
 
-  const rating = await reviewModuleService.getAvgRating("seller", "sel_123")
+    export async function GET(req: MedusaRequest, res: MedusaResponse) {
+      const reviewService = req.scope.resolve(MercurModules.REVIEW)
 
-  res.json({ rating })
-}
-```
+      const average = await reviewService.getAvgRating("seller", req.params.id)
+
+      res.json({ rating: average === null ? null : Number(average) })
+    }
+    ```
+
+    The first argument is `"product"` or `"seller"`, the second the target’s id. The method returns a numeric string, or `null` when the target has no reviews, so the route converts it to a number.
+  </Step>
+  <Step title="Average published reviews only">
+    Load the product’s linked reviews with `query.graph` and average the published ones:
+
+    ```ts title="src/api/store/products/[id]/rating/route.ts"
+    import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
-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.
+    export async function GET(req: MedusaRequest, res: MedusaResponse) {
+      const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+      const { data: [product] } = await query.graph({
+        entity: "product",
+        fields: ["id", "reviews.rating", "reviews.status"],
+        filters: { id: req.params.id },
+      })
 
-## Ratings for a list
+      const ratings = (product?.reviews ?? [])
+        .filter((review) => review?.status === "published")
+        .map((review) => review!.rating)
+      const rating = ratings.length
+        ? ratings.reduce((sum, value) => sum + value, 0) / ratings.length
+        : null
 
-For list views, `getProductsWithRating` and `getSellersWithRating` return records
-with their average rating joined in, so you don't fan out a call per row:
+      res.json({ rating, count: ratings.length })
+    }
+    ```
+
+    `reviews` is the alias the product to review link adds to a product. Soft deleted reviews don’t come back from `query.graph`, so they never count.
+  </Step>
+</Steps>
+
+## Rate every product or store in one query
+
+For list pages, `getProductsWithRating` and `getSellersWithRating` return every row of the `product` or `seller` table with its average joined in:
 
 ```ts
-const reviewModuleService = container.resolve(MercurModules.REVIEW)
+const reviewService = container.resolve(MercurModules.REVIEW)
 
-const sellers = await reviewModuleService.getSellersWithRating([
-  "id",
-  "name",
-])
-// => [{ id, name, rating }, ...]
+const sellers = await reviewService.getSellersWithRating(["id", "name"])
+// [{ id: "sel_01JD8Q1234567", name: "ACME", rating: "4.5000000000000000" }]
 ```
 
-Pass the fields you want selected from the target table; each returned record
-gains a `rating` field with the average.
+Pass column names of the target table. Each row gains a `rating` string, or `null` for rows without reviews. The helpers take no filters or pagination and include soft deleted products and sellers, so filter the result before you return it.
+
+## Next steps
 
-<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>
+- [Learn what the rating helpers count](/platform/review/concepts/ratings-and-moderation)
+- [See every service method](/platform/review/reference/service)
+- [Query reviews through their links](/platform/review/reference/links)

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

@@ -1,55 +1,125 @@
 ---
-title: "Create a review"
+title: "Create a review from your own route"
 sidebarTitle: "Create a review"
-description: "Create a review programmatically with createReviewWorkflow."
+description: "Run createReviewWorkflow from a custom API route, an import script, or a seed."
 ---
 
-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.
+Run `createReviewWorkflow` to create a review outside the built-in `POST /store/reviews` route, for example in a custom checkout follow-up, an import script, or a seed. The workflow validates the order, creates the review as `pending`, and writes its four links.
 
-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.
+## Before you begin
 
-## Run the workflow
+You need the following:
 
-```ts title="src/api/custom/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createReviewWorkflow } from "@mercurjs/core/workflows"
+- **A customer and an order**: the order’s `customer_id` must match the customer you pass
+- **A target id**: a product id for a product review, or a seller id for a store review
+- **Mercur core installed**: the Review module ships in `@mercurjs/core`, so there’s nothing else to register
 
-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",
-    },
-  })
+<Steps>
+  <Step title="Add the route">
+    Create a route that reads the signed-in customer and runs the workflow:
 
-  res.status(201).json({ review: result })
+    ```ts title="src/api/store/order-reviews/route.ts" {14-22}
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { createReviewWorkflow } from "@mercurjs/core/workflows"
+
+    type Body = { order_id: string; product_id: string; rating: number }
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest<Body>,
+      res: MedusaResponse
+    ) {
+      const { order_id, product_id, rating } = req.body
+      const { result } = await createReviewWorkflow(req.scope).run({
+        input: {
+          order_id,
+          reference: "product",
+          reference_id: product_id,
+          rating,
+          customer_id: req.auth_context.actor_id,
+        },
+      })
+
+      res.status(201).json({ review: result })
+    }
+    ```
+
+    The route always creates a product review. Pass `reference: "seller"` with a seller id in `reference_id` to rate a store instead. `customer_note` is optional and defaults to `null`.
+  </Step>
+  <Step title="Require a signed-in customer">
+    Custom `/store` routes aren’t authenticated by default. Add the `authenticate` middleware so `auth_context.actor_id` holds the customer id:
+
+    ```ts title="src/api/middlewares.ts"
+    import { authenticate, defineMiddlewares } from "@medusajs/framework/http"
+
+    export default defineMiddlewares({
+      routes: [
+        {
+          method: ["POST"],
+          matcher: "/store/order-reviews",
+          middlewares: [authenticate("customer", ["session", "bearer"])],
+        },
+      ],
+    })
+    ```
+
+    This is the same middleware the built-in Store review routes use.
+  </Step>
+  <Step title="Call the route">
+    Send a request as the customer who placed the order:
+
+    ```bash
+    curl -X POST http://localhost:9000/store/order-reviews \
+      -H "Authorization: Bearer your_customer_token" \
+      -H "x-publishable-api-key: your_publishable_key" \
+      -H "Content-Type: application/json" \
+      -d '{
+        "order_id": "order_01JD8Q1234567",
+        "product_id": "prod_01JD8Q1234568",
+        "rating": 5
+      }'
+    ```
+
+    The response holds the new review with `status: "pending"`.
+  </Step>
+</Steps>
+
+## Validate the rating and the target
+
+`createReviewWorkflow` checks only that the order belongs to the customer and that the order hasn’t reviewed this target yet. It stores any `rating` you pass and doesn’t check that the product or seller was part of the order. Validate both before you run it:
+
+```ts title="src/api/store/order-reviews/route.ts"
+if (!Number.isInteger(rating) || rating < 1 || rating > 5) {
+  throw new MedusaError(MedusaError.Types.INVALID_DATA, "Invalid rating")
+}
+
+const query = req.scope.resolve(ContainerRegistrationKeys.QUERY)
+const { data: [order] } = await query.graph({
+  entity: "order",
+  fields: ["items.product_id"],
+  filters: { id: order_id },
+})
+
+if (!order?.items?.some((item) => item?.product_id === product_id)) {
+  throw new MedusaError(MedusaError.Types.NOT_ALLOWED, "Not in order")
 }
 ```
 
-The `reference` field selects the target: pass `"product"` with a product id, or
-`"seller"` with a seller id, in `reference_id`.
+Import `MedusaError` and `ContainerRegistrationKeys` from `@medusajs/framework/utils`. Put this block before the workflow call.
+
+## Handle a rejected submission
+
+The workflow throws a `MedusaError` with type `INVALID_DATA` in two cases, and Medusa returns them as `400` responses:
 
-<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>
+- **“Order not found!”**: the order doesn’t exist or belongs to another customer
+- **“Review already exists”**: this order already has a review with the same `reference` and target id
 
-## Statuses on creation
+When either check fails, nothing is written. If a later step fails, the workflow deletes the review it created.
 
-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.
+## Next steps
 
-<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>
+- [Moderate the new review](/platform/review/guides/moderate-a-review)
+- [Check createReviewWorkflow’s steps and input](/platform/review/reference/workflows)
+- [Learn how reference picks the target](/platform/review/concepts/product-vs-seller-reviews)

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

@@ -1,58 +1,104 @@
 ---
-title: "Moderate a review"
+title: "Publish, reject, and delete reviews in code"
 sidebarTitle: "Moderate a review"
-description: "Publish, reject, and delete reviews from server code."
+description: "Set a review's status with updateReviewWorkflow and remove it with deleteReviewWorkflow."
 ---
 
-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.
+Moderate reviews from your own code when the Admin API doesn’t fit, for example to auto-publish high ratings or to reject reviews flagged by a spam filter. Moderation is an `updateReviewWorkflow` run that sets `status`, and removal is a `deleteReviewWorkflow` run that soft deletes the review.
 
-## Publish or reject
+<Steps>
+  <Step title="Set the status">
+    Run `updateReviewWorkflow` with the review id and the new status:
 
-Move a `pending` review to `published` or `rejected` with `updateReviewWorkflow`,
-setting the `status` field:
+    ```ts title="src/api/admin/review-moderation/[id]/route.ts" {13-15}
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { updateReviewWorkflow } from "@mercurjs/core/workflows"
 
-```ts title="src/api/custom/moderate/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    type Body = { status: "published" | "rejected" }
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest<Body>,
+      res: MedusaResponse
+    ) {
+      const { result } = await updateReviewWorkflow(req.scope).run({
+        input: { id: req.params.id, status: req.body.status },
+      })
+
+      res.json({ review: result })
+    }
+    ```
+
+    Routes under `/admin` require an authenticated admin user by default. The workflow returns the updated review.
+  </Step>
+  <Step title="Delete a review">
+    Add a `DELETE` handler to the same file that runs `deleteReviewWorkflow` with the review id as its whole input:
+
+    ```ts title="src/api/admin/review-moderation/[id]/route.ts"
+    import { deleteReviewWorkflow } from "@mercurjs/core/workflows"
+
+    export async function DELETE(
+      req: AuthenticatedMedusaRequest,
+      res: MedusaResponse
+    ) {
+      await deleteReviewWorkflow(req.scope).run({ input: req.params.id })
+
+      res.json({ id: req.params.id, object: "review", deleted: true })
+    }
+    ```
+
+    The review gets a `deleted_at` timestamp. Its row and its four links stay in the database.
+  </Step>
+</Steps>
+
+## Publish reviews automatically
+
+Run the moderation from a subscriber to publish reviews without an operator. The module emits `review.review.created` with the new review’s id, so you can load the review and decide:
+
+```ts title="src/subscribers/auto-publish-reviews.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { MercurModules } from "@mercurjs/types"
 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",
-    },
-  })
+export default async function autoPublish({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const reviewService = container.resolve(MercurModules.REVIEW)
+  const review = await reviewService.retrieveReview(event.data.id)
 
-  res.sendStatus(200)
+  if (review.rating >= 4) {
+    await updateReviewWorkflow(container).run({
+      input: { id: review.id, status: "published" },
+    })
+  }
 }
+
+export const config: SubscriberConfig = { event: "review.review.created" }
 ```
 
-`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.
+This publishes every review rated 4 or 5 and leaves the rest `pending` for an operator. See the [Events reference](/platform/review/reference/events) for the payload.
 
-## Delete a review
+## Correct a review’s content
 
-Remove a review with `deleteReviewWorkflow`. This is a **soft delete**. The row
-is retained and restored automatically if the workflow is rolled back:
+`updateReviewWorkflow` also accepts `rating`, `customer_note`, and `seller_note`. Use it to fix a rating, redact a note, or clear a store’s answer:
 
 ```ts
-import { deleteReviewWorkflow } from "@mercurjs/core/workflows"
-
-await deleteReviewWorkflow(container).run({ input: "rev_123" })
+await updateReviewWorkflow(container).run({
+  input: { id: "rev_01JD8Q1234567", customer_note: null },
+})
 ```
 
-<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>
+The workflow saves the previous `rating`, `customer_note`, `seller_note`, and `status` before it writes, and restores them if a later step fails.
+
+## Account for soft deleted reviews in averages
+
+A soft deleted review disappears from `query.graph` and the APIs, but the service’s rating helpers still count it, because their query doesn’t check `deleted_at`. Compute averages with `query.graph` if deletions must change the number, as shown in [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings).
 
-## React to moderation
+## Next steps
 
-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.
+- [Let the store answer the review](/platform/review/guides/respond-to-a-review)
+- [Learn which status changes are allowed](/platform/review/concepts/ratings-and-moderation)
+- [Check updateReviewWorkflow’s input](/platform/review/reference/workflows)

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

@@ -1,61 +1,106 @@
 ---
-title: "Respond to a review"
+title: "Answer a review as a store"
 sidebarTitle: "Respond to a review"
-description: "Attach a store's public response with respondReviewWorkflow."
+description: "Attach a store's public answer to a review 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 `respondReviewWorkflow` to attach a store’s answer to a review, for example from a custom vendor route or a support tool. The workflow writes `seller_note` once and refuses to overwrite an existing answer.
 
-## Run the workflow
+## Before you begin
 
-`respondReviewWorkflow` writes the `seller_note` on an existing review:
+Check which reviews a store may answer before you build on this workflow:
 
-```ts title="src/api/custom/respond/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { respondReviewWorkflow } from "@mercurjs/core/workflows"
+- **Seller reviews only**: product reviews have no seller link, so the built-in Vendor API can’t reach them
+- **One answer per review**: a second call fails until `seller_note` is cleared
+- **No status change**: answering leaves `status` as it is
 
-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!",
-    },
-  })
+<Steps>
+  <Step title="Check that the review belongs to the store">
+    Look up the seller link before you write. The built-in Vendor route runs the same check:
 
-  res.sendStatus(200)
-}
-```
+    ```ts title="src/api/vendor/review-answers/[id]/helpers.ts"
+    import { MedusaContainer } from "@medusajs/framework"
+    import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
-<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>
+    export async function storeOwnsReview(
+      scope: MedusaContainer,
+      sellerId: string,
+      reviewId: string
+    ) {
+      const query = scope.resolve(ContainerRegistrationKeys.QUERY)
+      const { data } = await query.graph({
+        entity: "seller_seller_review_review",
+        fields: ["review_id"],
+        filters: { seller_id: sellerId, review_id: reviewId },
+      })
 
-## Clearing a response
+      return data.length > 0
+    }
+    ```
 
-The respond flow won't overwrite an existing note. To replace a response, first
-clear it with `updateReviewWorkflow`, then respond again:
+    `seller_seller_review_review` is the link table between sellers and reviews.
+  </Step>
+  <Step title="Run the workflow">
+    Call `respondReviewWorkflow` with the review id and the answer:
 
-```ts
-import {
-  updateReviewWorkflow,
-  respondReviewWorkflow,
-} from "@mercurjs/core/workflows"
+    ```ts title="src/api/vendor/review-answers/[id]/route.ts" {16-18}
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { MedusaError } from "@medusajs/framework/utils"
+    import { respondReviewWorkflow } from "@mercurjs/core/workflows"
+    import { storeOwnsReview } from "./helpers"
+
+    export async function POST(req: AuthenticatedMedusaRequest<{
+      seller_note: string
+    }>, res: MedusaResponse) {
+      const sellerId = req.seller_context!.seller_id
+      if (!(await storeOwnsReview(req.scope, sellerId, req.params.id))) {
+        throw new MedusaError(MedusaError.Types.NOT_FOUND, "Review not found")
+      }
+      const { result } = await respondReviewWorkflow(req.scope).run({
+        input: { id: req.params.id, seller_note: req.body.seller_note },
+      })
+
+      res.json({ review: result })
+    }
+    ```
+
+    Mercur fills `req.seller_context` on `/vendor` routes with the signed-in member’s current store.
+  </Step>
+</Steps>
+
+## Handle a second answer
+
+`respondReviewWorkflow` throws in two cases:
 
+- **`NOT_FOUND`, “Review not found”**: no review has this id
+- **`NOT_ALLOWED`, “This review already has a response”**: `seller_note` is already set
+
+The built-in routes return `400` for the second case. If a later step fails after the write, the workflow sets `seller_note` back to `null`.
+
+## Replace an existing answer
+
+The respond workflow never overwrites. To replace an answer, clear it with `updateReviewWorkflow`, then respond again:
+
+```ts
 await updateReviewWorkflow(container).run({
-  input: { id: "rev_123", seller_note: null },
+  input: { id: "rev_01JD8Q1234567", seller_note: null },
 })
 
 await respondReviewWorkflow(container).run({
-  input: { id: "rev_123", seller_note: "Updated response." },
+  input: {
+    id: "rev_01JD8Q1234567",
+    seller_note: "Sorry for the delay, a replacement is on its way.",
+  },
 })
 ```
 
-<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>
+Import both workflows from `@mercurjs/core/workflows`. The built-in APIs cap `seller_note` at 300 characters, while the workflow itself doesn’t.
+
+## Next steps
+
+- [Publish the review so the answer is shown](/platform/review/guides/moderate-a-review)
+- [Learn why stores see only seller reviews](/platform/review/concepts/product-vs-seller-reviews)
+- [Check respondReviewWorkflow’s input](/platform/review/reference/workflows)