opencandle 0.5.0 → 0.7.0

package/src/infra/cache.ts

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
 interface CacheEntry<T> {
   value: T;
   expiresAt: number;
@@ -10,10 +12,26 @@ export interface StaleResult<T> {
   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>>();
-  private lastStaleHit = false;
-  private lastStaleCachedAt = 0;
 
   get<T>(key: string): T | undefined {
     const entry = this.store.get(key);
@@ -36,23 +54,14 @@ export class Cache {
       return undefined;
     }
 
-    this.lastStaleHit = true;
-    this.lastStaleCachedAt = entry.cachedAt;
+    const metadata = staleMetadataStorage.getStore();
+    if (metadata) {
+      metadata.stale = true;
+      metadata.cachedAt = entry.cachedAt;
+    }
     return { value: entry.value as T, stale: true, cachedAt: entry.cachedAt };
   }
 
-  /**
-   * Consume the stale flag set by the last getStale() hit.
-   * Returns { stale: true, cachedAt } if the last getStale() found data,
-   * then resets the flag. Used by wrapProvider to propagate stale metadata.
-   */
-  consumeStaleFlag(): { stale: boolean; cachedAt: number } {
-    const result = { stale: this.lastStaleHit, cachedAt: this.lastStaleCachedAt };
-    this.lastStaleHit = false;
-    this.lastStaleCachedAt = 0;
-    return result;
-  }
-
   set<T>(key: string, value: T, ttlMs: number): void {
     this.store.set(key, { value, expiresAt: Date.now() + ttlMs, cachedAt: Date.now() });
   }
@@ -79,25 +88,27 @@ export const cache = new Cache();
 
 // Default TTLs
 export const TTL = {
-  QUOTE: 60_000,         // 1 minute
-  HISTORY: 3_600_000,    // 1 hour
+  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
+  MACRO: 3_600_000, // 1 hour
+  SENTIMENT: 300_000, // 5 minutes
   OPTIONS_CHAIN: 120_000, // 2 minutes
-  CRUMB: 900_000,        // 15 minutes
-  WEB_SEARCH: 300_000,   // 5 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
-  WEB_SEARCH: 3_600_000,          // 1 hour
-  FINNHUB_NEWS: 3_600_000,        // 1 hour
+  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

@@ -2,6 +2,7 @@ export interface HttpClientOptions {
   timeoutMs?: number;
   maxRetries?: number;
   retryDelayMs?: number;
+  maxRetryAfterMs?: number;
   headers?: Record<string, string>;
 }
 
@@ -9,6 +10,7 @@ const DEFAULT_OPTIONS: Required<HttpClientOptions> = {
   timeoutMs: 10_000,
   maxRetries: 2,
   retryDelayMs: 1_000,
+  maxRetryAfterMs: 5_000,
   headers: {},
 };
 
@@ -17,52 +19,116 @@ export class HttpError extends Error {
     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>(
+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++) {
-    if (attempt > 0) {
-      await sleep(opts.retryDelayMs * 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);
+        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 (error instanceof HttpError && error.status >= 400 && error.status < 500) {
+      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,18 +1,14 @@
 export { Cache, cache, TTL } from "./cache.js";
-export { RateLimiter, rateLimiter } from "./rate-limiter.js";
-export { httpGet, HttpError, type HttpClientOptions } from "./http-client.js";
-export { StealthBrowser } from "./browser.js";
+export { type HttpClientOptions, HttpError, httpGet } from "./http-client.js";
 export {
-  getOpenCandleHomeDir,
   ensureOpenCandleHomeDir,
-  resolveOpenCandlePath,
   ensureParentDir,
-  getWatchlistPath,
-  getPortfolioPath,
-  getPredictionsPath,
+  getBrowserProfileDir,
   getConfigPath,
+  getLogsDir,
   getOnboardingPath,
+  getOpenCandleHomeDir,
   getStateDbPath,
-  getLogsDir,
-  getBrowserProfileDir,
+  resolveOpenCandlePath,
 } from "./opencandle-paths.js";
+export { RateLimiter, rateLimiter } from "./rate-limiter.js";

package/src/infra/native-dependencies.ts

@@ -1,4 +1,7 @@
-export function getNativeDependencyErrorMessage(error: unknown, dependencyName: string): string | null {
+export function getNativeDependencyErrorMessage(
+  error: unknown,
+  dependencyName: string,
+): string | null {
   const message = error instanceof Error ? error.message : String(error);
   if (
     !message.includes("NODE_MODULE_VERSION") &&
@@ -7,6 +10,8 @@ export function getNativeDependencyErrorMessage(error: unknown, dependencyName:
     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\`.`;
+  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\`.`
+  );
 }

package/src/infra/node-version.ts

@@ -10,7 +10,9 @@ function isSupportedNodeVersion(version: string): boolean {
   return major >= 24 && major < 27;
 }
 
-export function getUnsupportedNodeVersionMessage(version: string = process.versions.node): string | null {
+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\`.`;

package/src/infra/opencandle-paths.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
@@ -6,7 +6,7 @@ const OPENCANDLE_HOME_ENV = "OPENCANDLE_HOME";
 
 function ensureDir(path: string): void {
   if (!existsSync(path)) {
-    mkdirSync(path, { recursive: true });
+    mkdirSync(path, { recursive: true, mode: 0o700 });
   }
 }
 
@@ -18,6 +18,7 @@ export function getOpenCandleHomeDir(): string {
 export function ensureOpenCandleHomeDir(): string {
   const home = getOpenCandleHomeDir();
   ensureDir(home);
+  if (process.platform !== "win32") chmodSync(home, 0o700);
   return home;
 }
 
@@ -31,18 +32,6 @@ export function ensureParentDir(path: string): string {
   return parent;
 }
 
-export function getWatchlistPath(): string {
-  return resolveOpenCandlePath("watchlist.json");
-}
-
-export function getPortfolioPath(): string {
-  return resolveOpenCandlePath("portfolio.json");
-}
-
-export function getPredictionsPath(): string {
-  return resolveOpenCandlePath("predictions.json");
-}
-
 export function getConfigPath(): string {
   return resolveOpenCandlePath("config.json");
 }

package/src/infra/rate-limiter.ts

@@ -29,18 +29,17 @@ export class RateLimiter {
     const bucket = this.buckets.get(provider);
     if (!bucket) return; // No limit configured
 
-    this.refill(bucket);
+    while (true) {
+      this.refill(bucket);
 
-    if (bucket.tokens >= 1) {
-      bucket.tokens -= 1;
-      return;
-    }
+      if (bucket.tokens >= 1) {
+        bucket.tokens -= 1;
+        return;
+      }
 
-    // Wait until a token is available
-    const waitMs = ((1 - bucket.tokens) / bucket.config.refillRate) * 1000;
-    await new Promise((resolve) => setTimeout(resolve, Math.ceil(waitMs)));
-    this.refill(bucket);
-    bucket.tokens -= 1;
+      const waitMs = ((1 - bucket.tokens) / bucket.config.refillRate) * 1000;
+      await new Promise((resolve) => setTimeout(resolve, Math.ceil(waitMs)));
+    }
   }
 
   private refill(bucket: Bucket): void {
@@ -56,18 +55,22 @@ export class RateLimiter {
 
 // 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("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("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)
+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

@@ -0,0 +1,82 @@
+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 };
+}