gloomberb 0.15.7 → 0.16.0

package/src/api-client/perps.ts

@@ -0,0 +1,127 @@
+const ASSET_CLASSES = ["stocks", "indices", "energy", "metals", "fx", "crypto", "other"] as const
+type AssetClass = (typeof ASSET_CLASSES)[number]
+type PerpVenue = "hyperliquid" | "binance" | "bybit" | "okx" | "deribit" | "coinbase" | "kraken" | "dydx"
+
+/** Rates and premiums are fractions, timestamps UTC; null always means unavailable. */
+interface PerpMarket {
+  marketId: string
+  venue: PerpVenue
+  dex: string
+  symbol: string
+  baseAsset: string
+  displayName: string
+  assetClass: AssetClass
+  underlyingSymbol: string | null
+  underlyingCurrency: string | null
+  quoteCurrency: string
+  marginCurrency: string
+  contractType: "linear" | "inverse" | "quanto"
+  priceMultiplier: number
+  markPrice: number | null
+  oraclePrice: number | null
+  lastPrice: number | null
+  previousDayPrice: number | null
+  priceChange24h: number | null
+  premium: number | null
+  venuePremium: number | null
+  fundingRate: number | null
+  fundingIntervalHours: number | null
+  fundingKind: "current" | "last-paid" | "continuous"
+  fundingRate8h: number | null
+  fundingApr: number | null
+  predictedFundingRate: number | null
+  predictedFundingIntervalHours: number | null
+  nextFundingAt: string | null
+  openInterestBase: number | null
+  openInterestUsd: number | null
+  volume24hUsd: number | null
+  maxLeverage: number | null
+  isolatedOnly: boolean | null
+  delisted: boolean
+  observedAt: string
+  sourceAsOf: string | null
+  sourceUrl: string
+  confidence: "high" | "medium" | "low"
+  qualityFlags: string[]
+}
+
+interface PerpFunding {
+  marketId: string
+  time: string
+  rate: number
+  intervalHours: number
+  premium: number | null
+  observedAt: string
+  sourceUrl: string
+}
+
+interface PerpCandle {
+  marketId: string
+  time: string
+  interval: "1h"
+  open: number
+  high: number
+  low: number
+  close: number
+  volumeBase: number | null
+  trades: number | null
+  observedAt: string
+  sourceUrl: string
+}
+
+interface UnderlyingReference {
+  symbol: string
+  price: number
+  currency: string
+  asOf: string
+  marketState: string | null
+  sourceUrl: string
+}
+
+export interface PerpBoardRow extends PerpMarket {
+  stale: boolean
+  oiChange1h: number | null
+  oiChange24h: number | null
+  oiUsdChange1h: number | null
+  oiUsdChange24h: number | null
+  underlying: UnderlyingReference | null
+  underlyingPremium: number | null
+  closedMarketPremium: number | null
+}
+
+type PerpHistoryPoint = {
+  time: string
+  resolution: "minute" | "hour" | "day"
+  markPrice: number | null
+  oraclePrice: number | null
+  premium: number | null
+  fundingRate: number | null
+  fundingIntervalHours: number | null
+  openInterestBase: number | null
+  openInterestUsd: number | null
+  sampleCount: number
+  firstObservedAt: string
+  lastObservedAt: string
+}
+
+export interface PerpBoardPayload {
+  status: string; asOf: string | null; rows: PerpBoardRow[]; total: number; locked: number;
+  access: "pro" | "preview"; sources?: unknown[];
+}
+export interface PerpHistoryPayload {
+  status: string; marketId: string; rows: PerpHistoryPoint[]; funding: PerpFunding[]; candles: PerpCandle[];
+  locked: boolean; access: "pro" | "preview"; asOf: string | null;
+  from?: string; to?: string; resolution?: "minute" | "hour" | "day"; truncated?: boolean;
+}
+export interface PerpRankingsPayload {
+  status: string; asOf: string | null; access: "pro" | "preview"; locked: boolean;
+  fundingPositive: PerpBoardRow[]; fundingNegative: PerpBoardRow[]; oiSurges: PerpBoardRow[];
+  premiumDislocations: PerpBoardRow[]; closedMarketDislocations: PerpBoardRow[];
+}
+export type PerpBoardQuery = { assetClass?: string; search?: string; sort?: string; includeDelisted?: boolean };
+export type PerpHistoryQuery = { marketId: string; from?: string; to?: string; resolution?: "auto" | "minute" | "hour" | "day"; limit?: number };
+
+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;
+}

package/src/api-client/power.ts

@@ -0,0 +1,148 @@
+/** Power quantities are MW unless explicitly qualified in metrics; dates retain source precision. */
+type PowerKind = "queue" | "load" | "capacity" | "utility"
+type PowerStatus = "active" | "completed" | "withdrawn" | "approved" | "operating" | "unknown"
+type PowerFuel = "solar" | "wind" | "storage" | "gas" | "nuclear" | "hydro" | "coal" | "hybrid" | "other" | "load" | "unknown"
+interface PowerRecord {
+  id: string
+  sourceId: string
+  sourceProjectId: string
+  kind: PowerKind
+  name: string
+  country: string
+  region: string
+  state: string | null
+  county: string | null
+  zone: string | null
+  developer: string | null
+  utility: string | null
+  fuel: PowerFuel
+  technology: string | null
+  status: PowerStatus
+  statusRaw: string | null
+  capacityMw: number | null
+  requestedDate: string | null
+  proposedDate: string | null
+  completedDate: string | null
+  withdrawnDate: string | null
+  period: string | null
+  asOf: string | null
+  observedAt: string
+  sourceUrl: string
+  sourceLocator: string
+  confidence: number
+  /** Raw source cells or exact source excerpt. Never manufactured prose presented as a quote. */
+  evidence: Record<string, unknown>
+  /** Optional native facts e.g. generationMwh, customers, salesMwh, loadClass. */
+  metrics: Record<string, string | number | boolean | null>
+  /** Historical benchmarks never add to current direct-source queue totals. */
+  historical: boolean
+}
+interface PowerEntityLink {
+  name: string
+  entityId: string
+  tickers: { ticker: string; exchange?: string }[]
+  confidence: number
+  role: "developer" | "utility"
+}
+export interface PowerProject extends PowerRecord {
+  snapshotId: string
+  revision: number
+  entities: PowerEntityLink[]
+}
+export interface PowerFilter {
+  sort?: "capacityMw" | "name" | "region" | "status" | "proposedDate" | "generationMwh" | "salesMwh" | "revenueUsd" | "summerPeakDemandMw" | "winterPeakDemandMw"
+  direction?: "asc" | "desc"
+  country?: string
+  region?: string
+  fuel?: string
+  status?: string
+  kind?: string
+  symbol?: string
+  search?: string
+  loadClass?: string
+  sourceId?: string
+  historical?: boolean
+  offset?: number
+  limit?: number
+  from?: string
+  to?: string
+}
+export interface PowerAggregate {
+  sourceId: string
+  country: string
+  region: string
+  fuel: string
+  status: string
+  kind: string
+  projects: number
+  capacityMw: number
+  unknownCapacity: number
+}
+export interface PowerHistoryPoint extends PowerAggregate {
+  basis: "observed" | "published"
+  sourceUrls: string[]
+  sourceId: string
+  observedAt: string
+  asOf: string | null
+  period: string | null
+  historical: boolean
+}
+export interface PowerCoverage {
+  id: string
+  country: string
+  region: string
+  kind: PowerKind
+  role: "direct" | "benchmark" | "context"
+  status: "current" | "stale" | "pending" | "failed" | "disabled"
+  reason: string | null
+  sourceUrl: string
+  asOf: string | null
+  observedAt: string | null
+  records: number
+  nextPollAt: string | null
+}
+export interface PowerRates {
+  sourceId: string
+  region: string
+  country: string
+  cohort: string
+  projects: number
+  completed: number
+  withdrawn: number
+  active: number
+  unknown: number
+  completionRate: number | null
+  withdrawalRate: number | null
+}
+export interface PowerExposure {
+  sourceId: string
+  sourceUrls: string[]
+  asOf: string | null
+  observedAt: string
+  utility: string
+  country: string
+  region: string
+  requestedMw: number
+  approvedMw: number
+  operatingMw: number
+  requests: number
+  unknownCapacity: number
+  entities: PowerEntityLink[]
+}
+export interface PowerBoard {
+  generatedAt: string
+  access: "full" | "preview"
+  projects: PowerProject[]
+  total: number
+  hasMore: boolean
+  nextOffset: number | null
+  aggregates: PowerAggregate[]
+  rates: PowerRates[]
+  exposure: PowerExposure[]
+  coverage: PowerCoverage[]
+  filters: { countries: string[]; regions: string[]; fuels: string[]; statuses: string[] }
+  locked: { projects: number; aggregates: number; rates: number; exposure: number }
+}
+
+export interface PowerHistory { generatedAt: string; access: "full" | "preview"; points: PowerHistoryPoint[]; locked: number; hasMore: boolean; nextOffset: number | null }
+export interface PowerDetail { generatedAt: string; access: "full" | "preview"; project: PowerProject | null; revisions: PowerProject[]; totalRevisions: number; hasMore: boolean; nextOffset: number | null; locked: number }

package/src/api-client/request.ts

@@ -53,7 +53,22 @@ export interface CloudApiFetchTransportOptions {
   streamFetch?: CloudApiStreamFetch;
 }
 
+/**
+ * One upload with its bytes and the headers the client built. A transport that
+ * can watch the body go out (a browser XMLHttpRequest) reports `onProgress`
+ * with the fraction sent; others never call it.
+ */
+export interface CloudApiUploadRequest {
+  url: string;
+  body: Blob | Uint8Array;
+  headers: Headers;
+  signal?: AbortSignal;
+  onProgress?: (fraction: number) => void;
+}
+type CloudApiUploadTransport = (request: CloudApiUploadRequest) => Promise<CloudApiResponse>;
+
 let cloudApiFetchTransport: CloudApiFetchTransport = httpFetch;
+let cloudApiUploadTransport: CloudApiUploadTransport | null = null;
 let cloudApiTransportInstalled = false;
 let cloudApiFetchStreaming = true;
 let cloudApiStreamFetch: CloudApiStreamFetch | null = null;
@@ -68,6 +83,11 @@ export function setCloudApiFetchTransport(
   cloudApiStreamFetch = transport ? options.streamFetch ?? null : null;
 }
 
+/** Installs the transport uploads go through; without one they use the fetch transport. */
+export function setCloudApiUploadTransport(transport: CloudApiUploadTransport | null): void {
+  cloudApiUploadTransport = transport;
+}
+
 /**
  * The fetch to use for a response that must be read while it arrives, or null
  * when the installed transport buffers whole responses.
@@ -292,10 +312,47 @@ export class CloudApiRequestTransport {
     }
   }
 
+  /**
+   * POSTs raw bytes, such as an image, and parses the JSON answer like
+   * `request`. Progress is reported where the installed upload transport can
+   * see the body go out.
+   */
+  async upload<T>(
+    path: string,
+    body: Blob | Uint8Array,
+    options: {
+      contentType: string;
+      headers?: HeadersInit;
+      signal?: AbortSignal;
+      onProgress?: (fraction: number) => void;
+    },
+  ): Promise<T> {
+    const headers = new Headers(options.headers);
+    headers.set("Content-Type", options.contentType);
+    const uploadTransport = this.fetchTransport ? null : cloudApiUploadTransport;
+    const send: CloudApiFetchTransport | undefined = uploadTransport
+      ? (url, init) => uploadTransport({
+        url,
+        body,
+        headers: new Headers(init?.headers),
+        signal: options.signal,
+        onProgress: options.onProgress,
+      })
+      : undefined;
+    return this.performRequest<T>(path, {
+      method: "POST",
+      headers,
+      // Typed arrays are valid fetch bodies; RequestInit's DOM typing lags behind.
+      body: body as BodyInit,
+      signal: options.signal,
+    }, () => true, send);
+  }
+
   private async performRequest<T>(
     path: string,
     options: RequestInit | undefined,
     canApplySession: () => boolean,
+    send?: CloudApiFetchTransport,
   ): Promise<T> {
     throwIfRequestAborted(options?.signal);
     const headers = new Headers(options?.headers);
@@ -312,7 +369,7 @@ export class CloudApiRequestTransport {
 
     const operation = `${options?.method ?? "GET"} ${path.split("?")[0]}`;
     const request = async () => {
-      const res = await (this.fetchTransport ?? cloudApiFetchTransport)(
+      const res = await (send ?? this.fetchTransport ?? cloudApiFetchTransport)(
         `${this.baseUrl}${path}`,
         {
           ...options,

package/src/api-client/research-activity.ts

@@ -1,6 +1,10 @@
 import { apiClient } from "./index";
 import { getCurrentPluginTarget } from "../plugins/current-target";
 import type { DesktopDeepLinkBridge } from "../types/desktop-deeplink";
+import { exposeExperiment, storedExperimentAssignments } from "./web-experiments";
+import { createWallExperimentSession, type WallExperiment, type WallExperimentContext, type WallTeaserVariant } from "./wall-experiments";
+import { hasProAccess } from "./plan-rules";
+import { withDeadline } from "../utils/async-deadline";
 
 export type ResearchActivity =
   | "workspace_opened"
@@ -10,6 +14,8 @@ export type ResearchActivity =
   | "ticker_saved"
   | "pro_feature_used"
   | "upgrade_intent"
+  | "wall_viewed"
+  | "wall_cta_clicked"
   // First-run funnel, one per step reached. Keep in sync with the server's list.
   | "onboarding_started"
   | "onboarding_position_added"
@@ -30,6 +36,9 @@ export type ResearchFeature =
 const sent = new Set<string>();
 let anonymousId: string | undefined;
 let attribution: Record<string, string> = {};
+const wallExperiment = createWallExperimentSession();
+const signinWallExperiment = createWallExperimentSession("wall_teaser_signin");
+const WALL_VIEWS_SESSION_KEY = "gloomberb.wall-teaser.views";
 
 const ATTRIBUTION_STORAGE_KEY = "gloomberb.web.attribution";
 const ANONYMOUS_ID_STORAGE_KEY = "gloomberb.web.anonymous-id";
@@ -38,8 +47,8 @@ const ATTRIBUTION_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
 /** Another device's clock may run slightly ahead; a touch from a minute in the future is still fresh. */
 const CLOCK_SKEW_MS = 5 * 60 * 1000;
 const ANONYMOUS_ID = /^[a-f0-9-]{36}$/;
-/** The server accepts a tab id only in this shape. */
-const RESEARCH_TAB_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+/** The server accepts a tab id or an upgrade placement only in this shape. */
+const ACTIVITY_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const CAMPAIGN_KEYS = [
   "utm_source",
   "utm_medium",
@@ -310,29 +319,67 @@ export function observeDesktopDeepLinks(
 /** What the server stores against the account: stored touches plus the product marker. */
 function attributionPayload(): Record<string, string> | undefined {
   const target = getCurrentPluginTarget();
-  if (target === "web") return { product: "gloomberb", ...attribution };
-  if (target === "desktop" && Object.keys(attribution).length > 0) return { product: "gloomberb", ...attribution };
-  return undefined;
+  const context = wallExperimentContext();
+  const wallVariant = wallExperiment.variant(context);
+  // Keep an already-exposed visitor attributable after signup without enrolling
+  // the account or accepting a stored arm from an earlier session.
+  const signinVariant = signinWallExperiment.variant({ ...context, accountId: undefined, pro: false });
+  const base = target === "web"
+    ? { product: "gloomberb", ...attribution, ...webExperimentAttribution() }
+    : target === "desktop" && Object.keys(attribution).length > 0
+      ? { product: "gloomberb", ...attribution }
+      : undefined;
+  // A remembered browser arm is sent with the exposure request, but joins
+  // milestones only after this session has an accepted answer. Other live
+  // experiments keep their existing attribution unchanged.
+  const experiments = (base?.experiments ?? "").split(",").filter((part) => part && !part.startsWith("wall_teaser:") && !part.startsWith("wall_teaser_signin:"));
+  if (wallVariant) experiments.push(`wall_teaser:${wallVariant}`);
+  if (signinVariant) experiments.push(`wall_teaser_signin:${signinVariant}`);
+  if (!base && experiments.length === 0) return undefined;
+  const next: Record<string, string> = { ...base };
+  delete next.experiments;
+  if (experiments.length > 0) next.experiments = experiments.join(",");
+  return next;
+}
+
+export interface ResearchActivityDetails {
+  /** The desks picked at "What do you trade?", on the milestone that ends the first run. */
+  desks?: readonly string[];
+  /**
+   * Which prompt raised an `upgrade_intent` (a pane footer, a wall, the
+   * command bar), as a short id like a tab id. Never the prompt's text.
+   */
+  placement?: string;
+  /** Only ids describing what a teaser-arm wall rendered, never its content. */
+  teaser_kind?: "summary" | "sample" | "none";
+  /** The sign-in wall action, never the button copy. */
+  cta?: "login" | "signup";
 }
 
 /**
- * Counts milestones once per feature/session/account, never their content.
- * Native surfaces report anonymously only with an identifier the website
- * handed over; they still never mint one of their own. `desks` rides on the
- * end of the first-run funnel: the desks picked at "What do you trade?".
+ * Counts milestones once per feature/tab/placement, session and account, never
+ * their content. Wall views require an account or an identified web visitor;
+ * other native milestones can retain an identifier handed over by the website.
  */
 export function recordResearchActivity(
   event: ResearchActivity,
   feature?: ResearchFeature,
   tab?: string,
-  desks?: readonly string[],
+  { desks, placement: rawPlacement, teaser_kind, cta }: ResearchActivityDetails = {},
 ): void {
   const target = getCurrentPluginTarget();
   const user = apiClient.getCurrentUser();
+  const wallEvent = event === "wall_viewed" || event === "wall_cta_clicked";
+  if (wallEvent && (wallPrivacyBlocked() || (!user && target !== "web"))) return;
   if (!user && !anonymousId) return;
   if (!user && target !== "web" && target !== "desktop") return;
-  const key = `${user?.id ?? "guest"}:${event}:${feature ?? ""}:${tab ?? ""}`;
-  if (sent.has(key)) return;
+  // The server refuses the whole event over a malformed id, so one is dropped instead.
+  const placement = rawPlacement && ACTIVITY_ID.test(rawPlacement) ? rawPlacement : undefined;
+  if (wallEvent && !placement) return;
+  if (event === "wall_cta_clicked" && cta !== "login" && cta !== "signup") return;
+  const identity = user?.id ?? (wallEvent ? anonymousId : "guest");
+  const key = `${identity}:${event}:${feature ?? ""}:${tab ?? ""}:${placement ?? ""}${event === "wall_cta_clicked" ? `:${cta}` : ""}`;
+  if (sent.has(key) || (wallEvent && wallSessionViews().has(key))) return;
   sent.add(key);
   if (event !== "workspace_opened") recordResearchActivity("workspace_opened");
   void apiClient
@@ -345,6 +392,15 @@ export function recordResearchActivity(
       feature,
       tab,
       desks,
+      placement,
+      ...(event === "wall_viewed" && teaser_kind ? { teaser_kind } : {}),
+      ...(event === "wall_cta_clicked" ? { cta } : {}),
+    })
+    .then(() => {
+      if (!wallEvent) return;
+      const views = wallSessionViews();
+      views.add(key);
+      try { sessionStorage.setItem(WALL_VIEWS_SESSION_KEY, JSON.stringify([...views])); } catch { /* Native sessions use the in-memory set. */ }
     })
     .catch(() => {
       sent.delete(key);
@@ -357,7 +413,7 @@ export function recordResearchActivity(
  * someone installed stay private; so is any id the server would refuse.
  */
 export function recordResearchTabView(tabId: string, fromExternalPlugin: boolean): void {
-  const tab = !fromExternalPlugin && RESEARCH_TAB_ID.test(tabId) ? tabId : "plugin";
+  const tab = !fromExternalPlugin && ACTIVITY_ID.test(tabId) ? tabId : "plugin";
   recordResearchActivity("research_tab_viewed", undefined, tab);
 }
 
@@ -375,6 +431,109 @@ export function identifyResearchUser(): void {
   }
 }
 
+/** The arms this browser was given, so each milestone carries them as `exp_<key>`. */
+function webExperimentAttribution(): { experiments?: string } {
+  if (!anonymousId) return {};
+  try {
+    const experiments = storedExperimentAssignments(localStorage);
+    return experiments ? { experiments } : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The arm of a web terminal experiment to show, asked for at the moment it
+ * would show and counted then, in every arm; null shows nothing. Only signed-out
+ * visitors on term.gloom.sh with an analytics id (no Do Not Track or Global
+ * Privacy Control) and not driven by automation are asked. See web-experiments.ts.
+ */
+export function exposeWebExperiment(experiment: string): Promise<string | null> {
+  if (getCurrentPluginTarget() !== "web") return Promise.resolve(null);
+  try {
+    return exposeExperiment(experiment, {
+      anonymousId,
+      signedIn: !!apiClient.getCurrentUser(),
+      automated: navigator.webdriver === true,
+      local: localStorage,
+      session: sessionStorage,
+      ask: ({ experiment: key, variant }) => apiClient.recordExperimentExposure({
+        eventId: crypto.randomUUID(),
+        surface: "web",
+        anonymousId,
+        attribution: attributionPayload(),
+        experiment: key,
+        variant,
+      }),
+    });
+  } catch {
+    return Promise.resolve(null);
+  }
+}
+
+function wallPrivacyBlocked(): boolean {
+  if (typeof navigator === "undefined") return false;
+  return navigator.doNotTrack === "1"
+    || (navigator as Navigator & { globalPrivacyControl?: boolean }).globalPrivacyControl === true
+    || navigator.webdriver === true;
+}
+
+function wallExperimentContext(): WallExperimentContext {
+  const user = apiClient.getCurrentUser();
+  const surface = getCurrentPluginTarget();
+  let local: StorageLike | undefined;
+  let session: StorageLike | undefined;
+  try {
+    if (surface === "web") local = localStorage;
+    if (surface === "web" || surface === "desktop") session = sessionStorage;
+  } catch { /* Native and private sessions keep their answer in memory. */ }
+  return {
+    surface,
+    accountId: user?.id,
+    pro: hasProAccess(user),
+    anonymousId,
+    optedOut: wallPrivacyBlocked(),
+    automated: typeof navigator !== "undefined" && navigator.webdriver === true,
+    local,
+    session,
+  };
+}
+
+function wallSessionViews(): Set<string> {
+  try {
+    const saved: unknown = JSON.parse(sessionStorage.getItem(WALL_VIEWS_SESSION_KEY) ?? "[]");
+    if (Array.isArray(saved)) return new Set(saved.filter((value): value is string => typeof value === "string"));
+  } catch { /* Native sessions use the in-memory set. */ }
+  return new Set();
+}
+
+/** A wall's first render asks once per eligible account or web visitor per session. */
+export function exposeWallTeaser(experiment: WallExperiment = "wall_teaser"): Promise<WallTeaserVariant | null> {
+  const context = wallExperimentContext();
+  const session = experiment === "wall_teaser_signin" ? signinWallExperiment : wallExperiment;
+  return session.expose(context, (variant) => {
+    const controller = new AbortController();
+    return withDeadline(apiClient.recordExperimentExposure({
+      eventId: crypto.randomUUID(),
+      surface: context.surface,
+      anonymousId: context.surface === "web" ? anonymousId : undefined,
+      attribution: attributionPayload(),
+      experiment,
+      variant,
+    }, controller.signal), 3_000, "Wall experiment request timed out", (error) => controller.abort(error));
+  });
+}
+
+/** Records the visible wall once per placement, including visitors outside the experiment. */
+export function recordWallViewed(placement: string, teaserKind?: "summary" | "sample" | "none"): void {
+  recordResearchActivity("wall_viewed", undefined, undefined, { placement, teaser_kind: teaserKind });
+}
+
+/** Counts each sign-in action once per eligible placement and session. */
+export function recordWallCtaClicked(placement: string, cta: "login" | "signup"): void {
+  recordResearchActivity("wall_cta_clicked", undefined, undefined, { placement, cta });
+}
+
 export function researchUpgradeUrl(returnTo?: string): string {
   const url = new URL("https://gloom.sh/cloud?upgrade=pro");
   if (returnTo) url.searchParams.set("returnTo", returnTo);