Product reviews

import { createCatalogClient } from '@usethrottle/catalog';

const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
});

// Newest first by default. `rating` keeps only reviews with exactly that
// many stars. Up to 50 a page (10 by default), then follow nextCursor.
const answer = await catalog.reviews.list('ceramic-brake-pads', {
  sort: 'highest',
  limit: 20,
});

if ('redirectTo' in answer) {
  // A renamed product: ask again with the new handle.
} else {
  const { average, count, histogram } = answer.summary;
  console.log(`${average ?? '–'} out of 5 from ${count} reviews`, histogram['5']);

  for (const review of answer.reviews) {
    console.log(review.rating, review.displayName, review.verified, review.reply?.body);
  }

  if (answer.nextCursor) {
    await catalog.reviews.list('ceramic-brake-pads', {
      sort: 'highest',
      limit: 20,
      cursor: answer.nextCursor,
    });
  }
}

import { createCatalogClient, isCatalogError } from '@usethrottle/catalog';

declare const auth: { getAccessToken(): Promise<string | null> };

// Both calls need the signed-in customer's token.
const catalog = createCatalogClient({
  publishableKey: 'pc_pk_your_browser_key',
  customerToken: () => auth.getAccessToken(),
});

const { canReview, reason } = await catalog.reviews.eligibility('ceramic-brake-pads');
if (!canReview) {
  // reviews_disabled, not_signed_in, email_not_verified, already_reviewed
  // or not_verified_buyer: show the matching message instead of the form.
  console.log(reason);
} else {
  try {
    const { review } = await catalog.reviews.submit(
      'ceramic-brake-pads',
      {
        rating: 5,
        title: 'Quiet and clean',
        body: 'No squeal after 2,000 miles.',
        displayName: 'Sam',
      },
      // The same key for a retry of this submission: never a second review.
      { idempotencyKey: crypto.randomUUID() },
    );
    // 'pending' while the store holds new reviews for approval.
    console.log(review.id, review.status);
  } catch (error) {
    if (!isCatalogError(error)) throw error;
    switch (error.code) {
      case 'EMAIL_NOT_VERIFIED':
      case 'NOT_VERIFIED_BUYER':
      case 'PURCHASE_REFUNDED':
      case 'ALREADY_REVIEWED':
        console.log('This review cannot be posted:', error.code);
        break;
      case 'RATE_LIMITED':
      case 'REVIEW_QUEUE_FULL':
      case 'REVIEW_VERIFICATION_UNAVAILABLE':
        console.log(`Try again in ${error.retryAfterSeconds ?? 10} s`);
        break;
      default:
        throw error;
    }
  }
}

import type { StorefrontReviewsAnswer } from '@usethrottle/catalog';

type Review = Extract<StorefrontReviewsAnswer, { reviews: unknown }>['reviews'][number];

// Review text is the shopper's own plain text. Put it in the page as text,
// never as HTML: textContent here, or {review.body} in JSX, which React
// escapes. Never innerHTML or dangerouslySetInnerHTML.
export function renderReview(review: Review): HTMLElement {
  const item = document.createElement('article');
  const title = document.createElement('h3');
  title.textContent = review.title ?? `${review.rating} stars`;
  const body = document.createElement('p');
  body.textContent = review.body;
  const byline = document.createElement('p');
  byline.textContent = `${review.displayName}${review.verified ? ' · Verified buyer' : ''}`;
  item.append(title, body, byline);
  return item;
}