Adaptic Utilities

Last updated: 20 Feb 2025

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

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

Installation

``bash
npm install adaptic-utils
`

Usage

Import the functions from the library:

`typescript
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

$3

Asynchronously retrieves detailed information about a specific Alpaca trading account.

Parameters:
- accountId: string - The Alpaca account ID

Returns:
- Promise - Comprehensive account details including:
`typescript
{
id: string;
account_number: string;
status: 'ONBOARDING' | 'SUBMISSION_FAILED' | 'SUBMITTED' | 'ACCOUNT_UPDATED' | 'APPROVAL_PENDING' | 'ACTIVE' | 'REJECTED';
currency: string;
cash: string;
portfolio_value: string; // deprecated, equivalent to equity
equity: string;
buying_power: string;
initial_margin: string;
maintenance_margin: string;
daytrade_count: number;
daytrading_buying_power: string;
options_buying_power: string;
options_approved_level: 0 | 1 | 2 | 3;
// ... and more fields available
}
`

Example:
`typescript
const accountDetails = await adaptic.alpaca.fetchAccountDetails('your-account-id');
console.log(Account equity: ${accountDetails.equity});
`

$3

Asynchronously retrieves historical portfolio data including equity and profit/loss information from either the Adaptic backend or directly from an Alpaca account.

Parameters:
- FetchPortfolioHistoryProps:
`typescript
{
params: PortfolioHistoryParams; // Portfolio history query parameters
accountId?: string; // The Alpaca account ID (required if alpacaAccount not provided)
client?: ApolloClientType; // Optional Apollo client for backend queries
alpacaAccount?: types.AlpacaAccount;// Optional Alpaca account object (if provided, accountId not required)
}
`
- PortfolioHistoryParams:
`typescript
{
period?: string; // e.g., '1D', '1W', '1M', '1A', 'YTD' (YTD will be converted to '1A')
timeframe?: '1Min' | '5Min' | '15Min' | '1H' | '1D';
intraday_reporting?: 'market_hours' | 'extended_hours' | 'continuous';
start?: string; // RFC3339 format (if specified with period, period will be ignored)
end?: string; // RFC3339 format
pnl_reset?: 'per_day' | 'no_reset';
}
`

Returns:
- Promise:
`typescript
{
timestamp: number[]; // UNIX epoch format
equity: number[];
profit_loss: number[];
profit_loss_pct: number[];
base_value: number;
base_value_asof?: string;
timeframe: string;
cashflow?: Record;
}
`

Example:
`typescript
// Using accountId
const history = await adaptic.alpaca.fetchPortfolioHistory({
accountId: 'your-account-id',
params: {
period: '1M',
timeframe: '1D'
}
});

// Using direct Alpaca account object
const history = await adaptic.alpaca.fetchPortfolioHistory({
alpacaAccount: yourAlpacaAccount,
params: {
start: '2025-01-01T00:00:00Z',
end: '2025-01-31T00:00:00Z',
timeframe: '1D'
}
});
`

$3

Asynchronously fetches all current open positions for an Alpaca trading account.

Parameters:
- auth: AlpacaAuth - Authentication details:
`typescript
{
adapticAccountId?: string; // Either this
alpacaApiKey?: string; // Or these two
alpacaApiSecret?: string;
}
`

Returns:
- Promise - Array of positions with the following type:
`typescript
{
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:
`typescript
// Using adapticAccountId
const positions = await adaptic.position.fetchAll({
adapticAccountId: 'your-account-id'
});

// Using direct API keys
const positions = await adaptic.position.fetchAll({
alpacaApiKey: 'your-api-key',
alpacaApiSecret: 'your-api-secret'
});
`

$3

Asynchronously fetches a specific position for an Alpaca trading account.

Parameters:
- symbolOrAssetId: string - The symbol or asset ID to fetch the position for
- auth: AlpacaAuth - Authentication details (same as above)

Returns:
- Promise - Single position details with the same type as in fetchAll

Example:
`typescript
const position = await adaptic.position.fetch('AAPL', {
adapticAccountId: 'your-account-id'
});
`

$3

Closes a specific position in an Alpaca trading account.

Parameters:
- symbolOrAssetId: string - The symbol or asset ID of the position to close
- auth: AlpacaAuth - Authentication details (same as above)
- params?: ClosePositionParams - Optional closing parameters:
`typescript
{
qty?: number; // Quantity of shares to close (up to 9 decimal places)
percentage?: number; // Percentage of position to close (0-100, up to 9 decimal places)
}
`

Returns:
- Promise - The order created to close the position

Example:
`typescript
// Close entire position
const order = await adaptic.position.close('AAPL', {
adapticAccountId: 'your-account-id'
});

// Close 50% of position
const order = await adaptic.position.close('AAPL', {
adapticAccountId: 'your-account-id'
}, {
percentage: 50
});
`

$3

Closes all positions in an Alpaca trading account.

Parameters:
- auth: AlpacaAuth - Authentication details (same as above)
- params?: CloseAllPositionsParams - Optional parameters:
`typescript
{
cancelOrders?: boolean; // If true, cancels all open orders before closing positions
}
`

Returns:
- Promise> - Status of each position closure attempt:
- symbol: string - The symbol of the position
- status: number - HTTP status code for the attempt
- body?: Order - The order created to close the position (if successful)

Example:
`typescript
// Close all positions
const results = await adaptic.position.closeAll({
adapticAccountId: 'your-account-id'
});

// Close all positions and cancel pending orders
const results = await adaptic.position.closeAll({
adapticAccountId: 'your-account-id'
}, {
cancelOrders: true
});
`

$3

Creates a new order for trading.

Parameters:
- params: CreateOrderParams:
`typescript
{
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 - Created order details with full order type information

Crypto Functions

$3

Fetches historical bar data for crypto trading pairs.

Parameters:
- params: CryptoBarsParams:
`typescript
{
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:
`typescript
{
bars: {
[symbol: string]: CryptoBar[];
};
next_page_token?: string;
}
`
where CryptoBar is:
`typescript
{
t: number; // timestamp
o: number; // open
h: number; // high
l: number; // low
c: number; // close
v: number; // volume
}
`

Market Data Functions

$3

Fetches historical price data from Polygon.io.

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

Returns:
- Promise:
`typescript
{
date: string;
timeStamp: number;
open: number;
high: number;
low: number;
close: number;
vol: number;
vwap: number;
}[]
`

Performance Metrics

$3

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:
`typescript
{
beta: number;
covariance: number;
variance: number;
averagePortfolioReturn: number;
averageBenchmarkReturn: number;
}
`

$3

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)

$3

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

$3

Fetches financial news articles.

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

Returns:
- Promise:
`typescript
{
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

$3

The following types are used throughout the market time utilities:

`typescript
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;
}

interface MarketOpenCloseOptions {
date?: Date;
}

interface MarketOpenCloseResult {
marketOpen: boolean;
open: Date | null;
close: Date | null;
openExt: Date | null;
closeExt: Date | null;
}
`

$3

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

$3

Gets market open/close times for both regular and extended hours for a given date.

Parameters:
- options?: MarketOpenCloseOptions - Optional parameters:
- date?: Date - The date to check (default: current date)

Returns:
- MarketOpenCloseResult:
`typescript
{
marketOpen: boolean; // Whether the market is open on this date
open: Date | null; // Regular market hours open time
close: Date | null; // Regular market hours close time
openExt: Date | null; // Extended hours open time
closeExt: Date | null; // Extended hours close time
}
`

Example:
`typescript
const { marketOpen, open, close, openExt, closeExt } = adaptic.time.getMarketOpenClose({
date: new Date('2024-12-24')
});
`

$3

Gets the current market status and detailed information about market periods.

Parameters:
- options?: object - Optional parameters:
- date?: Date - The date to check (default: current date)

Returns:
- MarketStatus:
`typescript
{
time: Date; // Current time
timeString: string; // Formatted time string
status: "closed" | "extended hours" | "open"; // Current market status
nextStatus: "closed" | "extended hours" | "open"; // Next market status
marketPeriod: "preMarket" | "earlyMarket" | "regularMarket" | "afterMarket" | "closed"; // Detailed market period
nextStatusTime: Date; // Time when next status begins
nextStatusTimeDifference: number; // Milliseconds until next status
nextStatusTimeString: string; // Formatted next status time
}
`

The marketPeriod field indicates the specific trading period:
- preMarket: 4:00 AM - 9:30 AM ET
- earlyMarket: 9:30 AM - 10:00 AM ET
- regularMarket: 10:00 AM - Market Close (typically 4:00 PM ET)
- afterMarket: Market Close - 8:00 PM ET
- closed: Outside of all trading hours

Example:
`typescript
const status = adaptic.time.getMarketStatus();
console.log(Current market period: ${status.marketPeriod});
`

$3

Converts a date to Unix timestamp.

Parameters:
- date: Date - The date to convert

Returns:
- number - Unix timestamp

$3

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')

$3

Standardizes a date to a consistent format.

Parameters:
- date: Date - The date to standardize

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

$3

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

$3

Generates start and end timestamps for a given period.

Parameters:
- params: MarketTimeParams - Optional parameters for the period

Returns:
- PeriodDates - Start and end timestamps for the period

$3

Gets the start and end dates for a given period.

Parameters:
- params: MarketTimeParams - Optional parameters for the period

Returns:
- { start: Date; end: Date } - Start and end dates for the period

$3

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

Returns:
- string - Last trading date in YYYY-MM-DD format

$3

Gets the last full trading date, considering market hours and holidays.

Parameters:
- currentDate?: Date - Optional reference date (defaults to current date)

Returns:
- Object containing:
- date: Date - The last full trading date
- YYYYMMDD: string - The date formatted as YYYY-MM-DD

$3

Gets the next market day from a reference date.

Parameters:
- referenceDate?: Date - Optional reference date (defaults to current date)

Returns:
- Object containing:
- date: Date - The next market day (start of day in NY time)
- yyyymmdd: string - The date formatted as YYYY-MM-DD
- dateISOString: string - Full ISO date string

Example:
`typescript
const nextMarketDay = adaptic.time.getNextMarketDay();
console.log(Next market day: ${nextMarketDay.yyyymmdd});

// With reference date
const nextMarketDay = adaptic.time.getNextMarketDay({ referenceDate: new Date('2025-01-01') });
`

$3

Gets the current time in Eastern Time.

Returns:
- Date - Current time in Eastern Time

Formatting Utilities

$3

Capitalizes the first letter of a string.

Parameters:
- string: string - The string to capitalize

Returns:
- string - Capitalized string

$3

Formats an enum value for display.

Parameters:
- enumValue: any - The enum value to format

Returns:
- string - Formatted enum value

$3

Formats a number as currency.

Parameters:
- value: number - The number to format

Returns:
- string - Formatted currency string

$3

Formats a number as a percentage.

Parameters:
- value: number - The number to format

Returns:
- string - Formatted percentage string

Misc utilities

$3

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')

$3

Fetches data from a URL with retry logic.

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

Returns:
- Promise - Fetched response

Alpaca API Utilities

This module provides several utility functions to interact with the Alpaca API, including fetching account details, placing orders, and retrieving market news.

$3

The fetchNews function retrieves news articles for specified symbols from the Alpaca API. It supports pagination and accepts various optional parameters to customize the query.

#### Usage

`typescript
import { fetchNews } from './alpaca';

// Example: Fetch news for a single symbol or multiple symbols (comma-separated)
const symbols = "AAPL,MSFT,GOOG"; // For multiple symbols, use a comma-separated string

(async () => {
try {
// Option 1: Pass Alpaca API credentials via the auth parameter
const newsData = await fetchNews(symbols, {
auth: {
alpacaApiKey: "YOUR_API_KEY",
alpacaApiSecret: "YOUR_API_SECRET",
},
start: new Date(Date.now() - 24 60 60 * 1000), // Default: last 24 hours
end: new Date(),
limit: 10,
sort: 'desc',
});
console.log(newsData.news);

// Option 2: Rely on environment variables ALPACA_API_KEY and ALPACA_API_SECRET
const newsDataEnv = await fetchNews(symbols, {
start: new Date(Date.now() - 24 60 60 * 1000),
end: new Date(),
limit: 10,
sort: 'desc',
});
console.log(newsDataEnv.news);

// Pagination
// fetchNews automatically fetches all pages if a next_page_token is provided by the API.
// The final returned result contains all aggregated news articles along with a nextPageToken (if any remain).

} catch (error) {
console.error(Error fetching news: ${error});
}
})();
`

#### Parameter Details

- symbols: A required string listing the symbols to fetch news for. For multiple symbols, separate them with commas (e.g., "AAPL,MSFT,GOOG").
- params.auth: (Optional) An object of type AlpacaAuth containing either:
- alpacaApiKey and alpacaApiSecret for direct authentication, or
- adapticAccountId to look up credentials from your backend via Adaptic.

If the auth parameter is not provided, the function will fallback to using the environment variables ALPACA_API_KEY and ALPACA_API_SECRET.

- params.start and params.end: Specify the date range (as a Date object or string) for the news articles. Defaults to the last 24 hours if not provided.
- params.limit: The maximum number of articles to return per page (default is 10).
- params.sort: The sort order for articles. Use 'asc' for ascending order or 'desc' for descending order (default is 'desc').
- params.page_token: A token for pagination. This is automatically handled by fetchNews if more results are available.

The function consolidates all pages of results and returns an object with a news array (of type SimpleNews[]) and an optional nextPageToken`.

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!