# Gotcha

> Gotcha is a developer-first contextual feedback SDK for React. Install via `npm install gotcha-feedback`. It lets developers add feedback buttons to any UI component, collecting star ratings and text feedback tied to specific elements rather than generic page surveys.

Website: https://gotcha.cx
npm: https://www.npmjs.com/package/gotcha-feedback
Dashboard: https://gotcha.cx/dashboard

## Installation

```bash
npm install gotcha-feedback
```

## Quick Start

```tsx
import { GotchaProvider, Gotcha } from 'gotcha-feedback';

function App() {
  return (
    <GotchaProvider apiKey="your-api-key">
      <div style={{ position: 'relative' }}>
        <YourComponent />
        <Gotcha elementId="feature-x" mode="feedback" />
      </div>
    </GotchaProvider>
  );
}
```

## Key Features

- **One-line integration**: Place `<Gotcha>` inside any relative-positioned parent to add a contextual feedback button
- **Element-specific feedback**: Responses are tied to UI elements, not just pages
- **Two collection modes**: `feedback` (1-5 star rating + text) and `vote` (thumbs up/down)
- **Editable responses**: Users can update their previous feedback on the same element
- **Configurable fields**: Show/hide star rating and text input independently with `showRating` and `showText`
- **Dashboard analytics**: Filter responses by element, date, rating at gotcha.cx/dashboard
- **Domain allowlisting**: API keys restricted to specific domains for security
- **TypeScript support**: Full type definitions included
- **Lightweight**: ~15KB gzipped, only peer dependency is React

## Feedback Mode

Shows a floating "G" button positioned on the parent element. On click:
- 5-star rating selector (toggleable via `showRating`)
- Optional text feedback input (toggleable via `showText`)
- Submit button
- Automatic element ID tracking
- If user has already submitted, pre-fills their previous response for editing

## Vote Mode

Shows a floating "G" button. On click:
- Thumbs up / thumbs down buttons (customizable labels via `voteLabels`)
- Optional comment field
- Quick sentiment collection

## Component Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `elementId` | string | Yes | - | Unique identifier for tracking |
| `mode` | 'feedback' \| 'vote' | Yes | - | Collection type |
| `showText` | boolean | No | true | Show text input in feedback mode |
| `showRating` | boolean | No | true | Show star rating in feedback mode |
| `position` | 'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' \| 'inline' | No | 'top-right' | Button placement |
| `size` | 'sm' \| 'md' \| 'lg' | No | 'md' | Button size |
| `theme` | 'light' \| 'dark' \| 'auto' \| 'custom' | No | 'light' | Color theme |
| `showOnHover` | boolean | No | true | Only show button when parent is hovered |
| `touchBehavior` | 'always-visible' \| 'tap-to-reveal' | No | 'always-visible' | Mobile behavior |
| `promptText` | string | No | - | Custom prompt text in modal |
| `placeholder` | string | No | - | Input placeholder text |
| `submitText` | string | No | 'Submit' | Submit button text |
| `thankYouMessage` | string | No | 'Thanks for your feedback!' | Post-submission message |
| `voteLabels` | { up: string; down: string } | No | - | Custom vote button labels |
| `visible` | boolean | No | true | Control visibility programmatically |
| `onSubmit` | (response) => void | No | - | Called after successful submission |
| `onOpen` | () => void | No | - | Called when modal opens |
| `onClose` | () => void | No | - | Called when modal closes |
| `onError` | (error) => void | No | - | Called on error |

## Error Handling

```tsx
<Gotcha
  elementId="feature-x"
  mode="feedback"
  onError={(error) => console.error('Gotcha error:', error)}
/>
```

Common errors:
- `INVALID_API_KEY`: API key not found or revoked
- `ORIGIN_NOT_ALLOWED`: Request origin not in allowlist
- `RATE_LIMITED`: Too many requests (Free: 100/min, Pro: 1000/min)
- `QUOTA_EXCEEDED`: Monthly response limit reached

## Pricing

- **Free**: 500 responses/month, 1 project, 30-day analytics
- **Pro**: $29/month, unlimited responses, unlimited projects, full analytics, CSV/JSON export

## Use Cases

1. **Feature feedback**: Gauge satisfaction on new features
2. **UI testing**: Compare user sentiment across design variations
3. **Bug context**: Users report issues on specific components
4. **Content rating**: Rate articles, docs, tutorials
5. **NPS collection**: Net Promoter Score on key user flows

## Why Gotcha vs Generic Surveys?

| Gotcha | Generic Surveys |
|--------|-----------------|
| Feedback tied to specific UI elements | Page-level or site-wide only |
| Non-intrusive floating button | Popup modals interrupt flow |
| Developer-friendly React SDK | Embed scripts, iframe widgets |
| Real-time dashboard by element | Aggregated reports |
| 15KB, no dependencies | Often 50KB+ with dependencies |

## API Endpoints

- `POST /api/v1/responses` - Submit feedback (requires API key)
- `GET /api/v1/responses` - List responses with filters
- `DELETE /api/v1/users/:userId` - GDPR data deletion
- `GET /api/v1/users/:userId/export` - GDPR data export

## Contact

- Email: info@braintwopoint0.com
- Website: https://gotcha.cx

## Optional

- [Pricing Details](https://gotcha.cx/pricing): Full pricing comparison
- [Live Demo](https://gotcha.cx/demo): Try the SDK without installing