reportify-sdk 0.2.0 → 0.2.2

package/dist/index.d.mts

@@ -430,125 +430,120 @@ declare class DocsModule {
  * Quant Module
  *
  * Provides quantitative analysis tools including indicators, factors, quotes, and backtesting.
+ * Based on Mai-language syntax compatible with TongDaXin/TongHuaShun.
  */
 
-interface IndicatorParams {
-    symbols: string[];
-    indicators: string[];
-    startDate?: string;
-    endDate?: string;
-    interval?: '1d' | '1w' | '1m';
-    params?: Record<string, unknown>;
-}
-interface IndicatorDefinition {
+type StockMarket = 'cn' | 'hk' | 'us';
+interface IndicatorMeta {
     name: string;
     description: string;
-    category: string;
-    parameters: Array<{
-        name: string;
-        type: string;
-        default?: unknown;
-        description: string;
-    }>;
+    fields: string[];
 }
-interface FactorParams {
+interface IndicatorComputeParams {
     symbols: string[];
-    factors: string[];
+    formula: string;
+    market?: StockMarket;
     startDate?: string;
     endDate?: string;
-    frequency?: 'daily' | 'weekly' | 'monthly';
 }
-interface FactorDefinition {
+interface IndicatorData {
+    symbol: string;
+    date: string;
+    [key: string]: unknown;
+}
+interface FactorMeta {
     name: string;
-    category: string;
+    type: 'variable' | 'function';
+    level: 0 | 1 | 2;
     description: string;
 }
-interface QuoteParams {
-    symbols: string[];
-    fields?: string[];
-}
-interface QuoteHistoryParams {
+interface FactorComputeParams {
     symbols: string[];
+    formula: string;
+    market?: StockMarket;
     startDate?: string;
     endDate?: string;
-    interval?: '1d' | '1w' | '1m';
-    adjust?: 'forward' | 'backward' | 'none';
-    limit?: number;
-}
-interface BacktestStrategy {
-    type: string;
-    universe: string[];
-    rebalance?: 'daily' | 'weekly' | 'monthly' | 'quarterly';
-    [key: string]: unknown;
 }
-interface BacktestParams {
-    strategy: BacktestStrategy;
-    startDate: string;
-    endDate: string;
-    initialCapital?: number;
-    benchmark?: string;
-}
-interface BacktestMetrics {
-    totalReturn: number;
-    annualizedReturn: number;
-    sharpeRatio: number;
-    maxDrawdown: number;
-    winRate: number;
-    volatility: number;
-}
-interface BacktestResult {
-    backtestId: string;
-    status: 'pending' | 'running' | 'completed' | 'failed';
-    metrics?: BacktestMetrics;
-    error?: string;
+interface ScreenParams {
+    formula: string;
+    market?: StockMarket;
+    checkDate?: string;
+    symbols?: string[];
 }
-interface IndicatorData {
-    date: string;
+interface ScreenedStock {
     symbol: string;
-    [key: string]: unknown;
+    close: number;
+    factor_value?: number | boolean;
 }
-interface FactorData {
-    date: string;
+interface OHLCVParams {
     symbol: string;
-    [key: string]: unknown;
+    market?: StockMarket;
+    startDate?: string;
+    endDate?: string;
 }
-interface QuoteData {
+interface BatchOHLCVParams {
+    symbols: string[];
+    market?: StockMarket;
+    startDate?: string;
+    endDate?: string;
+}
+interface OHLCVData {
     symbol: string;
-    price: number;
-    change: number;
-    changePercent: number;
-    volume: number;
+    date: string;
+    open: number;
     high: number;
     low: number;
-    open: number;
-    previousClose: number;
-    marketCap?: number;
-    timestamp: number;
+    close: number;
+    volume: number;
+    [key: string]: unknown;
 }
-interface TradeData {
-    date: string;
+interface BacktestParams {
+    startDate: string;
+    endDate: string;
     symbol: string;
-    action: 'buy' | 'sell';
-    quantity: number;
-    price: number;
-    value: number;
+    market?: StockMarket;
+    entryFormula: string;
+    exitFormula?: string;
+    initialCash?: number;
+    commission?: number;
+    stopLoss?: number;
+    sizerPercent?: number;
+    autoClose?: boolean;
+    labels?: Record<string, string>;
 }
-interface ReturnData {
-    date: string;
-    portfolioValue: number;
-    dailyReturn: number;
-    cumulativeReturn: number;
-    benchmarkReturn?: number;
+interface BacktestResult {
+    success: boolean;
+    initial_cash: number;
+    final_cash: number;
+    total_return: number;
+    total_return_pct: number;
+    max_drawdown: number;
+    profit_factor: number;
+    win_rate: number;
+    total_trades: number;
+    trades: Array<{
+        date: string;
+        action: 'buy' | 'sell';
+        price: number;
+        quantity: number;
+        value: number;
+        pnl?: number;
+    }>;
 }
 /**
  * Quantitative analysis module
  *
  * @example
  * ```typescript
- * const indicators = await client.quant.indicators({
- *   symbols: ['US:AAPL'],
- *   indicators: ['ma', 'rsi'],
- *   params: { ma_period: 20 }
+ * // Compute RSI indicator
+ * const data = await client.quant.computeIndicators({
+ *   symbols: ['000001'],
+ *   formula: 'RSI(14)'
+ * });
+ *
+ * // Screen stocks by formula
+ * const stocks = await client.quant.screen({
+ *   formula: 'RSI(14) < 30'
  * });
  * ```
  */
@@ -556,88 +551,175 @@ declare class QuantModule {
     private client;
     constructor(client: Reportify);
     /**
-     * Get technical indicators for given symbols
+     * Get list of available technical indicators
      *
-     * @param params - Indicator parameters
-     * @returns Array of indicator data
+     * @returns Array of indicator definitions
+     *
+     * @example
+     * ```typescript
+     * const indicators = await client.quant.listIndicators();
+     * indicators.forEach(ind => {
+     *   console.log(`${ind.name}: ${ind.description}`);
+     *   console.log(`  Fields: ${ind.fields.join(', ')}`);
+     * });
+     * ```
      */
-    indicators(params: IndicatorParams): Promise<IndicatorData[]>;
+    listIndicators(): Promise<IndicatorMeta[]>;
     /**
-     * Get list of available technical indicators
+     * Compute indicator values for given symbols
+     *
+     * @param params - Indicator computation parameters
+     * @returns Array of indicator data
+     *
+     * @example
+     * ```typescript
+     * // RSI indicator
+     * const data = await client.quant.computeIndicators({
+     *   symbols: ['000001'],
+     *   formula: 'RSI(14)'
+     * });
+     *
+     * // MACD indicator
+     * const data = await client.quant.computeIndicators({
+     *   symbols: ['000001'],
+     *   formula: 'MACD()'
+     * });
+     * ```
      */
-    indicatorList(): Promise<IndicatorDefinition[]>;
+    computeIndicators(params: IndicatorComputeParams): Promise<IndicatorData[]>;
     /**
-     * Get factor data for given symbols
+     * Get list of available factors (variables and functions)
      *
-     * @param params - Factor parameters
-     * @returns Array of factor data
+     * @returns Array of factor definitions organized by level
      */
-    factors(params: FactorParams): Promise<FactorData[]>;
+    listFactors(): Promise<FactorMeta[]>;
     /**
-     * Get list of available factors
+     * Compute factor values for given symbols
+     *
+     * Uses Mai-language syntax compatible with TongDaXin/TongHuaShun.
+     *
+     * @param params - Factor computation parameters
+     * @returns Array of factor data
+     *
+     * @example
+     * ```typescript
+     * // Simple indicator
+     * const data = await client.quant.computeFactors({
+     *   symbols: ['000001'],
+     *   formula: 'RSI(14)'
+     * });
+     *
+     * // MACD DIF line
+     * const data = await client.quant.computeFactors({
+     *   symbols: ['000001'],
+     *   formula: 'MACD().dif'
+     * });
+     *
+     * // Close above 20-day MA
+     * const data = await client.quant.computeFactors({
+     *   symbols: ['000001'],
+     *   formula: 'CLOSE > MA(20)'
+     * });
+     * ```
      */
-    factorList(): Promise<FactorDefinition[]>;
+    computeFactors(params: FactorComputeParams): Promise<IndicatorData[]>;
     /**
-     * Get factor exposure for given symbols
+     * Screen stocks based on factor formula
+     *
+     * @param params - Screening parameters
+     * @returns Array of stocks that passed the filter
      *
-     * @param symbols - Stock symbols
-     * @param date - Specific date (optional)
+     * @example
+     * ```typescript
+     * // RSI oversold
+     * const stocks = await client.quant.screen({
+     *   formula: 'RSI(14) < 30'
+     * });
+     *
+     * // Golden cross
+     * const stocks = await client.quant.screen({
+     *   formula: 'CROSS(MA(5), MA(10))'
+     * });
+     *
+     * // Uptrend
+     * const stocks = await client.quant.screen({
+     *   formula: '(CLOSE > MA(20)) & (MA(20) > MA(60))'
+     * });
+     * ```
      */
-    factorExposure(symbols: string[], date?: string): Promise<FactorData[]>;
+    screen(params: ScreenParams): Promise<ScreenedStock[]>;
     /**
-     * Get real-time quotes for given symbols
+     * Get OHLCV daily data for a single symbol
+     *
+     * @param params - OHLCV parameters
+     * @returns Array of OHLCV data
      *
-     * @param params - Quote parameters
-     * @returns Array of quote data
+     * @example
+     * ```typescript
+     * const data = await client.quant.ohlcv({
+     *   symbol: '000001',
+     *   startDate: '2024-01-01'
+     * });
+     * ```
      */
-    quotes(params: QuoteParams): Promise<QuoteData[]>;
+    ohlcv(params: OHLCVParams): Promise<OHLCVData[]>;
     /**
-     * Get historical quotes data
+     * Get OHLCV data for multiple symbols
      *
-     * @param params - History parameters
-     * @returns Array of historical OHLCV data
+     * @param params - Batch OHLCV parameters
+     * @returns Array of OHLCV data sorted by date (descending), then by symbol
+     *
+     * @example
+     * ```typescript
+     * const data = await client.quant.ohlcvBatch({
+     *   symbols: ['000001', '600519'],
+     *   startDate: '2024-01-01'
+     * });
+     * ```
      */
-    quotesHistory(params: QuoteHistoryParams): Promise<IndicatorData[]>;
+    ohlcvBatch(params: BatchOHLCVParams): Promise<OHLCVData[]>;
     /**
-     * Run a backtest for a given strategy
+     * Execute strategy backtest
      *
      * @param params - Backtest parameters
-     * @returns Backtest result with job ID and metrics
+     * @returns Backtest results
      *
      * @example
      * ```typescript
+     * // Simple golden cross strategy
      * const result = await client.quant.backtest({
-     *   strategy: {
-     *     type: 'momentum',
-     *     universe: ['US:AAPL', 'US:MSFT', 'US:GOOGL'],
-     *     rebalance: 'monthly',
-     *     top_n: 2
-     *   },
-     *   startDate: '2020-01-01',
+     *   startDate: '2023-01-01',
      *   endDate: '2024-01-01',
-     *   benchmark: 'US:SPY'
+     *   symbol: '000001',
+     *   entryFormula: 'CROSS(MA(5), MA(20))',  // Buy when MA5 crosses above MA20
+     *   initialCash: 100000
      * });
-     * ```
-     */
-    backtest(params: BacktestParams): Promise<BacktestResult>;
-    /**
-     * Get backtest result by ID
      *
-     * @param backtestId - Backtest job ID
-     */
-    backtestResult(backtestId: string): Promise<BacktestResult>;
-    /**
-     * Get backtest return series
+     * console.log(`Total Return: ${(result.total_return_pct * 100).toFixed(2)}%`);
+     * console.log(`Max Drawdown: ${(result.max_drawdown * 100).toFixed(2)}%`);
+     * console.log(`Win Rate: ${(result.win_rate * 100).toFixed(2)}%`);
      *
-     * @param backtestId - Backtest job ID
-     */
-    backtestReturns(backtestId: string): Promise<ReturnData[]>;
-    /**
-     * Get backtest trade history
+     * // Strategy with entry and exit signals
+     * const result2 = await client.quant.backtest({
+     *   startDate: '2023-01-01',
+     *   endDate: '2024-01-01',
+     *   symbol: '000001',
+     *   entryFormula: 'CROSS(MA(5), MA(20))',  // Buy signal
+     *   exitFormula: 'CROSSDOWN(MA(5), MA(20))'  // Sell signal
+     * });
      *
-     * @param backtestId - Backtest job ID
+     * // With custom labels for analysis
+     * const result3 = await client.quant.backtest({
+     *   startDate: '2023-01-01',
+     *   endDate: '2024-01-01',
+     *   symbol: '000001',
+     *   entryFormula: 'RSI(14) < 30',
+     *   exitFormula: 'RSI(14) > 70',
+     *   labels: { rsi: 'RSI(14)', ma20: 'MA(20)' }
+     * });
+     * ```
      */
-    backtestTrades(backtestId: string): Promise<TradeData[]>;
+    backtest(params: BacktestParams): Promise<BacktestResult>;
 }
 
 /**
@@ -717,4 +799,4 @@ declare class Reportify {
     searchTranscripts(query: string, options?: SearchOptions): Promise<Document[]>;
 }
 
-export { APIError, AuthenticationError, type BacktestMetrics, type BacktestParams, type BacktestResult, type BacktestStrategy, type Chunk, type CompanyInfo, type CompanyOverview, DocsModule, type Document, type EarningsEvent, type FactorData, type FactorDefinition, type FactorParams, type FinancialStatement, type IPOEvent, type IPOStatus, type IndicatorData, type IndicatorDefinition, type IndicatorParams, type Interval, KBModule, type KBSearchOptions, type Market, NotFoundError, type PaginatedResponse, type Period, type PriceAdjust, type PriceData, QuantModule, type Quote, type QuoteData, type QuoteHistoryParams, type QuoteParams, RateLimitError, Reportify, type ReportifyConfig, ReportifyError, type ReturnData, type SearchOptions, type Shareholder, type StockInfo, StockModule, TimelineModule, type TimelineOptions, type TradeData };
+export { APIError, AuthenticationError, type BacktestParams, type BacktestResult, type BatchOHLCVParams, type Chunk, type CompanyInfo, type CompanyOverview, DocsModule, type Document, type EarningsEvent, type FactorComputeParams, type FactorMeta, type FinancialStatement, type IPOEvent, type IPOStatus, type IndicatorComputeParams, type IndicatorData, type IndicatorMeta, type Interval, KBModule, type KBSearchOptions, type Market, NotFoundError, type OHLCVData, type OHLCVParams, type PaginatedResponse, type Period, type PriceAdjust, type PriceData, QuantModule, type Quote, RateLimitError, Reportify, type ReportifyConfig, ReportifyError, type ScreenParams, type ScreenedStock, type SearchOptions, type Shareholder, type StockInfo, type StockMarket, StockModule, TimelineModule, type TimelineOptions };