gloomberb 0.4.0 → 0.5.0

package/src/plugins/builtin/econ/fred-client.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { resolveFredMapping, getFredSeriesId, getRelatedTickers } from "./fred-series-map";
+
+describe("resolveFredMapping", () => {
+  test("maps exact US event titles", () => {
+    const m = resolveFredMapping("CPI m/m", "US");
+    expect(m).not.toBeNull();
+    expect(m!.seriesId).toBe("CPIAUCSL");
+    expect(m!.relatedTickers).toContain("TIP");
+  });
+
+  test("case insensitive matching", () => {
+    expect(resolveFredMapping("cpi m/m", "US")?.seriesId).toBe("CPIAUCSL");
+    expect(resolveFredMapping("CPI M/M", "US")?.seriesId).toBe("CPIAUCSL");
+  });
+
+  test("strips prefixes for fuzzy match", () => {
+    expect(resolveFredMapping("Final GDP q/q", "US")?.seriesId).toBe("GDP");
+    expect(resolveFredMapping("Prelim GDP q/q", "US")?.seriesId).toBe("GDP");
+    expect(resolveFredMapping("Advance GDP q/q", "US")?.seriesId).toBe("GDP");
+  });
+
+  test("returns null for non-US events", () => {
+    expect(resolveFredMapping("CPI m/m", "EU")).toBeNull();
+    expect(resolveFredMapping("CPI m/m", "GB")).toBeNull();
+  });
+
+  test("returns null for unmapped events", () => {
+    expect(resolveFredMapping("President Trump Speaks", "US")).toBeNull();
+    expect(resolveFredMapping("Bank Holiday", "US")).toBeNull();
+  });
+
+  test("maps FOMC and Fed events", () => {
+    expect(resolveFredMapping("Federal Funds Rate", "US")?.seriesId).toBe("FEDFUNDS");
+  });
+
+  test("maps commodity indicators", () => {
+    expect(resolveFredMapping("Crude Oil Inventories", "US")?.seriesId).toBe("WCOILWTICO");
+    expect(resolveFredMapping("Natural Gas Storage", "US")?.seriesId).toBe("NATURALGAS");
+  });
+});
+
+describe("getFredSeriesId", () => {
+  test("returns series ID for known events", () => {
+    expect(getFredSeriesId("Unemployment Rate", "US")).toBe("UNRATE");
+  });
+
+  test("returns null for unknown events", () => {
+    expect(getFredSeriesId("Some Random Event", "US")).toBeNull();
+  });
+});
+
+describe("getRelatedTickers", () => {
+  test("returns related tickers for known events", () => {
+    const tickers = getRelatedTickers("CPI m/m", "US");
+    expect(tickers).toContain("TIP");
+    expect(tickers).toContain("DX-Y.NYB");
+  });
+
+  test("returns empty array for unknown events", () => {
+    expect(getRelatedTickers("Unknown Event", "US")).toEqual([]);
+  });
+});

package/src/plugins/builtin/econ/fred-client.ts

@@ -0,0 +1,79 @@
+import { createThrottledFetch, type ThrottledFetchClient } from "../../../utils/throttled-fetch";
+
+const FRED_BASE = "https://api.stlouisfed.org/fred";
+
+// FRED free tier: 120 requests per minute, but be conservative
+const fredFetch = createThrottledFetch({
+  requestsPerMinute: 30,
+  maxRetries: 2,
+  timeoutMs: 15_000,
+});
+
+export interface FredObservation {
+  date: string;       // "2024-01-01"
+  value: number | null; // null for missing/revised data
+}
+
+export interface FredSeriesInfo {
+  id: string;
+  title: string;
+  units: string;
+  frequency: string;
+  seasonalAdjustment: string;
+  source: string;
+  notes: string;
+}
+
+export async function fetchFredObservations(
+  apiKey: string,
+  seriesId: string,
+  options?: { startDate?: string; endDate?: string; limit?: number; sortOrder?: "asc" | "desc" },
+): Promise<FredObservation[]> {
+  const params = new URLSearchParams({
+    series_id: seriesId,
+    api_key: apiKey,
+    file_type: "json",
+    sort_order: options?.sortOrder ?? "desc",
+  });
+  if (options?.startDate) params.set("observation_start", options.startDate);
+  if (options?.endDate) params.set("observation_end", options.endDate);
+  if (options?.limit) params.set("limit", String(options.limit));
+
+  const url = `${FRED_BASE}/series/observations?${params}`;
+  const data = await fredFetch.fetchJson<any>(url);
+
+  if (!Array.isArray(data?.observations)) return [];
+
+  return data.observations
+    .map((obs: any) => ({
+      date: obs.date,
+      value: obs.value === "." ? null : parseFloat(obs.value),
+    }))
+    .filter((obs: FredObservation) => obs.value !== null && !isNaN(obs.value as number));
+}
+
+export async function fetchFredSeriesInfo(
+  apiKey: string,
+  seriesId: string,
+): Promise<FredSeriesInfo | null> {
+  const params = new URLSearchParams({
+    series_id: seriesId,
+    api_key: apiKey,
+    file_type: "json",
+  });
+  const url = `${FRED_BASE}/series?${params}`;
+  const data = await fredFetch.fetchJson<any>(url);
+
+  const series = data?.seriess?.[0];
+  if (!series) return null;
+
+  return {
+    id: series.id,
+    title: series.title ?? seriesId,
+    units: series.units ?? "",
+    frequency: series.frequency ?? "",
+    seasonalAdjustment: series.seasonal_adjustment ?? "",
+    source: "", // FRED doesn't include source in this endpoint
+    notes: series.notes ?? "",
+  };
+}

package/src/plugins/builtin/econ/fred-series-map.ts

@@ -0,0 +1,88 @@
+interface FredMapping {
+  seriesId: string;
+  /** How to display the value: "level" shows the raw number, "change" shows month-over-month or quarter-over-quarter percent change */
+  displayMode: "level" | "change";
+  relatedTickers: string[];
+}
+
+// Normalized event title → FRED mapping
+const SERIES_MAP: Record<string, FredMapping> = {
+  "cpi m/m": { seriesId: "CPIAUCSL", displayMode: "change", relatedTickers: ["TIP", "DX-Y.NYB", "^TNX"] },
+  "core cpi m/m": { seriesId: "CPILFESL", displayMode: "change", relatedTickers: ["TIP", "DX-Y.NYB", "^TNX"] },
+  "cpi y/y": { seriesId: "CPIAUCSL", displayMode: "level", relatedTickers: ["TIP", "DX-Y.NYB"] },
+  "core cpi y/y": { seriesId: "CPILFESL", displayMode: "level", relatedTickers: ["TIP", "DX-Y.NYB"] },
+  "ppi m/m": { seriesId: "PPIACO", displayMode: "change", relatedTickers: ["DX-Y.NYB"] },
+  "core pce price index m/m": { seriesId: "PCEPILFE", displayMode: "change", relatedTickers: ["TIP", "DX-Y.NYB", "^TNX"] },
+  "pce price index m/m": { seriesId: "PCEPI", displayMode: "change", relatedTickers: ["TIP", "DX-Y.NYB"] },
+  "final gdp q/q": { seriesId: "GDP", displayMode: "change", relatedTickers: ["SPY", "DX-Y.NYB"] },
+  "advance gdp q/q": { seriesId: "GDP", displayMode: "change", relatedTickers: ["SPY", "DX-Y.NYB"] },
+  "prelim gdp q/q": { seriesId: "GDP", displayMode: "change", relatedTickers: ["SPY", "DX-Y.NYB"] },
+  "gdp q/q": { seriesId: "GDP", displayMode: "change", relatedTickers: ["SPY", "DX-Y.NYB"] },
+  "unemployment rate": { seriesId: "UNRATE", displayMode: "level", relatedTickers: ["SPY", "DX-Y.NYB"] },
+  "unemployment claims": { seriesId: "ICSA", displayMode: "level", relatedTickers: ["SPY"] },
+  "non-farm employment change": { seriesId: "PAYEMS", displayMode: "change", relatedTickers: ["SPY", "DX-Y.NYB", "^TNX"] },
+  "adp non-farm employment change": { seriesId: "NPPTTL", displayMode: "change", relatedTickers: ["SPY"] },
+  "retail sales m/m": { seriesId: "RSAFS", displayMode: "change", relatedTickers: ["XRT", "SPY"] },
+  "core retail sales m/m": { seriesId: "RSFSXMV", displayMode: "change", relatedTickers: ["XRT", "SPY"] },
+  "ism manufacturing pmi": { seriesId: "NAPM", displayMode: "level", relatedTickers: ["SPY", "XLI"] },
+  "consumer confidence": { seriesId: "UMCSENT", displayMode: "level", relatedTickers: ["SPY"] },
+  "prelim uom consumer sentiment": { seriesId: "UMCSENT", displayMode: "level", relatedTickers: ["SPY"] },
+  "revised uom consumer sentiment": { seriesId: "UMCSENT", displayMode: "level", relatedTickers: ["SPY"] },
+  "cb consumer confidence": { seriesId: "CSCICP03USM665S", displayMode: "level", relatedTickers: ["SPY"] },
+  "federal funds rate": { seriesId: "FEDFUNDS", displayMode: "level", relatedTickers: ["^TNX", "TLT", "DX-Y.NYB"] },
+  "crude oil inventories": { seriesId: "WCOILWTICO", displayMode: "level", relatedTickers: ["CL=F", "USO"] },
+  "natural gas storage": { seriesId: "NATURALGAS", displayMode: "level", relatedTickers: ["NG=F", "UNG"] },
+  "housing starts": { seriesId: "HOUST", displayMode: "level", relatedTickers: ["XHB", "ITB"] },
+  "building permits": { seriesId: "PERMIT", displayMode: "level", relatedTickers: ["XHB", "ITB"] },
+  "existing home sales": { seriesId: "EXHOSLUSM495S", displayMode: "level", relatedTickers: ["XHB"] },
+  "new home sales": { seriesId: "HSN1F", displayMode: "level", relatedTickers: ["XHB", "ITB"] },
+  "durable goods orders m/m": { seriesId: "DGORDER", displayMode: "change", relatedTickers: ["XLI", "SPY"] },
+  "core durable goods orders m/m": { seriesId: "ADXTNO", displayMode: "change", relatedTickers: ["XLI"] },
+  "factory orders m/m": { seriesId: "AMTMNO", displayMode: "change", relatedTickers: ["XLI"] },
+  "trade balance": { seriesId: "BOPGSTB", displayMode: "level", relatedTickers: ["DX-Y.NYB"] },
+  "industrial production m/m": { seriesId: "INDPRO", displayMode: "change", relatedTickers: ["XLI", "SPY"] },
+  "capacity utilization rate": { seriesId: "TCU", displayMode: "level", relatedTickers: ["XLI"] },
+  "personal income m/m": { seriesId: "PI", displayMode: "change", relatedTickers: ["SPY"] },
+  "personal spending m/m": { seriesId: "PCE", displayMode: "change", relatedTickers: ["XRT", "SPY"] },
+  "current account": { seriesId: "NETFI", displayMode: "level", relatedTickers: ["DX-Y.NYB"] },
+  "import prices m/m": { seriesId: "IR", displayMode: "change", relatedTickers: ["DX-Y.NYB"] },
+  "export prices m/m": { seriesId: "IQ", displayMode: "change", relatedTickers: ["DX-Y.NYB"] },
+  "jolts job openings": { seriesId: "JTSJOL", displayMode: "level", relatedTickers: ["SPY"] },
+  "nonfarm productivity q/q": { seriesId: "OPHNFB", displayMode: "change", relatedTickers: ["SPY"] },
+  "unit labor costs q/q": { seriesId: "ULCNFB", displayMode: "change", relatedTickers: ["SPY", "^TNX"] },
+};
+
+function normalizeEventTitle(title: string): string {
+  return title.toLowerCase().trim();
+}
+
+export function resolveFredMapping(eventTitle: string, country: string): FredMapping | null {
+  // Only US events have FRED data
+  if (country !== "US" && country !== "USD") return null;
+
+  const normalized = normalizeEventTitle(eventTitle);
+
+  // Direct match
+  if (SERIES_MAP[normalized]) return SERIES_MAP[normalized];
+
+  // Fuzzy: try removing common prefixes
+  for (const prefix of ["final ", "prelim ", "revised ", "flash ", "advance "]) {
+    const stripped = normalized.startsWith(prefix) ? normalized.slice(prefix.length) : null;
+    if (stripped && SERIES_MAP[stripped]) return SERIES_MAP[stripped];
+  }
+
+  // Fuzzy: try partial match on key words
+  for (const [key, mapping] of Object.entries(SERIES_MAP)) {
+    if (normalized.includes(key) || key.includes(normalized)) return mapping;
+  }
+
+  return null;
+}
+
+export function getRelatedTickers(eventTitle: string, country: string): string[] {
+  return resolveFredMapping(eventTitle, country)?.relatedTickers ?? [];
+}
+
+export function getFredSeriesId(eventTitle: string, country: string): string | null {
+  return resolveFredMapping(eventTitle, country)?.seriesId ?? null;
+}