# API Reference

## Product7

### Constructor

```javascript
new Product7(config);
```

### Config Options

| 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>`

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,
});
```

#### `createLiveChatWidget(options?): LiveChatWidget`

Creates the web chat widget.

#### `createChangelogWidget(options?): ChangelogWidget`

Creates the changelog widget.

#### `createSurveyWidget(options?): SurveyWidget`

Creates the survey widget.

#### `createWidget(type, options?): Widget`

Low-level factory for advanced usage. Supported types include:

- `'feedback'`
- `'button'` (legacy alias for feedback)
- `'liveChat'`
- `'survey'`
- `'changelog'`
- `'inline'`
- `'tab'`

### Other Instance Methods

#### `getWidget(id): Widget | undefined`

Get a widget by ID.

#### `getAllWidgets(): Widget[]`

Get all widgets created by this SDK instance.

#### `destroyWidget(id): boolean`

Destroy a single widget by ID.

#### `destroyAllWidgets(): void`

Destroy all widgets.

#### `updateConfig(config): void`

Update SDK config and propagate the change to mounted widgets.

#### `setMetadata(metadata): void`

Update stored metadata locally. This does not replace `identify()`.

#### `getMetadata(): Object | null`

Get the currently stored metadata.

#### `async reinitialize(metadata?): Promise<Object>`

Clear the current session and initialize again. If metadata is passed, it will be stored and automatically identified after the new session is created.

#### `async getActiveSurveys(context?): Promise<Array>`

Fetch active surveys for the current session.

#### `async showSurveyById(surveyId, options?): Promise<SurveyWidget | null>`

Find and display a survey by ID.

#### `showSurvey(options?): SurveyWidget | null`

Render a survey directly from options.

#### `showChangelog(options?): ChangelogWidget | null`

Create, mount, and show a changelog widget.

#### `async getChangelogs(options?): Promise<Array>`

Fetch changelog items.

#### `on(event, callback): Product7`

Subscribe to an SDK event.

#### `off(event, callback): Product7`

Unsubscribe from an SDK event.

#### `once(event, callback): Product7`

Subscribe to an event once.

---

## FeedbackWidget

Created by `sdk.createFeedbackWidget()` or `sdk.createWidget('feedback', ...)`.

### Methods

- `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`

---

## LiveChatWidget

Created by `sdk.createLiveChatWidget()`.

### Methods

- `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`

---

## SurveyWidget

Created by `sdk.createSurveyWidget()`.

### Methods

- `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`

---

## ChangelogWidget

Created by `sdk.createChangelogWidget()`.

### Methods

- `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>`

---

## Events

### SDK Events

- `sdk:initialized`
- `sdk:identified`
- `sdk:error`
- `sdk:destroyed`
- `config:updated`
- `metadata:updated`

### Widget Events

- `widget:created`
- `widget:mounted`
- `widget:destroyed`
- `widget:suppressed`
- `widgets:cleared`

### Feedback Events

- `feedback:submitted`
- `feedback:error`

### Web Chat Events

- `liveChat:opened`
- `liveChat:closed`
- `liveChat:messageSent`

### Survey Events

- `survey:shown`
- `survey:submitted`
- `survey:dismissed`
- `survey:closed`
- `survey:questionAnswered`
- `survey:suppressed`

---

## APIService

Access via `sdk.apiService`.

### Methods

#### `async init(): Promise<Object>`

Initialize a workspace session.

#### `async identify(metadata): Promise<Object>`

Identify the current user for the active session.

#### `async submitFeedback(data): Promise<Object>`

Submit feedback.

#### `async getActiveSurveys(context?): Promise<Object>`

Fetch surveys.

#### `async submitSurveyResponse(surveyId, response): Promise<Object>`

Submit a survey response.

#### `isSessionValid(): boolean`

Check whether the current session token is still valid.

#### `clearSession(): void`

Clear the stored session and metadata.

---

## Error Classes

### `SDKError`

General SDK-level errors.

### `APIError`

API errors. Helpful methods include:

- `isNetworkError()`
- `isClientError()`
- `isServerError()`

### `ConfigError`

Configuration and metadata validation errors.

### `WidgetError`

Widget-specific runtime errors.

---

## Utilities

Available helpers include:

- `generateId(prefix?)`
- `deepMerge(target, source)`
- `debounce(func, wait)`
- `throttle(func, limit)`
- `isValidEmail(email)`
- `isMobile()`
- `formatFileSize(bytes)`
- `delay(ms)`