clodds 1.1.0

package/dist/browser/index.js

@@ -0,0 +1,458 @@
+"use strict";
+/**
+ * Browser Control - Clawdbot-style Chrome/Chromium CDP control
+ *
+ * Features:
+ * - Launch managed browser instance
+ * - Navigate, click, type, screenshot
+ * - Profile management
+ * - Cookie/session persistence
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserService = createBrowserService;
+exports.screenshotUrl = screenshotUrl;
+exports.fetchPageContent = fetchPageContent;
+const logger_1 = require("../utils/logger");
+const events_1 = require("events");
+const child_process_1 = require("child_process");
+const os_1 = require("os");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const http = __importStar(require("http"));
+/** Simple WebSocket implementation for CDP */
+class CDPConnection extends events_1.EventEmitter {
+    ws = null;
+    messageId = 0;
+    pending = new Map();
+    async connect(wsUrl) {
+        // Dynamic import ws
+        const WebSocket = (await Promise.resolve().then(() => __importStar(require('ws')))).default;
+        return new Promise((resolve, reject) => {
+            this.ws = new WebSocket(wsUrl);
+            this.ws.on('open', () => {
+                logger_1.logger.debug({ wsUrl }, 'CDP connected');
+                resolve();
+            });
+            this.ws.on('message', (data) => {
+                const msg = JSON.parse(data.toString());
+                if (msg.id !== undefined) {
+                    const pending = this.pending.get(msg.id);
+                    if (pending) {
+                        this.pending.delete(msg.id);
+                        if (msg.error) {
+                            pending.reject(new Error(msg.error.message));
+                        }
+                        else {
+                            pending.resolve(msg.result);
+                        }
+                    }
+                }
+                else if (msg.method) {
+                    this.emit(msg.method, msg.params);
+                }
+            });
+            this.ws.on('error', (err) => {
+                logger_1.logger.error({ error: err }, 'CDP error');
+                reject(err);
+            });
+            this.ws.on('close', () => {
+                logger_1.logger.debug('CDP disconnected');
+                this.emit('disconnected');
+            });
+        });
+    }
+    async send(method, params = {}) {
+        if (!this.ws)
+            throw new Error('Not connected');
+        const id = ++this.messageId;
+        const message = JSON.stringify({ id, method, params });
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.ws.send(message);
+            // Timeout after 30s
+            setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`CDP timeout: ${method}`));
+                }
+            }, 30000);
+        });
+    }
+    close() {
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}
+function createPage(cdp, targetId) {
+    let currentUrl = '';
+    const page = {
+        async goto(url, options = {}) {
+            await cdp.send('Page.enable');
+            await cdp.send('Page.navigate', { url });
+            currentUrl = url;
+            // Wait for load
+            await new Promise((resolve) => {
+                const handler = () => {
+                    cdp.off('Page.loadEventFired', handler);
+                    resolve();
+                };
+                cdp.on('Page.loadEventFired', handler);
+                // Timeout fallback
+                setTimeout(resolve, 30000);
+            });
+            logger_1.logger.debug({ url }, 'Page navigated');
+        },
+        async click(selector) {
+            // Get element position
+            const result = await cdp.send('Runtime.evaluate', {
+                expression: `
+          (function() {
+            const el = document.querySelector(${JSON.stringify(selector)});
+            if (!el) throw new Error('Element not found: ${selector}');
+            const rect = el.getBoundingClientRect();
+            return { x: rect.x + rect.width/2, y: rect.y + rect.height/2 };
+          })()
+        `,
+                returnByValue: true,
+            });
+            const { x, y } = result.result.value;
+            // Click at position
+            await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 });
+            await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 });
+            logger_1.logger.debug({ selector }, 'Clicked element');
+        },
+        async type(selector, text, options = {}) {
+            // Focus element
+            await cdp.send('Runtime.evaluate', {
+                expression: `document.querySelector(${JSON.stringify(selector)})?.focus()`,
+            });
+            // Type each character
+            const delay = options.delay || 0;
+            for (const char of text) {
+                await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', text: char });
+                await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', text: char });
+                if (delay)
+                    await new Promise(r => setTimeout(r, delay));
+            }
+            logger_1.logger.debug({ selector, length: text.length }, 'Typed text');
+        },
+        async screenshot(options = {}) {
+            const format = options.format || 'png';
+            if (options.fullPage) {
+                // Get full page dimensions
+                const metrics = await cdp.send('Page.getLayoutMetrics');
+                await cdp.send('Emulation.setDeviceMetricsOverride', {
+                    width: Math.ceil(metrics.contentSize.width),
+                    height: Math.ceil(metrics.contentSize.height),
+                    deviceScaleFactor: 1,
+                    mobile: false,
+                });
+            }
+            const result = await cdp.send('Page.captureScreenshot', { format });
+            logger_1.logger.debug({ format, fullPage: options.fullPage }, 'Screenshot captured');
+            return Buffer.from(result.data, 'base64');
+        },
+        async content() {
+            const result = await cdp.send('Runtime.evaluate', {
+                expression: 'document.documentElement.outerHTML',
+                returnByValue: true,
+            });
+            return result.result.value;
+        },
+        async title() {
+            const result = await cdp.send('Runtime.evaluate', {
+                expression: 'document.title',
+                returnByValue: true,
+            });
+            return result.result.value;
+        },
+        url() {
+            return currentUrl;
+        },
+        async evaluate(fn, ...args) {
+            const expression = typeof fn === 'string'
+                ? fn
+                : `(${fn.toString()})(${args.map(a => JSON.stringify(a)).join(',')})`;
+            const result = await cdp.send('Runtime.evaluate', {
+                expression,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            return result.result.value;
+        },
+        async waitForSelector(selector, options = {}) {
+            const timeout = options.timeout || 30000;
+            const start = Date.now();
+            while (Date.now() - start < timeout) {
+                const result = await cdp.send('Runtime.evaluate', {
+                    expression: `!!document.querySelector(${JSON.stringify(selector)})`,
+                    returnByValue: true,
+                });
+                if (result.result.value)
+                    return;
+                await new Promise(r => setTimeout(r, 100));
+            }
+            throw new Error(`Timeout waiting for selector: ${selector}`);
+        },
+        async waitForNavigation(options = {}) {
+            const timeout = options.timeout || 30000;
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new Error('Navigation timeout')), timeout);
+                const handler = () => {
+                    clearTimeout(timer);
+                    cdp.off('Page.loadEventFired', handler);
+                    resolve();
+                };
+                cdp.on('Page.loadEventFired', handler);
+            });
+        },
+        async setViewport(width, height) {
+            await cdp.send('Emulation.setDeviceMetricsOverride', {
+                width,
+                height,
+                deviceScaleFactor: 1,
+                mobile: false,
+            });
+        },
+        async cookies() {
+            const result = await cdp.send('Network.getAllCookies');
+            return result.cookies;
+        },
+        async setCookie(name, value, options = {}) {
+            await cdp.send('Network.setCookie', {
+                name,
+                value,
+                domain: options.domain || new URL(currentUrl).hostname,
+                path: options.path || '/',
+            });
+        },
+        async close() {
+            await cdp.send('Target.closeTarget', { targetId });
+            cdp.close();
+            logger_1.logger.debug({ targetId }, 'Page closed');
+        },
+    };
+    return page;
+}
+/** Find Chrome executable */
+function findChrome() {
+    const os = (0, os_1.platform)();
+    const paths = os === 'darwin' ? [
+        '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+        '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        `${(0, os_1.homedir)()}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+    ] : os === 'linux' ? [
+        '/usr/bin/google-chrome',
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ] : [
+        'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+        'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    ];
+    for (const p of paths) {
+        if ((0, fs_1.existsSync)(p))
+            return p;
+    }
+    return null;
+}
+/** Get list of targets from CDP */
+async function getTargets(port) {
+    return new Promise((resolve, reject) => {
+        http.get(`http://127.0.0.1:${port}/json/list`, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        }).on('error', reject);
+    });
+}
+/** Create new target */
+async function createTarget(port, url = 'about:blank') {
+    return new Promise((resolve, reject) => {
+        http.get(`http://127.0.0.1:${port}/json/new?${url}`, (res) => {
+            let data = '';
+            res.on('data', chunk => data += chunk);
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch (e) {
+                    reject(e);
+                }
+            });
+        }).on('error', reject);
+    });
+}
+function createBrowserService() {
+    let process = null;
+    let debuggingPort = 0;
+    let running = false;
+    const pages = [];
+    return {
+        async launch(options = {}) {
+            const chromePath = options.executablePath || findChrome();
+            if (!chromePath) {
+                throw new Error('Chrome not found. Install Chrome or specify executablePath.');
+            }
+            // Find available port
+            debuggingPort = 9222 + Math.floor(Math.random() * 100);
+            // User data dir for profile persistence
+            const userDataDir = options.userDataDir || (0, path_1.join)((0, os_1.homedir)(), '.clodds', 'browser-profile');
+            if (!(0, fs_1.existsSync)(userDataDir)) {
+                (0, fs_1.mkdirSync)(userDataDir, { recursive: true });
+            }
+            const args = [
+                `--remote-debugging-port=${debuggingPort}`,
+                `--user-data-dir=${userDataDir}`,
+                '--no-first-run',
+                '--no-default-browser-check',
+                ...(options.headless !== false ? ['--headless=new'] : []),
+                ...(options.args || []),
+            ];
+            logger_1.logger.info({ chromePath, port: debuggingPort, headless: options.headless !== false }, 'Launching browser');
+            process = (0, child_process_1.spawn)(chromePath, args, {
+                stdio: 'ignore',
+                detached: false,
+            });
+            process.on('exit', (code) => {
+                logger_1.logger.debug({ code }, 'Browser process exited');
+                running = false;
+                process = null;
+            });
+            // Wait for CDP to be ready
+            let attempts = 0;
+            while (attempts < 30) {
+                try {
+                    await getTargets(debuggingPort);
+                    running = true;
+                    logger_1.logger.info({ port: debuggingPort }, 'Browser launched');
+                    return;
+                }
+                catch {
+                    await new Promise(r => setTimeout(r, 100));
+                    attempts++;
+                }
+            }
+            throw new Error('Browser failed to start');
+        },
+        async newPage() {
+            if (!running)
+                throw new Error('Browser not running');
+            const target = await createTarget(debuggingPort);
+            if (!target.webSocketDebuggerUrl) {
+                throw new Error('Failed to create page');
+            }
+            const cdp = new CDPConnection();
+            await cdp.connect(target.webSocketDebuggerUrl);
+            // Enable required domains
+            await cdp.send('Page.enable');
+            await cdp.send('Runtime.enable');
+            await cdp.send('Network.enable');
+            const page = createPage(cdp, target.id);
+            pages.push(page);
+            logger_1.logger.debug({ targetId: target.id }, 'New page created');
+            return page;
+        },
+        async pages() {
+            return [...pages];
+        },
+        async close() {
+            // Close all pages
+            for (const page of pages) {
+                try {
+                    await page.close();
+                }
+                catch { }
+            }
+            pages.length = 0;
+            // Kill browser process
+            if (process) {
+                process.kill();
+                process = null;
+            }
+            running = false;
+            logger_1.logger.info('Browser closed');
+        },
+        isRunning() {
+            return running;
+        },
+    };
+}
+// =============================================================================
+// CONVENIENCE FUNCTIONS
+// =============================================================================
+/** Quick screenshot of a URL */
+async function screenshotUrl(url, options) {
+    const browser = createBrowserService();
+    await browser.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        await page.goto(url);
+        const screenshot = await page.screenshot({ fullPage: options?.fullPage });
+        return screenshot;
+    }
+    finally {
+        await browser.close();
+    }
+}
+/** Quick page content extraction */
+async function fetchPageContent(url) {
+    const browser = createBrowserService();
+    await browser.launch({ headless: true });
+    try {
+        const page = await browser.newPage();
+        await page.goto(url);
+        return {
+            title: await page.title(),
+            content: await page.content(),
+            url: page.url(),
+        };
+    }
+    finally {
+        await browser.close();
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"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"}

package/dist/cache/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * LRU Cache with TTL Support
+ *
+ * High-performance caching for Clodds hot paths:
+ * - Market lookups
+ * - API key validation
+ * - Price subscriptions
+ *
+ * Features:
+ * - LRU eviction policy
+ * - Per-entry TTL
+ * - Memory-efficient storage
+ * - Cache statistics
+ */
+export interface CacheOptions<K = string, V = unknown> {
+    /** Maximum number of entries (default: 1000) */
+    maxSize?: number;
+    /** Default TTL in ms (default: 60000 = 1 minute) */
+    defaultTtl?: number;
+    /** Name for logging (default: 'cache') */
+    name?: string;
+    /** Custom key serializer for complex keys */
+    keySerializer?: (key: K) => string;
+    /** On eviction callback */
+    onEvict?: (key: K, value: V, reason: EvictionReason) => void;
+    /** Enable stats collection (default: true) */
+    collectStats?: boolean;
+}
+export interface CacheEntry<V> {
+    value: V;
+    expiresAt: number;
+    createdAt: number;
+    accessCount: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    evictions: number;
+    size: number;
+    maxSize: number;
+    hitRate: number;
+}
+export type EvictionReason = 'expired' | 'capacity' | 'manual';
+export interface LRUCache<K = string, V = unknown> {
+    /** Get value from cache */
+    get(key: K): V | undefined;
+    /** Get value or compute if missing */
+    getOrSet(key: K, compute: () => V | Promise<V>, ttl?: number): Promise<V>;
+    /** Set value in cache */
+    set(key: K, value: V, ttl?: number): void;
+    /** Check if key exists and is not expired */
+    has(key: K): boolean;
+    /** Delete key from cache */
+    delete(key: K): boolean;
+    /** Clear all entries */
+    clear(): void;
+    /** Get cache statistics */
+    stats(): CacheStats;
+    /** Reset statistics */
+    resetStats(): void;
+    /** Get all keys */
+    keys(): K[];
+    /** Get size */
+    size(): number;
+    /** Prune expired entries */
+    prune(): number;
+}
+export declare function createCache<K = string, V = unknown>(options?: CacheOptions<K, V>): LRUCache<K, V>;
+/**
+ * Market cache - for caching market data lookups
+ */
+export interface MarketCacheKey {
+    platform?: string;
+    marketId: string;
+}
+export declare function createMarketCache<V = unknown>(options?: Omit<CacheOptions<MarketCacheKey, V>, 'keySerializer'>): LRUCache<MarketCacheKey, V>;
+/**
+ * API key validation cache - brief caching for validated keys
+ */
+export interface ApiKeyCacheKey {
+    keyId: string;
+    secretHash: string;
+}
+export declare function createApiKeyCache<V = unknown>(options?: Omit<CacheOptions<ApiKeyCacheKey, V>, 'keySerializer'>): LRUCache<ApiKeyCacheKey, V>;
+/**
+ * Subscription deduplication cache - track active subscriptions
+ */
+export interface SubscriptionKey {
+    platform: string;
+    marketId: string;
+    callbackId: string;
+}
+export declare function createSubscriptionCache<V = number>(options?: Omit<CacheOptions<SubscriptionKey, V>, 'keySerializer'>): LRUCache<SubscriptionKey, V>;
+/**
+ * Batch get multiple keys at once
+ */
+export declare function batchGet<K, V>(cache: LRUCache<K, V>, keys: K[]): Map<K, V | undefined>;
+/**
+ * Batch set multiple key-value pairs
+ */
+export declare function batchSet<K, V>(cache: LRUCache<K, V>, entries: Array<[K, V, number?]>): void;
+/**
+ * Get multiple values, computing missing ones in batch
+ */
+export declare function batchGetOrCompute<K, V>(cache: LRUCache<K, V>, keys: K[], computeBatch: (missingKeys: K[]) => Promise<Map<K, V>>, ttl?: number): Promise<Map<K, V>>;