# SDK API reference

The complete surface of the `CherryEmbed` instance.

## Constructor

```ts
new CherryEmbed(config: CherryEmbedConfig)
```

See [Configuration](https://portal.cherry.fun/docs/embed/configuration.md) for the full config shape.

## Methods

### Lifecycle

| Method | Signature | Notes |
|---|---|---|
| `mount` | `() => Promise<void>` | Attaches the iframe and resolves when ready. Register `signChallengeHandler` first. |
| `destroy` | `() => void` | Removes the iframe and tears down listeners. |

### Rooms

| Method | Signature | Notes |
|---|---|---|
| `setRoom` | `(roomId: string) => void` | Switch the active room. Drives [`external-controlled` mode](https://portal.cherry.fun/docs/embed/display-modes.md). |

### Auth

| Method | Signature | Notes |
|---|---|---|
| `setToken` | `(token: string) => void` | Provide a fresh embed token and force a re-exchange (e.g. after an account switch). |
| `setWalletAddress` | `(address: string) => void` | Update the user's wallet address. |
| `signOut` | `() => void` | Clear the session and reload the iframe. |
| `onSignChallenge` | `(handler: SignChallengeHandler) => void` | Register the wallet sign handler (alternative to the config field). See [Authentication](https://portal.cherry.fun/docs/embed/authentication.md). |
| `offSignChallenge` | `() => void` | Remove the sign handler. |

### Theme & layout

| Method | Signature | Notes |
|---|---|---|
| `setTheme` | `(theme: Partial<EmbedTheme>) => void` | Merge theme changes. See [Theming](https://portal.cherry.fun/docs/embed/theming.md). |
| `resetTheme` | `() => void` | Reset to defaults before applying a new theme. |
| `setLayout` | `(layout: Partial<EmbedLayout>) => void` | Toggle UI chrome at runtime. |

### Visibility

| Method | Signature | Notes |
|---|---|---|
| `show` / `hide` / `toggle` | `() => void` | Show, hide, or toggle the widget (useful for floating mode). |

### Events

| Method | Signature |
|---|---|
| `on` | `(event, handler) => void` |
| `off` | `(event, handler) => void` |

### Getters

| Getter | Type | Notes |
|---|---|---|
| `isReady` | `boolean` | Iframe mounted and ready. |
| `isAuthenticated` | `boolean` | User is authenticated (not in preview). |
| `isVisible` | `boolean` | Widget currently visible. |
| `walletAddress` | `string \| undefined` | Current wallet address. |
| `currentMode` | `EmbedMode` | Active room mode. |

## Events

Subscribe with `chat.on(event, handler)`.

| Event | Payload | Fires when |
|---|---|---|
| `ready` | `void` | The widget has mounted and is ready. |
| `authStateChange` | `boolean` | Auth state flips (`true` = authenticated, `false` = preview). |
| `tokenExpired` | `void` | Reserved: not currently emitted (sessions renew silently in the iframe). |
| `walletConnectRequested` | `void` | The user asked to connect a wallet from a preview state. |
| `message` | `{ roomId: string; senderId: string; timestamp: number }` | A new message arrives. |
| `unreadCount` | `number` | The unread count changes. |
| `roomChanged` | `{ roomId: string }` | Reserved: not currently emitted (only `single` mode is available today). |
| `preview` | `{ visible: boolean; gated: boolean }` | The widget enters/leaves a gated preview state. |
| `error` | `{ code: string; message: string }` | Reserved: not currently emitted. |

```ts
chat.on('ready', () => console.log('chat ready'));
chat.on('unreadCount', (n) => updateBadge(n));
chat.on('message', ({ roomId }) => console.log('new message in', roomId));
```

## Types

The package ships full TypeScript types - import them directly:

```ts
import type {
  CherryEmbedConfig,
  EmbedTheme,
  EmbedLayout,
  EmbedMode,
} from '@cherrydotfun/chat-embed-sdk';
```

## Next steps

- Drive rooms from your backend: [Cherry API](https://portal.cherry.fun/docs/api/authentication.md).
- End-to-end: [Guides](https://portal.cherry.fun/docs/guides/public-chat.md).