gloomberb 0.4.0 → 0.5.0

package/src/plugins/builtin/earnings/index.tsx

@@ -0,0 +1,337 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { TextAttributes, type ScrollBoxRenderable } from "@opentui/core";
+import { useKeyboard } from "@opentui/react";
+import { DataTable, type DataTableCell, type DataTableColumn } from "../../../components";
+import type { GloomPlugin, PaneProps } from "../../../types/plugin";
+import type { EarningsEvent } from "../../../types/data-provider";
+import { colors } from "../../../theme/colors";
+import { getSharedDataProvider } from "../../registry";
+import { useAppSelector, getFocusedCollectionId } from "../../../state/app-context";
+import { getCollectionTickers } from "../../../state/selectors";
+import { formatCompact } from "../../../utils/format";
+import { usePluginPaneState, usePluginTickerActions } from "../../plugin-runtime";
+import {
+  attachEarningsCalendarPersistence,
+  loadEarningsCalendar,
+  resetEarningsCalendarPersistence,
+} from "./earnings-cache";
+
+type DisplayRow =
+  | { kind: "separator"; key: string; label: string }
+  | { kind: "event"; key: string; event: EarningsEvent; eventIdx: number };
+
+type EarningsColumnId = "date" | "symbol" | "name" | "epsEstimate" | "revenueEstimate";
+type EarningsColumn = DataTableColumn & { id: EarningsColumnId };
+
+function groupByRelativeDate(events: EarningsEvent[]): DisplayRow[] {
+  const now = new Date();
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const tomorrow = new Date(today);
+  tomorrow.setDate(tomorrow.getDate() + 1);
+  const dayAfterTomorrow = new Date(today);
+  dayAfterTomorrow.setDate(dayAfterTomorrow.getDate() + 2);
+
+  const endOfWeek = new Date(today);
+  endOfWeek.setDate(endOfWeek.getDate() + (7 - endOfWeek.getDay()));
+  const endOfNextWeek = new Date(endOfWeek);
+  endOfNextWeek.setDate(endOfNextWeek.getDate() + 7);
+
+  const groups: { label: string; events: EarningsEvent[] }[] = [
+    { label: "TODAY", events: [] },
+    { label: "TOMORROW", events: [] },
+    { label: "THIS WEEK", events: [] },
+    { label: "NEXT WEEK", events: [] },
+    { label: "LATER", events: [] },
+  ];
+
+  for (const event of events) {
+    const date = event.earningsDate;
+    if (date >= today && date < tomorrow) {
+      groups[0]!.events.push(event);
+    } else if (date >= tomorrow && date < dayAfterTomorrow) {
+      groups[1]!.events.push(event);
+    } else if (date >= dayAfterTomorrow && date < endOfWeek) {
+      groups[2]!.events.push(event);
+    } else if (date >= endOfWeek && date < endOfNextWeek) {
+      groups[3]!.events.push(event);
+    } else if (date >= endOfNextWeek) {
+      groups[4]!.events.push(event);
+    }
+  }
+
+  const rows: DisplayRow[] = [];
+  let eventIdx = 0;
+  for (const group of groups) {
+    if (group.events.length === 0) continue;
+    rows.push({ kind: "separator", key: `sep-${group.label}`, label: `${group.label} (${group.events.length})` });
+    for (const event of group.events) {
+      rows.push({
+        kind: "event",
+        key: `event-${event.symbol}-${event.earningsDate.getTime()}-${eventIdx}`,
+        event,
+        eventIdx,
+      });
+      eventIdx++;
+    }
+  }
+  return rows;
+}
+
+const MONTH_NAMES = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+function formatDate(date: Date): string {
+  return `${MONTH_NAMES[date.getMonth()]} ${date.getDate()}`;
+}
+
+function buildColumns(width: number): EarningsColumn[] {
+  const dateWidth = 8;
+  const symbolWidth = 8;
+  const epsWidth = 10;
+  const revenueWidth = 10;
+  const columnCount = 5;
+  const fixedWidth = dateWidth + symbolWidth + epsWidth + revenueWidth;
+  const nameWidth = Math.max(12, width - 2 - columnCount - fixedWidth);
+
+  return [
+    { id: "date", label: "DATE", width: dateWidth, align: "left" },
+    { id: "symbol", label: "TICKER", width: symbolWidth, align: "left" },
+    { id: "name", label: "NAME", width: nameWidth, align: "left" },
+    { id: "epsEstimate", label: "EPS EST", width: epsWidth, align: "right" },
+    { id: "revenueEstimate", label: "REV EST", width: revenueWidth, align: "right" },
+  ];
+}
+
+function EarningsCalendarPane({ focused, width, height }: PaneProps) {
+  const { navigateTicker } = usePluginTickerActions();
+  const [events, setEvents] = useState<EarningsEvent[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [selectedIdx, setSelectedIdx] = usePluginPaneState<number>("selectedIdx", 0);
+  const [hoveredIdx, setHoveredIdx] = useState<number | null>(null);
+  const scrollRef = useRef<ScrollBoxRenderable>(null);
+  const headerScrollRef = useRef<ScrollBoxRenderable>(null);
+
+  const state = useAppSelector((current) => current);
+  const collectionId = getFocusedCollectionId(state);
+  const tickerSymbols = useMemo(() => {
+    if (collectionId) {
+      return getCollectionTickers(state, collectionId).map((ticker) => ticker.metadata.ticker);
+    }
+    return [...state.tickers.values()].map((ticker) => ticker.metadata.ticker);
+  }, [state.tickers, collectionId]);
+
+  const rows = useMemo(() => groupByRelativeDate(events), [events]);
+  const eventRows = useMemo(
+    () => rows.filter((row): row is DisplayRow & { kind: "event" } => row.kind === "event"),
+    [rows],
+  );
+  const eventCount = eventRows.length;
+  const activeEventIdx = eventCount > 0 ? Math.min(Math.max(selectedIdx, 0), eventCount - 1) : -1;
+  const selectedRowIndex = rows.findIndex((row) => row.kind === "event" && row.eventIdx === activeEventIdx);
+  const columns = useMemo(() => buildColumns(width), [width]);
+
+  const syncHeaderScroll = useCallback(() => {
+    const bodyScrollBox = scrollRef.current;
+    const headerScrollBox = headerScrollRef.current;
+    if (bodyScrollBox && headerScrollBox && headerScrollBox.scrollLeft !== bodyScrollBox.scrollLeft) {
+      headerScrollBox.scrollLeft = bodyScrollBox.scrollLeft;
+    }
+  }, []);
+
+  const handleBodyScrollActivity = useCallback(() => {
+    syncHeaderScroll();
+  }, [syncHeaderScroll]);
+
+  const reload = useCallback((force = false) => {
+    if (tickerSymbols.length === 0) {
+      setEvents([]);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+
+    const provider = getSharedDataProvider();
+    setLoading(true);
+    setError(null);
+    loadEarningsCalendar(provider, tickerSymbols, { force })
+      .then((data) => {
+        setEvents(data);
+      })
+      .catch((err) => {
+        setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        setLoading(false);
+      });
+  }, [tickerSymbols]);
+
+  useEffect(() => {
+    reload(false);
+  }, [reload]);
+
+  useEffect(() => {
+    if (eventCount > 0 && selectedIdx >= eventCount) {
+      setSelectedIdx(eventCount - 1);
+    }
+  }, [eventCount, selectedIdx, setSelectedIdx]);
+
+  useEffect(() => {
+    const scrollBox = scrollRef.current;
+    if (!scrollBox || selectedRowIndex < 0) return;
+    scrollBox.scrollTo?.(0, Math.max(0, selectedRowIndex - Math.floor((height - 3) / 2)));
+  }, [height, selectedRowIndex]);
+
+  const openEvent = useCallback((event: EarningsEvent) => {
+    navigateTicker(event.symbol);
+  }, [navigateTicker]);
+
+  const selectEventIndex = useCallback((index: number) => {
+    if (eventCount === 0) return;
+    setSelectedIdx(Math.min(Math.max(index, 0), eventCount - 1));
+  }, [eventCount, setSelectedIdx]);
+
+  useKeyboard((event) => {
+    if (!focused) return;
+    if (event.name === "j" || event.name === "down") {
+      selectEventIndex(activeEventIdx + 1);
+    } else if (event.name === "k" || event.name === "up") {
+      selectEventIndex(activeEventIdx - 1);
+    } else if (event.name === "return" || event.name === "enter") {
+      const selected = eventRows[activeEventIdx];
+      if (selected) openEvent(selected.event);
+    } else if (event.name === "r") {
+      reload(true);
+    }
+  });
+
+  const selectDisplayRow = useCallback((row: DisplayRow) => {
+    if (row.kind !== "event") return;
+    if (row.eventIdx === activeEventIdx) {
+      openEvent(row.event);
+      return;
+    }
+    setSelectedIdx(row.eventIdx);
+  }, [activeEventIdx, openEvent, setSelectedIdx]);
+
+  const renderSectionHeader = useCallback((row: DisplayRow) => {
+    if (row.kind !== "separator") return null;
+    return {
+      text: row.label,
+      color: colors.textBright,
+      attributes: TextAttributes.BOLD,
+    };
+  }, []);
+
+  const renderCell = useCallback((
+    row: DisplayRow,
+    column: EarningsColumn,
+    _index: number,
+    rowState: { selected: boolean },
+  ): DataTableCell => {
+    if (row.kind !== "event") return { text: "" };
+
+    const selectedColor = rowState.selected ? colors.selectedText : undefined;
+    switch (column.id) {
+      case "date":
+        return { text: formatDate(row.event.earningsDate), color: selectedColor ?? colors.textDim };
+      case "symbol":
+        return {
+          text: row.event.symbol,
+          color: selectedColor ?? colors.text,
+          attributes: TextAttributes.BOLD,
+        };
+      case "name":
+        return { text: row.event.name, color: selectedColor ?? colors.text };
+      case "epsEstimate":
+        return {
+          text: row.event.epsEstimate != null ? row.event.epsEstimate.toFixed(2) : "—",
+          color: selectedColor ?? colors.textDim,
+        };
+      case "revenueEstimate":
+        return {
+          text: row.event.revenueEstimate != null ? formatCompact(row.event.revenueEstimate) : "—",
+          color: selectedColor ?? colors.textDim,
+        };
+    }
+  }, []);
+
+  return (
+    <box flexDirection="column" width={width} height={height}>
+      <box height={1} paddingX={1} flexDirection="row">
+        <text fg={colors.textDim}>
+          {loading ? "loading..." : `${eventCount} upcoming`}
+        </text>
+      </box>
+
+      {error ? (
+        <box paddingX={1}>
+          <text fg={colors.negative}>{error}</text>
+        </box>
+      ) : null}
+
+      <DataTable<DisplayRow, EarningsColumn>
+        columns={columns}
+        items={rows}
+        sortColumnId={null}
+        sortDirection="asc"
+        onHeaderClick={() => {}}
+        headerScrollRef={headerScrollRef}
+        scrollRef={scrollRef}
+        syncHeaderScroll={syncHeaderScroll}
+        onBodyScrollActivity={handleBodyScrollActivity}
+        hoveredIdx={hoveredIdx}
+        setHoveredIdx={setHoveredIdx}
+        getItemKey={(row) => row.key}
+        isSelected={(row) => row.kind === "event" && row.eventIdx === activeEventIdx}
+        onSelect={selectDisplayRow}
+        renderSectionHeader={renderSectionHeader}
+        renderCell={renderCell}
+        emptyStateTitle={loading ? "Loading earnings..." : "No upcoming earnings found"}
+        showHorizontalScrollbar={false}
+      />
+
+      <box height={1} paddingX={1}>
+        <text fg={colors.textMuted}>[r]efresh</text>
+      </box>
+    </box>
+  );
+}
+
+export const earningsPlugin: GloomPlugin = {
+  id: "earnings-calendar",
+  name: "Earnings Calendar",
+  version: "1.0.0",
+  description: "Upcoming earnings dates for tracked tickers",
+  toggleable: true,
+
+  setup(ctx) {
+    attachEarningsCalendarPersistence(ctx.persistence);
+  },
+
+  dispose() {
+    resetEarningsCalendarPersistence();
+  },
+
+  panes: [
+    {
+      id: "earnings-calendar",
+      name: "Earnings Calendar",
+      icon: "$",
+      component: EarningsCalendarPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 85, height: 25 },
+    },
+  ],
+
+  paneTemplates: [
+    {
+      id: "earnings-calendar-pane",
+      paneId: "earnings-calendar",
+      label: "Earnings Calendar",
+      description: "Upcoming earnings dates and estimates for your tickers.",
+      keywords: ["earn", "earnings", "calendar", "eps", "revenue", "quarterly"],
+      shortcut: { prefix: "ERN" },
+    },
+  ],
+};

package/src/plugins/builtin/econ/calendar-source.test.ts

@@ -0,0 +1,219 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { PersistedResourceValue } from "../../../types/persistence";
+import type { PluginPersistence } from "../../../types/plugin";
+import {
+  attachEconCalendarPersistence,
+  ECON_CALENDAR_CACHE_POLICY,
+  fetchEconCalendar,
+  parseCalendarJson,
+  resetEconCalendarPersistence,
+} from "./calendar-source";
+
+const SAMPLE_DATA = [
+  {
+    title: "CPI m/m",
+    country: "USD",
+    date: "2026-04-10T08:30:00-04:00",
+    impact: "High",
+    forecast: "0.3%",
+    previous: "0.2%",
+  },
+  {
+    title: "ECB Rate Decision",
+    country: "EUR",
+    date: "2026-04-10T14:00:00-04:00",
+    impact: "Medium",
+    forecast: "4.50%",
+    previous: "4.50%",
+  },
+  {
+    title: "Bank Holiday",
+    country: "GBP",
+    date: "2026-04-10T03:00:00-04:00",
+    impact: "Holiday",
+    forecast: "",
+    previous: "",
+  },
+];
+
+const originalFetch = globalThis.fetch;
+
+class MemoryPluginPersistence implements PluginPersistence {
+  private readonly resources = new Map<string, PersistedResourceValue<unknown>>();
+  private readonly state = new Map<string, { schemaVersion: number; value: unknown }>();
+
+  getState<T = unknown>(key: string, options?: { schemaVersion?: number }): T | null {
+    const record = this.state.get(key);
+    if (!record) return null;
+    if (options?.schemaVersion != null && record.schemaVersion !== options.schemaVersion) return null;
+    return record.value as T;
+  }
+
+  setState(key: string, value: unknown, options?: { schemaVersion?: number }): void {
+    this.state.set(key, { schemaVersion: options?.schemaVersion ?? 1, value });
+  }
+
+  deleteState(key: string): void {
+    this.state.delete(key);
+  }
+
+  getResource<T = unknown>(
+    kind: string,
+    key: string,
+    options?: { sourceKey?: string; schemaVersion?: number; allowExpired?: boolean },
+  ): PersistedResourceValue<T> | null {
+    const record = this.resources.get(this.resourceKey(kind, key, options?.sourceKey));
+    if (!record) return null;
+    if (options?.schemaVersion != null && record.schemaVersion !== options.schemaVersion) return null;
+    const next = this.withFreshness(record);
+    if (!options?.allowExpired && next.expired) return null;
+    return next as PersistedResourceValue<T>;
+  }
+
+  setResource<T = unknown>(
+    kind: string,
+    key: string,
+    value: T,
+    options: {
+      cachePolicy: { staleMs: number; expireMs: number };
+      sourceKey?: string;
+      schemaVersion?: number;
+      provenance?: unknown;
+    },
+  ): PersistedResourceValue<T> {
+    const now = Date.now();
+    const record: PersistedResourceValue<T> = {
+      value,
+      fetchedAt: now,
+      staleAt: now + options.cachePolicy.staleMs,
+      expiresAt: now + options.cachePolicy.expireMs,
+      sourceKey: options.sourceKey ?? "",
+      schemaVersion: options.schemaVersion ?? 1,
+      provenance: options.provenance,
+      stale: false,
+      expired: false,
+    };
+    this.resources.set(this.resourceKey(kind, key, options.sourceKey), record);
+    return record;
+  }
+
+  deleteResource(kind: string, key: string, options?: { sourceKey?: string }): void {
+    this.resources.delete(this.resourceKey(kind, key, options?.sourceKey));
+  }
+
+  seedResource<T>(
+    kind: string,
+    key: string,
+    value: T,
+    options: { sourceKey?: string; stale?: boolean; expired?: boolean } = {},
+  ): void {
+    const now = Date.now();
+    const record: PersistedResourceValue<T> = {
+      value,
+      fetchedAt: now - 60_000,
+      staleAt: options.stale ? now - 1 : now + ECON_CALENDAR_CACHE_POLICY.staleMs,
+      expiresAt: options.expired ? now - 1 : now + ECON_CALENDAR_CACHE_POLICY.expireMs,
+      sourceKey: options.sourceKey ?? "",
+      schemaVersion: 1,
+      stale: !!options.stale,
+      expired: !!options.expired,
+    };
+    this.resources.set(this.resourceKey(kind, key, options.sourceKey), record);
+  }
+
+  private resourceKey(kind: string, key: string, sourceKey = ""): string {
+    return `${kind}:${key}:${sourceKey}`;
+  }
+
+  private withFreshness<T>(record: PersistedResourceValue<T>): PersistedResourceValue<T> {
+    const now = Date.now();
+    return {
+      ...record,
+      stale: now >= record.staleAt,
+      expired: now >= record.expiresAt,
+    };
+  }
+}
+
+afterEach(() => {
+  resetEconCalendarPersistence();
+  globalThis.fetch = originalFetch;
+});
+
+describe("parseCalendarJson", () => {
+  test("parses events from JSON, skips holidays", () => {
+    const events = parseCalendarJson(SAMPLE_DATA);
+    expect(events).toHaveLength(2);
+  });
+
+  test("maps fields correctly", () => {
+    const events = parseCalendarJson(SAMPLE_DATA);
+    const ev = events[0]!;
+    expect(ev.event).toBe("CPI m/m");
+    expect(ev.country).toBe("US");
+    expect(ev.impact).toBe("high");
+    expect(ev.forecast).toBe("0.3%");
+    expect(ev.prior).toBe("0.2%");
+    expect(ev.time).toMatch(/^\d{2}:\d{2}$/);
+  });
+
+  test("resolves EUR to EU country code", () => {
+    const events = parseCalendarJson(SAMPLE_DATA);
+    expect(events[1]!.country).toBe("EU");
+    expect(events[1]!.impact).toBe("medium");
+  });
+
+  test("returns empty forecast/prior as null", () => {
+    const events = parseCalendarJson([
+      { title: "Test", country: "USD", date: "2026-04-10T10:00:00-04:00", impact: "Low", forecast: "", previous: "" },
+    ]);
+    expect(events[0]!.forecast).toBeNull();
+    expect(events[0]!.prior).toBeNull();
+  });
+
+  test("returns [] for non-array input", () => {
+    expect(parseCalendarJson(null)).toEqual([]);
+    expect(parseCalendarJson({})).toEqual([]);
+    expect(parseCalendarJson("")).toEqual([]);
+  });
+});
+
+describe("fetchEconCalendar cache", () => {
+  test("uses a fresh plugin resource cache without fetching", async () => {
+    const persistence = new MemoryPluginPersistence();
+    attachEconCalendarPersistence(persistence);
+    persistence.setResource("calendar", "this-week", SAMPLE_DATA, {
+      sourceKey: "forexfactory",
+      cachePolicy: ECON_CALENDAR_CACHE_POLICY,
+    });
+    let fetchCalls = 0;
+    globalThis.fetch = (async () => {
+      fetchCalls += 1;
+      throw new Error("unexpected fetch");
+    }) as unknown as typeof fetch;
+
+    const events = await fetchEconCalendar();
+
+    expect(events).toHaveLength(2);
+    expect(fetchCalls).toBe(0);
+  });
+
+  test("falls back to stale plugin resource cache when refresh fails", async () => {
+    const persistence = new MemoryPluginPersistence();
+    attachEconCalendarPersistence(persistence);
+    persistence.seedResource("calendar", "this-week", SAMPLE_DATA, {
+      sourceKey: "forexfactory",
+      stale: true,
+    });
+    let fetchCalls = 0;
+    globalThis.fetch = (async () => {
+      fetchCalls += 1;
+      throw new Error("offline");
+    }) as unknown as typeof fetch;
+
+    const events = await fetchEconCalendar();
+
+    expect(events).toHaveLength(2);
+    expect(fetchCalls).toBe(1);
+  });
+});

package/src/plugins/builtin/econ/calendar-source.ts

@@ -0,0 +1,121 @@
+import type { PersistedResourceValue } from "../../../types/persistence";
+import type { PluginPersistence } from "../../../types/plugin";
+import { createThrottledFetch } from "../../../utils/throttled-fetch";
+import type { EconEvent, EconImpact } from "./types";
+
+const CALENDAR_URL = "https://nfs.faireconomy.media/ff_calendar_thisweek.json";
+const CACHE_KIND = "calendar";
+const CACHE_KEY = "this-week";
+const CACHE_SOURCE = "forexfactory";
+export const ECON_CALENDAR_CACHE_POLICY = {
+  staleMs: 30 * 60 * 1000,
+  expireMs: 7 * 24 * 60 * 60 * 1000,
+} as const;
+
+let econCalendarPersistence: PluginPersistence | null = null;
+
+const calendarClient = createThrottledFetch({
+  requestsPerMinute: 5,
+  maxRetries: 2,
+  timeoutMs: 15_000,
+  defaultHeaders: {
+    "User-Agent": "Gloomberb/0.4.1",
+    Accept: "application/json",
+  },
+});
+
+export function attachEconCalendarPersistence(persistence: PluginPersistence): void {
+  econCalendarPersistence = persistence;
+}
+
+export function resetEconCalendarPersistence(): void {
+  econCalendarPersistence = null;
+}
+
+function readCalendarCache(options?: {
+  allowExpired?: boolean;
+}): PersistedResourceValue<unknown> | null {
+  return econCalendarPersistence?.getResource<unknown>(CACHE_KIND, CACHE_KEY, {
+    sourceKey: CACHE_SOURCE,
+    allowExpired: options?.allowExpired,
+  }) ?? null;
+}
+
+function writeCalendarCache(data: unknown): void {
+  econCalendarPersistence?.setResource(CACHE_KIND, CACHE_KEY, data, {
+    sourceKey: CACHE_SOURCE,
+    cachePolicy: ECON_CALENDAR_CACHE_POLICY,
+  });
+}
+
+const CURRENCY_TO_COUNTRY: Record<string, string> = {
+  USD: "US", EUR: "EU", GBP: "GB", JPY: "JP", CAD: "CA",
+  AUD: "AU", CHF: "CH", CNY: "CN", NZD: "NZ", SEK: "SE",
+  All: "--",
+};
+
+function resolveCountry(currency: string): string {
+  return CURRENCY_TO_COUNTRY[currency] ?? currency.slice(0, 2);
+}
+
+function resolveImpact(raw: string): EconImpact {
+  const lower = raw.toLowerCase();
+  if (lower === "high") return "high";
+  if (lower === "medium") return "medium";
+  return "low";
+}
+
+interface RawCalendarEvent {
+  title: string;
+  country: string;
+  date: string;
+  impact: string;
+  forecast: string;
+  previous: string;
+}
+
+export function parseCalendarJson(data: unknown): EconEvent[] {
+  if (!Array.isArray(data)) return [];
+
+  return data
+    .filter((entry: any) => entry?.title && entry?.date)
+    .filter((entry: any) => entry.impact !== "Holiday")
+    .map((entry: any, idx: number): EconEvent => {
+      const raw = entry as RawCalendarEvent;
+      const date = new Date(raw.date);
+      const hours = date.getHours().toString().padStart(2, "0");
+      const minutes = date.getMinutes().toString().padStart(2, "0");
+      const time = `${hours}:${minutes}`;
+
+      return {
+        id: `ff-${idx}`,
+        date,
+        time,
+        country: resolveCountry(raw.country),
+        event: raw.title,
+        actual: null, // ForexFactory this-week feed doesn't include actuals
+        forecast: raw.forecast || null,
+        prior: raw.previous || null,
+        impact: resolveImpact(raw.impact),
+      };
+    });
+}
+
+export async function fetchEconCalendar(): Promise<EconEvent[]> {
+  const cached = readCalendarCache();
+  if (cached && !cached.stale) {
+    return parseCalendarJson(cached.value);
+  }
+
+  try {
+    const data = await calendarClient.fetchJson(CALENDAR_URL);
+    writeCalendarCache(data);
+    return parseCalendarJson(data);
+  } catch (err) {
+    const staleCache = cached ?? readCalendarCache({ allowExpired: true });
+    if (staleCache) {
+      return parseCalendarJson(staleCache.value);
+    }
+    throw err;
+  }
+}