@product7/feedback-sdk 1.0.6 → 1.0.8

package/src/docs/api.md

@@ -1,686 +1,192 @@
 # API Reference
 
-Complete reference for the Feedback Widget SDK API.
-
-## 🏗️ FeedbackSDK Class
-
-The main SDK class that manages widgets and configuration.
+## FeedbackSDK
 
 ### Constructor
 
 ```javascript
-new FeedbackSDK(config);
+new FeedbackSDK(config)
 ```
 
-**Parameters:**
-
-- `config` (Object) - SDK configuration object
+**Config Options:**
 
-**Example:**
-
-```javascript
-const feedback = new FeedbackSDK({
-	workspace: 'my-workspace',
-	boardId: 'board-123',
-	theme: 'light',
-});
-```
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `workspace` | String | Yes | - | Workspace identifier |
+| `userContext` | Object | Yes | - | User identification |
+| `apiUrl` | String | No | Auto | Custom API endpoint |
+| `boardId` | String | No | `'general'` | Default board |
+| `theme` | String | No | `'light'` | `'light'` or `'dark'` |
+| `position` | String | No | `'bottom-right'` | Widget position |
+| `showBackdrop` | Boolean | No | `true` | Show panel backdrop |
+| `debug` | Boolean | No | `false` | Debug logging |
 
 ### 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');
-});
-```
+#### `async init(): Promise<Object>`
+Initialize SDK and create session.
 
 #### `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',
-});
-```
+Create widget. Type: `'button'`.
 
 #### `getWidget(id): Widget | undefined`
+Get widget by ID.
 
-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`
+#### `getAllWidgets(): Array<Widget>`
+Get all widgets.
 
-Destroy a specific widget.
+#### `destroyWidget(id): Boolean`
+Destroy widget by ID.
 
-**Parameters:**
+#### `destroyAllWidgets(): void`
+Destroy all widgets.
 
-- `id` (String) - Widget ID
+#### `updateConfig(config): void`
+Update configuration.
 
-**Example:**
+#### `setUserContext(userContext): void`
+Update user context.
 
-```javascript
-feedback.destroyWidget('widget_123');
-```
-
-#### `updateConfig(newConfig): void`
+#### `getUserContext(): Object | null`
+Get current user context.
 
-Update SDK configuration.
+#### `async reinitialize(userContext?): Promise<Object>`
+Reinitialize with new user.
 
-**Parameters:**
+#### `on(event, callback): FeedbackSDK`
+Subscribe to event.
 
-- `newConfig` (Object) - Configuration updates
+#### `off(event, callback): FeedbackSDK`
+Unsubscribe from event.
 
-**Example:**
-
-```javascript
-feedback.updateConfig({
-	theme: 'dark',
-	position: 'top-left',
-});
-```
+#### `once(event, callback): FeedbackSDK`
+Subscribe once.
 
 #### `destroy(): void`
+Destroy SDK.
 
-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`
+### Static Methods
 
-Event bus for SDK communication
+#### `FeedbackSDK.create(config): FeedbackSDK`
+Create SDK instance.
 
-#### `initialized: Boolean`
+#### `async FeedbackSDK.createAndInit(config): Promise<FeedbackSDK>`
+Create and initialize.
 
-Whether the SDK is initialized (read-only)
+#### `FeedbackSDK.extractUserContextFromAuth(authData): Object`
+Extract user context from auth.
 
 ---
 
-## 🎛️ Widget Classes
+## Widget
 
-### BaseWidget
-
-Base class for all widgets. Not used directly.
+### ButtonWidget
 
 #### 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'));
-```
+Mount to DOM.
 
 ##### `show(): Widget`
-
-Show the widget.
-
-**Example:**
-
-```javascript
-widget.show();
-```
+Show widget.
 
 ##### `hide(): Widget`
+Hide widget.
 
-Hide the widget.
-
-**Example:**
-
-```javascript
-widget.hide();
-```
-
-##### `openModal(): void`
+##### `openPanel(): void`
+Open feedback panel.
 
-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
+##### `closePanel(): void`
+Close panel.
 
 ##### `updateText(text): void`
-
 Update button text.
 
-**Example:**
-
-```javascript
-buttonWidget.updateText('Send Feedback');
-```
-
 ##### `updatePosition(position): void`
+Update position.
 
-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`
+##### `destroy(): void`
+Destroy widget.
 
-Fired when feedback submission fails.
+#### Properties
 
-**Data:**
-
-```javascript
-{
-    widget: Widget, // Widget that failed
-    error: Error    // Error object
-}
-```
+- `id: String` - Widget ID
+- `type: String` - Widget type
+- `mounted: Boolean` - Mount status
+- `state: Object` - Widget state
 
 ---
 
-## 🏭 WidgetFactory
+## Events
 
-Factory for creating widgets.
-
-### Static Methods
+### SDK Events
 
-#### `register(type, WidgetClass): void`
+- `sdk:initialized` - SDK ready
+- `sdk:error` - Error occurred
+- `sdk:destroyed` - SDK destroyed
+- `config:updated` - Config changed
+- `user:updated` - User changed
 
-Register a custom widget type.
+### Widget Events
 
-**Parameters:**
+- `widget:created` - Widget created
+- `widget:mounted` - Widget mounted
+- `widget:destroyed` - Widget destroyed
+- `widgets:cleared` - All cleared
 
-- `type` (String) - Widget type name
-- `WidgetClass` (Class) - Widget class constructor
+### Feedback Events
 
-**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
-}
-```
+- `feedback:submitted` - Feedback sent
+- `feedback:error` - Submission failed
 
 ---
 
-## 🌐 APIService
+## APIService
 
-Service for API communication.
+Access via `sdk.apiService`.
 
 ### 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.
+#### `async init(userContext?): Promise<Object>`
+Initialize session.
 
-**Parameters:**
+#### `async submitFeedback(data): Promise<Object>`
+Submit feedback.
 
-- `file` (File) - File object
+#### `isSessionValid(): Boolean`
+Check session validity.
 
-**Returns:** Object with file URL
+#### `clearSession(): void`
+Clear session.
 
 ---
 
-## 🚨 Error Classes
+## Error Classes
 
 ### SDKError
-
 General SDK errors.
 
-**Properties:**
-
-- `name` (String) - 'SDKError'
-- `message` (String) - Error message
-- `cause` (Error) - Original error (if any)
-
 ### APIError
+API errors with methods:
+- `isNetworkError()`
+- `isClientError()`
+- `isServerError()`
 
-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
+### ConfigError
+Configuration errors.
 
 ### 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
-}
-```
+Widget errors.
 
 ---
 
-## 📚 TypeScript Definitions
+## Utilities
 
-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');
-```
+- `generateId(prefix?)`
+- `deepMerge(target, source)`
+- `debounce(func, wait)`
+- `throttle(func, limit)`
+- `isValidEmail(email)`
+- `isMobile()`
+- `formatFileSize(bytes)`
+- `delay(ms)`