@startsimpli/api 0.5.17 → 0.5.19

package/package.json

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

package/src/constants/endpoints.ts

@@ -78,6 +78,12 @@ export const ENDPOINTS = {
   EARNINGS_CALENDAR: 'api/v1/markets/calendar',
   TRADING_SNAPSHOTS: 'api/v1/markets/trading/snapshots',
 
+  // Options — schemas aligned with brain-trading prefs (agent_bridge req b09a6bb6)
+  OPTIONS_CHAIN: 'api/v1/markets/options/chain',
+  OPTIONS_IV_HISTORY: (symbol: string) => `api/v1/markets/instruments/${symbol}/options/iv/history`,
+  OPTIONS_GREEKS: 'api/v1/markets/options/greeks',
+  VIX_TERM: 'api/v1/markets/vix_term',
+
   // Sources ops
   SOURCES_HEALTH: 'api/v1/sources/ops/health',
 } as const;

package/src/index.ts

@@ -231,4 +231,17 @@ export type {
   TradingSnapshot,
   TradingSnapshotsResponse,
   TradingSnapshotsParams,
+  OptionSide,
+  OptionContract,
+  OptionsChainParams,
+  OptionsChainResponse,
+  OptionsIvPoint,
+  OptionsIvResponse,
+  OptionsIvHistoryParams,
+  OptionsSkewPoint,
+  OptionsGreeks,
+  VixTenor,
+  VixTermState,
+  VixTermPoint,
+  VixTermResponse,
 } from './lib/markets-api';

package/src/lib/markets-api.ts

@@ -215,15 +215,126 @@ export interface PairSnapshot {
   [key: string]: unknown;
 }
 
+export type OptionSide = 'call' | 'put';
+
 export interface AlpacaPosition {
   symbol: string;
   qty: number;
   marketValue: number;
   costBasis: number;
   unrealizedPl: number;
+  // Optional options-position fields (populated server-side when symbol is OCC-format)
+  underlying?: string | null;
+  optionSide?: OptionSide | null;
+  strike?: number | null;
+  expiry?: string | null;
+  contracts?: number | null;
+  delta?: number | null;
+  gamma?: number | null;
+  theta?: number | null;
+  vega?: number | null;
+  iv?: number | null;
   [key: string]: unknown;
 }
 
+// ===== Options + VIX =====================================================
+// Schemas are TENTATIVE pending claude-mac confirmation (agent_bridge req
+// 42c763b2). All numeric fields run through coerce helpers since Django
+// serializes Decimals as strings.
+
+export interface OptionContract {
+  strike: number;
+  side: OptionSide;
+  bid: number | null;
+  ask: number | null;
+  last: number | null;
+  iv: number | null;
+  delta: number | null;
+  gamma: number | null;
+  theta: number | null;
+  vega: number | null;
+  oi: number;
+  volume: number;
+}
+
+export interface OptionsChainResponse {
+  symbol: string;
+  expiry: string;
+  spot: number;
+  contracts: OptionContract[];
+  expiries?: string[];
+  computedAt?: string | null;
+}
+
+export interface OptionsChainParams {
+  symbol: string;
+  expiry?: string;
+}
+
+// Per brain-trading req b09a6bb6 — atm/skew/put-call ratios as a single snapshot row
+export interface OptionsIvPoint {
+  snapshotDate: string;
+  atmIv: number;
+  atmCallIv: number | null;
+  atmPutIv: number | null;
+  ivSkew25d: number | null;
+  ivSkewOtmPuts: number | null;
+  putCallVolumeRatio: number | null;
+  putCallOiRatio: number | null;
+  // Populated once 20+ days of history accumulate
+  ivRank30d: number | null;
+  ivRank252d: number | null;
+}
+
+export interface OptionsIvResponse {
+  symbol: string;
+  results: OptionsIvPoint[];
+}
+
+export interface OptionsIvHistoryParams {
+  symbol: string;
+  since?: string;
+  until?: string;
+}
+
+// Skew is derived client-side from chain (per brain-trading guidance);
+// kept as a local UI type, not an endpoint.
+export interface OptionsSkewPoint {
+  strike: number;
+  iv: number;
+  side: OptionSide;
+}
+
+export interface OptionsGreeks {
+  symbol: string;
+  expiry: string;
+  strike: number;
+  side: OptionSide;
+  delta: number;
+  gamma: number;
+  theta: number;
+  vega: number;
+  iv: number;
+  computedAt: string | null;
+}
+
+export type VixTenor = '9D' | '30D' | '3M' | string;
+export type VixTermState = 'contango' | 'backwardation';
+
+export interface VixTermPoint {
+  tenor: VixTenor;
+  symbol: string;
+  value: number;
+  percentile252d: number | null;
+  delta1d: number | null;
+}
+
+export interface VixTermResponse {
+  generatedAt: string;
+  state: VixTermState;
+  points: VixTermPoint[];
+}
+
 export interface AlpacaSnapshot {
   equity: number;
   cash: number;
@@ -282,6 +393,85 @@ export interface MarketsHealth {
   sourceInstances: SourceInstanceHealth[];
 }
 
+// Django serializes Decimal/numeric fields as strings (e.g. "219.440002").
+// Coerce known numeric fields to numbers so consumers can call .toFixed safely.
+const n = (v: unknown): number => typeof v === 'number' ? v : Number(v);
+const maybeN = (v: unknown): number | null => v == null ? null : n(v);
+
+function coerceBar(b: PriceBar): PriceBar {
+  return { ...b, open: n(b.open), high: n(b.high), low: n(b.low), close: n(b.close), volume: maybeN(b.volume) };
+}
+
+function coerceReturns(r: ReturnsAnalytics): ReturnsAnalytics {
+  return { ...r, startPrice: n(r.startPrice), endPrice: n(r.endPrice), simpleReturn: n(r.simpleReturn), logReturn: n(r.logReturn) };
+}
+
+function coercePairSpread(p: PairSpreadPoint): PairSpreadPoint {
+  return { ...p, longClose: n(p.longClose), shortClose: n(p.shortClose), spread: n(p.spread), logSpread: n(p.logSpread) };
+}
+
+function coerceBreadth(b: SectorBreadthPoint): SectorBreadthPoint {
+  return { ...b, nUp: n(b.nUp), nTotal: n(b.nTotal), pctUp: n(b.pctUp), meanReturn: n(b.meanReturn), returnDispersion: n(b.returnDispersion) };
+}
+
+function coercePosition(p: AlpacaPosition): AlpacaPosition {
+  return {
+    ...p,
+    qty: n(p.qty),
+    marketValue: n(p.marketValue),
+    costBasis: n(p.costBasis),
+    unrealizedPl: n(p.unrealizedPl),
+    strike: maybeN(p.strike),
+    contracts: maybeN(p.contracts),
+    delta: maybeN(p.delta),
+    gamma: maybeN(p.gamma),
+    theta: maybeN(p.theta),
+    vega: maybeN(p.vega),
+    iv: maybeN(p.iv),
+  };
+}
+
+function coerceContract(c: OptionContract): OptionContract {
+  return {
+    ...c,
+    strike: n(c.strike),
+    bid: maybeN(c.bid),
+    ask: maybeN(c.ask),
+    last: maybeN(c.last),
+    iv: maybeN(c.iv),
+    delta: maybeN(c.delta),
+    gamma: maybeN(c.gamma),
+    theta: maybeN(c.theta),
+    vega: maybeN(c.vega),
+    oi: n(c.oi),
+    volume: n(c.volume),
+  };
+}
+
+function coerceIvPoint(p: OptionsIvPoint): OptionsIvPoint {
+  return {
+    ...p,
+    atmIv: n(p.atmIv),
+    atmCallIv: maybeN(p.atmCallIv),
+    atmPutIv: maybeN(p.atmPutIv),
+    ivSkew25d: maybeN(p.ivSkew25d),
+    ivSkewOtmPuts: maybeN(p.ivSkewOtmPuts),
+    putCallVolumeRatio: maybeN(p.putCallVolumeRatio),
+    putCallOiRatio: maybeN(p.putCallOiRatio),
+    ivRank30d: maybeN(p.ivRank30d),
+    ivRank252d: maybeN(p.ivRank252d),
+  };
+}
+
+function coerceVixPoint(p: VixTermPoint): VixTermPoint {
+  return {
+    ...p,
+    value: n(p.value),
+    percentile252d: maybeN(p.percentile252d),
+    delta1d: maybeN(p.delta1d),
+  };
+}
+
 export class MarketsApi {
   constructor(private client: ApiClient) {}
 
@@ -296,22 +486,31 @@ export class MarketsApi {
   }
 
   async getBars(symbol: string, params?: BarsParams): Promise<PriceBar[] | PaginatedResponse<PriceBar>> {
-    return this.client.fetch.get<PriceBar[] | PaginatedResponse<PriceBar>>(
+    const res = await this.client.fetch.get<PriceBar[] | PaginatedResponse<PriceBar>>(
       ENDPOINTS.INSTRUMENT_BARS(symbol),
       { params: params as Record<string, unknown> | undefined },
     );
+    if (Array.isArray(res)) return res.map(coerceBar);
+    return { ...res, results: res.results.map(coerceBar) };
   }
 
   async getLatestBar(symbol: string, interval: BarInterval = '1d'): Promise<PriceBar> {
-    return this.client.fetch.get<PriceBar>(ENDPOINTS.INSTRUMENT_LATEST(symbol), {
+    const b = await this.client.fetch.get<PriceBar>(ENDPOINTS.INSTRUMENT_LATEST(symbol), {
       params: { interval },
     });
+    return coerceBar(b);
   }
 
   async getAnalytics(symbol: string, params: AnalyticsParams): Promise<AnalyticsResponse> {
-    return this.client.fetch.get<AnalyticsResponse>(ENDPOINTS.INSTRUMENT_ANALYTICS(symbol), {
+    const res = await this.client.fetch.get<AnalyticsResponse>(ENDPOINTS.INSTRUMENT_ANALYTICS(symbol), {
       params: params as unknown as Record<string, unknown>,
     });
+    if (params.metric === 'returns') return coerceReturns(res as ReturnsAnalytics);
+    if (params.metric === 'pair_spread' && Array.isArray(res)) return (res as PairSpreadPoint[]).map(coercePairSpread);
+    if (params.metric === 'volatility' && Array.isArray(res)) {
+      return (res as VolatilityPoint[]).map((v) => ({ ...v, volatility: n(v.volatility) }));
+    }
+    return res;
   }
 
   async getNews(symbol: string, params?: NewsParams): Promise<InstrumentNewsResponse> {
@@ -325,9 +524,10 @@ export class MarketsApi {
   }
 
   async getSectorBreadth(params: SectorBreadthParams): Promise<SectorBreadthResponse> {
-    return this.client.fetch.get<SectorBreadthResponse>(ENDPOINTS.SECTOR_BREADTH, {
+    const res = await this.client.fetch.get<SectorBreadthResponse>(ENDPOINTS.SECTOR_BREADTH, {
       params: params as unknown as Record<string, unknown>,
     });
+    return { ...res, results: res.results.map(coerceBreadth) };
   }
 
   async getEarningsCalendar(params: EarningsCalendarParams): Promise<EarningsCalendarResponse> {
@@ -337,9 +537,63 @@ export class MarketsApi {
     });
   }
 
+  // ===== Options + VIX (tentative — see agent_bridge req 42c763b2) =======
+
+  async getOptionsChain(params: OptionsChainParams): Promise<OptionsChainResponse> {
+    const res = await this.client.fetch.get<OptionsChainResponse>(ENDPOINTS.OPTIONS_CHAIN, {
+      params: params as unknown as Record<string, unknown>,
+    });
+    return {
+      ...res,
+      spot: n(res.spot),
+      contracts: (res.contracts ?? []).map(coerceContract),
+    };
+  }
+
+  async getOptionsIvHistory(params: OptionsIvHistoryParams): Promise<OptionsIvResponse> {
+    const { symbol, ...rest } = params;
+    const res = await this.client.fetch.get<OptionsIvResponse>(ENDPOINTS.OPTIONS_IV_HISTORY(symbol), {
+      params: rest as Record<string, unknown>,
+    });
+    return { ...res, results: (res.results ?? []).map(coerceIvPoint) };
+  }
+
+  async getOptionsGreeks(symbol: string, expiry: string, strike: number, side: OptionSide): Promise<OptionsGreeks> {
+    const res = await this.client.fetch.get<OptionsGreeks>(ENDPOINTS.OPTIONS_GREEKS, {
+      params: { symbol, expiry, strike, side },
+    });
+    return {
+      ...res,
+      strike: n(res.strike),
+      delta: n(res.delta),
+      gamma: n(res.gamma),
+      theta: n(res.theta),
+      vega: n(res.vega),
+      iv: n(res.iv),
+    };
+  }
+
+  async getVixTerm(): Promise<VixTermResponse> {
+    const res = await this.client.fetch.get<VixTermResponse>(ENDPOINTS.VIX_TERM);
+    return { ...res, points: (res.points ?? []).map(coerceVixPoint) };
+  }
+
   async getTradingSnapshots(params?: TradingSnapshotsParams): Promise<TradingSnapshotsResponse> {
-    return this.client.fetch.get<TradingSnapshotsResponse>(ENDPOINTS.TRADING_SNAPSHOTS, {
+    const res = await this.client.fetch.get<TradingSnapshotsResponse>(ENDPOINTS.TRADING_SNAPSHOTS, {
       params: params as Record<string, unknown> | undefined,
     });
+    return {
+      ...res,
+      results: res.results.map((s) => ({
+        ...s,
+        alpaca: {
+          ...s.alpaca,
+          equity: n(s.alpaca.equity),
+          cash: n(s.alpaca.cash),
+          buyingPower: n(s.alpaca.buyingPower),
+          positions: (s.alpaca.positions ?? []).map(coercePosition),
+        },
+      })),
+    };
   }
 }