npm package: @reviewhub/sdk
Description: Lightweight TypeScript SDK for the ReviewHub API — fetch reviews, summaries & widget config from any JS runtime
Latest version: 0.1.0

# @reviewhub/sdk

Lightweight TypeScript SDK for the [ReviewHub](https://myreviewhub.duckdns.org) API.  
Zero dependencies — works in Node.js, browsers, edge runtimes and any JS framework.

## Install

```bash
npm install @reviewhub/sdk
```

## Quick start

```typescript
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:

```typescript
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:**

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

### `client.getProductSummary(productId)`

Returns the rating summary for a product.

```typescript
{
  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:

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

### `PublicReview`

```typescript
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