@pipsend/sdk 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -16,15 +16,86 @@ interface WebSocketConfig {
     heartbeatInterval?: number;
 }
 /**
- * WebSocket message structure
+ * Available WebSocket channels for subscription
+ */
+type WebSocketChannel = 'positions:new' | 'positions:closed' | 'positions:updated' | 'accounts:balance';
+/**
+ * WebSocket operation types from server
+ */
+type WebSocketOperation = 'connected' | 'subscription_success' | 'unsubscription_success' | 'push' | 'error';
+/**
+ * Position event types
+ */
+type PositionEventType = 'position.opened' | 'position.closed' | 'position.partially_closed' | 'position.updated';
+/**
+ * WebSocket message structure from server
  */
 interface WebSocketMessage {
-    type: string;
-    payload?: any;
-    timestamp?: number;
+    op: WebSocketOperation;
+    topic?: string;
+    data: any;
+}
+/**
+ * Position data structure
+ */
+interface PositionData {
+    position_id: string;
+    symbol: string;
+    symbol_name?: string;
+    status: 'open' | 'closed';
+    side: 1 | -1;
+    qty: number;
+    entry_avg: number;
+    exit_avg?: number;
+    current_price?: number;
+    unrealized_pnl?: number;
+    unrealized_pnl_pct?: number;
+    net_pnl?: number;
+    net_pnl_pct?: number;
+    sl?: number;
+    tp?: number;
+    contract_size?: number;
+    point_value?: number;
+    account_ccy?: string;
+    fees_accrued?: number;
+    financing_accrued?: number;
+    close_reason?: string;
+    close_comment?: string;
+    opened_at: number;
+    updated_at: number;
+    version: number;
+}
+/**
+ * Position event structure
+ */
+interface PositionEvent {
+    type: PositionEventType;
+    ts: number;
+    account_id: string;
+    position: PositionData;
+    diff?: {
+        previous_qty: string;
+        new_qty: string;
+    };
 }
 /**
- * Real-time price update
+ * Balance update event
+ */
+interface BalanceEvent {
+    account_id: string;
+    balance: number;
+    equity: number;
+    margin: number;
+    free_margin: number;
+    margin_level: number;
+    timestamp: number;
+}
+/**
+ * WebSocket event types (internal)
+ */
+type WebSocketEventType = 'position:opened' | 'position:closed' | 'position:updated' | 'balance:updated' | 'connected' | 'disconnected' | 'error' | 'subscription_success' | 'unsubscription_success' | '*';
+/**
+ * @deprecated Use PositionEvent instead
  */
 interface PriceUpdate {
     symbol: string;
@@ -34,7 +105,7 @@ interface PriceUpdate {
     timestamp: number;
 }
 /**
- * Real-time order update
+ * @deprecated Use PositionEvent instead
  */
 interface OrderUpdate {
     orderId: string;
@@ -49,7 +120,7 @@ interface OrderUpdate {
     timestamp: number;
 }
 /**
- * Real-time position update
+ * @deprecated Use PositionEvent instead
  */
 interface PositionUpdate {
     positionId: string;
@@ -63,7 +134,7 @@ interface PositionUpdate {
     timestamp: number;
 }
 /**
- * Account balance update
+ * @deprecated Use BalanceEvent instead
  */
 interface BalanceUpdate {
     balance: number;
@@ -73,10 +144,6 @@ interface BalanceUpdate {
     marginLevel: number;
     timestamp: number;
 }
-/**
- * WebSocket event types
- */
-type WebSocketEventType = 'price' | 'order' | 'position' | 'balance' | 'connected' | 'disconnected' | 'error' | 'authenticated' | '*';
 /**
  * WebSocket event callback
  */
@@ -174,6 +241,134 @@ interface AccountStatisticsParams {
 interface ChangePasswordRequest {
     new_password: string;
 }
+/**
+ * Create account request
+ */
+interface CreateAccountRequest {
+    /** Trading group name or path (e.g., "Premium" or "Standard/VIP") */
+    trading_group: string;
+    /** Country code or name (e.g., "MX", "Mexico", "US") */
+    country: string;
+    /** Master password (minimum 8 characters) */
+    master_password: string;
+    /** Investor password (minimum 8 characters) */
+    investor_password: string;
+    /** Valid email address */
+    email: string;
+    /** First name */
+    first_name: string;
+    /** Last name */
+    last_name: string;
+    /** Specific login (auto-generated if not provided) */
+    login?: number;
+    /** Middle name */
+    middle_name?: string;
+    /** Company name */
+    company?: string;
+    /** Phone number */
+    phone?: string;
+    /** City */
+    city?: string;
+    /** Address */
+    address?: string;
+    /** Zip code */
+    zip_code?: string;
+    /** Phone password */
+    phone_password?: string;
+    /** Leverage (uses group default if not specified) */
+    leverage?: number;
+    /** Account state: "active" or "inactive" (default: "active") */
+    state?: 'active' | 'inactive';
+}
+/**
+ * Create account response
+ */
+interface CreateAccountResponse {
+    status: 'success';
+    status_code: 'CREATED';
+    data: Account;
+}
+/**
+ * Update account request (all fields are optional)
+ */
+interface UpdateAccountRequest {
+    /** Trading group name or path (e.g., "Premium" or "Standard/VIP") */
+    trading_group?: string;
+    /** Country code or name (e.g., "MX", "Mexico", "US") */
+    country?: string;
+    /** Valid email address */
+    email?: string;
+    /** First name */
+    first_name?: string;
+    /** Last name */
+    last_name?: string;
+    /** Middle name */
+    middle_name?: string;
+    /** Company name */
+    company?: string;
+    /** Phone number */
+    phone?: string;
+    /** City */
+    city?: string;
+    /** Address */
+    address?: string;
+    /** Zip code */
+    zip_code?: string;
+    /** Leverage */
+    leverage?: number;
+    /** Account state: "active" or "inactive" */
+    state?: 'active' | 'inactive';
+}
+/**
+ * Update account response
+ */
+interface UpdateAccountResponse {
+    status: 'success';
+    status_code: 'SUCCESS';
+    data: Account;
+}
+/**
+ * Adjust balance or credit request
+ */
+interface AdjustBalanceRequest {
+    /** Type of adjustment: "balance" or "credit" */
+    type: 'balance' | 'credit';
+    /** Amount to adjust (positive = add, negative = subtract) */
+    amount: number;
+    /** Descriptive comment (max 255 characters) */
+    comment?: string;
+}
+/**
+ * Adjust balance or credit response
+ */
+interface AdjustBalanceResponse {
+    status: 'success';
+    status_code: 'SUCCESS';
+    data: Account;
+}
+/**
+ * Account status/metrics
+ */
+interface AccountStatus {
+    /** Account login */
+    login: number;
+    /** Effective balance (balance + credit) */
+    balance: number;
+    /** Equity (balance + unrealized P&L) */
+    equity: number;
+    /** Available credit */
+    credit: number;
+    /** Used margin (margin required by open positions) */
+    margin: number;
+}
+/**
+ * Account status response
+ */
+interface AccountStatusResponse {
+    status: 'success';
+    status_code: 'SUCCESS';
+    data: AccountStatus;
+}
 
 /**
  * Trading Group types
@@ -750,6 +945,7 @@ interface PipsendConfig {
  */
 interface TokenInfo {
     token: string;
+    refreshToken?: string;
     expiresAt: Date;
     issuedAt: Date;
 }
@@ -765,12 +961,28 @@ interface OrderData {
     takeProfit?: number;
 }
 /**
- * Server authentication response
- * TODO: Adjust according to real API response
+ * Server authentication response from /api/v1/auth/login
  */
 interface AuthResponse {
-    token: string;
-    expiresIn: number;
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    token_type: string;
+    user: {
+        login: number;
+        email: string;
+        first_name: string;
+        last_name: string;
+        balance: number;
+    };
+    logged_with: string;
+}
+/**
+ * Validation error detail
+ */
+interface ValidationError {
+    field: string;
+    message: string;
 }
 /**
  * Custom SDK errors
@@ -778,7 +990,17 @@ interface AuthResponse {
 declare class PipsendError extends Error {
     code?: string | undefined;
     statusCode?: number | undefined;
-    constructor(message: string, code?: string | undefined, statusCode?: number | undefined);
+    errors?: ValidationError[];
+    response?: any;
+    constructor(message: string, code?: string | undefined, statusCode?: number | undefined, errors?: ValidationError[], response?: any);
+    /**
+     * Get formatted error message with validation details
+     */
+    getDetailedMessage(): string;
+    /**
+     * Check if this is a validation error
+     */
+    isValidationError(): boolean;
 }
 declare class AuthenticationError extends PipsendError {
     constructor(message: string);
@@ -790,16 +1012,59 @@ declare class WebSocketError extends PipsendError {
     constructor(message: string);
 }
 
+/**
+ * Authentication manager with auto-refresh tokens
+ */
+declare class AuthManager {
+    private config;
+    private tokenInfo?;
+    private refreshMarginMs;
+    constructor(config: PipsendConfig);
+    /**
+     * Checks if a valid token is available
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Gets the current token (if it exists and is valid)
+     */
+    getToken(): string | undefined;
+    /**
+     * Ensures a valid token exists, authenticating if necessary
+     */
+    ensureAuthenticated(): Promise<string>;
+    /**
+     * Performs authentication with the server
+     */
+    private authenticate;
+    /**
+     * Refreshes the access token using the refresh token
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * Clears the current token
+     */
+    clearToken(): void;
+    /**
+     * Checks if the token is expired or about to expire
+     */
+    private isTokenExpired;
+    /**
+     * Stores the received token information
+     */
+    private setTokenInfo;
+}
+
 /**
  * HTTP client for making requests to the Pipsend API
  */
 declare class HttpClient {
     private baseUrl;
-    constructor(baseUrl: string);
+    private authManager?;
+    constructor(baseUrl: string, authManager?: AuthManager | undefined);
     /**
      * Makes an HTTP request
      */
-    request<T>(endpoint: string, options?: RequestInit): Promise<T>;
+    request<T>(endpoint: string, options?: RequestInit, retryOn401?: boolean): Promise<T>;
     /**
      * GET request
      */
@@ -828,6 +1093,10 @@ declare class HttpClient {
 declare class AccountsAPI {
     private http;
     constructor(http: HttpClient);
+    /**
+     * Create a new trading account
+     */
+    create(request: CreateAccountRequest): Promise<CreateAccountResponse>;
     /**
      * List all accounts with optional filters and pagination
      */
@@ -836,6 +1105,10 @@ declare class AccountsAPI {
      * Get all account logins
      */
     getLogins(): Promise<number[]>;
+    /**
+     * Get account status/metrics (balance, equity, credit, margin)
+     */
+    getStatus(login: number): Promise<AccountStatusResponse>;
     /**
      * Get account statistics with optional filters
      */
@@ -856,6 +1129,16 @@ declare class AccountsAPI {
      * Unarchive an account
      */
     unarchive(login: number): Promise<void>;
+    /**
+     * Update account information (partial update)
+     * All fields are optional, only send the ones you want to update
+     */
+    update(login: number, request: UpdateAccountRequest): Promise<UpdateAccountResponse>;
+    /**
+     * Adjust balance or credit for an account
+     * The adjustment is relative: amount is added or subtracted from current value
+     */
+    balance(login: number, request: AdjustBalanceRequest): Promise<AdjustBalanceResponse>;
 }
 
 /**
@@ -1108,33 +1391,49 @@ declare class PipsendClient {
          */
         isConnected: () => boolean;
         /**
-         * Subscribes to symbols or channels
+         * Subscribes to WebSocket channels
          * @example
-         * client.stream.subscribe(['EURUSD', 'GBPUSD']);
+         * client.stream.subscribe(['positions:new', 'positions:closed']);
          */
-        subscribe: (channels: string[]) => void;
+        subscribe: (channels: WebSocketChannel[]) => void;
         /**
-         * Unsubscribes from symbols or channels
+         * Unsubscribes from WebSocket channels
          */
-        unsubscribe: (channels: string[]) => void;
+        unsubscribe: (channels: WebSocketChannel[]) => void;
         /**
          * Gets list of subscribed channels
          */
-        getSubscriptions: () => string[];
+        getSubscriptions: () => WebSocketChannel[];
+        /**
+         * Listens to position opened events
+         */
+        onPositionOpened: (callback: WebSocketCallback<PositionEvent>) => void;
+        /**
+         * Listens to position closed events (includes partial closes)
+         */
+        onPositionClosed: (callback: WebSocketCallback<PositionEvent>) => void;
+        /**
+         * Listens to position updated events (throttled to max 1 per 2 seconds)
+         */
+        onPositionUpdated: (callback: WebSocketCallback<PositionEvent>) => void;
+        /**
+         * Listens to balance updated events
+         */
+        onBalanceUpdated: (callback: WebSocketCallback<BalanceEvent>) => void;
         /**
-         * Listens to real-time price updates
+         * @deprecated Use onPositionUpdated instead
          */
         onPriceUpdate: (callback: WebSocketCallback<PriceUpdate>) => void;
         /**
-         * Listens to real-time order updates
+         * @deprecated Use onPositionOpened/onPositionClosed instead
          */
         onOrderUpdate: (callback: WebSocketCallback<OrderUpdate>) => void;
         /**
-         * Listens to real-time position updates
+         * @deprecated Use onPositionUpdated instead
          */
         onPositionUpdate: (callback: WebSocketCallback<PositionUpdate>) => void;
         /**
-         * Listens to real-time balance updates
+         * @deprecated Use onBalanceUpdated instead
          */
         onBalanceUpdate: (callback: WebSocketCallback<BalanceUpdate>) => void;
         /**