gloomberb 0.18.4 → 0.19.0

package/src/api-client/index.ts

@@ -67,6 +67,8 @@ export const ASSIST_ARG_OPTION_LIMIT = 128;
 const ASSIST_ARG_OPTION_VALUE_MAX_LENGTH = 40;
 const ASSIST_ARG_OPTION_LABEL_MAX_LENGTH = 60;
 const ASSIST_REQUEST_TIMEOUT_MS = 6_000;
+const SESSION_REVALIDATION_INITIAL_MS = 1_000;
+const SESSION_REVALIDATION_MAX_MS = 30_000;
 
 /**
  * Fits a command's argument values inside the server caps. The value is what
@@ -94,8 +96,15 @@ interface PendingSessionRequest {
 
 class GloomApiClient {
   private currentUser: AuthUser | null = null;
-  /** Local identity of a verified user/credential pair, never serialized. */
+  /** Local user/credential binding, masked until verified and never serialized. */
   private verifiedSessionIdentity: object | null = null;
+  private verifiedSessionCredential: string | null = null;
+  private sessionTransitions = 0;
+  private sessionTransition: Promise<void> | null = null;
+  /** Device adoption and external session installs supersede pending email auth. */
+  private sessionInstallationGeneration = 0;
+  private sessionRevalidationGeneration = 0;
+  private sessionRevalidationTimer: ReturnType<typeof setTimeout> | null = null;
   private sessionChecked = false;
   /** Last few session transitions, content-free, for app://auth. */
   private authTrace: Array<{ at: number; event: string; token: boolean; user: string }> = [];
@@ -110,7 +119,7 @@ class GloomApiClient {
     request: (path, options, canApplySession) => this.request(path, options, canApplySession),
     requireCapturedSession: (message) => this.requireCapturedSession(message),
     setCurrentUser: (user) => this.setCurrentUser(user),
-    setSessionToken: (token) => this.setSessionToken(token),
+    setSessionToken: (token) => this.installSessionToken(token),
     updateCurrentUser: (updater) => this.updateCurrentUser(updater),
   });
   private readonly socket: CloudApiSocket = new CloudApiSocket({
@@ -123,7 +132,6 @@ class GloomApiClient {
     markCurrentUserUnverified: () => {
       if (this.currentUser) {
         this.currentUser = { ...this.currentUser, emailVerified: false };
-        this.verifiedSessionIdentity = null;
         this.emitCurrentUserChange();
       }
     },
@@ -165,6 +173,8 @@ class GloomApiClient {
   }
 
   setCookieSessionMode(enabled: boolean): void {
+    this.cancelSessionRevalidation();
+    this.sessionInstallationGeneration += 1;
     this.sessionChecked = false;
     this.verifiedSessionIdentity = null;
     this.transport.setCookieSessionMode(enabled);
@@ -172,12 +182,21 @@ class GloomApiClient {
   }
 
   setSessionToken(token: string | null): void {
+    if (this.transport.getSessionToken() !== token || !token) {
+      this.cancelSessionRevalidation();
+      this.sessionInstallationGeneration += 1;
+    }
+    this.installSessionToken(token);
+  }
+
+  private installSessionToken(token: string | null): void {
     const changed = this.transport.getSessionToken() !== token;
     this.sessionChecked = false;
     this.transport.setSessionToken(token);
     if (changed) this.verifiedSessionIdentity = null;
     this.traceAuth(changed ? "setSessionToken:changed" : "setSessionToken:same");
     if (!token) {
+      this.cancelSessionRevalidation();
       this.currentUser = null;
       this.verifiedSessionIdentity = null;
     }
@@ -206,6 +225,14 @@ class GloomApiClient {
     return !!this.transport.getSessionToken() || !!this.currentUser;
   }
 
+  /**
+   * Whether a request sent now carries a session: the token this client
+   * holds, or, in the browser, the cookie it cannot see and assumes is there.
+   */
+  hasSessionCredential(): boolean {
+    return this.transport.hasSessionCredential();
+  }
+
   /** Notifies when the user or credential changes, including plan and trial entitlement. */
   subscribeCurrentUser(listener: () => void): () => void {
     this.currentUserListeners.add(listener);
@@ -224,7 +251,9 @@ class GloomApiClient {
 
   /** Null while a replacement credential still awaits its matching user. */
   getVerifiedSessionIdentity(): object | null {
-    return this.isVerified() ? this.verifiedSessionIdentity : null;
+    return this.sessionTransitions === 0 && this.isVerified()
+      && this.verifiedSessionCredential === this.transport.getSessionToken()
+      ? this.verifiedSessionIdentity : null;
   }
 
   /**
@@ -276,11 +305,18 @@ class GloomApiClient {
     if (this.authTrace.length > 24) this.authTrace.shift();
   }
 
-  private setCurrentUser(user: AuthUser | null): void {
+  private setCurrentUser(user: AuthUser | null, confirmSession = true): void {
+    const sameAccount = this.currentUser?.id === user?.id;
     const changed = this.socketEntitlementKey(this.currentUser) !== this.socketEntitlementKey(user);
     this.traceAuth("setCurrentUser", user);
     this.currentUser = user;
-    this.verifiedSessionIdentity = this.isVerified() ? {} : null;
+    if (confirmSession) {
+      this.clearSessionRevalidationTimer();
+      this.verifiedSessionIdentity = user ? {} : null;
+      this.verifiedSessionCredential = this.transport.getSessionToken();
+    } else if (!sameAccount || !user) {
+      this.verifiedSessionIdentity = null;
+    }
     this.socket.syncAuthState({ reconnect: changed });
     this.emitCurrentUserChange();
   }
@@ -291,7 +327,9 @@ class GloomApiClient {
 
   private updateCurrentUser(updater: (user: AuthUser) => AuthUser): void {
     if (!this.currentUser) return;
-    this.setCurrentUser(updater(this.currentUser));
+    // A socket/profile update is metadata, not proof that a replacement
+    // credential belongs to this user. Keep its existing binding, even null.
+    this.setCurrentUser(updater(this.currentUser), false);
   }
 
   private socketEntitlementKey(user: AuthUser | null): string {
@@ -326,11 +364,123 @@ class GloomApiClient {
     return this.currentUser?.emailVerified ? this.currentUser : null;
   }
 
-  signUp = this.auth.signUp.bind(this.auth);
-  signIn = this.auth.signIn.bind(this.auth);
+  signUp = (email: string, username: string, name: string, password: string) =>
+    this.withSessionTransition((isCurrent) => this.auth.signUp(email, username, name, password, isCurrent));
+  signIn = (email: string, password: string) =>
+    this.withSessionTransition((isCurrent) => this.auth.signIn(email, password, isCurrent));
   startDeviceSignIn = this.auth.startDeviceSignIn.bind(this.auth);
   pollDeviceSignIn = this.auth.pollDeviceSignIn.bind(this.auth);
-  signOut = this.auth.signOut.bind(this.auth);
+  signOut = () => this.withSessionTransition((isCurrent) => this.auth.signOut(isCurrent), false);
+
+  /** Cookies can change before an auth response's body arrives, including ones the browser hides. */
+  private withSessionTransition<T>(run: (isCurrent: () => boolean) => Promise<T>, reconcileFailure = true): Promise<T> {
+    const previous = this.sessionTransition;
+    this.cancelSessionRevalidation();
+    let revalidationGeneration = this.sessionRevalidationGeneration;
+    const generation = this.sessionInstallationGeneration;
+    const isCurrent = () => generation === this.sessionInstallationGeneration;
+    this.sessionTransitions += 1;
+    this.sessionChecked = false;
+    this.verifiedSessionIdentity = null;
+    this.sessionRequestGeneration += 1;
+    this.emitCurrentUserChange();
+    let needsRevalidation = false;
+    const operation = (async () => {
+      // Serialize credential-changing requests so a late response cannot pair
+      // one account's user with another request's installed cookie.
+      if (previous) await previous;
+      try {
+        if (!isCurrent()) throw new Error("Another sign-in replaced this request.");
+        // An earlier queued sign-out may have retired retries while clearing its token.
+        revalidationGeneration = this.sessionRevalidationGeneration;
+        this.sessionRequestGeneration += 1;
+        const result = await run(isCurrent);
+        if (!isCurrent()) throw new Error("Another sign-in replaced this request.");
+        return result;
+      } catch (error) {
+        if (isCurrent()) {
+          this.verifiedSessionIdentity = null;
+          this.sessionChecked = false;
+        }
+        if (isCurrent() && reconcileFailure && this.transport.hasSessionCredential()) {
+          // A failed body may already have changed the cookie. A fresh session
+          // check is the only way to resume; retry if it cannot validate yet.
+          needsRevalidation = true;
+          this.sessionRequestGeneration += 1;
+          await this.revalidateSession(() => isCurrent()
+            && revalidationGeneration === this.sessionRevalidationGeneration).catch((failure) => {
+            if (!isCurrent()) return;
+            this.verifiedSessionIdentity = null;
+            logFailure("cloud.auth", "Restore session after failed sign-in failed")(failure);
+          });
+        }
+        throw error;
+      } finally {
+        if (isCurrent()) this.sessionRequestGeneration += 1;
+        this.sessionTransitions -= 1;
+        if (isCurrent() && needsRevalidation) this.scheduleSessionRevalidation(revalidationGeneration);
+        this.emitCurrentUserChange();
+      }
+    })();
+    const settled = operation.then(() => {}, () => {
+      // Intentional ignore: the caller receives the error while the auth queue continues.
+    });
+    this.sessionTransition = settled;
+    void settled.then(() => { if (this.sessionTransition === settled) this.sessionTransition = null; });
+    return operation;
+  }
+
+  private clearSessionRevalidationTimer(): void {
+    if (this.sessionRevalidationTimer !== null) clearTimeout(this.sessionRevalidationTimer);
+    this.sessionRevalidationTimer = null;
+  }
+
+  private cancelSessionRevalidation(): void {
+    this.sessionRevalidationGeneration += 1;
+    this.clearSessionRevalidationTimer();
+  }
+
+  /** A failed auth response can replace a cookie even when its recovery read is offline. */
+  private scheduleSessionRevalidation(generation: number, delay = SESSION_REVALIDATION_INITIAL_MS): void {
+    const isCurrent = () => generation === this.sessionRevalidationGeneration;
+    const needsRevalidation = () => isCurrent() && this.sessionTransitions === 0
+      && !this.sessionChecked && this.verifiedSessionIdentity === null && this.transport.hasSessionCredential();
+    if (!needsRevalidation() || this.sessionRevalidationTimer !== null) return;
+    this.sessionRevalidationTimer = setTimeout(() => {
+      this.sessionRevalidationTimer = null;
+      if (!needsRevalidation()) return;
+      void this.revalidateSession(isCurrent).catch((error) => {
+        if (isCurrent()) logFailure("cloud.auth", "Retry session validation failed")(error);
+      }).finally(() => {
+        this.scheduleSessionRevalidation(generation, Math.min(delay * 2, SESSION_REVALIDATION_MAX_MS));
+      });
+    }, delay);
+    this.sessionRevalidationTimer.unref?.();
+  }
+
+  private async revalidateSession(isCurrent: () => boolean): Promise<void> {
+    const user = await this.getSession(isCurrent);
+    const credential = this.getSessionToken();
+    if (user || !credential || !isCurrent()) return;
+    // A native null-session response can retain a usable token. Validate it
+    // through the account endpoint, without pairing it with a cached user.
+    this.sessionChecked = false;
+    const previousUser = this.currentUser;
+    const canApply = () => isCurrent() && this.getSessionToken() === credential && this.currentUser === previousUser;
+    try {
+      const profile = await this.auth.getAccountProfile(canApply);
+      if (!canApply()) return;
+      this.sessionChecked = true;
+      this.auth.restoreCachedUser({ ...profile, updatedAt: profile.updatedAt ?? undefined });
+    } catch (error) {
+      if (!canApply()) return;
+      if (error instanceof ApiRequestError && error.status === 401) {
+        this.installSessionToken(null);
+        return;
+      }
+      throw error;
+    }
+  }
 
   async getSession(isCurrent: () => boolean = () => true): Promise<AuthUser | null> {
     if (!isCurrent()) return this.currentUser;
@@ -353,7 +503,10 @@ class GloomApiClient {
       credential: this.getSessionToken(),
       promise: this.auth.getSession(canApply)
         .then(({ user, validated }) => {
-          if (validated && canApply()) this.sessionChecked = true;
+          if (validated && canApply()) {
+            this.sessionChecked = true;
+            this.clearSessionRevalidationTimer();
+          }
           this.traceAuth(validated ? "getSession:done" : "getSession:retained", user);
           return user;
         })
@@ -753,6 +906,8 @@ class GloomApiClient {
   subscribeScanner = this.socket.subscribeScanner.bind(this.socket);
 
   dispose(): void {
+    this.cancelSessionRevalidation();
+    this.sessionInstallationGeneration += 1;
     this.sessionRequestGeneration += 1;
     this.sessionRequest = null;
     this.socket.dispose();
@@ -799,11 +954,14 @@ class GloomApiClient {
   getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
   getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
   getScannerFlowHistory = this.data.getScannerFlowHistory.bind(this.data);
+  getScannerFlowSession = this.data.getScannerFlowSession.bind(this.data);
+  getLiveScan = this.data.getLiveScan.bind(this.data);
   getCloudEstimateRevisions = this.data.getCloudEstimateRevisions.bind(this.data);
   getCloudMoneyMarkets = this.data.getCloudMoneyMarkets.bind(this.data);
   equityScreener = this.data.equityScreener.bind(this.data);
   getMemberFunds = this.data.getMemberFunds.bind(this.data);
   getFundMembers = this.data.getFundMembers.bind(this.data);
+  getFundBreadth = this.data.getFundBreadth.bind(this.data);
   getFundChanges = this.data.getFundChanges.bind(this.data);
   getFundFacts = this.data.getFundFacts.bind(this.data);
   getCloudExchangeAnnouncements = this.data.getCloudExchangeAnnouncements.bind(this.data);
@@ -855,6 +1013,8 @@ class GloomApiClient {
   getCloudPerpsHistory = this.data.getCloudPerpsHistory.bind(this.data);
   getCloudPerpsRankings = this.data.getCloudPerpsRankings.bind(this.data);
   getCloudPerpsCompare = this.data.getCloudPerpsCompare.bind(this.data);
+  getCloudPerpsLiquidations = this.data.getCloudPerpsLiquidations.bind(this.data);
+  getCloudPerpsDepth = this.data.getCloudPerpsDepth.bind(this.data);
   getCloudPerpsEquity = this.data.getCloudPerpsEquity.bind(this.data);
   getCloudPerpsEquities = this.data.getCloudPerpsEquities.bind(this.data);
   getCloudPerpsMarket = this.data.getCloudPerpsMarket.bind(this.data);

package/src/api-client/live-scan.ts

@@ -0,0 +1,91 @@
+/**
+ * The live scanner's wire format: a user's own intraday conditions over a
+ * universe of US stocks, evaluated by Gloom Cloud against a market-wide
+ * snapshot it refreshes every few seconds (real-time for Pro, 15 minutes
+ * delayed otherwise). `GET /market/scanner/live?scan=<definition JSON>`.
+ */
+
+/** Minutes a move, a volume window or an event can look back over. */
+export const LIVE_SCAN_WINDOWS = [1, 5, 15, 30, 60] as const;
+export type LiveScanWindow = (typeof LIVE_SCAN_WINDOWS)[number];
+
+export const LIVE_SCAN_INDEXES = ["sp500", "sp400", "sp600", "russell1000", "russell2000"] as const;
+export type LiveScanIndex = (typeof LIVE_SCAN_INDEXES)[number];
+
+/** The universe as Gloom Cloud reads it; a watchlist goes as its symbols. */
+type LiveScanWireUniverse =
+  | { kind: "all" }
+  | { kind: "index"; index: LiveScanIndex }
+  | { kind: "sector"; sector: string }
+  | { kind: "symbols"; symbols: string[] };
+
+export type LiveScanDirection = "up" | "down" | "either";
+
+export type LiveScanCondition =
+  /** Volume over the window (or the session so far) against the 20-session average's pace. */
+  | { kind: "volume_spike"; window: LiveScanWindow | "day"; ratio: number }
+  /** Percent move over the last `window` minutes. */
+  | { kind: "move"; window: LiveScanWindow; direction: LiveScanDirection; percent: number }
+  /** A new session high (low) printed in the last `within` minutes. */
+  | { kind: "new_high" | "new_low"; within: LiveScanWindow }
+  /** Crossed the session VWAP in the last `within` minutes, and still on that side. */
+  | { kind: "vwap_cross"; direction: "above" | "below" | "either"; within: LiveScanWindow }
+  /** The session's open against the previous close. */
+  | { kind: "gap"; direction: LiveScanDirection; percent: number };
+
+export interface LiveScanWireDefinition {
+  version: 1;
+  universe: LiveScanWireUniverse;
+  conditions: LiveScanCondition[];
+  minPrice?: number;
+  minMarketCap?: number;
+  minVolume?: number;
+}
+
+type LiveScanStatus = "live" | "starting" | "closed" | "degraded";
+
+export interface LiveScanMatch {
+  symbol: string;
+  name: string | null;
+  /** Its US venue (NASDAQ, NYSE, ...), null when the screener does not list it. */
+  exchange?: string | null;
+  price: number;
+  changePercent: number | null;
+  volume: number | null;
+  /** The session's volume against the 20-session average's pace so far. */
+  relativeVolume: number | null;
+  /** Price against the session VWAP, in percent. */
+  vwapPercent: number | null;
+  gapPercent: number | null;
+  /**
+   * The figure each condition matched on, in the definition's order: a
+   * percent for a move or a gap, a multiple for a volume spike, the time of
+   * the event (epoch ms) for a new high or low or a VWAP cross.
+   */
+  values: Array<number | null>;
+  /** The latest event a condition matched on. */
+  signalAt: number | null;
+  /** When the price printed. */
+  at: number | null;
+}
+
+export interface LiveScanPayload {
+  status: LiveScanStatus;
+  access: "realtime" | "delayed";
+  delayMinutes: number;
+  /** The market time the snapshot shows. */
+  asOf: number | null;
+  /** When the snapshot was refreshed. */
+  takenAt: number | null;
+  /** How often the snapshot refreshes. */
+  refreshMs: number;
+  scanned: number;
+  matched: number;
+  matches: LiveScanMatch[];
+  /** Windows the scanner cannot measure yet after it started; a condition over one matches nothing until then. */
+  warmingWindows: LiveScanWindow[];
+  warnings: string[];
+}
+
+/** The scan travels in a POST body: a watchlist of 1,000 symbols would not fit a request line. */
+export const LIVE_SCAN_PATH = "/market/scanner/live";

package/src/api-client/market-discovery.ts

@@ -21,6 +21,12 @@ export interface ScreenerQuote {
   previousClose?: number;
   /** The quote's sessions beside the live print the server ranked the row by, when the server sends them. */
   sessions?: CloudMoverSessionFields;
+  /** The listing's float as the equity screener serves it; absent where the server serves none or predates it. */
+  floatShares?: number;
+  /** Set with a float the source states no measurement date for: `partial`. */
+  floatSharesState?: "partial";
+  /** Why the float is partial, as the server says it. */
+  floatSharesReason?: string;
 }
 
 
@@ -105,6 +111,8 @@ export interface DividendSummary {
   /** The ex-date of the distribution that rate annualizes, YYYY-MM-DD. */
   forwardRateAsOf?: string | null;
   payoutRatio: number | null;
+  /** The trailing EPS fundamentals serve for the listing; only its sign is read, since a payout over a loss is not meaningful. Absent from older servers. */
+  trailingEps?: number | null;
   exDividendDate: number | null;
   dividendDate: number | null;
   currency: string | null;
@@ -117,4 +125,6 @@ export interface MarketDividendsPayload {
   summary: DividendSummary | null;
   historyError?: string;
   summaryError?: string;
+  /** When Gloom Cloud last asked for the history and the summary, ISO. Absent from older servers. */
+  triedAt?: string;
 }

package/src/api-client/market-movers.ts

@@ -37,7 +37,14 @@ export interface CloudSessionMoverItem {
   /** Regular-session VWAP. */
   vwap: number | null;
   vwapPercent: number | null;
+  /** The equity screener's float, null where it serves none. */
   floatShares: number | null;
+  /** Set with a float the source states no measurement date for: `partial`. */
+  floatSharesState?: "partial";
+  /** Why the float is partial, as the server says it. */
+  floatSharesReason?: string;
+  /** When the statistics the float is read from were retrieved (ISO). */
+  floatSharesRetrievedAt?: string;
   catalysts: CloudSessionCatalyst[];
   lastUpdated: number;
 }

package/src/api-client/members.ts

@@ -1,7 +1,7 @@
 interface MemberFund { ticker: string; name: string; aliases: string[]; changes: "sp500" | "announcements" | "none" }
 export interface FundMember {
   id: string; symbol: string | null; name: string; sector: string | null;
-  weight: number | null; shares: number; holdingPrice: number; marketValue: number;
+  weight: number | null; shares: number; holdingPrice: number | null; marketValue: number | null;
   price: number | null; priceAsOf: string | null; changePercent: number | null; dailyAsOf: string | null;
   return1WPercent: number | null; return1MPercent: number | null; returnYtdPercent: number | null;
   contribution: number | null; stale: boolean;
@@ -30,3 +30,15 @@ export interface FundChangesPayload {
   estimateLabel: string; attribution: { text: string; url: string } | null;
 }
 export interface MemberFundsPayload { funds: (MemberFund & { asOf: string | null })[] }
+
+interface BreadthCount { above: number; eligible: number; percent: number | null }
+export interface BreadthDay {
+  date: string; asOf: string; membershipAsOf: string; memberCount: number; observed: number;
+  advances: number; declines: number; unchanged: number; advanceDeclineEligible: number;
+  ma20: BreadthCount; ma50: BreadthCount; ma200: BreadthCount;
+  newHighs: number; newLows: number; highLowEligible: number; adLine: number | null;
+}
+export interface FundBreadthPayload {
+  fund: MemberFund; basis: "daily-close" | "intraday"; access?: "realtime" | "delayed"; membershipBasis: "current-members";
+  latest: BreadthDay | null; history: BreadthDay[]; stale: boolean;
+}

package/src/api-client/perps.ts

@@ -174,3 +174,46 @@ export interface PerpMarketPayload extends PerpBoardPayload {
   evidence: { kind: string; period_at: string; received_at: string; superseded_at: string | null; fingerprint: string; payload: PerpMarket | PerpFunding | PerpCandle }[];
   methodologyUrl: string;
 }
+
+/** One contract's liquidations: long is longs liquidated (forced sells), short is shorts; quote notional. */
+export interface PerpLiquidationMarket {
+  marketId: string; venue: string; symbol: string; dex: string; quoteCurrency: string;
+  long24h: number; short24h: number; long7d: number; short7d: number; count24h: number; count7d: number; lastEventAt: string | null;
+}
+export interface PerpLiquidationPrint {
+  marketId: string; venue: string; symbol: string; dex: string;
+  side: "long" | "short"; priceKind: "fill" | "bankruptcy"; price: number; quantity: number; notionalUsd: number;
+  /** The venue's time for the liquidation. */
+  eventAt: string;
+  /** When Gloom Cloud received it. */
+  receivedAt: string;
+}
+/** One base asset's liquidations across the venues' public streams. */
+export interface PerpLiquidationsPayload {
+  status: string; baseAsset: string; asOf: string; from: string; collectingSince: string | null;
+  markets: PerpLiquidationMarket[];
+  totals: Pick<PerpLiquidationMarket, "long24h" | "short24h" | "long7d" | "short7d" | "count24h" | "count7d">;
+  /** Pro: UTC hours with liquidations over the last 7 days; empty for a preview. */
+  hourly: { time: string; long: number; short: number; count: number }[];
+  largest: PerpLiquidationPrint[];
+  streams: { venue: string; state: "live" | "down"; lastOkAt: string | null; error: string | null }[];
+  notes: string[];
+  locked: boolean; access: "pro" | "preview";
+}
+/** Quote notional resting within 0.5%, 1% and 2% of mid; reach is how far the returned book went, as a fraction of mid. */
+export interface PerpDepthSnapshot {
+  marketId: string; bucket: string; observedAt: string; sourceAsOf: string | null; mid: number;
+  bid05: number; ask05: number; bid1: number; ask1: number; bid2: number; ask2: number;
+  bidReach: number; askReach: number; levels: number; grouping: number | null;
+}
+export interface PerpDepthRow extends PerpDepthSnapshot { venue: string; symbol: string; dex: string; quoteCurrency: string; stale: boolean }
+/** One base asset's hourly order book depth across the venues. */
+export interface PerpDepthPayload {
+  status: string; baseAsset: string; asOf: string;
+  rows: PerpDepthRow[];
+  /** Pro: every market's hourly snapshots over the last 7 days; empty for a preview. */
+  history: PerpDepthSnapshot[];
+  sources: { venue: string; lastOkAt: string | null; error: string | null }[];
+  notes: string[];
+  locked: boolean; access: "pro" | "preview";
+}