@core / reviews

1.0.1 ▾

1.0.1

verifiedMIT

GitHub

Product reviews on @core/comments: verified purchases, photos, labeled imported reviews, ratings and review requests

Code5 filesContext~540 tokensscan passed

~540 tokens→ src/lib/reviews/AGENTS.md→ .cursor/rules/genpm-core-reviews.mdc

This is exactly what your AI reads when it works in src/lib/reviews. Nothing else is added to its context.

@core/reviews — rules for AI agents

Purpose

Product reviews built on @core/comments (no duplicate comment system): a review is a comment on product/<id> with a 1–5 rating, plus review_meta (verified purchase, photos from @core/media, source) and review_stats per product. "Verified" means the signed-in author has a paid and shipped order with that product (by user id or their account's verified email); guest reviews are never verified, so the response never reveals whether an email bought. Imported reviews are always labeled with their source and never verified. Asks customers for a review N days after delivery.

Map

index.ts — public API: postReview, listReviews, productRating, moderateReview, importReviews, verifiedOrder.
reviews.ts — logic, stats and the reviews.request job (scheduled from the order delivered event on import).

Integration

Requires @core/comments (moderation, anti-spam) and @core/orders. Env: optional REVIEW_REQUEST_DELAY_DAYS (default 7, -1 disables), SITE_URL, EMAIL_FROM.
Migrations as in src/lib/db/AGENTS.md; import this module at startup.
Product page: productRating(id) for stars and JSON-LD (jsonLd.product({ rating }) from @core/seo), listReviews(id, { page, rating, sort }) for the list; show a "Verified purchase" badge and, for imported ones, "Imported from <source>".
Review form → postReview({ productId, rating, body, user | guest, photos }, { headers, fields }) with @core/antispam fields.
Moderate in the comments admin (filter entityType=product) and call moderateReview so stats update.
Verify: a buyer's review shows as verified after approval and the product rating changes.

Conventions

Explain on the page how reviews are checked (EU Omnibus Directive): verified = confirmed order.
Show all approved reviews, including negative ones; sort options must not hide them by default.

Don't

Don't write, generate or buy fake reviews, and don't mark imported reviews as verified.
Don't put aggregateRating in JSON-LD when there are no approved reviews.
Don't offer rewards conditioned on a positive review.

# @core/reviews — rules for AI agents

## Purpose
Product reviews built on @core/comments (no duplicate comment system): a review is a comment on `product/<id>` with a
1–5 rating, plus `review_meta` (verified purchase, photos from @core/media, source) and `review_stats` per product.
"Verified" means the signed-in author has a paid and shipped order with that product (by user id or their account's
verified email); guest reviews are never verified, so the response never reveals whether an email bought. Imported reviews are always labeled with
their source and never verified. Asks customers for a review N days after delivery.

## Map
- `index.ts` — public API: `postReview`, `listReviews`, `productRating`, `moderateReview`, `importReviews`, `verifiedOrder`.
- `reviews.ts` — logic, stats and the `reviews.request` job (scheduled from the order `delivered` event on import).

## Integration
1. Requires @core/comments (moderation, anti-spam) and @core/orders. Env: optional `REVIEW_REQUEST_DELAY_DAYS` (default 7, `-1` disables), `SITE_URL`, `EMAIL_FROM`.
2. Migrations as in `src/lib/db/AGENTS.md`; import this module at startup.
3. Product page: `productRating(id)` for stars and JSON-LD (`jsonLd.product({ rating })` from @core/seo), `listReviews(id, { page, rating, sort })`
   for the list; show a "Verified purchase" badge and, for imported ones, "Imported from <source>".
4. Review form → `postReview({ productId, rating, body, user | guest, photos }, { headers, fields })` with @core/antispam fields.
5. Moderate in the comments admin (filter `entityType=product`) and call `moderateReview` so stats update.
6. Verify: a buyer's review shows as verified after approval and the product rating changes.

## Conventions
- Explain on the page how reviews are checked (EU Omnibus Directive): verified = confirmed order.
- Show all approved reviews, including negative ones; sort options must not hide them by default.

## Don't
- Don't write, generate or buy fake reviews, and don't mark imported reviews as verified.
- Don't put `aggregateRating` in JSON-LD when there are no approved reviews.
- Don't offer rewards conditioned on a positive review.

The exact tree that will be injected, after .genpmignore. Pinned to

src/lib/reviews/schema.tsread-only · 9c40b7a

// Tablas de @core/reviews. Las reseñas son comentarios (@core/comments) con valoración; aquí solo sus datos extra.
import { boolean, integer, jsonb, pgTable, text } from 'drizzle-orm/pg-core';
import { comments } from '../comments/index.ts';
import { timestamps } from '../db/index.ts';

export const reviewMeta = pgTable('review_meta', {
  commentId: text('comment_id')
    .primaryKey()
    .references(() => comments.id, { onDelete: 'cascade' }),
  productId: text('product_id').notNull(),
  /** Compra comprobada: el autor tiene un pedido pagado y enviado con este producto. */
  verified: boolean('verified').notNull().default(false),
  orderId: text('order_id'),
  /** `site` o el origen de una reseña importada (`aliexpress`, `trustpilot`…), que se muestra siempre. */
  source: text('source').notNull().default('site'),
  photos: jsonb('photos').$type<string[]>().notNull().default([]),
  ...timestamps,
});

/** Agregado por producto (se recalcula al publicar o moderar). `average` × 100. */
export const reviewStats = pgTable('review_stats', {
  productId: text('product_id').primaryKey(),
  count: integer('count').notNull().default(0),
  average: integer('average').notNull().default(0),
  histogram: jsonb('histogram').$type<[number, number, number, number, number]>().notNull().default([0, 0, 0, 0, 0]),
  ...timestamps,
});