@product7/product7-js 0.1.0

package/src/docs/example.md

@@ -0,0 +1,461 @@
+# Examples
+
+## Basic Usage
+
+### Simple Setup
+
+```javascript
+import Product7 from '@product7/product7-js';
+
+const sdk = new Product7({
+	workspace: 'my-workspace',
+	metadata: {
+		user_id: 'user_123',
+		email: 'user@example.com',
+	},
+});
+
+await sdk.init();
+
+const widget = sdk.createWidget('button');
+widget.mount();
+```
+
+---
+
+## User Context
+
+### Basic User Context
+
+```javascript
+const sdk = new Product7({
+	workspace: 'my-workspace',
+	metadata: {
+		user_id: 'user_123',
+		email: 'user@example.com',
+		name: 'John Doe',
+	},
+});
+```
+
+### With Custom Fields
+
+```javascript
+metadata: {
+	user_id: 'user_123',
+	email: 'user@example.com',
+	name: 'John Doe',
+	custom_fields: {
+		role: 'admin',
+		plan: 'pro',
+		signup_date: '2024-01-01'
+	}
+}
+```
+
+### With Company Data
+
+```javascript
+metadata: {
+	user_id: 'user_123',
+	email: 'user@example.com',
+	name: 'John Doe',
+	company: {
+		id: 'company_456',
+		name: 'Acme Corp',
+		monthly_spend: 1000
+	}
+}
+```
+
+### Extract from Auth
+
+```javascript
+const authData = {
+	sub: 'user_123',
+	email: 'user@example.com',
+	name: 'John Doe',
+	role: 'admin',
+};
+
+const metadata = Product7.extractMetadataFromAuth(authData);
+
+const sdk = new Product7({
+	workspace: 'my-workspace',
+	metadata,
+});
+```
+
+---
+
+## Widget Customization
+
+### Different Positions
+
+```javascript
+// Bottom right (default)
+const widget1 = sdk.createWidget('button', {
+	position: 'bottom-right',
+});
+
+// Bottom left
+const widget2 = sdk.createWidget('button', {
+	position: 'bottom-left',
+});
+
+// Top right
+const widget3 = sdk.createWidget('button', {
+	position: 'top-right',
+});
+
+// Top left
+const widget4 = sdk.createWidget('button', {
+	position: 'top-left',
+});
+```
+
+### Dark Theme
+
+```javascript
+const widget = sdk.createWidget('button', {
+	theme: 'dark',
+});
+widget.mount();
+```
+
+### Custom Board
+
+```javascript
+const widget = sdk.createWidget('button', {
+	boardName: 'feature-requests',
+});
+widget.mount();
+```
+
+### Multiple Widgets
+
+```javascript
+// Feedback button
+const feedbackWidget = sdk.createWidget('button', {
+	position: 'bottom-right',
+	boardName: 'general',
+});
+feedbackWidget.mount();
+
+// Bug report button
+const bugWidget = sdk.createWidget('button', {
+	position: 'bottom-left',
+	boardName: 'bug-reports',
+});
+bugWidget.updateText('Report Bug');
+bugWidget.mount();
+```
+
+### Update Widget
+
+```javascript
+const widget = sdk.createWidget('button');
+widget.mount();
+
+// Update text
+widget.updateText('Send Feedback');
+
+// Update position
+widget.updatePosition('top-right');
+
+// Show/hide
+widget.hide();
+widget.show();
+```
+
+---
+
+## Event Handling
+
+### Track Submissions
+
+```javascript
+sdk.on('feedback:submitted', ({ widget, feedback }) => {
+	console.log('Feedback submitted:', feedback.id);
+
+	// Track in analytics
+	analytics.track('Feedback Submitted', {
+		feedbackId: feedback.id,
+		board: feedback.board,
+	});
+});
+```
+
+### Handle Errors
+
+```javascript
+sdk.on('feedback:error', ({ widget, error }) => {
+	console.error('Submission failed:', error.message);
+
+	// Show custom error notification
+	toast.error('Failed to submit feedback. Please try again.');
+});
+```
+
+### Widget Lifecycle
+
+```javascript
+sdk.on('widget:mounted', ({ widget }) => {
+	console.log('Widget mounted:', widget.id);
+});
+
+sdk.on('widget:destroyed', ({ widget }) => {
+	console.log('Widget destroyed:', widget.id);
+});
+```
+
+### Multiple Events
+
+```javascript
+sdk
+	.on('feedback:submitted', handleSubmit)
+	.on('feedback:error', handleError)
+	.on('config:updated', handleConfigUpdate);
+```
+
+### One-time Events
+
+```javascript
+sdk.once('sdk:initialized', (data) => {
+	console.log('SDK ready!', data.config);
+});
+```
+
+---
+
+## Authentication Flows
+
+### On Login
+
+```javascript
+async function handleLogin(authResponse) {
+	const metadata = Product7.extractMetadataFromAuth(authResponse);
+	await sdk.reinitialize(metadata);
+
+	// Create widget after login
+	const widget = sdk.createWidget('button');
+	widget.mount();
+}
+```
+
+### On Logout
+
+```javascript
+function handleLogout() {
+	sdk.apiService.clearSession();
+	sdk.destroyAllWidgets();
+}
+```
+
+### Check Session
+
+```javascript
+if (!sdk.apiService.isSessionValid()) {
+	await sdk.init();
+}
+```
+
+---
+
+## Configuration Updates
+
+### Update Theme
+
+```javascript
+sdk.updateConfig({ theme: 'dark' });
+```
+
+### Update Multiple Options
+
+```javascript
+sdk.updateConfig({
+	theme: 'dark',
+	position: 'top-right',
+	showBackdrop: false,
+});
+```
+
+### Update User Context
+
+```javascript
+sdk.setMetadata({
+	user_id: 'user_456',
+	email: 'newuser@example.com',
+	name: 'Jane Smith',
+});
+```
+
+---
+
+## Programmatic Control
+
+### Open Panel Programmatically
+
+```javascript
+const widget = sdk.createWidget('button');
+widget.mount();
+
+// Open panel from code
+setTimeout(() => {
+	widget.openPanel();
+}, 3000);
+```
+
+### Close Panel
+
+```javascript
+widget.closePanel();
+```
+
+### Trigger from Custom Button
+
+```javascript
+const customButton = document.getElementById('feedback-btn');
+customButton.addEventListener('click', () => {
+	const widget = sdk.getWidget('widget_123');
+	if (widget) {
+		widget.openPanel();
+	}
+});
+```
+
+---
+
+## Error Handling
+
+### Try-Catch Pattern
+
+```javascript
+try {
+	await sdk.init();
+	const widget = sdk.createWidget('button');
+	widget.mount();
+} catch (error) {
+	if (error instanceof ConfigError) {
+		console.error('Config error:', error.message);
+	} else if (error instanceof APIError) {
+		console.error('API error:', error.status);
+	} else {
+		console.error('Unexpected error:', error);
+	}
+}
+```
+
+### Handle API Errors
+
+```javascript
+try {
+	await sdk.apiService.submitFeedback(data);
+} catch (error) {
+	if (error.isNetworkError()) {
+		alert('No internet connection');
+	} else if (error.isClientError()) {
+		alert('Invalid data. Please check your input.');
+	} else if (error.isServerError()) {
+		alert('Server error. Please try again later.');
+	}
+}
+```
+
+---
+
+## Advanced Usage
+
+### Custom Widget Creation
+
+```javascript
+import { BaseWidget, WidgetFactory } from '@product7/product7-js';
+
+class CustomWidget extends BaseWidget {
+	constructor(options) {
+		super({ ...options, type: 'custom' });
+	}
+
+	_render() {
+		const element = document.createElement('div');
+		element.innerHTML = '<button>Custom Feedback</button>';
+		return element;
+	}
+
+	_attachEvents() {
+		this.element
+			.querySelector('button')
+			.addEventListener('click', this.openPanel);
+	}
+}
+
+WidgetFactory.register('custom', CustomWidget);
+
+const widget = sdk.createWidget('custom');
+widget.mount();
+```
+
+### Conditional Widget Loading
+
+```javascript
+// Only show feedback for authenticated users
+if (user.isAuthenticated) {
+	const sdk = new Product7({
+		workspace: 'my-workspace',
+		metadata: {
+			user_id: user.id,
+			email: user.email,
+		},
+	});
+
+	await sdk.init();
+	const widget = sdk.createWidget('button');
+	widget.mount();
+}
+```
+
+### Environment-based Configuration
+
+```javascript
+const config = {
+	workspace: 'my-workspace',
+	metadata: getMetadata(),
+	apiUrl:
+		process.env.NODE_ENV === 'production'
+			? 'https://api.product7.io/api/v1'
+			: 'https://staging.api.product7.io/api/v1',
+	debug: process.env.NODE_ENV === 'development',
+};
+
+const sdk = new Product7(config);
+```
+
+---
+
+## Testing
+
+### Mock SDK
+
+```javascript
+// In tests
+jest.mock('@product7/product7-js');
+
+test('should initialize SDK', async () => {
+	const sdk = new Product7({
+		workspace: 'test',
+		metadata: { user_id: '123' },
+	});
+	await sdk.init();
+	expect(sdk.initialized).toBe(true);
+});
+```
+
+### Check Widget Exists
+
+```javascript
+const widget = sdk.createWidget('button');
+widget.mount();
+
+const found = sdk.getWidget(widget.id);
+expect(found).toBeDefined();
+```