@86d-app/reviews 0.0.4 → 0.0.6

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc

package/AGENTS.md

@@ -1,41 +1,77 @@
 # reviews module
 
-Handles product reviews and ratings. Reviews start as `pending` and require admin approval before being publicly visible.
+Product reviews, ratings, reporting, and helpfulness voting. Reviews start as `pending` and require admin approval before being publicly visible (unless `autoApprove` is set).
+
+## Structure
+
+```
+src/
+  index.ts              Module factory, options, type re-exports
+  schema.ts             review, reviewVote, reviewReport tables
+  service.ts            ReviewController interface + types
+  service-impl.ts       Controller implementation
+  store/endpoints/      5 public endpoints
+  store/components/     Customer-facing review UI (TSX + MDX)
+  admin/endpoints/      12 admin endpoints
+  admin/components/     Admin review management UI
+  __tests__/            4 test files (246 tests)
+```
 
 ## Schema
 
-- `review` — stores a single product review with rating (1–5), author info, body, moderation status, and helpfulness count.
+- `review` — rating (1–5), author info, body, images, moderation status, helpfulness count, merchant response
+- `reviewVote` — tracks who voted helpful (reviewId + voterId) for deduplication
+- `reviewReport` — abuse/spam reports (reviewId, reason, status: pending/resolved/dismissed)
 
-## Service
+## Options
 
-`ReviewController` exposes:
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `autoApprove` | `"true" \| "false"` | `"false"` | Skip moderation queue |
 
-- `createReview` — submit a new review (always `pending`)
-- `getReview` — fetch a review by id
-- `listReviewsByProduct` — get reviews for a product (optionally only approved)
-- `listReviews` — admin listing with filters (status, productId, pagination)
-- `updateReviewStatus` — approve or reject a review
-- `deleteReview` — hard delete
-- `getProductRatingSummary` — average rating + distribution (approved reviews only)
+## Key patterns
+
+- **Duplicate prevention**: `hasReviewedProduct(customerId, productId)` — one review per customer per product (enforced in submit endpoint for authenticated users)
+- **Vote deduplication**: `voteHelpful(reviewId, voterId)` — authenticated users can only vote once per review; anonymous users get simple `markHelpful` increment
+- **Sorting**: `listReviewsByProduct` supports `sortBy`: recent, oldest, highest, lowest, helpful
+- **Photo reviews**: `images` field accepts up to 5 `{url, caption?}` objects
+- **Reporting**: customers can report reviews as spam/offensive/fake/irrelevant/harassment/other
+- **Analytics**: `getReviewAnalytics()` includes `reportedCount` (unique reviews with pending reports)
 
 ## Endpoints
 
 ### Store
-- `POST /reviews` — submit a review
-- `GET /reviews/products/:productId` — list approved reviews + summary
+- `POST /reviews` — submit review (duplicate check, images, sanitized input)
+- `GET /reviews/me` — list authenticated user's reviews (paginated)
+- `GET /reviews/products/:productId` — approved reviews + summary (sortBy: recent/oldest/highest/lowest/helpful)
+- `POST /reviews/:id/helpful` — vote helpful (deduplicated for auth users)
+- `POST /reviews/:id/report` — report review (reason + optional details)
 
 ### Admin
 - `GET /admin/reviews` — list all reviews (status/productId filters)
+- `GET /admin/reviews/analytics` — review analytics (includes reportedCount)
+- `GET /admin/reviews/reports` — list reports (status/reviewId filters)
+- `PUT /admin/reviews/reports/:id/update` — resolve/dismiss a report
+- `GET /admin/reviews/requests` — list review request emails
+- `GET /admin/reviews/request-stats` — review request stats
+- `POST /admin/reviews/send-request` — send review request email
+- `GET /admin/reviews/:id` — get single review
 - `PUT /admin/reviews/:id/approve` — approve
 - `PUT /admin/reviews/:id/reject` — reject
+- `POST /admin/reviews/:id/respond` — add merchant response
 - `DELETE /admin/reviews/:id/delete` — delete
 
-## Options
+## Security
 
-| Key | Type | Description |
-|-----|------|-------------|
-| `autoApprove` | `"true" \| "false"` | Skip moderation queue |
+- `customerId` derived from session — never accepted from client
+- `isVerifiedPurchase` always `false` from store endpoint — only admin/system can set
+- Report `reason` is enum-validated (spam, offensive, fake, irrelevant, harassment, other)
+- Image URLs validated as URLs; captions sanitized
+- All text inputs sanitized via `sanitizeText`
 
 ## Tests
 
-28 tests in `tests/service-impl.test.ts` covering all controller methods.
+- `service-impl.test.ts` — 109 controller unit tests
+- `controllers.test.ts` — 52 edge case tests
+- `endpoint-security.test.ts` — 45 security regression tests
+- `new-features.test.ts` — 40 tests covering photos, duplicate prevention, vote dedup, sorting, reporting, analytics

package/README.md

@@ -17,11 +17,11 @@
 > [!WARNING]
 > This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.
 
-# @86d-app/reviews
+# Reviews Module
 
-Product reviews and ratings for the 86d commerce platform. Manages a moderation queue so store owners can approve or reject reviews before they appear publicly.
+Product reviews and ratings for the 86d commerce platform. Supports moderation queue, photo reviews, helpfulness voting with deduplication, review sorting, abuse reporting, and merchant responses.
 
-![version](https://img.shields.io/badge/version-0.0.1-blue) ![license](https://img.shields.io/badge/license-MIT-green)
+![version](https://img.shields.io/badge/version-0.0.2-blue) ![license](https://img.shields.io/badge/license-MIT-green)
 
 ## Installation
 
@@ -62,10 +62,37 @@ When `autoApprove: "true"`, new reviews skip the pending state and go directly t
 
 | Method | Path | Description |
 |---|---|---|
-| `POST` | `/reviews` | Submit a review (status: pending) |
-| `GET` | `/reviews/products/:productId` | List approved reviews + rating summary |
+| `POST` | `/reviews` | Submit a review (with optional images, duplicate prevention) |
+| `GET` | `/reviews/me` | List authenticated user's reviews (paginated) |
+| `GET` | `/reviews/products/:productId` | List approved reviews + rating summary (sortable) |
+| `POST` | `/reviews/:id/helpful` | Vote review as helpful (deduplicated for auth users) |
+| `POST` | `/reviews/:id/report` | Report a review for abuse/spam |
+
+### Submit Review (`POST /reviews`)
+
+```json
+{
+  "productId": "prod_abc",
+  "authorName": "Jane Doe",
+  "authorEmail": "jane@example.com",
+  "rating": 5,
+  "title": "Excellent product!",
+  "body": "Exactly what I needed.",
+  "images": [
+    { "url": "https://example.com/photo.jpg", "caption": "Front view" }
+  ]
+}
+```
+
+Returns `409` if the authenticated customer has already reviewed this product.
+
+### List Product Reviews (`GET /reviews/products/:productId`)
+
+Query parameters:
+- `take` (1–100, default 20) — page size
+- `skip` (default 0) — offset
+- `sortBy` — `recent` | `oldest` | `highest` | `lowest` | `helpful` (default: `recent`)
 
-**Response for `GET /reviews/products/:productId`:**
 ```json
 {
   "reviews": [...],
@@ -77,13 +104,32 @@ When `autoApprove: "true"`, new reviews skip the pending state and go directly t
 }
 ```
 
+### Report Review (`POST /reviews/:id/report`)
+
+```json
+{
+  "reason": "spam",
+  "details": "This review is advertising another product"
+}
+```
+
+Reason must be one of: `spam`, `offensive`, `fake`, `irrelevant`, `harassment`, `other`.
+
 ## Admin Endpoints
 
 | Method | Path | Description |
 |---|---|---|
 | `GET` | `/admin/reviews` | List all reviews (filter: `status`, `productId`) |
+| `GET` | `/admin/reviews/analytics` | Review analytics (includes report counts) |
+| `GET` | `/admin/reviews/reports` | List abuse reports (filter: `status`, `reviewId`) |
+| `PUT` | `/admin/reviews/reports/:id/update` | Resolve or dismiss a report |
+| `GET` | `/admin/reviews/requests` | List review request emails |
+| `GET` | `/admin/reviews/request-stats` | Review request statistics |
+| `POST` | `/admin/reviews/send-request` | Send a review request email |
+| `GET` | `/admin/reviews/:id` | Get a single review |
 | `PUT` | `/admin/reviews/:id/approve` | Approve a review |
 | `PUT` | `/admin/reviews/:id/reject` | Reject a review |
+| `POST` | `/admin/reviews/:id/respond` | Add merchant response |
 | `DELETE` | `/admin/reviews/:id/delete` | Delete a review permanently |
 
 ## Controller API
@@ -98,15 +144,16 @@ controller.createReview(params: {
   body: string;
   customerId?: string;
   isVerifiedPurchase?: boolean;
+  images?: Array<{ url: string; caption?: string }>;
 }): Promise<Review>
 
 controller.getReview(id: string): Promise<Review | null>
 
-// Returns only approved reviews by default (set approvedOnly: false for all)
 controller.listReviewsByProduct(productId: string, params?: {
   approvedOnly?: boolean;
   take?: number;
   skip?: number;
+  sortBy?: "recent" | "oldest" | "highest" | "lowest" | "helpful";
 }): Promise<Review[]>
 
 controller.listReviews(params?: {
@@ -120,52 +167,47 @@ controller.updateReviewStatus(id: string, status: ReviewStatus): Promise<Review
 
 controller.deleteReview(id: string): Promise<boolean>
 
-// Calculates stats from approved reviews only
 controller.getProductRatingSummary(productId: string): Promise<RatingSummary>
-```
 
-## Rating Summary
+controller.hasReviewedProduct(customerId: string, productId: string): Promise<boolean>
 
-`getProductRatingSummary` only counts **approved** reviews. The `count` is the number of approved reviews, `average` is rounded to 1 decimal place, and `distribution` maps each star rating (1–5) to its count.
+controller.voteHelpful(reviewId: string, voterId: string): Promise<{
+  review: Review;
+  alreadyVoted: boolean;
+} | null>
 
-```ts
-interface RatingSummary {
-  average: number;                   // e.g. 4.3
-  count: number;                     // number of approved reviews
-  distribution: Record<string, number>; // { "1": 0, "2": 1, "3": 2, "4": 4, "5": 5 }
-}
-```
+controller.markHelpful(id: string): Promise<Review | null>
 
-## Example: Moderation Flow
+controller.reportReview(params: {
+  reviewId: string;
+  reporterId?: string;
+  reason: string;
+  details?: string;
+}): Promise<ReviewReport>
 
-```ts
-// Customer submits a review
-const review = await controller.createReview({
-  productId: "prod_abc",
-  authorName: "Jane Doe",
-  authorEmail: "jane@example.com",
-  rating: 5,
-  title: "Excellent product!",
-  body: "Exactly what I needed. Fast shipping too.",
-  isVerifiedPurchase: true,
-});
-// review.status === "pending"
-
-// Admin approves it
-await controller.updateReviewStatus(review.id, "approved");
-
-// Fetch public ratings for a product page
-const summary = await controller.getProductRatingSummary("prod_abc");
-// { average: 5.0, count: 1, distribution: { "5": 1, "4": 0, ... } }
-
-// Fetch approved reviews for display
-const reviews = await controller.listReviewsByProduct("prod_abc");
+controller.listReports(params?: {
+  status?: ReportStatus;
+  reviewId?: string;
+  take?: number;
+  skip?: number;
+}): Promise<ReviewReport[]>
+
+controller.updateReportStatus(id: string, status: ReportStatus): Promise<ReviewReport | null>
+
+controller.getReportCount(reviewId: string): Promise<number>
 ```
 
 ## Types
 
 ```ts
 type ReviewStatus = "pending" | "approved" | "rejected";
+type ReportStatus = "pending" | "resolved" | "dismissed";
+type ReviewSortBy = "recent" | "oldest" | "highest" | "lowest" | "helpful";
+
+interface ReviewImage {
+  url: string;
+  caption?: string;
+}
 
 interface Review {
   id: string;
@@ -179,13 +221,80 @@ interface Review {
   status: ReviewStatus;
   isVerifiedPurchase: boolean;
   helpfulCount: number;
+  images?: ReviewImage[];
+  merchantResponse?: string;
+  merchantResponseAt?: Date;
+  moderationNote?: string;
   createdAt: Date;
   updatedAt: Date;
 }
 
+interface ReviewVote {
+  id: string;
+  reviewId: string;
+  voterId: string;
+  createdAt: Date;
+}
+
+interface ReviewReport {
+  id: string;
+  reviewId: string;
+  reporterId?: string;
+  reason: string;
+  details?: string;
+  status: ReportStatus;
+  createdAt: Date;
+}
+
 interface RatingSummary {
   average: number;
   count: number;
   distribution: Record<string, number>;
 }
+
+interface ReviewAnalytics {
+  totalReviews: number;
+  pendingCount: number;
+  approvedCount: number;
+  rejectedCount: number;
+  averageRating: number;
+  ratingsDistribution: Record<string, number>;
+  withMerchantResponse: number;
+  reportedCount: number;
+}
 ```
+
+## Store Components
+
+### ReviewsSummary
+
+Compact star rating and count for product cards.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `productId` | `string` | Product ID to fetch review summary for |
+
+```mdx
+<ReviewsSummary productId={product.id} />
+```
+
+### ProductReviews
+
+Full reviews section with summary, distribution bars, review list, and submit form.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `productId` | `string` | — | Product ID |
+| `title` | `string` | `"Customer Reviews"` | Section heading |
+
+```mdx
+<ProductReviews productId={product.id} />
+```
+
+## Notes
+
+- Only approved reviews appear in product listings and rating summaries
+- Authenticated customers can only submit one review per product
+- Helpfulness votes are deduplicated for authenticated users (anonymous votes are not tracked)
+- Report reasons are enum-validated; details are sanitized
+- Images are validated as URLs with a max of 5 per review

package/dist/__tests__/controllers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=controllers.test.d.ts.map

package/dist/__tests__/controllers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controllers.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/controllers.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/endpoint-security.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=endpoint-security.test.d.ts.map

package/dist/__tests__/endpoint-security.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-security.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/endpoint-security.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/new-features.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=new-features.test.d.ts.map

package/dist/__tests__/new-features.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-features.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/new-features.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/service-impl.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-impl.test.d.ts.map

package/dist/__tests__/service-impl.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-impl.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/service-impl.test.ts"],"names":[],"mappings":""}

package/dist/admin/components/index.d.ts

@@ -0,0 +1,4 @@
+export { ReviewAnalytics } from "./review-analytics";
+export { ReviewList } from "./review-list";
+export { ReviewModeration } from "./review-moderation";
+//# sourceMappingURL=index.d.ts.map

package/dist/admin/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/admin/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/admin/components/review-analytics.d.ts

@@ -0,0 +1,2 @@
+export declare function ReviewAnalytics(): import("react").JSX.Element;
+//# sourceMappingURL=review-analytics.d.ts.map

package/dist/admin/components/review-analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-analytics.d.ts","sourceRoot":"","sources":["../../../src/admin/components/review-analytics.tsx"],"names":[],"mappings":"AA8FA,wBAAgB,eAAe,gCA8H9B"}

package/dist/admin/components/review-list.d.ts

@@ -0,0 +1,2 @@
+export declare function ReviewList(): import("react").JSX.Element;
+//# sourceMappingURL=review-list.d.ts.map

package/dist/admin/components/review-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-list.d.ts","sourceRoot":"","sources":["../../../src/admin/components/review-list.tsx"],"names":[],"mappings":"AAqGA,wBAAgB,UAAU,gCA8MzB"}

package/dist/admin/components/review-moderation.d.ts

@@ -0,0 +1,6 @@
+export declare function ReviewModeration(props: {
+    reviewId?: string;
+    params?: Record<string, string>;
+    onAction?: () => void;
+}): import("react").JSX.Element;
+//# sourceMappingURL=review-moderation.d.ts.map

package/dist/admin/components/review-moderation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-moderation.d.ts","sourceRoot":"","sources":["../../../src/admin/components/review-moderation.tsx"],"names":[],"mappings":"AA8FA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB,+BA4VA"}

package/dist/admin/endpoints/approve-review.d.ts

@@ -0,0 +1,16 @@
+import { z } from "@86d-app/core";
+export declare const approveReview: import("better-call").StrictEndpoint<"/admin/reviews/:id/approve", {
+    method: "PUT";
+    params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+}, {
+    error: string;
+    status: number;
+    review?: never;
+} | {
+    review: import("../..").Review;
+    error?: never;
+    status?: never;
+}>;
+//# sourceMappingURL=approve-review.d.ts.map

package/dist/admin/endpoints/approve-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve-review.d.ts","sourceRoot":"","sources":["../../../src/admin/endpoints/approve-review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,CAAC,EAAE,MAAM,eAAe,CAAC;AAGvD,eAAO,MAAM,aAAa;;;;;;;;;;;;;EAezB,CAAC"}

package/dist/admin/endpoints/delete-review.d.ts

@@ -0,0 +1,16 @@
+import { z } from "@86d-app/core";
+export declare const deleteReview: import("better-call").StrictEndpoint<"/admin/reviews/:id/delete", {
+    method: "DELETE";
+    params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+}, {
+    error: string;
+    status: number;
+    deleted?: never;
+} | {
+    deleted: boolean;
+    error?: never;
+    status?: never;
+}>;
+//# sourceMappingURL=delete-review.d.ts.map

package/dist/admin/endpoints/delete-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delete-review.d.ts","sourceRoot":"","sources":["../../../src/admin/endpoints/delete-review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,CAAC,EAAE,MAAM,eAAe,CAAC;AAGvD,eAAO,MAAM,YAAY;;;;;;;;;;;;;EAaxB,CAAC"}

package/dist/admin/endpoints/get-review.d.ts

@@ -0,0 +1,16 @@
+import { z } from "@86d-app/core";
+export declare const getReview: import("better-call").StrictEndpoint<"/admin/reviews/:id", {
+    method: "GET";
+    params: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+}, {
+    error: string;
+    status: number;
+    review?: never;
+} | {
+    review: import("../..").Review;
+    error?: never;
+    status?: never;
+}>;
+//# sourceMappingURL=get-review.d.ts.map

package/dist/admin/endpoints/get-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-review.d.ts","sourceRoot":"","sources":["../../../src/admin/endpoints/get-review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,CAAC,EAAE,MAAM,eAAe,CAAC;AAGvD,eAAO,MAAM,SAAS;;;;;;;;;;;;;EAYrB,CAAC"}