npm - @product7/feedback-sdk - Versions diffs - 1.0.1 - Mend

@product7/feedback-sdk 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md +227 -0
package/dist/README.md +227 -0
package/dist/feedback-sdk.js +2483 -0
package/dist/feedback-sdk.js.map +1 -0
package/dist/feedback-sdk.min.js +2 -0
package/dist/feedback-sdk.min.js.map +1 -0
package/package.json +111 -0
package/src/core/APIService.js +338 -0
package/src/core/EventBus.js +54 -0
package/src/core/FeedbackSDK.js +285 -0
package/src/docs/api.md +686 -0
package/src/docs/example.md +823 -0
package/src/docs/installation.md +264 -0
package/src/index.js +281 -0
package/src/styles/styles.js +557 -0
package/src/types/index.d.ts +12 -0
package/src/utils/errors.js +142 -0
package/src/utils/helpers.js +219 -0
package/src/widgets/BaseWidget.js +334 -0
package/src/widgets/ButtonWidget.js +62 -0
package/src/widgets/InlineWidget.js +145 -0
package/src/widgets/TabWidget.js +65 -0
package/src/widgets/WidgetFactory.js +64 -0

package/src/docs/example.md ADDED Viewed

@@ -0,0 +1,823 @@
+# Examples
+Real-world examples of using the Feedback Widget SDK.
+## 🚀 Quick Start Examples
+### Basic Button Widget
+The simplest implementation - just a feedback button:
+```html
+<!DOCTYPE html>
+<html>
+	<head>
+		<title>Basic Feedback Button</title>
+	</head>
+	<body>
+		<h1>My Website</h1>
+		<p>This is my awesome website content...</p>
+		<script src="https://cdn.jsdelivr.net/npm/@product7/feedback-sdk@1/dist/feedback-sdk.min.js"></script>
+		<script>
+			const feedback = new FeedbackSDK({
+				workspace: 'my-company',
+				boardId: 'general-feedback',
+			});
+			feedback.init().then(() => {
+				const widget = feedback.createWidget('button');
+				widget.mount();
+			});
+		</script>
+	</body>
+</html>
+```
+### Auto-Initialization
+Let the SDK set itself up automatically:
+```html
+<script>
+	// Configure before loading the SDK
+	window.FeedbackSDKConfig = {
+		workspace: 'my-company',
+		boardId: 'general-feedback',
+		theme: 'light',
+		autoCreate: {
+			type: 'button',
+			position: 'bottom-right',
+		},
+	};
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@product7/feedback-sdk@1/dist/feedback-sdk.min.js"></script>
+<!-- Widget appears automatically! -->
+```
+## 🎨 Widget Customization Examples
+### Multiple Widgets
+Create different widgets for different purposes:
+```javascript
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	debug: true,
+});
+await feedback.init();
+// Button for general feedback
+const generalButton = feedback.createWidget('button', {
+	position: 'bottom-right',
+	boardId: 'general-feedback',
+});
+generalButton.mount();
+// Tab for bug reports
+const bugTab = feedback.createWidget('tab', {
+	position: 'bottom-left',
+	boardId: 'bug-reports',
+});
+bugTab.mount();
+// Inline form in footer
+const footerForm = feedback.createWidget('inline', {
+	boardId: 'feature-requests',
+});
+footerForm.mount('#footer-feedback');
+```
+### Custom Styling
+Override default styles with CSS:
+```html
+<style>
+	/* Custom button color */
+	.feedback-widget {
+		--feedback-primary-color: #10b981;
+		--feedback-primary-hover: #059669;
+	}
+	/* Custom positioning */
+	.feedback-widget-button.position-bottom-right {
+		bottom: 100px;
+		right: 30px;
+	}
+	/* Custom font */
+	.feedback-widget {
+		--feedback-font-family: 'Poppins', sans-serif;
+	}
+	/* Custom border radius */
+	.feedback-trigger-btn {
+		border-radius: 8px !important;
+	}
+</style>
+<script>
+	const feedback = new FeedbackSDK({
+		workspace: 'my-company',
+		boardId: 'styled-feedback',
+	});
+	feedback.init().then(() => {
+		const widget = feedback.createWidget('button');
+		widget.mount();
+	});
+</script>
+```
+### Dynamic Theme Switching
+Switch themes based on user preference:
+```javascript
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	boardId: 'general-feedback',
+	theme: 'light',
+});
+await feedback.init();
+const widget = feedback.createWidget('button');
+widget.mount();
+// Theme toggle function
+function toggleTheme() {
+	const isDark = document.body.classList.contains('dark-mode');
+	const newTheme = isDark ? 'light' : 'dark';
+	// Update SDK theme
+	feedback.updateConfig({ theme: newTheme });
+	// Update your site theme
+	document.body.classList.toggle('dark-mode');
+}
+// Bind to your theme toggle button
+document.getElementById('theme-toggle').addEventListener('click', toggleTheme);
+```
+## 📱 Responsive Examples
+### Mobile-First Design
+Optimize for mobile devices:
+```javascript
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	boardId: 'mobile-feedback',
+});
+await feedback.init();
+// Different widgets for different screen sizes
+if (window.innerWidth <= 768) {
+	// Mobile: Use tab widget to save space
+	const mobileWidget = feedback.createWidget('tab', {
+		position: 'bottom-right',
+	});
+	mobileWidget.mount();
+} else {
+	// Desktop: Use button widget
+	const desktopWidget = feedback.createWidget('button', {
+		position: 'bottom-right',
+	});
+	desktopWidget.mount();
+}
+// Handle screen resize
+window.addEventListener('resize', () => {
+	// Destroy current widgets and recreate based on new size
+	feedback.widgets.forEach((widget) => widget.destroy());
+	if (window.innerWidth <= 768) {
+		const mobileWidget = feedback.createWidget('tab');
+		mobileWidget.mount();
+	} else {
+		const desktopWidget = feedback.createWidget('button');
+		desktopWidget.mount();
+	}
+});
+```
+## 🎯 Event-Driven Examples
+### Analytics Integration
+Track feedback events with your analytics:
+```javascript
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	boardId: 'analytics-feedback',
+});
+await feedback.init();
+// Track feedback interactions
+feedback.eventBus.on('widget:mounted', (data) => {
+	// Track widget load
+	gtag('event', 'feedback_widget_loaded', {
+		widget_type: data.widget.type,
+		widget_id: data.widget.id,
+	});
+});
+feedback.eventBus.on('feedback:submitted', (data) => {
+	// Track successful submission
+	gtag('event', 'feedback_submitted', {
+		widget_type: data.widget.type,
+		feedback_length: data.feedback.content?.length || 0,
+	});
+	// Show thank you message
+	showToast('Thank you for your feedback! 🙏');
+});
+feedback.eventBus.on('feedback:error', (error) => {
+	// Track errors
+	gtag('event', 'feedback_error', {
+		error_type: error.error.name,
+		error_message: error.error.message,
+	});
+	// Show error message
+	showToast('Failed to send feedback. Please try again.', 'error');
+});
+const widget = feedback.createWidget('button');
+widget.mount();
+function showToast(message, type = 'success') {
+	// Your toast implementation
+	console.log(`${type}: ${message}`);
+}
+```
+### User Authentication Integration
+Integrate with your user system:
+```javascript
+// Get user info from your auth system
+const currentUser = getCurrentUser();
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	boardId: 'user-feedback',
+	apiKey: currentUser?.apiKey, // Use user's API key if available
+});
+await feedback.init();
+const widget = feedback.createWidget('inline');
+widget.mount('#feedback-section');
+// Pre-populate user email
+if (currentUser?.email) {
+	feedback.eventBus.on('widget:mounted', () => {
+		// Pre-fill email field
+		const emailInput = document.querySelector('input[name="email"]');
+		if (emailInput) {
+			emailInput.value = currentUser.email;
+			emailInput.disabled = true; // Prevent editing
+		}
+	});
+}
+// Add user context to feedback
+feedback.eventBus.on('feedback:submitted', (data) => {
+	// Log user-specific feedback submission
+	console.log(`Feedback from ${currentUser.email}:`, data.feedback);
+});
+```
+## 🌐 Framework Integration Examples
+### React Integration
+```jsx
+import React, { useEffect, useRef, useState } from 'react';
+import { FeedbackSDK } from '@product7/feedback-sdk';
+const FeedbackWidget = ({ workspace, boardId, type = 'button' }) => {
+	const [sdk, setSdk] = useState(null);
+	const [widget, setWidget] = useState(null);
+	const containerRef = useRef(null);
+	useEffect(() => {
+		// Initialize SDK
+		const initSDK = async () => {
+			const feedbackSDK = new FeedbackSDK({
+				workspace,
+				boardId,
+				debug: process.env.NODE_ENV === 'development',
+			});
+			await feedbackSDK.init();
+			setSdk(feedbackSDK);
+			// Create and mount widget
+			const feedbackWidget = feedbackSDK.createWidget(type);
+			if (type === 'inline' && containerRef.current) {
+				feedbackWidget.mount(containerRef.current);
+			} else {
+				feedbackWidget.mount();
+			}
+			setWidget(feedbackWidget);
+		};
+		initSDK();
+		// Cleanup
+		return () => {
+			if (widget) widget.destroy();
+			if (sdk) sdk.destroy();
+		};
+	}, [workspace, boardId, type]);
+	// For inline widgets, provide a container
+	if (type === 'inline') {
+		return <div ref={containerRef} className="feedback-container" />;
+	}
+	// For button/tab widgets, no container needed
+	return null;
+};
+// Usage
+export const App = () => {
+	return (
+		<div>
+			<h1>My React App</h1>
+			{/* Button widget */}
+			<FeedbackWidget
+				workspace="my-company"
+				boardId="react-feedback"
+				type="button"
+			/>
+			{/* Inline widget in footer */}
+			<footer>
+				<FeedbackWidget
+					workspace="my-company"
+					boardId="footer-feedback"
+					type="inline"
+				/>
+			</footer>
+		</div>
+	);
+};
+```
+### Vue.js Integration
+```vue
+<template>
+	<div>
+		<h1>My Vue App</h1>
+		<!-- Container for inline widget -->
+		<div v-if="widgetType === 'inline'" ref="feedbackContainer"></div>
+	</div>
+</template>
+<script>
+	import { FeedbackSDK } from '@product7/feedback-sdk';
+	export default {
+		name: 'FeedbackWidget',
+		props: {
+			workspace: { type: String, required: true },
+			boardId: { type: String, required: true },
+			widgetType: { type: String, default: 'button' },
+		},
+		data() {
+			return {
+				sdk: null,
+				widget: null,
+			};
+		},
+		async mounted() {
+			await this.initFeedback();
+		},
+		beforeUnmount() {
+			this.cleanup();
+		},
+		methods: {
+			async initFeedback() {
+				this.sdk = new FeedbackSDK({
+					workspace: this.workspace,
+					boardId: this.boardId,
+					debug: process.env.NODE_ENV === 'development',
+				});
+				await this.sdk.init();
+				// Listen to events
+				this.sdk.eventBus.on('feedback:submitted', this.onFeedbackSubmitted);
+				this.sdk.eventBus.on('feedback:error', this.onFeedbackError);
+				// Create widget
+				this.widget = this.sdk.createWidget(this.widgetType);
+				if (this.widgetType === 'inline') {
+					this.widget.mount(this.$refs.feedbackContainer);
+				} else {
+					this.widget.mount();
+				}
+			},
+			onFeedbackSubmitted(data) {
+				this.$emit('feedback-submitted', data);
+				this.$toast.success('Thank you for your feedback!');
+			},
+			onFeedbackError(error) {
+				this.$emit('feedback-error', error);
+				this.$toast.error('Failed to submit feedback');
+			},
+			cleanup() {
+				if (this.widget) this.widget.destroy();
+				if (this.sdk) this.sdk.destroy();
+			},
+		},
+	};
+</script>
+```
+### Angular Integration
+```typescript
+// feedback-widget.component.ts
+import {
+	Component,
+	Input,
+	OnInit,
+	OnDestroy,
+	ElementRef,
+	ViewChild,
+} from '@angular/core';
+import { FeedbackSDK } from '@product7/feedback-sdk';
+@Component({
+	selector: 'app-feedback-widget',
+	template: `
+		<div #feedbackContainer *ngIf="type === 'inline'"></div>
+	`,
+	styleUrls: ['./feedback-widget.component.css'],
+})
+export class FeedbackWidgetComponent implements OnInit, OnDestroy {
+	@Input() workspace: string = '';
+	@Input() boardId: string = '';
+	@Input() type: string = 'button';
+	@ViewChild('feedbackContainer') containerRef?: ElementRef;
+	private sdk?: FeedbackSDK;
+	private widget?: any;
+	async ngOnInit() {
+		await this.initializeFeedback();
+	}
+	ngOnDestroy() {
+		this.cleanup();
+	}
+	private async initializeFeedback() {
+		this.sdk = new FeedbackSDK({
+			workspace: this.workspace,
+			boardId: this.boardId,
+			debug: !environment.production,
+		});
+		await this.sdk.init();
+		// Set up event listeners
+		this.sdk.eventBus.on('feedback:submitted', (data) => {
+			console.log('Feedback submitted:', data);
+		});
+		// Create widget
+		this.widget = this.sdk.createWidget(this.type);
+		if (this.type === 'inline' && this.containerRef) {
+			this.widget.mount(this.containerRef.nativeElement);
+		} else {
+			this.widget.mount();
+		}
+	}
+	private cleanup() {
+		if (this.widget) this.widget.destroy();
+		if (this.sdk) this.sdk.destroy();
+	}
+}
+```
+## 🚀 Advanced Examples
+### A/B Testing
+Test different widget configurations:
+```javascript
+// A/B test: Button vs Tab widget
+const variant = Math.random() < 0.5 ? 'button' : 'tab';
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	boardId: 'ab-test-feedback',
+});
+await feedback.init();
+// Track A/B test variant
+gtag('event', 'feedback_widget_variant', {
+	variant: variant,
+});
+const widget = feedback.createWidget(variant, {
+	position: variant === 'button' ? 'bottom-right' : 'bottom-left',
+});
+widget.mount();
+// Track which variant gets more engagement
+feedback.eventBus.on('feedback:submitted', (data) => {
+	gtag('event', 'feedback_submitted_variant', {
+		variant: variant,
+		widget_type: data.widget.type,
+	});
+});
+```
+### Conditional Loading
+Load feedback widget based on conditions:
+```javascript
+async function loadFeedbackWidget() {
+	// Only load for logged-in users
+	if (!isUserLoggedIn()) {
+		return;
+	}
+	// Only load on certain pages
+	const allowedPages = ['/dashboard', '/profile', '/settings'];
+	if (!allowedPages.includes(window.location.pathname)) {
+		return;
+	}
+	// Don't load if user has submitted feedback recently
+	const lastFeedback = localStorage.getItem('lastFeedbackSubmission');
+	if (
+		lastFeedback &&
+		Date.now() - parseInt(lastFeedback) < 7 * 24 * 60 * 60 * 1000
+	) {
+		return; // 7 days cooldown
+	}
+	// Initialize SDK
+	const feedback = new FeedbackSDK({
+		workspace: 'my-company',
+		boardId: 'conditional-feedback',
+	});
+	await feedback.init();
+	// Track feedback submission timestamp
+	feedback.eventBus.on('feedback:submitted', () => {
+		localStorage.setItem('lastFeedbackSubmission', Date.now().toString());
+	});
+	const widget = feedback.createWidget('button');
+	widget.mount();
+}
+// Load when page is ready
+document.addEventListener('DOMContentLoaded', loadFeedbackWidget);
+```
+### Custom Widget Creation
+Create your own widget type:
+```javascript
+// Custom popup widget
+class PopupWidget extends FeedbackSDK.BaseWidget {
+	constructor(options) {
+		super({ ...options, type: 'popup' });
+		this.showDelay = options.showDelay || 5000;
+	}
+	_render() {
+		const popup = document.createElement('div');
+		popup.className = `feedback-popup theme-${this.options.theme}`;
+		popup.innerHTML = `
+            <div class="popup-content">
+                <button class="popup-close">&times;</button>
+                <h3>Quick Feedback</h3>
+                <p>How was your experience?</p>
+                <div class="popup-buttons">
+                    <button class="popup-btn good">😊 Good</button>
+                    <button class="popup-btn okay">😐 Okay</button>
+                    <button class="popup-btn bad">😞 Bad</button>
+                </div>
+            </div>
+        `;
+		// Auto-hide after delay
+		setTimeout(() => {
+			if (this.mounted && !this.destroyed) {
+				this.show();
+			}
+		}, this.showDelay);
+		return popup;
+	}
+	_attachEvents() {
+		const popup = this.element;
+		// Close button
+		popup.querySelector('.popup-close').addEventListener('click', () => {
+			this.hide();
+		});
+		// Rating buttons
+		popup.querySelectorAll('.popup-btn').forEach((btn) => {
+			btn.addEventListener('click', (e) => {
+				const rating = e.target.classList.contains('good')
+					? 5
+					: e.target.classList.contains('okay')
+						? 3
+						: 1;
+				this.submitQuickFeedback(rating);
+				this.hide();
+			});
+		});
+	}
+	async submitQuickFeedback(rating) {
+		try {
+			const payload = {
+				title: `Quick Feedback - Rating: ${rating}`,
+				content: `User gave a ${rating}/5 rating`,
+				board_id: this.options.boardId,
+			};
+			await this.apiService.submitFeedback(payload);
+			this.sdk.eventBus.emit('feedback:submitted', { widget: this, rating });
+		} catch (error) {
+			this.sdk.eventBus.emit('feedback:error', { widget: this, error });
+		}
+	}
+}
+// Register the custom widget
+FeedbackSDK.WidgetFactory.register('popup', PopupWidget);
+// Use the custom widget
+const feedback = new FeedbackSDK({
+	workspace: 'my-company',
+	boardId: 'popup-feedback',
+});
+await feedback.init();
+const popupWidget = feedback.createWidget('popup', {
+	showDelay: 3000, // Show after 3 seconds
+});
+popupWidget.mount();
+```
+## 💡 Best Practices Examples
+### Performance Optimization
+Lazy load the SDK when needed:
+```javascript
+// Lazy load function
+async function loadFeedbackSDK() {
+	if (window.FeedbackSDK) {
+		return window.FeedbackSDK;
+	}
+	return new Promise((resolve) => {
+		const script = document.createElement('script');
+		script.src =
+			'https://cdn.jsdelivr.net/npm/@product7/feedback-sdk@1/dist/feedback-sdk.min.js';
+		script.onload = () => resolve(window.FeedbackSDK);
+		document.head.appendChild(script);
+	});
+}
+// Load SDK only when user interacts with feedback trigger
+document
+	.getElementById('feedback-trigger')
+	.addEventListener('click', async () => {
+		const FeedbackSDK = await loadFeedbackSDK();
+		const feedback = new FeedbackSDK({
+			workspace: 'my-company',
+			boardId: 'lazy-feedback',
+		});
+		await feedback.init();
+		const widget = feedback.createWidget('button');
+		widget.mount();
+		// Open modal immediately
+		widget.openModal();
+	});
+```
+### Error Handling
+Robust error handling and fallbacks:
+```javascript
+async function initializeFeedback() {
+	try {
+		const feedback = new FeedbackSDK({
+			workspace: 'my-company',
+			boardId: 'error-handling-feedback',
+			debug: true,
+		});
+		await feedback.init();
+		// Set up comprehensive error handling
+		feedback.eventBus.on('feedback:error', (error) => {
+			console.error('Feedback error:', error);
+			// Show user-friendly error message
+			const errorMsg = getUserFriendlyErrorMessage(error.error);
+			showNotification(errorMsg, 'error');
+			// Track error for monitoring
+			if (window.Sentry) {
+				Sentry.captureException(error.error);
+			}
+		});
+		const widget = feedback.createWidget('button');
+		widget.mount();
+		// Success tracking
+		feedback.eventBus.on('feedback:submitted', () => {
+			showNotification('Feedback submitted successfully!', 'success');
+		});
+	} catch (initError) {
+		console.error('Failed to initialize feedback SDK:', initError);
+		// Fallback: show simple mailto link
+		showFallbackFeedback();
+	}
+}
+function getUserFriendlyErrorMessage(error) {
+	if (error.name === 'APIError') {
+		if (error.status === 0) {
+			return 'Network error. Please check your connection.';
+		} else if (error.status >= 500) {
+			return 'Server error. Please try again later.';
+		}
+	}
+	return 'Failed to submit feedback. Please try again.';
+}
+function showFallbackFeedback() {
+	const fallback = document.createElement('div');
+	fallback.innerHTML = `
+        <div style="position: fixed; bottom: 20px; right: 20px; z-index: 9999;">
+            <a href="mailto:feedback@my-company.com?subject=Website Feedback"
+               style="background: #155EEF; color: white; padding: 12px 20px;
+                      border-radius: 25px; text-decoration: none;">
+                Send Feedback
+            </a>
+        </div>
+    `;
+	document.body.appendChild(fallback);
+}
+function showNotification(message, type) {
+	// Your notification system
+	console.log(`${type}: ${message}`);
+}
+// Initialize with error handling
+initializeFeedback();
+```