@porulle/plugin-reviews 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @porulle/plugin-reviews
+
+Customer reviews on catalog entities with moderation, replies, and aggregate summaries.
+
+## Install
+
+```bash
+bun add @porulle/plugin-reviews
+```
+
+Add to `commerce.config.ts`:
+
+```typescript
+import { reviewsPlugin } from "@porulle/plugin-reviews";
+
+export default defineConfig({
+  plugins: [reviewsPlugin()],
+});
+```
+
+Add to `drizzle.config.ts`:
+
+```typescript
+schema: [
+  "./node_modules/@porulle/plugin-reviews/src/schema.ts",
+  // ...
+],
+```
+
+## What it does
+
+Stores per-entity reviews with optional verified order linkage, publishes after approval, supports merchant replies, and exposes summaries for storefront display.
+
+## Routes exposed
+
+**`/reviews`** — `POST /`, `GET /entity/{entityId}`, `GET /entity/{entityId}/summary`, `PATCH /{id}/approve`, `PATCH /{id}/reject`, `POST /{id}/reply`, `GET /mine`
+
+## Hooks
+
+**Emitted:** none.
+
+**Consumed:** none.
+
+## MCP tools
+
+**`reviews`** — `list`, `summary`, `submit`, `approve`
+
+## Configuration options
+
+None (`reviewsPlugin()` takes no options).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { Db } from "./types.js";
+export { ReviewService } from "./services/review-service.js";
+export declare function reviewsPlugin(): import("@porulle/core").CommercePlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE7D,wBAAgB,aAAa,2CA2B5B"}

package/dist/index.js

@@ -0,0 +1,25 @@
+import { defineCommercePlugin } from "@porulle/core";
+import { customerReviews } from "./schema.js";
+import { ReviewService } from "./services/review-service.js";
+import { buildReviewRoutes } from "./routes/reviews.js";
+export { ReviewService } from "./services/review-service.js";
+export function reviewsPlugin() {
+    return defineCommercePlugin({
+        id: "reviews",
+        version: "1.0.0",
+        permissions: [
+            { scope: "reviews:admin", description: "Approve, reject, and reply to reviews." },
+            { scope: "reviews:write", description: "Submit reviews." },
+            { scope: "reviews:read", description: "View reviews and summaries." },
+        ],
+        schema: () => ({ customerReviews }),
+        hooks: () => [],
+        routes: (ctx) => {
+            const db = ctx.database.db;
+            if (!db)
+                return [];
+            const customers = ctx.services?.customers;
+            return buildReviewRoutes(new ReviewService(db, customers ? { customers } : undefined), ctx);
+        },
+    });
+}

package/dist/routes/reviews.d.ts

@@ -0,0 +1,9 @@
+import type { ReviewService } from "../services/review-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+export declare function buildReviewRoutes(service: ReviewService, ctx: {
+    services?: Record<string, unknown>;
+    database?: {
+        db: unknown;
+    };
+}): PluginRouteRegistration[];
+//# sourceMappingURL=reviews.d.ts.map

package/dist/routes/reviews.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reviews.d.ts","sourceRoot":"","sources":["../../src/routes/reviews.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,GACtE,uBAAuB,EAAE,CAwE3B"}

package/dist/routes/reviews.js

@@ -0,0 +1,72 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+export function buildReviewRoutes(service, ctx) {
+    const r = router("Reviews", "/reviews", ctx);
+    r.post("/").summary("Submit review").permission("reviews:write")
+        .input(z.object({
+        customerId: z.string().uuid().optional(),
+        entityId: z.string().uuid(),
+        orderId: z.string().uuid().optional(),
+        rating: z.number().int().min(1).max(5),
+        title: z.string().optional(),
+        body: z.string().optional(),
+    }))
+        .handler(async ({ input, orgId, actor }) => {
+        const body = input;
+        const result = await service.submit(orgId, body, (actor ?? null));
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.get("/entity/{entityId}").summary("List reviews for entity").permission("reviews:read")
+        .handler(async ({ params, orgId }) => {
+        const result = await service.listForEntity(orgId, params.entityId);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.get("/entity/{entityId}/summary").summary("Review summary for entity").permission("reviews:read")
+        .handler(async ({ params, orgId }) => {
+        const result = await service.getSummary(orgId, params.entityId);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.patch("/{id}/approve").summary("Approve review").permission("reviews:admin")
+        .handler(async ({ params, orgId }) => {
+        const result = await service.approve(orgId, params.id);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.patch("/{id}/reject").summary("Reject review").permission("reviews:admin")
+        .handler(async ({ params, orgId }) => {
+        const result = await service.reject(orgId, params.id);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.post("/{id}/reply").summary("Reply to review").permission("reviews:admin")
+        .input(z.object({
+        response: z.string().min(1),
+        responseBy: z.string().min(1),
+    }))
+        .handler(async ({ params, input, orgId }) => {
+        const body = input;
+        const result = await service.reply(orgId, params.id, body.response, body.responseBy);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    r.get("/mine").summary("My reviews").permission("reviews:write")
+        .handler(async ({ actor, orgId }) => {
+        // Use the authenticated actor's userId — never accept customerId from query
+        if (!actor?.userId)
+            throw new Error("Authentication required");
+        const result = await service.listByCustomer(orgId, actor.userId);
+        if (!result.ok)
+            throw new Error(result.error);
+        return result.value;
+    });
+    return r.routes();
+}

package/dist/schema.d.ts

@@ -0,0 +1,280 @@
+export declare const customerReviews: import("drizzle-orm/pg-core/table").PgTableWithColumns<{
+    name: "customer_reviews";
+    schema: undefined;
+    columns: {
+        id: import("@porulle/core/drizzle").PgColumn<{
+            name: "id";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        organizationId: import("@porulle/core/drizzle").PgColumn<{
+            name: "organization_id";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        customerId: import("@porulle/core/drizzle").PgColumn<{
+            name: "customer_id";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        entityId: import("@porulle/core/drizzle").PgColumn<{
+            name: "entity_id";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        orderId: import("@porulle/core/drizzle").PgColumn<{
+            name: "order_id";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        rating: import("@porulle/core/drizzle").PgColumn<{
+            name: "rating";
+            tableName: "customer_reviews";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        title: import("@porulle/core/drizzle").PgColumn<{
+            name: "title";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        body: import("@porulle/core/drizzle").PgColumn<{
+            name: "body";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("@porulle/core/drizzle").PgColumn<{
+            name: "status";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgText";
+            data: "pending" | "approved" | "rejected";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "approved", "rejected"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        isVerified: import("@porulle/core/drizzle").PgColumn<{
+            name: "is_verified";
+            tableName: "customer_reviews";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        isPublished: import("@porulle/core/drizzle").PgColumn<{
+            name: "is_published";
+            tableName: "customer_reviews";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        response: import("@porulle/core/drizzle").PgColumn<{
+            name: "response";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        responseBy: import("@porulle/core/drizzle").PgColumn<{
+            name: "response_by";
+            tableName: "customer_reviews";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        responseAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "response_at";
+            tableName: "customer_reviews";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "created_at";
+            tableName: "customer_reviews";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("@porulle/core/drizzle").PgColumn<{
+            name: "updated_at";
+            tableName: "customer_reviews";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuBzB,CAAC"}

package/dist/schema.js

@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, integer, boolean, timestamp, index } from "@porulle/core/drizzle";
+export const customerReviews = pgTable("customer_reviews", {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id").notNull(),
+    customerId: uuid("customer_id"),
+    entityId: uuid("entity_id").notNull(),
+    orderId: uuid("order_id"),
+    rating: integer("rating").notNull(),
+    title: text("title"),
+    body: text("body"),
+    status: text("status", { enum: ["pending", "approved", "rejected"] })
+        .notNull()
+        .default("pending"),
+    isVerified: boolean("is_verified").notNull().default(false),
+    isPublished: boolean("is_published").notNull().default(false),
+    response: text("response"),
+    responseBy: text("response_by"),
+    responseAt: timestamp("response_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+    orgIdx: index("idx_customer_reviews_org").on(table.organizationId),
+    entityIdx: index("idx_customer_reviews_entity").on(table.entityId),
+    statusIdx: index("idx_customer_reviews_status").on(table.status),
+}));

package/dist/services/review-service.d.ts

@@ -0,0 +1,40 @@
+import type { PluginResult } from "@porulle/core";
+import type { Actor } from "@porulle/core";
+import type { Db, Review } from "../types.js";
+export interface ReviewSummary {
+    averageRating: number;
+    totalCount: number;
+    distribution: Record<number, number>;
+}
+export declare class ReviewService {
+    private db;
+    private services?;
+    constructor(db: Db, services?: {
+        customers?: {
+            getByUserId(userId: string, actor?: Actor | null): Promise<{
+                ok: true;
+                value: {
+                    id: string;
+                };
+            } | {
+                ok: false;
+                error: unknown;
+            }>;
+        };
+    } | undefined);
+    submit(orgId: string, input: {
+        customerId?: string;
+        entityId: string;
+        orderId?: string;
+        rating: number;
+        title?: string;
+        body?: string;
+    }, actor: Actor | null): Promise<PluginResult<Review>>;
+    listForEntity(orgId: string, entityId: string, publishedOnly?: boolean): Promise<PluginResult<Review[]>>;
+    getSummary(orgId: string, entityId: string): Promise<PluginResult<ReviewSummary>>;
+    approve(orgId: string, id: string): Promise<PluginResult<Review>>;
+    reject(orgId: string, id: string): Promise<PluginResult<Review>>;
+    reply(orgId: string, id: string, response: string, responseBy: string): Promise<PluginResult<Review>>;
+    listByCustomer(orgId: string, customerId: string): Promise<PluginResult<Review[]>>;
+}
+//# sourceMappingURL=review-service.d.ts.map

package/dist/services/review-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-service.d.ts","sourceRoot":"","sources":["../../src/services/review-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,qBAAa,aAAa;IAEtB,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,QAAQ,CAAC;gBADT,EAAE,EAAE,EAAE,EACN,QAAQ,CAAC,EAAE;QACjB,SAAS,CAAC,EAAE;YACV,WAAW,CACT,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,GACnB,OAAO,CAAC;gBAAE,EAAE,EAAE,IAAI,CAAC;gBAAC,KAAK,EAAE;oBAAE,EAAE,EAAE,MAAM,CAAA;iBAAE,CAAA;aAAE,GAAG;gBAAE,EAAE,EAAE,KAAK,CAAC;gBAAC,KAAK,EAAE,OAAO,CAAA;aAAE,CAAC,CAAC;SACjF,CAAC;KACH,YAAA;IAGG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;QACjC,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAuChD,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IAYxG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;IAwBjF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IASjE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAShE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IASrG,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;CAQzF"}

package/dist/services/review-service.js

@@ -0,0 +1,110 @@
+import { eq, and, sql } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import { customerReviews } from "../schema.js";
+export class ReviewService {
+    db;
+    services;
+    constructor(db, services) {
+        this.db = db;
+        this.services = services;
+    }
+    async submit(orgId, input, actor) {
+        if (input.rating < 1 || input.rating > 5 || !Number.isInteger(input.rating)) {
+            return Err("Rating must be an integer between 1 and 5");
+        }
+        if (!actor?.userId) {
+            return Err("Authentication required");
+        }
+        const staffRoles = new Set(["staff", "admin", "owner", "ai_agent", "service"]);
+        const isStaff = typeof actor.role === "string" && staffRoles.has(actor.role);
+        let resolvedCustomerId = null;
+        if (isStaff) {
+            resolvedCustomerId = input.customerId ?? null;
+        }
+        else {
+            const customers = this.services?.customers;
+            if (!customers?.getByUserId) {
+                return Err("Customer resolution is not configured");
+            }
+            const profile = await customers.getByUserId(actor.userId, actor);
+            if (!profile.ok) {
+                return Err("Customer profile not found");
+            }
+            resolvedCustomerId = profile.value.id;
+        }
+        const isVerified = input.orderId != null;
+        const rows = await this.db.insert(customerReviews).values({
+            organizationId: orgId,
+            customerId: resolvedCustomerId,
+            entityId: input.entityId,
+            orderId: input.orderId ?? null,
+            rating: input.rating,
+            title: input.title ?? null,
+            body: input.body ?? null,
+            isVerified,
+        }).returning();
+        return Ok(rows[0]);
+    }
+    async listForEntity(orgId, entityId, publishedOnly) {
+        const conditions = [
+            eq(customerReviews.organizationId, orgId),
+            eq(customerReviews.entityId, entityId),
+        ];
+        if (publishedOnly) {
+            conditions.push(eq(customerReviews.isPublished, true));
+        }
+        const rows = await this.db.select().from(customerReviews).where(and(...conditions));
+        return Ok(rows);
+    }
+    async getSummary(orgId, entityId) {
+        const rows = await this.db.select({
+            rating: customerReviews.rating,
+            count: sql `count(*)::int`,
+        })
+            .from(customerReviews)
+            .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.entityId, entityId)))
+            .groupBy(customerReviews.rating);
+        const distribution = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+        let totalCount = 0;
+        let totalSum = 0;
+        for (const row of rows) {
+            distribution[row.rating] = row.count;
+            totalCount += row.count;
+            totalSum += row.rating * row.count;
+        }
+        const averageRating = totalCount > 0 ? Math.round((totalSum / totalCount) * 100) / 100 : 0;
+        return Ok({ averageRating, totalCount, distribution });
+    }
+    async approve(orgId, id) {
+        const rows = await this.db.update(customerReviews)
+            .set({ status: "approved", isPublished: true, updatedAt: new Date() })
+            .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.id, id)))
+            .returning();
+        if (rows.length === 0)
+            return Err("Review not found");
+        return Ok(rows[0]);
+    }
+    async reject(orgId, id) {
+        const rows = await this.db.update(customerReviews)
+            .set({ status: "rejected", isPublished: false, updatedAt: new Date() })
+            .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.id, id)))
+            .returning();
+        if (rows.length === 0)
+            return Err("Review not found");
+        return Ok(rows[0]);
+    }
+    async reply(orgId, id, response, responseBy) {
+        const rows = await this.db.update(customerReviews)
+            .set({ response, responseBy, responseAt: new Date(), updatedAt: new Date() })
+            .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.id, id)))
+            .returning();
+        if (rows.length === 0)
+            return Err("Review not found");
+        return Ok(rows[0]);
+    }
+    async listByCustomer(orgId, customerId) {
+        const rows = await this.db.select().from(customerReviews)
+            .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.customerId, customerId)));
+        return Ok(rows);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,5 @@
+import type { customerReviews } from "./schema.js";
+export type { PluginDb as Db } from "@porulle/core";
+export type Review = typeof customerReviews.$inferSelect;
+export type ReviewInsert = typeof customerReviews.$inferInsert;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,eAAe,CAAC;AACpD,MAAM,MAAM,MAAM,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC;AACzD,MAAM,MAAM,YAAY,GAAG,OAAO,eAAe,CAAC,YAAY,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@porulle/plugin-reviews",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    },
+    "./schema": {
+      "bun": "./src/schema.ts",
+      "import": "./dist/schema.js",
+      "require": "./dist/schema.js",
+      "types": "./src/schema.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "@porulle/core": "workspace:*",
+    "hono": "^4.12.5"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "description": "Customer reviews on catalog entities with moderation, replies, and aggregate summaries.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/plugins/plugin-reviews"
+  },
+  "author": "Porulle contributors"
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+import { defineCommercePlugin } from "@porulle/core";
+import { customerReviews } from "./schema.js";
+import { ReviewService } from "./services/review-service.js";
+import { buildReviewRoutes } from "./routes/reviews.js";
+export type { Db } from "./types.js";
+export { ReviewService } from "./services/review-service.js";
+
+export function reviewsPlugin() {
+  return defineCommercePlugin({
+    id: "reviews",
+    version: "1.0.0",
+    permissions: [
+      { scope: "reviews:admin", description: "Approve, reject, and reply to reviews." },
+      { scope: "reviews:write", description: "Submit reviews." },
+      { scope: "reviews:read", description: "View reviews and summaries." },
+    ],
+    schema: () => ({ customerReviews }),
+    hooks: () => [],
+
+    routes: (ctx) => {
+      const db = ctx.database.db;
+      if (!db) return [];
+      const customers = ctx.services?.customers as {
+        getByUserId(
+          userId: string,
+          actor?: import("@porulle/core").Actor | null,
+        ): Promise<{ ok: true; value: { id: string } } | { ok: false; error: unknown }>;
+      } | undefined;
+      return buildReviewRoutes(
+        new ReviewService(db, customers ? { customers } : undefined),
+        ctx,
+      );
+    },
+  });
+}

package/src/routes/reviews.ts

@@ -0,0 +1,82 @@
+import { router } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { Actor } from "@porulle/core";
+import type { ReviewService } from "../services/review-service.js";
+import type { PluginRouteRegistration } from "@porulle/core";
+
+export function buildReviewRoutes(
+  service: ReviewService,
+  ctx: { services?: Record<string, unknown>; database?: { db: unknown } },
+): PluginRouteRegistration[] {
+  const r = router("Reviews", "/reviews", ctx);
+
+  r.post("/").summary("Submit review").permission("reviews:write")
+    .input(z.object({
+      customerId: z.string().uuid().optional(),
+      entityId: z.string().uuid(),
+      orderId: z.string().uuid().optional(),
+      rating: z.number().int().min(1).max(5),
+      title: z.string().optional(),
+      body: z.string().optional(),
+    }))
+    .handler(async ({ input, orgId, actor }) => {
+      const body = input as {
+        customerId?: string; entityId: string; orderId?: string;
+        rating: number; title?: string; body?: string;
+      };
+      const result = await service.submit(orgId, body, (actor ?? null) as Actor | null);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.get("/entity/{entityId}").summary("List reviews for entity").permission("reviews:read")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.listForEntity(orgId, params.entityId!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.get("/entity/{entityId}/summary").summary("Review summary for entity").permission("reviews:read")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.getSummary(orgId, params.entityId!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.patch("/{id}/approve").summary("Approve review").permission("reviews:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.approve(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.patch("/{id}/reject").summary("Reject review").permission("reviews:admin")
+    .handler(async ({ params, orgId }) => {
+      const result = await service.reject(orgId, params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.post("/{id}/reply").summary("Reply to review").permission("reviews:admin")
+    .input(z.object({
+      response: z.string().min(1),
+      responseBy: z.string().min(1),
+    }))
+    .handler(async ({ params, input, orgId }) => {
+      const body = input as { response: string; responseBy: string };
+      const result = await service.reply(orgId, params.id!, body.response, body.responseBy);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  r.get("/mine").summary("My reviews").permission("reviews:write")
+    .handler(async ({ actor, orgId }) => {
+      // Use the authenticated actor's userId — never accept customerId from query
+      if (!actor?.userId) throw new Error("Authentication required");
+      const result = await service.listByCustomer(orgId, actor.userId);
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    });
+
+  return r.routes();
+}

package/src/schema.ts

@@ -0,0 +1,26 @@
+import { pgTable, uuid, text, integer, boolean, timestamp, index } from "@porulle/core/drizzle";
+
+export const customerReviews = pgTable("customer_reviews", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  customerId: uuid("customer_id"),
+  entityId: uuid("entity_id").notNull(),
+  orderId: uuid("order_id"),
+  rating: integer("rating").notNull(),
+  title: text("title"),
+  body: text("body"),
+  status: text("status", { enum: ["pending", "approved", "rejected"] })
+    .notNull()
+    .default("pending"),
+  isVerified: boolean("is_verified").notNull().default(false),
+  isPublished: boolean("is_published").notNull().default(false),
+  response: text("response"),
+  responseBy: text("response_by"),
+  responseAt: timestamp("response_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_customer_reviews_org").on(table.organizationId),
+  entityIdx: index("idx_customer_reviews_entity").on(table.entityId),
+  statusIdx: index("idx_customer_reviews_status").on(table.status),
+}));

package/src/services/review-service.ts

@@ -0,0 +1,144 @@
+import { eq, and, sql } from "@porulle/core/drizzle";
+import { Ok, Err } from "@porulle/core";
+import type { PluginResult } from "@porulle/core";
+import type { Actor } from "@porulle/core";
+import { customerReviews } from "../schema.js";
+import type { Db, Review } from "../types.js";
+
+export interface ReviewSummary {
+  averageRating: number;
+  totalCount: number;
+  distribution: Record<number, number>;
+}
+
+export class ReviewService {
+  constructor(
+    private db: Db,
+    private services?: {
+      customers?: {
+        getByUserId(
+          userId: string,
+          actor?: Actor | null,
+        ): Promise<{ ok: true; value: { id: string } } | { ok: false; error: unknown }>;
+      };
+    },
+  ) {}
+
+  async submit(orgId: string, input: {
+    customerId?: string;
+    entityId: string;
+    orderId?: string;
+    rating: number;
+    title?: string;
+    body?: string;
+  }, actor: Actor | null): Promise<PluginResult<Review>> {
+    if (input.rating < 1 || input.rating > 5 || !Number.isInteger(input.rating)) {
+      return Err("Rating must be an integer between 1 and 5");
+    }
+    if (!actor?.userId) {
+      return Err("Authentication required");
+    }
+    const staffRoles = new Set(["staff", "admin", "owner", "ai_agent", "service"]);
+    const isStaff = typeof actor.role === "string" && staffRoles.has(actor.role);
+
+    let resolvedCustomerId: string | null = null;
+    if (isStaff) {
+      resolvedCustomerId = input.customerId ?? null;
+    } else {
+      const customers = this.services?.customers;
+      if (!customers?.getByUserId) {
+        return Err("Customer resolution is not configured");
+      }
+      const profile = await customers.getByUserId(actor.userId, actor);
+      if (!profile.ok) {
+        return Err("Customer profile not found");
+      }
+      resolvedCustomerId = profile.value.id;
+    }
+
+    const isVerified = input.orderId != null;
+    const rows = await this.db.insert(customerReviews).values({
+      organizationId: orgId,
+      customerId: resolvedCustomerId,
+      entityId: input.entityId,
+      orderId: input.orderId ?? null,
+      rating: input.rating,
+      title: input.title ?? null,
+      body: input.body ?? null,
+      isVerified,
+    }).returning();
+    return Ok(rows[0]!);
+  }
+
+  async listForEntity(orgId: string, entityId: string, publishedOnly?: boolean): Promise<PluginResult<Review[]>> {
+    const conditions = [
+      eq(customerReviews.organizationId, orgId),
+      eq(customerReviews.entityId, entityId),
+    ];
+    if (publishedOnly) {
+      conditions.push(eq(customerReviews.isPublished, true));
+    }
+    const rows = await this.db.select().from(customerReviews).where(and(...conditions));
+    return Ok(rows);
+  }
+
+  async getSummary(orgId: string, entityId: string): Promise<PluginResult<ReviewSummary>> {
+    const rows = await this.db.select({
+      rating: customerReviews.rating,
+      count: sql<number>`count(*)::int`,
+    })
+      .from(customerReviews)
+      .where(and(
+        eq(customerReviews.organizationId, orgId),
+        eq(customerReviews.entityId, entityId),
+      ))
+      .groupBy(customerReviews.rating);
+
+    const distribution: Record<number, number> = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+    let totalCount = 0;
+    let totalSum = 0;
+    for (const row of rows) {
+      distribution[row.rating] = row.count;
+      totalCount += row.count;
+      totalSum += row.rating * row.count;
+    }
+    const averageRating = totalCount > 0 ? Math.round((totalSum / totalCount) * 100) / 100 : 0;
+    return Ok({ averageRating, totalCount, distribution });
+  }
+
+  async approve(orgId: string, id: string): Promise<PluginResult<Review>> {
+    const rows = await this.db.update(customerReviews)
+      .set({ status: "approved", isPublished: true, updatedAt: new Date() })
+      .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.id, id)))
+      .returning();
+    if (rows.length === 0) return Err("Review not found");
+    return Ok(rows[0]!);
+  }
+
+  async reject(orgId: string, id: string): Promise<PluginResult<Review>> {
+    const rows = await this.db.update(customerReviews)
+      .set({ status: "rejected", isPublished: false, updatedAt: new Date() })
+      .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.id, id)))
+      .returning();
+    if (rows.length === 0) return Err("Review not found");
+    return Ok(rows[0]!);
+  }
+
+  async reply(orgId: string, id: string, response: string, responseBy: string): Promise<PluginResult<Review>> {
+    const rows = await this.db.update(customerReviews)
+      .set({ response, responseBy, responseAt: new Date(), updatedAt: new Date() })
+      .where(and(eq(customerReviews.organizationId, orgId), eq(customerReviews.id, id)))
+      .returning();
+    if (rows.length === 0) return Err("Review not found");
+    return Ok(rows[0]!);
+  }
+
+  async listByCustomer(orgId: string, customerId: string): Promise<PluginResult<Review[]>> {
+    const rows = await this.db.select().from(customerReviews)
+      .where(and(
+        eq(customerReviews.organizationId, orgId),
+        eq(customerReviews.customerId, customerId),
+      ));
+    return Ok(rows);
+  }
+}

package/src/types.ts

@@ -0,0 +1,5 @@
+import type { customerReviews } from "./schema.js";
+
+export type { PluginDb as Db } from "@porulle/core";
+export type Review = typeof customerReviews.$inferSelect;
+export type ReviewInsert = typeof customerReviews.$inferInsert;