@ckir/corelib-markets

Financial market utilities and data providers for the Corelib monorepo, featuring high-resilience wrappers for Nasdaq and real-time streaming via Yahoo Finance.

Features

• Nasdaq API Wrapper: Resilient requests with custom headers and error handling.
• Market Status & Scheduling: Intelligent pollers and sleep-calculators based on market phases.
• Market Monitor: Adaptive poller with heuristic fallback during API failures.
• CNN Fear & Greed Index: Retrieval and filtering of the popular sentiment indicator.
• Yahoo Real-Time Streaming: High-performance ticker streaming powered by Rust FFI.

Installation

pnpm add @ckir/corelib-markets
Copy

Usage Examples

1. Market Monitor (Resilient Status Poller)

Intelligent long-running task that adapts to market hours and handles failures gracefully.

import { MarketMonitor, type MarketPhase } from '@ckir/corelib-markets';

const monitor = new MarketMonitor({
  liveIntervalSec: 15,      // Frequency when market is open
  closedIntervalSec: 1800,  // Frequency when market is closed
  warnIntervalSec: 60       // Warning throttle
});

monitor.on("status-change", (phase: MarketPhase, data, heuristic) => {
  console.log(`Current phase: ${phase}`);
  console.log(`Is heuristic (using fallback data): ${!!heuristic}`);
  console.log('Full Market Data:', data);
});

monitor.on("stopped", () => {
  console.log("Monitor gracefully stopped.");
});

monitor.start();

// Later...
// monitor.stop();
Copy

2. Nasdaq Market Status & Sleep Calculation

Direct retrieval and wait-time calculation.

import { MarketStatus } from '@ckir/corelib-markets';

const result = await MarketStatus.getStatus();

if (result.status === 'success') {
  const info = result.value;
  console.log(`Nasdaq Status: ${info.mrktStatus}`);
  
  // Calculate milliseconds until next open or pre-market
  const sleepMs = MarketStatus.getSleepDuration(info);
  console.log(`Sleeping ${sleepMs}ms until next event.`);
}
Copy

3. CNN Fear & Greed Index

Retrieve sentiment data with optional historical filtering.

import { CnnFearAndGreed, CnnFearAndGreedFilter } from '@ckir/corelib-markets';

// Fetch current Fear & Greed Index
const current = await CnnFearAndGreed.getFearAndGreed();

// Fetch historical score for specific date with filter
const voldata = await CnnFearAndGreed.getFearAndGreed(
  "2026-03-15", 
  CnnFearAndGreedFilter.MarketVolatilityVix
);

if (current.status === 'success') {
  console.log(`Score: ${current.value.score} (${current.value.rating})`);
}
Copy

4. Yahoo Real-Time Streaming (FFI)

High-performance ticker updates using the Rust bridge.

import { YahooStreaming } from '@ckir/corelib-markets';

const stream = new YahooStreaming();

// Initialize with a 45s silence threshold before auto-reconnect
await stream.init({ silenceSeconds: 45 });
await stream.start();

// Subscribe to multiple symbols
stream.subscribe(["AAPL", "TSLA", "NVDA", "BTC-USD"]);

stream.on("pricing", (data) => {
  console.log(`Price Update: ${data.symbol} = ${data.price}`);
});

stream.on("silence-reconnect", () => {
  console.log("Yahoo stream silent for too long, reconnecting...");
});
Copy

5. Persistent Symbol Database (MarketSymbols)

Automated Nasdaq symbol directory with auto-refresh, environment-aware search sequencing, and cloud integration.

Features

• Auto-Refresh: Synchronizes with official Nasdaq directories if data is missing or outdated (older than today NY time).
• Environment-Aware: Automatically optimizes search sequence (DB vs API) based on whether it is running on the Edge.
• Turso Support: Supports both local SQLite and remote Turso/LibSQL databases.
• Custom Ingestors: Extensible registry for querying additional symbol data sources (e.g., Google Apps Script).

Basic Usage (Local SQLite)

import { MarketSymbols } from '@ckir/corelib-markets';

// Initialize (defaults to local SQLite file)
const symbols = new MarketSymbols();

// Get details (Sequence: DB -> Nasdaq API -> Ingestors)
const aapl = await symbols.get("AAPL");
Copy

Cloud Usage (Turso)

const symbols = new MarketSymbols({
  dbUrl: "libsql://your-db.turso.io",
  dbToken: "your-auth-token"
});
Copy

Custom Ingestors (e.g., Google Apps Script)

const ingestorUrl = "https://script.google.com/macros/s/.../exec";
const symbols = new MarketSymbols(undefined, [ingestorUrl]);

// If not in DB or Nasdaq API, it will query your script
const custom = await symbols.get("MY_PRIVATE_SYMBOL");
Copy

Manual Maintenance

// Force a full directory refresh from Nasdaq sources
await symbols.refresh();

// Graceful shutdown
await symbols.close();
Copy

6. Resilient Nasdaq API

Low-level wrapper for custom Nasdaq API interactions.

import { ApiNasdaqUnlimited } from '@ckir/corelib-markets';

// Execute single high-resilience request
const result = await ApiNasdaqUnlimited.endPoint('https://api.nasdaq.com/api/quote/AAPL/info');

if (result.status === 'success') {
  console.log('AAPL Info:', result.value);
}
Copy

7. Integration with Core (Logging & Config)

ts-markets is designed to seamlessly use the logging and configuration systems provided by @ckir/corelib.

import { logger, ConfigManager } from '@ckir/corelib';
import { MarketMonitor } from '@ckir/corelib-markets';

// The monitor automatically uses the global logger
const monitor = new MarketMonitor();

// You can configure intervals via ConfigManager (if supported by your implementation)
const config = ConfigManager.getInstance();
await config.initialize();

logger.info("Starting market services...");
monitor.start();
Copy