@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:runThe 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.