@product7/feedback-sdk 1.0.1

package/src/docs/api.md

@@ -0,0 +1,686 @@
+# API Reference
+
+Complete reference for the Feedback Widget SDK API.
+
+## 🏗️ FeedbackSDK Class
+
+The main SDK class that manages widgets and configuration.
+
+### Constructor
+
+```javascript
+new FeedbackSDK(config);
+```
+
+**Parameters:**
+
+- `config` (Object) - SDK configuration object
+
+**Example:**
+
+```javascript
+const feedback = new FeedbackSDK({
+	workspace: 'my-workspace',
+	boardId: 'board-123',
+	theme: 'light',
+});
+```
+
+### Methods
+
+#### `init(): Promise<FeedbackSDK>`
+
+Initialize the SDK and prepare it for use.
+
+**Returns:** Promise that resolves to the SDK instance
+
+**Example:**
+
+```javascript
+await feedback.init();
+// or
+feedback.init().then(() => {
+	console.log('SDK ready');
+});
+```
+
+#### `createWidget(type, options?): Widget`
+
+Create a new widget instance.
+
+**Parameters:**
+
+- `type` (String) - Widget type: `'button'`, `'tab'`, or `'inline'`
+- `options` (Object) - Widget-specific options
+
+**Returns:** Widget instance
+
+**Example:**
+
+```javascript
+const widget = feedback.createWidget('button', {
+	position: 'bottom-right',
+	theme: 'dark',
+});
+```
+
+#### `getWidget(id): Widget | undefined`
+
+Get a widget by its ID.
+
+**Parameters:**
+
+- `id` (String) - Widget ID
+
+**Returns:** Widget instance or undefined
+
+**Example:**
+
+```javascript
+const widget = feedback.getWidget('widget_123');
+if (widget) {
+	widget.show();
+}
+```
+
+#### `destroyWidget(id): void`
+
+Destroy a specific widget.
+
+**Parameters:**
+
+- `id` (String) - Widget ID
+
+**Example:**
+
+```javascript
+feedback.destroyWidget('widget_123');
+```
+
+#### `updateConfig(newConfig): void`
+
+Update SDK configuration.
+
+**Parameters:**
+
+- `newConfig` (Object) - Configuration updates
+
+**Example:**
+
+```javascript
+feedback.updateConfig({
+	theme: 'dark',
+	position: 'top-left',
+});
+```
+
+#### `destroy(): void`
+
+Destroy the SDK and all widgets.
+
+**Example:**
+
+```javascript
+feedback.destroy();
+```
+
+### Properties
+
+#### `config: Object`
+
+Current SDK configuration (read-only)
+
+#### `widgets: Map<String, Widget>`
+
+Map of all created widgets (read-only)
+
+#### `eventBus: EventBus`
+
+Event bus for SDK communication
+
+#### `initialized: Boolean`
+
+Whether the SDK is initialized (read-only)
+
+---
+
+## 🎛️ Widget Classes
+
+### BaseWidget
+
+Base class for all widgets. Not used directly.
+
+#### Methods
+
+##### `mount(container?): Widget`
+
+Mount the widget to the DOM.
+
+**Parameters:**
+
+- `container` (String | Element) - CSS selector or DOM element. Defaults to `document.body`
+
+**Returns:** Widget instance for chaining
+
+**Example:**
+
+```javascript
+widget.mount('#my-container');
+// or
+widget.mount(document.getElementById('container'));
+```
+
+##### `show(): Widget`
+
+Show the widget.
+
+**Example:**
+
+```javascript
+widget.show();
+```
+
+##### `hide(): Widget`
+
+Hide the widget.
+
+**Example:**
+
+```javascript
+widget.hide();
+```
+
+##### `openModal(): void`
+
+Open the feedback modal (button and tab widgets only).
+
+**Example:**
+
+```javascript
+widget.openModal();
+```
+
+##### `closeModal(): void`
+
+Close the feedback modal.
+
+**Example:**
+
+```javascript
+widget.closeModal();
+```
+
+##### `destroy(): void`
+
+Destroy the widget and clean up.
+
+**Example:**
+
+```javascript
+widget.destroy();
+```
+
+#### Properties
+
+##### `id: String`
+
+Unique widget ID (read-only)
+
+##### `type: String`
+
+Widget type (read-only)
+
+##### `mounted: Boolean`
+
+Whether widget is mounted (read-only)
+
+##### `destroyed: Boolean`
+
+Whether widget is destroyed (read-only)
+
+##### `state: Object`
+
+Widget state object
+
+### ButtonWidget
+
+Floating button widget.
+
+#### Additional Methods
+
+##### `updateText(text): void`
+
+Update button text.
+
+**Example:**
+
+```javascript
+buttonWidget.updateText('Send Feedback');
+```
+
+##### `updatePosition(position): void`
+
+Update button position.
+
+**Parameters:**
+
+- `position` (String) - Position: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`
+
+**Example:**
+
+```javascript
+buttonWidget.updatePosition('top-left');
+```
+
+### TabWidget
+
+Side tab widget.
+
+#### Additional Methods
+
+##### `updateText(text): void`
+
+Update tab text.
+
+**Example:**
+
+```javascript
+tabWidget.updateText('Feedback');
+```
+
+##### `updatePosition(position): void`
+
+Update tab position.
+
+**Example:**
+
+```javascript
+tabWidget.updatePosition('bottom-left');
+```
+
+### InlineWidget
+
+Inline form widget.
+
+#### Additional Methods
+
+##### `updateTitle(title): void`
+
+Update form title.
+
+**Example:**
+
+```javascript
+inlineWidget.updateTitle('Share your thoughts');
+```
+
+##### `setPlaceholder(field, placeholder): void`
+
+Set placeholder text for form fields.
+
+**Parameters:**
+
+- `field` (String) - Field name: `'title'`, `'content'`, `'email'`
+- `placeholder` (String) - Placeholder text
+
+**Example:**
+
+```javascript
+inlineWidget.setPlaceholder('content', 'Tell us what you think...');
+```
+
+---
+
+## 📡 EventBus
+
+Event system for SDK communication.
+
+### Methods
+
+#### `on(event, callback): Function`
+
+Subscribe to an event.
+
+**Parameters:**
+
+- `event` (String) - Event name
+- `callback` (Function) - Event handler
+
+**Returns:** Unsubscribe function
+
+**Example:**
+
+```javascript
+const unsubscribe = feedback.eventBus.on('feedback:submitted', (data) => {
+	console.log('Feedback submitted:', data);
+});
+
+// Later, unsubscribe
+unsubscribe();
+```
+
+#### `off(event, callback): void`
+
+Unsubscribe from an event.
+
+**Example:**
+
+```javascript
+const handler = (data) => console.log(data);
+feedback.eventBus.on('feedback:submitted', handler);
+feedback.eventBus.off('feedback:submitted', handler);
+```
+
+#### `emit(event, data): void`
+
+Emit an event.
+
+**Example:**
+
+```javascript
+feedback.eventBus.emit('custom:event', { message: 'Hello' });
+```
+
+#### `once(event, callback): Function`
+
+Subscribe to an event once.
+
+**Example:**
+
+```javascript
+feedback.eventBus.once('sdk:ready', () => {
+	console.log('SDK is ready!');
+});
+```
+
+### Events
+
+#### SDK Events
+
+##### `sdk:ready`
+
+Fired when SDK initialization completes.
+
+**Data:**
+
+```javascript
+{
+	config: Object; // SDK configuration
+}
+```
+
+##### `sdk:destroyed`
+
+Fired when SDK is destroyed.
+
+##### `config:updated`
+
+Fired when SDK configuration is updated.
+
+**Data:**
+
+```javascript
+{
+	// Updated configuration object
+}
+```
+
+#### Widget Events
+
+##### `widget:mounted`
+
+Fired when a widget is mounted.
+
+**Data:**
+
+```javascript
+{
+	widget: Widget; // Widget instance
+}
+```
+
+##### `widget:destroyed`
+
+Fired when a widget is destroyed.
+
+**Data:**
+
+```javascript
+{
+	widget: Widget; // Widget instance
+}
+```
+
+#### Feedback Events
+
+##### `feedback:submitted`
+
+Fired when feedback is successfully submitted.
+
+**Data:**
+
+```javascript
+{
+    widget: Widget, // Widget that submitted
+    feedback: Object // Server response
+}
+```
+
+##### `feedback:error`
+
+Fired when feedback submission fails.
+
+**Data:**
+
+```javascript
+{
+    widget: Widget, // Widget that failed
+    error: Error    // Error object
+}
+```
+
+---
+
+## 🏭 WidgetFactory
+
+Factory for creating widgets.
+
+### Static Methods
+
+#### `register(type, WidgetClass): void`
+
+Register a custom widget type.
+
+**Parameters:**
+
+- `type` (String) - Widget type name
+- `WidgetClass` (Class) - Widget class constructor
+
+**Example:**
+
+```javascript
+class CustomWidget extends BaseWidget {
+	// Custom implementation
+}
+
+WidgetFactory.register('custom', CustomWidget);
+```
+
+#### `create(type, options): Widget`
+
+Create a widget instance.
+
+**Parameters:**
+
+- `type` (String) - Widget type
+- `options` (Object) - Widget options
+
+**Returns:** Widget instance
+
+#### `getAvailableTypes(): Array<String>`
+
+Get all registered widget types.
+
+**Returns:** Array of type names
+
+**Example:**
+
+```javascript
+const types = WidgetFactory.getAvailableTypes();
+console.log(types); // ['button', 'tab', 'inline']
+```
+
+#### `isTypeRegistered(type): Boolean`
+
+Check if a widget type is registered.
+
+**Example:**
+
+```javascript
+if (WidgetFactory.isTypeRegistered('custom')) {
+	// Type is available
+}
+```
+
+---
+
+## 🌐 APIService
+
+Service for API communication.
+
+### Methods
+
+#### `submitFeedback(payload): Promise<Object>`
+
+Submit feedback to the API.
+
+**Parameters:**
+
+- `payload` (Object) - Feedback data
+
+**Example:**
+
+```javascript
+const response = await feedback.apiService.submitFeedback({
+	title: 'Bug Report',
+	content: 'Found a bug...',
+	email: 'user@example.com',
+});
+```
+
+#### `uploadFile(file): Promise<Object>`
+
+Upload a file attachment.
+
+**Parameters:**
+
+- `file` (File) - File object
+
+**Returns:** Object with file URL
+
+---
+
+## 🚨 Error Classes
+
+### SDKError
+
+General SDK errors.
+
+**Properties:**
+
+- `name` (String) - 'SDKError'
+- `message` (String) - Error message
+- `cause` (Error) - Original error (if any)
+
+### APIError
+
+API-related errors.
+
+**Properties:**
+
+- `name` (String) - 'APIError'
+- `message` (String) - Error message
+- `status` (Number) - HTTP status code
+- `response` (Object) - Server response
+
+**Methods:**
+
+- `isNetworkError()` - Returns true if network error
+- `isClientError()` - Returns true if 4xx error
+- `isServerError()` - Returns true if 5xx error
+
+### WidgetError
+
+Widget-related errors.
+
+**Properties:**
+
+- `name` (String) - 'WidgetError'
+- `widgetType` (String) - Widget type
+- `widgetId` (String) - Widget ID
+
+---
+
+## 🛠️ Utility Helpers
+
+Utility functions available at `feedback.helpers` or by importing directly.
+
+### `generateId(prefix?): String`
+
+Generate a unique ID.
+
+**Example:**
+
+```javascript
+const id = generateId('widget'); // 'widget_1234567890_abc123'
+```
+
+### `isValidEmail(email): Boolean`
+
+Validate email address.
+
+**Example:**
+
+```javascript
+const valid = isValidEmail('user@example.com'); // true
+```
+
+### `debounce(func, wait): Function`
+
+Debounce a function.
+
+**Example:**
+
+```javascript
+const debouncedSearch = debounce(searchFunction, 300);
+```
+
+### `isMobile(): Boolean`
+
+Check if running on mobile device.
+
+**Example:**
+
+```javascript
+if (isMobile()) {
+	// Mobile-specific behavior
+}
+```
+
+---
+
+## 📚 TypeScript Definitions
+
+The SDK includes full TypeScript definitions:
+
+```typescript
+import { FeedbackSDK, ButtonWidget, SDKConfig } from '@product7/feedback-sdk';
+
+const config: SDKConfig = {
+	workspace: 'my-workspace',
+	boardId: 'board-123',
+};
+
+const sdk = new FeedbackSDK(config);
+const widget: ButtonWidget = sdk.createWidget('button');
+```