0.0.151 • Published 6 months ago

adaptic-utils-dev v0.0.151

Weekly downloads
-
License
ISC
Repository
-
Last release
6 months ago

Adaptic Utilities

Last updated: 20 Jan 2025

A comprehensive utility library for financial data processing, time manipulation, and formatting.

NPM repo: https://www.npmjs.com/package/adaptic-utils

Installation

npm install adaptic-utils

Usage

Import the functions from the library:

import { adaptic } from 'adaptic-utils';

Environment Variables

  • POLYGON_API_KEY
  • ALPHA_VANTAGE_API_KEY
  • ALPACA_API_KEY - Required for crypto data and news
  • ALPACA_API_SECRET - Required for crypto data and news
  • GOOGLE_SHEETS_CLIENT_EMAIL - Required for Google Sheets operations
  • GOOGLE_SHEETS_PRIVATE_KEY - Required for Google Sheets operations (with newlines preserved)
  • BACKEND_HTTPS_URL= for the backend functions
  • NODE_ENV='production' for backend functions to work with a remote server

Alpaca Functions

fetchAccountDetails(accountId: string): Promise<AccountConfiguration>

Asynchronously retrieves detailed information about a specific Alpaca trading account.

Parameters:

  • accountId: string - The Alpaca account ID

Returns:

  • Promise<AccountConfiguration> - Account configuration details including:
    {
  marketOpen: boolean;
  realTime: boolean;
  minOrderSize: number;
  maxOrderSize: number;
  dtbp_check: 'both' | 'entry' | 'exit';
  trade_confirm_email: 'all' | 'none';
  suspend_trade: boolean;
  no_shorting: boolean;
  fractional_trading: boolean;
  max_margin_multiplier: '1' | '2' | '4';
  max_options_trading_level: 0 | 1 | 2;
  pdt_check: 'both' | 'entry' | 'exit';
  ptp_no_exception_entry: boolean;
}

Example:

const accountDetails = await adaptic.alpaca.fetchAccountDetails('your-account-id');

fetchPositions(accountId: string): Promise<Position[]>

Asynchronously fetches current open positions for a specific Alpaca trading account.

Parameters:

  • accountId: string - The Alpaca account ID

Returns:

  • Promise<Position[]> - Array of positions with the following type:
    {
  asset_id: string;
  symbol: string;
  exchange: string;
  asset_class: string;
  asset_marginable: boolean;
  qty: string;
  qty_available: string;
  avg_entry_price: string;
  side: 'long' | 'short';
  market_value: string;
  cost_basis: string;
  unrealized_pl: string;
  unrealized_plpc: string;
  unrealized_intraday_pl: string;
  unrealized_intraday_plpc: string;
  current_price: string;
  lastday_price: string;
  change_today: string;
}

Example:

const positions = await adaptic.alpaca.fetchPositions('your-account-id');

fetchPortfolioHistory(accountId: string, params: { period?: string, timeframe?: string, start?: string, end?: string }): Promise<PortfolioHistory>

Asynchronously retrieves historical portfolio performance data with flexible time range options.

Parameters:

  • accountId: string - The Alpaca account ID
  • params: object
    • period?: string - Optional time period ('1D', '1W', '1M', '3M', '1Y')
    • timeframe?: string - Optional data granularity
    • start?: string - Optional start date
    • end?: string - Optional end date

Returns:

  • Promise<PortfolioHistory> - Portfolio history data:
    {
  equity: number[];
  timestamp: number[];
}

Example:

const portfolioHistory = await adaptic.alpaca.fetchPortfolioHistory('your-account-id', {
  period: '1M',
  timeframe: '1D'
});

createOrder(params: CreateOrderParams): Promise<Order>

Creates a new order for trading.

Parameters:

  • params: CreateOrderParams:
    {
  symbol: string;
  qty?: string;
  notional?: string;
  side: 'buy' | 'sell';
  type: 'market' | 'limit' | 'stop' | 'stop_limit' | 'trailing_stop';
  time_in_force: 'day' | 'gtc' | 'opg' | 'cls' | 'ioc' | 'fok';
  limit_price?: string;
  stop_price?: string;
  trail_price?: string;
  trail_percent?: string;
  extended_hours?: boolean;
  client_order_id?: string;
  order_class?: 'simple' | 'oco' | 'oto' | 'bracket';
  take_profit?: {
    limit_price: string;
    stop_price?: string;
    order_class?: OrderClass;
  };
  stop_loss?: {
    stop_price: string;
    limit_price?: string;
    order_class?: OrderClass;
  };
  position_intent?: 'buy_to_open' | 'buy_to_close' | 'sell_to_open' | 'sell_to_close';
}

Returns:

  • Promise<Order> - Created order details with full order type information

Crypto Functions

fetchBars(params: CryptoBarsParams): Promise<CryptoBarsResponse>

Fetches historical bar data for crypto trading pairs.

Parameters:

  • params: CryptoBarsParams:
    {
  symbols: CryptoPair[];
  timeframe: CryptoTimeframe;  // '1Min' | '5Min' | '15Min' | '1Hour' | '1Day' | '1Week' | '1Month'
  start?: Date;
  end?: Date;
  limit?: number;
  page_token?: string;
  sort?: 'asc' | 'desc';
}

Returns:

  • Promise<CryptoBarsResponse>:
    {
  bars: {
    [symbol: string]: CryptoBar[];
  };
  next_page_token?: string;
}
    where CryptoBar is:
    {
  t: number;  // timestamp
  o: number;  // open
  h: number;  // high
  l: number;  // low
  c: number;  // close
  v: number;  // volume
}

Market Data Functions

fetchPolygonPrices(symbol: string, params: object): Promise<PolygonPriceData[]>

Fetches historical price data from Polygon.io.

Parameters:

  • symbol: string - The trading symbol
  • params: object - Query parameters for the data fetch

Returns:

  • Promise<PolygonPriceData[]>:
    {
  date: string;
  timeStamp: number;
  open: number;
  high: number;
  low: number;
  close: number;
  vol: number;
  vwap: number;
}[]

Performance Metrics

calculateBeta(returns: number[], benchmarkReturns: number[]): CalculateBetaResult

Calculates beta and related statistics for a portfolio against a benchmark.

Parameters:

  • returns: number[] - Array of portfolio returns
  • benchmarkReturns: number[] - Array of benchmark returns

Returns:

  • CalculateBetaResult:
    {
  beta: number;
  covariance: number;
  variance: number;
  averagePortfolioReturn: number;
  averageBenchmarkReturn: number;
}

calculateMaxDrawdown(portfolioValues: number[]): number

Calculates the maximum drawdown from peak for a series of portfolio values.

Parameters:

  • portfolioValues: number[] - Array of portfolio values over time

Returns:

  • number - Maximum drawdown as a decimal (e.g., 0.25 for 25% drawdown)

calculateDailyReturns(portfolioValues: number[]): number[]

Computes daily returns from a series of portfolio values.

Parameters:

  • portfolioValues: number[] - Array of portfolio values

Returns:

  • number[] - Array of daily returns as decimals

News Functions

fetchNews(params: NewsParams): Promise<NewsResponse>

Fetches financial news articles.

Parameters:

  • params: NewsParams:
    {
  start?: Date | string;
  end?: Date | string;
  symbols?: string | string[];
  limit?: number;
  sort?: 'asc' | 'desc';
  page_token?: string;
}

Returns:

  • Promise<NewsResponse>:
    {
  news: {
    id: number;
    author: string;
    content: string;
    created_at: string;
    updated_at: string;
    headline: string;
    source: string;
    summary: string;
    url: string;
    symbols: string[];
    images: {
      size: 'large' | 'small' | 'thumb';
      url: string;
    }[];
  }[];
  next_page_token?: string;
}

Time Utilities

Market Time Types

The following types are used throughout the market time utilities:

type Period = "1D" | "3D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "YTD";
type Timeframe = "1Min" | "5Min" | "15Min" | "1H" | "1D";
type IntradayReporting = 'market_hours' | 'extended_hours' | 'continuous';
type OutputFormat = 'iso' | 'unix-seconds' | 'unix-ms';

interface MarketTimeParams {
  period?: Period;
  start?: Date;
  end?: Date;
  timezone?: string;
  intraday_reporting?: IntradayReporting;
  outputFormat?: OutputFormat;
}

interface PeriodDates {
  start: string | number;
  end: string | number;
}

createMarketTimeUtil(timezone?: string, intraday_reporting?: IntradayReporting): MarketTimeUtil

Creates a utility for market time-related operations.

Parameters:

  • timezone?: string - Optional timezone (default: 'America/New_York')
  • intraday_reporting?: IntradayReporting - Optional intraday reporting mode:
    • 'market_hours' - Regular market hours (9:30 AM - 4:00 PM ET)
    • 'extended_hours' - Extended market hours (4:00 AM - 8:00 PM ET)
    • 'continuous' - All day, 24/7

Returns:

  • MarketTimeUtil - Market time utility object

toUnixTimestamp(date: Date): number

Converts a date to Unix timestamp.

Parameters:

  • date: Date - The date to convert

Returns:

  • number - Unix timestamp

getTimeAgo(date: Date): string

Returns a human-readable time difference from now.

Parameters:

  • date: Date - The date to calculate from

Returns:

  • string - Human-readable time difference (e.g., '1 minute ago')

normalizeDate(date: Date): string

Standardizes a date to a consistent format.

Parameters:

  • date: Date - The date to standardize

Returns:

  • string - Standardized date string (e.g., '2024-11-09')

getDateInNY(time: number | string | { year: number; month: number; day: number }): Date

Returns the current date in New York timezone.

Parameters:

  • time: number | string | { year: number; month: number; day: number } - The time or date to convert

Returns:

  • Date - Date in New York timezone

getStartAndEndTimestamps(params: MarketTimeParams = {}): Promise<PeriodDates>

Generates start and end timestamps for a given period.

Parameters:

  • params: MarketTimeParams - Optional parameters for the period

Returns:

  • Promise<PeriodDates> - Start and end timestamps for the period

getStartAndEndDates(params: MarketTimeParams = {}): Promise<{ start: Date; end: Date }>

Gets the start and end dates for a given period.

Parameters:

  • params: MarketTimeParams - Optional parameters for the period

Returns:

  • Promise<{ start: Date; end: Date }> - Start and end dates for the period

getLastTradingDateYYYYMMDD(): Promise<string>

Gets the last trading date in YYYY-MM-DD format.

Returns:

  • Promise<string> - Last trading date in YYYY-MM-DD format

getLastFullTradingDate(): Promise<{ date: Date; YYYYMMDD: string }>

Gets the last full trading date.

Returns:

  • Promise<{ date: Date; YYYYMMDD: string }> - Last full trading date

currentTimeET(): Date

Gets the current time in Eastern Time.

Returns:

  • Date - Current time in Eastern Time

Formatting Utilities

capitalize(string: string): string

Capitalizes the first letter of a string.

Parameters:

  • string: string - The string to capitalize

Returns:

  • string - Capitalized string

formatEnum(enumValue: any): string

Formats an enum value for display.

Parameters:

  • enumValue: any - The enum value to format

Returns:

  • string - Formatted enum value

formatCurrency(value: number): string

Formats a number as currency.

Parameters:

  • value: number - The number to format

Returns:

  • string - Formatted currency string

formatPercentage(value: number): string

Formats a number as a percentage.

Parameters:

  • value: number - The number to format

Returns:

  • string - Formatted percentage string

Misc utilities

logIfDebug(message: string, data?: unknown, type: LogType = 'info' | 'warn' | 'error' | 'debug' | 'trace'): void

Debug logging utility that respects environment debug flags.

Parameters:

  • message: string - The log message
  • data?: unknown - Optional data to log
  • type: LogType - Optional log type (default: 'info')

fetchWithRetry(url: string, options: RequestInit): Promise<Response>

Fetches data from a URL with retry logic.

Parameters:

  • url: string - The URL to fetch
  • options: RequestInit - Optional fetch options

Returns:

  • Promise<Response> - Fetched response

Crypto Functions

fetchBars(params: CryptoBarsParams): Promise<CryptoBarsResponse>

Fetches historical bar data for crypto trading pairs.

Parameters:

  • params: CryptoBarsParams:
    {
  symbols: CryptoPair[];
  timeframe: CryptoTimeframe;  // '1Min' | '5Min' | '15Min' | '1Hour' | '1Day' | '1Week' | '1Month'
  start?: Date;
  end?: Date;
  limit?: number;
  page_token?: string;
  sort?: 'asc' | 'desc';
}

Returns:

  • Promise<CryptoBarsResponse>:
    {
  bars: {
    [symbol: string]: CryptoBar[];
  };
  next_page_token?: string;
}
    where CryptoBar is:
    {
  t: number;  // timestamp
  o: number;  // open
  h: number;  // high
  l: number;  // low
  c: number;  // close
  v: number;  // volume
}

fetchNews(params: { symbol: string; start?: Date; sort?: string; includeContent?: boolean; limit?: number }, auth: AlpacaAuth): Promise<AlpacaNewsArticle[]>

Fetches cryptocurrency-related news articles with pagination support.

Parameters:

  • params: object:
    {
  symbol: string;
  start?: Date;
  sort?: string;
  includeContent?: boolean;
  limit?: number;
}
  • auth: AlpacaAuth - Alpaca API credentials

Returns:

  • Promise<AlpacaNewsArticle[]>:
    {
  title: string;
  url: string;
  time_published: string;
  authors: string[];
  summary: string;
  banner_image: string;
  source: string;
  category_within_source: string | null;
  source_domain: string;
  topics: {
    topic: string;
    relevance_score: string;
  }[];
  overall_sentiment_score: number;
  overall_sentiment_label: string;
  ticker_sentiment: {
    ticker: string;
    relevance_score: string;
    ticker_sentiment_score: string;
    ticker_sentiment_label: string;
  }[];
}[]

Technical Analysis Functions

Bollinger Bands

interface BollingerBandsParams {
  period?: number;
  standardDeviations?: number;
}

interface BollingerBandsData {
  date: string;
  middle: number;
  upper: number;
  lower: number;
  close: number;
}

EMA (Exponential Moving Average)

interface EMAParams {
  period?: number;
  period2?: number;
}

interface EMAData {
  date: string;
  ema: number;
  ema2?: number;
  close: number;
}

MACD (Moving Average Convergence Divergence)

interface MACDParams {
  shortPeriod?: number;
  longPeriod?: number;
  signalPeriod?: number;
}

interface MACDData {
  date: string;
  macd: number;
  signal: number;
  histogram: number;
  close: number;
}

Fibonacci Retracement

interface FibonacciParams {
  lookbackPeriod?: number;
  retracementLevels?: number[];
  extensionLevels?: number[];
  reverseDirection?: boolean;  // true for downtrend, false for uptrend
}

interface FibonacciLevel {
  level: number;
  price: number;
  type: 'retracement' | 'extension';
}

interface FibonacciData {
  date: string;
  levels?: FibonacciLevel[];
  swingHigh?: number;
  swingLow?: number;
  trend?: 'uptrend' | 'downtrend';
  close: number;
}

RSI (Relative Strength Index)

interface RSIParams {
  period?: number;
}

interface RSIData {
  date: string;
  rsi: number;
  close: number;
}

Stochastic Oscillator

interface StochasticParams {
  lookbackPeriod?: number;
  signalPeriod?: number;
  smoothingFactor?: number;
}

interface StochData {
  date: string;
  slowK: number;
  slowD: number;
  close: number;
}

Support and Resistance

interface SupportResistanceParams {
  windowSize?: number;
  sensitivity?: number;
  minGapBetweenLevels?: number;
  maxLevels?: number;
  lookbackPeriod?: number;
}

interface SupportResistanceLevel {
  price: number;
  strength: number;
  type: 'support' | 'resistance';
}

interface SupportResistanceData {
  date: string;
  levels: SupportResistanceLevel[];
  close: number;
}

Alpha Vantage News Types

interface AVNewsArticle {
  title: string;
  url: string;
  time_published: string;
  authors: string[];
  summary: string;
  banner_image: string;
  source: string;
  category_within_source: string | null;
  source_domain: string;
  topics: {
    topic: string;
    relevance_score: string;
  }[];
  overall_sentiment_score: number;
  overall_sentiment_label: string;
  ticker_sentiment: {
    ticker: string;
    relevance_score: string;
    ticker_sentiment_score: string;
    ticker_sentiment_label: string;
  }[];
}

interface AVNewsResponse {
  items: number;
  sentiment_score_definition: string;
  relevance_score_definition: string;
  feed: AVNewsArticle[];
}

Asset Overview Types

interface AssetOverview {
  id: string;
  symbol: string;
  [key: string]: any;
}

interface AssetOverviewResponse {
  asset: AssetOverview | null;
  error: string | null;
  success: boolean;
}

Google Sheets Functions

Types

interface GoogleSheetConfig {
  spreadsheetId: string;
  sheetName: string;
}

interface GoogleSheetCell {
  row: number;
  column: number;
}

interface GoogleSheetRange {
  startCell: GoogleSheetCell;
  endCell: GoogleSheetCell;
}

interface GoogleSheetResponse {
  success: boolean;
  error?: string;
  data?: any;
}

interface GoogleSheetAddRowResponse extends GoogleSheetResponse {
  data?: {
    rowNumber: number;
    values: any[];
  };
}

interface GoogleSheetAddSheetResponse extends GoogleSheetResponse {
  data?: {
    sheetId: number;
    title: string;
  };
}

interface GoogleSheetCellResponse extends GoogleSheetResponse {
  data?: {
    value: any;
  };
}

interface GoogleSheetWriteArrayResponse extends GoogleSheetResponse {
  data?: {
    updatedRange: string;
    updatedRows: number;
    updatedColumns: number;
  };
}

addRow(config: GoogleSheetConfig, values: any[]): Promise<GoogleSheetAddRowResponse>

Adds a new row to a Google Sheet.

Parameters:

  • config: GoogleSheetConfig - Configuration for the target spreadsheet and sheet
  • values: any[] - Array of values to add as a new row

Returns:

  • Promise<GoogleSheetAddRowResponse> - Response containing the new row number and values

addSheet(spreadsheetId: string, sheetName: string): Promise<GoogleSheetAddSheetResponse>

Creates a new sheet in an existing spreadsheet.

Parameters:

  • spreadsheetId: string - ID of the target spreadsheet
  • sheetName: string - Name for the new sheet

Returns:

  • Promise<GoogleSheetAddSheetResponse> - Response containing the new sheet ID and title

getCell(config: GoogleSheetConfig, cell: GoogleSheetCell): Promise<GoogleSheetCellResponse>

Retrieves the value of a specific cell.

Parameters:

  • config: GoogleSheetConfig - Configuration for the target spreadsheet and sheet
  • cell: GoogleSheetCell - Cell coordinates to read

Returns:

  • Promise<GoogleSheetCellResponse> - Response containing the cell value

writeArray(config: GoogleSheetConfig, range: GoogleSheetRange, values: any[][]): Promise<GoogleSheetWriteArrayResponse>

Writes a 2D array of values to a specified range.

Parameters:

  • config: GoogleSheetConfig - Configuration for the target spreadsheet and sheet
  • range: GoogleSheetRange - Target range for writing values
  • values: any[][] - 2D array of values to write

Returns:

  • Promise<GoogleSheetWriteArrayResponse> - Response containing update statistics

Polygon Functions

fetchTickerInfo(symbol: string): Promise<{ ticker: string; name: string; type: 'stock' | 'ETF'; exchange: string } | null>

Fetches details about a stock ticker to verify its existence.

Parameters:

  • symbol: string - The trading symbol

Returns:

  • Promise<{ ticker: string; name: string; type: 'stock' | 'ETF'; exchange: string } | null> - Ticker information or null if not found

fetchLastTrade(symbol: string): Promise<{ price: number; vol: number; time: Date }>

Fetches the most recent trade price, volume, and timestamp.

Parameters:

  • symbol: string - The trading symbol

Returns:

  • Promise<{ price: number; vol: number; time: Date }> - Last trade information

fetchPrices(params: { ticker: string; start: number; end?: number; multiplier: number; timespan: string; limit?: number }): Promise<PolygonPriceData[]>

Fetches historical price data with pagination support.

Parameters:

  • params: object:
    {
  ticker: string;
  start: number;
  end?: number;
  multiplier: number;
  timespan: string;
  limit?: number;
}

Returns:

  • Promise<PolygonPriceData[]>:
    {
  date: string;
  timeStamp: number;
  open: number;
  high: number;
  low: number;
  close: number;
  vol: number;
  vwap: number;
}[]

analysePolygonPriceData(priceData: PolygonPriceData[]): string

Generates a report summarizing key statistics from price data.

Parameters:

  • priceData: PolygonPriceData[] - Historical price data

Returns:

  • string - Summary report

formatPriceData(priceData: PolygonPriceData[]): string

Formats price data into a readable string with daily OHLCV values.

Parameters:

  • priceData: PolygonPriceData[] - Historical price data

Returns:

  • string - Formatted price data string

Contributing to the Repository

Contributions are welcome! Please submit a pull request or open an issue for any enhancements or bug fixes.

Author

This project is a product of Lumic.ai.

Thanks for reading this far! Why did the trader bring a ladder to the bar? Because they heard the drinks were on the house!

fsmsreactdotenvopenaip-limitdate-fnsdate-fns-tzchild_process@apollo/clientadaptic-backend@googleapis/sheetsadaptic-backend-devgoogle-auth-library
0.0.151

6 months ago