brainerce 1.23.14 → 1.24.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,42 @@ 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;
+}
+interface SubmitProductReviewInput {
+    authorName: string;
+    authorEmail?: string;
+    rating: number;
+    body?: string;
+}
 interface ProductImage {
     url: string;
     position?: number;
@@ -6081,6 +6114,48 @@ 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>>;
+    /**
+     * Submit a customer review for a product (storefront / sales-channel modes).
+     * Publishes immediately. Duplicate submissions from the same email return 409.
+     *
+     * @example
+     * ```typescript
+     * const review = await client.submitProductReview('prod_123', {
+     *   authorName: 'Jane Doe',
+     *   authorEmail: 'jane@example.com',
+     *   rating: 5,
+     *   body: 'Loved it!',
+     * });
+     * ```
+     */
+    submitProductReview(productId: string, input: SubmitProductReviewInput): Promise<ProductReview>;
+    /**
+     * 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,42 @@ 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;
+}
+interface SubmitProductReviewInput {
+    authorName: string;
+    authorEmail?: string;
+    rating: number;
+    body?: string;
+}
 interface ProductImage {
     url: string;
     position?: number;
@@ -6081,6 +6114,48 @@ 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>>;
+    /**
+     * Submit a customer review for a product (storefront / sales-channel modes).
+     * Publishes immediately. Duplicate submissions from the same email return 409.
+     *
+     * @example
+     * ```typescript
+     * const review = await client.submitProductReview('prod_123', {
+     *   authorName: 'Jane Doe',
+     *   authorEmail: 'jane@example.com',
+     *   rating: 5,
+     *   body: 'Loved it!',
+     * });
+     * ```
+     */
+    submitProductReview(productId: string, input: SubmitProductReviewInput): Promise<ProductReview>;
+    /**
+     * 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,107 @@ 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);
+  }
+  /**
+   * Submit a customer review for a product (storefront / sales-channel modes).
+   * Publishes immediately. Duplicate submissions from the same email return 409.
+   *
+   * @example
+   * ```typescript
+   * const review = await client.submitProductReview('prod_123', {
+   *   authorName: 'Jane Doe',
+   *   authorEmail: 'jane@example.com',
+   *   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);
+  }
+  /**
+   * 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,107 @@ 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);
+  }
+  /**
+   * Submit a customer review for a product (storefront / sales-channel modes).
+   * Publishes immediately. Duplicate submissions from the same email return 409.
+   *
+   * @example
+   * ```typescript
+   * const review = await client.submitProductReview('prod_123', {
+   *   authorName: 'Jane Doe',
+   *   authorEmail: 'jane@example.com',
+   *   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);
+  }
+  /**
+   * 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.24.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",