@startsimpli/api 0.5.19 → 0.5.21

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/team-invitations-api.ts

@@ -0,0 +1,49 @@
+/**
+ * TeamInvitations API wrapper for /api/v1/team-invitations/*.
+ *
+ * The accept endpoint is intentionally public-ish — it accepts an unauth
+ * caller carrying the one-time invite token in the body. The TeamMember
+ * row is created idempotently by the backend manager (startsim-tsm).
+ */
+
+import type { ApiClient } from './api-client';
+import { ENDPOINTS } from '../constants/endpoints';
+import type {
+  TeamInvitation,
+  TeamInvitationListParams,
+  CreateTeamInvitationInput,
+} from '../types/team';
+import type { PaginatedResponse } from '../types';
+
+export class TeamInvitationsApi {
+  constructor(private client: ApiClient) {}
+
+  list(params?: TeamInvitationListParams): Promise<PaginatedResponse<TeamInvitation>> {
+    return this.client.fetch.get<PaginatedResponse<TeamInvitation>>(
+      ENDPOINTS.TEAM_INVITATIONS,
+      { params },
+    );
+  }
+
+  /**
+   * Send a single invitation. The create response includes the raw token;
+   * subsequent reads will redact it.
+   */
+  create(input: CreateTeamInvitationInput): Promise<TeamInvitation> {
+    return this.client.fetch.post<TeamInvitation>(ENDPOINTS.TEAM_INVITATIONS, input);
+  }
+
+  revoke(id: string): Promise<void> {
+    return this.client.fetch.post<void>(ENDPOINTS.TEAM_INVITATION_REVOKE(id));
+  }
+
+  /**
+   * Accept an invitation. The caller posts the one-time token; the backend
+   * wires the TeamMember idempotently (startsim-tsm).
+   */
+  accept(id: string, token: string): Promise<TeamInvitation> {
+    return this.client.fetch.post<TeamInvitation>(ENDPOINTS.TEAM_INVITATION_ACCEPT(id), {
+      token,
+    });
+  }
+}

package/src/lib/teams-api.ts

@@ -0,0 +1,73 @@
+/**
+ * Teams API wrapper for /api/v1/teams/* plus the bulk-mgmt actions shipped
+ * by startsim-tsm (bulk-invite, remove-member, update-role).
+ *
+ * The Django TeamViewSet accepts numeric id OR slug. Member-mutation
+ * endpoints take user_id in the body, not the URL. startsim-o7s.
+ */
+
+import type { ApiClient } from './api-client';
+import { ENDPOINTS } from '../constants/endpoints';
+import type {
+  Team,
+  TeamMember,
+  TeamListParams,
+  BulkInviteEntry,
+  BulkInviteResult,
+  TeamRole,
+} from '../types/team';
+import type { PaginatedResponse } from '../types';
+
+/** Shape returned by /team-members/my-teams/ — a flat array of memberships. */
+export interface MyTeamMembership extends TeamMember {
+  team?: Team;
+}
+
+export class TeamsApi {
+  constructor(private client: ApiClient) {}
+
+  /** List teams visible to the current user. */
+  list(params?: TeamListParams): Promise<PaginatedResponse<Team>> {
+    return this.client.fetch.get<PaginatedResponse<Team>>(ENDPOINTS.TEAMS, { params });
+  }
+
+  /** Retrieve a single team by id or slug. */
+  retrieve(idOrSlug: string): Promise<Team> {
+    return this.client.fetch.get<Team>(ENDPOINTS.TEAM(idOrSlug));
+  }
+
+  /** List members of a team. Backend returns the full set (no pagination). */
+  members(idOrSlug: string): Promise<TeamMember[]> {
+    return this.client.fetch.get<TeamMember[]>(ENDPOINTS.TEAM_MEMBERS(idOrSlug));
+  }
+
+  /**
+   * Bulk-invite endpoint shipped by startsim-tsm. Sends one POST with the
+   * full list of {email, role} pairs and returns invited + skipped.
+   */
+  bulkInvite(idOrSlug: string, invitations: BulkInviteEntry[]): Promise<BulkInviteResult> {
+    return this.client.fetch.post<BulkInviteResult>(ENDPOINTS.TEAM_BULK_INVITE(idOrSlug), {
+      invitations,
+    });
+  }
+
+  /** Remove a member from the team. user_id goes in the body (not the URL). */
+  removeMember(idOrSlug: string, userId: string): Promise<void> {
+    return this.client.fetch.post<void>(ENDPOINTS.TEAM_REMOVE_MEMBER(idOrSlug), {
+      userId,
+    });
+  }
+
+  /** Promote/demote a member — fails if it would leave zero OWNERs. */
+  updateRole(idOrSlug: string, userId: string, role: TeamRole): Promise<TeamMember> {
+    return this.client.fetch.post<TeamMember>(ENDPOINTS.TEAM_UPDATE_ROLE(idOrSlug), {
+      userId,
+      role,
+    });
+  }
+
+  /** Return the current user's membership rows across every team they touch. */
+  myTeams(): Promise<MyTeamMembership[]> {
+    return this.client.fetch.get<MyTeamMembership[]>(ENDPOINTS.TEAM_MEMBERS_MY_TEAMS);
+  }
+}

package/src/lib/users-api.ts

@@ -7,6 +7,8 @@ import type {
   UpdateProfileRequest,
   ChangePasswordRequest,
   ChangePasswordResponse,
+  EarlyRegisterRequest,
+  EarlyRegisterResponse,
 } from '../types/user';
 import { ENDPOINTS } from '../constants/endpoints';
 import type { ApiClient } from './api-client';
@@ -37,4 +39,15 @@ export class UsersApi {
       data
     );
   }
+
+  /**
+   * Passwordless early-access registration (name + email only).
+   * Public endpoint — no auth token required.
+   */
+  async earlyRegister(data: EarlyRegisterRequest): Promise<EarlyRegisterResponse> {
+    return this.client.fetch.post<EarlyRegisterResponse>(
+      ENDPOINTS.AUTH_EARLY_REGISTER,
+      data
+    );
+  }
 }

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 });
+  });
+});