opencandle 0.11.1 → 0.13.0

package/src/infra/cache.ts

@@ -1,127 +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 CacheMetadata {
-  status: "none" | "cached" | "stale";
-  cachedAt: number;
-}
-
-const cacheMetadataStorage = new AsyncLocalStorage<CacheMetadata>();
-
-export async function runWithStaleMetadata<T>(fn: () => Promise<T>): Promise<{
-  value: T;
-  cache?: { status: "cached" | "stale"; cachedAt: number };
-  stale?: { cachedAt: number };
-}> {
-  const metadata: CacheMetadata = { status: "none", cachedAt: 0 };
-  const value = await cacheMetadataStorage.run(metadata, fn);
-  return {
-    value,
-    cache:
-      metadata.status === "cached" || metadata.status === "stale"
-        ? { status: metadata.status, cachedAt: metadata.cachedAt }
-        : undefined,
-    stale: metadata.status === "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;
-    const metadata = cacheMetadataStorage.getStore();
-    if (metadata && metadata.status === "none") {
-      metadata.status = "cached";
-      metadata.cachedAt = entry.cachedAt;
-    }
-    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 = cacheMetadataStorage.getStore();
-    if (metadata) {
-      metadata.status = "stale";
-      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
-  PREDICTION_MARKETS: 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
-  PREDICTION_MARKETS: 3_600_000, // 1 hour
-} as const;

package/src/infra/freshness.ts

@@ -1,165 +0,0 @@
-import {
-  classifyMarketStatusAt,
-  lastTradingDay,
-  localDateTimeParts,
-  type MarketSession,
-} from "./market-calendar.js";
-
-export interface FreshnessStamp {
-  fetchedAt: string;
-  providerDataAt?: string;
-  providerDataDate?: string;
-  cacheStatus: "live" | "cached" | "stale";
-  cachedAt?: string;
-  marketSession: MarketSession;
-  dataDelayMs?: number;
-  isStaleForSession: boolean;
-}
-
-export function buildFreshnessStamp(input: {
-  asOf?: string | number | Date;
-  cached?: boolean;
-  stale?: boolean;
-  cachedAt?: string;
-  dataDelayMs?: number;
-  now?: Date;
-  assetClass?: "equity" | "crypto";
-}): FreshnessStamp {
-  const now = input.now ?? new Date();
-  const parsedAsOf = normalizeAsOf(input.asOf);
-  const fetchedAt = now.toISOString();
-  const cacheStatus = input.stale ? "stale" : input.cached ? "cached" : "live";
-  const marketSession = input.assetClass === "crypto" ? "unknown" : classifyMarketStatusAt(now);
-  const cachedAt = input.cachedAt ? normalizeDate(input.cachedAt)?.toISOString() : undefined;
-  const providerDataAt = parsedAsOf?.date.toISOString();
-  const providerDataDate = parsedAsOf?.dateOnly;
-  const isStaleForSession =
-    input.assetClass === "crypto"
-      ? isCryptoStale(parsedAsOf?.date, cachedAt, now, cacheStatus)
-      : isEquityStale(parsedAsOf, cacheStatus, now);
-
-  return {
-    fetchedAt,
-    providerDataAt,
-    providerDataDate,
-    cacheStatus,
-    cachedAt,
-    marketSession,
-    dataDelayMs: input.dataDelayMs,
-    isStaleForSession,
-  };
-}
-
-export function formatAsOfLine(stamp: FreshnessStamp): string {
-  if (stamp.isStaleForSession && stamp.providerDataAt) {
-    const date = stamp.providerDataDate ?? formatEtDate(new Date(stamp.providerDataAt));
-    const parenthetical = staleSessionParenthetical(stamp.marketSession);
-    const cached = stamp.cachedAt
-      ? ` Cached from ${formatEtDateTime(new Date(stamp.cachedAt))} ET.`
-      : "";
-    return `Last available price as of ${date}${parenthetical}. This is not a live quote.${cached}`;
-  }
-
-  if (stamp.cacheStatus === "stale" && stamp.cachedAt) {
-    const notLive = stamp.isStaleForSession ? " This is not a live quote." : "";
-    return `Using cached data from ${formatEtDateTime(new Date(stamp.cachedAt))} ET (provider unavailable).${notLive}`;
-  }
-
-  if (stamp.providerDataAt || stamp.dataDelayMs !== undefined) {
-    const reference = stamp.providerDataAt ?? stamp.cachedAt ?? stamp.fetchedAt;
-    const asOf = stamp.providerDataDate ?? formatEtDateTime(new Date(reference));
-    if (stamp.dataDelayMs !== undefined)
-      return `As of ${asOf} ET (~${Math.round(stamp.dataDelayMs / 60_000)}m delayed).`;
-    return `As of ${asOf} ET (${marketSessionLabel(stamp.marketSession)}).`;
-  }
-
-  return `As of ${formatEtDateTime(new Date(stamp.fetchedAt))} ET (${marketSessionLabel(stamp.marketSession)}).`;
-}
-
-function normalizeAsOf(
-  asOf: string | number | Date | undefined,
-): { date: Date; dateOnly?: string } | undefined {
-  if (asOf === undefined) return undefined;
-  if (asOf instanceof Date) return Number.isNaN(asOf.getTime()) ? undefined : { date: asOf };
-  if (typeof asOf === "number") {
-    const milliseconds = asOf < 10_000_000_000 ? asOf * 1000 : asOf;
-    const date = new Date(milliseconds);
-    return Number.isNaN(date.getTime()) ? undefined : { date };
-  }
-  if (/^\d{4}-\d{2}-\d{2}$/.test(asOf)) {
-    const date = new Date(`${asOf}T00:00:00.000Z`);
-    return Number.isNaN(date.getTime()) ? undefined : { date, dateOnly: asOf };
-  }
-  const date = new Date(asOf);
-  return Number.isNaN(date.getTime()) ? undefined : { date };
-}
-
-function normalizeDate(value: string): Date | undefined {
-  const date = new Date(value);
-  return Number.isNaN(date.getTime()) ? undefined : date;
-}
-
-function isEquityStale(
-  parsedAsOf: { date: Date; dateOnly?: string } | undefined,
-  cacheStatus: FreshnessStamp["cacheStatus"],
-  now: Date,
-): boolean {
-  if (!parsedAsOf) return cacheStatus === "stale";
-  const localNow = localDateTimeParts(now, "America/New_York");
-  const providerTradingDate =
-    parsedAsOf.dateOnly ?? localDateTimeParts(parsedAsOf.date, "America/New_York").date;
-  const marketSession = classifyMarketStatusAt(now);
-  const requiredTradingDate =
-    marketSession === "open" ||
-    marketSession === "after_close" ||
-    marketSession === "closed_after_hours"
-      ? localNow.date
-      : lastTradingDay(localNow.date);
-  return providerTradingDate < requiredTradingDate;
-}
-
-function isCryptoStale(
-  providerDate: Date | undefined,
-  cachedAt: string | undefined,
-  now: Date,
-  cacheStatus: FreshnessStamp["cacheStatus"],
-): boolean {
-  const reference =
-    providerDate ?? (cacheStatus === "stale" && cachedAt ? new Date(cachedAt) : undefined);
-  if (!reference) return cacheStatus === "stale";
-  return now.getTime() - reference.getTime() > 15 * 60_000;
-}
-
-function formatEtDate(date: Date): string {
-  return localDateTimeParts(date, "America/New_York").date;
-}
-
-function formatEtDateTime(date: Date): string {
-  const parts = localDateTimeParts(date, "America/New_York");
-  return `${parts.date} ${parts.time}`;
-}
-
-function staleSessionParenthetical(marketSession: MarketSession): string {
-  if (marketSession === "closed_weekend") return " (market closed — weekend)";
-  if (marketSession === "closed_holiday") return " (market closed — holiday)";
-  return "";
-}
-
-function marketSessionLabel(marketSession: MarketSession): string {
-  switch (marketSession) {
-    case "open":
-      return "market open";
-    case "pre_market":
-      return "pre-market";
-    case "closed_weekend":
-      return "market closed — weekend";
-    case "closed_holiday":
-      return "market closed — holiday";
-    case "after_close":
-      return "after close";
-    case "closed_after_hours":
-      return "market closed";
-    case "unknown":
-      return "market session unknown";
-  }
-}

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/market-calendar.ts

@@ -1,193 +0,0 @@
-export type MarketSession =
-  | "closed_weekend"
-  | "closed_holiday"
-  | "pre_market"
-  | "open"
-  | "after_close"
-  | "closed_after_hours"
-  | "unknown";
-
-export interface LocalDateTimeParts {
-  date: string;
-  time: string;
-  weekday: string;
-  minutesSinceMidnight: number;
-}
-
-export const KNOWN_US_MARKET_HOLIDAYS: Record<string, string> = new Proxy(
-  {} as Record<string, string>,
-  {
-    get(_target, property) {
-      return typeof property === "string" ? marketHolidayName(property) : undefined;
-    },
-    has(_target, property) {
-      return typeof property === "string" && marketHolidayName(property) !== undefined;
-    },
-  },
-);
-
-export function marketHolidayName(key: string): string | undefined {
-  const date = dateFromKey(key);
-  const year = date.getUTCFullYear();
-  for (const candidateYear of [year - 1, year, year + 1]) {
-    const holiday = marketHolidaysForYear(candidateYear).find((entry) => entry.date === key);
-    if (holiday) return holiday.name;
-  }
-  return undefined;
-}
-
-export function classifyMarketStatus(
-  local: LocalDateTimeParts,
-  isWeekend: boolean,
-  isMarketHoliday: boolean,
-  temporalReferences: string[],
-): Exclude<MarketSession, "unknown"> {
-  if (isWeekend) return "closed_weekend";
-  if (isMarketHoliday) return "closed_holiday";
-  if (local.minutesSinceMidnight < 9 * 60 + 30) return "pre_market";
-  if (local.minutesSinceMidnight < 16 * 60) return "open";
-  if (temporalReferences.includes("after_close")) return "after_close";
-  return "closed_after_hours";
-}
-
-export function classifyMarketStatusAt(now: Date): MarketSession {
-  const local = localDateTimeParts(now, "America/New_York");
-  return classifyMarketStatus(
-    local,
-    local.weekday === "Sat" || local.weekday === "Sun",
-    marketHolidayName(local.date) !== undefined,
-    [],
-  );
-}
-
-export function localDateTimeParts(date: Date, timezone: string): LocalDateTimeParts {
-  const formatter = new Intl.DateTimeFormat("en-US", {
-    timeZone: timezone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-    hour: "2-digit",
-    minute: "2-digit",
-    hour12: false,
-    weekday: "short",
-  });
-  const parts = formatter.formatToParts(date).reduce<Record<string, string>>((acc, part) => {
-    acc[part.type] = part.value;
-    return acc;
-  }, {});
-  const hour = Number(parts.hour);
-  const minute = Number(parts.minute);
-  return {
-    date: `${parts.year}-${parts.month}-${parts.day}`,
-    time: `${parts.hour}:${parts.minute}`,
-    weekday: parts.weekday ?? "",
-    minutesSinceMidnight: hour * 60 + minute,
-  };
-}
-
-export function lastTradingDay(localDate: string): string {
-  let cursor = dateFromKey(localDate);
-  do {
-    cursor = addDays(cursor, -1);
-  } while (isWeekendOrKnownHoliday(dateKey(cursor)));
-  return dateKey(cursor);
-}
-
-export function isWeekendOrKnownHoliday(key: string): boolean {
-  const date = dateFromKey(key);
-  const day = date.getUTCDay();
-  return day === 0 || day === 6 || marketHolidayName(key) !== undefined;
-}
-
-function marketHolidaysForYear(year: number): Array<{ date: string; name: string }> {
-  return [
-    observedFixedHoliday(year, 1, 1, "New Year's Day"),
-    nthWeekdayHoliday(year, 1, 1, 3, "Martin Luther King Jr. Day"),
-    nthWeekdayHoliday(year, 2, 1, 3, "Washington's Birthday"),
-    { date: dateKey(addDays(easterDate(year), -2)), name: "Good Friday" },
-    lastWeekdayHoliday(year, 5, 1, "Memorial Day"),
-    observedFixedHoliday(year, 6, 19, "Juneteenth"),
-    observedFixedHoliday(year, 7, 4, "Independence Day"),
-    nthWeekdayHoliday(year, 9, 1, 1, "Labor Day"),
-    nthWeekdayHoliday(year, 11, 4, 4, "Thanksgiving Day"),
-    observedFixedHoliday(year, 12, 25, "Christmas Day"),
-  ];
-}
-
-function observedFixedHoliday(
-  year: number,
-  month: number,
-  day: number,
-  name: string,
-): {
-  date: string;
-  name: string;
-} {
-  const actual = new Date(Date.UTC(year, month - 1, day));
-  const weekday = actual.getUTCDay();
-  const observed =
-    weekday === 0 ? addDays(actual, 1) : weekday === 6 ? addDays(actual, -1) : actual;
-  return {
-    date: dateKey(observed),
-    name: observed.getTime() === actual.getTime() ? name : `${name} observed`,
-  };
-}
-
-function nthWeekdayHoliday(
-  year: number,
-  month: number,
-  weekday: number,
-  occurrence: number,
-  name: string,
-): { date: string; name: string } {
-  const first = new Date(Date.UTC(year, month - 1, 1));
-  const offset = (weekday - first.getUTCDay() + 7) % 7;
-  return { date: dateKey(addDays(first, offset + (occurrence - 1) * 7)), name };
-}
-
-function lastWeekdayHoliday(
-  year: number,
-  month: number,
-  weekday: number,
-  name: string,
-): { date: string; name: string } {
-  const last = new Date(Date.UTC(year, month, 0));
-  const offset = (last.getUTCDay() - weekday + 7) % 7;
-  return { date: dateKey(addDays(last, -offset)), name };
-}
-
-function easterDate(year: number): Date {
-  const a = year % 19;
-  const b = Math.floor(year / 100);
-  const c = year % 100;
-  const d = Math.floor(b / 4);
-  const e = b % 4;
-  const f = Math.floor((b + 8) / 25);
-  const g = Math.floor((b - f + 1) / 3);
-  const h = (19 * a + b - d - g + 15) % 30;
-  const i = Math.floor(c / 4);
-  const k = c % 4;
-  const l = (32 + 2 * e + 2 * i - h - k) % 7;
-  const m = Math.floor((a + 11 * h + 22 * l) / 451);
-  const easterMonth = Math.floor((h + l - 7 * m + 114) / 31);
-  const easterDay = ((h + l - 7 * m + 114) % 31) + 1;
-  return new Date(Date.UTC(year, easterMonth - 1, easterDay));
-}
-
-function dateFromKey(key: string): Date {
-  const [year, month, day] = key.split("-").map(Number);
-  return new Date(Date.UTC(year, month - 1, day));
-}
-
-function addDays(date: Date, days: number): Date {
-  const next = new Date(date);
-  next.setUTCDate(next.getUTCDate() + days);
-  return next;
-}
-
-function dateKey(date: Date): string {
-  const year = date.getUTCFullYear();
-  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
-  const day = String(date.getUTCDate()).padStart(2, "0");
-  return `${year}-${month}-${day}`;
-}