@reviewhub/sdk

Lightweight TypeScript SDK for the ReviewHub API.
Zero dependencies — works in Node.js, browsers, edge runtimes and any JS framework.

Install

npm install @reviewhub/sdk

Quick start

import { ReviewHubClient } from "@reviewhub/sdk";

const client = new ReviewHubClient({
  sellerKey: "pk_your_seller_key",
  apiBaseUrl: "https://myreviewhub.duckdns.org/api", // optional
});

// Fetch reviews for a product
const { data: reviews, meta } = await client.getProductReviews({
  productId: "your-product-id",
  limit: 10,
  sortBy: "createdAt",
  sortOrder: "desc",
});

// Fetch rating summary
const summary = await client.getProductSummary("your-product-id");
console.log(summary.averageRating); // 4.7
console.log(summary.totalReviews);  // 128

Singleton pattern

If you prefer a global instance you can use the init / getClient helpers:

import { init, getProductReviews, getProductSummary } from "@reviewhub/sdk";

// Call once at app startup
init({ sellerKey: "pk_your_seller_key" });

// Then anywhere in your code
const { data } = await getProductReviews({ productId: "abc123" });
const summary = await getProductSummary("abc123");

API reference

new ReviewHubClient(config)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | sellerKey | string | Yes | Your public seller API key (pk_...) | | apiBaseUrl | string | No | API base URL (defaults to https://api.reviewhub.dev/api) |

client.getProductReviews(options)

Returns a paginated list of reviews.

| Option | Type | Default | Description | |--------|------|---------|-------------| | productId | string | — | Product to fetch reviews for | | page | number | 1 | Page number | | limit | number | 10 | Reviews per page | | sortBy | "createdAt" \| "rating" | "createdAt" | Sort field | | sortOrder | "asc" \| "desc" | "desc" | Sort direction |

Response:

{
  data: PublicReview[];
  meta: { page: number; limit: number; total: number; totalPages: number };
}

client.getProductSummary(productId)

Returns the rating summary for a product.

{
  productId: string;
  averageRating: number;      // e.g. 4.7
  totalReviews: number;       // e.g. 128
  ratingDistribution: {       // count per star
    1: number;
    2: number;
    3: number;
    4: number;
    5: number;
  };
}

client.getWidgetConfig()

Returns the seller's widget display configuration (theme, colors, layout preferences).

Types

All types are exported for full TypeScript support:

import type {
  ReviewHubConfig,
  PublicReview,
  ProductReviewSummary,
  PaginatedResponse,
  ReviewsQueryOptions,
  WidgetConfig,
} from "@reviewhub/sdk";

PublicReview

interface PublicReview {
  id: string;
  rating: number;
  comment: string | null;
  customerName: string | null;
  isVerifiedScan: boolean;
  isVerifiedPurchase: boolean;
  createdAt: string;
  voice?: {
    fileUrl: string;
    mimeType: string;
    durationMs: number | null;
  } | null;
  authIdentity?: {
    displayName: string | null;
    photoUrl: string | null;
    provider: string;
  } | null;
}

License

MIT