@gaberoo/kalshitools 1.0.0

package/dist/lib/output/formatter.js

@@ -0,0 +1,111 @@
+import Table from 'cli-table3';
+import chalk from 'chalk';
+/**
+ * Output formatter for both human and JSON formats
+ */
+export class OutputFormatter {
+    jsonMode;
+    startTime;
+    command;
+    constructor(jsonMode = false, command) {
+        this.jsonMode = jsonMode;
+        this.startTime = Date.now();
+        this.command = command;
+    }
+    /**
+     * Output a success response
+     */
+    success(data) {
+        if (this.jsonMode) {
+            this.outputJSON(this.createSuccessResponse(data));
+        }
+        // For human-readable output, let the caller format the data
+    }
+    /**
+     * 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)));
+            }
+        }
+    }
+    /**
+     * Create a table for human-readable output
+     */
+    createTable(head, rows) {
+        const table = new Table({
+            head: head.map((h) => chalk.cyan(h)),
+            style: {
+                head: [],
+                border: ['gray'],
+            },
+        });
+        for (const row of rows) {
+            table.push(row);
+        }
+        return table;
+    }
+    /**
+     * 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]])));
+            this.success(data);
+        }
+        else {
+            const table = this.createTable(head, rows);
+            console.log(table.toString());
+        }
+    }
+    /**
+     * 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
+     */
+    createErrorResponse(code, message, details) {
+        return {
+            success: false,
+            error: {
+                code,
+                message,
+                ...(details && { details }),
+            },
+            metadata: {
+                timestamp: new Date().toISOString(),
+                ...(this.command && { command: this.command }),
+            },
+        };
+    }
+    /**
+     * Output JSON to stdout
+     */
+    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

@@ -0,0 +1,18 @@
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    retryableErrors?: Array<new (...args: any[]) => Error>;
+}
+/**
+ * Retry a function with exponential backoff
+ */
+export declare function retry<T>(fn: () => Promise<T>, config?: RetryConfig, context?: string): Promise<T>;
+/**
+ * Retry wrapper for async functions
+ */
+export declare function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, config?: RetryConfig, context?: string): T;

package/dist/lib/retry.js

@@ -0,0 +1,81 @@
+import { RateLimitError } from './errors/base.js';
+import { logger } from './logger.js';
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxAttempts: 3,
+    initialDelayMs: 1000, // 1 second
+    maxDelayMs: 10000, // 10 seconds
+    backoffMultiplier: 2,
+    retryableErrors: [RateLimitError],
+};
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Calculate delay with exponential backoff and jitter
+ */
+function calculateDelay(attempt, config) {
+    const exponentialDelay = config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt - 1);
+    const cappedDelay = Math.min(exponentialDelay, config.maxDelayMs);
+    // Add jitter (±25% randomization)
+    const jitter = cappedDelay * 0.25 * (Math.random() * 2 - 1);
+    return Math.floor(cappedDelay + jitter);
+}
+/**
+ * Check if error is retryable
+ */
+function isRetryable(error, retryableErrors) {
+    return retryableErrors.some((ErrorClass) => error instanceof ErrorClass);
+}
+/**
+ * Retry a function with exponential backoff
+ */
+export async function retry(fn, config = {}, context) {
+    const fullConfig = { ...DEFAULT_RETRY_CONFIG, ...config };
+    let lastError;
+    for (let attempt = 1; attempt <= fullConfig.maxAttempts; attempt++) {
+        try {
+            logger.debug({ attempt, maxAttempts: fullConfig.maxAttempts, context }, 'Attempting operation');
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if we should retry
+            const shouldRetry = isRetryable(lastError, fullConfig.retryableErrors);
+            if (!shouldRetry || attempt >= fullConfig.maxAttempts) {
+                logger.warn({
+                    attempt,
+                    context,
+                    error: lastError.message,
+                    shouldRetry,
+                }, 'Operation failed, not retrying');
+                throw lastError;
+            }
+            // Calculate delay and wait
+            const delayMs = calculateDelay(attempt, fullConfig);
+            logger.info({
+                attempt,
+                maxAttempts: fullConfig.maxAttempts,
+                delayMs,
+                context,
+                error: lastError.message,
+            }, 'Operation failed, retrying after delay');
+            await sleep(delayMs);
+        }
+    }
+    // Should never reach here, but TypeScript needs it
+    throw lastError || new Error('Retry failed with unknown error');
+}
+/**
+ * Retry wrapper for async functions
+ */
+export function withRetry(fn, config = {}, context) {
+    return ((...args) => {
+        return retry(() => fn(...args), config, context || fn.name);
+    });
+}

package/dist/lib/sanitize.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sanitize a string to prevent injection attacks
+ */
+export declare function sanitizeString(input: string, maxLength?: number): string;
+/**
+ * Sanitize a ticker symbol
+ */
+export declare function sanitizeTicker(ticker: string): string;
+/**
+ * Sanitize a file path
+ */
+export declare function sanitizePath(path: string): string;
+/**
+ * Sanitize an email address
+ */
+export declare function sanitizeEmail(email: string): string;
+/**
+ * Sanitize a number (ensure it's actually a number)
+ */
+export declare function sanitizeNumber(input: unknown, min?: number, max?: number): number;
+/**
+ * Sanitize boolean input
+ */
+export declare function sanitizeBoolean(input: unknown): boolean;
+/**
+ * Redact sensitive information from a string
+ */
+export declare function redactSensitive(input: string): string;

package/dist/lib/sanitize.js

@@ -0,0 +1,124 @@
+import { ValidationError } from './errors/base.js';
+/**
+ * Sanitize a string to prevent injection attacks
+ */
+export function sanitizeString(input, maxLength = 1000) {
+    if (typeof input !== 'string') {
+        throw new ValidationError('Input must be a string');
+    }
+    // Limit length
+    if (input.length > maxLength) {
+        throw new ValidationError(`Input exceeds maximum length of ${maxLength}`, {
+            length: input.length,
+            maxLength,
+        });
+    }
+    // Remove null bytes (can cause issues in some systems)
+    const sanitized = input.replace(/\0/g, '');
+    // Remove control characters except newline, carriage return, and tab
+    return sanitized.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+}
+/**
+ * Sanitize a ticker symbol
+ */
+export function sanitizeTicker(ticker) {
+    const sanitized = sanitizeString(ticker, 100);
+    // Ensure uppercase
+    const uppercased = sanitized.toUpperCase();
+    // Remove any characters that aren't alphanumeric or hyphens
+    const cleaned = uppercased.replace(/[^A-Z0-9-]/g, '');
+    if (cleaned !== uppercased) {
+        throw new ValidationError('Ticker contains invalid characters', {
+            original: ticker,
+            sanitized: cleaned,
+        });
+    }
+    return cleaned;
+}
+/**
+ * Sanitize a file path
+ */
+export function sanitizePath(path) {
+    const sanitized = sanitizeString(path, 500);
+    // Check for path traversal attempts
+    if (sanitized.includes('..')) {
+        throw new ValidationError('Path contains path traversal sequence', { path });
+    }
+    // Check for null byte injection
+    if (sanitized.includes('\0')) {
+        throw new ValidationError('Path contains null byte', { path });
+    }
+    return sanitized;
+}
+/**
+ * Sanitize an email address
+ */
+export function sanitizeEmail(email) {
+    const sanitized = sanitizeString(email, 254); // Max email length per RFC
+    // Basic email format validation
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(sanitized)) {
+        throw new ValidationError('Invalid email format', { email: sanitized });
+    }
+    return sanitized.toLowerCase();
+}
+/**
+ * Sanitize a number (ensure it's actually a number)
+ */
+export function sanitizeNumber(input, min, max) {
+    const num = Number(input);
+    if (Number.isNaN(num)) {
+        throw new ValidationError('Input is not a valid number', { input });
+    }
+    if (!Number.isFinite(num)) {
+        throw new ValidationError('Input is not a finite number', { input });
+    }
+    if (min !== undefined && num < min) {
+        throw new ValidationError(`Number is below minimum value of ${min}`, {
+            value: num,
+            min,
+        });
+    }
+    if (max !== undefined && num > max) {
+        throw new ValidationError(`Number exceeds maximum value of ${max}`, {
+            value: num,
+            max,
+        });
+    }
+    return num;
+}
+/**
+ * Sanitize boolean input
+ */
+export function sanitizeBoolean(input) {
+    if (typeof input === 'boolean') {
+        return input;
+    }
+    if (typeof input === 'string') {
+        const lower = input.toLowerCase();
+        if (lower === 'true' || lower === '1' || lower === 'yes') {
+            return true;
+        }
+        if (lower === 'false' || lower === '0' || lower === 'no') {
+            return false;
+        }
+    }
+    if (typeof input === 'number') {
+        return Boolean(input);
+    }
+    throw new ValidationError('Input cannot be converted to boolean', { input });
+}
+/**
+ * Redact sensitive information from a string
+ */
+export function redactSensitive(input) {
+    // Redact potential API keys (long alphanumeric strings)
+    let redacted = input.replace(/[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]');
+    // Redact potential private keys (PEM format)
+    redacted = redacted.replace(/-----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]');
+    return redacted;
+}

package/dist/lib/shutdown.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Cleanup function type
+ */
+type CleanupFunction = () => Promise<void> | void;
+/**
+ * Graceful shutdown manager
+ */
+declare class ShutdownManager {
+    private cleanupFunctions;
+    private isShuttingDown;
+    private shutdownTimeout;
+    constructor();
+    /**
+     * Register a cleanup function to be called on shutdown
+     */
+    registerCleanup(fn: CleanupFunction): void;
+    /**
+     * Set shutdown timeout
+     */
+    setShutdownTimeout(ms: number): void;
+    /**
+     * Register signal handlers
+     */
+    private registerSignalHandlers;
+    /**
+     * Perform graceful shutdown
+     */
+    private shutdown;
+    /**
+     * Check if shutdown is in progress
+     */
+    isShutdownInProgress(): boolean;
+}
+export declare const shutdownManager: ShutdownManager;
+/**
+ * Register a cleanup function
+ */
+export declare function onShutdown(fn: CleanupFunction): void;
+/**
+ * Check if shutdown is in progress
+ */
+export declare function isShuttingDown(): boolean;
+export {};

package/dist/lib/shutdown.js

@@ -0,0 +1,106 @@
+import { logger } from './logger.js';
+/**
+ * Graceful shutdown manager
+ */
+class ShutdownManager {
+    cleanupFunctions = [];
+    isShuttingDown = false;
+    shutdownTimeout = 5000; // 5 seconds
+    constructor() {
+        // Register signal handlers
+        this.registerSignalHandlers();
+    }
+    /**
+     * Register a cleanup function to be called on shutdown
+     */
+    registerCleanup(fn) {
+        this.cleanupFunctions.push(fn);
+    }
+    /**
+     * Set shutdown timeout
+     */
+    setShutdownTimeout(ms) {
+        this.shutdownTimeout = ms;
+    }
+    /**
+     * Register signal handlers
+     */
+    registerSignalHandlers() {
+        // Handle SIGINT (Ctrl+C)
+        process.on('SIGINT', () => {
+            logger.info('Received SIGINT, initiating graceful shutdown...');
+            this.shutdown('SIGINT');
+        });
+        // Handle SIGTERM (kill)
+        process.on('SIGTERM', () => {
+            logger.info('Received SIGTERM, initiating graceful shutdown...');
+            this.shutdown('SIGTERM');
+        });
+        // Handle uncaught exceptions
+        process.on('uncaughtException', (error) => {
+            logger.error({ error }, 'Uncaught exception, initiating shutdown');
+            this.shutdown('uncaughtException', 1);
+        });
+        // Handle unhandled promise rejections
+        process.on('unhandledRejection', (reason) => {
+            logger.error({ reason }, 'Unhandled promise rejection, initiating shutdown');
+            this.shutdown('unhandledRejection', 1);
+        });
+    }
+    /**
+     * Perform graceful shutdown
+     */
+    async shutdown(signal, exitCode = 0) {
+        if (this.isShuttingDown) {
+            logger.warn('Shutdown already in progress');
+            return;
+        }
+        this.isShuttingDown = true;
+        logger.info({ signal, cleanupCount: this.cleanupFunctions.length }, 'Starting graceful shutdown');
+        // Set timeout for shutdown
+        const shutdownTimer = setTimeout(() => {
+            logger.error({ timeout: this.shutdownTimeout }, 'Shutdown timeout exceeded, forcing exit');
+            process.exit(exitCode || 1);
+        }, this.shutdownTimeout);
+        try {
+            // Run all cleanup functions
+            await Promise.all(this.cleanupFunctions.map(async (fn, index) => {
+                try {
+                    logger.debug({ index }, 'Running cleanup function');
+                    await fn();
+                }
+                catch (error) {
+                    logger.error({ error, index }, 'Cleanup function failed');
+                }
+            }));
+            logger.info('Graceful shutdown complete');
+            clearTimeout(shutdownTimer);
+            process.exit(exitCode);
+        }
+        catch (error) {
+            logger.error({ error }, 'Error during shutdown');
+            clearTimeout(shutdownTimer);
+            process.exit(1);
+        }
+    }
+    /**
+     * Check if shutdown is in progress
+     */
+    isShutdownInProgress() {
+        return this.isShuttingDown;
+    }
+}
+// Singleton instance
+export const shutdownManager = new ShutdownManager();
+/**
+ * Register a cleanup function
+ */
+export function onShutdown(fn) {
+    shutdownManager.registerCleanup(fn);
+}
+/**
+ * Check if shutdown is in progress
+ */
+export function isShuttingDown() {
+    return shutdownManager.isShutdownInProgress();
+}

package/dist/lib/validation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Validation utilities for trading commands
+ */
+/**
+ * Validate ticker format
+ * Kalshi tickers are typically uppercase alphanumeric with hyphens
+ */
+export declare function validateTicker(ticker: string): void;
+/**
+ * Validate order quantity
+ */
+export declare function validateQuantity(quantity: number, maxOrderSize: number): void;
+/**
+ * Validate price (for limit orders)
+ * Kalshi prices are between 0 and 1 (representing probabilities)
+ */
+export declare function validatePrice(price: number): void;
+/**
+ * Validate side
+ */
+export declare function validateSide(side: string): 'yes' | 'no';
+/**
+ * Validate action
+ */
+export declare function validateAction(action: string): 'buy' | 'sell';
+/**
+ * Validate order type
+ */
+export declare function validateOrderType(type: string): 'market' | 'limit';
+/**
+ * Calculate order cost estimate
+ */
+export declare function estimateOrderCost(side: 'yes' | 'no', action: 'buy' | 'sell', quantity: number, price?: number): {
+    min: number;
+    max: number;
+    estimate: number;
+};

package/dist/lib/validation.js

@@ -0,0 +1,120 @@
+import { ValidationError } from './errors/base.js';
+/**
+ * Validation utilities for trading commands
+ */
+/**
+ * Validate ticker format
+ * Kalshi tickers are typically uppercase alphanumeric with hyphens
+ */
+export function validateTicker(ticker) {
+    if (!ticker || ticker.trim().length === 0) {
+        throw new ValidationError('Ticker cannot be empty');
+    }
+    // Basic format check - alphanumeric and hyphens
+    if (!/^[A-Z0-9-]+$/.test(ticker)) {
+        throw new ValidationError('Ticker must contain only uppercase letters, numbers, and hyphens', {
+            ticker,
+        });
+    }
+    if (ticker.length < 3 || ticker.length > 100) {
+        throw new ValidationError('Ticker must be between 3 and 100 characters', {
+            ticker,
+            length: ticker.length,
+        });
+    }
+}
+/**
+ * Validate order quantity
+ */
+export function validateQuantity(quantity, maxOrderSize) {
+    if (!Number.isInteger(quantity)) {
+        throw new ValidationError('Quantity must be a whole number', { quantity });
+    }
+    if (quantity <= 0) {
+        throw new ValidationError('Quantity must be positive', { quantity });
+    }
+    if (quantity > maxOrderSize) {
+        throw new ValidationError(`Quantity exceeds maximum order size of ${maxOrderSize}`, {
+            quantity,
+            maxOrderSize,
+        });
+    }
+}
+/**
+ * Validate price (for limit orders)
+ * Kalshi prices are between 0 and 1 (representing probabilities)
+ */
+export function validatePrice(price) {
+    if (price < 0.01 || price > 0.99) {
+        throw new ValidationError('Price must be between 0.01 and 0.99', { price });
+    }
+    // Check for reasonable precision (2 decimal places)
+    const decimalPlaces = (price.toString().split('.')[1] || '').length;
+    if (decimalPlaces > 2) {
+        throw new ValidationError('Price cannot have more than 2 decimal places', {
+            price,
+            decimalPlaces,
+        });
+    }
+}
+/**
+ * Validate side
+ */
+export function validateSide(side) {
+    const normalized = side.toLowerCase();
+    if (normalized !== 'yes' && normalized !== 'no') {
+        throw new ValidationError('Side must be either "yes" or "no"', { side });
+    }
+    return normalized;
+}
+/**
+ * Validate action
+ */
+export function validateAction(action) {
+    const normalized = action.toLowerCase();
+    if (normalized !== 'buy' && normalized !== 'sell') {
+        throw new ValidationError('Action must be either "buy" or "sell"', { action });
+    }
+    return normalized;
+}
+/**
+ * Validate order type
+ */
+export function validateOrderType(type) {
+    const normalized = type.toLowerCase();
+    if (normalized !== 'market' && normalized !== 'limit') {
+        throw new ValidationError('Order type must be either "market" or "limit"', { type });
+    }
+    return normalized;
+}
+/**
+ * Calculate order cost estimate
+ */
+export function estimateOrderCost(side, action, quantity, price) {
+    // For buy orders, cost is quantity * price
+    // For sell orders, cost is negative (you receive funds)
+    if (action === 'buy') {
+        if (price) {
+            // Limit buy - exact price known
+            const cost = quantity * price;
+            return { min: cost, max: cost, estimate: cost };
+        }
+        else {
+            // Market buy - could fill at any price
+            // Estimate mid-range
+            const estimate = quantity * 0.5;
+            return { min: quantity * 0.01, max: quantity * 0.99, estimate };
+        }
+    }
+    else {
+        // Sell orders
+        if (price) {
+            const proceeds = quantity * price;
+            return { min: proceeds, max: proceeds, estimate: proceeds };
+        }
+        else {
+            const estimate = quantity * 0.5;
+            return { min: quantity * 0.01, max: quantity * 0.99, estimate };
+        }
+    }
+}