npm package: @oxvo/messenger
Description: React and core web SDK package for OXVO Messenger
Latest version: 0.1.0

# @oxvo/messenger

React and core web SDK package for OXVO Messenger.

## Structure

- `src/core/` shared controller and lazy-load engine
- `src/react/` React provider, hook, launcher
- `../shared/core/` canonical shared source synced into `src/core/`

## Install

```bash
npm install @oxvo/messenger
```

## Full Settings Support

`createOxvoMessengerController` and `OxvoMessengerProvider` support the full modern settings surface used by `/app/javascript/entrypoints/sdk.js`.

You can pass settings using either `settings` or `oxvoSettings` (alias). When both are present, `settings` wins per key.

```tsx
<OxvoMessengerProvider
  baseUrl="https://your-oxvo-domain"
  websiteToken="your-website-token"
  scriptUrl="https://static.oxvo.com/messenger/sdk.js"
  settings={{
    baseDomain: '',
    useBrowserLanguage: true,
    locale: 'en',
    position: 'right',
    launcherVisible: true,
    showPopoutButton: true,
    showUnreadMessagesDialog: true,
    widgetStyle: 'standard',
    theme: 'auto',
    type: 'expanded_bubble',
    launcherTitle: 'Welcome to OXVO',
    welcomeTitle: 'Welcome to OXVO',
    welcomeDescription: 'Ask us anything and we will be right here.',
    availableMessage: 'We are online and happy to help.',
    unavailableMessage: 'We are away right now, leave a message.',
    enableFileUpload: true,
    enableEmojiPicker: true,
    enableEndConversation: true,
    enableGifPicker: true,
    headerTextColor: '#ffffff',
    headerDecorationMode: 3,
    tabSpaces: ['Home', 'Chat'],
    convStarters: [{ text: 'I need help with my account', enabled: true }],
    convLinks: [
      { label: 'Docs', url: 'https://www.oxvo.com/docs', target: '_blank', enabled: true },
    ],
    homeBlocksOrder: ['Starters', 'Articles', 'Links', 'Apps'],
    avatarUrl: 'https://placehold.co/64x64',
    helpCenterSlug: 'help-center',
    preChatFormEnabled: true,
    preChatFormOptions: {
      pre_chat_message: 'Tell us about your issue.',
      pre_chat_fields: [],
    },
    apps: [
      {
        title: 'Docs',
        description: 'Product documentation',
        url: 'https://www.oxvo.com/docs',
        img_url: 'https://placehold.co/32x32',
      },
    ],
  }}
/>
```

Compatibility aliases accepted:
- `darkMode` -> `theme`
- `hideMessageBubble` -> inverted into `launcherVisible` (only when `launcherVisible` is not explicitly set)
- `locale: 'auto'` -> enables `useBrowserLanguage` automatically (unless `useBrowserLanguage` is explicitly set)

## Live Chat Loader (Default Off)

Use `liveChatLoader: true` to show a lightweight launcher first and delay full SDK loading until idle/user interaction.

```js
<OxvoMessengerProvider
  baseUrl="https://your-oxvo-domain"
  websiteToken="your-website-token"
  scriptUrl="https://static.oxvo.com/messenger/sdk.js"
  liveChatLoader={true}
/>
```

`liveChatLoader` is `false` by default.

### Appearance + override precedence

`liveChatLoader` also accepts an object:

```js
<OxvoMessengerProvider
  baseUrl="https://your-oxvo-domain"
  websiteToken="your-website-token"
  scriptUrl="https://static.oxvo.com/messenger/sdk.js"
  settings={{
    position: 'left',
    theme: 'dark',
    widgetStyle: 'flat',
  }}
  liveChatLoader={{
    enabled: true,
    appearance: {
      position: 'right',
      horizontalSpacing: 24,
      verticalSpacing: 24,
      messengerColor: '#2d6bff',
      type: 'expanded_bubble',
      launcherTitle: 'Support',
    },
  }}
/>
```

Precedence:
- defaults
- `settings` passed to `init`
- `liveChatLoader.appearance` (highest priority)

Note:
- `widgetStyle` is inherited from messenger `settings` and is not overridable via `liveChatLoader.appearance`.

### Custom launcher

Use `render` in `OxvoMessengerLauncher` to completely replace the default placeholder bubble while still using `load()`/`open()` actions.

## Test

```bash
npm test
```

## Production Build

```bash
npm run build
```