npm package: @mariamalakhova/ws-client
Description: A comprehensive WebSocket client library with React integration, auto-reconnection, and TypeScript support.
Latest version: 0.1.0

# @marketing-architects/ws-client

A comprehensive WebSocket client library with React integration, auto-reconnection, and TypeScript support.

## Features

- 🔄 **Auto-reconnection** with exponential backoff
- 📦 **Message queuing** when disconnected
- 🔧 **Middleware pipeline** for inbound/outbound messages
- 🤝 **Handshake protocol** with authentication
- ⚛️ **React integration** with hooks and context
- 📝 **Full TypeScript** support
- 🌳 **Tree-shakable** ESM modules

## Installation

```bash
npm install @marketing-architects/ws-client
```

## Usage

### Core Usage

```typescript
import { WSCore, type WSClientOptions } from '@marketing-architects/ws-client'

const client = new WSCore({
  url: 'wss://api.example.com/ws',
  autoReconnect: true,
  onHandshake: (msg, api) => {
    api.sendJSON({ 
      access_token: 'your-token',
      id_token: 'your-id-token' 
    })
  },
  onMessage: (msg) => {
    console.log('Received:', msg)
  }
})

await client.connect()
```

### React Integration

```typescript
import { WSProvider, useWS } from '@marketing-architects/ws-client/react'

function App() {
  const client = useMemo(() => new WSCore({
    url: 'wss://api.example.com/ws',
    onHandshake: (msg, api) => {
      api.sendJSON({ access_token: getAccessToken() })
    }
  }), [])

  return (
    <WSProvider client={client} autoConnect>
      <ChatComponent />
    </WSProvider>
  )
}

function ChatComponent() {
  const { sendJSON, isConnected, state } = useWS()
  
  return (
    <div>
      <div>Status: {state}</div>
      <button onClick={() => sendJSON({ hello: 'world' })} disabled={!isConnected}>
        Send
      </button>
    </div>
  )
}
```

### Sub-exports for Tree-shaking

```typescript
// Core only (smaller bundle)
import { WSCore } from '@marketing-architects/ws-client/core'

// React integration only
import { WSProvider, useWS } from '@marketing-architects/ws-client/react'

// Utilities
import { createDefaultBackoff } from '@marketing-architects/ws-client/utils'
```

## API Reference

### WSCore

The main WebSocket client class.

#### Methods

- `connect(): Promise<void>` - Connect to WebSocket
- `close(code?: number, reason?: string): void` - Close connection
- `sendRaw(data: string | ArrayBuffer | Blob): void` - Send raw data
- `sendJSON(data: unknown): void` - Send JSON data
- `isConnected(): boolean` - Check if connected
- `getState(): WSState` - Get current state
- `setEvents(events: WSClientEvents): void` - Set event handlers
- `setReconnectEnabled(enabled: boolean): void` - Enable/disable reconnection
- `forceReconnect(): void` - Force reconnection

#### Options

- `url: string` - WebSocket URL
- `protocols?: string | string[]` - WebSocket protocols
- `autoReconnect?: boolean` - Enable auto-reconnection (default: true)
- `maxReconnectAttempts?: number` - Max reconnection attempts (default: 5)
- `backoff?: Backoff` - Backoff strategy
- `onHandshake?: (msg: unknown, api: WSClient) => void | Promise<void>` - Handshake handler
- `onMessage?: (msg: unknown, e: MessageEvent) => void` - Message handler
- `onOpen?: (e: Event) => void` - Open handler
- `onClose?: (e: CloseEvent) => void` - Close handler
- `onError?: (e: Event) => void` - Error handler

### React Hooks

- `useWS()` - Get WebSocket client and state
- `WSProvider` - Context provider for WebSocket client

## License

MIT