@devx-commerce/plugin-product-reviews/README.md

Product Reviews Plugin for Medusa

<p align="center">
  <a href="https://www.medusajs.com">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
    </picture>
  </a>
</p>
<h1 align="center">
  Medusa Plugin - Product Reviews
</h1>

<h4 align="center">
  <a href="https://docs.medusajs.com">Documentation</a> |
  <a href="https://www.medusajs.com">Website</a>
</h4>

<p align="center">
A Medusa plugin that adds product review functionality to your Medusa store. This plugin allows customers to leave reviews for products, helping other customers make informed purchasing decisions.
</p>
<p align="center">
  <a href="https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md">
    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
  </a>
    <a href="https://www.producthunt.com/posts/medusa"><img src="https://img.shields.io/badge/Product%20Hunt-%231%20Product%20of%20the%20Day-%23DA552E" alt="Product Hunt"></a>
  <a href="https://discord.gg/xpCwq3Kfn8">
    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
  </a>
  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
  </a>
</p>

## Features

- Product review management
- Review submission and moderation
- Integration with Medusa admin dashboard
- Customizable review settings
- Review workflow management
- Review response system
- Review statistics and analytics
- Image attachments for reviews
- Rating system (1-5 stars)
- Review status management (pending, approved, flagged)

## Technical Overview

### Data Models

The plugin implements three main data models:

1. **Product Review**

   - Basic review information (name, email, rating, content)
   - Product and order associations
   - Image attachments
   - Review status (pending/approved/flagged)
   - Order line item reference

2. **Product Review Response**

   - Store owner responses to reviews
   - Response content and metadata

3. **Product Review Stats**
   - Aggregated statistics for products
   - Review counts
   - Average ratings
   - Rating distribution (1-5 stars)

### Core Functionality

- **Review Management**

  - Create, update, and delete reviews
  - Moderate review status
  - Attach images to reviews
  - Respond to customer reviews

- **Statistics and Analytics**

  - Automatic calculation of product review statistics
  - Rating distribution tracking
  - Average rating computation
  - Review count tracking

- **Configuration Options**
  - Default review status (pending/approved/flagged)
  - Customizable review workflow
  - Integration with Medusa's admin interface

### Database Features

- Optimized indexes for product and order lookups
- Efficient statistics calculation using SQL aggregation
- Support for review search functionality
- Relationship management between reviews and products

## Prerequisites

- Node.js >= 20
- Medusa v2.4.0 or higher
- PostgreSQL database

## Installation

1. Install the plugin:

```bash
npm install @devx-commerce/product-reviews
# or
yarn add @devx-commerce/product-reviews
```

2. Add the plugin to your `medusa-config.js`:

```javascript
const plugins = [
  // ... other plugins
  {
    resolve: "@devx-commerce/product-reviews",
    options: {
      defaultReviewStatus: "approved", // or "pending" or "flagged"
    },
  },
];
```

## API Endpoints

### Admin API

#### Product Reviews

- `GET /admin/product-reviews` - List all product reviews
  - Query parameters:
    - `fields`: Fields to include in response
    - `filters`: Filter criteria
    - `limit`: Number of items per page
    - `offset`: Page offset

#### Product Review Stats

- `GET /admin/product-review-stats` - List all product review statistics
  - Query parameters:
    - `fields`: Fields to include in response
    - `filters`: Filter criteria
    - `limit`: Number of items per page
    - `offset`: Page offset

### Store API

#### Product Reviews

- `GET /store/product-reviews` - List all product reviews
  - Query parameters:
    - `fields`: Fields to include in response
    - `filters`: Filter criteria
    - `limit`: Number of items per page
    - `offset`: Page offset
- `POST /store/product-reviews` - Create or update product reviews
  - Request body:
    ```typescript
    {
      reviews: Array<{
        id?: string;
        name?: string;
        email?: string;
        rating: number;
        content?: string;
        order_line_item_id?: string;
        product_id?: string;
        order_id?: string;
        images?: string[];
      }>;
    }
    ```

#### Product Review Stats

- `GET /store/product-review-stats` - List all product review statistics
  - Query parameters:
    - `fields`: Fields to include in response
    - `filters`: Filter criteria
    - `limit`: Number of items per page
    - `offset`: Page offset

### Response Format

All list endpoints return data in the following format:

```typescript
{
  data: T[], // Array of items
  count: number, // Total count of items
  offset: number, // Current page offset
  limit: number // Items per page
}
```

## License

MIT