npm package: @ryan-weber-ltd/fivestar
Description: TypeScript SDK for FiveStar Support - Customer feedback platform
Author: Ryan Weber Ltd
Latest version: 1.1.1

# @ryan-weber-ltd/fivestar

[![npm version](https://badge.fury.io/js/%40ryan-weber-ltd%2Ffivestar.svg)](https://www.npmjs.com/package/@ryan-weber-ltd/fivestar)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TypeScript/JavaScript SDK for [FiveStar Support](https://fivestar.support) - Customer feedback platform.

## Installation

```bash
npm install @ryan-weber-ltd/fivestar
# or
yarn add @ryan-weber-ltd/fivestar
# or
pnpm add @ryan-weber-ltd/fivestar
```

## Features

- **Server-Side Customer ID Generation**: Secure customer IDs generated by the server
- **Response Types**: Fetch available feedback categories (bug, feature request, etc.)
- **Feedback Submission**: Submit bug reports and feature requests
- **Type-Safe**: Written in TypeScript with full type definitions

## Quick Start

```typescript
import { FiveStarClient } from '@ryan-weber-ltd/fivestar'

// Initialize the client
const client = new FiveStarClient({
  clientId: 'your-client-uuid', // Get this from your FiveStar dashboard
  platform: 'web', // 'web', 'ios', 'android', 'flutter', 'laravel'
  appVersion: '1.0.0', // Your app version
})

// Generate a customer ID from the server
const { customerId, expiresAt } = await client.generateCustomerId()

// Register the customer (recommended on first launch)
await client.registerCustomer(customerId, {
  email: 'user@example.com',
  name: 'John Doe',
})

// Get available response types
const responseTypes = await client.getResponseTypes()

// Submit feedback
await client.submitResponse({
  customerId,
  title: 'Feature request: Dark mode',
  description: 'Please add a dark mode to the application',
  typeId: responseTypes[0].id,
})
```

## API Reference

### FiveStarClient

#### `constructor(config: FiveStarClientConfig)`

Creates a new FiveStar client instance.

```typescript
const client = new FiveStarClient({
  clientId: string,              // Required: Your client UUID
  apiUrl?: string,               // Optional: API URL (defaults to 'https://fivestar.support')
  platform?: string,             // Optional: 'web', 'ios', 'android', 'flutter', 'laravel'
  appVersion?: string,           // Optional: Your app version
  deviceModel?: string,          // Optional: Device model (e.g., 'iPhone14,2')
  osVersion?: string             // Optional: OS version (e.g., '16.0')
})
```

#### `async generateCustomerId(): Promise<GenerateCustomerIdResult>`

Generate a new customer ID from the server.

```typescript
const { customerId, expiresAt, deviceId } = await client.generateCustomerId()

// customerId: The server-generated customer ID
// expiresAt: When the customer ID expires (90 days)
// deviceId: Short device identifier for tracking
```

#### `async getResponseTypes(): Promise<ResponseType[]>`

Get all available response types for this client.

```typescript
const types = await client.getResponseTypes()
// Returns: [{ id, name, slug, color, icon }, ...]
```

#### `async submitResponse(options: SubmitResponseOptions): Promise<SubmitResponseResult>`

Submit a new response/feedback.

```typescript
await client.submitResponse({
  customerId: string,            // Required: Customer ID from generateCustomerId()
  title: string,                 // Required: Feedback title
  description: string,           // Required: Feedback description
  typeId: string,               // Required: Response type ID
  email?: string,                // Optional: Customer email
  name?: string                  // Optional: Customer name
})
```

#### `async registerCustomer(customerId: string, options?: RegisterCustomerOptions): Promise<RegisterCustomerResult>`

Register a customer ID for this client with optional customer information.

```typescript
await client.registerCustomer(customerId, {
  email?: string,  // Optional: Customer email
  name?: string    // Optional: Customer name
})
```

#### `async verifyCustomer(customerId: string): Promise<{ valid: boolean; message?: string }>`

Check if a customer ID is valid and registered for this client.

```typescript
const result = await client.verifyCustomer(customerId)
if (result.valid) {
  // Customer ID is valid and registered
}
```

#### `getPublicUrl(locale?: string): string`

Get the public feedback page URL for this client.

```typescript
const url = client.getPublicUrl('en')
// Returns: 'https://fivestar.support/en/c/{clientId}'
```

## Migration from v1.x

The SDK has been simplified in v2.x:

### Customer ID Generation

```typescript
const { customerId } = await client.generateCustomerId()
```

## License

MIT © [Ryan Weber Ltd](https://ryan-weber.com)

## Support

- [Documentation](https://fivestar.support)
- [GitHub Issues](https://github.com/ryanw3b3r/fivestar-sdk-ts/issues)