types.ts

/**
 * The platform a review originated from. Featurable currently sources reviews
 * from Google Business Profile, but the field is left open for future platforms.
 */
export type ReviewPlatform = 'google' | (string & {});

/** The author of a review. */
export interface ReviewAuthor {
  /** The reviewer's display name. */
  name: string;
  /** URL of the reviewer's avatar, or `null` when unavailable. */
  avatarUrl: string | null;
  /** URL of the reviewer's public profile, or `null` when unavailable. */
  profileUrl: string | null;
}

/** A star rating and its maximum possible value. */
export interface ReviewRating {
  /** The rating given by the reviewer. */
  value: number;
  /** The maximum rating on the scale (typically `5`). */
  max: number;
}

/** A single review returned by the Featurable API. */
export interface Review {
  /** Unique identifier for the review. */
  id: string;
  /** The platform the review originated from. */
  platform: ReviewPlatform;
  /** The review's author. */
  author: ReviewAuthor;
  /** The review title, or `null` when the platform has no title. */
  title: string | null;
  /** The review body text (translated to the widget language when applicable). */
  text: string;
  /** The original, untranslated review text, or `null`. */
  originalText: string | null;
  /** BCP-47 language code of {@link Review.text}. */
  languageCode: string;
  /** The star rating. */
  rating: ReviewRating;
  /** ISO-8601 timestamp of when the review was published on the source platform. */
  publishedAt: string;
  /** ISO-8601 timestamp of when Featurable first ingested the review. */
  createdAt: string;
  /** ISO-8601 timestamp of when the review was last updated. */
  updatedAt: string;
  /** ISO-8601 timestamp of the last sync with the source platform, or `null`. */
  lastSyncedAt: string | null;
  /** Platform-specific metadata. */
  metadata: Record<string, unknown>;
  /** A canonical URL for the review, or `null`. */
  url: string | null;
}

/** Presentation configuration for a widget. */
export interface WidgetConfig {
  layout: string;
  language: string;
  name: string | null;
  color_scheme: string;
  name_display: string;
  title: string;
  show_title: boolean;
  carousel_autoplay: boolean;
  carousel_speed: number;
  max_characters: number;
  date_display: string;
  schema: boolean;
  schema_type: string | null;
  schema_sub_type: string | null;
  schema_sub_sub_type: string | null;
  summary: boolean;
  summary_review_button: boolean;
  show_profile_pictures: boolean;
  custom_css: string;
  allowed_domains: string[];
}

/** Aggregate review statistics for the widget's Google Business Profile location. */
export interface GbpLocationSummary {
  /** Total number of reviews on the source location. */
  reviewsCount: number;
  /** The location's average rating. */
  rating: number;
  /** A URL prospective reviewers can use to leave a review. */
  writeAReviewUri: string;
}

/** A Featurable widget together with its reviews and configuration. */
export interface Widget {
  /** The widget's unique identifier. */
  uuid: string;
  /** Presentation configuration. */
  config: WidgetConfig;
  /** The reviews attached to the widget. */
  reviews: Review[];
  /** Whether the returned reviews are placeholder/example content. */
  isExampleReviews: boolean;
  /** The UUID of the linked Google Business Profile location. */
  gbpLocationUuid: string;
  /** Aggregate statistics for the linked location. */
  gbpLocationSummary: GbpLocationSummary;
  /** Whether Featurable branding should be shown. */
  showBranding: boolean;
}

/** The raw envelope returned by `GET /widgets/{uuid}`. */
export interface WidgetResponse {
  success: boolean;
  widget: Widget;
}