opencandle 0.11.0 → 0.12.0

package/src/infra/cache.ts

@@ -1,114 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-interface CacheEntry<T> {
-  value: T;
-  expiresAt: number;
-  cachedAt: number;
-}
-
-export interface StaleResult<T> {
-  value: T;
-  stale: true;
-  cachedAt: number;
-}
-
-interface StaleMetadata {
-  stale: boolean;
-  cachedAt: number;
-}
-
-const staleMetadataStorage = new AsyncLocalStorage<StaleMetadata>();
-
-export async function runWithStaleMetadata<T>(
-  fn: () => Promise<T>,
-): Promise<{ value: T; stale?: { cachedAt: number } }> {
-  const metadata: StaleMetadata = { stale: false, cachedAt: 0 };
-  const value = await staleMetadataStorage.run(metadata, fn);
-  return {
-    value,
-    stale: metadata.stale ? { cachedAt: metadata.cachedAt } : undefined,
-  };
-}
-
-export class Cache {
-  private store = new Map<string, CacheEntry<unknown>>();
-
-  get<T>(key: string): T | undefined {
-    const entry = this.store.get(key);
-    if (!entry) return undefined;
-    if (Date.now() > entry.expiresAt) return undefined;
-    return entry.value as T;
-  }
-
-  /**
-   * Return an expired entry if it exists and is within the stale limit.
-   * Unlike get(), this does not require the entry to be within its TTL.
-   * Entries beyond the stale limit are deleted.
-   */
-  getStale<T>(key: string, staleLimitMs: number): StaleResult<T> | undefined {
-    const entry = this.store.get(key);
-    if (!entry) return undefined;
-
-    if (Date.now() > entry.cachedAt + staleLimitMs) {
-      this.store.delete(key);
-      return undefined;
-    }
-
-    const metadata = staleMetadataStorage.getStore();
-    if (metadata) {
-      metadata.stale = true;
-      metadata.cachedAt = entry.cachedAt;
-    }
-    return { value: entry.value as T, stale: true, cachedAt: entry.cachedAt };
-  }
-
-  set<T>(key: string, value: T, ttlMs: number): void {
-    this.store.set(key, { value, expiresAt: Date.now() + ttlMs, cachedAt: Date.now() });
-  }
-
-  invalidate(pattern: string): void {
-    for (const key of this.store.keys()) {
-      if (key.includes(pattern)) {
-        this.store.delete(key);
-      }
-    }
-  }
-
-  clear(): void {
-    this.store.clear();
-  }
-
-  get size(): number {
-    return this.store.size;
-  }
-}
-
-// Shared cache instance
-export const cache = new Cache();
-
-// Default TTLs
-export const TTL = {
-  QUOTE: 60_000, // 1 minute
-  HISTORY: 3_600_000, // 1 hour
-  FUNDAMENTALS: 86_400_000, // 24 hours
-  MACRO: 3_600_000, // 1 hour
-  SENTIMENT: 300_000, // 5 minutes
-  OPTIONS_CHAIN: 120_000, // 2 minutes
-  SCREENER: 60_000, // 1 minute
-  CRUMB: 900_000, // 15 minutes
-  WEB_SEARCH: 300_000, // 5 minutes
-  FINNHUB_NEWS: 300_000, // 5 minutes
-} as const;
-
-// Stale limits — how long past TTL expiry a cached value is still useful as fallback
-export const STALE_LIMIT = {
-  QUOTE: 15 * 60_000, // 15 minutes
-  HISTORY: 24 * 3_600_000, // 24 hours
-  FUNDAMENTALS: 7 * 86_400_000, // 7 days
-  MACRO: 24 * 3_600_000, // 24 hours
-  SENTIMENT: 3_600_000, // 1 hour
-  OPTIONS_CHAIN: 30 * 60_000, // 30 minutes
-  SCREENER: 15 * 60_000, // 15 minutes
-  WEB_SEARCH: 3_600_000, // 1 hour
-  FINNHUB_NEWS: 3_600_000, // 1 hour
-} as const;

package/src/infra/http-client.ts

@@ -1,134 +0,0 @@
-export interface HttpClientOptions {
-  timeoutMs?: number;
-  maxRetries?: number;
-  retryDelayMs?: number;
-  maxRetryAfterMs?: number;
-  headers?: Record<string, string>;
-}
-
-const DEFAULT_OPTIONS: Required<HttpClientOptions> = {
-  timeoutMs: 10_000,
-  maxRetries: 2,
-  retryDelayMs: 1_000,
-  maxRetryAfterMs: 5_000,
-  headers: {},
-};
-
-export class HttpError extends Error {
-  constructor(
-    public readonly status: number,
-    public readonly statusText: string,
-    public readonly body: string,
-    public readonly retryAfterMs?: number,
-  ) {
-    super(`HTTP ${status} ${statusText}`);
-    this.name = "HttpError";
-  }
-}
-
-export async function httpGet<T>(url: string, options: HttpClientOptions = {}): Promise<T> {
-  return httpRequest<T>(url, { ...options, method: "GET" });
-}
-
-export async function httpPost<T>(
-  url: string,
-  body: unknown,
-  options: HttpClientOptions = {},
-): Promise<T> {
-  return httpRequest<T>(url, {
-    ...options,
-    method: "POST",
-    body: JSON.stringify(body),
-    headers: {
-      "Content-Type": "application/json",
-      ...options.headers,
-    },
-  });
-}
-
-interface HttpRequestOptions extends HttpClientOptions {
-  method: "GET" | "POST";
-  body?: string;
-}
-
-async function httpRequest<T>(url: string, options: HttpRequestOptions): Promise<T> {
-  const opts = { ...DEFAULT_OPTIONS, ...options };
-  let lastError: Error | undefined;
-
-  for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
-    let retryDelayMs: number | undefined;
-
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), opts.timeoutMs);
-
-    try {
-      const response = await fetch(url, {
-        method: opts.method,
-        signal: controller.signal,
-        headers: opts.headers,
-        ...(opts.body !== undefined && { body: opts.body }),
-      });
-
-      if (!response.ok) {
-        const body = await response.text().catch(() => "");
-        throw new HttpError(
-          response.status,
-          response.statusText,
-          body,
-          parseRetryAfterMs(response.headers?.get?.("retry-after") ?? null),
-        );
-      }
-
-      return (await response.json()) as T;
-    } catch (error) {
-      lastError = error as Error;
-      if (!isRetryableError(error)) {
-        throw error; // Don't retry client errors
-      }
-      if (attempt < opts.maxRetries) {
-        retryDelayMs =
-          error instanceof HttpError && error.status === 429 && error.retryAfterMs !== undefined
-            ? capRetryAfterMs(error.retryAfterMs, opts.maxRetryAfterMs)
-            : opts.retryDelayMs * (attempt + 1);
-      }
-    } finally {
-      clearTimeout(timeout);
-    }
-
-    if (retryDelayMs !== undefined) {
-      await sleep(retryDelayMs);
-    }
-  }
-
-  throw lastError!;
-}
-
-function isRetryableError(error: unknown): boolean {
-  if (!(error instanceof HttpError)) return true;
-  if (error.status === 429) return true;
-  return error.status < 400 || error.status >= 500;
-}
-
-function parseRetryAfterMs(value: string | null): number | undefined {
-  if (!value) return undefined;
-  const trimmed = value.trim();
-  if (trimmed.length === 0) return undefined;
-
-  const seconds = Number(trimmed);
-  if (Number.isFinite(seconds) && seconds >= 0) {
-    return seconds * 1000;
-  }
-
-  const dateMs = Date.parse(trimmed);
-  if (Number.isNaN(dateMs)) return undefined;
-  return Math.max(0, dateMs - Date.now());
-}
-
-function capRetryAfterMs(retryAfterMs: number, maxRetryAfterMs: number | undefined): number {
-  if (maxRetryAfterMs === undefined) return retryAfterMs;
-  return Math.min(retryAfterMs, Math.max(0, maxRetryAfterMs));
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}

package/src/infra/index.ts

@@ -1,14 +0,0 @@
-export { Cache, cache, TTL } from "./cache.js";
-export { type HttpClientOptions, HttpError, httpGet } from "./http-client.js";
-export {
-  ensureOpenCandleHomeDir,
-  ensureParentDir,
-  getBrowserProfileDir,
-  getConfigPath,
-  getLogsDir,
-  getOnboardingPath,
-  getOpenCandleHomeDir,
-  getStateDbPath,
-  resolveOpenCandlePath,
-} from "./opencandle-paths.js";
-export { RateLimiter, rateLimiter } from "./rate-limiter.js";

package/src/infra/native-dependencies.ts

@@ -1,84 +0,0 @@
-export function getNativeDependencyErrorMessage(
-  error: unknown,
-  dependencyName: string,
-): string | null {
-  const message = error instanceof Error ? error.message : String(error);
-  if (
-    !message.includes("NODE_MODULE_VERSION") &&
-    !message.includes("was compiled against a different Node.js version")
-  ) {
-    return null;
-  }
-
-  return (
-    `${dependencyName} native binding was built for a different Node ABI than the active Node ${process.versions.node}. ` +
-    `Run \`npm rebuild ${dependencyName}\` or reinstall dependencies under the active Node with \`npm install\`.`
-  );
-}
-
-export async function rebuildNativeDependency(dependencyName: string): Promise<void> {
-  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
-  const { spawn } = await import("node:child_process");
-
-  await new Promise<void>((resolve, reject) => {
-    const child = spawn(npmCommand, ["rebuild", dependencyName], {
-      stdio: "inherit",
-    });
-
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) {
-        resolve();
-        return;
-      }
-
-      reject(new Error(`npm rebuild ${dependencyName} failed with exit code ${code}.`));
-    });
-  });
-}
-
-export async function ensureNativeDependency({
-  dependencyName,
-  load,
-  rebuild = rebuildNativeDependency,
-  log = console.error,
-}: {
-  dependencyName: string;
-  load: () => Promise<void>;
-  rebuild?: (dependencyName: string) => Promise<void>;
-  log?: (message: string) => void;
-}): Promise<void> {
-  try {
-    await load();
-    return;
-  } catch (error) {
-    const message = getNativeDependencyErrorMessage(error, dependencyName);
-    if (!message) throw error;
-
-    log(`${message}\nAttempting \`npm rebuild ${dependencyName}\` before continuing...`);
-  }
-
-  await rebuild(dependencyName);
-
-  try {
-    await load();
-  } catch (error) {
-    const message = getNativeDependencyErrorMessage(error, dependencyName);
-    if (!message) throw error;
-
-    throw new Error(
-      `${message}\nAutomatic rebuild did not repair the native binding. Run \`npm install\` under Node ${process.versions.node} and retry.`,
-    );
-  }
-}
-
-export async function ensureOpenCandleNativeDependencies(): Promise<void> {
-  await ensureNativeDependency({
-    dependencyName: "better-sqlite3",
-    async load() {
-      const { default: Database } = await import("better-sqlite3");
-      const db = new Database(":memory:");
-      db.close();
-    },
-  });
-}

package/src/infra/node-version.ts

@@ -1,23 +0,0 @@
-const SUPPORTED_NODE_RANGE = "22.19+ or 24.x-26.x";
-
-function isSupportedNodeVersion(version: string): boolean {
-  const [majorRaw, minorRaw] = version.split(".");
-  const major = Number(majorRaw);
-  const minor = Number(minorRaw);
-
-  if (major === 22) return minor >= 19;
-  return major >= 24 && major < 27;
-}
-
-export function getUnsupportedNodeVersionMessage(
-  version: string = process.versions.node,
-): string | null {
-  if (isSupportedNodeVersion(version)) return null;
-
-  return `OpenCandle supports Node ${SUPPORTED_NODE_RANGE}. Current Node is ${version}. Use Node ${SUPPORTED_NODE_RANGE}; the repo default is Node 22.22.0 via \`nvm use\`. After switching Node versions, reinstall dependencies under the active Node with \`npm install\` or rebuild native modules with \`npm rebuild better-sqlite3\`.`;
-}
-
-export function assertSupportedNodeVersion(version?: string): void {
-  const message = getUnsupportedNodeVersionMessage(version);
-  if (message) throw new Error(message);
-}

package/src/infra/open-url.ts

@@ -1,28 +0,0 @@
-import { execFile } from "node:child_process";
-
-export function openInBrowser(url: string): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    let command: string;
-    let args: string[];
-
-    if (process.platform === "darwin") {
-      command = "open";
-      args = [url];
-    } else if (process.platform === "win32") {
-      command = "cmd";
-      args = ["/c", "start", "", url];
-    } else {
-      command = "xdg-open";
-      args = [url];
-    }
-
-    const child = execFile(command, args, { timeout: 5000 }, (error) => {
-      if (error) {
-        reject(error);
-      } else {
-        resolve();
-      }
-    });
-    child.unref();
-  });
-}

package/src/infra/opencandle-paths.ts

@@ -1,53 +0,0 @@
-import { chmodSync, existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-
-const OPENCANDLE_HOME_ENV = "OPENCANDLE_HOME";
-
-function ensureDir(path: string): void {
-  if (!existsSync(path)) {
-    mkdirSync(path, { recursive: true, mode: 0o700 });
-  }
-}
-
-export function getOpenCandleHomeDir(): string {
-  const override = process.env[OPENCANDLE_HOME_ENV];
-  return override ? resolve(override) : join(homedir(), ".opencandle");
-}
-
-export function ensureOpenCandleHomeDir(): string {
-  const home = getOpenCandleHomeDir();
-  ensureDir(home);
-  if (process.platform !== "win32") chmodSync(home, 0o700);
-  return home;
-}
-
-export function resolveOpenCandlePath(...segments: string[]): string {
-  return join(getOpenCandleHomeDir(), ...segments);
-}
-
-export function ensureParentDir(path: string): string {
-  const parent = dirname(path);
-  ensureDir(parent);
-  return parent;
-}
-
-export function getConfigPath(): string {
-  return resolveOpenCandlePath("config.json");
-}
-
-export function getOnboardingPath(): string {
-  return resolveOpenCandlePath("onboarding.json");
-}
-
-export function getStateDbPath(): string {
-  return resolveOpenCandlePath("state.db");
-}
-
-export function getLogsDir(): string {
-  return resolveOpenCandlePath("logs");
-}
-
-export function getBrowserProfileDir(): string {
-  return resolveOpenCandlePath("browser-profile");
-}

package/src/infra/rate-limiter.ts

@@ -1,76 +0,0 @@
-interface BucketConfig {
-  maxTokens: number;
-  refillRate: number; // tokens per second
-}
-
-interface Bucket {
-  tokens: number;
-  lastRefill: number;
-  config: BucketConfig;
-}
-
-export const ALPHA_VANTAGE_RATE_LIMIT = {
-  maxTokens: 5,
-  refillRate: 0.083,
-} as const;
-
-export class RateLimiter {
-  private buckets = new Map<string, Bucket>();
-
-  configure(provider: string, maxTokens: number, refillRate: number): void {
-    this.buckets.set(provider, {
-      tokens: maxTokens,
-      lastRefill: Date.now(),
-      config: { maxTokens, refillRate },
-    });
-  }
-
-  async acquire(provider: string): Promise<void> {
-    const bucket = this.buckets.get(provider);
-    if (!bucket) return; // No limit configured
-
-    while (true) {
-      this.refill(bucket);
-
-      if (bucket.tokens >= 1) {
-        bucket.tokens -= 1;
-        return;
-      }
-
-      const waitMs = ((1 - bucket.tokens) / bucket.config.refillRate) * 1000;
-      await new Promise((resolve) => setTimeout(resolve, Math.ceil(waitMs)));
-    }
-  }
-
-  private refill(bucket: Bucket): void {
-    const now = Date.now();
-    const elapsed = (now - bucket.lastRefill) / 1000;
-    bucket.tokens = Math.min(
-      bucket.config.maxTokens,
-      bucket.tokens + elapsed * bucket.config.refillRate,
-    );
-    bucket.lastRefill = now;
-  }
-}
-
-// Shared instance with default provider limits
-export const rateLimiter = new RateLimiter();
-rateLimiter.configure("yahoo", 5, 5); // 5 req/s
-rateLimiter.configure("coingecko", 10, 0.167); // 10 req/min
-rateLimiter.configure(
-  "alphavantage",
-  ALPHA_VANTAGE_RATE_LIMIT.maxTokens,
-  ALPHA_VANTAGE_RATE_LIMIT.refillRate,
-); // 5 req/min (free tier)
-rateLimiter.configure("fred", 120, 2); // 120 req/min
-rateLimiter.configure("twitter", 5, 0.167); // 5 req, ~10 req/min
-rateLimiter.configure("reddit", 5, 0.167); // 5 req, ~10 req/min
-rateLimiter.configure("reddit_comments", 10, 0.5); // 10 req, ~30 req/min
-rateLimiter.configure("ddg", 3, 0.1); // 3 req, ~6 req/min
-rateLimiter.configure("brave_search", 5, 0.083); // 5 req, ~5 req/min
-rateLimiter.configure("exa", 5, 0.1); // 5 req, ~6 req/min
-rateLimiter.configure("finnhub", 60, 1); // 60 req/min (free tier)
-// TradingView scanner is undocumented; keep usage batch-first and paced.
-rateLimiter.configure("tradingview", 5, 1); // 5 burst, 1 req/s sustained
-// SEC EDGAR fair-access guideline is 10 req/s; stay below it.
-rateLimiter.configure("sec_edgar", 5, 5); // 5 burst, 5 req/s sustained

package/src/market-state/alert-conditions.ts

@@ -1,82 +0,0 @@
-export const ALERT_CONDITION_VERSION = 1;
-
-export type AlertCondition =
-  | ReturnType<typeof priceCrossesAbove>
-  | ReturnType<typeof priceCrossesBelow>
-  | ReturnType<typeof percentMove>
-  | ReturnType<typeof priceCrossesSma>
-  | ReturnType<typeof smaCross>
-  | ReturnType<typeof rsiThreshold>
-  | ReturnType<typeof volumeSpike>;
-
-export function priceCrossesAbove(threshold: number): {
-  threshold: number;
-  field: "last_price";
-} {
-  return { threshold, field: "last_price" };
-}
-
-export function priceCrossesBelow(threshold: number): {
-  threshold: number;
-  field: "last_price";
-} {
-  return { threshold, field: "last_price" };
-}
-
-export function percentMove(
-  direction: "up" | "down",
-  percent: number,
-  window = "1d",
-): {
-  direction: "up" | "down";
-  percent: number;
-  window: string;
-} {
-  return { direction, percent, window };
-}
-
-export function priceCrossesSma(
-  period: number,
-  direction: "above" | "below",
-  priceField: "close" | "last_price" = "close",
-): {
-  period: number;
-  direction: "above" | "below";
-  price_field: "close" | "last_price";
-} {
-  return { period, direction, price_field: priceField };
-}
-
-export function smaCross(
-  fastPeriod: number,
-  slowPeriod: number,
-  direction: "above" | "below",
-): {
-  fast_period: number;
-  slow_period: number;
-  direction: "above" | "below";
-} {
-  return { fast_period: fastPeriod, slow_period: slowPeriod, direction };
-}
-
-export function rsiThreshold(
-  period: number,
-  threshold: number,
-  direction: "above" | "below",
-): {
-  period: number;
-  threshold: number;
-  direction: "above" | "below";
-} {
-  return { period, threshold, direction };
-}
-
-export function volumeSpike(
-  lookbackPeriod: number,
-  multiplier: number,
-): {
-  lookback_period: number;
-  multiplier: number;
-} {
-  return { lookback_period: lookbackPeriod, multiplier };
-}