<!-- source-hash: 60ad035125eceb97fa074f58783d5bc8 -->
Defines TypeScript interfaces for API interactions and React hook contracts used across Flamingo's chat and dialog systems, covering NATS/JetStream subscriptions, real-time chunk processing, and REST-style request/response shapes.

## Key Components

### Hook Options
| Interface | Purpose |
|---|---|
| `UseChunkCatchupOptions` | Configure chunk catch-up replay with optional custom fetch function |
| `UseNatsDialogSubscriptionOptions` | Core NATS WebSocket subscription config with reconnection backoff tuning |
| `UseJetStreamDialogSubscriptionOptions` | JetStream-based subscription with sequence-based resume support |
| `UseRealtimeChunkProcessorOptions` | Controls how streaming chunks are parsed, including approval routing and batch mode |

### Hook Return Types
| Interface | Purpose |
|---|---|
| `UseChunkCatchupReturn` | Exposes catchup, processing, and buffering controls |
| `UseNatsDialogSubscriptionReturn` | Connection state and reconnection counter |
| `UseJetStreamDialogSubscriptionReturn` | Connection state plus current stream sequence |
| `UseRealtimeChunkProcessorReturn` | Chunk processing, segment access, and approval status management |

### Callbacks
- **`RealtimeChunkCallbacks`** — Rich event callback map for streaming events: `onStreamStart`, `onStreamEnd`, `onSegmentsUpdate`, `onTokenUsage`, `onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`, `onToolExecuted`, `onDialogClosed`, and more.

### API Request/Response Types
- **Chat** — `ChatAPIRequest` / `ChatAPIResponse`
- **Dialogs** — `DialogCreateRequest/Response`, `DialogListRequest/Response`
- **Approvals** — `ApprovalRequest` / `ApprovalResponse`
- **Settings** — `ChatSettings`, `UpdateSettingsRequest/Response`

## Usage Example

```typescript
const options: UseRealtimeChunkProcessorOptions = {
  callbacks: {
    onSegmentsUpdate: (segments, meta) => {
      if (meta?.append) appendToLastMessage(segments)
      else setSegments(segments)
    },
    onApprovalResolved: (requestId, status, approvalType) => {
      updateApprovalBadge(requestId, status)
    },
    onTokenUsage: (data) => console.log('Tokens used:', data),
  },
  batchApprovalsEnabled: true,
  displayApprovalTypes: ['CLIENT'],
  enableThinking: false,
}

const natsOptions: UseNatsDialogSubscriptionOptions = {
  enabled: true,
  dialogId: 'dialog-123',
  getNatsWsUrl: () => 'wss://nats.example.com',
  reconnectionBackoff: {
    fastRetries: 3,
    fastRetryDelayMs: 500,
    maxDelayMs: 30000,
    multiplier: 2,
  },
  onBeforeReconnect: async () => refreshAuthToken(),
}
```