<!-- source-hash: 33e3e72c7a8bed6ac4ea84dd9600a0c6 -->
React hook that manages a NATS WebSocket subscription for a specific dialog, handling connection lifecycle, automatic reconnection, and multi-topic message subscriptions.

## Key Components

### `useNatsDialogSubscription(options)`

Primary hook that establishes and maintains a shared NATS client connection and subscribes to one or more topics scoped to a `dialogId`.

**Options (`UseNatsDialogSubscriptionOptions`):**

| Option | Description |
|---|---|
| `enabled` | Enables/disables the connection |
| `dialogId` | Target dialog ID; topics are subscribed as `chat.<dialogId>.<topic>` |
| `topics` | Array of `NatsMessageType` values (defaults to `['message']`) |
| `onEvent` | Callback fired with each decoded JSON message and its topic type |
| `onConnect` / `onDisconnect` | Connection lifecycle callbacks |
| `onSubscribed` | Fired once all topic subscriptions are active |
| `onBeforeReconnect` | Called before each reconnection attempt |
| `getNatsWsUrl` | Function returning the current WebSocket URL |
| `clientConfig` | NATS client credentials (`name`, `user`, `pass`) |
| `reconnectionBackoff` | Backoff strategy for reconnection attempts |

**Returns (`UseNatsDialogSubscriptionReturn`):**

| Field | Type | Description |
|---|---|---|
| `isConnected` | `boolean` | Whether the NATS client is currently connected |
| `isSubscribed` | `boolean` | Whether topic subscriptions are active |
| `reconnectionCount` | `number` | Number of reconnections since mount |

**Key implementation details:**
- Resolves the WebSocket URL synchronously each render to avoid re-running effects on callback identity changes (e.g. silent token rotations)
- Stabilizes all callbacks via `useRef` to prevent unnecessary subscription teardowns
- Joins `topics` to a string key (`topicsKey`) so the subscription effect only re-runs when topic content changes, not on inline array re-allocations
- Uses a shared NATS client pool (`acquireClient` / `releaseClient`) — multiple hook instances sharing the same URL reuse the same connection

### `buildNatsWsUrl(apiBaseUrl, options?)`

Utility that constructs a NATS WebSocket URL from an HTTP/HTTPS base URL.

## Usage Example

```typescript
import {
  useNatsDialogSubscription,
  buildNatsWsUrl,
} from './use-nats-dialog-subscription'

function DialogListener({ dialogId, token }: { dialogId: string; token: string }) {
  const { isConnected, isSubscribed, reconnectionCount } =
    useNatsDialogSubscription({
      enabled: true,
      dialogId,
      topics: ['message', 'typing'],
      getNatsWsUrl: () =>
        buildNatsWsUrl('https://api.example.com', {
          token,
          includeAuthParam: true,
          source: 'dashboard',
        }),
      onEvent: (payload, topic) => {
        console.log(`[${topic}]`, payload)
      },
      onConnect: () => console.log('NATS connected'),
      onDisconnect: () => console.log('NATS disconnected'),
    })

  return (
    <div>
      Connected: {String(isConnected)} | Subscribed: {String(isSubscribed)} |
      Reconnections: {reconnectionCount}
    </div>
  )
}
```

## Source

[`use-nats-dialog-subscription.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-nats-dialog-subscription.ts)