Skip to content

Wishlists and verified reviews

Configure customer-owned wishlists, delivered-purchase product reviews, moderation, and public rating aggregates.

@adocommercekit/engagement adds default/named wishlists and verified-purchase product reviews without requiring either HTTP API package.

Install, configure, and migrate

Configure core first and use matching exact commerce package versions:

pnpm add @adocommercekit/engagement
node ace configure @adocommercekit/engagement
node ace migration:run

The configurator registers @adocommercekit/engagement/engagement_provider, publishes config/commerce_engagement.ts and validators, and creates a host-owned migration for wishlists, wishlist items, product reviews, and rating aggregates. The migration uses core’s table prefix; the generated config calls defineEngagementConfig({ tablePrefix: commerce.tablePrefix }). Run migrations before resolving these APIs against the database.

Storefront publication requires the existing start/routes/commerce.ts surface; admin publication requires app/services/commerce_admin.ts. Only those available surfaces receive controllers, routes, and preloads. Core-only hosts use EngagementService directly. Configure the optional storefront/admin API first and reconfigure engagement to publish it later. Existing host files are left untouched.

Published application files:

Surface Files
Always config/commerce_engagement.ts, app/validators/commerce_engagement.ts, timestamped database/migrations/*_engagement.ts
Storefront routes present app/controllers/commerce/engagement_controller.ts, start/routes/commerce_engagement.ts
Admin API present app/controllers/commerce_admin/engagement_controller.ts, start/routes/commerce_admin_engagement.ts

The provider registers EngagementService; it does not subscribe to commerce events. Verified-purchase eligibility is queried from persisted delivered shipments at submission.

Public entrypoints

Import Contents
@adocommercekit/engagement Config helper, errors, models, EngagementService, and types
@adocommercekit/engagement/models Wishlist, WishlistItem, and ProductReview
@adocommercekit/engagement/services EngagementService and service types
@adocommercekit/engagement/configure Adonis configure hook
@adocommercekit/engagement/engagement_provider Service provider
@adocommercekit/engagement/upgrade Publication manifest and artifact loader

Customer authentication and ownership

Wishlist operations and review submission require an authenticated host user linked to a commerce customer by Customer.userId. An unauthenticated call fails with E_CUSTOMER_AUTH_REQUIRED (401); a missing customer is not found. Integrate the host auth mechanism so ctx.auth.user is populated; the published controller does not accept a customer ID from request input as authority.

Every wishlist read/mutation checks stored customer ownership. Move-to-cart checks actual persisted cart ownership as well, not a caller-supplied cart snapshot. Public review listing and rating reads need no customer authentication, and review DTOs omit customerId.

Default and named wishlist APIs

createWishlist(customerId, name = 'default', options?) creates or returns the customer’s same named list. Names are trimmed, nonempty, and at most 80 characters. Calling it without a name selects the default list; named lists are otherwise independent.

Use listWishlists(customerId, input?), addItem(customerId, wishlistId, variantId, options?), listItems(customerId, wishlistId, input?), and removeItem(customerId, wishlistId, itemId, options?). Adding the same variant again is idempotent; the variant must exist. Lists return { data, nextCursor }; limits are 1–100 (default 20), and cursors are bound to the customer/list or review filter scope.

moveToCart(customerId, wishlistId, itemId, cart, quantity = 1, options?) adds the variant through core CartService.addLine and removes the wishlist item in the same transaction. If cart validation or recalculation fails, the item remains in the wishlist. This is a move, not a copy and not a promise of checkout availability.

Storefront routes

All paths below use /api/commerce, commerce error middleware, and the engagement rate-limit scope (120 requests per 60 seconds):

Method Path Input / access
GET /wishlists Customer; cursor/limit
POST /wishlists Customer; optional name
GET /wishlists/:listId/items Owner; cursor/limit
POST /wishlists/:listId/items Owner; variantId
DELETE /wishlists/:listId/items/:itemId Owner; returns 204
POST /wishlists/:listId/items/:itemId/cart Owner; cartId, optional quantity; returns cart ID
GET /products/:productId/reviews Public approved reviews; cursor/limit
GET /products/:productId/rating Public count/average
PUT /products/:productId/reviews Customer; rating, title, body

Delivered-purchase reviews and ratings

submitReview(customerId, productId, input, options?) requires a positive-quantity shipment line for that product on the customer’s order with shipment state delivered. Merely placing or paying an order is not verified-purchase eligibility. Ineligible submission throws VerifiedPurchaseRequiredException.

Rating must be an integer from 1–5, title nonempty and at most 120 characters, and body nonempty and at most 5000 characters. Stored title/body are trimmed. A customer has one review per product: resubmission updates that record and resets it to pending, including previously approved reviews. That removes the old rating contribution until moderation approves the new content.

listReviews(productId, input?) returns only approved reviews, includes verifiedPurchase: true, and omits customer IDs. rating(productId) returns { count, average }, computed only from approved reviews; an empty aggregate is { count: 0, average: 0 }. Submission and moderation update aggregates transactionally under a product lock. Pending/rejected content never contributes to public count or average. Treat review title/body as customer-authored text and escape it when rendering.

Admin moderation and auditing

Under /api/commerce/admin:

Method Path Behavior
GET /reviews listModeration({ state?, cursor?, limit? })
PATCH /reviews/:id moderateReview(id, state, options?)

Both routes require admin authentication and commerce.reviews.moderate, plus pre-auth and read/mutation rate-limit tiers. Map that ability in the host’s deny-by-default policy. Moderation accepts pending, approved, or rejected. The published controller commits the review transition, aggregate update, and audit entry in one transaction; safe audit metadata includes the review ID and resulting state. Admin moderation records include customer identity for authorized operators, unlike the public DTO.

Upgrades and publication baselines

@adocommercekit/engagement/upgrade exports engagementUpgradeManifest and loadEngagementUpgradeArtifacts(root?). Version comes from the package manifest. Configuration records baselines only for newly published files in .commercekit/publications; commerce:upgrade uses these for reviewable no-op/update/conflict plans. The root-aware loader filters storefront/admin artifacts when the host lacks those surfaces; calling without a root returns the complete artifact catalog. Review host edits rather than replacing published code wholesale, reconfigure after adding an optional API, and run new migrations before deployment. See operations.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close