npm package: @feedinbox/widgets
Description: React components and vanilla JavaScript SDK for FeedInbox feedback and subscription widgets
Author: FeedInbox Team
Latest version: 1.0.0

# @feedinbox/widgets

> React components and vanilla JavaScript SDK for FeedInbox feedback and subscription widgets

[![npm version](https://badge.fury.io/js/@feedinbox%2Fwidgets.svg)](https://badge.fury.io/js/@feedinbox%2Fwidgets)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@feedinbox/widgets)](https://bundlephobia.com/package/@feedinbox/widgets)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

## 🚀 Quick Start

### React Components

```bash
npm install @feedinbox/widgets
```

```tsx
import { FeedbackWidget, NewsletterWidget, ContactWidget } from '@feedinbox/widgets'
import '@feedinbox/widgets/style.css'

function App() {
  return (
    <div>
      <FeedbackWidget apiKey="fb_your_api_key_here" />
      <NewsletterWidget apiKey="fb_your_api_key_here" />
      <ContactWidget apiKey="fb_your_api_key_here" />
    </div>
  )
}
```

### Vanilla JavaScript SDK

```html
<!-- CDN -->
<script src="https://unpkg.com/@feedinbox/widgets/dist/sdk/feedinbox-sdk.umd.js"></script>

<!-- NPM -->
<script type="module">
  import { FeedInboxSDK } from '@feedinbox/widgets/sdk'
  
  const feedinbox = new FeedInboxSDK({
    apiKey: 'fb_your_api_key_here',
    apiUrl: 'https://api.feedinbox.com'
  })
  
  // Create widgets
  feedinbox.createFeedbackWidget('feedback-container')
  feedinbox.createNewsletterWidget('newsletter-container')
  feedinbox.createContactWidget('contact-container')
</script>
```

## 📦 What's Included

### React Components
- **FeedbackWidget** - Collect user feedback with priority levels
- **NewsletterWidget** - Newsletter subscription forms
- **ContactWidget** - Contact forms with custom fields

### Vanilla JavaScript SDK
- **Framework-agnostic** - Works with any website
- **Zero dependencies** - Lightweight and fast
- **TypeScript support** - Full type definitions included

## 🔑 Authentication

All widgets require an API key from your FeedInbox dashboard:

1. Login to [FeedInbox Dashboard](https://app.feedinbox.com)
2. Go to Settings → API Keys
3. Generate a new API key
4. Use the key in your widgets

## 📚 API Reference

### React Components

#### FeedbackWidget

```tsx
interface FeedbackWidgetProps {
  apiKey: string                    // Your FeedInbox API key
  apiUrl?: string                   // API endpoint (optional)
  workspaceId?: string              // Target workspace (optional)
}

<FeedbackWidget 
  apiKey="fb_your_api_key"
  workspaceId="workspace-uuid"      // Optional: specify workspace
/>
```

#### NewsletterWidget

```tsx
interface NewsletterWidgetProps {
  apiKey: string
  apiUrl?: string
  workspaceId?: string
}

<NewsletterWidget 
  apiKey="fb_your_api_key"
/>
```

#### ContactWidget

```tsx
interface ContactWidgetProps {
  apiKey: string
  apiUrl?: string
  workspaceId?: string
  title?: string                    // Widget title
  description?: string              // Widget description
  phone?: string                    // Contact phone
  email?: string                    // Contact email
  web?: { label: string, url: string }  // Website link
}

<ContactWidget 
  apiKey="fb_your_api_key"
  title="Get in Touch"
  description="We'd love to hear from you"
  phone="+1 (555) 123-4567"
  email="hello@yourcompany.com"
  web={{ label: "yourcompany.com", url: "https://yourcompany.com" }}
/>
```

### Vanilla JavaScript SDK

#### Initialization

```javascript
const feedinbox = new FeedInboxSDK({
  apiKey: 'fb_your_api_key',        // Required
  apiUrl: 'https://api.feedinbox.com',  // Optional
  debug: false                      // Optional: enable debug logs
})
```

#### Widget Creation

```javascript
// Create feedback widget
feedinbox.createFeedbackWidget('container-id', {
  buttonText: 'Give Feedback',
  title: 'Share Your Feedback',
  description: 'Help us improve our product',
  onSuccess: (response) => console.log('Success:', response),
  onError: (error) => console.error('Error:', error)
})

// Create newsletter widget  
feedinbox.createNewsletterWidget('container-id', {
  buttonText: 'Subscribe',
  title: 'Join Our Newsletter',
  description: 'Get updates and exclusive content'
})

// Create contact widget
feedinbox.createContactWidget('container-id', {
  buttonText: 'Contact Us',
  title: 'Get in Touch'
})
```

#### Direct API Methods

```javascript
// Submit feedback
await feedinbox.submitFeedback({
  userEmail: 'user@example.com',
  message: 'Great product!',
  subject: 'Product Feedback',
  priority: 'medium',              // 'low' | 'medium' | 'high'
  workspaceId: 'workspace-uuid'    // Optional
})

// Subscribe to newsletter
await feedinbox.subscribe({
  email: 'user@example.com',
  subscription: 'newsletter',      // 'newsletter' | 'updates'
  workspaceId: 'workspace-uuid'    // Optional
})

// Submit contact form
await feedinbox.submitContact({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  subject: 'Question about pricing',
  message: 'I have a question...',
  workspaceId: 'workspace-uuid'    // Optional
})
```

## 🎨 Styling

### React Components

Import the CSS file for default styling:

```tsx
import '@feedinbox/widgets/style.css'
```

### Custom Styling

All widgets use CSS classes you can override:

```css
/* Feedback Widget */
.feedinbox-feedback-widget { }
.feedinbox-feedback-button { }
.feedinbox-feedback-modal { }

/* Newsletter Widget */
.feedinbox-newsletter-widget { }
.feedinbox-newsletter-button { }
.feedinbox-newsletter-modal { }

/* Contact Widget */
.feedinbox-contact-widget { }
.feedinbox-contact-button { }
.feedinbox-contact-modal { }
```

## 🏗️ Advanced Usage

### Multi-Workspace Support

If your API key has access to multiple workspaces:

```tsx
// React
<FeedbackWidget 
  apiKey="fb_your_api_key"
  workspaceId="specific-workspace-id"
/>

// Vanilla JS
await feedinbox.submitFeedback({
  userEmail: 'user@example.com',
  message: 'Feedback',
  workspaceId: 'specific-workspace-id'
})
```

### Error Handling

```javascript
try {
  const response = await feedinbox.submitFeedback({
    userEmail: 'user@example.com',
    message: 'Test feedback'
  })
  
  if (response.success) {
    console.log('Feedback submitted successfully')
  } else {
    console.error('Error:', response.error)
  }
} catch (error) {
  console.error('Network error:', error)
}
```

## 📊 Bundle Sizes

| Distribution | Size (Minified) | Size (Gzipped) |
|--------------|-----------------|----------------|
| React Components (ES) | 25 KB | 5.8 KB |
| React Components (UMD) | 16 KB | 5.1 KB |
| Vanilla SDK (ES) | 18 KB | 3.9 KB |
| Vanilla SDK (UMD) | 17 KB | 3.8 KB |
| CSS Styles | 10 KB | 1.8 KB |

## 🛠️ Development

```bash
# Clone repository
git clone https://github.com/feedinbox/feedinbox.git
cd feedinbox/packages/widget

# Install dependencies
pnpm install

# Start development server
pnpm run dev

# Build all distributions
pnpm run build:all

# Build individual distributions
pnpm run build:lib    # React components
pnpm run build:sdk    # Vanilla SDK
```

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Support

- **Documentation**: [https://docs.feedinbox.com](https://docs.feedinbox.com)
- **Issues**: [GitHub Issues](https://github.com/feedinbox/feedinbox/issues)
- **Email**: support@feedinbox.com

## 🔗 Links

- **Website**: [https://feedinbox.com](https://feedinbox.com)
- **Dashboard**: [https://app.feedinbox.com](https://app.feedinbox.com)
- **API Docs**: [https://api.feedinbox.com/docs](https://api.feedinbox.com/docs)