@ryan-weber-ltd/fivestar

TypeScript/JavaScript SDK for FiveStar Support - Customer feedback platform.

Installation

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

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: '[email protected]',
  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.

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.

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.

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

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

Submit a new response/feedback.

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.

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.

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.

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

const { customerId } = await client.generateCustomerId()

License

MIT © Ryan Weber Ltd

Support

• Documentation
• GitHub Issues