@startsimpli/api 0.5.19 → 0.5.20

package/src/index.ts

@@ -163,6 +163,7 @@ 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 { VaultApi } from './lib/vault-api';
 
 import type { ApiClientConfig } from './lib/api-client';
 
@@ -187,9 +188,25 @@ export function createStartSimpliApi(config: ApiClientConfig = {}) {
     targetLists: new TargetListsApi(client),
     messageTemplates: new MessageTemplatesApi(client),
     markets: new MarketsApi(client),
+    vault: new VaultApi(client),
   };
 }
 
+// Vault API
+export { VaultApi } from './lib/vault-api';
+export type {
+  VaultEnvironment,
+  VaultEnvironmentInput,
+  VaultSecret,
+  VaultSecretInput,
+  VaultSecretReveal,
+  VaultAccessKey,
+  VaultAccessKeyCreated,
+  VaultAccessKeyInput,
+  VaultAuditEntry,
+  VaultListParams,
+} from './lib/vault-api';
+
 // Markets API
 export { MarketsApi } from './lib/markets-api';
 export type {
@@ -239,9 +256,29 @@ export type {
   OptionsIvResponse,
   OptionsIvHistoryParams,
   OptionsSkewPoint,
+  OptionsChainRaw,
   OptionsGreeks,
+  OptionsUnusualActivityPoint,
+  OptionsUnusualActivityParams,
+  OptionsUnusualActivityResponse,
+  AtmIvHistoryPoint,
+  AtmIvHistoryParams,
+  AtmIvHistoryResponse,
+  MacroCategory,
+  MacroCalendarRow,
+  MacroCalendarParams,
+  MacroCalendarResponse,
   VixTenor,
   VixTermState,
   VixTermPoint,
   VixTermResponse,
+  BarsBulkParams,
+  BarsBulkResponse,
+  SocialPlatform,
+  SocialDirection,
+  SocialPost,
+  SocialPostMatchedEntity,
+  SocialPostResolvedContact,
+  SocialPostsParams,
+  SocialPostsResponse,
 } from './lib/markets-api';

package/src/lib/error-handler.ts

@@ -9,23 +9,34 @@ export class ApiException extends Error {
   public statusText?: string;
   public errors?: Record<string, string[]>;
   public detail?: string;
-
-  constructor(message: string, options?: Partial<DRFApiError>) {
+  /** Machine-readable code from the standardized error response (e.g.
+   * 'limit_reached', 'no_company'). Set by parseErrorResponse when the
+   * backend emits a structured error shape via the core exception handler. */
+  public code?: string;
+  /** Extra context the backend stapled onto the standardized response —
+   * e.g. limit_reached carries { feature_key, limit, current }. */
+  public details?: Record<string, unknown>;
+
+  constructor(message: string, options?: Partial<DRFApiError> & { code?: string; details?: Record<string, unknown> }) {
     super(message);
     this.name = 'ApiException';
     this.status = options?.status;
     this.statusText = options?.statusText;
     this.errors = options?.errors;
     this.detail = options?.detail;
+    this.code = options?.code;
+    this.details = options?.details;
   }
 
-  toJSON(): DRFApiError {
+  toJSON(): DRFApiError & { code?: string; details?: Record<string, unknown> } {
     return {
       message: this.message,
       detail: this.detail,
       status: this.status,
       statusText: this.statusText,
       errors: this.errors,
+      code: this.code,
+      details: this.details,
     };
   }
 }
@@ -41,7 +52,31 @@ export async function parseErrorResponse(response: Response): Promise<DRFApiErro
     try {
       const data = await response.json();
 
-      // Django REST Framework error format
+      // 1) Standardized response shape from apps.core.exceptions:
+      //    { error, code, statusCode, fieldErrors?, ...details } — the
+      //    'error' field carries the human message; 'code' is the machine
+      //    code (e.g. 'limit_reached'); any extra keys are structured
+      //    context the view stapled on (feature_key, limit, current, …).
+      //    Snake_case keys keep through camelCase transform too (already
+      //    converted by snakeToCamel before we get here when the client
+      //    applies it; both shapes handled here for safety).
+      if (typeof data === 'object' && data !== null && typeof (data.error ?? data.message) === 'string' && data.code) {
+        const reservedKeys = new Set(['error', 'code', 'statusCode', 'status_code', 'fieldErrors', 'field_errors', 'timestamp', 'requestId', 'request_id', 'detail']);
+        const extras: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+          if (!reservedKeys.has(k)) extras[k] = v;
+        }
+        return {
+          message: (data.error as string) ?? (data.message as string),
+          detail: (data.detail as string | undefined) ?? (data.error as string),
+          code: data.code as string,
+          details: Object.keys(extras).length > 0 ? extras : undefined,
+          status: response.status,
+          statusText: response.statusText,
+        };
+      }
+
+      // 2) Plain Django REST Framework error: { detail: '...' }
       if (data.detail) {
         return {
           detail: data.detail,
@@ -51,7 +86,7 @@ export async function parseErrorResponse(response: Response): Promise<DRFApiErro
         };
       }
 
-      // Validation errors format
+      // 3) Field-level validation errors: { email: ['...'], password: ['...'] }
       if (typeof data === 'object') {
         return {
           errors: data,

package/src/lib/errors.ts

@@ -70,8 +70,13 @@ export class AppError extends Error {
     this.details = details;
     this.isOperational = isOperational;
 
-    // Maintains proper stack trace for where our error was thrown
-    Error.captureStackTrace(this, this.constructor);
+    // Maintains proper stack trace where supported (V8/Hermes). Guarded and
+    // typed locally so the package stays portable to engines/tsconfigs without
+    // the Node-only Error.captureStackTrace global (e.g. React Native).
+    const captureStackTrace = (
+      Error as { captureStackTrace?: (target: object, ctor?: unknown) => void }
+    ).captureStackTrace;
+    captureStackTrace?.(this, this.constructor);
   }
 
   /**

package/src/lib/markets-api.ts

@@ -257,6 +257,18 @@ export interface OptionContract {
   volume: number;
 }
 
+// Server returns separate calls[]/puts[] (confirmed stable, mac req 22ac4889).
+// Client flattens into a single contracts[] with side tag.
+export interface OptionsChainRaw {
+  symbol: string;
+  expiry: string;
+  spot: number | string;
+  calls?: Omit<OptionContract, 'side'>[];
+  puts?: Omit<OptionContract, 'side'>[];
+  expiries?: string[];
+  computedAt?: string | null;
+}
+
 export interface OptionsChainResponse {
   symbol: string;
   expiry: string;
@@ -271,7 +283,8 @@ export interface OptionsChainParams {
   expiry?: string;
 }
 
-// Per brain-trading req b09a6bb6 — atm/skew/put-call ratios as a single snapshot row
+// Per brain-trading req b09a6bb6 — atm/skew/put-call ratios as a single snapshot row.
+// realized_vol_30d + iv_rv_spread_30d added in mac req 22ac4889.
 export interface OptionsIvPoint {
   snapshotDate: string;
   atmIv: number;
@@ -284,6 +297,11 @@ export interface OptionsIvPoint {
   // Populated once 20+ days of history accumulate
   ivRank30d: number | null;
   ivRank252d: number | null;
+  atmIvPercentile252d: number | null;
+  // Annualized 30d stdev of close-to-close log returns (decimal, e.g. 0.42)
+  realizedVol30d: number | null;
+  // atm_iv - realized_vol_30d. >0 ⇒ options priced rich vs realized.
+  ivRvSpread30d: number | null;
 }
 
 export interface OptionsIvResponse {
@@ -298,13 +316,68 @@ export interface OptionsIvHistoryParams {
 }
 
 // Skew is derived client-side from chain (per brain-trading guidance);
-// kept as a local UI type, not an endpoint.
+// kept as a local UI type for the chart.
 export interface OptionsSkewPoint {
   strike: number;
   iv: number;
   side: OptionSide;
 }
 
+export interface BarsBulkParams {
+  symbols: string[];
+  interval?: BarInterval;
+  since?: string;
+  until?: string;
+}
+
+export interface BarsBulkResponse {
+  interval: BarInterval;
+  count: number;
+  results: Record<string, PriceBar[]>;
+}
+
+export type SocialPlatform = 'truth_social' | string;
+export type SocialDirection = 'bullish' | 'bearish' | 'neutral' | 'unclear';
+
+export interface SocialPostMatchedEntity {
+  symbol: string;
+  name?: string | null;
+}
+
+export interface SocialPostResolvedContact {
+  id: string;
+  name: string;
+}
+
+export interface SocialPost {
+  id: string;
+  platform: SocialPlatform;
+  postedAt: string;
+  url?: string | null;
+  text?: string | null;
+  resolvedContact: SocialPostResolvedContact | null;
+  matchedEntities: SocialPostMatchedEntity[];
+  sentiment: number | null;
+  sentimentLabel: NewsSentimentLabel | null;
+  eventType: string | null;
+  marketMovingScore: number | null;
+  directionForSymbol: SocialDirection | null;
+}
+
+export interface SocialPostsParams {
+  symbol?: string;
+  platform?: SocialPlatform;
+  since?: string;
+  until?: string;
+  direction?: SocialDirection;
+  limit?: number;
+}
+
+export interface SocialPostsResponse {
+  count: number;
+  results: SocialPost[];
+}
+
 export interface OptionsGreeks {
   symbol: string;
   expiry: string;
@@ -318,8 +391,85 @@ export interface OptionsGreeks {
   computedAt: string | null;
 }
 
+// ATM IV history derived from Tradier OptionContractBar via BS inversion (mac req e5b8c299).
+// Deeper history than /options/iv/history/ for symbols where contract listings predate
+// MarketOptionsSnapshot accumulation (UCO has 112 rows back to Sep 2025).
+export interface AtmIvHistoryPoint {
+  date: string;
+  spot: number;
+  atmStrike: number;
+  atmCallIv: number | null;
+  atmPutIv: number | null;
+  atmIv: number | null;
+  ivRank30d: number | null;
+  ivRank252d: number | null;
+}
+
+export interface AtmIvHistoryParams {
+  symbol: string;
+  since?: string;
+  until?: string;
+  // Drop rows where both call AND put closest-strike fall outside |strike/spot - 1| > moneynessMax.
+  // Omit = full series. Recommended 0.10 to filter early UCO Sep-2025 garbage; tighter (0.05) risks
+  // dropping thin-coverage days entirely. (mac req 47ac5ec6)
+  moneynessMax?: number;
+}
+
+export interface AtmIvHistoryResponse {
+  symbol: string;
+  count: number;
+  results: AtmIvHistoryPoint[];
+}
+
+// Macro event calendar (mac req e5b8c299). FOMC + CPI + NFP + PCE + EIA petroleum/natgas.
+export type MacroCategory = 'fomc' | 'cpi' | 'nfp' | 'pce' | 'eia_petroleum' | 'eia_natgas' | string;
+
+export interface MacroCalendarRow {
+  releaseAt: string;
+  category: MacroCategory;
+  name: string;
+  expectedMovers: string[];
+}
+
+export interface MacroCalendarParams {
+  since?: string;
+  until?: string;
+  categories?: MacroCategory[];
+  movers?: string[];
+}
+
+export interface MacroCalendarResponse {
+  count: number;
+  results: MacroCalendarRow[];
+}
+
+// Unusual options activity z-score per underlying (mac req 748b457e).
+// z_score = (latest_volume - mean) / std over the trailing lookback window.
+// sample_size < 5 ⇒ "collecting"; z_score >= 2 ⇒ unusual.
+export interface OptionsUnusualActivityPoint {
+  symbol: string;
+  latestDate: string | null;
+  latestVolume: number | null;
+  mean: number | null;
+  std: number | null;
+  zScore: number | null;
+  sampleSize: number;
+  lookback: number;
+}
+
+export interface OptionsUnusualActivityParams {
+  symbols: string[];
+  lookback?: number;
+}
+
+export interface OptionsUnusualActivityResponse {
+  count: number;
+  results: OptionsUnusualActivityPoint[];
+}
+
 export type VixTenor = '9D' | '30D' | '3M' | string;
-export type VixTermState = 'contango' | 'backwardation';
+// 3-state regime confirmed by mac req 22ac4889 — threshold ±2% spread VIX vs VIX3M.
+export type VixTermState = 'contango_calm' | 'contango_neutral' | 'backwardation_stress';
 
 export interface VixTermPoint {
   tenor: VixTenor;
@@ -460,6 +610,9 @@ function coerceIvPoint(p: OptionsIvPoint): OptionsIvPoint {
     putCallOiRatio: maybeN(p.putCallOiRatio),
     ivRank30d: maybeN(p.ivRank30d),
     ivRank252d: maybeN(p.ivRank252d),
+    atmIvPercentile252d: maybeN(p.atmIvPercentile252d),
+    realizedVol30d: maybeN(p.realizedVol30d),
+    ivRvSpread30d: maybeN(p.ivRvSpread30d),
   };
 }
 
@@ -540,13 +693,19 @@ 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>,
+    const { symbol, expiry } = params;
+    const res = await this.client.fetch.get<OptionsChainRaw>(ENDPOINTS.OPTIONS_CHAIN(symbol), {
+      params: expiry ? { expiry } : undefined,
     });
+    const calls = (res.calls ?? []).map((c) => coerceContract({ ...c, side: 'call' as const }));
+    const puts = (res.puts ?? []).map((c) => coerceContract({ ...c, side: 'put' as const }));
     return {
-      ...res,
+      symbol: res.symbol,
+      expiry: res.expiry,
       spot: n(res.spot),
-      contracts: (res.contracts ?? []).map(coerceContract),
+      contracts: [...calls, ...puts],
+      expiries: res.expiries,
+      computedAt: res.computedAt,
     };
   }
 
@@ -573,6 +732,77 @@ export class MarketsApi {
     };
   }
 
+  async getAtmIvHistory(params: AtmIvHistoryParams): Promise<AtmIvHistoryResponse> {
+    const { symbol, moneynessMax, ...rest } = params;
+    const res = await this.client.fetch.get<AtmIvHistoryResponse>(ENDPOINTS.OPTIONS_ATM_IV_HISTORY(symbol), {
+      params: {
+        ...rest,
+        ...(moneynessMax != null ? { moneyness_max: moneynessMax } : {}),
+      } as Record<string, unknown>,
+    });
+    return {
+      ...res,
+      results: (res.results ?? []).map((p) => ({
+        ...p,
+        spot: n(p.spot),
+        atmStrike: n(p.atmStrike),
+        atmCallIv: maybeN(p.atmCallIv),
+        atmPutIv: maybeN(p.atmPutIv),
+        atmIv: maybeN(p.atmIv),
+        ivRank30d: maybeN(p.ivRank30d),
+        ivRank252d: maybeN(p.ivRank252d),
+      })),
+    };
+  }
+
+  async getMacroCalendar(params?: MacroCalendarParams): Promise<MacroCalendarResponse> {
+    const { categories, movers, ...rest } = params ?? {};
+    return this.client.fetch.get<MacroCalendarResponse>(ENDPOINTS.MACRO_CALENDAR, {
+      params: {
+        ...rest,
+        ...(categories ? { categories: categories.join(',') } : {}),
+        ...(movers ? { movers: movers.join(',') } : {}),
+      } as Record<string, unknown>,
+    });
+  }
+
+  async getOptionsUnusualActivity(params: OptionsUnusualActivityParams): Promise<OptionsUnusualActivityResponse> {
+    const { symbols, lookback } = params;
+    const res = await this.client.fetch.get<OptionsUnusualActivityResponse>(ENDPOINTS.OPTIONS_UNUSUAL_ACTIVITY, {
+      params: { symbols: symbols.join(','), ...(lookback != null ? { lookback } : {}) } as Record<string, unknown>,
+    });
+    return {
+      ...res,
+      results: (res.results ?? []).map((p) => ({
+        ...p,
+        latestVolume: maybeN(p.latestVolume),
+        mean: maybeN(p.mean),
+        std: maybeN(p.std),
+        zScore: maybeN(p.zScore),
+        sampleSize: n(p.sampleSize),
+        lookback: n(p.lookback),
+      })),
+    };
+  }
+
+  async getBarsBulk(params: BarsBulkParams): Promise<BarsBulkResponse> {
+    const { symbols, ...rest } = params;
+    const res = await this.client.fetch.get<BarsBulkResponse>(ENDPOINTS.BARS_BULK, {
+      params: { ...rest, symbols: symbols.join(','), format: 'json' } as Record<string, unknown>,
+    });
+    const out: Record<string, PriceBar[]> = {};
+    for (const [sym, bars] of Object.entries(res.results ?? {})) {
+      out[sym] = (bars ?? []).map(coerceBar);
+    }
+    return { ...res, results: out };
+  }
+
+  async getSocialPosts(params?: SocialPostsParams): Promise<SocialPostsResponse> {
+    return this.client.fetch.get<SocialPostsResponse>(ENDPOINTS.SOCIAL_POSTS, {
+      params: params as Record<string, unknown> | undefined,
+    });
+  }
+
   async getVixTerm(): Promise<VixTermResponse> {
     const res = await this.client.fetch.get<VixTermResponse>(ENDPOINTS.VIX_TERM);
     return { ...res, points: (res.points ?? []).map(coerceVixPoint) };

package/src/lib/sanitize-core.ts

@@ -0,0 +1,32 @@
+/**
+ * Platform-neutral sanitize helpers — no DOM, no DOMPurify.
+ *
+ * Shared by sanitize.ts (web/node, DOMPurify-backed `sanitizeHtml`) and
+ * sanitize.native.ts (React Native, DOM-free `sanitizeHtml`). Keeping these
+ * pure functions here avoids duplicating them across the two platform entries.
+ */
+
+/**
+ * Validate and sanitize a search query string.
+ *
+ * Trims whitespace, escapes regex special characters, and limits length to 100 chars.
+ */
+export function sanitizeSearchQuery(query: string): string {
+  if (!query || typeof query !== 'string') {
+    return '';
+  }
+
+  return query
+    .trim()
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
+    .substring(0, 100); // Limit length
+}
+
+/**
+ * Validate that a string is a safe SQL/API identifier.
+ *
+ * Only allows alphanumeric characters, underscores, and hyphens.
+ */
+export function validateIdentifier(input: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(input);
+}

package/src/lib/sanitize.native.ts

@@ -0,0 +1,17 @@
+export { sanitizeSearchQuery, validateIdentifier } from './sanitize-core';
+
+/**
+ * XSS protection for React Native, where there is no DOM and no DOMPurify
+ * (isomorphic-dompurify pulls in jsdom, which cannot be bundled by Metro).
+ *
+ * React Native renders text through <Text>, never as interpreted HTML, so the
+ * safe and correct transform is to strip all markup and return plain text. The
+ * web build (sanitize.ts) keeps an allowlist via DOMPurify because the browser
+ * actually renders the result as HTML; RN never does.
+ */
+export function sanitizeHtml(input: string): string {
+  if (!input || typeof input !== 'string') {
+    return '';
+  }
+  return input.replace(/<[^>]*>/g, '');
+}

package/src/lib/sanitize.ts

@@ -1,9 +1,14 @@
 import DOMPurify from 'isomorphic-dompurify';
 
+export { sanitizeSearchQuery, validateIdentifier } from './sanitize-core';
+
 /**
- * XSS Protection - sanitize HTML content
+ * XSS Protection - sanitize HTML content (web/node, via DOMPurify).
  *
  * Strips all tags except a safe allowlist and removes dangerous attributes.
+ *
+ * React Native has no DOM, and bundling isomorphic-dompurify drags in jsdom,
+ * so Metro resolves the `sanitize.native.ts` sibling on native builds instead.
  */
 export function sanitizeHtml(input: string): string {
   return DOMPurify.sanitize(input, {
@@ -12,28 +17,3 @@ export function sanitizeHtml(input: string): string {
     ALLOW_DATA_ATTR: false,
   });
 }
-
-/**
- * Validate and sanitize a search query string.
- *
- * Trims whitespace, escapes regex special characters, and limits length to 100 chars.
- */
-export function sanitizeSearchQuery(query: string): string {
-  if (!query || typeof query !== 'string') {
-    return '';
-  }
-
-  return query
-    .trim()
-    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars
-    .substring(0, 100); // Limit length
-}
-
-/**
- * Validate that a string is a safe SQL/API identifier.
- *
- * Only allows alphanumeric characters, underscores, and hyphens.
- */
-export function validateIdentifier(input: string): boolean {
-  return /^[a-zA-Z0-9_-]+$/.test(input);
-}

package/src/lib/vault-api.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { VaultApi } from './vault-api';
+
+function makeApi() {
+  const fetch = { get: vi.fn(), post: vi.fn(), patch: vi.fn(), delete: vi.fn() };
+  // VaultApi only ever touches client.fetch.*
+  const api = new VaultApi({ fetch } as never);
+  return { api, fetch };
+}
+
+describe('VaultApi', () => {
+  let api: VaultApi;
+  let fetch: { get: ReturnType<typeof vi.fn>; post: ReturnType<typeof vi.fn>; patch: ReturnType<typeof vi.fn>; delete: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    ({ api, fetch } = makeApi());
+  });
+
+  it('listEnvironments hits the environments endpoint with params', async () => {
+    fetch.get.mockResolvedValue({ results: [], count: 0 });
+    await api.listEnvironments({ page: 2 });
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/vault/environments', { params: { page: 2 } });
+  });
+
+  it('createSecret posts to the env-scoped secrets endpoint', async () => {
+    fetch.post.mockResolvedValue({ id: '1', key: 'K' });
+    await api.createSecret('quinns-mac', { key: 'K', value: 'v' });
+    expect(fetch.post).toHaveBeenCalledWith(
+      'api/v1/vault/environments/quinns-mac/secrets',
+      { key: 'K', value: 'v' },
+    );
+  });
+
+  it('revealSecret gets the reveal endpoint and returns the value', async () => {
+    fetch.get.mockResolvedValue({ key: 'K', value: 'sk-secret' });
+    const r = await api.revealSecret('quinns-mac', 'abc');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/vault/environments/quinns-mac/secrets/abc/reveal');
+    expect(r.value).toBe('sk-secret');
+  });
+
+  it('createAccessKey returns the raw key once', async () => {
+    fetch.post.mockResolvedValue({ id: '1', name: 'laptop', key: 'RAW-KEY' });
+    const r = await api.createAccessKey('quinns-mac', { name: 'laptop' });
+    expect(fetch.post).toHaveBeenCalledWith(
+      'api/v1/vault/environments/quinns-mac/access-keys',
+      { name: 'laptop' },
+    );
+    expect(r.key).toBe('RAW-KEY');
+  });
+
+  it('deleteEnvironment deletes by slug', async () => {
+    fetch.delete.mockResolvedValue(undefined);
+    await api.deleteEnvironment('prod');
+    expect(fetch.delete).toHaveBeenCalledWith('api/v1/vault/environments/prod');
+  });
+
+  it('listAudit hits the audit endpoint', async () => {
+    fetch.get.mockResolvedValue({ results: [], count: 0 });
+    await api.listAudit('prod');
+    expect(fetch.get).toHaveBeenCalledWith('api/v1/vault/environments/prod/audit', { params: undefined });
+  });
+});