@pipsend/sdk 0.1.0 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@pipsend/sdk.svg)](https://www.npmjs.com/package/@pipsend/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Official Pipsend SDK for Node.js and TypeScript. Complete MT5 trading platform integration with WebSocket support.
+Official Pipsend SDK for Node.js and TypeScript. Complete trading platform integration with WebSocket support.
 
 ## 🚀 Features
 
@@ -31,13 +31,59 @@ yarn add @pipsend/sdk
 pnpm add @pipsend/sdk
 ```
 
+## 🔐 Authentication
+
+The SDK uses JWT-based authentication with automatic token refresh.
+
+```typescript
+import { createClient } from '@pipsend/sdk';
+
+const client = createClient({
+  server: 'http://localhost:8080',
+  login: '1000',              // Your admin/API login
+  password: 'YourPassword'    // Your admin/API password
+});
+
+// The SDK automatically:
+// ✅ Authenticates on first API call
+// ✅ Stores access and refresh tokens in memory
+// ✅ Refreshes tokens automatically when they expire
+// ✅ Re-authenticates if refresh fails
+```
+
+**Authentication happens automatically** - you don't need to call any login method. Just create the client and start making API calls.
+
+### Manual Authentication Control (Advanced)
+
+If you need manual control over authentication:
+
+```typescript
+// Check authentication status
+const isAuthenticated = client.isAuthenticated();
+
+// Manually refresh token
+await client.refreshToken();
+
+// Logout (clears tokens)
+await client.logout();
+
+// Get current token info
+const tokenInfo = client.getTokenInfo();
+console.log('Token expires at:', tokenInfo?.expiresAt);
+```
+
+---
+
 ## 🔧 Quick Start
 
 ```typescript
 import { createClient } from '@pipsend/sdk';
 
+// Create authenticated client
 const client = createClient({
-  server: 'http://localhost:8080'
+  server: 'http://localhost:8080',
+  login: '1000',
+  password: 'DemoMaster'
 });
 
 const login = 50001;
@@ -79,9 +125,22 @@ await client.stream.connect();
 
 ### 1. Accounts API
 
-Manage MT5 accounts with advanced filtering and statistics.
+Manage accounts with advanced filtering and statistics.
 
 ```typescript
+// Create a new trading account
+const newAccount = await client.accounts.create({
+  trading_group: 'Premium',
+  country: 'MX',
+  master_password: 'SecurePass123!',
+  investor_password: 'InvestorPass123!',
+  email: 'trader@example.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  leverage: 100,
+  state: 'active'
+});
+
 // List accounts with filters
 const accounts = await client.accounts.list({
   state: 'active',
@@ -102,6 +161,13 @@ const stats = await client.accounts.getStatistics({
 // Get all account logins
 const logins = await client.accounts.getLogins();
 
+// Get account status/metrics (balance, equity, credit, margin)
+const status = await client.accounts.getStatus(50001);
+console.log('Balance:', status.data.balance);
+console.log('Equity:', status.data.equity);
+console.log('Credit:', status.data.credit);
+console.log('Margin:', status.data.margin);
+
 // Change passwords
 await client.accounts.changeMasterPassword(50001, {
   new_password: 'NewPass123!'
@@ -114,6 +180,34 @@ await client.accounts.changeInvestorPassword(50001, {
 // Archive/Unarchive
 await client.accounts.archive(50001);
 await client.accounts.unarchive(50001);
+
+// Update account information (partial update)
+await client.accounts.update(50001, {
+  email: 'newemail@example.com',
+  leverage: 200,
+  city: 'Los Angeles',
+  trading_group: 'Premium'
+});
+
+// Adjust balance or credit
+await client.accounts.balance(50001, {
+  type: 'balance',
+  amount: 500.00,
+  comment: 'Client deposit'
+});
+
+await client.accounts.balance(50001, {
+  type: 'credit',
+  amount: 1000.00,
+  comment: 'Credit line increase'
+});
+
+// Subtract balance
+await client.accounts.balance(50001, {
+  type: 'balance',
+  amount: -200.00,
+  comment: 'Withdrawal request'
+});
 ```
 
 ### 2. Orders API
@@ -340,51 +434,120 @@ const stats = await client.tradingGroups.getStatistics();
 
 ### 7. WebSocket API
 
-Real-time updates for prices, orders, positions, and balance.
+Real-time updates for positions and balance with manual channel subscription.
 
 ```typescript
+// Enable WebSocket in config
+const client = createClient({
+  server: 'http://localhost:8080',
+  login: '1000',
+  password: 'DemoMaster',
+  websocket: {
+    enabled: true,
+    autoConnect: false
+  }
+});
+
 // Connect to WebSocket
 await client.stream.connect();
 
-// Subscribe to price updates
-client.stream.onPriceUpdate((price) => {
-  console.log('Price:', price.symbol, price.bid, price.ask);
+// Subscribe to channels
+client.stream.subscribe([
+  'positions:new',      // New positions opened
+  'positions:closed',   // Positions closed (total and partial)
+  'positions:updated',  // Position PnL updates (throttled to 1 per 2s)
+  'accounts:balance'    // Balance updates
+]);
+
+// Listen to position opened events
+client.stream.onPositionOpened((event) => {
+  const pos = event.position;
+  console.log('Position opened:', pos.symbol, pos.side === 1 ? 'LONG' : 'SHORT', pos.qty);
 });
 
-// Subscribe to order updates
-client.stream.onOrderUpdate((order) => {
-  console.log('Order:', order.id, order.status);
+// Listen to position closed events
+client.stream.onPositionClosed((event) => {
+  const pos = event.position;
+  console.log('Position closed:', pos.symbol, 'PnL:', pos.net_pnl);
 });
 
-// Subscribe to position updates
-client.stream.onPositionUpdate((position) => {
-  console.log('Position:', position.id, position.profit);
+// Listen to position updated events (throttled)
+client.stream.onPositionUpdated((event) => {
+  const pos = event.position;
+  console.log('Position update:', pos.position_id, 'PnL:', pos.unrealized_pnl);
 });
 
-// Subscribe to balance updates
-client.stream.onBalanceUpdate((balance) => {
-  console.log('Balance:', balance.balance, balance.equity);
+// Listen to balance updates
+client.stream.onBalanceUpdated((event) => {
+  console.log('Balance:', event.balance, 'Equity:', event.equity);
 });
 
+// Unsubscribe from channels
+client.stream.unsubscribe(['positions:updated']);
+
 // Disconnect
-await client.stream.disconnect();
+client.stream.disconnect();
 ```
 
+**Available Channels**:
+- `positions:new` - New position opened
+- `positions:closed` - Position closed (total or partial)
+- `positions:updated` - PnL updates (throttled to max 1 per 2 seconds)
+- `accounts:balance` - Balance changes
+
 **Features**:
+- Manual subscription to specific channels
 - Auto-reconnect with exponential backoff
 - Heartbeat/ping-pong mechanism
-- Automatic subscription restoration
+- Automatic subscription restoration on reconnect
+- Throttled position updates to reduce load
+
+See [WebSocket API Documentation](docs/WEBSOCKET_API.md) for complete guide.
 
 ## 🔧 Configuration
 
+### Basic Configuration
+
 ```typescript
 const client = createClient({
-  server: 'http://localhost:8080',  // Required
-  login: 'username',                 // Optional (for future auth)
-  password: 'password'               // Optional (for future auth)
+  server: 'http://localhost:8080',  // Required: API server URL
+  login: '1000',                     // Required: Admin/API login
+  password: 'YourPassword'           // Required: Admin/API password
 });
 ```
 
+### Advanced Configuration
+
+```typescript
+const client = createClient({
+  server: 'http://localhost:8080',
+  login: '1000',
+  password: 'YourPassword',
+  
+  // WebSocket configuration (optional)
+  websocket: {
+    enabled: true,              // Enable WebSocket support
+    autoConnect: false,         // Auto-connect on client creation
+    autoReconnect: true,        // Auto-reconnect on disconnect
+    maxReconnectAttempts: 5,    // Max reconnection attempts
+    heartbeatInterval: 30000    // Heartbeat interval in ms
+  }
+});
+```
+
+### Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `server` | string | ✅ Yes | - | Pipsend API server URL |
+| `login` | string | ✅ Yes | - | Admin/API login for authentication |
+| `password` | string | ✅ Yes | - | Admin/API password |
+| `websocket.enabled` | boolean | No | `false` | Enable WebSocket support |
+| `websocket.autoConnect` | boolean | No | `false` | Auto-connect on creation |
+| `websocket.autoReconnect` | boolean | No | `true` | Auto-reconnect on disconnect |
+| `websocket.maxReconnectAttempts` | number | No | `5` | Max reconnection attempts |
+| `websocket.heartbeatInterval` | number | No | `30000` | Heartbeat interval (ms) |
+
 ## 📦 API Response Structure
 
 All API endpoints return a consistent response structure:
@@ -593,9 +756,13 @@ const candles = await client.marketData.getCandles({
 
 ## ⚠️ Error Handling
 
-Always wrap API calls in try-catch blocks:
+All errors thrown by the SDK are instances of `PipsendError` with detailed information.
+
+### Basic Error Handling
 
 ```typescript
+import { PipsendError } from '@pipsend/sdk';
+
 try {
   const trade = await client.trades.open({
     login: 50001,
@@ -607,20 +774,80 @@ try {
   
   console.log('Trade opened:', trade.position_id);
   
-} catch (error: any) {
-  // Check status code
-  if (error.status_code === 'INSUFFICIENT_MARGIN') {
-    console.error('Not enough margin to open trade');
-  } else if (error.status_code === 'SYMBOL_NOT_FOUND') {
-    console.error('Symbol does not exist');
-  } else if (error.status_code === 'VALIDATION_ERROR') {
-    console.error('Invalid parameters:', error.errors);
-  } else {
-    console.error('Unexpected error:', error.message);
+} catch (error) {
+  if (error instanceof PipsendError) {
+    console.error('Error code:', error.code);
+    console.error('Status code:', error.statusCode);
+    console.error('Message:', error.message);
+    
+    // Check if it's a validation error
+    if (error.isValidationError()) {
+      console.error('Validation errors:', error.errors);
+      // Get formatted message with all details
+      console.error(error.getDetailedMessage());
+    }
+  }
+}
+```
+
+### Handling Validation Errors (422)
+
+When the API returns validation errors, the SDK provides detailed field-level information:
+
+```typescript
+try {
+  const account = await client.accounts.create({
+    trading_group: 'InvalidGroup',
+    country: 'XYZ',
+    master_password: 'short',
+    investor_password: 'short',
+    email: 'invalid-email',
+    first_name: 'John',
+    last_name: 'Doe'
+  });
+} catch (error) {
+  if (error instanceof PipsendError && error.isValidationError()) {
+    console.log('Validation failed:');
+    
+    // Access individual validation errors
+    error.errors?.forEach(err => {
+      console.log(`  - ${err.field}: ${err.message}`);
+    });
+    
+    // Or get formatted message
+    console.log(error.getDetailedMessage());
+    
+    // Output:
+    // The provided data is not valid.
+    //   - trading_group: Trading group 'InvalidGroup' not found
+    //   - country: Country 'XYZ' not found
+    //   - master_password: The field master_password must be at least 8 characters.
+    //   - email: The field email must be a valid email address.
   }
 }
 ```
 
+### Error Properties
+
+```typescript
+interface PipsendError {
+  message: string;              // Error message
+  code: string;                 // Error code (e.g., 'VALIDATION_ERROR', 'NOT_FOUND')
+  statusCode: number;           // HTTP status code (e.g., 422, 404, 500)
+  errors?: ValidationError[];   // Validation errors (for 422 responses)
+  response?: any;               // Full error response from server
+  
+  // Helper methods
+  isValidationError(): boolean;      // Check if it's a validation error
+  getDetailedMessage(): string;      // Get formatted message with details
+}
+
+interface ValidationError {
+  field: string;    // Field name that failed validation
+  message: string;  // Validation error message
+}
+```
+
 ### Common Error Scenarios
 
 ```typescript