@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/review/overview.mdx

@@ -1,87 +1,97 @@
 ---
-title: "Review"
+title: "Reviews"
 sidebarTitle: "Overview"
-description: "Collect, moderate, and surface customer ratings for products and sellers."
+description: "Let customers rate the products and stores they bought from, then moderate, answer, and average those ratings."
 ---
 
-Use Mercur to let customers rate the products they bought and the stores they
-bought from.
+Use Mercur to let customers rate the products they bought and the stores that sold them.
 
-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.
+A review is one customer’s rating of one target: a master product or a store. Each review is tied to the order that earned it, starts as `pending`, and waits for an operator to publish or reject it. The Review module ships inside `@mercurjs/core`, so it’s registered with the rest of the marketplace modules and needs no extra install. It connects to products, stores, orders, and customers through module links.
+
+<img className="block dark:hidden" src="/images/figures/review-overview-light.svg" alt="Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998." />
+<img className="hidden dark:block" src="/images/figures/review-overview-dark.svg" alt="Behind, createReviewWorkflow, which writes every review. In front, the review table: order #1001 backs a published seller review of ACME and a pending product review of the linen shirt, beside a rejected review from order #998." />
 
 <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.
+  The panels call the target a store. The code calls the same record a `Seller`, so a store review has `reference: "seller"`. Reviews use the id prefix `rev` and resolve with `MercurModules.REVIEW`.
 </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.
+The Review module covers a review from submission to the number on a storefront:
+
+- **One model, two targets**: a single `Review` record rates a product or a store, chosen by its `reference` field
+- **Order-backed**: the order must belong to the customer, and each order can review a given target once
+- **Moderation**: reviews start `pending`, and an operator sets them to `published` or `rejected`
+- **Store responses**: a store answers a review once through `seller_note`
+- **Rating helpers**: service methods compute average ratings per product or per store at query time
+- **Compensation**: every review workflow rolls its write back if a later step fails
+
+## How it works
+
+A review moves through four stages:
+
+1. A customer calls `POST /store/reviews` with an order they own, which runs `createReviewWorkflow`
+2. The workflow validates the order, creates the review as `pending`, and links it to its customer, order, and target
+3. An operator publishes or rejects it with `updateReviewWorkflow`, and the store answers it with `respondReviewWorkflow`
+4. Your own storefront route reads published reviews and averages them with the service’s rating helpers
+
+<Warning>
+  Core ships no public endpoint that lists a product’s or a store’s published reviews, and no route returns an average rating. `GET /store/reviews` returns only the signed-in customer’s own reviews. Add a route for storefront display, as shown in [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings).
+</Warning>
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how reviews, their targets, and their statuses fit 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.
+    The fields of a review: rating, notes, status, and display id.
   </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.
+    How `reference` picks the target and which links 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.
+    Status changes, store responses, and how averages are computed.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against the Review domain in your own code.
+Build against reviews in your own server 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.
+    Run `createReviewWorkflow` from a custom route.
   </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`.
+    Attach a store’s answer with `respondReviewWorkflow`.
   </Card>
   <Card title="Aggregate ratings" icon="calculator" href="/platform/review/guides/compute-aggregate-ratings">
-    Compute average ratings for products and sellers.
+    Serve average ratings for products and stores.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, links, workflows, service methods, and events for the Review domain.
+The data model, links, workflows, service methods, and events behind reviews.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/review/reference/data-models">
-    The `Review` entity and its fields.
+    The `Review` model, its fields, and its indexes.
   </Card>
   <Card title="Links" icon="link" href="/platform/review/reference/links">
-    How reviews link to products, sellers, orders, and customers.
+    The four links to products, sellers, orders, and customers.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/review/reference/workflows">
-    Create, update, respond, and delete workflows.
+    Create, update, respond, and delete workflows with their steps.
   </Card>
   <Card title="Service" icon="gear" href="/platform/review/reference/service">
-    Module service methods, including aggregate-rating helpers.
+    Generated methods and the rating helpers.
   </Card>
   <Card title="Events" icon="bell" href="/platform/review/reference/events">
-    Running side effects as reviews change.
+    The mutation events the module emits.
   </Card>
 </CardGroup>

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

@@ -1,36 +1,50 @@
 ---
-title: "Data models"
+title: "Review data model"
 sidebarTitle: "Data models"
-description: "The data models owned by the Review domain."
+description: "Every field and index of the Review model in the Review module."
 ---
 
-The Review domain is owned by the **Review module**. This reference lists its
-data model and fields.
+The Review module owns one data model, `Review`. It’s defined in `packages/core/src/modules/review/models/review.ts` and stored in the `review` table. Resolve the module with `MercurModules.REVIEW`.
 
 ## Review
 
-Table `review`, id prefix `rev`. A customer's rating of a single product or
-seller.
+A customer’s rating of one product or one seller. Table `review`, id prefix `rev`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `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>
+| `id` | `text` | Primary key with the prefix `rev`, such as `rev_01JD8Q1234567` |
+| `display_id` | `autoincrement` | Serial number for display, stored as a Postgres `serial` |
+| `reference` | `enum` | The target type: `product` or `seller`. Required |
+| `rating` | `number` | The score, stored as an `integer`. Required, no range constraint in the model |
+| `customer_note` | `text` | The customer’s text. Nullable, searchable |
+| `seller_note` | `text` | The store’s answer. Nullable, searchable |
+| `status` | `enum` | `pending`, `published`, or `rejected`. Default `pending` |
+| `created_at` | `timestamptz` | Set on creation |
+| `updated_at` | `timestamptz` | Set on every change |
+| `deleted_at` | `timestamptz` | Nullable. Set by a soft delete |
+
+The model has no column for its target, order, or customer. Those live in [module links](/platform/review/reference/links), and `reference` tells you whether to follow `product` or `seller`.
+
+### Indexes
+
+Two indexes speed up the lists the APIs run:
+
+| Index | Columns | Condition |
+| --- | --- | --- |
+| `IDX_review_deleted_at` | `deleted_at` | `deleted_at IS NULL` |
+| `IDX_review_reference_status_created_at` | `reference`, `status`, `created_at` | `deleted_at IS NULL` |
+
+### Relations
+
+The model defines no relations of its own. Through links, a review exposes these `query.graph` fields:
+
+| Field | Target | Set when |
+| --- | --- | --- |
+| `product` | Product | `reference` is `product` |
+| `seller` | Seller | `reference` is `seller` |
+| `order` | Order | Always |
+| `customer` | Customer | Always |
+
+### Types
+
+`@mercurjs/types` exports `ReviewDTO`, `ReviewReference` (`"product" | "seller"`), and `ReviewStatus` (`"pending" | "published" | "rejected"`) for this model.

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

@@ -1,61 +1,79 @@
 ---
-title: "Event reference"
+title: "Review events"
 sidebarTitle: "Events"
-description: "Running side effects as reviews are created, moderated, and answered."
+description: "The mutation events the Review module service emits, and how to subscribe to them."
 ---
 
-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.
+Mercur defines no review events of its own, and the review workflows don’t call `emitEventStep`. The Review module service emits Medusa’s standard mutation events instead, because every method `MedusaService` generates publishes an event when it changes a `Review` row. Subscribe to these to notify a store, refresh a search index, or recompute a cached rating.
 
-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.
+## Event list
 
-## Emit your own event
+Event names follow Medusa’s `<module>.<model>.<action>` pattern, with the module and the model both named `review`:
 
-Emit an event alongside the workflow, then handle it in a subscriber:
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `review.review.created` | `createReviewWorkflow` or `createReviews` creates a review | `{ id }` |
+| `review.review.updated` | `updateReviewWorkflow`, `respondReviewWorkflow`, or `updateReviews` changes a review | `{ id }` |
+| `review.review.deleted` | `deleteReviewWorkflow` or `softDeleteReviews` soft deletes a review, or `deleteReviews` removes one | `{ id }` |
+| `review.review.restored` | `restoreReviews` restores a soft deleted review, including a delete rollback | `{ id }` |
 
-```ts title="src/api/custom/route.ts"
-import { Modules } from "@medusajs/framework/utils"
-import { createReviewWorkflow } from "@mercurjs/core/workflows"
+The payload holds only the review id. Load the review in the subscriber when you need its fields or links.
 
-export async function POST(req, res) {
-  const { result } = await createReviewWorkflow(req.scope).run({
-    input: req.body,
-  })
+<Note>
+  `review.review.updated` doesn’t say which field changed. A moderation, a customer edit, and a store answer all emit the same event, so compare against your own state when you need to tell them apart.
+</Note>
 
-  const eventBus = req.scope.resolve(Modules.EVENT_BUS)
-  await eventBus.emit({ name: "review.created", data: { id: result.id } })
+## Subscribe to an event
 
-  res.status(201).json({ review: result })
-}
-```
+Create a subscriber that loads the review and its links:
 
 ```ts title="src/subscribers/review-created.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
-export default async function reviewCreatedHandler({
+export default async function reviewCreated({
   event,
   container,
 }: SubscriberArgs<{ id: string }>) {
-  const reviewId = event.data.id
-  // ...notify the store, update a search index, etc.
-}
+  const query = container.resolve(ContainerRegistrationKeys.QUERY)
+  const { data: [review] } = await query.graph({
+    entity: "review",
+    fields: ["rating", "reference", "seller.email", "product.title"],
+    filters: { id: event.data.id },
+  })
 
-export const config: SubscriberConfig = {
-  event: "review.created",
+  const logger = container.resolve(ContainerRegistrationKeys.LOGGER)
+  logger.info(`Review ${event.data.id} rated ${review.rating}`)
 }
+
+export const config: SubscriberConfig = { event: "review.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>
+This logs each new review. Replace the log with your side effect, such as a notification to `review.seller.email` for a store review.
+
+## Emit a named event
+
+To give a moderation step its own event, wrap `updateReviewWorkflow` in your own workflow and add Medusa’s `emitEventStep`:
 
-## React without an event
+```ts title="src/workflows/publish-review.ts"
+import {
+  createWorkflow,
+  WorkflowResponse,
+} from "@medusajs/framework/workflows-sdk"
+import { emitEventStep } from "@medusajs/medusa/core-flows"
+import { updateReviewWorkflow } from "@mercurjs/core/workflows"
+
+export const publishReviewWorkflow = createWorkflow(
+  "publish-review",
+  (input: { id: string }) => {
+    const review = updateReviewWorkflow.runAsStep({
+      input: { id: input.id, status: "published" },
+    })
+    emitEventStep({ eventName: "review.published", data: { id: input.id } })
+
+    return new WorkflowResponse(review)
+  }
+)
+```
 
-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.
+`review.published` is a name you define, so subscribe to the same string.

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

@@ -1,43 +1,101 @@
 ---
-title: "Links to other modules"
+title: "Review links"
 sidebarTitle: "Links"
-description: "How the Review domain links to products, sellers, orders, and customers."
+description: "The four module links that connect reviews 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.
+A review stores no foreign keys. Four module links in `packages/core/src/links/` connect it to the records around it, and `query.graph` follows them by alias. Every link is a list link on the other module’s side: one product, seller, order, or customer has many reviews, and each review has one of each it’s linked to.
 
 ```ts
 const { data: reviews } = await query.graph({
   entity: "review",
-  fields: ["id", "rating", "product.*", "seller.*"],
+  fields: ["id", "rating", "product.title", "seller.name", "order.id"],
+  filters: { status: "published" },
 })
 ```
 
-## Targets
+This loads published reviews with their target and order. Only one of `product` and `seller` is set on each review.
 
-| Linked module | Relationship |
+## Product and review
+
+Connects a master product to its product reviews. Written by `createReviewWorkflow` through the `create-remote-links` step when `reference` is `product`.
+
+| Property | Value |
 | --- | --- |
-| **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`. |
+| File | `product-review.ts` |
+| Sides | `Modules.PRODUCT` `product` and `MercurModules.REVIEW` `review` |
+| Cardinality | One product, many reviews |
+| Link table | `product_product_review_review` |
+| Aliases | `review.product`, `product.reviews` |
 
-A review is linked to **either** a product or a seller, never both. The
-`reference` field on the review decides which link is created.
+```ts
+const { data: [product] } = await query.graph({
+  entity: "product",
+  fields: ["title", "reviews.rating", "reviews.status"],
+  filters: { id: "prod_01JD8Q1234567" },
+})
+```
+
+## Seller and review
 
-## Provenance
+Connects a seller to its store reviews. Written by `createReviewWorkflow` through the `create-remote-links` step when `reference` is `seller`. The Vendor API scopes reviews to a store through this link.
 
-| Linked module | Relationship |
+| Property | Value |
 | --- | --- |
-| **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`). |
+| File | `seller-review.ts` |
+| Sides | `MercurModules.SELLER` `seller` and `MercurModules.REVIEW` `review` |
+| Cardinality | One seller, many reviews |
+| Link table | `seller_seller_review_review` |
+| Aliases | `review.seller`, `seller.reviews` |
 
-These two links are written for every review and back the validation that a
-customer can review a target only once per order.
+```ts
+const { data: [seller] } = await query.graph({
+  entity: "seller",
+  fields: ["name", "reviews.rating", "reviews.seller_note"],
+  filters: { id: "sel_01JD8Q1234567" },
+})
+```
+
+## Order and review
+
+Connects a review to the order that earned it. Written for every review by the `create-review` step. `createReviewWorkflow` reads it to reject a second review of the same target from one order.
+
+| Property | Value |
+| --- | --- |
+| File | `order-review.ts` |
+| Sides | `Modules.ORDER` `order` and `MercurModules.REVIEW` `review` |
+| Cardinality | One order, many reviews |
+| Link table | `order_order_review_review` |
+| Aliases | `review.order`, `order.reviews` |
+
+```ts
+const { data: [order] } = await query.graph({
+  entity: "order",
+  fields: ["display_id", "reviews.reference", "reviews.rating"],
+  filters: { id: "order_01JD8Q1234567" },
+})
+```
+
+## Customer and review
+
+Connects a review to the customer who wrote it. Written for every review by the `create-review` step. The Store API limits a customer to their own reviews through this link.
+
+| Property | Value |
+| --- | --- |
+| File | `customer-review.ts` |
+| Sides | `Modules.CUSTOMER` `customer` and `MercurModules.REVIEW` `review` |
+| Cardinality | One customer, many reviews |
+| Link table | `customer_customer_review_review` |
+| Aliases | `review.customer`, `customer.reviews` |
+
+```ts
+const { data: [customer] } = await query.graph({
+  entity: "customer",
+  fields: ["email", "reviews.id", "reviews.status"],
+  filters: { id: "cus_01JD8Q1234567" },
+})
+```
 
 <Note>
-  All four links are list links (`isList: true`) on the owning side. A product,
-  seller, order, or customer has many reviews.
+  `deleteReviewWorkflow` soft deletes the review but keeps all of its link rows. The service’s rating helpers join through the product and seller link tables, so they still count a soft deleted review.
 </Note>

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

@@ -1,54 +1,82 @@
 ---
-title: "Service reference"
+title: "Review module service"
 sidebarTitle: "Service"
-description: "The Review module service: CRUD methods and aggregate-rating helpers."
+description: "Resolve the Review module service, its generated CRUD methods, and its three 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.
+The Review module service, `ReviewModuleService`, reads and writes `Review` records directly and computes average ratings. Use it in subscribers, scheduled jobs, and routes when you don’t need a workflow’s validation, links, or compensation.
+
+## Resolve the service
+
+Resolve the service from the Medusa container with `MercurModules.REVIEW`, which is the string `"review"`:
 
 ```ts
 import { MercurModules } from "@mercurjs/types"
 
-const reviewModuleService = container.resolve(MercurModules.REVIEW)
+const reviewService = container.resolve(MercurModules.REVIEW)
 
-const [reviews, count] = await reviewModuleService.listAndCountReviews({
-  status: "published",
-})
+const [reviews, count] = await reviewService.listAndCountReviews(
+  { status: "published" },
+  { order: { created_at: "DESC" }, take: 20 }
+)
 ```
 
+This lists the 20 newest published reviews and the total count. Filters apply to the review’s own fields, so you can’t filter by product or seller here: use `query.graph` from the linked side, as shown in the [Links reference](/platform/review/reference/links).
+
+<Warning>
+  Writing through the service skips the workflow checks. `createReviews` doesn’t validate the order, reject duplicates, or write any link, and `updateReviews` doesn’t stop a second store answer.
+</Warning>
+
 ## Generated methods
 
-The `Review` model gets a standard set of auto-generated methods:
+`MedusaService` generates these methods for the `Review` model:
 
 | 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 |
+| `retrieveReview(id, config?)` | Retrieve one review. Throws when it doesn’t exist |
+| `listReviews(filters?, config?)` | List reviews |
+| `listAndCountReviews(filters?, config?)` | List reviews and the total count |
+| `createReviews(data)` | Create one review or an array of reviews |
+| `updateReviews(data)` | Update by `id`, or by `{ selector, data }` |
+| `deleteReviews(ids)` | Delete reviews permanently |
+| `softDeleteReviews(ids)` | Set `deleted_at` on reviews |
+| `restoreReviews(ids)` | Clear `deleted_at` on reviews |
 
-## Aggregate-rating methods
+Each write emits a mutation event, listed in the [Events reference](/platform/review/reference/events).
 
-The service adds three helpers that compute average ratings on demand:
+## getAvgRating
 
-| 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 |
+Returns the average rating of one product or one seller.
+
+```ts
+getAvgRating(
+  type: "seller" | "product",
+  id: string
+): Promise<string | null>
+```
 
-See [Compute aggregate ratings](/platform/review/guides/compute-aggregate-ratings)
-for usage.
+The result is the Postgres `AVG` of `rating` as a numeric string, such as `"4.5000000000000000"`, or `null` when the target has no linked reviews. It counts every linked review whatever its `status`, including soft deleted ones.
 
-<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>
+## getProductsWithRating
+
+Returns every product with its average rating.
+
+```ts
+getProductsWithRating(fields: string[]): Promise<Record<string, unknown>[]>
+```
+
+`fields` are column names of the `product` table, such as `["id", "title"]`. Each row gains a `rating` numeric string, or `null`. The query left joins the `product_product_review_review` link table and groups by product, with no filters, pagination, or `deleted_at` checks.
+
+## getSellersWithRating
+
+Returns every seller with its average rating.
+
+```ts
+getSellersWithRating(fields: string[]): Promise<Record<string, unknown>[]>
+```
+
+`fields` are column names of the `seller` table, such as `["id", "name"]`. It works like `getProductsWithRating`, joining through `seller_seller_review_review`.
+
+<Note>
+  The return types above describe the rows. The source declares no explicit return type for the two list helpers, so TypeScript infers Knex’s result type.
+</Note>