@product7/product7-js 0.3.1 → 0.3.4

package/src/docs/api.md

@@ -8,40 +8,95 @@
 new Product7(config);
 ```
 
-**Config Options:**
-
-| Option         | Type    | Required | Default          | Description           |
-| -------------- | ------- | -------- | ---------------- | --------------------- |
-| `workspace`    | String  | Yes      | -                | Workspace identifier  |
-| `metadata`     | Object  | Yes      | -                | User identification   |
-| `apiUrl`       | String  | No       | Auto             | Custom API endpoint   |
-| `boardName`    | 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         |
+### Config Options
 
-### Methods
+| Option      | Type      | Required | Default     | Description                    |
+| ----------- | --------- | -------- | ----------- | ------------------------------ |
+| `workspace` | `string`  | Yes      | -           | Workspace identifier           |
+| `boardName` | `string`  | No       | `'general'` | Default feedback board         |
+| `apiUrl`    | `string`  | No       | Auto        | Custom API endpoint            |
+| `theme`     | `string`  | No       | `'light'`   | Default widget theme           |
+| `position`  | `string`  | No       | `'right'`   | Default widget position        |
+| `debug`     | `boolean` | No       | `false`     | Enable debug logging           |
+| `mock`      | `boolean` | No       | `false`     | Use mock responses             |
+| `metadata`  | `object`  | No       | `null`      | Optional legacy identify input |
+
+### Lifecycle
 
 #### `async init(): Promise<Object>`
 
-Initialize SDK and create session.
+Initializes the SDK session for the configured workspace.
+
+```javascript
+await sdk.init();
+```
+
+#### `async identify(metadata): Promise<Object>`
+
+Associates the current session with a user after `init()`.
+
+```javascript
+await sdk.identify({
+	user_id: 'user_123',
+	email: 'user@example.com',
+	name: 'Jane Doe',
+});
+```
+
+#### `destroy(): void`
+
+Destroys widgets, clears the session, and tears down event listeners.
+
+### Widget Factory Methods
+
+#### `createFeedbackWidget(options?): FeedbackWidget`
+
+Creates the feedback widget.
+
+```javascript
+const widget = sdk.createFeedbackWidget({
+	position: 'bottom-right',
+	headless: true,
+});
+```
+
+#### `createMessengerWidget(options?): MessengerWidget`
+
+Creates the messenger widget.
+
+#### `createChangelogWidget(options?): ChangelogWidget`
+
+Creates the changelog widget.
+
+#### `createSurveyWidget(options?): SurveyWidget`
+
+Creates the survey widget.
 
 #### `createWidget(type, options?): Widget`
 
-Create widget. Type: `'button'`.
+Low-level factory for advanced usage. Supported types include:
+
+- `'feedback'`
+- `'button'` (legacy alias for feedback)
+- `'messenger'`
+- `'survey'`
+- `'changelog'`
+- `'inline'`
+- `'tab'`
+
+### Other Instance Methods
 
 #### `getWidget(id): Widget | undefined`
 
-Get widget by ID.
+Get a widget by ID.
 
-#### `getAllWidgets(): Array<Widget>`
+#### `getAllWidgets(): Widget[]`
 
-Get all widgets.
+Get all widgets created by this SDK instance.
 
-#### `destroyWidget(id): Boolean`
+#### `destroyWidget(id): boolean`
 
-Destroy widget by ID.
+Destroy a single widget by ID.
 
 #### `destroyAllWidgets(): void`
 
@@ -49,96 +104,174 @@ Destroy all widgets.
 
 #### `updateConfig(config): void`
 
-Update configuration.
+Update SDK config and propagate the change to mounted widgets.
 
 #### `setMetadata(metadata): void`
 
-Update user context.
+Update stored metadata locally. This does not replace `identify()`.
 
 #### `getMetadata(): Object | null`
 
-Get current user context.
+Get the currently stored metadata.
 
 #### `async reinitialize(metadata?): Promise<Object>`
 
-Reinitialize with new user.
-
-#### `on(event, callback): Product7`
+Clear the current session and initialize again. If metadata is passed, it will be stored and automatically identified after the new session is created.
 
-Subscribe to event.
+#### `async getActiveSurveys(context?): Promise<Array>`
 
-#### `off(event, callback): Product7`
+Fetch active surveys for the current session.
 
-Unsubscribe from event.
+#### `async showSurveyById(surveyId, options?): Promise<SurveyWidget | null>`
 
-#### `once(event, callback): Product7`
+Find and display a survey by ID.
 
-Subscribe once.
+#### `showSurvey(options?): SurveyWidget | null`
 
-#### `destroy(): void`
+Render a survey directly from options.
 
-Destroy SDK.
+#### `showChangelog(options?): ChangelogWidget | null`
 
-### Static Methods
+Create, mount, and show a changelog widget.
 
-#### `Product7.create(config): Product7`
+#### `async getChangelogs(options?): Promise<Array>`
 
-Create SDK instance.
+Fetch changelog items.
 
-#### `async Product7.createAndInit(config): Promise<Product7>`
+#### `on(event, callback): Product7`
 
-Create and initialize.
+Subscribe to an SDK event.
 
-#### `Product7.extractMetadataFromAuth(authData): Object`
+#### `off(event, callback): Product7`
 
-Extract user context from auth.
+Unsubscribe from an SDK event.
 
----
+#### `once(event, callback): Product7`
 
-## Widget
+Subscribe to an event once.
 
-### ButtonWidget
+---
 
-#### Methods
+## FeedbackWidget
 
-##### `mount(container?): Widget`
+Created by `sdk.createFeedbackWidget()` or `sdk.createWidget('feedback', ...)`.
 
-Mount to DOM.
+### Methods
 
-##### `show(): Widget`
+- `mount(container?): this`
+- `destroy(): void`
+- `show(): this`
+- `hide(): this`
+- `open(): this`
+- `close(): this`
+- `toggle(): this`
+- `openPanel(): void`
+- `closePanel(): void`
+- `openModal(): void`
+- `closeModal(): void`
+- `updateText(text): void`
+- `updatePosition(position): void`
+
+### Common Options
+
+- `boardName`
+- `position`
+- `theme`
+- `displayMode`
+- `headless`
+- `trigger`
+- `primaryColor`
+- `backgroundColor`
+- `textColor`
 
-Show widget.
+---
 
-##### `hide(): Widget`
+## MessengerWidget
 
-Hide widget.
+Created by `sdk.createMessengerWidget()`.
 
-##### `openPanel(): void`
+### Methods
 
-Open feedback panel.
+- `mount(container?): this`
+- `destroy(): void`
+- `open(): void`
+- `close(): void`
+- `toggle(): void`
+- `navigateTo(view): void`
+- `setConversations(conversations): void`
+- `setHelpArticles(articles): void`
+- `setChangelogItems(items): void`
+- `setHomeChangelogItems(items): void`
+- `setUnreadCount(count): void`
+- `loadInitialData(): Promise<void>`
+- `checkAgentAvailability(): Promise<any>`
+- `getState(): Object`
+
+### Common Options
+
+- `position`
+- `theme`
+- `headless`
+- `teamName`
+- `teamAvatars`
+- `welcomeMessage`
+- `enableHelp`
+- `enableChangelog`
+- `primaryColor`
 
-##### `closePanel(): void`
+---
 
-Close panel.
+## SurveyWidget
 
-##### `updateText(text): void`
+Created by `sdk.createSurveyWidget()`.
 
-Update button text.
+### Methods
 
-##### `updatePosition(position): void`
+- `mount(container?): this`
+- `show(): this`
+- `hide(): this`
+- `open(): this`
+- `close(): this`
+- `toggle(): this`
+- `destroy(): void`
+
+### Common Options
+
+- `surveyId`
+- `surveyType`
+- `position`
+- `theme`
+- `title`
+- `description`
+- `ratingScale`
+- `showFeedbackInput`
+- `showSubmitButton`
+- `autoSubmitOnSelect`
+- `onSubmit`
+- `onDismiss`
 
-Update position.
+---
 
-##### `destroy(): void`
+## ChangelogWidget
 
-Destroy widget.
+Created by `sdk.createChangelogWidget()`.
 
-#### Properties
+### Methods
 
-- `id: String` - Widget ID
-- `type: String` - Widget type
-- `mounted: Boolean` - Mount status
-- `state: Object` - Widget state
+- `mount(container?): this`
+- `destroy(): void`
+- `open(): this`
+- `close(): this`
+- `toggle(): this`
+- `openModal(): void`
+- `closeModal(): void`
+- `openSidebar(): void`
+- `closeSidebar(): void`
+- `hideBadge(): void`
+- `showBadge(): void`
+- `nextChangelog(): void`
+- `prevChangelog(): void`
+- `refresh(): Promise<void>`
 
 ---
 
@@ -146,23 +279,40 @@ Destroy widget.
 
 ### SDK Events
 
-- `sdk:initialized` - SDK ready
-- `sdk:error` - Error occurred
-- `sdk:destroyed` - SDK destroyed
-- `config:updated` - Config changed
-- `user:updated` - User changed
+- `sdk:initialized`
+- `sdk:identified`
+- `sdk:error`
+- `sdk:destroyed`
+- `config:updated`
+- `metadata:updated`
 
 ### Widget Events
 
-- `widget:created` - Widget created
-- `widget:mounted` - Widget mounted
-- `widget:destroyed` - Widget destroyed
-- `widgets:cleared` - All cleared
+- `widget:created`
+- `widget:mounted`
+- `widget:destroyed`
+- `widget:suppressed`
+- `widgets:cleared`
 
 ### Feedback Events
 
-- `feedback:submitted` - Feedback sent
-- `feedback:error` - Submission failed
+- `feedback:submitted`
+- `feedback:error`
+
+### Messenger Events
+
+- `messenger:opened`
+- `messenger:closed`
+- `messenger:messageSent`
+
+### Survey Events
+
+- `survey:shown`
+- `survey:submitted`
+- `survey:dismissed`
+- `survey:closed`
+- `survey:questionAnswered`
+- `survey:suppressed`
 
 ---
 
@@ -172,50 +322,64 @@ Access via `sdk.apiService`.
 
 ### Methods
 
-#### `async init(metadata?): Promise<Object>`
+#### `async init(): Promise<Object>`
+
+Initialize a workspace session.
+
+#### `async identify(metadata): Promise<Object>`
 
-Initialize session.
+Identify the current user for the active session.
 
 #### `async submitFeedback(data): Promise<Object>`
 
 Submit feedback.
 
-#### `isSessionValid(): Boolean`
+#### `async getActiveSurveys(context?): Promise<Object>`
+
+Fetch surveys.
+
+#### `async submitSurveyResponse(surveyId, response): Promise<Object>`
 
-Check session validity.
+Submit a survey response.
+
+#### `isSessionValid(): boolean`
+
+Check whether the current session token is still valid.
 
 #### `clearSession(): void`
 
-Clear session.
+Clear the stored session and metadata.
 
 ---
 
 ## Error Classes
 
-### SDKError
+### `SDKError`
 
-General SDK errors.
+General SDK-level errors.
 
-### APIError
+### `APIError`
 
-API errors with methods:
+API errors. Helpful methods include:
 
 - `isNetworkError()`
 - `isClientError()`
 - `isServerError()`
 
-### ConfigError
+### `ConfigError`
 
-Configuration errors.
+Configuration and metadata validation errors.
 
-### WidgetError
+### `WidgetError`
 
-Widget errors.
+Widget-specific runtime errors.
 
 ---
 
 ## Utilities
 
+Available helpers include:
+
 - `generateId(prefix?)`
 - `deepMerge(target, source)`
 - `debounce(func, wait)`