@adaptic/utils 0.0.359

package/README.md

@@ -0,0 +1,824 @@
+# 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
+
+### `fetchAccountDetails(accountId: string): Promise<AccountDetails>`
+
+Asynchronously retrieves detailed information about a specific Alpaca trading account.
+
+**Parameters:**
+- `accountId: string` - The Alpaca account ID
+
+**Returns:**
+- `Promise<AccountDetails>` - 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}`);
+```
+
+### `fetchPortfolioHistory({ params, accountId, client, alpacaAccount }: FetchPortfolioHistoryProps): Promise<PortfolioHistoryResponse>`
+
+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<NormalizedCacheObject>;         // 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<PortfolioHistoryResponse>`:
+  ```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<string, number>;
+  }
+  ```
+
+**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'
+  }
+});
+```
+
+### `adaptic.position.fetchAll(auth: AlpacaAuth): Promise<Position[]>`
+
+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<Position[]>` - 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'
+});
+```
+
+### `adaptic.position.fetch(symbolOrAssetId: string, auth: AlpacaAuth): Promise<Position>`
+
+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<Position>` - Single position details with the same type as in `fetchAll`
+
+**Example:**
+```typescript
+const position = await adaptic.position.fetch('AAPL', {
+  adapticAccountId: 'your-account-id'
+});
+```
+
+### `adaptic.position.close(symbolOrAssetId: string, auth: AlpacaAuth, params?: ClosePositionParams): Promise<Order>`
+
+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<Order>` - 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
+});
+```
+
+### `adaptic.position.closeAll(auth: AlpacaAuth, params?: CloseAllPositionsParams): Promise<Array<{ symbol: string; status: number; body?: Order }>>`
+
+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<Array<{ symbol: string; status: number; body?: Order }>>` - 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
+});
+```
+
+### `createOrder(params: CreateOrderParams): Promise<Order>`
+
+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<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`:
+  ```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<CryptoBarsResponse>`:
+  ```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
+
+### `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[]>`:
+  ```typescript
+  {
+    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`:
+  ```typescript
+  {
+    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`:
+  ```typescript
+  {
+    start?: Date | string;
+    end?: Date | string;
+    symbols?: string | string[];
+    limit?: number;
+    sort?: 'asc' | 'desc';
+    page_token?: string;
+  }
+  ```
+
+**Returns:**
+- `Promise<NewsResponse>`:
+  ```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
+
+### Market Time Types
+
+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;
+}
+```
+
+### `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
+
+### `getMarketOpenClose(options?: MarketOpenCloseOptions): MarketOpenCloseResult`
+
+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')
+});
+```
+
+### `getMarketStatus(options?: { date?: Date }): MarketStatus`
+
+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}`);
+```
+
+### `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 = {}): PeriodDates`
+
+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
+
+### `getStartAndEndDates(params: MarketTimeParams = {}): { start: Date; end: Date }`
+
+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
+
+### `getLastTradingDateYYYYMMDD(): string`
+
+Gets the last trading date in YYYY-MM-DD format.
+
+**Returns:**
+- `string` - Last trading date in YYYY-MM-DD format
+
+### `getLastFullTradingDate(currentDate?: Date): { date: Date; YYYYMMDD: string }`
+
+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
+
+### `getNextMarketDay({ referenceDate?: Date }): { date: Date; yyyymmdd: string; dateISOString: string }`
+
+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') });
+```
+
+### `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
+
+## 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.
+
+### Fetching News Articles
+
+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](https://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!