@gaberoo/kalshitools 1.0.2 → 1.1.0

package/dist/lib/output/formatter.js

@@ -1,39 +1,47 @@
-import Table from 'cli-table3';
 import chalk from 'chalk';
+import Table from 'cli-table3';
 /**
  * Output formatter for both human and JSON formats
  */
 export class OutputFormatter {
+    command;
     jsonMode;
     startTime;
-    command;
     constructor(jsonMode = false, command) {
         this.jsonMode = jsonMode;
         this.startTime = Date.now();
         this.command = command;
     }
     /**
-     * Output a success response
+     * Create an error response object
      */
-    success(data) {
-        if (this.jsonMode) {
-            this.outputJSON(this.createSuccessResponse(data));
-        }
-        // For human-readable output, let the caller format the data
+    createErrorResponse(code, message, details) {
+        return {
+            error: {
+                code,
+                message,
+                ...(details && { details }),
+            },
+            metadata: {
+                timestamp: new Date().toISOString(),
+                ...(this.command && { command: this.command }),
+            },
+            success: false,
+        };
     }
     /**
-     * Output an error response
+     * Create a success response object
      */
-    error(code, message, details) {
-        if (this.jsonMode) {
-            this.outputJSON(this.createErrorResponse(code, message, details));
-        }
-        else {
-            console.error(chalk.red(`Error: ${message}`));
-            if (details) {
-                console.error(chalk.gray(JSON.stringify(details, null, 2)));
-            }
-        }
+    createSuccessResponse(data) {
+        return {
+            data,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                ...(this.command && { command: this.command }),
+                duration_ms: Date.now() - this.startTime,
+            },
+            success: true,
+        };
     }
     /**
      * Create a table for human-readable output
@@ -42,8 +50,8 @@ export class OutputFormatter {
         const table = new Table({
             head: head.map((h) => chalk.cyan(h)),
             style: {
-                head: [],
                 border: ['gray'],
+                head: [],
             },
         });
         for (const row of rows) {
@@ -51,13 +59,33 @@ export class OutputFormatter {
         }
         return table;
     }
+    /**
+     * Output an error response
+     */
+    error(code, message, details) {
+        if (this.jsonMode) {
+            this.outputJSON(this.createErrorResponse(code, message, details));
+        }
+        else {
+            console.error(chalk.red(`Error: ${message}`));
+            if (details) {
+                console.error(chalk.gray(JSON.stringify(details, null, 2)));
+            }
+        }
+    }
+    /**
+     * Check if JSON mode is enabled
+     */
+    isJSONMode() {
+        return this.jsonMode;
+    }
     /**
      * Output a table
      */
     outputTable(head, rows) {
         if (this.jsonMode) {
             // In JSON mode, output structured data instead of a table
-            const data = rows.map((row) => Object.fromEntries(head.map((h, i) => [h.toLowerCase().replace(/\s+/g, '_'), row[i]])));
+            const data = rows.map((row) => Object.fromEntries(head.map((h, i) => [h.toLowerCase().replaceAll(/\s+/g, '_'), row[i]])));
             this.success(data);
         }
         else {
@@ -66,35 +94,13 @@ export class OutputFormatter {
         }
     }
     /**
-     * Create a success response object
-     */
-    createSuccessResponse(data) {
-        return {
-            success: true,
-            data,
-            metadata: {
-                timestamp: new Date().toISOString(),
-                ...(this.command && { command: this.command }),
-                duration_ms: Date.now() - this.startTime,
-            },
-        };
-    }
-    /**
-     * Create an error response object
+     * Output a success response
      */
-    createErrorResponse(code, message, details) {
-        return {
-            success: false,
-            error: {
-                code,
-                message,
-                ...(details && { details }),
-            },
-            metadata: {
-                timestamp: new Date().toISOString(),
-                ...(this.command && { command: this.command }),
-            },
-        };
+    success(data) {
+        if (this.jsonMode) {
+            this.outputJSON(this.createSuccessResponse(data));
+        }
+        // For human-readable output, let the caller format the data
     }
     /**
      * Output JSON to stdout
@@ -102,10 +108,4 @@ export class OutputFormatter {
     outputJSON(data) {
         console.log(JSON.stringify(data, null, 2));
     }
-    /**
-     * Check if JSON mode is enabled
-     */
-    isJSONMode() {
-        return this.jsonMode;
-    }
 }

package/dist/lib/retry.d.ts

@@ -2,10 +2,10 @@
  * Retry configuration
  */
 export interface RetryConfig {
-    maxAttempts?: number;
+    backoffMultiplier?: number;
     initialDelayMs?: number;
+    maxAttempts?: number;
     maxDelayMs?: number;
-    backoffMultiplier?: number;
     retryableErrors?: Array<new (...args: any[]) => Error>;
 }
 /**

package/dist/lib/retry.js

@@ -4,10 +4,10 @@ import { logger } from './logger.js';
  * Default retry configuration
  */
 const DEFAULT_RETRY_CONFIG = {
-    maxAttempts: 3,
-    initialDelayMs: 1000, // 1 second
-    maxDelayMs: 10000, // 10 seconds
     backoffMultiplier: 2,
+    initialDelayMs: 1000, // 1 second
+    maxAttempts: 3,
+    maxDelayMs: 10_000, // 10 seconds
     retryableErrors: [RateLimitError],
 };
 /**
@@ -20,7 +20,7 @@ function sleep(ms) {
  * Calculate delay with exponential backoff and jitter
  */
 function calculateDelay(attempt, config) {
-    const exponentialDelay = config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt - 1);
+    const exponentialDelay = config.initialDelayMs * config.backoffMultiplier ** (attempt - 1);
     const cappedDelay = Math.min(exponentialDelay, config.maxDelayMs);
     // Add jitter (±25% randomization)
     const jitter = cappedDelay * 0.25 * (Math.random() * 2 - 1);
@@ -40,7 +40,7 @@ export async function retry(fn, config = {}, context) {
     let lastError;
     for (let attempt = 1; attempt <= fullConfig.maxAttempts; attempt++) {
         try {
-            logger.debug({ attempt, maxAttempts: fullConfig.maxAttempts, context }, 'Attempting operation');
+            logger.debug({ attempt, context, maxAttempts: fullConfig.maxAttempts }, 'Attempting operation');
             return await fn();
         }
         catch (error) {
@@ -60,10 +60,10 @@ export async function retry(fn, config = {}, context) {
             const delayMs = calculateDelay(attempt, fullConfig);
             logger.info({
                 attempt,
-                maxAttempts: fullConfig.maxAttempts,
-                delayMs,
                 context,
+                delayMs,
                 error: lastError.message,
+                maxAttempts: fullConfig.maxAttempts,
             }, 'Operation failed, retrying after delay');
             await sleep(delayMs);
         }
@@ -75,7 +75,5 @@ export async function retry(fn, config = {}, context) {
  * Retry wrapper for async functions
  */
 export function withRetry(fn, config = {}, context) {
-    return ((...args) => {
-        return retry(() => fn(...args), config, context || fn.name);
-    });
+    return ((...args) => retry(() => fn(...args), config, context || fn.name));
 }

package/dist/lib/risk.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Risk management calculation utilities
+ */
+import type { Market, Position } from './kalshi/types.js';
+export type RiskLevel = 'HIGH' | 'LOW' | 'MEDIUM';
+/**
+ * Calculate risk score for a single position (0-100)
+ * Higher score = higher risk
+ */
+export declare function calculatePositionRiskScore(position: Position, portfolioValue: number, threshold: number): number;
+/**
+ * Detect correlated positions by grouping them by event or series
+ * Returns map of event/series ticker to positions and total exposure
+ */
+export declare function detectCorrelatedPositions(positions: Position[], markets: Market[]): Map<string, {
+    exposure: number;
+    markets: string[];
+}>;
+/**
+ * Suggest maximum safe position size based on portfolio value and risk tolerance
+ */
+export declare function suggestMaxPositionSize(balance: number, portfolioValue: number, maxPct: number): number;
+/**
+ * Group positions by event, series, or ticker
+ */
+export declare function groupPositionsBy(positions: Position[], markets: Market[], groupBy: 'event' | 'series' | 'ticker'): Map<string, {
+    positions: Position[];
+    totalExposure: number;
+}>;
+/**
+ * Calculate overall portfolio risk score (0-100) and categorize risk level
+ */
+export declare function calculatePortfolioRiskScore(positions: Position[], portfolioValue: number): {
+    level: RiskLevel;
+    score: number;
+};
+/**
+ * Identify positions that exceed a risk threshold
+ */
+export declare function identifyHighRiskPositions(positions: Position[], portfolioValue: number, threshold: number): Position[];
+/**
+ * Calculate concentration by grouping
+ * Returns sorted array of concentrations
+ */
+export declare function calculateConcentrationByGroup(positions: Position[], markets: Market[], portfolioValue: number, groupBy: 'event' | 'series' | 'ticker', threshold: number): Array<{
+    alert: boolean;
+    exposure: number;
+    markets?: string[];
+    name: string;
+    pct_of_portfolio: number;
+}>;

package/dist/lib/risk.js

@@ -0,0 +1,153 @@
+/**
+ * Risk management calculation utilities
+ */
+/**
+ * Calculate risk score for a single position (0-100)
+ * Higher score = higher risk
+ */
+export function calculatePositionRiskScore(position, portfolioValue, threshold) {
+    if (portfolioValue <= 0)
+        return 0;
+    const concentrationPct = (position.market_exposure / portfolioValue) * 100;
+    // Risk increases exponentially as concentration approaches/exceeds threshold
+    let score = (concentrationPct / threshold) * 50;
+    // Additional risk if position is unrealized loss
+    if (position.realized_pnl < 0) {
+        const lossRatio = Math.abs(position.realized_pnl) / position.total_cost;
+        score += lossRatio * 25;
+    }
+    return Math.min(100, Math.max(0, score));
+}
+/**
+ * Detect correlated positions by grouping them by event or series
+ * Returns map of event/series ticker to positions and total exposure
+ */
+export function detectCorrelatedPositions(positions, markets) {
+    const correlations = new Map();
+    // Create a map of ticker to market for quick lookup
+    const marketMap = new Map(markets.map(m => [m.ticker, m]));
+    // Group positions by event ticker
+    for (const position of positions) {
+        const market = marketMap.get(position.ticker);
+        if (!market)
+            continue;
+        const eventTicker = market.event_ticker;
+        const existing = correlations.get(eventTicker) || { exposure: 0, markets: [] };
+        existing.markets.push(position.ticker);
+        existing.exposure += position.market_exposure;
+        correlations.set(eventTicker, existing);
+    }
+    // Filter to only events with multiple positions
+    const filtered = new Map();
+    for (const [eventTicker, data] of correlations) {
+        if (data.markets.length > 1) {
+            filtered.set(eventTicker, data);
+        }
+    }
+    return filtered;
+}
+/**
+ * Suggest maximum safe position size based on portfolio value and risk tolerance
+ */
+export function suggestMaxPositionSize(balance, portfolioValue, maxPct) {
+    if (portfolioValue <= 0)
+        return balance;
+    return (portfolioValue * maxPct) / 100;
+}
+/**
+ * Group positions by event, series, or ticker
+ */
+export function groupPositionsBy(positions, markets, groupBy) {
+    const grouped = new Map();
+    // Create a map of ticker to market for quick lookup
+    const marketMap = new Map(markets.map(m => [m.ticker, m]));
+    for (const position of positions) {
+        let key;
+        if (groupBy === 'ticker') {
+            key = position.ticker;
+        }
+        else {
+            const market = marketMap.get(position.ticker);
+            if (!market)
+                continue;
+            key = groupBy === 'event' ? market.event_ticker : market.event_ticker;
+            // series - extract from event ticker (format: SERIES-SPECIFIC or just use event_ticker)
+            // For now, use event_ticker as series identifier
+        }
+        const existing = grouped.get(key) || { positions: [], totalExposure: 0 };
+        existing.positions.push(position);
+        existing.totalExposure += position.market_exposure;
+        grouped.set(key, existing);
+    }
+    return grouped;
+}
+/**
+ * Calculate overall portfolio risk score (0-100) and categorize risk level
+ */
+export function calculatePortfolioRiskScore(positions, portfolioValue) {
+    if (positions.length === 0 || portfolioValue <= 0) {
+        return { level: 'LOW', score: 0 };
+    }
+    // Calculate exposure ratio
+    const totalExposure = positions.reduce((sum, pos) => sum + pos.market_exposure, 0);
+    const exposureRatio = totalExposure / portfolioValue;
+    // Calculate concentration (largest position as % of portfolio)
+    const largestExposure = Math.max(...positions.map(pos => pos.market_exposure));
+    const largestConcentration = (largestExposure / portfolioValue) * 100;
+    // Calculate unrealized loss ratio
+    const totalUnrealizedLoss = positions
+        .filter(pos => pos.realized_pnl < 0)
+        .reduce((sum, pos) => sum + Math.abs(pos.realized_pnl), 0);
+    const lossRatio = totalExposure > 0 ? totalUnrealizedLoss / totalExposure : 0;
+    // Weighted risk score
+    let score = 0;
+    // Exposure contributes up to 40 points (0.5 exposure = 20 points, 1.0 = 40 points)
+    score += Math.min(40, exposureRatio * 40);
+    // Concentration contributes up to 30 points (20% = 15 points, 40% = 30 points)
+    score += Math.min(30, (largestConcentration / 40) * 30);
+    // Loss ratio contributes up to 30 points
+    score += Math.min(30, lossRatio * 100 * 0.3);
+    // Categorize risk level
+    let level;
+    if (score < 30)
+        level = 'LOW';
+    else if (score < 60)
+        level = 'MEDIUM';
+    else
+        level = 'HIGH';
+    return { level, score: Math.round(score) };
+}
+/**
+ * Identify positions that exceed a risk threshold
+ */
+export function identifyHighRiskPositions(positions, portfolioValue, threshold) {
+    if (portfolioValue <= 0)
+        return [];
+    return positions.filter(pos => {
+        const concentrationPct = (pos.market_exposure / portfolioValue) * 100;
+        return concentrationPct > threshold;
+    });
+}
+/**
+ * Calculate concentration by grouping
+ * Returns sorted array of concentrations
+ */
+// eslint-disable-next-line max-params
+export function calculateConcentrationByGroup(positions, markets, portfolioValue, groupBy, threshold) {
+    if (portfolioValue <= 0)
+        return [];
+    const grouped = groupPositionsBy(positions, markets, groupBy);
+    const concentrations = [];
+    for (const [name, data] of grouped) {
+        const pctOfPortfolio = (data.totalExposure / portfolioValue) * 100;
+        concentrations.push({
+            alert: pctOfPortfolio > threshold,
+            exposure: data.totalExposure,
+            markets: groupBy === 'ticker' ? undefined : data.positions.map(p => p.ticker),
+            name,
+            pct_of_portfolio: pctOfPortfolio,
+        });
+    }
+    // Sort by exposure descending
+    return concentrations.sort((a, b) => b.exposure - a.exposure);
+}

package/dist/lib/sanitize.js

@@ -14,9 +14,9 @@ export function sanitizeString(input, maxLength = 1000) {
         });
     }
     // Remove null bytes (can cause issues in some systems)
-    const sanitized = input.replace(/\0/g, '');
+    const sanitized = input.replaceAll('\0', '');
     // Remove control characters except newline, carriage return, and tab
-    return sanitized.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+    return sanitized.replaceAll(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
 }
 /**
  * Sanitize a ticker symbol
@@ -26,7 +26,7 @@ export function sanitizeTicker(ticker) {
     // Ensure uppercase
     const uppercased = sanitized.toUpperCase();
     // Remove any characters that aren't alphanumeric or hyphens
-    const cleaned = uppercased.replace(/[^A-Z0-9-]/g, '');
+    const cleaned = uppercased.replaceAll(/[^A-Z0-9-]/g, '');
     if (cleaned !== uppercased) {
         throw new ValidationError('Ticker contains invalid characters', {
             original: ticker,
@@ -75,14 +75,14 @@ export function sanitizeNumber(input, min, max) {
     }
     if (min !== undefined && num < min) {
         throw new ValidationError(`Number is below minimum value of ${min}`, {
-            value: num,
             min,
+            value: num,
         });
     }
     if (max !== undefined && num > max) {
         throw new ValidationError(`Number exceeds maximum value of ${max}`, {
-            value: num,
             max,
+            value: num,
         });
     }
     return num;
@@ -113,12 +113,12 @@ export function sanitizeBoolean(input) {
  */
 export function redactSensitive(input) {
     // Redact potential API keys (long alphanumeric strings)
-    let redacted = input.replace(/[a-zA-Z0-9]{32,}/g, '[REDACTED_KEY]');
+    let redacted = input.replaceAll(/[a-zA-Z0-9]{32,}/g, '[REDACTED_KEY]');
     // Redact email addresses
-    redacted = redacted.replace(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[REDACTED_EMAIL]');
+    redacted = redacted.replaceAll(/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g, '[REDACTED_EMAIL]');
     // Redact potential private keys (PEM format)
-    redacted = redacted.replace(/-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g, '[REDACTED_KEY]');
+    redacted = redacted.replaceAll(/-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g, '[REDACTED_KEY]');
     // Redact file paths that might contain sensitive info
-    redacted = redacted.replace(/\/[a-zA-Z0-9_\-./]+\/\.kalshitools\/[a-zA-Z0-9_\-./]+/g, '[REDACTED_PATH]');
+    redacted = redacted.replaceAll(/\/[a-zA-Z0-9_\-./]+\/\.kalshitools\/[a-zA-Z0-9_\-./]+/g, '[REDACTED_PATH]');
     return redacted;
 }

package/dist/lib/scanner.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Market scanning and opportunity detection utilities
+ */
+import type { Market, OrderBook } from './kalshi/types.js';
+export type OpportunityType = 'balanced' | 'high_liquidity' | 'high_volume' | 'wide_spread';
+/**
+ * Calculate total liquidity from an orderbook
+ */
+export declare function calculateOrderbookLiquidity(orderbook: OrderBook): {
+    noTotal: number;
+    total: number;
+    yesTotal: number;
+};
+/**
+ * Calculate bid-ask spread from an orderbook
+ *
+ * In Kalshi orderbooks:
+ * - Lower prices in the yes array are bids (buyers)
+ * - Higher prices in the yes array are asks (sellers)
+ * - Spread = ask - bid
+ */
+export declare function calculateSpread(orderbook: OrderBook): null | {
+    spreadCents: number;
+    spreadPct: number;
+    yesAsk: number;
+    yesBid: number;
+};
+/**
+ * Score a market based on liquidity, spread, and volume
+ * Returns score from 0-100
+ */
+export declare function scoreMarket(market: Market, orderbook: OrderBook, weights?: {
+    liquidity: number;
+    spread: number;
+    volume: number;
+}): number;
+/**
+ * Classify the type of opportunity a market presents
+ */
+export declare function classifyOpportunity(spread: number, liquidity: number, volume: number): OpportunityType;
+/**
+ * Generate human-readable reason for opportunity
+ */
+export declare function generateOpportunityReason(type: OpportunityType, spread: number, liquidity: number, volume: number): string;
+/**
+ * Filter markets based on criteria
+ */
+export declare function filterMarketsByCriteria<T extends {
+    liquidity: number;
+    market: Market;
+    spread: null | number;
+    volume: number;
+}>(markets: T[], criteria: {
+    maxSpread?: number;
+    minLiquidity?: number;
+    minSpread?: number;
+    minVolume?: number;
+}): T[];