@pear-protocol/hyperliquid-sdk 0.0.1 → 0.0.2

package/README.md

@@ -1,265 +1,230 @@
-# Pear Hyperliquid SDK
+# @pear-protocol/hyperliquid-sdk
 
-React SDK for Pear Protocol Hyperliquid API integration.
+> React SDK for Pear Protocol Hyperliquid API integration
+
+[![npm version](https://badge.fury.io/js/%40pear-protocol%2Fhyperliquid-sdk.svg)](https://badge.fury.io/js/%40pear-protocol%2Fhyperliquid-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A comprehensive React SDK for integrating with Pear Protocol's Hyperliquid trading platform. This SDK provides React hooks, TypeScript support, real-time WebSocket connections, and migration utilities for seamless integration.
+
+## Features
+
+- 🚀 **React Hooks**: Easy-to-use hooks for trading data and account management
+- 🔌 **Real-time WebSocket**: Live updates for positions, orders, and trade history
+- 📝 **TypeScript**: Full TypeScript support with comprehensive type definitions
+- 🔄 **Migration Tools**: Built-in SDK for migrating trading data
+- 📱 **Responsive**: Works with React 16.8+ and modern React patterns
 
 ## Installation
 
 ```bash
 npm install @pear-protocol/hyperliquid-sdk
-# or
+```
+
+or
+
+```bash
 yarn add @pear-protocol/hyperliquid-sdk
 ```
 
-## Usage
+## Quick Start
 
-### React Provider Setup
+### 1. Setup the Provider
 
-The SDK provides a React Provider that manages both the client and migration functions:
+Wrap your application with the `PearHyperliquidProvider`:
 
-```typescript
-import React from 'react';
+```tsx
 import { PearHyperliquidProvider } from '@pear-protocol/hyperliquid-sdk';
 
 function App() {
   return (
     <PearHyperliquidProvider
       config={{
-        baseUrl: 'https://api.hyperliquid.xyz',
-        timeout: 30000, // optional
-        headers: { // optional
-          'Authorization': 'Bearer your-token'
-        }
+        baseUrl: 'https://hl-v2.pearprotocol.io',
+        timeout: 30000, // Optional: Request timeout in ms
       }}
+      wsUrl="wss://hl-v2.pearprotocol.io/ws" // Optional: Custom WebSocket URL
     >
-      <YourAppComponents />
+      <YourApp />
     </PearHyperliquidProvider>
   );
 }
 ```
 
-### Using Migration Functions
+### 2. Use the Hooks
 
-The migration functions are provided directly by the PearHyperliquidProvider and accessed via hooks:
+#### Address Management
 
-```typescript
-import React from 'react';
-import { useMigrationHooks, SyncTradeHistoryDto } from '@pear-protocol/hyperliquid-sdk';
-
-function TradeHistoryMigration() {
-  const { tradeHistory } = useMigrationHooks();
-
-  const handleMigration = async () => {
-    const payload: SyncTradeHistoryDto = {
-      address: '0x1234567890abcdef1234567890abcdef12345678',
-      data: {
-        tradeHistoryId: 'trade-123',
-        positionId: 'pos-123',
-        address: '0x1234...abcd',
-        externalFeePaid: 0.001,
-        builderFeePaid: 0.0005,
-        realizedPnl: 0.15,
-        totalValue: 20000,
-        entryRatio: 0.5,
-        exitRatio: 0.5,
-        leverage: 2,
-        longAssets: [],
-        shortAssets: [],
-        createdAt: '2024-01-01T00:00:00.000Z'
-      }
-    };
-
-    try {
-      await tradeHistory.sync(payload);
-    } catch (error) {
-      console.error('Migration failed:', error);
-    }
-  };
+```tsx
+import { useAddress } from '@pear-protocol/hyperliquid-sdk';
+
+function LoginComponent() {
+  const { address, setAddress, clearAddress, isLoggedIn } = useAddress();
 
   return (
     <div>
-      <button onClick={handleMigration} disabled={tradeHistory.loading}>
-        {tradeHistory.loading ? 'Migrating...' : 'Migrate Trade History'}
-      </button>
-      
-      {tradeHistory.error && (
-        <div style={{ color: 'red' }}>
-          Error: {tradeHistory.error.message}
+      {isLoggedIn ? (
+        <div>
+          <p>Logged in as: {address}</p>
+          <button onClick={clearAddress}>Logout</button>
         </div>
+      ) : (
+        <button onClick={() => setAddress('0x1234...')}>
+          Login
+        </button>
       )}
-      
-      {tradeHistory.data && (
-        <div style={{ color: 'green' }}>
-          Success: {tradeHistory.data.message}
-          <br />
-          Position ID: {tradeHistory.data.positionId}
-          <br />
-          Trade History ID: {tradeHistory.data.tradeHistoryId}
-        </div>
-      )}
-      
-      <button onClick={tradeHistory.reset}>Reset</button>
     </div>
   );
 }
 ```
 
-### Using Generic SDK Functions
-
-For general SDK operations, use the generic hook:
-
-```typescript
-import React from 'react';
-import { usePearHyperliquid } from '@pear-protocol/hyperliquid-sdk';
+#### Trading Data
 
-function MyComponent() {
-  const { client, setAuthToken, setHeaders, getBaseUrl } = usePearHyperliquid();
+```tsx
+import { 
+  useTradeHistories, 
+  useOpenPositions, 
+  useOpenOrders, 
+  useAccountSummary 
+} from '@pear-protocol/hyperliquid-sdk';
 
-  const handleAuth = () => {
-    setAuthToken('new-bearer-token');
-  };
+function TradingDashboard() {
+  const tradeHistories = useTradeHistories();
+  const openPositions = useOpenPositions();
+  const openOrders = useOpenOrders();
+  const accountSummary = useAccountSummary();
 
   return (
     <div>
-      <p>Base URL: {getBaseUrl()}</p>
-      <button onClick={handleAuth}>Set Auth Token</button>
+      <h2>Account Summary</h2>
+      {accountSummary && (
+        <div>
+          <p>Balance: {accountSummary.balance}</p>
+          <p>Margin Used: {accountSummary.marginUsed}</p>
+        </div>
+      )}
+
+      <h2>Open Positions</h2>
+      {openPositions?.map(position => (
+        <div key={position.coin}>
+          <p>{position.coin}: {position.szi} @ {position.entryPx}</p>
+        </div>
+      ))}
+
+      <h2>Open Orders</h2>
+      {openOrders?.map(order => (
+        <div key={order.oid}>
+          <p>{order.coin}: {order.sz} @ {order.limitPx}</p>
+        </div>
+      ))}
     </div>
   );
 }
 ```
 
-### Direct Client Usage (Legacy)
+## API Reference
 
-You can still use the client directly without the provider:
+### Configuration
 
 ```typescript
-import { PearHyperliquidClient, SyncTradeHistoryDto } from '@pear-protocol/hyperliquid-sdk';
-
-const client = new PearHyperliquidClient({ baseUrl: 'https://api.hyperliquid.xyz' });
-
-const syncData: SyncTradeHistoryDto = {
-  address: '0x1234567890abcdef1234567890abcdef12345678',
-  data: {
-    tradeHistoryId: 'trade-123',
-    positionId: 'pos-123',
-    address: '0x1234...abcd',
-    externalFeePaid: 0.001,
-    builderFeePaid: 0.0005,
-    realizedPnl: 0.15,
-    totalValue: 20000,
-    entryRatio: 0.5,
-    exitRatio: 0.5,
-    leverage: 2,
-    longAssets: [],
-    shortAssets: [],
-    createdAt: '2024-01-01T00:00:00.000Z'
-  }
-};
-
-try {
-  const response = await client.syncTradeHistory(syncData);
-  console.log('Sync successful:', response.data);
-} catch (error) {
-  console.error('Sync failed:', error);
+interface PearHyperliquidConfig {
+  baseUrl: string;
+  timeout?: number;
+  headers?: Record<string, string>;
 }
 ```
 
-## API Reference
+### Hooks
 
-### PearHyperliquidProvider
+#### `useAddress()`
+Manages user address and login state.
 
-React Provider component that manages both the SDK client and migration functions.
+**Returns:**
+- `address: string | null` - Current user address
+- `setAddress: (address: string | null) => void` - Set user address
+- `clearAddress: () => void` - Clear current address
+- `isLoggedIn: boolean` - Whether user is logged in
 
-**Props:**
-- `config: PearHyperliquidConfig` - Configuration object
-  - `baseUrl: string` - Base URL for the API (required)
-  - `timeout?: number` - Request timeout in milliseconds (default: 30000)
-  - `headers?: Record<string, string>` - Additional headers
+#### `useTradeHistories()`
+Returns paginated trade history data from WebSocket.
 
-**Provides:**
-- Client instance for API calls
-- Migration functions with state management
-- Context for all child hooks
+#### `useOpenPositions()`
+Returns array of current open positions from WebSocket.
 
-### Hooks
+#### `useOpenOrders()`
+Returns array of current open orders from WebSocket.
 
-#### useMigrationHooks()
-Returns migration-specific operations managed by the provider. Must be used within `PearHyperliquidProvider`.
+#### `useAccountSummary()`
+Returns account summary including balance and margin information.
 
-**Returns:**
-- `tradeHistory.sync: (payload: SyncTradeHistoryDto) => Promise<ApiResponse<SyncTradeHistoryResponseDto>>`
-- `tradeHistory.loading: boolean` - Loading state
-- `tradeHistory.error: ApiErrorResponse | null` - Error state  
-- `tradeHistory.data: SyncTradeHistoryResponseDto | null` - Response data
-- `tradeHistory.reset: () => void` - Reset state
+### Client Methods
 
-**Future migration operations:**
-- `openPositions.sync()` - Will be added for open positions migration
-- `closedPositions.sync()` - Will be added for closed positions migration
+The `PearHyperliquidClient` provides methods for:
+- `syncTradeHistories(data: SyncTradeHistoryDto)` - Sync trade history
+- `syncOpenPositions(data: SyncOpenPositionDto)` - Sync open positions  
+- `syncOpenOrders(data: SyncOpenOrderDto)` - Sync open orders
 
-#### usePearHyperliquid()
-Returns generic SDK utilities. Must be used within `PearHyperliquidProvider`.
+### WebSocket Channels
 
-**Returns:**
-- `client: PearHyperliquidClient` - Direct client access
-- `setAuthToken: (token: string) => void` - Set authorization header
-- `setHeaders: (headers: Record<string, string>) => void` - Update request headers
-- `getBaseUrl: () => string` - Get configured base URL
+The SDK automatically subscribes to these channels when an address is set:
+- `trade-histories` - Real-time trade history updates
+- `open-positions` - Real-time position updates
+- `open-orders` - Real-time order updates
+- `account-summary` - Real-time account summary updates
 
-#### usePearHyperliquidClient()
-Lower-level hook that returns the client instance directly.
+## TypeScript Support
 
-### PearHyperliquidClient
+The SDK includes comprehensive TypeScript definitions for all data structures:
 
-#### Methods
-- `getBaseUrl(): string` - Get the configured base URL
-- `setHeaders(headers: Record<string, string>): void` - Update request headers
-- `setAuthToken(token: string): void` - Set authorization header
-- `syncTradeHistory(payload: SyncTradeHistoryDto): Promise<ApiResponse<SyncTradeHistoryResponseDto>>` - Sync trade history
-
-## Types
-
-All TypeScript types are exported from the main package:
-- `PearHyperliquidConfig`
-- `ApiResponse<T>`
-- `ApiErrorResponse`
-- `TradeHistoryAssetDataDto`
-- `TradeHistoryDataDto`
-- `SyncTradeHistoryDto`
-- `SyncTradeHistoryResponseDto`
+```typescript
+import type {
+  PearHyperliquidConfig,
+  TradeHistoryV1Dto,
+  OpenPositionDto,
+  OpenLimitOrderDto,
+  AccountSummaryResponseDto,
+  // ... and many more
+} from '@pear-protocol/hyperliquid-sdk';
+```
 
 ## Error Handling
 
-The SDK provides structured error handling with the `ApiErrorResponse` type:
+The SDK provides structured error handling:
 
 ```typescript
-interface ApiErrorResponse {
-  statusCode: number;
-  message: string;
-  error?: string;
+try {
+  await client.syncTradeHistories(data);
+} catch (error) {
+  // Error is typed as ApiErrorResponse
+  console.error(`API Error ${error.statusCode}: ${error.message}`);
 }
 ```
 
-Errors are automatically intercepted and transformed into this format.
+## Requirements
 
-## Architecture
+- React >= 16.8.0
+- Node.js >= 16.0.0
 
-The SDK follows a provider-centric architecture where:
+## Development
 
-1. **PearHyperliquidProvider** manages both the client instance and migration functions
-2. **Migration functions** are provided as part of the provider context with built-in state management
-3. **Hooks** access the provider context and must be used within the provider
-4. **State management** for migrations (loading, error, data) is handled automatically by the provider
+```bash
+# Install dependencies
+npm install
 
-This ensures that migration functions are properly integrated with React's component lifecycle and state management.
+# Build the package
+npm run build
 
-## Future Migration Operations
+# Run in development mode (watch)
+npm run dev
 
-The provider is designed to be extensible. Future versions will include additional migration functions:
-- Open positions migration
-- Closed positions migration  
-- Account data migration
-- Additional migration utilities
+# Type check
+npm run type-check
+```
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+For questions and support, please contact the Pear Protocol team.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/hyperliquid-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "description": "React SDK for Pear Protocol Hyperliquid API integration",
   "main": "dist/index.js",