# @wioex/stream-sdk

[![npm version](https://badge.fury.io/js/%40wioex%2Fstream-sdk.svg)](https://www.npmjs.com/package/@wioex/stream-sdk)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

WebSocket streaming SDK for real-time WioEX market data. Receive live stock ticker updates with a simple, event-driven API.

## Features

- **Real-time streaming** - WebSocket-based live market data
- **Enhanced reliability** - Multi-source failover architecture for improved connection stability (NEW in v1.13.0)
- **Trading signals** - Real-time trading signals with entry/target/stop-loss levels
- **High-performance** - Optimized for high-frequency data with throttling & batching
- **Multiple stocks** - Track up to 50 stocks simultaneously (no more connection limits)
- **Auto-reconnection** - Automatic reconnection with exponential backoff
- **Type-safe** - Written in TypeScript with full type definitions
- **Universal** - Works in Node.js and browsers
- **Lightweight** - ~88KB ESM, ~75KB UMD minified (includes optional MessagePack)
- **Event-driven** - Simple EventEmitter-based API
- **Production-ready** - Robust error handling and heartbeat mechanism
- **Error reporting** - Automatic error tracking with batching & deduplication

### Latest Features (v1.18.0)

- **Standardized Message Types** (NEW) - Complete type consistency between SDK and server:
  - Comprehensive TypeScript enum system for all message types
  - Eliminated authentication and communication issues
  - Type-safe client-server message protocol
  - Enhanced error handling with standardized error types
  - Full compatibility with existing code
- **Enhanced Connection Reliability** - Multi-source failover architecture with:
  - Automatic health monitoring and intelligent switching
  - Improved connection stability and reduced latency
  - Enhanced error handling and recovery mechanisms
  - Message batching and buffering optimizations
  - Performance metrics tracking and monitoring
- **Trading signals** - Subscribe to real-time trading signals with:
  - Signal types: BUY, SELL, STRONG_BUY, STRONG_SELL, HOLD
  - Entry price, target price, stop-loss levels
  - Confidence score (0-100%)
  - Signal triggered events (entry/target/stop-loss)
  - Multiple timeframes (5m, 15m, 1h, 4h, 1d, 1w, 1M)
- **Browser & jQuery support** - CDN-ready with jQuery plugin wrapper
- **Binary protocol support** - Optional MessagePack encoding for 50-60% faster parsing (opt-in)

## Installation

### NPM (Node.js, React, Vue, Angular, etc.)

```bash
npm install @wioex/stream-sdk
```

### CDN (Browser - No build tools required)

**Vanilla JavaScript:**
```html
<script src="https://unpkg.com/@wioex/stream-sdk@latest/dist/wioex-stream.min.js"></script>
```

**jQuery Plugin:**
```html
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://unpkg.com/@wioex/stream-sdk@latest/dist/wioex-stream.jquery.min.js"></script>
```

**Specific Version (Recommended for production):**
```html
<script src="https://unpkg.com/@wioex/stream-sdk@1.13.0/dist/wioex-stream.min.js"></script>
```

### Self-Hosted

Download from NPM and host on your own server:

```bash
npm pack @wioex/stream-sdk
# Extract dist/ folder and upload to your server
```

> **Complete Browser Guide:** See [docs/BROWSER_GUIDE.md](./docs/BROWSER_GUIDE.md) for CDN options, self-hosting, jQuery integration, and framework examples.

## Anonymous Telemetry

WioEX Stream SDK collects **anonymous** usage statistics to help us improve the SDK. This happens once on first usage.

**What we collect:**
- SDK version and type
- Runtime environment (Node.js/Browser version)
- Operating system type
- Installation timestamp
- Anonymous machine ID (hash-based, no personal info)

**What we DON'T collect:**
- Personal information
- API keys or tokens
- IP addresses
- Business data or stock symbols
- Any identifiable information

**Disable telemetry:**

Set environment variable:
```bash
export WIOEX_TELEMETRY_DISABLED=1
```

Or in your code (before importing):
```javascript
process.env.WIOEX_TELEMETRY_DISABLED = '1';
// Then import
import { WioexStreamClient } from '@wioex/stream-sdk';
```

Or in browser:
```html
<script>
  window.WIOEX_TELEMETRY_DISABLED = '1';
</script>
<script src="path/to/wioex-stream.min.js"></script>
```

Read our [Privacy Policy](https://wioex.com/privacy) for details.

## Quick Start

### Super Simple! Just provide your API key

**Node.js / Backend:**

```typescript
import { WioexStreamClient } from '@wioex/stream-sdk';

// Just provide your API key - SDK handles everything automatically!
const client = new WioexStreamClient({
  apiKey: process.env.WIOEX_API_KEY
});

client.on('ticker', (data) => {
  console.log(`${data.ticket}: $${data.last} (${data.changePercent}%)`);
});

// Lazy connect - just subscribe and SDK connects automatically!
client.subscribe(['AAPL', 'TSLA', 'GOOGL']);
```

**Browser / Frontend (Vanilla JavaScript):**

```html
<script src="https://unpkg.com/@wioex/stream-sdk@latest/dist/wioex-stream.min.js"></script>
<script>
  // Initialize with token endpoint (recommended for browser)
  const client = new WioexStream({
    tokenEndpoint: '/api/stream/token'  // Your backend endpoint
  });

  client.on('ticker', (data) => {
    console.log(`${data.ticket}: $${data.last}`);
  });

  // Lazy connect - just subscribe and SDK connects automatically!
  client.subscribe(['AAPL', 'TSLA']);
</script>
```

**Browser / Frontend (jQuery Plugin):**

```html
<!-- Load jQuery first -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<!-- Load WioEX jQuery plugin -->
<script src="https://unpkg.com/@wioex/stream-sdk@latest/dist/wioex-stream.jquery.min.js"></script>

<script>
  // Initialize with jQuery
  $('#app').wioexStream({
    tokenEndpoint: '/api/stream/token',
    stocks: ['AAPL', 'TSLA', 'GOOGL']
  });

  // Listen to jQuery events
  $('#app').on('wioex:ticker', function(event, data) {
    console.log(`${data.ticket}: $${data.last}`);
  });
</script>
```

---

### Trading Signals

Subscribe to real-time trading signals with entry prices, targets, and stop-loss levels:

```typescript
import { WioexStreamClient } from '@wioex/stream-sdk';

const client = new WioexStreamClient({
  apiKey: process.env.WIOEX_API_KEY
});

// Subscribe to ticker updates
client.subscribe(['AAPL', 'TSLA']);

// Subscribe to trading signals for same symbols
client.subscribeSignals(['AAPL', 'TSLA']);

// Listen to new signals
client.on('signal', (signal) => {
  console.log(`${signal.symbol} ${signal.signalType} Signal`);
  console.log(`   Entry: $${signal.entryPrice}`);
  console.log(`   Target: $${signal.targetPrice}`);
  console.log(`   Stop Loss: $${signal.stopLoss}`);
  console.log(`   Confidence: ${signal.confidence}%`);
  console.log(`   Reason: ${signal.reason}`);
  console.log(`   Timeframe: ${signal.timeframe}`);
});

// Listen to signal triggers (entry/target/stop-loss hit)
client.on('signalTriggered', (trigger) => {
  console.log(`Signal Triggered: ${trigger.triggerType.toUpperCase()}`);
  console.log(`   ${trigger.symbol} @ $${trigger.triggeredPrice}`);
});

// Signal subscription events
client.on('signalSubscribed', (symbols) => {
  console.log(`Subscribed to signals for: ${symbols.join(', ')}`);
});

client.on('signalError', (error) => {
  console.error('Signal error:', error.message);
});
```

**Signal Types:**
- `BUY` - Buy signal
- `SELL` - Sell signal
- `STRONG_BUY` - Strong buy recommendation
- `STRONG_SELL` - Strong sell recommendation
- `HOLD` - Hold position

**Trigger Types:**
- `entry` - Price reached entry level
- `target` - Price reached target (take profit)
- `stop_loss` - Price hit stop-loss level
- `expired` - Signal expired

**Available Methods:**
```typescript
client.subscribeSignals(['AAPL', 'TSLA']);        // Subscribe to signals
client.unsubscribeSignals(['AAPL']);              // Unsubscribe from signals
client.getSignalSubscriptions();                   // Get subscribed symbols
```

---

### **IMPORTANT: Browser Security**

**NEVER expose your API key in browser/frontend code!**

If you see your API key in browser DevTools Network tab, you're doing it wrong!

**WRONG (API key visible in browser):**
```javascript
// This exposes your API key in browser Network tab!
const client = new WioexStream({
  apiKey: 'your-api-key-here'  // INSECURE!
});
```

**CORRECT (API key stays on server):**
```javascript
// API key is safely stored on your backend
const client = new WioexStream({
  tokenEndpoint: '/api/stream/token'  // SECURE!
});
```

**Why this matters:**
- Anyone can inspect browser Network tab
- Exposed API keys can be stolen and abused
- Your account could be compromised

**How it works:**
```
Browser → Your Backend (/api/stream/token) → WioEX API
  (token)      (api_key)                     (token)
```

Your backend fetches the token using YOUR API key (server-side), then passes only the token to the browser.

**Backend example:**
- PHP: [`examples/backend-token-proxy.php`](./examples/backend-token-proxy.php)

---

**What happens behind the scenes:**
1. SDK automatically fetches a secure token from your backend endpoint
2. Connects to WebSocket stream with the token
3. Your API key is NEVER exposed in browser code (security first!)
4. Token automatically refreshes before expiry

> **Pro Tip:** Use `lazyConnect: true` (default) so you don't need to call `connect()` - just subscribe!

> **Browser Guide:** See [docs/BROWSER_GUIDE.md](./docs/BROWSER_GUIDE.md) for comprehensive browser usage documentation including CDN, self-hosting, jQuery integration, and framework examples.

## API Reference

### Constructor

```typescript
new WioexStreamClient(config: WioexStreamConfig)
```

#### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | *Backend only* | **Backend (Node.js):** Your WioEX API key - SDK auto-fetches token |
| `token` | `string` | *Frontend only* | **Frontend (Browser):** Secure token from your backend |
| `tokenExpiresAt` | `number` | - | Token expiration Unix timestamp (seconds) |
| `tokenEndpoint` | `string` | - | Backend endpoint URL to fetch token (browser only) |
| `tokenFetchHeaders` | `object` | - | Custom headers for token endpoint request |
| `tokenFetchRetry` | `object` | See below | Token fetch retry configuration |
| `onTokenExpiring` | `function` | - | Async callback to fetch new token on expiry |
| `autoRefreshToken` | `boolean` | `true`* | Auto-refresh token before expiry (*if `onTokenExpiring` provided) |
| `refreshBeforeExpiry` | `number` | `3600000` | Refresh token N ms before expiry (default: 1 hour) |
| `lazyConnect` | `boolean` | `true` | Auto-connect on first subscribe (no manual `connect()` needed) |
| `debug` | `boolean` | `false` | Enable debug logging to console |
| `maxSymbols` | `number` | `50` | Maximum symbols to track (1-50) |
| `autoReconnect` | `boolean` | `true` | Enable auto-reconnection |
| `reconnectDelay` | `number` | `3000` | Reconnection delay (ms) |
| `maxReconnectAttempts` | `number` | `0` | Max reconnect attempts (0 = infinite) |
| `streamUrl` | `string` | Auto | WebSocket URL (auto-generated) |
| `errorReportingLevel` | `string` | `'detailed'` | Error reporting level (`none`, `minimal`, `standard`, `detailed`) |
| `performance` | `object` | See below | Performance optimization options |

**Authentication:**
- **Backend (Node.js):** Use `apiKey` - SDK automatically fetches and manages tokens
- **Frontend (Browser):** Use `token` OR `tokenEndpoint` - Get from your backend (API key blocked for security)

#### Token Fetch Retry Options (`tokenFetchRetry` config)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `maxAttempts` | `number` | `3` | Maximum number of retry attempts |
| `delay` | `number` | `1000` | Initial delay between retries in milliseconds |
| `backoff` | `'linear' \| 'exponential'` | `'exponential'` | Backoff strategy (exponential: 1s → 2s → 4s, linear: 1s → 2s → 3s) |

**Example:**
```typescript
const client = new WioexStreamClient({
  tokenEndpoint: '/api/stream/token',
  tokenFetchRetry: {
    maxAttempts: 5,
    delay: 2000,
    backoff: 'exponential',  // 2s → 4s → 8s → 16s → 32s
  },
});
```

#### Performance Options (`performance` config)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `tickerThrottle` | `number` | `16` | Throttle ticker events (ms). `0` = disabled, `16` = 60 FPS |
| `batchTickers` | `boolean` | `false` | Enable ticker batching mode |
| `tickerBatchSize` | `number` | `10` | Maximum ticker batch size |
| `errorBatchSize` | `number` | `10` | Error reporting batch size |
| `errorBatchInterval` | `number` | `5000` | Error flush interval (ms) |
| `errorDeduplication` | `boolean` | `true` | Enable error deduplication |
| `enableStats` | `boolean` | `true` | Enable stats tracking (disable in production for 5-10% performance gain) |
| `useBinaryProtocol` | `boolean` | `false` | Use binary protocol (MessagePack) for 50-60% faster parsing (opt-in) |

**Performance Presets:**

```typescript
// Default (balanced - 60 FPS throttling)
const client = new WioexStreamClient({ apiKey: 'xxx' });

// High-performance (no throttling, immediate events)
const client = new WioexStreamClient({
  apiKey: 'xxx',
  performance: {
    tickerThrottle: 0,           // No throttling
    errorBatchSize: 1,           // Immediate error reporting
    errorDeduplication: false,   // No deduplication
  }
});

// Production-optimized (maximum performance, minimal overhead)
const client = new WioexStreamClient({
  apiKey: 'xxx',
  performance: {
    enableStats: false,          // Disable stats for 5-10% CPU reduction
    tickerThrottle: 0,           // No throttling
    errorBatchSize: 20,          // Batch errors
  }
});

// Binary protocol (50-60% faster parsing, requires server support)
const client = new WioexStreamClient({
  apiKey: 'xxx',
  performance: {
    useBinaryProtocol: true,     // Enable MessagePack encoding
    enableStats: false,          // Disable stats for extra speed
  }
});

// See BINARY_PROTOCOL.md for comprehensive guide on binary protocol

// High-volume (optimized for charts - 20 FPS batching)
const client = new WioexStreamClient({
  apiKey: 'xxx',
  performance: {
    tickerThrottle: 50,         // 20 FPS
    batchTickers: true,         // Enable batching
    tickerBatchSize: 20,        // Larger batches
  }
});

// Memory-optimized (aggressive batching)
const client = new WioexStreamClient({
  apiKey: 'xxx',
  performance: {
    errorBatchSize: 50,         // Large error batches
    errorBatchInterval: 10000,  // 10s flush interval
  }
});
```

### Message Types (v1.18.0)

WioEX Stream SDK now includes **type-safe message definitions** for enhanced development experience:

```typescript
import { WioexStreamClient, ClientMessageType, ServerMessageType } from '@wioex/stream-sdk';

// All message types are now strongly typed
const client = new WioexStreamClient({ apiKey: 'xxx' });

// TypeScript will provide full intellisense and type checking
client.on('ticker', (data) => {
  // data is fully typed - no more guessing what properties exist!
  console.log(`${data.symbol}: $${data.price}`);
});

// Message types are available as enums for advanced usage
console.log('Available client message types:', Object.values(ClientMessageType));
console.log('Available server message types:', Object.values(ServerMessageType));
```

**Benefits:**
- **Type Safety** - No more typos in message handling
- **IntelliSense** - Full autocomplete in your IDE
- **Better Debugging** - Clear error messages for invalid data
- **Consistent Protocol** - SDK and server use identical message types

### Methods

#### `connect(): Promise<void>`

Connect to WioEX WebSocket stream. In Node.js with `apiKey`, automatically fetches token before connecting.

```typescript
// Backend (with apiKey) - await to ensure token fetch completes
await client.connect();

// Frontend (with token) - can be called without await
client.connect();
```

#### `disconnect(): void`

Disconnect from WebSocket stream.

```typescript
client.disconnect();
```

#### `subscribe(stocks: string | string[]): void`

Subscribe to stock ticker updates.

```typescript
client.subscribe('AAPL');
client.subscribe(['AAPL', 'TSLA', 'GOOGL']);
```

**Throws:** Error if attempting to subscribe to more than `maxSymbols`.

#### `unsubscribe(stocks: string | string[]): void`

Unsubscribe from stock ticker updates.

```typescript
client.unsubscribe('AAPL');
client.unsubscribe(['AAPL', 'TSLA']);
```

#### `getState(): ConnectionState`

Get current connection state.

```typescript
const state = client.getState();
// Returns: 'disconnected' | 'connecting' | 'connected' | 'registered' | 'reconnecting' | 'failed'
```

#### `getSubscribedStocks(): string[]`

Get list of currently subscribed stocks.

```typescript
const stocks = client.getSubscribedStocks();
console.log(stocks); // ['AAPL', 'TSLA', 'GOOGL']
```

#### `getStats(): ClientStats`

Get client statistics.

```typescript
const stats = client.getStats();
console.log(stats);
// {
//   connectedAt: 1704067200000,
//   reconnectAttempts: 0,
//   messagesReceived: 152,
//   messagesSent: 3,
//   tickersReceived: 148,
//   subscribedStocks: ['AAPL', 'TSLA'],
//   state: 'registered'
// }
```

#### `isConnected(): boolean`

Check if client is connected.

```typescript
if (client.isConnected()) {
  console.log('Connected!');
}
```

#### `updateToken(token: string, expiresAt: number): void`

Manually update authentication token (useful for token refresh implementations).

```typescript
// Update token and schedule auto-refresh
client.updateToken(newToken, newExpiresAt);
```

### Events

The client extends `EventEmitter` and emits the following events:

#### `connected`

Emitted when WebSocket connection is established.

```typescript
client.on('connected', () => {
  console.log('Connected to WioEX stream');
});
```

#### `registered`

Emitted when client is registered with API key.

```typescript
client.on('registered', (data) => {
  console.log('Registered:', data.message);
});
```

#### `subscribed`

Emitted when subscribed to stocks.

```typescript
client.on('subscribed', (stocks: string[]) => {
  console.log('Subscribed to:', stocks);
});
```

#### `unsubscribed`

Emitted when unsubscribed from stocks.

```typescript
client.on('unsubscribed', (stocks: string[]) => {
  console.log('Unsubscribed from:', stocks);
});
```

#### `ticker`

Emitted when ticker data is received.

```typescript
client.on('ticker', (data: TickerData) => {
  console.log(`${data.ticket}: $${data.last}`);
});
```

**TickerData Structure:**

```typescript
interface TickerData {
  ticket: string;        // Stock symbol
  last: string;          // Last price
  open: string;          // Opening price
  high: string;          // High price
  low: string;           // Low price
  volume: string;        // Trading volume
  bid: string;           // Bid price
  ask: string;           // Ask price
  change: string;        // Price change
  changePercent: string; // Change percentage
  timestamp: number;     // Unix timestamp
}
```

---

## Message Format

### WebSocket Ticker Updates

WioEX Stream uses a streamlined type-based message format for real-time ticker updates.

**Message Structure:**

```json
{
  "type": "ticker",
  "data": {
    "ticket": "AAPL",
    "last": "150.25",
    "open": "149.80",
    "high": "151.00",
    "low": "149.50",
    "volume": "52847100",
    "bid": "150.20",
    "ask": "150.30",
    "change": "0.45",
    "changePercent": "0.30",
    "timestamp": 1697294400
  }
}
```

### Custom WebSocket Implementation

If you're building a custom WebSocket client (not using this SDK):

```javascript
const WebSocket = require('ws');

const ws = new WebSocket('wss://stream.wioex.com/...');

ws.on('message', (data) => {
  const message = JSON.parse(data);

  if (message.type === 'ticker') {
    const ticker = message.data;
    console.log(`${ticker.ticket}: $${ticker.last} (${ticker.changePercent}%)`);
  }
});
```

### Benefits of v2 Format

- **37% smaller payload** with MessagePack binary protocol
- **15-20% faster parsing** (reduced nesting depth)
- **Enhanced reliability** with improved connection stability
- **More extensible** for future message types
- **Cleaner code** and better developer experience

### Migration from v1.10.0

**Breaking Change:** If updating from v1.10.0 or earlier, update your custom implementations:

```javascript
// v1.10.0 (OLD - No longer supported)
if (message.sarex && message.sarex.ticker) {
  const ticker = message.sarex.ticker;
}

// v1.11.0+ (NEW - Required)
if (message.type === 'ticker') {
  const ticker = message.data;
}
```

**Note:** The official SDK handles this automatically - just update to v1.11.0+

---

#### `error`

Emitted when an error occurs.

```typescript
client.on('error', (error: Error) => {
  console.error('Error:', error.message);
});
```

#### `disconnected`

Emitted when connection is closed.

```typescript
client.on('disconnected', (code: number, reason: string) => {
  console.log(`Disconnected (${code}): ${reason}`);
});
```

#### `reconnecting`

Emitted when attempting to reconnect.

```typescript
client.on('reconnecting', (attempt: number) => {
  console.log(`Reconnecting... (attempt ${attempt})`);
});
```

#### `stateChange`

Emitted when connection state changes.

```typescript
client.on('stateChange', (state: ConnectionState) => {
  console.log(`State: ${state}`);
});
```

#### `tokenExpiring`

Emitted when token is about to expire (before auto-refresh).

```typescript
client.on('tokenExpiring', ({ currentToken, expiresAt }) => {
  console.log(`Token expiring at ${new Date(expiresAt * 1000)}`);
});
```

#### `tokenRefreshed`

Emitted when token has been successfully refreshed.

```typescript
client.on('tokenRefreshed', ({ token, expiresAt }) => {
  console.log(`Token refreshed! New expiry: ${new Date(expiresAt * 1000)}`);
});
```

#### `tokenRefreshFailed`

Emitted when token refresh fails.

```typescript
client.on('tokenRefreshFailed', (error: Error) => {
  console.error('Token refresh failed:', error.message);
});
```

#### `tokenFetchStarted`

Emitted when token fetch starts (from endpoint or API).

```typescript
client.on('tokenFetchStarted', (source: 'endpoint' | 'api') => {
  console.log(`Fetching token from ${source}...`);
});
```

#### `tokenFetchSucceeded`

Emitted when token fetch succeeds.

```typescript
client.on('tokenFetchSucceeded', ({ token, expiresAt, source }) => {
  console.log(`Token fetched from ${source}`);
  console.log(`Expires at: ${new Date(expiresAt * 1000)}`);
});
```

#### `tokenFetchFailed`

Emitted when token fetch fails (will retry if configured).

```typescript
client.on('tokenFetchFailed', (error: Error, attempt: number, willRetry: boolean) => {
  console.error(`Token fetch failed (attempt ${attempt}):`, error.message);
  if (willRetry) {
    console.log('Will retry...');
  }
});
```

## WebSocket Protocol

The SDK communicates with WioEX WebSocket API using JSON messages:

### Connection

```
wss://stream.wioex.com/rs/i/{max_symbols}/websocket
```

### Registration

```json
{
  "action": "register",
  "token": "your-temporary-token"
}
```

**Response:**
```json
{
  "status": "success",
  "type": "registered",
  "message": "Client registered successfully"
}
```

### Subscribe

```json
{
  "action": "subscribe",
  "stocks": ["AAPL", "TSLA", "GOOGL"]
}
```

**Response:**
```json
{
  "status": "success",
  "type": "subscribed",
  "message": "Subscribed to stocks",
  "stocks": ["AAPL", "TSLA", "GOOGL"]
}
```

### Ticker Update

```json
{
  "sarex": {
    "_p": { "e": "d" },
    "ticker": {
      "ticket": "AAPL",
      "last": "185.25",
      "open": "183.50",
      "high": "186.00",
      "low": "183.00",
      "volume": "52478963",
      "bid": "185.20",
      "ask": "185.30",
      "change": "1.75",
      "changePercent": "0.95",
      "timestamp": 1704067200000
    }
  }
}
```

## TypeScript Support

The SDK is written in TypeScript with full type definitions included:

```typescript
import type {
  WioexStreamClient,
  WioexStreamConfig,
  TickerData,
  ConnectionState
} from '@wioex/stream-sdk';

// Full IntelliSense and type checking
const client = new WioexStreamClient({
  apiKey: process.env.WIOEX_API_KEY,
  maxSymbols: 50
});

client.on('ticker', (data: TickerData) => {
  // TypeScript auto-complete for all properties
  console.log(data.ticket, data.last, data.changePercent);
});
```

All types are automatically available when you install the package - no `@types/*` package needed!

## Browser Support

The SDK works in all modern browsers that support WebSocket:

- Chrome 16+
- Firefox 11+
- Safari 7+
- Edge 12+
- Opera 12.1+

## Node.js Support

Requires Node.js 16 or higher.

## Development

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run linter
npm run lint

# Run tests
npm test

# Development mode (watch)
npm run dev
```

## Examples

See the `examples/` directory for complete examples:

### Browser Examples

- **Simple Vanilla JS:** `examples/simple-vanilla.html` - Minimal 100-line example, copy-paste ready
- **jQuery Plugin:** `examples/jquery-example.html` - jQuery plugin integration with Bootstrap UI
- **Complete Browser Example:** `examples/browser-example.html` - Complete UI with all features
- **PHP Backend Proxy:** `examples/backend-token-proxy.php` - Secure token endpoint example

### Quick Start

**Simple Vanilla JS (Easiest):**
1. Build the package: `npm run build`
2. Open `examples/simple-vanilla.html` in a browser
3. Works with token endpoint or pre-fetched token

**jQuery Plugin:**
1. Build the package: `npm run build`
2. Open `examples/jquery-example.html` in a browser
3. jQuery-friendly API with event delegation

**PHP Backend Setup:**
```bash
# Set up PHP backend proxy
cp examples/backend-token-proxy.php /path/to/your/backend/
# Set your WIOEX_API_KEY environment variable
export WIOEX_API_KEY="your-api-key"
# Or add to your .env file
```

See `examples/backend-token-proxy.php` for detailed documentation.

## Documentation

- **[BROWSER_GUIDE.md](./docs/BROWSER_GUIDE.md)** - Comprehensive browser usage guide
- **[BINARY_PROTOCOL.md](./BINARY_PROTOCOL.md)** - Binary protocol guide (MessagePack)
- **[PERFORMANCE.md](./PERFORMANCE.md)** - Performance optimization guide
- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and changes

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Documentation:** [https://docs.wioex.com](https://docs.wioex.com)
- **API Reference:** [https://api.wioex.com/docs](https://api.wioex.com/docs)
- **Issues:** [https://github.com/wioex/wioex-stream-sdk/issues](https://github.com/wioex/wioex-stream-sdk/issues)

## Related Projects

- [@wioex/php-sdk](https://github.com/wioex/wioex-php-sdk) - PHP SDK for WioEX API

---

Made by [WioEX](https://wioex.com)