@product7/product7-js 0.1.0

package/README.md

@@ -0,0 +1,1025 @@
+# Feedback Widget SDK
+
+[![npm version](https://badge.fury.io/js/%40product7%2Fproduct7-js.svg)](https://badge.fury.io/js/%40product7%2Fproduct7-js)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@product7/product7-js)](https://bundlephobia.com/package/@product7/product7-js)
+
+A lightweight, customizable JavaScript SDK for collecting user feedback on any website. Built for the Product7 feedback platform.
+
+---
+
+## Features
+
+- **Display modes** — Side panel or centered modal
+- **Size options** — Small, medium, or large widget sizes
+- **Full color customization** — Background, text, and primary colors
+- **Custom triggers** — Use your own buttons instead of floating widget
+- **Mock mode** — Development without backend connection
+- **Multiple positions** — 7 position options including center
+- **Responsive design** — Works on desktop, tablet, and mobile
+- **Easy integration** — Simple JavaScript API, minimal setup
+- **Lightweight** — ~12KB gzipped
+- **TypeScript support** — Full type definitions included
+- **Accessible** — WCAG 2.1 compliant
+- **Secure** — CSP friendly, no `eval()` usage
+- **Messenger widget** — Real-time chat with WebSocket support
+- **Help center** — Integrated help articles and collections
+- **Changelog** — Display product updates and announcements
+- **Environment auto-detection** — Automatic staging/production switching
+
+---
+
+## Quick Start
+
+### CDN Installation (Recommended)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@product7/product7-js/dist/product7-js.min.js"></script>
+<script>
+	const feedback = new Product7({
+		workspace: 'your-workspace-name',
+		boardName: 'your-board-id',
+	});
+
+	feedback.init().then(() => {
+		const widget = feedback.createWidget('button');
+		widget.mount();
+	});
+</script>
+```
+
+### NPM Installation
+
+```bash
+npm install @product7/product7-js
+```
+
+```javascript
+import { Product7 } from '@product7/product7-js';
+
+const feedback = new Product7({
+	workspace: 'your-workspace-name',
+	boardName: 'your-board-id',
+});
+
+await feedback.init();
+const widget = feedback.createWidget('button');
+widget.mount();
+```
+
+### Auto-Initialization
+
+```html
+<script>
+	window.Product7Config = {
+		workspace: 'your-workspace',
+		boardName: 'your-board-id',
+		autoCreate: {
+			type: 'button',
+			position: 'bottom-right',
+		},
+	};
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@product7/product7-js/dist/product7-js.min.js"></script>
+```
+
+---
+
+## Documentation
+
+- [Installation Guide](src/docs/installation.md)
+- [Framework Integrations](src/docs/framework-integrations.md)
+- [API Reference](src/docs/api.md)
+- [Examples](src/docs/example.md)
+
+---
+
+## Widget Types
+
+**Button Widget with Side Panel**
+
+```javascript
+const widget = feedback.createWidget('button', {
+	position: 'bottom-right',
+	displayMode: 'panel', // Slides in from the side
+	size: 'medium',
+});
+widget.mount();
+```
+
+**Button Widget with Modal**
+
+```javascript
+const widget = feedback.createWidget('button', {
+	position: 'bottom-right',
+	displayMode: 'modal',
+	size: 'large',
+	backgroundColor: '#ffffff',
+	textColor: '#1F2937',
+	primaryColor: '#21244A',
+});
+widget.mount();
+```
+
+**Inline Widget**
+
+```javascript
+const inline = feedback.createWidget('inline');
+inline.mount('#feedback-container');
+```
+
+**Messenger Widget**
+
+```javascript
+const messenger = feedback.createWidget('messenger', {
+	position: 'bottom-right',
+	theme: 'light',
+	teamName: 'Support',
+	enableHelp: true,
+	enableChangelog: true,
+});
+messenger.mount();
+```
+
+---
+
+## Configuration
+
+### SDK Configuration
+
+| Option      | Type    | Required | Default     | Description                            |
+| ----------- | ------- | -------- | ----------- | -------------------------------------- |
+| `workspace` | string  | ✅       | -           | Your workspace subdomain               |
+| `boardName` | string  | ❌       | 'general'   | Target board for feedback              |
+| `metadata`  | object  | ❌       | null        | User identification data               |
+| `mock`      | boolean | ❌       | false       | Enable mock mode for development       |
+| `debug`     | boolean | ❌       | false       | Enable debug logging                   |
+| `env`       | string  | ❌       | auto-detect | Environment: 'production' or 'staging' |
+| `apiUrl`    | string  | ❌       | null        | Custom API URL (overrides env)         |
+
+### Widget Configuration
+
+| Option            | Type   | Default        | Description                                    |
+| ----------------- | ------ | -------------- | ---------------------------------------------- |
+| `displayMode`     | string | 'panel'        | `'panel'` (side slide) or `'modal'` (centered) |
+| `size`            | string | 'medium'       | `'small'`, `'medium'`, or `'large'`            |
+| `position`        | string | 'bottom-right' | Button position (see below)                    |
+| `backgroundColor` | string | '#ffffff'      | Panel/modal background color                   |
+| `textColor`       | string | '#1F2937'      | Text color                                     |
+| `primaryColor`    | string | ''#21244A      | Button and accent color                        |
+
+### Position Options
+
+- `bottom-right` (default)
+- `bottom-left`
+- `top-right`
+- `top-left`
+- `bottom-center`
+- `top-center`
+- `center`
+
+### Size Variants
+
+| Size   | Modal Width | Panel Width |
+| ------ | ----------- | ----------- |
+| small  | 360px       | 320px       |
+| medium | 480px       | 420px       |
+| large  | 600px       | 520px       |
+
+---
+
+## Color Customization
+
+Instead of predefined themes, use direct color values for full flexibility:
+
+```javascript
+const widget = feedback.createWidget('button', {
+	displayMode: 'modal',
+	backgroundColor: '#1a1a2e', // Dark background
+	textColor: '#ffffff', // White text
+	primaryColor: '#e94560', // Red accent
+});
+```
+
+This approach works better than predefined themes because:
+
+- Supports any brand color
+- Works with both light and dark designs
+- No restrictions on color combinations
+
+---
+
+## Custom Triggers
+
+Hide the default floating button and trigger from your own UI:
+
+```javascript
+window.Product7.onReady((sdk) => {
+	const widget = sdk.createWidget('button', {
+		displayMode: 'modal',
+		size: 'medium',
+	});
+	widget.mount();
+	widget.hide(); // Hide the floating button
+
+	// Trigger from your own button
+	document.getElementById('my-feedback-btn').addEventListener('click', () => {
+		widget.openPanel();
+	});
+});
+```
+
+---
+
+## Mock Mode
+
+For development without a backend connection:
+
+```javascript
+window.Product7Config = {
+	workspace: 'demo',
+	mock: true, // No backend required
+	metadata: {
+		user_id: 'test_user',
+		email: 'test@example.com',
+	},
+};
+```
+
+Mock mode simulates:
+
+- Session initialization
+- Feedback submission (with 500ms delay)
+- Default configuration values
+- Messenger conversations and messages
+- Help articles and collections
+- Changelog entries
+- Agent availability status
+
+---
+
+## Environments
+
+The SDK supports multiple environments for development and production use.
+
+### Production (Default)
+
+```javascript
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	environment: 'production', // Default, can be omitted
+});
+```
+
+**API URLs:**
+
+- `https://api.product7.io/api/v1`
+- `https://{workspace}.api.product7.io/api/v1`
+
+### Staging
+
+```javascript
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	environment: 'staging',
+});
+```
+
+**API URLs:**
+
+- `https://staging.api.product7.io/api/v1`
+- `https://{workspace}.staging.api.product7.io/api/v1`
+
+### Custom API URL
+
+For self-hosted or custom deployments:
+
+```javascript
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	apiUrl: 'https://your-custom-api.com/api/v1',
+});
+```
+
+---
+
+## Configuration Priority
+
+Configuration values merge in this order (later overrides earlier):
+
+1. **Default values** — Built-in SDK defaults
+2. **Backend config** — Returned from `/widget/init` API
+3. **SDK config** — `window.Product7Config`
+4. **Widget options** — Passed to `createWidget()`
+
+This allows backend-managed defaults while permitting per-widget customization.
+
+---
+
+## Events
+
+```javascript
+feedback.eventBus.on('feedback:submitted', (data) => {
+	console.log('Feedback submitted:', data);
+});
+
+feedback.eventBus.on('feedback:error', (error) => {
+	console.error('Submission failed:', error);
+});
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/product7/product7-js.git
+cd product7-js
+npm install
+npm run dev
+npm run build
+npm test
+npm run size
+```
+
+---
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 12+
+- Edge 79+
+- iOS Safari 12+
+- Android Chrome 60+
+
+---
+
+## Bundle Size
+
+- **Minified**: ~41KB
+- **Minified + Gzipped**: ~12KB
+
+---
+
+## Contributing
+
+We welcome contributions! See [Contributing Guide](CONTRIBUTING.md).
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## Support
+
+- Docs: [docs.product7.io/product7-js](https://docs.product7.io/product7-js)
+- Issues: [GitHub Issues](https://github.com/product7/product7-js/issues)
+- Discord: [Join our community](https://discord.gg/product7)
+- Email: [support@product7.io](mailto:support@product7.io)
+
+---
+
+## Messenger Widget
+
+The SDK includes a full-featured messenger widget for real-time customer conversations, help articles, and changelog updates.
+
+### Features
+
+- **Real-time messaging** — WebSocket-powered live chat with typing indicators
+- **Conversation management** — View and manage multiple conversations
+- **Help center integration** — Browse help articles and collections
+- **Changelog updates** — Display product updates and announcements
+- **Agent availability** — Show online status and response times
+- **Customizable UI** — Theme, colors, and position options
+
+### Quick Start
+
+```javascript
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	metadata: {
+		user_id: 'user_123',
+		email: 'user@example.com',
+		name: 'John Doe',
+	},
+});
+
+await feedback.init();
+
+const messenger = feedback.createWidget('messenger', {
+	position: 'bottom-right',
+	theme: 'light',
+	teamName: 'Support Team',
+	welcomeMessage: 'How can we help you today?',
+	enableHelp: true,
+	enableChangelog: true,
+	primaryColor: '#155EEF',
+});
+
+messenger.mount();
+```
+
+### Messenger Configuration Options
+
+| Option             | Type     | Default            | Description                             |
+| ------------------ | -------- | ------------------ | --------------------------------------- |
+| `position`         | string   | 'bottom-right'     | Widget position on screen               |
+| `theme`            | string   | 'light'            | 'light' or 'dark'                       |
+| `teamName`         | string   | 'Support'          | Team name displayed in header           |
+| `teamAvatars`      | array    | []                 | Array of team member avatar URLs        |
+| `welcomeMessage`   | string   | 'How can we help?' | Welcome message on home view            |
+| `enableHelp`       | boolean  | true               | Show help articles section              |
+| `enableChangelog`  | boolean  | true               | Show changelog section                  |
+| `enableNews`       | boolean  | -                  | Alias for `enableChangelog`             |
+| `autoLoadData`     | boolean  | true               | Auto-fetch conversations/help/changelog |
+| `initialView`      | string   | 'home'             | Initial view on mount                   |
+| `previewData`      | object   | null               | Seed deterministic local data           |
+| `logoUrl`          | string   | -                  | Custom logo URL                         |
+| `primaryColor`     | string   | '#155EEF'          | Primary accent color                    |
+| `onSendMessage`    | function | null               | Callback when message is sent           |
+| `onArticleClick`   | function | null               | Callback when help article is clicked   |
+| `onChangelogClick` | function | null               | Callback when changelog item is clicked |
+
+### Messenger Views
+
+The messenger widget includes multiple views:
+
+| View        | Description                       |
+| ----------- | --------------------------------- |
+| `home`      | Welcome screen with quick actions |
+| `messages`  | List of all conversations         |
+| `chat`      | Individual conversation chat view |
+| `help`      | Help articles and collections     |
+| `changelog` | Product updates and announcements |
+
+### Programmatic Control
+
+```javascript
+// Open/close messenger
+messenger.open();
+messenger.close();
+messenger.toggle();
+
+// Navigate to specific view
+messenger.navigateTo('messages');
+messenger.navigateTo('help');
+messenger.navigateTo('changelog');
+
+// Get current state
+const state = messenger.getState();
+console.log(state.isOpen, state.currentView, state.unreadCount);
+
+// Update unread count
+messenger.setUnreadCount(3);
+```
+
+### Real-time Events
+
+```javascript
+// Message sent
+feedback.eventBus.on('messenger:messageSent', (data) => {
+	console.log('Message sent:', data.message);
+});
+
+// Messenger opened/closed
+feedback.eventBus.on('messenger:opened', () => {
+	console.log('Messenger opened');
+});
+
+feedback.eventBus.on('messenger:closed', () => {
+	console.log('Messenger closed');
+});
+```
+
+### WebSocket Connection
+
+The messenger automatically establishes a WebSocket connection for real-time features:
+
+- **Incoming messages** — New messages appear instantly
+- **Typing indicators** — See when agents are typing
+- **Presence updates** — Real-time agent availability
+
+The WebSocket connection is managed automatically and reconnects on disconnection.
+
+---
+
+## Environment Auto-Detection
+
+The SDK automatically detects the environment based on the hostname:
+
+| Hostname Pattern                    | Environment |
+| ----------------------------------- | ----------- |
+| `localhost`, `127.0.0.1`, `*.local` | staging     |
+| Contains `staging`                  | staging     |
+| All other hostnames                 | production  |
+
+```javascript
+// Auto-detection (recommended)
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	// env is auto-detected from window.location.hostname
+});
+
+// Manual override
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	env: 'staging', // Force staging environment
+});
+```
+
+---
+
+## Survey Widget
+
+The SDK includes a powerful survey widget for collecting structured user feedback through NPS, CSAT, CES, and custom surveys. Surveys can be triggered manually, on specific events, or managed through the backend dashboard.
+
+### Survey Types
+
+| Type       | Description           | Scale                                             |
+| ---------- | --------------------- | ------------------------------------------------- |
+| **NPS**    | Net Promoter Score    | 1-5 numeric scale (default; configurable to 0-10) |
+| **CSAT**   | Customer Satisfaction | 5-point emoji scale                               |
+| **CES**    | Customer Effort Score | 5-level difficulty scale                          |
+| **Custom** | Multi-question forms  | Flexible input types                              |
+
+### Quick Start
+
+```javascript
+const feedback = new Product7({
+	workspace: 'your-workspace',
+	boardName: 'your-board-id',
+});
+
+await feedback.init();
+
+// Show NPS survey
+feedback.showSurvey({
+	surveyType: 'nps',
+	description:
+		'To what extent do you agree or disagree that our tools support the work you do?',
+	ratingScale: 5,
+	showTitle: false,
+	showDescription: true,
+	showFeedbackInput: false,
+	showSubmitButton: false,
+	autoSubmitOnSelect: true,
+	onSubmit: (response) => {
+		console.log('Survey submitted:', response);
+	},
+});
+```
+
+### Survey Configuration Options
+
+```javascript
+feedback.showSurvey({
+	surveyId: 'backend-survey-id', // Optional: links response to backend survey
+	surveyType: 'nps', // 'nps' | 'csat' | 'ces' | 'custom'
+	position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'center' | 'bottom'
+	theme: 'light', // 'light' | 'dark'
+	title: 'Your survey title',
+	description: 'Optional description',
+	ratingScale: 5, // NPS scale (default 5, set 11 for 0-10)
+	showTitle: false, // default false for single-step rating surveys
+	showDescription: true, // default true for single-step rating surveys
+	showFeedbackInput: false, // default false for single-step rating surveys
+	showSubmitButton: false, // default false for single-step rating surveys
+	autoSubmitOnSelect: true, // default true for single-step rating surveys
+	lowLabel: 'Not likely', // Low end label (NPS/CES)
+	highLabel: 'Very likely', // High end label (NPS/CES)
+	customQuestions: [], // For custom surveys
+	onSubmit: (response) => {},
+	onDismiss: () => {},
+});
+```
+
+---
+
+### Backend-Driven Surveys
+
+For surveys configured in the Product7 dashboard, use `showSurveyById()` to fetch and display them:
+
+```javascript
+// Show a specific survey by its backend ID
+await feedback.showSurveyById('survey_abc123', {
+	position: 'center', // Override position if needed
+	onSubmit: (response) => {
+		console.log('Survey completed:', response);
+	},
+});
+```
+
+### Fetching Active Surveys
+
+Retrieve surveys that match the current user's targeting criteria:
+
+```javascript
+// Get all active surveys for the current context
+const surveys = await feedback.getActiveSurveys();
+
+console.log('Available surveys:', surveys);
+// [{ id: 'survey_123', type: 'nps', title: '...', ... }]
+
+// Show the first matching survey
+if (surveys.length > 0) {
+	await feedback.showSurveyById(surveys[0].id);
+}
+```
+
+With custom targeting context:
+
+```javascript
+const surveys = await feedback.getActiveSurveys({
+	url: '/dashboard/settings', // Override current URL
+	userProperties: {
+		plan: 'enterprise',
+		feature_usage: 'high',
+	},
+});
+```
+
+---
+
+### Survey Types
+
+#### NPS Survey (Net Promoter Score)
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'nps',
+	description:
+		'To what extent do you agree or disagree that our tools support the work you do?',
+	ratingScale: 5,
+	showTitle: false,
+	showDescription: true,
+	showFeedbackInput: false,
+	showSubmitButton: false,
+	autoSubmitOnSelect: true,
+	lowLabel: 'Strongly Disagree',
+	highLabel: 'Strongly Agree',
+	position: 'bottom-right',
+	onSubmit: (response) => {
+		console.log('Score:', response.score); // 1-5 by default
+		console.log('Feedback:', response.feedback);
+	},
+});
+```
+
+#### CSAT Survey (Customer Satisfaction)
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'csat',
+	title: 'How satisfied are you with our service?',
+	position: 'center',
+	theme: 'dark',
+	onSubmit: (response) => {
+		console.log('Satisfaction:', response.score); // 1-5
+	},
+});
+```
+
+#### CES Survey (Customer Effort Score)
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'ces',
+	title: 'How easy was it to complete your task?',
+	position: 'bottom',
+	onSubmit: (response) => {
+		console.log('Effort score:', response.score); // 1-5
+	},
+});
+```
+
+#### Custom Survey
+
+```javascript
+feedback.showSurvey({
+	surveyType: 'custom',
+	title: 'Quick Feedback',
+	customQuestions: [
+		{
+			id: 'feature',
+			type: 'select',
+			label: 'Which feature do you use most?',
+			options: [
+				{ value: 'dashboard', label: 'Dashboard' },
+				{ value: 'reports', label: 'Reports' },
+				{ value: 'settings', label: 'Settings' },
+			],
+		},
+		{
+			id: 'improvement',
+			type: 'text',
+			label: 'What could we improve?',
+			placeholder: 'Your suggestions...',
+		},
+	],
+	onSubmit: (response) => {
+		console.log('Answers:', response.customAnswers);
+		// { feature: 'dashboard', improvement: 'Better charts' }
+	},
+});
+```
+
+---
+
+### Event-Triggered Surveys
+
+Trigger surveys based on user actions:
+
+```javascript
+// After completing a purchase
+document.getElementById('checkout-btn').addEventListener('click', async () => {
+	await processPayment();
+
+	feedback.showSurvey({
+		surveyType: 'csat',
+		title: 'How was your checkout experience?',
+		position: 'center',
+	});
+});
+
+// After closing support chat
+chatWidget.on('close', () => {
+	feedback.showSurvey({
+		surveyType: 'ces',
+		title: 'How easy was it to get help?',
+		position: 'bottom-right',
+	});
+});
+
+// On page exit intent
+document.addEventListener('mouseleave', (e) => {
+	if (e.clientY < 0 && !sessionStorage.getItem('exit_survey_shown')) {
+		sessionStorage.setItem('exit_survey_shown', 'true');
+		feedback.showSurvey({
+			surveyType: 'nps',
+			title: 'Before you go...',
+			description: 'How likely are you to recommend us?',
+			position: 'center',
+		});
+	}
+});
+```
+
+### Time-Based Surveys
+
+```javascript
+// Show after 60 seconds on page
+setTimeout(() => {
+	feedback.showSurvey({
+		surveyType: 'nps',
+		title: 'Enjoying our product?',
+		position: 'bottom-right',
+	});
+}, 60000);
+
+// Show after N page views
+const pageViews = parseInt(localStorage.getItem('page_views') || '0') + 1;
+localStorage.setItem('page_views', pageViews);
+
+if (pageViews === 5) {
+	feedback.showSurvey({
+		surveyType: 'csat',
+		title: 'How are you finding things so far?',
+	});
+}
+```
+
+---
+
+### React Integration
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { Product7 } from '@product7/product7-js';
+
+function useSurvey() {
+	const sdkRef = useRef(null);
+
+	useEffect(() => {
+		const sdk = new Product7({
+			workspace: 'your-workspace',
+			metadata: {
+				user_id: currentUser.id,
+				email: currentUser.email,
+			},
+		});
+
+		sdk.init().then(() => {
+			sdkRef.current = sdk;
+		});
+
+		return () => sdk.destroy();
+	}, []);
+
+	const showNPS = (options = {}) => {
+		sdkRef.current?.showSurvey({
+			surveyType: 'nps',
+			...options,
+		});
+	};
+
+	const showCSAT = (options = {}) => {
+		sdkRef.current?.showSurvey({
+			surveyType: 'csat',
+			...options,
+		});
+	};
+
+	return { showNPS, showCSAT };
+}
+
+// Usage in component
+function CheckoutSuccess() {
+	const { showCSAT } = useSurvey();
+
+	useEffect(() => {
+		showCSAT({
+			title: 'How was your checkout experience?',
+			position: 'center',
+		});
+	}, []);
+
+	return <div>Thank you for your purchase!</div>;
+}
+```
+
+### Vue.js Integration
+
+```vue
+<script setup>
+	import { onMounted, onUnmounted, ref } from 'vue';
+	import { Product7 } from '@product7/product7-js';
+
+	const sdk = ref(null);
+
+	onMounted(async () => {
+		sdk.value = new Product7({
+			workspace: 'your-workspace',
+			metadata: {
+				user_id: currentUser.value.id,
+				email: currentUser.value.email,
+			},
+		});
+		await sdk.value.init();
+	});
+
+	onUnmounted(() => {
+		sdk.value?.destroy();
+	});
+
+	const showSurvey = (type, options = {}) => {
+		sdk.value?.showSurvey({
+			surveyType: type,
+			...options,
+		});
+	};
+
+	// Trigger on button click
+	const handleFeedbackClick = () => {
+		showSurvey('nps', {
+			title: 'How likely are you to recommend us?',
+			position: 'center',
+		});
+	};
+</script>
+```
+
+---
+
+### Survey Events
+
+```javascript
+// Survey displayed
+feedback.eventBus.on('survey:shown', (data) => {
+	console.log('Survey displayed:', data.type);
+	analytics.track('Survey Shown', { type: data.type });
+});
+
+// Survey submitted
+feedback.eventBus.on('survey:submitted', (data) => {
+	console.log('Survey submitted:', data.response);
+	analytics.track('Survey Completed', {
+		type: data.response.type,
+		score: data.response.score,
+	});
+});
+
+// Survey dismissed without completing
+feedback.eventBus.on('survey:dismissed', (data) => {
+	console.log('Survey dismissed');
+	analytics.track('Survey Dismissed');
+});
+```
+
+### Response Data Format
+
+```javascript
+// NPS/CSAT/CES response
+{
+  type: 'nps',
+  score: 9,
+  feedback: 'Great product!',
+  timestamp: '2025-01-26T10:30:00.000Z'
+}
+
+// Custom survey response
+{
+  type: 'custom',
+  score: null,
+  feedback: 'Additional comments here',
+  customAnswers: {
+    feature: 'dashboard',
+    improvement: 'Better mobile support'
+  },
+  timestamp: '2025-01-26T10:30:00.000Z'
+}
+```
+
+---
+
+### Position Options
+
+| Position       | Description                   |
+| -------------- | ----------------------------- |
+| `bottom-right` | Bottom right corner (default) |
+| `bottom-left`  | Bottom left corner            |
+| `center`       | Centered modal with backdrop  |
+| `bottom`       | Full-width bottom bar         |
+
+### Theme Options
+
+| Theme   | Description                           |
+| ------- | ------------------------------------- |
+| `light` | White background, dark text (default) |
+| `dark`  | Dark background, light text           |
+
+---
+
+### Programmatic Control
+
+```javascript
+// Create survey widget for later use
+const survey = feedback.createWidget('survey', {
+	surveyType: 'nps',
+	title: 'Rate us',
+});
+survey.mount();
+
+// Show when ready
+survey.show();
+
+// Hide programmatically
+survey.hide();
+
+// Destroy when done
+survey.destroy();
+```
+
+### Survey Rate Limiting
+
+Avoid survey fatigue by tracking when surveys were last shown:
+
+```javascript
+const SURVEY_COOLDOWN = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+function canShowSurvey(surveyType) {
+	const lastShown = localStorage.getItem(`survey_${surveyType}_shown`);
+	if (!lastShown) return true;
+	return Date.now() - parseInt(lastShown) > SURVEY_COOLDOWN;
+}
+
+function showSurveyWithCooldown(options) {
+	if (!canShowSurvey(options.surveyType)) {
+		console.log('Survey on cooldown');
+		return null;
+	}
+
+	localStorage.setItem(`survey_${options.surveyType}_shown`, Date.now());
+	return feedback.showSurvey(options);
+}
+```
+
+---
+
+## Related
+
+- [Product7 Platform](https://product7.io)
+- [Vue.js Example](https://github.com/product7/product7-js-vue-example)
+- [React Example](https://github.com/product7/product7-js-react-example)
+
+---
+
+Made by the [Product7 Team](https://product7.io)