npm package: @northeon/northeon-chat-react
Description: React components for Northeon Chat Widget
Author: Northeon
Latest version: 2.0.1

# @northeon/northeon-chat-react

[![npm version](https://img.shields.io/npm/v/@northeon/northeon-chat-react.svg)](https://www.npmjs.com/package/@northeon/northeon-chat-react)
[![npm downloads](https://img.shields.io/npm/dm/@northeon/northeon-chat-react.svg)](https://www.npmjs.com/package/@northeon/northeon-chat-react)

React components for the Northeon Chat Widget.

## Installation

```bash
npm install @northeon/northeon-chat-react
```

## Quick Start

```tsx
import { NortheonChat } from '@northeon/northeon-chat-react';

function App() {
  return (
    <NortheonChat
      appId="your-app-id"
      tokenEndpoint="/api/chatbot-token"
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `appId` | `string` | Required | Your Northeon App ID |
| `token` | `string` | - | JWT token (if not using tokenEndpoint) |
| `tokenEndpoint` | `string` | - | Endpoint to fetch token from |
| `getToken` | `() => Promise<string>` | - | Custom function to get token |
| `userContext` | `object` | - | Context to pass to the agent |
| `position` | `string` | `'bottom-right'` | Widget position |
| `color` | `string` | `'#FF5757'` | Bubble color |
| `bubbleSize` | `number` | `64` | Bubble size in pixels |
| `zIndex` | `number` | `999998` | CSS z-index |
| `hideBubble` | `boolean` | `false` | Hide the default bubble |
| `windowWidth` | `number` | `384` | Chat window width |
| `windowHeight` | `number` | `600` | Chat window height |
| `embedUrl` | `string` | Production URL | Custom embed script URL |
| `onReady` | `() => void` | - | Called when widget is ready |
| `onOpen` | `() => void` | - | Called when chat opens |
| `onClose` | `() => void` | - | Called when chat closes |
| `onMessage` | `(msg) => void` | - | Called on new message |
| `onError` | `(err) => void` | - | Called on error |

## Examples

### With Custom Token Function

```tsx
<NortheonChat
  appId="your-app-id"
  getToken={async () => {
    const res = await fetch('/api/chatbot-token', {
      headers: { Authorization: `Bearer ${authToken}` },
    });
    const { token } = await res.json();
    return token;
  }}
/>
```

### With User Context

```tsx
<NortheonChat
  appId="your-app-id"
  tokenEndpoint="/api/chatbot-token"
  userContext={{
    orderId: 'ORD-12345',
    currentPage: '/orders',
    userTier: 'premium',
  }}
/>
```

### With Custom Trigger Button

```tsx
import { NortheonChat, useNortheon } from '@northeon/northeon-chat-react';

function ChatButton() {
  const { open, isOpen } = useNortheon();

  return (
    <button onClick={() => open()}>
      {isOpen() ? 'Chat is open' : 'Chat with us'}
    </button>
  );
}

function App() {
  return (
    <>
      <NortheonChat
        appId="your-app-id"
        tokenEndpoint="/api/chatbot-token"
        hideBubble
      />
      <ChatButton />
    </>
  );
}
```

### Programmatic Message Sending

```tsx
import { useNortheon } from '@northeon/northeon-chat-react';

function HelpButton({ orderId }) {
  const { sendMessage, setUserContext } = useNortheon();

  const handleClick = () => {
    setUserContext({ orderId });
    sendMessage(`I need help with order ${orderId}`);
  };

  return <button onClick={handleClick}>Get Help</button>;
}
```

## useNortheon Hook

Access the widget API from any component:

```tsx
const {
  isReady,        // Whether widget API is loaded
  open,           // Open the chat window
  close,          // Close the chat window
  toggle,         // Toggle open/closed
  isOpen,         // Check if chat is open
  sendMessage,    // Send a message
  setUserContext, // Set context for agent
  clearUserContext,
  refreshToken,   // Provide new JWT token
  showBubble,     // Show the bubble
  hideBubble,     // Hide the bubble
  showNotification,
  hideNotification,
  getConfig,      // Get widget config
  destroy,        // Destroy and cleanup
} = useNortheon();
```

### Checking Widget Ready State

```tsx
function ChatButton() {
  const { isReady, open } = useNortheon();
  
  return (
    <button onClick={open} disabled={!isReady}>
      {isReady ? 'Chat with us' : 'Loading...'}
    </button>
  );
}
```

## SSR / Next.js Compatibility

This package is fully compatible with server-side rendering frameworks like Next.js, Remix, and Gatsby.

The widget only initializes in the browser and will not cause hydration mismatches:

```tsx
// Works in Next.js App Router
'use client';

import { NortheonChat } from '@northeon/northeon-chat-react';

export default function ChatWidget() {
  return (
    <NortheonChat
      appId="your-app-id"
      tokenEndpoint="/api/chatbot-token"
    />
  );
}
```

For Next.js Pages Router, you can also use dynamic imports:

```tsx
import dynamic from 'next/dynamic';

const NortheonChat = dynamic(
  () => import('@northeon/northeon-chat-react').then((mod) => mod.NortheonChat),
  { ssr: false }
);
```

## TypeScript

Full TypeScript support is included. Import types:

```tsx
import type {
  NortheonChatProps,
  NortheonError,
  NortheonMessageEvent,
  NortheonUserContext,
} from '@northeon/northeon-chat-react';
```

## License

MIT