@vesper85/strategy-sdk 0.1.0 → 0.1.2

package/README.md

@@ -24,7 +24,7 @@ yarn add @osiris-ai/strategy-sdk
 
 ## Quick Start
 
-### 1. Create a Strategy (Tick-Based)
+### 1. Create a Tick-Based Strategy
 
 ```typescript
 import type { OsirisContext, CodeStrategy } from '@osiris-ai/strategy-sdk';
@@ -45,41 +45,72 @@ export default class MyStrategy implements CodeStrategy {
 }
 ```
 
-### 2. Run the Strategy
+### 2. Create an Event-Based Strategy
+
+```typescript
+import type { 
+    CodeStrategy, 
+    EventSubscription, 
+    StrategyEvent, 
+    OsirisContext 
+} from '@osiris-ai/strategy-sdk';
+
+export class PriceAlertStrategy implements CodeStrategy {
+    // Define what events to subscribe to
+    subscriptions: EventSubscription[] = [
+        {
+            type: 'price',
+            market: 'BTC-USD',
+            conditions: { priceChangePercent: 5 }
+        }
+    ];
+
+    // Called when subscribed events occur
+    async onEvent(event: StrategyEvent, osiris: OsirisContext): Promise<void> {
+        osiris.log(`Price event for ${event.market}: ${event.data.price}`);
+    }
+}
+```
+
+### 3. Run the Strategy
 
 ```typescript
 import {
     createOsirisContext,
     createConsoleLogger,
-    runStrategy,
+    createStrategyEngine,
+    createEventRunner,
     PrivateKeySigner,
 } from '@osiris-ai/strategy-sdk';
-import MyStrategy from './my-strategy';
 
 async function main() {
     const logger = createConsoleLogger();
 
-    // Create signer
     const signer = new PrivateKeySigner({
         privateKey: process.env.PRIVATE_KEY!,
     });
 
-    // Create context
     const context = createOsirisContext({
         strategyId: 'my-strategy',
-        market: 'hyperliquid', // or 'polymarket'
+        market: 'hyperliquid',
         userAddress: signer.getAddress()!,
         signer,
     });
 
-    // Create strategy instance
-    const strategy = new MyStrategy();
-
-    // Run strategy once
-    await runStrategy(strategy, { logger }, context);
+    // For tick-based strategies
+    const engine = createStrategyEngine(strategy, {
+        logger,
+        tickIntervalMs: 60000,
+    }, context);
+    engine.start();
+
+    // For event-based strategies
+    const runner = createEventRunner(strategy, {
+        logger,
+        eventSourceUrl: 'wss://events.example.com/ws',
+    }, context);
+    runner.start();
 }
-
-main();
 ```
 
 ## Execution Modes
@@ -102,7 +133,7 @@ import { createStrategyEngine } from '@osiris-ai/strategy-sdk';
 
 const engine = createStrategyEngine(strategy, {
     logger,
-    strategyId: 'my-strategy', // Optional, for logging
+    strategyId: 'my-strategy',
     tickIntervalMs: 60000, // Run every 60 seconds
 }, context);
 
@@ -112,7 +143,7 @@ engine.start();
 
 ### Event-Based Execution (Real-time WebSocket)
 
-Reacts to real-time events from your WebSocket server. Best for reactive strategies (price alerts, arbitrage, etc.)
+Reacts to real-time events from WebSocket streams. Best for strategies that need immediate response to market changes.
 
 ```typescript
 interface CodeStrategy {
@@ -121,55 +152,121 @@ interface CodeStrategy {
 }
 ```
 
+## Event Subscription Types
+
+The SDK uses a discriminated union for type-safe event subscriptions:
+
+### MarketSubscription
+
+Subscribe to market events (price, orderbook, trade, fill):
+
 ```typescript
-import { createEventRunner, type EventSubscription, type StrategyEvent } from '@osiris-ai/strategy-sdk';
+{
+    type: 'price',  // or 'orderbook', 'trade', 'fill'
+    market: 'BTC-USD',
+    eventSource: 'polymarket',  // optional
+    conditions: {
+        priceChangePercent: 5,
+        volumeAbove: 10000,
+    }
+}
+```
 
-class PriceAlertStrategy implements CodeStrategy {
-    subscriptions: EventSubscription[] = [
-        {
-            type: 'price',
-            market: 'BTC-USD',
-            conditions: { priceChangePercent: 5 }
-        }
-    ];
+### WalletSubscription
 
-    async onEvent(event: StrategyEvent, osiris: OsirisContext): Promise<void> {
-        osiris.log(`Price changed: ${event.data.changePercent}%`);
-        // React to price change...
+Subscribe to wallet analysis events (Osiris Pub/Sub only):
+
+```typescript
+{
+    type: 'wallet',
+    wallet: '0x1234567890abcdef...',
+    conditions: {
+        minWinRate: 60,
+        minTradeCount: 10,
     }
 }
+```
+
+### OpportunitySubscription
+
+Subscribe to trading opportunities (Osiris Pub/Sub only):
+
+```typescript
+{
+    type: 'opportunity',
+    filter: 'wide_spread_markets',  // optional, defaults to 'all'
+    conditions: {
+        minScore: 70,
+    }
+}
+```
+
+### CustomSubscription
 
+Subscribe to custom topics:
+
+```typescript
+{
+    type: 'custom',
+    topic: 'custom:my-topic',
+}
+```
+
+## Event Sources
+
+### Osiris Pub/Sub
+
+Connect to Osiris analytics WebSocket for market analysis, wallet tracking, and opportunities:
+
+```typescript
 const runner = createEventRunner(strategy, {
     logger,
-    eventSourceUrl: 'wss://your-event-server.com/ws',
-    strategyId: 'price-alert', // Optional
+    eventSourceUrl: 'wss://your-osiris-server.com/ws',
 }, context);
-
-runner.start();
-// runner.stop();
 ```
 
-#### Event Types
+**Supported topics:**
+- `market:{slug}` - Market analysis events
+- `wallet:{address}` - Wallet analysis events
+- `opps:{filter}` - Trading opportunities
+
+### Polymarket RTDS
+
+Connect directly to Polymarket's Real-Time Data Socket:
 
 ```typescript
-type EventType = 'price' | 'orderbook' | 'time' | 'trade' | 'fill' | 'liquidation' | 'custom';
+// Set eventSource: 'polymarket' in subscriptions
+subscriptions: EventSubscription[] = [
+    {
+        type: 'price',
+        eventSource: 'polymarket',
+        market: 'ETH',
+    }
+];
+
+const runner = createEventRunner(strategy, {
+    logger,
+    polymarket: {
+        walletAddress: '0x...',
+        // clobAuth: { ... } for private subscriptions
+    },
+}, context);
 ```
 
-#### Event Subscriptions
+## Type Guards
+
+Use type guards for runtime type checking:
 
 ```typescript
-interface EventSubscription {
-    type: EventType;
-    market?: string;
-    conditions?: {
-        priceAbove?: number;
-        priceBelow?: number;
-        priceChangePercent?: number;
-        spreadAbove?: number;
-        volumeAbove?: number;
-        cron?: string;
-        interval?: number;
-    };
+import { 
+    isMarketSubscription, 
+    isWalletSubscription,
+    isOpportunitySubscription,
+    isCustomSubscription 
+} from '@osiris-ai/strategy-sdk';
+
+if (isWalletSubscription(subscription)) {
+    console.log(subscription.wallet); // TypeScript knows this is WalletSubscription
 }
 ```
 
@@ -179,20 +276,34 @@ interface EventSubscription {
 
 #### `CodeStrategy`
 
-Interface that all strategies must implement (choose one execution mode):
+Interface that all strategies must implement:
 
 ```typescript
 interface CodeStrategy {
-    // Tick-based (optional if using event-based)
+    // Tick-based execution
     shouldTrigger?(osiris: OsirisContext): Promise<boolean>;
     onTrigger?(osiris: OsirisContext): Promise<void>;
-    
-    // Event-based (optional if using tick-based)
+
+    // Event-based execution
     subscriptions?: EventSubscription[];
     onEvent?(event: StrategyEvent, osiris: OsirisContext): Promise<void>;
 }
 ```
 
+#### `StrategyEvent`
+
+Event passed to `onEvent` handler:
+
+```typescript
+interface StrategyEvent {
+    type: EventType;
+    timestamp: number;
+    market?: string;   // For market events
+    wallet?: string;   // For wallet events
+    data: EventData;
+}
+```
+
 #### `OsirisContext`
 
 The context object passed to your strategy methods:
@@ -203,21 +314,19 @@ interface OsirisContext {
     hyperliquid?: HyperliquidAPI;    // Available when market='hyperliquid'
     ta: TechnicalAnalysisAPI;        // Technical analysis functions
     state: OsirisState;              // State management
-    signer: SignerAPI;               // Transaction signer
-    log: (message: string, meta?: any) => void; // Logging function
+    signer?: SignerAPI;              // Transaction signer (if configured)
+    log: (message: string, meta?: any) => void;
 }
 ```
 
 ### State Management
 
-#### In Strategy
+#### In-Memory State (for testing)
 
 ```typescript
-// Get state
-const value = await osiris.state.get('myKey');
+import { MemoryStateManager } from '@osiris-ai/strategy-sdk';
 
-// Set state
-await osiris.state.set('myKey', { count: 42 });
+const stateManager = new MemoryStateManager();
 ```
 
 #### Redis State (for production)
@@ -232,83 +341,35 @@ const stateManager = new RedisStateManager(
 );
 
 await stateManager.connect();
-// ... use stateManager
-await stateManager.disconnect();
 ```
 
 ### Market APIs
 
-#### Polymarket Trading
-
-```typescript
-if (osiris.polymarket) {
-    // Initialize trading client (required before trading)
-    await osiris.polymarket.initializeTradingClient();
-    
-    // ============================================
-    // Convenience Trading Methods (Recommended)
-    // ============================================
-    
-    // Limit orders
-    await osiris.polymarket.buyLimit(tokenId, 0.65, 100);    // Buy 100 shares @ $0.65
-    await osiris.polymarket.sellLimit(tokenId, 0.70, 50);    // Sell 50 shares @ $0.70
-    
-    // Market orders (execute immediately)
-    await osiris.polymarket.buyMarket(tokenId, 100);         // Buy $100 worth
-    await osiris.polymarket.sellMarket(tokenId, 50);         // Sell 50 shares
-    
-    // ============================================
-    // Full Order Methods (More control)
-    // ============================================
-    
-    await osiris.polymarket.createLimitOrder({
-        tokenId: '0x...',
-        price: 0.65,
-        size: 100,
-        side: 'BUY',
-        feeRateBps: '0',
-    });
-    
-    await osiris.polymarket.createMarketOrder({
-        tokenId: '0x...',
-        amount: 100,
-        side: 'BUY',
-        slippageTolerance: 0.05,
-    });
-    
-    // Order management
-    const orders = await osiris.polymarket.getOpenOrders();
-    await osiris.polymarket.cancelOrder(orderId);
-    await osiris.polymarket.cancelAllOrders();
-    
-    // Market data
-    const market = await osiris.polymarket.getMarket('market-slug');
-    const markets = await osiris.polymarket.getMarkets({ active: true, limit: 50 });
-    const orderBook = await osiris.polymarket.getOrderBook(tokenId);
-}
-```
-
-#### Hyperliquid Trading
+#### Hyperliquid API
 
 ```typescript
 if (osiris.hyperliquid) {
-    // Get price
     const price = await osiris.hyperliquid.getPrice('BTC');
-
-    // Get position
     const position = await osiris.hyperliquid.getPosition('BTC');
-
-    // Get all positions
     const positions = await osiris.hyperliquid.getPositions();
+}
+```
 
-    // Get candle data
-    const candles = await osiris.hyperliquid.getCandleSnapshot(
-        'BTC', '1d', startTime, endTime
-    );
+#### Polymarket API
 
-    // Execute trades
-    await osiris.hyperliquid.buy('BTC', 0.1);
-    await osiris.hyperliquid.sell('BTC', 0.1);
+```typescript
+if (osiris.polymarket) {
+    const market = await osiris.polymarket.getMarket('market-slug');
+    const markets = await osiris.polymarket.getMarkets({ active: true });
+
+    // Trading (requires initialization)
+    await osiris.polymarket.initializeTradingClient();
+    await osiris.polymarket.createLimitOrder({
+        tokenId: 'token-id',
+        side: 'BUY',
+        price: 0.5,
+        size: 10,
+    });
 }
 ```
 
@@ -318,18 +379,13 @@ if (osiris.hyperliquid) {
 // Calculate RSI
 const rsi = osiris.ta.calculate('rsi_14', ohlcvData, { period: 14 });
 
-// Calculate MACD (returns [MACD, signal, histogram])
+// Calculate MACD
 const macd = osiris.ta.calculate('macd_12_26_9', ohlcvData, {
     fastPeriod: 12,
     slowPeriod: 26,
     signalPeriod: 9
 });
 
-// Get specific component from multi-value indicator
-const macdSignal = osiris.ta.calculate('macd_12_26_9', ohlcvData, {
-    component: 'signal'
-});
-
 // Available indicators:
 // Single-value: rsi, sma, ema, atr, adx, obv, cci, mfi, vwap, williams_r, roc, psar, wma
 // Multi-value: macd, bollinger_bands, stochastic, stochastic_rsi, keltner_channels
@@ -337,111 +393,44 @@ const macdSignal = osiris.ta.calculate('macd_12_26_9', ohlcvData, {
 
 ### Signing Transactions
 
-#### Using Private Key Signer
-
 ```typescript
-import { PrivateKeySigner, createOsirisContext } from '@osiris-ai/strategy-sdk';
+import { PrivateKeySigner, OsirisSigner } from '@osiris-ai/strategy-sdk';
 
+// Private key signer
 const signer = new PrivateKeySigner({
     privateKey: process.env.PRIVATE_KEY!,
 });
 
-const address = signer.getAddress();
-
-const context = createOsirisContext({
-    strategyId: 'my-strategy',
-    market: 'polymarket',
-    userAddress: address!,
-    signer,
-});
-```
-
-#### Using Osiris Hub Signer
-
-```typescript
-import { OsirisSigner, createOsirisContext } from '@osiris-ai/strategy-sdk';
-
-const signer = new OsirisSigner({
+// Osiris Hub signer (for managed wallets)
+const osirisSigner = new OsirisSigner({
     hubBaseUrl: 'https://api.osirislabs.xyz/v1',
-    accessToken: process.env.OSIRIS_ACCESS_TOKEN!,
-    connectionId: process.env.WALLET_CONNECTION_ID!,
+    accessToken: 'your-oauth-token',
+    connectionId: 'wallet-connection-id',
 });
 
+// Use in context
 const context = createOsirisContext({
     strategyId: 'my-strategy',
     market: 'polymarket',
-    userAddress: '0x...',
+    userAddress: signer.getAddress()!,
     signer,
-    polymarketOptions: {
-        useMcpForOrders: true,
-        mcpUrl: 'https://gateway.backend.osirislabs.xyz/@osiris/polymarket/mcp',
-        mcpAccessToken: process.env.MCP_ACCESS_TOKEN!,
-    },
 });
 ```
 
-### Logging
-
-```typescript
-import { createConsoleLogger } from '@osiris-ai/strategy-sdk';
-
-const logger = createConsoleLogger();
-```
-
 ## Examples
 
-See the `examples/` directory:
-
-- `example-rsi.ts` - RSI-based trading strategy (tick-based)
-- `example-polymarket.ts` - Polymarket arbitrage strategy (tick-based)
-- `example-event-strategy.ts` - Price alert strategy (event-based)
-- `example-usage.ts` - Complete usage examples
-- `example-signer.ts` - Signer usage examples
-
-## Strategy Patterns
-
-### Tick-Based Strategy Pattern
-
-```typescript
-class MyTickStrategy implements CodeStrategy {
-    async shouldTrigger(osiris: OsirisContext): Promise<boolean> {
-        // Called every tick - return true to execute
-        return true;
-    }
-
-    async onTrigger(osiris: OsirisContext): Promise<void> {
-        // Your trading logic
-    }
-}
-```
-
-### Event-Based Strategy Pattern
-
-```typescript
-class MyEventStrategy implements CodeStrategy {
-    subscriptions: EventSubscription[] = [
-        { type: 'price', market: 'BTC-USD', conditions: { priceChangePercent: 5 } }
-    ];
+See the `examples/` directory for complete working examples:
 
-    async onEvent(event: StrategyEvent, osiris: OsirisContext): Promise<void> {
-        // Triggered by real-time events
-        osiris.log(`Event: ${event.type} - ${JSON.stringify(event.data)}`);
-    }
-}
-```
+- `example-event-strategy.ts` - Event-based price alert strategy
+- `example-polymarket-events.ts` - Polymarket RTDS integration
 
 ## Best Practices
 
-1. **State Management**: Use `osiris.state` for persistent data that should survive restarts
-2. **Error Handling**: Always wrap API calls in try-catch blocks
-3. **Rate Limiting**: Be mindful of API rate limits when making frequent calls
-4. **Testing**: Use `MemoryStateManager` for testing, `RedisStateManager` for production
-5. **Logging**: Use `osiris.log()` for strategy-specific logs
-6. **Execution Mode**: Choose tick-based for polling, event-based for real-time reactions
-
-## TypeScript Support
-
-The SDK is written in TypeScript and provides full type definitions. All types are exported.
+1. **Choose the right execution mode**: Use tick-based for periodic checks, event-based for real-time reactions
+2. **State Management**: Use `osiris.state` for persistent data that should survive restarts
+3. **Error Handling**: Always wrap API calls in try-catch blocks
+4. **Rate Limiting**: Be mindful of API rate limits when making frequent calls
+5. **Testing**: Use `MemoryStateManager` for testing, `RedisStateManager` for production
 
 ## License
 

package/dist/clients/polymarket-client.d.ts

@@ -87,22 +87,6 @@ export declare class PolymarketClient implements PolymarketAPI {
     private ensureApprovals;
     buy(tokenId: string, size: number): Promise<void>;
     sell(tokenId: string, size: number): Promise<void>;
-    /**
-     * Place a limit buy order
-     */
-    buyLimit(tokenId: string, price: number, size: number): Promise<PolymarketOrderResponse>;
-    /**
-     * Place a limit sell order
-     */
-    sellLimit(tokenId: string, price: number, size: number): Promise<PolymarketOrderResponse>;
-    /**
-     * Place a market buy order
-     */
-    buyMarket(tokenId: string, amount: number, slippage?: number): Promise<PolymarketOrderResponse>;
-    /**
-     * Place a market sell order
-     */
-    sellMarket(tokenId: string, size: number, slippage?: number): Promise<PolymarketOrderResponse>;
     getPrice(ticker: string): Promise<number>;
     getIndicator(ticker: string, indicator: string, params?: any): Promise<number>;
     search(params: SearchParams): Promise<SearchResults>;

package/dist/engine/event-runner.d.ts

@@ -1,16 +1,24 @@
 import type { CodeStrategy } from "../types/strategy";
 import type { OsirisContext } from "../types/osiris";
 import type { Logger } from "../utils/logger";
+import { PolymarketEventRunner, type PolymarketClobAuth } from "./polymarket-event-runner";
+export type EventRunner = OsirisEventRunner | PolymarketEventRunner;
 /**
  * Configuration for the EventRunner
  */
 export interface EventRunnerConfig {
     /** Logger instance for logging */
     logger: Logger;
-    /** WebSocket URL for the event source server */
-    eventSourceUrl: string;
+    /** WebSocket URL for the event source server (Required for 'osiris' source) */
+    eventSourceUrl?: string;
     /** Optional strategy ID for logging (defaults to 'unnamed-strategy') */
     strategyId?: string;
+    /** Polymarket specific configuration */
+    polymarket?: {
+        clobAuth?: PolymarketClobAuth;
+        walletAddress?: string;
+        pingIntervalMs?: number;
+    };
     /** Reconnection settings */
     reconnect?: {
         /** Maximum number of reconnection attempts (default: 10) */
@@ -41,7 +49,12 @@ export interface EventRunnerConfig {
  * runner.stop();
  * ```
  */
-export declare class EventRunner {
+/**
+ * Osiris Event Runner (Generic)
+ *
+ * Connects to a generic Osiris WebSocket event source.
+ */
+export declare class OsirisEventRunner {
     private strategy;
     private config;
     private context;
@@ -87,7 +100,19 @@ export declare class EventRunner {
     /**
      * Subscribe to events based on strategy's subscriptions
      */
+    /**
+     * Subscribe to events based on strategy's subscriptions
+     * Maps SDK subscriptions to Osiris Pub/Sub protocol
+     */
     private subscribeToEvents;
+    /**
+     * Map EventSubscription to Osiris Pub/Sub topic string
+     * Uses discriminated union to properly handle each subscription type
+     */
+    private mapSubscriptionToTopic;
+    /**
+     * Unsubscribe from events before disconnecting
+     */
     /**
      * Unsubscribe from events before disconnecting
      */
@@ -96,6 +121,11 @@ export declare class EventRunner {
      * Handle incoming WebSocket messages
      */
     private handleMessage;
+    /**
+     * Map incoming Osiris message to StrategyEvent
+     * Uses proper fields for each event type (market vs wallet)
+     */
+    private mapMessageToStrategyEvent;
     /**
      * Validate that a message is a valid StrategyEvent
      */