brainerce 1.23.14 → 1.25.0

package/README.md

@@ -48,6 +48,7 @@ Every Brainerce storefront must include **all mandatory features** below. Featur
 | Account area (profile + order history)                  | `client.getMyProfile()`, `client.getMyOrders()`                                                               | ✅          |
 | Global header: cart count + search autocomplete         | `client.getCart()`, `client.getSearchSuggestions(query)`                                                      | ✅          |
 | Discount banners + product badges                       | `client.getDiscountBanners()`, `client.getProductDiscountBadge(productId)`                                    | ✅          |
+| Product reviews on PDP + JSON-LD aggregateRating        | `client.listProductReviews(id)`, `client.submitProductReview(id, …)`                                          | ✅          |
 | Multi-language + RTL (when i18n enabled)                | `client.setLocale()`                                                                                          | conditional |
 
 ---

package/dist/index.d.mts

@@ -323,9 +323,55 @@ interface Product {
      * (`getProductBySlug`, `getProductById`); omitted from list responses.
      */
     modifierGroups?: ModifierGroup[];
+    /** Average rating across visible reviews (0 when reviewCount is 0). */
+    avgRating?: number;
+    /** Count of visible reviews (non-hidden). */
+    reviewCount?: number;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Product review submitted by a customer.
+ * Reviews publish immediately (no PENDING state). Merchants hide via the admin
+ * surface — hiddenAt is null for visible reviews.
+ */
+interface ProductReview {
+    id: string;
+    productId: string;
+    authorName: string;
+    rating: number;
+    body: string | null;
+    verifiedPurchase: boolean;
+    /** Only present in admin responses; null on storefront responses. */
+    hiddenAt?: string | null;
+    createdAt: string;
+}
+/** Admin-mode review with full PII. Returned by `client.adminReviews.*`. */
+interface ProductReviewAdmin extends ProductReview {
+    customerId: string | null;
+    authorEmail: string | null;
+    orderId: string | null;
+    updatedAt: string;
+}
+/**
+ * Body for customer-authenticated submit / update.
+ * Author name + email are derived server-side from the customer profile.
+ */
+interface WriteProductReviewInput {
+    rating: number;
+    body?: string;
+}
+/**
+ * Returned by `client.getMyProductReview(productId)`. Tells the storefront which
+ * UI to render: sign-in / not-eligible / submit / edit.
+ */
+interface MyProductReview {
+    eligible: boolean;
+    /** Machine-readable reason when not eligible. null when eligible=true. */
+    reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found' | null;
+    /** The customer's existing review for this product, or null. */
+    myReview: ProductReview | null;
+}
 interface ProductImage {
     url: string;
     position?: number;
@@ -6081,6 +6127,79 @@ declare class BrainerceClient {
      * ```
      */
     getProductRecommendations(productId: string, type?: ProductRelationType): Promise<ProductRecommendationsResponse>;
+    /**
+     * List visible reviews for a product (storefront / sales-channel modes).
+     * Reviews that the merchant has hidden are excluded.
+     *
+     * @example
+     * ```typescript
+     * const { data, meta } = await client.listProductReviews('prod_123', { page: 1, limit: 20 });
+     * data.forEach(r => console.log(r.rating, r.body, r.verifiedPurchase));
+     * ```
+     */
+    listProductReviews(productId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<ProductReview>>;
+    /**
+     * Get the current customer's review state for a product (storefront / sales-channel modes).
+     * Requires a customer token (`setCustomerToken(...)` after login).
+     *
+     * Returns whether the customer is *eligible* to review (only purchasers are),
+     * and their existing review for this product if any.
+     *
+     * @example
+     * ```typescript
+     * const { eligible, reason, myReview } = await client.getMyProductReview('prod_123');
+     * if (!eligible) showMessage(reason); // 'no_eligible_order' | 'reviews_disabled' | …
+     * else if (myReview) renderEditForm(myReview);
+     * else renderSubmitForm();
+     * ```
+     */
+    getMyProductReview(productId: string): Promise<MyProductReview>;
+    /**
+     * Submit a customer review for a product (storefront / sales-channel modes).
+     * Requires customer authentication AND that the customer has purchased the
+     * product (SHIPPED for physical, PAID for downloadable).
+     *
+     * 403 `no_eligible_order` if the customer didn't purchase the product.
+     * 409 `Conflict` if they already submitted a review (use `updateMyProductReview` instead).
+     *
+     * Author name + email are derived server-side from the customer profile.
+     *
+     * @example
+     * ```typescript
+     * const review = await client.submitProductReview('prod_123', {
+     *   rating: 5,
+     *   body: 'Loved it!',
+     * });
+     * ```
+     */
+    submitProductReview(productId: string, input: WriteProductReviewInput): Promise<ProductReview>;
+    /**
+     * Edit your own review on a product (storefront / sales-channel modes).
+     * Only updates rating + body; the author name/email and verifiedPurchase flag
+     * are preserved from the original submit.
+     */
+    updateMyProductReview(productId: string, input: WriteProductReviewInput): Promise<ProductReview>;
+    /**
+     * Delete your own review on a product (storefront / sales-channel modes).
+     * After deletion the customer is free to submit a new review (subject to eligibility).
+     */
+    deleteMyProductReview(productId: string): Promise<void>;
+    /**
+     * Admin: list all reviews for a product (incl. hidden). Requires API key with `reviews:read`.
+     */
+    adminListProductReviews(productId: string, params?: {
+        storeId?: string;
+        page?: number;
+        limit?: number;
+        visibility?: 'visible' | 'hidden' | 'all';
+    }): Promise<PaginatedResponse<ProductReviewAdmin>>;
+    /** Admin: hide a review (sets hiddenAt). */
+    hideProductReview(reviewId: string, storeId?: string): Promise<ProductReviewAdmin>;
+    /** Admin: unhide a previously hidden review. */
+    showProductReview(reviewId: string, storeId?: string): Promise<ProductReviewAdmin>;
     /**
      * Get cross-sell recommendations based on cart contents.
      * Returns products that complement items already in the cart.

package/dist/index.d.ts

@@ -323,9 +323,55 @@ interface Product {
      * (`getProductBySlug`, `getProductById`); omitted from list responses.
      */
     modifierGroups?: ModifierGroup[];
+    /** Average rating across visible reviews (0 when reviewCount is 0). */
+    avgRating?: number;
+    /** Count of visible reviews (non-hidden). */
+    reviewCount?: number;
     createdAt: string;
     updatedAt: string;
 }
+/**
+ * Product review submitted by a customer.
+ * Reviews publish immediately (no PENDING state). Merchants hide via the admin
+ * surface — hiddenAt is null for visible reviews.
+ */
+interface ProductReview {
+    id: string;
+    productId: string;
+    authorName: string;
+    rating: number;
+    body: string | null;
+    verifiedPurchase: boolean;
+    /** Only present in admin responses; null on storefront responses. */
+    hiddenAt?: string | null;
+    createdAt: string;
+}
+/** Admin-mode review with full PII. Returned by `client.adminReviews.*`. */
+interface ProductReviewAdmin extends ProductReview {
+    customerId: string | null;
+    authorEmail: string | null;
+    orderId: string | null;
+    updatedAt: string;
+}
+/**
+ * Body for customer-authenticated submit / update.
+ * Author name + email are derived server-side from the customer profile.
+ */
+interface WriteProductReviewInput {
+    rating: number;
+    body?: string;
+}
+/**
+ * Returned by `client.getMyProductReview(productId)`. Tells the storefront which
+ * UI to render: sign-in / not-eligible / submit / edit.
+ */
+interface MyProductReview {
+    eligible: boolean;
+    /** Machine-readable reason when not eligible. null when eligible=true. */
+    reason: 'no_eligible_order' | 'reviews_disabled' | 'product_not_found' | null;
+    /** The customer's existing review for this product, or null. */
+    myReview: ProductReview | null;
+}
 interface ProductImage {
     url: string;
     position?: number;
@@ -6081,6 +6127,79 @@ declare class BrainerceClient {
      * ```
      */
     getProductRecommendations(productId: string, type?: ProductRelationType): Promise<ProductRecommendationsResponse>;
+    /**
+     * List visible reviews for a product (storefront / sales-channel modes).
+     * Reviews that the merchant has hidden are excluded.
+     *
+     * @example
+     * ```typescript
+     * const { data, meta } = await client.listProductReviews('prod_123', { page: 1, limit: 20 });
+     * data.forEach(r => console.log(r.rating, r.body, r.verifiedPurchase));
+     * ```
+     */
+    listProductReviews(productId: string, params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<ProductReview>>;
+    /**
+     * Get the current customer's review state for a product (storefront / sales-channel modes).
+     * Requires a customer token (`setCustomerToken(...)` after login).
+     *
+     * Returns whether the customer is *eligible* to review (only purchasers are),
+     * and their existing review for this product if any.
+     *
+     * @example
+     * ```typescript
+     * const { eligible, reason, myReview } = await client.getMyProductReview('prod_123');
+     * if (!eligible) showMessage(reason); // 'no_eligible_order' | 'reviews_disabled' | …
+     * else if (myReview) renderEditForm(myReview);
+     * else renderSubmitForm();
+     * ```
+     */
+    getMyProductReview(productId: string): Promise<MyProductReview>;
+    /**
+     * Submit a customer review for a product (storefront / sales-channel modes).
+     * Requires customer authentication AND that the customer has purchased the
+     * product (SHIPPED for physical, PAID for downloadable).
+     *
+     * 403 `no_eligible_order` if the customer didn't purchase the product.
+     * 409 `Conflict` if they already submitted a review (use `updateMyProductReview` instead).
+     *
+     * Author name + email are derived server-side from the customer profile.
+     *
+     * @example
+     * ```typescript
+     * const review = await client.submitProductReview('prod_123', {
+     *   rating: 5,
+     *   body: 'Loved it!',
+     * });
+     * ```
+     */
+    submitProductReview(productId: string, input: WriteProductReviewInput): Promise<ProductReview>;
+    /**
+     * Edit your own review on a product (storefront / sales-channel modes).
+     * Only updates rating + body; the author name/email and verifiedPurchase flag
+     * are preserved from the original submit.
+     */
+    updateMyProductReview(productId: string, input: WriteProductReviewInput): Promise<ProductReview>;
+    /**
+     * Delete your own review on a product (storefront / sales-channel modes).
+     * After deletion the customer is free to submit a new review (subject to eligibility).
+     */
+    deleteMyProductReview(productId: string): Promise<void>;
+    /**
+     * Admin: list all reviews for a product (incl. hidden). Requires API key with `reviews:read`.
+     */
+    adminListProductReviews(productId: string, params?: {
+        storeId?: string;
+        page?: number;
+        limit?: number;
+        visibility?: 'visible' | 'hidden' | 'all';
+    }): Promise<PaginatedResponse<ProductReviewAdmin>>;
+    /** Admin: hide a review (sets hiddenAt). */
+    hideProductReview(reviewId: string, storeId?: string): Promise<ProductReviewAdmin>;
+    /** Admin: unhide a previously hidden review. */
+    showProductReview(reviewId: string, storeId?: string): Promise<ProductReviewAdmin>;
     /**
      * Get cross-sell recommendations based on cart contents.
      * Returns products that complement items already in the cart.

package/dist/index.js

@@ -2790,6 +2790,172 @@ var BrainerceClient = class {
       400
     );
   }
+  // ===================================================
+  // Product Reviews
+  // ===================================================
+  /**
+   * List visible reviews for a product (storefront / sales-channel modes).
+   * Reviews that the merchant has hidden are excluded.
+   *
+   * @example
+   * ```typescript
+   * const { data, meta } = await client.listProductReviews('prod_123', { page: 1, limit: 20 });
+   * data.forEach(r => console.log(r.rating, r.body, r.verifiedPurchase));
+   * ```
+   */
+  async listProductReviews(productId, params) {
+    const queryParams = {};
+    if (params?.page) queryParams.page = params.page;
+    if (params?.limit) queryParams.limit = params.limit;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/${productId}/reviews`,
+        void 0,
+        queryParams
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "GET",
+        `/products/${productId}/reviews`,
+        void 0,
+        queryParams
+      );
+    }
+    throw new BrainerceError("listProductReviews() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get the current customer's review state for a product (storefront / sales-channel modes).
+   * Requires a customer token (`setCustomerToken(...)` after login).
+   *
+   * Returns whether the customer is *eligible* to review (only purchasers are),
+   * and their existing review for this product if any.
+   *
+   * @example
+   * ```typescript
+   * const { eligible, reason, myReview } = await client.getMyProductReview('prod_123');
+   * if (!eligible) showMessage(reason); // 'no_eligible_order' | 'reviews_disabled' | …
+   * else if (myReview) renderEditForm(myReview);
+   * else renderSubmitForm();
+   * ```
+   */
+  async getMyProductReview(productId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/products/${productId}/reviews/me`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/products/${productId}/reviews/me`);
+    }
+    throw new BrainerceError("getMyProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Submit a customer review for a product (storefront / sales-channel modes).
+   * Requires customer authentication AND that the customer has purchased the
+   * product (SHIPPED for physical, PAID for downloadable).
+   *
+   * 403 `no_eligible_order` if the customer didn't purchase the product.
+   * 409 `Conflict` if they already submitted a review (use `updateMyProductReview` instead).
+   *
+   * Author name + email are derived server-side from the customer profile.
+   *
+   * @example
+   * ```typescript
+   * const review = await client.submitProductReview('prod_123', {
+   *   rating: 5,
+   *   body: 'Loved it!',
+   * });
+   * ```
+   */
+  async submitProductReview(productId, input) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", `/products/${productId}/reviews`, input);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", `/products/${productId}/reviews`, input);
+    }
+    throw new BrainerceError("submitProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Edit your own review on a product (storefront / sales-channel modes).
+   * Only updates rating + body; the author name/email and verifiedPurchase flag
+   * are preserved from the original submit.
+   */
+  async updateMyProductReview(productId, input) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "PATCH",
+        `/products/${productId}/reviews/me`,
+        input
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "PATCH",
+        `/products/${productId}/reviews/me`,
+        input
+      );
+    }
+    throw new BrainerceError("updateMyProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Delete your own review on a product (storefront / sales-channel modes).
+   * After deletion the customer is free to submit a new review (subject to eligibility).
+   */
+  async deleteMyProductReview(productId) {
+    if (this.isVibeCodedMode()) {
+      await this.vibeCodedRequest("DELETE", `/products/${productId}/reviews/me`);
+      return;
+    }
+    if (this.storeId && !this.apiKey) {
+      await this.storefrontRequest("DELETE", `/products/${productId}/reviews/me`);
+      return;
+    }
+    throw new BrainerceError("deleteMyProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Admin: list all reviews for a product (incl. hidden). Requires API key with `reviews:read`.
+   */
+  async adminListProductReviews(productId, params) {
+    if (!this.apiKey) {
+      throw new BrainerceError("adminListProductReviews() requires admin (API key) mode", 400);
+    }
+    const queryParams = {};
+    if (params?.storeId) queryParams.storeId = params.storeId;
+    if (params?.page) queryParams.page = params.page;
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.visibility) queryParams.visibility = params.visibility;
+    return this.adminRequest(
+      "GET",
+      `/api/v1/products/${productId}/reviews`,
+      void 0,
+      queryParams
+    );
+  }
+  /** Admin: hide a review (sets hiddenAt). */
+  async hideProductReview(reviewId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("hideProductReview() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/reviews/${reviewId}/hide`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
+  /** Admin: unhide a previously hidden review. */
+  async showProductReview(reviewId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("showProductReview() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/reviews/${reviewId}/show`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
   /**
    * Get cross-sell recommendations based on cart contents.
    * Returns products that complement items already in the cart.

package/dist/index.mjs

@@ -2727,6 +2727,172 @@ var BrainerceClient = class {
       400
     );
   }
+  // ===================================================
+  // Product Reviews
+  // ===================================================
+  /**
+   * List visible reviews for a product (storefront / sales-channel modes).
+   * Reviews that the merchant has hidden are excluded.
+   *
+   * @example
+   * ```typescript
+   * const { data, meta } = await client.listProductReviews('prod_123', { page: 1, limit: 20 });
+   * data.forEach(r => console.log(r.rating, r.body, r.verifiedPurchase));
+   * ```
+   */
+  async listProductReviews(productId, params) {
+    const queryParams = {};
+    if (params?.page) queryParams.page = params.page;
+    if (params?.limit) queryParams.limit = params.limit;
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "GET",
+        `/products/${productId}/reviews`,
+        void 0,
+        queryParams
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "GET",
+        `/products/${productId}/reviews`,
+        void 0,
+        queryParams
+      );
+    }
+    throw new BrainerceError("listProductReviews() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Get the current customer's review state for a product (storefront / sales-channel modes).
+   * Requires a customer token (`setCustomerToken(...)` after login).
+   *
+   * Returns whether the customer is *eligible* to review (only purchasers are),
+   * and their existing review for this product if any.
+   *
+   * @example
+   * ```typescript
+   * const { eligible, reason, myReview } = await client.getMyProductReview('prod_123');
+   * if (!eligible) showMessage(reason); // 'no_eligible_order' | 'reviews_disabled' | …
+   * else if (myReview) renderEditForm(myReview);
+   * else renderSubmitForm();
+   * ```
+   */
+  async getMyProductReview(productId) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("GET", `/products/${productId}/reviews/me`);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("GET", `/products/${productId}/reviews/me`);
+    }
+    throw new BrainerceError("getMyProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Submit a customer review for a product (storefront / sales-channel modes).
+   * Requires customer authentication AND that the customer has purchased the
+   * product (SHIPPED for physical, PAID for downloadable).
+   *
+   * 403 `no_eligible_order` if the customer didn't purchase the product.
+   * 409 `Conflict` if they already submitted a review (use `updateMyProductReview` instead).
+   *
+   * Author name + email are derived server-side from the customer profile.
+   *
+   * @example
+   * ```typescript
+   * const review = await client.submitProductReview('prod_123', {
+   *   rating: 5,
+   *   body: 'Loved it!',
+   * });
+   * ```
+   */
+  async submitProductReview(productId, input) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest("POST", `/products/${productId}/reviews`, input);
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest("POST", `/products/${productId}/reviews`, input);
+    }
+    throw new BrainerceError("submitProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Edit your own review on a product (storefront / sales-channel modes).
+   * Only updates rating + body; the author name/email and verifiedPurchase flag
+   * are preserved from the original submit.
+   */
+  async updateMyProductReview(productId, input) {
+    if (this.isVibeCodedMode()) {
+      return this.vibeCodedRequest(
+        "PATCH",
+        `/products/${productId}/reviews/me`,
+        input
+      );
+    }
+    if (this.storeId && !this.apiKey) {
+      return this.storefrontRequest(
+        "PATCH",
+        `/products/${productId}/reviews/me`,
+        input
+      );
+    }
+    throw new BrainerceError("updateMyProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Delete your own review on a product (storefront / sales-channel modes).
+   * After deletion the customer is free to submit a new review (subject to eligibility).
+   */
+  async deleteMyProductReview(productId) {
+    if (this.isVibeCodedMode()) {
+      await this.vibeCodedRequest("DELETE", `/products/${productId}/reviews/me`);
+      return;
+    }
+    if (this.storeId && !this.apiKey) {
+      await this.storefrontRequest("DELETE", `/products/${productId}/reviews/me`);
+      return;
+    }
+    throw new BrainerceError("deleteMyProductReview() requires vibe-coded or storefront mode", 400);
+  }
+  /**
+   * Admin: list all reviews for a product (incl. hidden). Requires API key with `reviews:read`.
+   */
+  async adminListProductReviews(productId, params) {
+    if (!this.apiKey) {
+      throw new BrainerceError("adminListProductReviews() requires admin (API key) mode", 400);
+    }
+    const queryParams = {};
+    if (params?.storeId) queryParams.storeId = params.storeId;
+    if (params?.page) queryParams.page = params.page;
+    if (params?.limit) queryParams.limit = params.limit;
+    if (params?.visibility) queryParams.visibility = params.visibility;
+    return this.adminRequest(
+      "GET",
+      `/api/v1/products/${productId}/reviews`,
+      void 0,
+      queryParams
+    );
+  }
+  /** Admin: hide a review (sets hiddenAt). */
+  async hideProductReview(reviewId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("hideProductReview() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/reviews/${reviewId}/hide`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
+  /** Admin: unhide a previously hidden review. */
+  async showProductReview(reviewId, storeId) {
+    if (!this.apiKey) {
+      throw new BrainerceError("showProductReview() requires admin (API key) mode", 400);
+    }
+    return this.adminRequest(
+      "PATCH",
+      `/api/v1/reviews/${reviewId}/show`,
+      void 0,
+      storeId ? { storeId } : void 0
+    );
+  }
   /**
    * Get cross-sell recommendations based on cart contents.
    * Returns products that complement items already in the cart.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.23.14",
+  "version": "1.25.0",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",