@86d-app/reviews 0.0.3

package/src/index.ts

@@ -0,0 +1,73 @@
+import type { Module, ModuleConfig, ModuleContext } from "@86d-app/core";
+import { adminEndpoints } from "./admin/endpoints";
+import { reviewsSchema } from "./schema";
+import { createReviewController } from "./service-impl";
+import { storeEndpoints } from "./store/endpoints";
+
+export type {
+	RatingSummary,
+	Review,
+	ReviewAnalytics,
+	ReviewController,
+	ReviewRequest,
+	ReviewRequestStats,
+	ReviewStatus,
+} from "./service";
+
+export interface ReviewsOptions extends ModuleConfig {
+	/** Auto-approve reviews (no moderation queue) */
+	autoApprove?: string;
+}
+
+export default function reviews(options?: ReviewsOptions): Module {
+	return {
+		id: "reviews",
+		version: "0.0.1",
+		schema: reviewsSchema,
+		exports: {
+			read: ["productRating", "reviewCount"],
+		},
+		events: {
+			emits: [
+				"review.submitted",
+				"review.approved",
+				"review.rejected",
+				"review.responded",
+				"review.requested",
+			],
+		},
+		init: async (ctx: ModuleContext) => {
+			const controller = createReviewController(ctx.data, {
+				autoApprove: options?.autoApprove === "true",
+			});
+			return { controllers: { reviews: controller } };
+		},
+		endpoints: {
+			store: storeEndpoints,
+			admin: adminEndpoints,
+		},
+		admin: {
+			pages: [
+				{
+					path: "/admin/reviews",
+					component: "ReviewList",
+					label: "Reviews",
+					icon: "Star",
+					group: "Marketing",
+				},
+				{
+					path: "/admin/reviews/analytics",
+					component: "ReviewAnalytics",
+					label: "Review Analytics",
+					icon: "ChartBar",
+					group: "Marketing",
+				},
+				{
+					path: "/admin/reviews/:id",
+					component: "ReviewModeration",
+				},
+			],
+		},
+		options,
+	};
+}

package/src/mdx.d.ts

@@ -0,0 +1,5 @@
+declare module "*.mdx" {
+	import type { ComponentType } from "react";
+	const Component: ComponentType<Record<string, unknown>>;
+	export default Component;
+}

package/src/schema.ts

@@ -0,0 +1,37 @@
+import type { ModuleSchema } from "@86d-app/core";
+
+export const reviewsSchema = {
+	review: {
+		fields: {
+			id: { type: "string", required: true },
+			productId: { type: "string", required: true },
+			customerId: { type: "string", required: false },
+			authorName: { type: "string", required: true },
+			authorEmail: { type: "string", required: true },
+			rating: { type: "number", required: true },
+			title: { type: "string", required: false },
+			body: { type: "string", required: true },
+			status: { type: "string", required: true, defaultValue: "pending" },
+			isVerifiedPurchase: {
+				type: "boolean",
+				required: true,
+				defaultValue: false,
+			},
+			helpfulCount: { type: "number", required: true, defaultValue: 0 },
+			merchantResponse: { type: "string", required: false },
+			merchantResponseAt: { type: "date", required: false },
+			moderationNote: { type: "string", required: false },
+			createdAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+			},
+			updatedAt: {
+				type: "date",
+				required: true,
+				defaultValue: () => new Date(),
+				onUpdate: () => new Date(),
+			},
+		},
+	},
+} satisfies ModuleSchema;

package/src/service-impl.ts

@@ -0,0 +1,263 @@
+import type { ModuleDataService } from "@86d-app/core";
+import type {
+	Review,
+	ReviewController,
+	ReviewRequest,
+	ReviewStatus,
+} from "./service";
+
+export function createReviewController(
+	data: ModuleDataService,
+	options?: { autoApprove?: boolean },
+): ReviewController {
+	return {
+		async createReview(params) {
+			const id = crypto.randomUUID();
+			const now = new Date();
+			const status: ReviewStatus =
+				options?.autoApprove === true ? "approved" : "pending";
+			const review: Review = {
+				id,
+				productId: params.productId,
+				customerId: params.customerId,
+				authorName: params.authorName,
+				authorEmail: params.authorEmail,
+				rating: params.rating,
+				title: params.title,
+				body: params.body,
+				status,
+				isVerifiedPurchase: params.isVerifiedPurchase ?? false,
+				helpfulCount: 0,
+				createdAt: now,
+				updatedAt: now,
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("review", id, review as Record<string, any>);
+			return review;
+		},
+
+		async getReview(id) {
+			const raw = await data.get("review", id);
+			if (!raw) return null;
+			return raw as unknown as Review;
+		},
+
+		async listReviewsByProduct(productId, params) {
+			// biome-ignore lint/suspicious/noExplicitAny: JSONB where filter
+			const where: Record<string, any> = { productId };
+			if (params?.approvedOnly) where.status = "approved";
+
+			const all = await data.findMany("review", {
+				where,
+				...(params?.take !== undefined ? { take: params.take } : {}),
+				...(params?.skip !== undefined ? { skip: params.skip } : {}),
+			});
+			return all as unknown as Review[];
+		},
+
+		async listReviews(params) {
+			// biome-ignore lint/suspicious/noExplicitAny: JSONB where filter
+			const where: Record<string, any> = {};
+			if (params?.productId) where.productId = params.productId;
+			if (params?.status) where.status = params.status;
+
+			const all = await data.findMany("review", {
+				...(Object.keys(where).length > 0 ? { where } : {}),
+				...(params?.take !== undefined ? { take: params.take } : {}),
+				...(params?.skip !== undefined ? { skip: params.skip } : {}),
+			});
+			return all as unknown as Review[];
+		},
+
+		async updateReviewStatus(id, status, moderationNote) {
+			const existing = await data.get("review", id);
+			if (!existing) return null;
+			const review = existing as unknown as Review;
+			const updated: Review = {
+				...review,
+				status,
+				updatedAt: new Date(),
+				...(moderationNote !== undefined ? { moderationNote } : {}),
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("review", id, updated as Record<string, any>);
+			return updated;
+		},
+
+		async deleteReview(id) {
+			const existing = await data.get("review", id);
+			if (!existing) return false;
+			await data.delete("review", id);
+			return true;
+		},
+
+		async addMerchantResponse(id, response) {
+			const existing = await data.get("review", id);
+			if (!existing) return null;
+			const review = existing as unknown as Review;
+			const updated: Review = {
+				...review,
+				merchantResponse: response,
+				merchantResponseAt: new Date(),
+				updatedAt: new Date(),
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("review", id, updated as Record<string, any>);
+			return updated;
+		},
+
+		async markHelpful(id) {
+			const existing = await data.get("review", id);
+			if (!existing) return null;
+			const review = existing as unknown as Review;
+			const updated: Review = {
+				...review,
+				helpfulCount: review.helpfulCount + 1,
+				updatedAt: new Date(),
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("review", id, updated as Record<string, any>);
+			return updated;
+		},
+
+		async getReviewAnalytics() {
+			const all = await data.findMany("review", {});
+			const reviews = all as unknown as Review[];
+
+			const distribution: Record<string, number> = {
+				"1": 0,
+				"2": 0,
+				"3": 0,
+				"4": 0,
+				"5": 0,
+			};
+			let pendingCount = 0;
+			let approvedCount = 0;
+			let rejectedCount = 0;
+			let ratingTotal = 0;
+			let withMerchantResponse = 0;
+
+			for (const r of reviews) {
+				if (r.status === "pending") pendingCount++;
+				else if (r.status === "approved") approvedCount++;
+				else if (r.status === "rejected") rejectedCount++;
+
+				ratingTotal += r.rating;
+				const key = String(r.rating);
+				if (key in distribution) {
+					distribution[key] = (distribution[key] ?? 0) + 1;
+				}
+				if (r.merchantResponse) withMerchantResponse++;
+			}
+
+			return {
+				totalReviews: reviews.length,
+				pendingCount,
+				approvedCount,
+				rejectedCount,
+				averageRating:
+					reviews.length > 0
+						? Math.round((ratingTotal / reviews.length) * 10) / 10
+						: 0,
+				ratingsDistribution: distribution,
+				withMerchantResponse,
+			};
+		},
+
+		async getProductRatingSummary(productId) {
+			const all = await data.findMany("review", {
+				where: { productId, status: "approved" },
+			});
+			const reviews = all as unknown as Review[];
+			if (reviews.length === 0) {
+				return {
+					average: 0,
+					count: 0,
+					distribution: { "1": 0, "2": 0, "3": 0, "4": 0, "5": 0 },
+				};
+			}
+			const distribution: Record<string, number> = {
+				"1": 0,
+				"2": 0,
+				"3": 0,
+				"4": 0,
+				"5": 0,
+			};
+			let total = 0;
+			for (const r of reviews) {
+				total += r.rating;
+				const key = String(r.rating);
+				if (key in distribution) {
+					distribution[key] = (distribution[key] ?? 0) + 1;
+				}
+			}
+			const average = Math.round((total / reviews.length) * 10) / 10;
+			return { average, count: reviews.length, distribution };
+		},
+
+		async createReviewRequest(params) {
+			const id = crypto.randomUUID();
+			const request: ReviewRequest = {
+				id,
+				orderId: params.orderId,
+				orderNumber: params.orderNumber,
+				email: params.email,
+				customerName: params.customerName,
+				items: params.items,
+				sentAt: new Date(),
+			};
+			// biome-ignore lint/suspicious/noExplicitAny: ModuleDataService requires any
+			await data.upsert("reviewRequest", id, request as Record<string, any>);
+			return request;
+		},
+
+		async getReviewRequest(orderId) {
+			const all = await data.findMany("reviewRequest", {
+				where: { orderId },
+				take: 1,
+			});
+			const requests = all as unknown as ReviewRequest[];
+			return requests.length > 0 ? requests[0] : null;
+		},
+
+		async listReviewRequests(params) {
+			const all = await data.findMany("reviewRequest", {
+				...(params?.take !== undefined ? { take: params.take } : {}),
+				...(params?.skip !== undefined ? { skip: params.skip } : {}),
+			});
+			return all as unknown as ReviewRequest[];
+		},
+
+		async listReviewsByCustomer(customerId, params) {
+			// biome-ignore lint/suspicious/noExplicitAny: JSONB where filter
+			const where: Record<string, any> = { customerId };
+			if (params?.status) where.status = params.status;
+
+			const all = await data.findMany("review", {
+				where,
+			});
+			const reviews = all as unknown as Review[];
+
+			const filtered = reviews.slice(
+				params?.skip ?? 0,
+				params?.skip !== undefined && params?.take !== undefined
+					? params.skip + params.take
+					: params?.take !== undefined
+						? params.take
+						: undefined,
+			);
+
+			return { reviews: filtered, total: reviews.length };
+		},
+
+		async getReviewRequestStats() {
+			const all = await data.findMany("reviewRequest", {});
+			const requests = all as unknown as ReviewRequest[];
+			const uniqueOrders = new Set(requests.map((r) => r.orderId));
+			return {
+				totalSent: requests.length,
+				uniqueOrders: uniqueOrders.size,
+			};
+		},
+	};
+}

package/src/service.ts

@@ -0,0 +1,126 @@
+import type { ModuleController } from "@86d-app/core";
+
+export type ReviewStatus = "pending" | "approved" | "rejected";
+
+export interface Review {
+	id: string;
+	productId: string;
+	customerId?: string | undefined;
+	authorName: string;
+	authorEmail: string;
+	rating: number;
+	title?: string | undefined;
+	body: string;
+	status: ReviewStatus;
+	isVerifiedPurchase: boolean;
+	helpfulCount: number;
+	merchantResponse?: string | undefined;
+	merchantResponseAt?: Date | undefined;
+	moderationNote?: string | undefined;
+	createdAt: Date;
+	updatedAt: Date;
+}
+
+export interface RatingSummary {
+	average: number;
+	count: number;
+	distribution: Record<string, number>;
+}
+
+export interface ReviewController extends ModuleController {
+	createReview(params: {
+		productId: string;
+		authorName: string;
+		authorEmail: string;
+		rating: number;
+		title?: string | undefined;
+		body: string;
+		customerId?: string | undefined;
+		isVerifiedPurchase?: boolean | undefined;
+	}): Promise<Review>;
+
+	getReview(id: string): Promise<Review | null>;
+
+	listReviewsByProduct(
+		productId: string,
+		params?: {
+			approvedOnly?: boolean | undefined;
+			take?: number | undefined;
+			skip?: number | undefined;
+		},
+	): Promise<Review[]>;
+
+	listReviews(params?: {
+		productId?: string | undefined;
+		status?: ReviewStatus | undefined;
+		take?: number | undefined;
+		skip?: number | undefined;
+	}): Promise<Review[]>;
+
+	updateReviewStatus(
+		id: string,
+		status: ReviewStatus,
+		moderationNote?: string | undefined,
+	): Promise<Review | null>;
+
+	deleteReview(id: string): Promise<boolean>;
+
+	getProductRatingSummary(productId: string): Promise<RatingSummary>;
+
+	addMerchantResponse(id: string, response: string): Promise<Review | null>;
+
+	markHelpful(id: string): Promise<Review | null>;
+
+	getReviewAnalytics(): Promise<ReviewAnalytics>;
+
+	createReviewRequest(params: {
+		orderId: string;
+		orderNumber: string;
+		email: string;
+		customerName: string;
+		items: Array<{ productId: string; name: string }>;
+	}): Promise<ReviewRequest>;
+
+	getReviewRequest(orderId: string): Promise<ReviewRequest | null>;
+
+	listReviewRequests(params?: {
+		take?: number | undefined;
+		skip?: number | undefined;
+	}): Promise<ReviewRequest[]>;
+
+	getReviewRequestStats(): Promise<ReviewRequestStats>;
+
+	listReviewsByCustomer(
+		customerId: string,
+		params?: {
+			status?: ReviewStatus | undefined;
+			take?: number | undefined;
+			skip?: number | undefined;
+		},
+	): Promise<{ reviews: Review[]; total: number }>;
+}
+
+export interface ReviewAnalytics {
+	totalReviews: number;
+	pendingCount: number;
+	approvedCount: number;
+	rejectedCount: number;
+	averageRating: number;
+	ratingsDistribution: Record<string, number>;
+	withMerchantResponse: number;
+}
+
+export interface ReviewRequest {
+	id: string;
+	orderId: string;
+	orderNumber: string;
+	email: string;
+	customerName: string;
+	items: Array<{ productId: string; name: string }>;
+	sentAt: Date;
+}
+
+export interface ReviewRequestStats {
+	totalSent: number;
+	uniqueOrders: number;
+}

package/src/store/components/_hooks.ts

@@ -0,0 +1,13 @@
+"use client";
+
+import { useModuleClient } from "@86d-app/core/client";
+
+export function useReviewsApi() {
+	const client = useModuleClient();
+	return {
+		submitReview: client.module("reviews").store["/reviews"],
+		listProductReviews:
+			client.module("reviews").store["/reviews/products/:productId"],
+		markHelpful: client.module("reviews").store["/reviews/:id/helpful"],
+	};
+}

package/src/store/components/_utils.ts

@@ -0,0 +1,16 @@
+export function formatDate(iso: string): string {
+	return new Intl.DateTimeFormat("en-US", {
+		month: "short",
+		day: "numeric",
+		year: "numeric",
+	}).format(new Date(iso));
+}
+
+export function extractError(error: Error | null, fallback: string): string {
+	if (!error) return fallback;
+	// biome-ignore lint/suspicious/noExplicitAny: accessing HTTP error body property
+	const body = (error as any)?.body;
+	if (typeof body?.error === "string") return body.error;
+	if (typeof body?.error?.message === "string") return body.error.message;
+	return fallback;
+}

package/src/store/components/distribution-bars.mdx

@@ -0,0 +1,21 @@
+<div className="space-y-1.5">
+  {[5, 4, 3, 2, 1].map((n) => {
+    const count = props.distribution[String(n)] ?? 0;
+    const pct = props.total > 0 ? (count / props.total) * 100 : 0;
+    return (
+      <div key={n} className="flex items-center gap-2 text-sm">
+        <span className="w-3 text-right text-muted-foreground">{n}</span>
+        <span className="text-amber-400 text-xs">★</span>
+        <div className="h-2 flex-1 overflow-hidden rounded-full bg-muted">
+          <div
+            className="h-full rounded-full bg-amber-400 transition-all"
+            style={{ width: `${pct}%` }}
+          />
+        </div>
+        <span className="w-5 text-right text-muted-foreground/70 text-xs">
+          {count}
+        </span>
+      </div>
+    );
+  })}
+</div>

package/src/store/components/distribution-bars.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+import DistributionBarsTemplate from "./distribution-bars.mdx";
+
+export function DistributionBars({
+	distribution,
+	total,
+}: {
+	distribution: Record<string, number>;
+	total: number;
+}) {
+	return <DistributionBarsTemplate distribution={distribution} total={total} />;
+}

package/src/store/components/index.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import type { MDXComponents } from "mdx/types";
+import { DistributionBars } from "./distribution-bars";
+import { ProductReviews } from "./product-reviews";
+import { ReviewCard } from "./review-card";
+import { ReviewForm } from "./review-form";
+import { ReviewsSummary } from "./reviews-summary";
+import { StarDisplay } from "./star-display";
+import { StarPicker } from "./star-picker";
+
+export default {
+	ReviewsSummary,
+	ProductReviews,
+	StarDisplay,
+	StarPicker,
+	ReviewCard,
+	ReviewForm,
+	DistributionBars,
+} satisfies MDXComponents;

package/src/store/components/product-reviews.mdx

@@ -0,0 +1,52 @@
+<section className="py-8">
+  <div className="mb-6 flex flex-wrap items-center justify-between gap-4">
+    <div>
+      <h2 className="font-semibold text-foreground text-xl">{props.title}</h2>
+      {!props.noReviews && props.summary && (
+        <div className="mt-1 flex items-center gap-2">
+          {props.starDisplay}
+          <span className="font-medium text-foreground text-lg">
+            {props.summary.average.toFixed(1)}
+          </span>
+          <span className="text-muted-foreground text-sm">
+            ({props.summary.count} review{props.summary.count !== 1 ? "s" : ""})
+          </span>
+        </div>
+      )}
+    </div>
+    <button
+      type="button"
+      onClick={props.onToggleForm}
+      className="rounded-lg border border-border bg-background px-4 py-2 font-medium text-foreground text-sm transition-colors hover:bg-muted"
+    >
+      {props.showForm ? "Cancel" : "Write a Review"}
+    </button>
+  </div>
+
+  {props.showForm && (
+    <div className="mb-8">
+      {props.formContent}
+    </div>
+  )}
+
+  {props.noReviews && !props.showForm && (
+    <div className="rounded-xl border border-border bg-muted/30 py-12 text-center">
+      <p className="font-medium text-foreground text-sm">No reviews yet</p>
+      <p className="mt-1 text-muted-foreground text-sm">
+        Be the first to review this product.
+      </p>
+    </div>
+  )}
+
+  {!props.noReviews && props.summary && (
+    <div className="mb-6 flex flex-col gap-5 sm:flex-row sm:items-start">
+      <div className="sm:w-48">
+        {props.distributionBars}
+      </div>
+      <div className="hidden h-auto w-px bg-border sm:block" />
+      <div className="flex-1">
+        {props.reviewListContent}
+      </div>
+    </div>
+  )}
+</section>