@startsimpli/api 0.5.14 → 0.5.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/api",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "Type-safe Django REST API client for StartSimpli apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/constants/endpoints.ts

@@ -65,4 +65,19 @@ export const ENDPOINTS = {
 
   // Companies / Feature flags
   FEATURE_FLAGS: 'api/v1/companies/feature-flags',
+
+  // Markets (instruments, prices, analytics, news, health)
+  INSTRUMENTS: 'api/v1/markets/instruments',
+  INSTRUMENT: (symbol: string) => `api/v1/markets/instruments/${symbol}`,
+  INSTRUMENT_BARS: (symbol: string) => `api/v1/markets/instruments/${symbol}/bars`,
+  INSTRUMENT_LATEST: (symbol: string) => `api/v1/markets/instruments/${symbol}/latest`,
+  INSTRUMENT_ANALYTICS: (symbol: string) => `api/v1/markets/instruments/${symbol}/analytics`,
+  INSTRUMENT_NEWS: (symbol: string) => `api/v1/markets/instruments/${symbol}/news`,
+  MARKETS_HEALTH: 'api/v1/markets/health',
+  SECTOR_BREADTH: 'api/v1/markets/sector_breadth',
+  EARNINGS_CALENDAR: 'api/v1/markets/calendar',
+  TRADING_SNAPSHOTS: 'api/v1/markets/trading/snapshots',
+
+  // Sources ops
+  SOURCES_HEALTH: 'api/v1/sources/ops/health',
 } as const;

package/src/index.ts

@@ -162,6 +162,7 @@ import { UsersApi } from './lib/users-api';
 import { EnrichmentApi } from './lib/enrichment-api';
 import { TargetListsApi } from './lib/target-lists-api';
 import { MessageTemplatesApi } from './lib/message-templates-api';
+import { MarketsApi } from './lib/markets-api';
 
 import type { ApiClientConfig } from './lib/api-client';
 
@@ -185,5 +186,48 @@ export function createStartSimpliApi(config: ApiClientConfig = {}) {
     enrichment: new EnrichmentApi(client),
     targetLists: new TargetListsApi(client),
     messageTemplates: new MessageTemplatesApi(client),
+    markets: new MarketsApi(client),
   };
 }
+
+// Markets API
+export { MarketsApi } from './lib/markets-api';
+export type {
+  BarInterval,
+  Instrument,
+  PriceBar,
+  InstrumentFilters,
+  BarsParams,
+  AnalyticsMetric,
+  AnalyticsParams,
+  AnalyticsResponse,
+  ReturnsAnalytics,
+  VolatilityPoint,
+  BetaAnalytics,
+  PairSpreadPoint,
+  NewsDirection,
+  NewsSentimentLabel,
+  NewsEventType,
+  InstrumentNewsItem,
+  InstrumentNewsResponse,
+  NewsParams,
+  InstrumentHealth,
+  InstrumentHealthInterval,
+  SourceInstanceHealth,
+  MarketsHealth,
+  SectorBreadthParams,
+  SectorBreadthPoint,
+  SectorBreadthResponse,
+  EarningsCalendarParams,
+  EarningsTimeOfDay,
+  EarningsCalendarRow,
+  EarningsCalendarResponse,
+  PairConsensus,
+  CommitteeVotes,
+  PairSnapshot,
+  AlpacaPosition,
+  AlpacaSnapshot,
+  TradingSnapshot,
+  TradingSnapshotsResponse,
+  TradingSnapshotsParams,
+} from './lib/markets-api';

package/src/lib/markets-api.ts

@@ -0,0 +1,333 @@
+/**
+ * Markets API wrapper for /api/v1/markets/*
+ *
+ * Backs the trade-simpli app: instruments, OHLCV bars, analytics
+ * (returns / volatility / beta / pair_spread), per-instrument news,
+ * and operational health rollup.
+ */
+
+import type { PaginatedResponse } from '../types';
+import { ENDPOINTS } from '../constants/endpoints';
+import type { ApiClient } from './api-client';
+
+export type BarInterval = '1d' | '1h' | '5m' | '1m';
+
+export interface Instrument {
+  symbol: string;
+  name?: string | null;
+  instrumentType?: string | null;
+  exchange?: string | null;
+  isActive?: boolean;
+  [key: string]: unknown;
+}
+
+export interface PriceBar {
+  barDate: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number | null;
+  interval?: BarInterval;
+}
+
+export interface InstrumentFilters {
+  q?: string;
+  instrumentType?: string;
+  exchange?: string;
+  isActive?: boolean;
+  page?: number;
+  pageSize?: number;
+}
+
+export interface BarsParams {
+  interval?: BarInterval;
+  since?: string;
+  limit?: number;
+}
+
+export type AnalyticsMetric = 'returns' | 'volatility' | 'beta' | 'pair_spread';
+
+export interface AnalyticsParams {
+  metric: AnalyticsMetric;
+  windowDays?: number;
+  window?: number;
+  interval?: BarInterval;
+  benchmark?: string;
+  vs?: string;
+}
+
+export interface ReturnsAnalytics {
+  symbol: string;
+  windowDays: number;
+  startPrice: number;
+  endPrice: number;
+  simpleReturn: number;
+  logReturn: number;
+  barCount: number;
+}
+
+export interface VolatilityPoint {
+  barDate: string;
+  volatility: number;
+}
+
+export interface BetaAnalytics {
+  symbol: string;
+  benchmark: string;
+  beta: number;
+}
+
+export interface PairSpreadPoint {
+  barDate: string;
+  longClose: number;
+  shortClose: number;
+  spread: number;
+  logSpread: number;
+}
+
+export type AnalyticsResponse =
+  | ReturnsAnalytics
+  | VolatilityPoint[]
+  | BetaAnalytics
+  | PairSpreadPoint[];
+
+export type NewsDirection = 'bullish' | 'bearish' | 'neutral' | 'unclear';
+export type NewsSentimentLabel = 'positive' | 'neutral' | 'negative';
+export type NewsEventType =
+  | 'ceasefire'
+  | 'escalation'
+  | 'supply_disruption'
+  | 'opec'
+  | 'earnings'
+  | 'central_bank'
+  | 'regulatory'
+  | 'general';
+
+export interface InstrumentNewsItem {
+  id: string;
+  title: string | null;
+  summary?: string | null;
+  url: string | null;
+  publisherName?: string | null;
+  publisherDomain?: string | null;
+  publishedAt?: string | null;
+  queryTag?: string | null;
+  confidence: number;
+  direction: NewsDirection | null;
+  sentiment: number | null;
+  sentimentLabel: NewsSentimentLabel | null;
+  eventType: NewsEventType;
+  marketMovingScore: number;
+  ingestedAt: string;
+}
+
+export interface InstrumentNewsResponse {
+  symbol: string;
+  count: number;
+  results: InstrumentNewsItem[];
+}
+
+export interface NewsParams {
+  limit?: number;
+  minConfidence?: number;
+  since?: string;
+}
+
+export interface SectorBreadthParams {
+  sector: string;
+  since?: string;
+  until?: string;
+}
+
+export interface SectorBreadthPoint {
+  barDate: string;
+  nUp: number;
+  nTotal: number;
+  pctUp: number;
+  meanReturn: number;
+  returnDispersion: number;
+}
+
+export interface SectorBreadthResponse {
+  sector: string;
+  interval: '1d';
+  members: string[];
+  count: number;
+  results: SectorBreadthPoint[];
+}
+
+export interface EarningsCalendarParams {
+  symbols: string[];
+  since?: string;
+  until?: string;
+}
+
+export type EarningsTimeOfDay = 'BMO' | 'AMC' | 'During' | 'Unknown';
+
+export interface EarningsCalendarRow {
+  date: string;
+  symbol: string;
+  eventType: 'earnings';
+  confirmed: boolean;
+  timeOfDay: EarningsTimeOfDay;
+  epsEstimate: number | null;
+  reportedEps: number | null;
+  surprisePct: number | null;
+}
+
+export interface EarningsCalendarResponse {
+  symbolsRequested: string[];
+  since: string | null;
+  until: string | null;
+  count: number;
+  errors: Record<string, string>;
+  results: EarningsCalendarRow[];
+}
+
+export type PairConsensus = 'BULL' | 'BEAR' | 'FLAT';
+
+export interface CommitteeVotes {
+  bull: number;
+  bear: number;
+  flat: number;
+}
+
+export interface PairSnapshot {
+  topScore?: number | null;
+  consensus?: PairConsensus | null;
+  committeeVotes?: CommitteeVotes | null;
+  topConfig?: string | null;
+  thresholds?: { long?: number | null; short?: number | null } | null;
+  [key: string]: unknown;
+}
+
+export interface AlpacaPosition {
+  symbol: string;
+  qty: number;
+  side?: 'long' | 'short';
+  marketValue?: number | null;
+  avgEntryPrice?: number | null;
+  unrealizedPl?: number | null;
+  [key: string]: unknown;
+}
+
+export interface AlpacaSnapshot {
+  equity: number;
+  cash: number;
+  buyingPower: number;
+  positions: AlpacaPosition[];
+}
+
+export interface TradingSnapshot {
+  id: string;
+  timestampUtc: string;
+  createdAt: string;
+  alpaca: AlpacaSnapshot;
+  pairs: Record<string, PairSnapshot>;
+  notes?: string | null;
+}
+
+export interface TradingSnapshotsResponse {
+  count: number;
+  results: TradingSnapshot[];
+}
+
+export interface TradingSnapshotsParams {
+  since?: string;
+  limit?: number;
+}
+
+export interface InstrumentHealthInterval {
+  interval: BarInterval;
+  barCount: number;
+  latestBarAt?: string | null;
+  ageSeconds?: number | null;
+  isStale: boolean;
+  gaps30d: number;
+}
+
+export interface InstrumentHealth {
+  symbol: string;
+  name?: string | null;
+  intervals: InstrumentHealthInterval[];
+}
+
+export interface SourceInstanceHealth {
+  sourceKey: string;
+  label?: string | null;
+  healthStatus: string;
+  consecutiveFailureCount: number;
+  runs24h: { total: number; completed: number; successRatio: number };
+  lastRunAt?: string | null;
+  lastSuccessAt?: string | null;
+  openDeadLetters: number;
+}
+
+export interface MarketsHealth {
+  generatedAt: string;
+  instruments: InstrumentHealth[];
+  sourceInstances: SourceInstanceHealth[];
+}
+
+export class MarketsApi {
+  constructor(private client: ApiClient) {}
+
+  async listInstruments(filters?: InstrumentFilters): Promise<PaginatedResponse<Instrument>> {
+    return this.client.fetch.get<PaginatedResponse<Instrument>>(ENDPOINTS.INSTRUMENTS, {
+      params: filters as Record<string, unknown> | undefined,
+    });
+  }
+
+  async getInstrument(symbol: string): Promise<Instrument> {
+    return this.client.fetch.get<Instrument>(ENDPOINTS.INSTRUMENT(symbol));
+  }
+
+  async getBars(symbol: string, params?: BarsParams): Promise<PriceBar[] | PaginatedResponse<PriceBar>> {
+    return this.client.fetch.get<PriceBar[] | PaginatedResponse<PriceBar>>(
+      ENDPOINTS.INSTRUMENT_BARS(symbol),
+      { params: params as Record<string, unknown> | undefined },
+    );
+  }
+
+  async getLatestBar(symbol: string, interval: BarInterval = '1d'): Promise<PriceBar> {
+    return this.client.fetch.get<PriceBar>(ENDPOINTS.INSTRUMENT_LATEST(symbol), {
+      params: { interval },
+    });
+  }
+
+  async getAnalytics(symbol: string, params: AnalyticsParams): Promise<AnalyticsResponse> {
+    return this.client.fetch.get<AnalyticsResponse>(ENDPOINTS.INSTRUMENT_ANALYTICS(symbol), {
+      params: params as unknown as Record<string, unknown>,
+    });
+  }
+
+  async getNews(symbol: string, params?: NewsParams): Promise<InstrumentNewsResponse> {
+    return this.client.fetch.get<InstrumentNewsResponse>(ENDPOINTS.INSTRUMENT_NEWS(symbol), {
+      params: params as Record<string, unknown> | undefined,
+    });
+  }
+
+  async getHealth(): Promise<MarketsHealth> {
+    return this.client.fetch.get<MarketsHealth>(ENDPOINTS.MARKETS_HEALTH);
+  }
+
+  async getSectorBreadth(params: SectorBreadthParams): Promise<SectorBreadthResponse> {
+    return this.client.fetch.get<SectorBreadthResponse>(ENDPOINTS.SECTOR_BREADTH, {
+      params: params as unknown as Record<string, unknown>,
+    });
+  }
+
+  async getEarningsCalendar(params: EarningsCalendarParams): Promise<EarningsCalendarResponse> {
+    const { symbols, ...rest } = params;
+    return this.client.fetch.get<EarningsCalendarResponse>(ENDPOINTS.EARNINGS_CALENDAR, {
+      params: { ...rest, symbols: symbols.join(',') } as unknown as Record<string, unknown>,
+    });
+  }
+
+  async getTradingSnapshots(params?: TradingSnapshotsParams): Promise<TradingSnapshotsResponse> {
+    return this.client.fetch.get<TradingSnapshotsResponse>(ENDPOINTS.TRADING_SNAPSHOTS, {
+      params: params as Record<string, unknown> | undefined,
+    });
+  }
+}