npm package: @hellotrust/react
Description: React SDK for displaying HelloTrust testimonials
Author: HelloTrust
Latest version: 0.1.1

# @hellotrust/react

React SDK for displaying HelloTrust testimonials on your website.

## Installation

```bash
npm install @hellotrust/react
# or
yarn add @hellotrust/react
```

## Usage

### Option 1: Using the Hook (Recommended)

```tsx
import { useTestimonials } from '@hellotrust/react';

function TestimonialList() {
  const { testimonials, loading, error } = useTestimonials('your-showcase-id');

  if (loading) return <div>Loading testimonials...</div>;
  if (error) return <div>Error loading testimonials</div>;

  return (
    <div>
      {testimonials.map((testimonial) => (
        <div key={testimonial.id}>
          <p>{testimonial.final_text}</p>
          <p>- {testimonial.provider_name || testimonial.provider_email}</p>
        </div>
      ))}
    </div>
  );
}
```

### Option 2: Using the Component with Render Prop

```tsx
import { Testimonials } from '@hellotrust/react';

function TestimonialList() {
  return (
    <Testimonials showcaseId="your-showcase-id">
      {({ testimonials, loading, error }) => {
        if (loading) return <div>Loading testimonials...</div>;
        if (error) return <div>Error loading testimonials</div>;

        return (
          <div>
            {testimonials.map((testimonial) => (
              <div key={testimonial.id}>
                <p>{testimonial.final_text}</p>
                <p>- {testimonial.provider_name || testimonial.provider_email}</p>
              </div>
            ))}
          </div>
        );
      }}
    </Testimonials>
  );
}
```

## TypeScript

The package includes full TypeScript type definitions:

```typescript
import type { Testimonial, UseTestimonialsResult } from '@hellotrust/react';

interface Testimonial {
  id: string;
  final_text: string;
  provider_email: string;
  provider_name?: string;
  created_at: string;
}

interface UseTestimonialsResult {
  testimonials: Testimonial[];
  loading: boolean;
  error: Error | null;
}
```

## Getting Your Showcase ID

1. Log in to your [HelloTrust dashboard](https://app.hellotrust.io)
2. Navigate to Settings → Showcases
3. Click on the showcase you want to display
4. Copy the showcase ID from the page

## API

### `useTestimonials(showcaseId: string)`

React hook that fetches testimonials from a showcase.

**Parameters:**
- `showcaseId` (string, required): The ID of the showcase to fetch testimonials from

**Returns:** `UseTestimonialsResult`
- `testimonials` (Testimonial[]): Array of testimonials in the showcase order
- `loading` (boolean): True while fetching testimonials
- `error` (Error | null): Error object if request failed, null otherwise

### `<Testimonials />`

React component using the render prop pattern.

**Props:**
- `showcaseId` (string, required): The ID of the showcase to fetch testimonials from
- `children` (function, required): Render function that receives `UseTestimonialsResult`

## Development vs Production

The SDK can be built in two modes:

**Development (localhost):**
```bash
yarn build:dev
```
Builds the SDK to connect to `http://localhost:8080` for local development.

**Production:**
```bash
yarn build:prod
```
Builds the SDK to connect to `https://api.hellotrust.io` for production use.

The API URL is baked into the build at compile time for maximum reliability and performance.

## License

MIT