npm package: @sessionsight/feedback
Description: User feedback and survey SDK for SessionSight.
Author: SessionSight
Latest version: 1.0.1

# @sessionsight/feedback

Collect structured feedback, bug reports, and ratings from your users.

## Installation

```bash
npm install @sessionsight/feedback
```

## Quick Start

```typescript
import SessionSightFeedback from '@sessionsight/feedback';

SessionSightFeedback.init({
  secretApiKey: 'sessionsight_sec_...',
  propertyId: 'your-property-id',
});

// Submit feedback
await SessionSightFeedback.submit('bug-report', {
  userId: 'user_456',
  option: 'critical',
  message: 'The checkout page crashes on Safari',
  metadata: { page: '/checkout', browser: 'Safari 17' },
});
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `secretApiKey` | `string` | **required** | Your secret API key from the dashboard |
| `propertyId` | `string` | **required** | Your property ID |
| `apiUrl` | `string` | `https://api.sessionsight.com` | Override for self-hosted or local dev |

## API

### `SessionSightFeedback.init(config)`

Initialize the SDK with your credentials.

### `SessionSightFeedback.submit(feedbackTypeId, options?)`

Submit feedback.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `feedbackTypeId` | `string` | Yes | The feedback type slug (created in the dashboard) |
| `options.userId` | `string` | No | Identifier for the user submitting the feedback |
| `options.visitorId` | `string` | No | SessionSight visitor ID for session attribution |
| `options.sessionId` | `string` | No | SessionSight session ID to link feedback to a specific session |
| `options.option` | `string` | No | Selected option value (must match a pre-defined option) |
| `options.message` | `string` | No | Free-text message (only if the feedback type allows text input) |
| `options.metadata` | `Record<string, string>` | No | Additional key-value context |

Returns `Promise<{ success: boolean; error?: string }>`.

### `SessionSightFeedback.destroy()`

Clean up resources.

## Class-based Usage

```typescript
import { FeedbackClient } from '@sessionsight/feedback';

const feedback = new FeedbackClient({
  secretApiKey: 'sessionsight_sec_...',
  propertyId: 'your-property-id',
});

await feedback.submit('star-rating', { option: '5', userId: 'user_123' });

feedback.destroy();
```

## Use Cases

### Bug Reports

```typescript
await SessionSightFeedback.submit('bug-report', {
  userId: 'user_123',
  option: 'critical',
  message: 'Payment fails with Amex cards',
  metadata: { page: '/checkout', browser: 'Chrome 120' },
});
```

### Star Ratings (1-5)

```typescript
await SessionSightFeedback.submit('star-rating', {
  option: '4',
  userId: 'user_123',
});
```

### Sentiment Feedback (Good/Neutral/Bad)

```typescript
await SessionSightFeedback.submit('page-feedback', {
  option: 'good',
  userId: 'user_123',
  message: 'This article was really helpful!',
});
```

## Script Tag

```html
<script src="https://cdn.sessionsight.com/sessionsight-feedback.js"></script>
<script>
  SessionSightFeedback.init({
    secretApiKey: 'sessionsight_sec_...',
    propertyId: 'your-property-id',
  });
</script>
```