Search Module — Storefront

{
  "data": { /* products + facets, or suggestions + products */ },
  "metadata": { /* on /store/product-search only */ },
  "message": "Success",
  "statusCode": 200
}

type ProductSearchVariant = {
  id: string;
  sku: string | null;
  price: number | null;
  specialPrice: number | null;
  specialPriceStartDate: string | null;     // ISO
  specialPriceEndDate: string | null;       // ISO
  inventoryQuantity: number;               // on-hand − reserved − safety stock
  isOrderable: boolean;                    // true even at 0 for backorder/untracked
  minQuantityPerCart: number | null;
  maxQuantityPerCart: number | null;
  thumbnail: string | null;
  images: string[];

  /** Computed at response time from the fields above. */
  originalPrice: number | null;             // = price
  currentPrice: number | null;              // = specialPriceActive ?? price
  specialPriceActive: number | null;        // specialPrice if window currently includes now, else null
};

type ProductSearchProduct = {
  id: string;
  title: string;
  subtitle: string | null;
  description: string | null;
  slug: string;                              // (beautybarn called this "handle")
  thumbnail: string | null;
  images: string[];
  /** min/max of currentPrice across in-stock variants; null when no variant is priced. */
  priceStart: number | null;
  priceEnd: number | null;
  brand: { id: string; slug: string; name: string } | null;
  inStock: boolean;                        // any variant is orderable
  hasActiveSpecial: boolean;
  /** Average star rating across approved, non-spam reviews and the count
   *  backing it. `average` is 0 and `count` is 0 when there are no reviews. */
  rating: { average: number; count: number };
  variants: ProductSearchVariant[];
  /** Present ONLY when the request passes `withReviews=true`. The product's
   *  newest approved, non-spam reviews (up to 10), newest first. Omitted
   *  (key absent) otherwise. */
  reviews?: ProductSearchReview[];
};

type ProductSearchReview = {
  id: string;
  reviewerName: string | null;   // display name only — customer name or admin-entered first+last
  title: string | null;
  content: string;
  stars: number;                 // 1-5
  recommended: boolean | null;
  isVerifiedPurchase: boolean;
  createdAt: string;             // ISO 8601
  images: string[];              // image URLs, ordered
};

type ProductSearchBrandFacet = {
  id: string;
  slug: string;
  name: string;
  productCount: number;
};

type ProductSearchIngredientFacet = {
  id: string;
  slug: string;
  name: string;
  productCount: number;
};

type ProductSearchAttributeFacet = {
  code: string;
  title: string;
  values: Array<{ value: string; productCount: number }>;
};

type ProductSearchRatingFacet = {
  rating: number;       // 1-5
  productCount: number; // cumulative — products with rating.average >= this value
};

{
  "data": {
    "products": [
      {
        "id": "01J9...",
        "title": "Hydrating Toner",
        "subtitle": "200ml",
        "description": "...",
        "slug": "hydrating-toner",
        "thumbnail": "https://cdn.example/p/hydrating-toner.jpg",
        "images": ["https://cdn.example/p/hydrating-toner-2.jpg"],
        "priceStart": 49900,
        "priceEnd": 79900,
        "brand": { "id": "01J9...", "slug": "skin-co", "name": "Skin Co" },
        "inStock": true,
        "hasActiveSpecial": false,
        "rating": { "average": 4.5, "count": 12 },
        "variants": [ /* ProductSearchVariant[] */ ]
      }
    ],
    "brands": [ { "id": "01J9...", "slug": "skin-co", "name": "Skin Co", "productCount": 12 } ],
    "ingredients": [ { "id": "01J9...", "slug": "niacinamide", "name": "Niacinamide", "productCount": 8 } ],
    "attributes": [
      { "code": "size", "title": "Size", "values": [ { "value": "200ml", "productCount": 5 } ] }
    ],
    "ratings": [
      { "rating": 5, "productCount": 18 },
      { "rating": 4, "productCount": 30 },
      { "rating": 3, "productCount": 35 },
      { "rating": 2, "productCount": 36 },
      { "rating": 1, "productCount": 36 }
    ]
  },
  "metadata": {
    "total": 42,
    "items": 20,
    "perPage": 20,
    "currentPage": 1,
    "lastPage": 3
  },
  "message": "Success",
  "statusCode": 200
}

{
  "data": {
    "suggestions": ["Hydrating Toner", "Hydrating Serum"],
    "products": [ /* ProductSearchProduct[] */ ]
  },
  "message": "Success",
  "statusCode": 200
}