Add PoE2 sidebar module: currency exchange watchlist

Tracks Path of Exile 2 currency values via poe.ninja's public economy
API, mirroring the existing Weather/Stocks sidebar modules. Always
follows the current challenge league (auto-detected, no admin picker).
Admin browses and picks currencies from a live list rather than typing
symbols, since currency ids are opaque. Change % is a 7-day window,
labeled accordingly to avoid the same interval ambiguity Stocks had.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014c1L8ghNBFjfiH64UMViP8

backend/src/api/admin.ts

@@ -5,6 +5,7 @@ import * as eventsDb from '../storage/db/events.js';
 import * as categoriesDb from '../storage/db/categories.js';
 import * as stocksDb from '../storage/db/stocks.js';
 import * as bookmarksDb from '../storage/db/bookmarks.js';
+import * as poe2WatchlistDb from '../storage/db/poe2Watchlist.js';
 import { clearSourceContent, reissueSourceContent, clearAllArticles, clearAllMedia } from '../storage/contentCascade.js';
 import { totalStorageBytes } from '../storage/media/index.js';
 import { OllamaProvider } from '../inference/ollama-provider.js';
@@ -14,6 +15,8 @@ import * as telegramClient from '../telegram/client.js';
 import { geocodeLocation } from '../weather/client.js';
 import { pollWeatherNow } from '../weather/poller.js';
 import { pollStocksNow } from '../stocks/poller.js';
+import { browseCurrencies, fetchCurrentLeague } from '../poe2/client.js';
+import { pollPoe2Now } from '../poe2/poller.js';
 
 // Not part of GlobalSettings itself (nothing to persist) — computed fresh on every
 // settings read/write so the Retention tab's "currently using" line and usage bar
@@ -276,6 +279,34 @@ export async function registerAdminRoutes(app: FastifyInstance) {
 		return reply.code(204).send();
 	});
 
+	// --- PoE2 (league is always auto-detected, never admin-set — see poe2/poller.ts) ---
+	app.get('/api/admin/poe2/browse', async (_req, reply) => {
+		try {
+			const league = await fetchCurrentLeague();
+			return await browseCurrencies(league.id);
+		} catch (err) {
+			return reply.code(502).send({ error: `poe.ninja unreachable: ${(err as Error).message}` });
+		}
+	});
+
+	app.get('/api/admin/poe2/watchlist', async () => poe2WatchlistDb.listWatchlist());
+
+	app.post('/api/admin/poe2/watchlist', async (req, reply) => {
+		const { currencyId, name, icon } = req.body as { currencyId?: string; name?: string; icon?: string | null };
+		if (!currencyId || !name) return reply.code(400).send({ error: 'currencyId and name are required' });
+		const created = poe2WatchlistDb.addWatchlistEntry(currencyId, name, icon ?? null);
+		// Poll immediately rather than waiting for the next tick (up to 15 minutes) — cheap,
+		// and refreshes every existing entry's value too.
+		pollPoe2Now().catch((err) => logger.error('poe2', `Immediate poll failed: ${err.message}`));
+		return reply.code(201).send(created);
+	});
+
+	app.delete('/api/admin/poe2/watchlist/:id', async (req, reply) => {
+		const { id } = req.params as { id: string };
+		poe2WatchlistDb.removeWatchlistEntry(id);
+		return reply.code(204).send();
+	});
+
 	// --- Logs ---
 	app.get('/api/admin/logs', async (req) => {
 		const { level, limit } = req.query as { level?: string; limit?: string };

backend/src/api/public.ts

@@ -6,6 +6,7 @@ import * as categoriesDb from '../storage/db/categories.js';
 import * as settingsDb from '../storage/db/settings.js';
 import * as stocksDb from '../storage/db/stocks.js';
 import * as bookmarksDb from '../storage/db/bookmarks.js';
+import * as poe2WatchlistDb from '../storage/db/poe2Watchlist.js';
 import { hasPrivateAccess } from './privateAccess.js';
 
 export async function registerPublicRoutes(app: FastifyInstance) {
@@ -69,4 +70,9 @@ export async function registerPublicRoutes(app: FastifyInstance) {
 		if (hasPrivateAccess(req)) return bookmarks;
 		return bookmarks.filter((b) => !b.isPrivate);
 	});
+
+	app.get('/api/poe2', async () => {
+		const { leagueName, primaryCurrencyName, updatedAt } = settingsDb.getSettings().poe2;
+		return { leagueName, primaryCurrencyName, updatedAt, entries: poe2WatchlistDb.listWatchlist() };
+	});
 }

backend/src/poe2/client.ts

@@ -0,0 +1,106 @@
+// poe.ninja's public PoE2 economy API — free, no account or API key required. This is the
+// only file that talks to it; poller.ts orchestrates when/how results get saved, same
+// separation as backend/src/telegram/ and backend/src/weather/ keep between the raw client
+// and their callers.
+//
+// Response shape confirmed against real requests (not just the published docs, which were
+// imprecise on two points): currency name/icon metadata lives in a top-level `items[]` array
+// on the overview response, NOT `core.items` (that only holds the handful of currencies used
+// for `core.rates`/`primary`/`secondary`). The icon field is `image` (a path relative to this
+// same host), not `icon`. Confirmed `sparkline.totalChange` always equals the last entry of
+// `sparkline.data`, and every observed `data` array has exactly 7 entries — so this is a
+// 7-day cumulative % change, not some other window.
+const BASE_URL = 'https://poe.ninja';
+
+export interface LeagueInfo {
+	id: string;
+	name: string;
+}
+
+export interface CurrencyBrowseEntry {
+	id: string;
+	name: string;
+	icon: string | null;
+}
+
+export interface CurrencyQuote {
+	value: number;
+	/** 7-day cumulative % change (see file header) — null if this line had no sparkline data. */
+	changePercent: number | null;
+}
+
+interface RawCurrencyItem {
+	id: string;
+	name: string;
+	image?: string;
+}
+
+interface RawCurrencyLine {
+	id: string;
+	primaryValue: number;
+	sparkline?: { totalChange: number; data: number[] } | null;
+}
+
+interface RawCurrencyOverview {
+	core: { primary: string };
+	lines: RawCurrencyLine[];
+	items: RawCurrencyItem[]; // top-level, not core.items — see file header
+}
+
+function resolveIcon(image: string | undefined): string | null {
+	return image ? `${BASE_URL}${image}` : null;
+}
+
+export async function fetchCurrentLeague(): Promise<LeagueInfo> {
+	const res = await fetch(`${BASE_URL}/poe2/api/economy/leagues`);
+	if (!res.ok) throw new Error(`poe.ninja leagues returned ${res.status}`);
+	const leagues = (await res.json()) as LeagueInfo[];
+	if (leagues.length === 0) throw new Error('No active leagues returned');
+	return leagues[0];
+}
+
+async function fetchCurrencyOverview(leagueId: string): Promise<RawCurrencyOverview> {
+	const url = `${BASE_URL}/poe2/api/economy/exchange/current/overview?league=${encodeURIComponent(leagueId)}&type=Currency`;
+	const res = await fetch(url);
+	if (!res.ok) throw new Error(`poe.ninja currency overview returned ${res.status}`);
+	return res.json();
+}
+
+// Fetches the whole traded-currency list for the admin's search-and-pick UI (see
+// api/admin.ts's GET /api/admin/poe2/browse) — only currencies that actually have a `lines`
+// entry (i.e. are currently traded), not every currency poe.ninja has ever known about.
+export async function browseCurrencies(leagueId: string): Promise<CurrencyBrowseEntry[]> {
+	const { lines, items } = await fetchCurrencyOverview(leagueId);
+	const metaById = new Map(items.map((item) => [item.id, item]));
+	return lines
+		.map((line) => {
+			const meta = metaById.get(line.id);
+			return { id: line.id, name: meta?.name ?? line.id, icon: resolveIcon(meta?.image) };
+		})
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// One overview fetch covers every watchlisted currency regardless of list size — unlike
+// Stocks, which needs one request per ticker (Yahoo has no equivalent single "give me all of
+// these" endpoint without a cookie/crumb handshake).
+export async function fetchWatchlistQuotes(
+	leagueId: string,
+	currencyIds: string[]
+): Promise<{ quotes: Map<string, CurrencyQuote | Error>; primaryCurrencyName: string | null }> {
+	const { lines, items, core } = await fetchCurrencyOverview(leagueId);
+	const lineById = new Map(lines.map((line) => [line.id, line]));
+	const nameById = new Map(items.map((item) => [item.id, item.name]));
+
+	const quotes = new Map<string, CurrencyQuote | Error>();
+	for (const id of currencyIds) {
+		const line = lineById.get(id);
+		if (!line) {
+			quotes.set(id, new Error('No longer traded in this league'));
+			continue;
+		}
+		quotes.set(id, { value: line.primaryValue, changePercent: line.sparkline?.totalChange ?? null });
+	}
+
+	const primaryCurrencyName = nameById.get(core.primary) ?? core.primary;
+	return { quotes, primaryCurrencyName };
+}

backend/src/poe2/poller.ts

@@ -0,0 +1,50 @@
+import * as poe2WatchlistDb from '../storage/db/poe2Watchlist.js';
+import * as settingsDb from '../storage/db/settings.js';
+import { logger } from '../storage/db/logs.js';
+import { fetchCurrentLeague, fetchWatchlistQuotes } from './client.js';
+
+// Called on a schedule (see queue/scheduler.ts) and immediately after the admin adds a
+// currency (see api/admin.ts) — always re-detects the current challenge league fresh (cheap,
+// guarantees correctness across league rotations with no separate staleness logic), then one
+// overview request covers the whole watchlist. A currency no longer traded this league gets
+// its own lastError, it never aborts the rest of the batch.
+export async function pollPoe2Now(): Promise<void> {
+	let league;
+	try {
+		league = await fetchCurrentLeague();
+	} catch (err) {
+		logger.error('poe2', `League lookup failed: ${(err as Error).message}`);
+		return;
+	}
+
+	const entries = poe2WatchlistDb.listWatchlist();
+	if (entries.length === 0) {
+		const { poe2 } = settingsDb.getSettings();
+		settingsDb.updateSettings({
+			poe2: { ...poe2, leagueId: league.id, leagueName: league.name, updatedAt: new Date().toISOString() }
+		});
+		return;
+	}
+
+	try {
+		const { quotes, primaryCurrencyName } = await fetchWatchlistQuotes(
+			league.id,
+			entries.map((e) => e.currencyId)
+		);
+		for (const entry of entries) {
+			const quote = quotes.get(entry.currencyId);
+			if (!quote) {
+				poe2WatchlistDb.markPolled(entry.id, null, null, 'No quote returned');
+			} else if (quote instanceof Error) {
+				poe2WatchlistDb.markPolled(entry.id, null, null, quote.message);
+			} else {
+				poe2WatchlistDb.markPolled(entry.id, quote.value, quote.changePercent, null);
+			}
+		}
+		settingsDb.updateSettings({
+			poe2: { leagueId: league.id, leagueName: league.name, primaryCurrencyName, updatedAt: new Date().toISOString() }
+		});
+	} catch (err) {
+		logger.error('poe2', `Watchlist poll failed: ${(err as Error).message}`);
+	}
+}

backend/src/queue/scheduler.ts

@@ -7,12 +7,14 @@ import * as settingsDb from '../storage/db/settings.js';
 import { logger } from '../storage/db/logs.js';
 import { pollWeatherNow } from '../weather/poller.js';
 import { pollStocksNow } from '../stocks/poller.js';
+import { pollPoe2Now } from '../poe2/poller.js';
 
 const POLL_TICK_MS = 60_000; // checks which sources are due every minute; each source's own interval governs actual fetch frequency
 const SYNTHESIS_TICK_MS = 60_000;
 const RETENTION_TICK_MS = 60 * 60_000; // hourly
 const WEATHER_TICK_MS = 45 * 60_000;
 const STOCKS_TICK_MS = 15 * 60_000; // per admin spec — stock prices move faster than weather
+const POE2_TICK_MS = 15 * 60_000; // matches Stocks' cadence
 
 export function startScheduler() {
 	const provider = () => {
@@ -79,5 +81,10 @@ export function startScheduler() {
 		pollStocksNow().catch((err) => logger.error('stocks', `Poll tick failed: ${err.message}`));
 	}, STOCKS_TICK_MS);
 
-	logger.info('scheduler', 'Started: poll every 1m, synthesis every 1m, retention every 1h, weather every 45m, stocks every 15m');
+	pollPoe2Now().catch((err) => logger.error('poe2', `Initial poll failed: ${err.message}`));
+	setInterval(() => {
+		pollPoe2Now().catch((err) => logger.error('poe2', `Poll tick failed: ${err.message}`));
+	}, POE2_TICK_MS);
+
+	logger.info('scheduler', 'Started: poll every 1m, synthesis every 1m, retention every 1h, weather every 45m, stocks every 15m, poe2 every 15m');
 }

backend/src/storage/db/index.ts

@@ -189,16 +189,20 @@ export function migrate() {
 			weather_hourly TEXT NOT NULL DEFAULT '[]', -- JSON array
 			weather_daily TEXT NOT NULL DEFAULT '[]', -- JSON array
 			weather_alerts TEXT NOT NULL DEFAULT '[]', -- JSON array — active NWS alerts for the configured location, US-only (see weather/client.ts)
-			weather_updated_at TEXT -- ISO timestamp, NULL pre-first-poll
+			weather_updated_at TEXT, -- ISO timestamp, NULL pre-first-poll
+			poe2_league_id TEXT,
+			poe2_league_name TEXT,
+			poe2_primary_currency_name TEXT, -- e.g. "Divine Orb" — the unit every poe2_watchlist value is quoted in
+			poe2_updated_at TEXT
 		);
 
-		-- Sidebar "Stocks" widget — polled every 15 minutes from Stooq (see stocks/poller.ts).
-		-- Price/change/poll-state live directly on the row, same as sources.last_polled_at,
-		-- rather than a separate quote-cache table.
+		-- Sidebar "Stocks" widget — polled every 15 minutes from Yahoo Finance (see
+		-- stocks/poller.ts). Price/change/poll-state live directly on the row, same as
+		-- sources.last_polled_at, rather than a separate quote-cache table.
 		CREATE TABLE IF NOT EXISTS stock_tickers (
 			id TEXT PRIMARY KEY,
 			label TEXT NOT NULL,
-			symbol TEXT NOT NULL, -- Stooq symbol syntax, e.g. "^dji", "aapl.us", "btcusd"
+			symbol TEXT NOT NULL, -- Yahoo symbol syntax, e.g. "^DJI", "AAPL", "BTC-USD"
 			priority_rank INTEGER NOT NULL,
 			last_price REAL,
 			last_change_percent REAL,
@@ -207,6 +211,22 @@ export function migrate() {
 			created_at TEXT NOT NULL
 		);
 
+		-- Sidebar "PoE2" widget — currency watchlist priced off poe.ninja's PoE2 economy API
+		-- (see poe2/poller.ts), always against the current challenge league (auto-detected,
+		-- no admin config). Same shape as stock_tickers — poll state lives on the row.
+		CREATE TABLE IF NOT EXISTS poe2_watchlist (
+			id TEXT PRIMARY KEY,
+			currency_id TEXT NOT NULL, -- opaque id from the exchange overview's lines[].id, e.g. "divine"
+			name TEXT NOT NULL, -- captured at add-time from the browse picker, not re-resolved
+			icon TEXT,
+			priority_rank INTEGER NOT NULL,
+			last_value REAL,
+			last_change_percent REAL,
+			last_polled_at TEXT,
+			last_error TEXT,
+			created_at TEXT NOT NULL
+		);
+
 		-- Sidebar "Bookmarks" widget — admin-curated links, each independently hidden/public
 		-- via is_private (same private-access lock feature as categories.is_private).
 		CREATE TABLE IF NOT EXISTS bookmarks (
@@ -302,6 +322,12 @@ export function migrate() {
 		db.exec("ALTER TABLE global_settings ADD COLUMN weather_pressure_unit TEXT NOT NULL DEFAULT 'inHg'");
 		db.exec("ALTER TABLE global_settings ADD COLUMN weather_alerts TEXT NOT NULL DEFAULT '[]'");
 	}
+	if (!hasColumn('global_settings', 'poe2_league_id')) {
+		db.exec('ALTER TABLE global_settings ADD COLUMN poe2_league_id TEXT');
+		db.exec('ALTER TABLE global_settings ADD COLUMN poe2_league_name TEXT');
+		db.exec('ALTER TABLE global_settings ADD COLUMN poe2_primary_currency_name TEXT');
+		db.exec('ALTER TABLE global_settings ADD COLUMN poe2_updated_at TEXT');
+	}
 
 	// Seed a handful of sensible default tickers so the Stocks widget isn't empty on a
 	// fresh install — the admin can remove/replace any of them via the Stocks tab.

backend/src/storage/db/poe2Watchlist.ts

@@ -0,0 +1,49 @@
+import { randomUUID } from 'node:crypto';
+import { db } from './index.js';
+import type { Poe2WatchlistEntry } from './types.js';
+
+function rowToEntry(row: any): Poe2WatchlistEntry {
+	return {
+		id: row.id,
+		currencyId: row.currency_id,
+		name: row.name,
+		icon: row.icon,
+		priorityRank: row.priority_rank,
+		lastValue: row.last_value,
+		lastChangePercent: row.last_change_percent,
+		lastPolledAt: row.last_polled_at,
+		lastError: row.last_error,
+		createdAt: row.created_at
+	};
+}
+
+export function listWatchlist(): Poe2WatchlistEntry[] {
+	const rows = db.prepare('SELECT * FROM poe2_watchlist ORDER BY priority_rank').all();
+	return rows.map(rowToEntry);
+}
+
+// No update() — entries are picked from a live browse list (see poe2/client.ts's
+// browseCurrencies), not typed, so there's nothing to edit; remove and re-add covers the
+// rare "picked the wrong one" case.
+export function addWatchlistEntry(currencyId: string, name: string, icon: string | null): Poe2WatchlistEntry {
+	const id = `poe2-${currencyId.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '')}-${randomUUID().slice(0, 6)}`;
+	const maxRank = db.prepare('SELECT COALESCE(MAX(priority_rank), 0) as m FROM poe2_watchlist').get() as { m: number };
+	const createdAt = new Date().toISOString();
+	db.prepare(
+		'INSERT INTO poe2_watchlist (id, currency_id, name, icon, priority_rank, created_at) VALUES (?, ?, ?, ?, ?, ?)'
+	).run(id, currencyId, name, icon, maxRank.m + 1, createdAt);
+	return {
+		id, currencyId, name, icon, priorityRank: maxRank.m + 1,
+		lastValue: null, lastChangePercent: null, lastPolledAt: null, lastError: null, createdAt
+	};
+}
+
+export function removeWatchlistEntry(id: string) {
+	db.prepare('DELETE FROM poe2_watchlist WHERE id = ?').run(id);
+}
+
+export function markPolled(id: string, value: number | null, changePercent: number | null, error: string | null) {
+	db.prepare(
+		'UPDATE poe2_watchlist SET last_value = ?, last_change_percent = ?, last_polled_at = ?, last_error = ? WHERE id = ?'
+	).run(value, changePercent, new Date().toISOString(), error, id);
+}

backend/src/storage/db/settings.ts

@@ -36,6 +36,12 @@ function rowToSettings(row: any): GlobalSettings {
 			daily: JSON.parse(row.weather_daily),
 			alerts: JSON.parse(row.weather_alerts),
 			updatedAt: row.weather_updated_at
+		},
+		poe2: {
+			leagueId: row.poe2_league_id,
+			leagueName: row.poe2_league_name,
+			primaryCurrencyName: row.poe2_primary_currency_name,
+			updatedAt: row.poe2_updated_at
 		}
 	};
 }
@@ -52,7 +58,8 @@ export function updateSettings(patch: Partial<GlobalSettings>): GlobalSettings {
 		...patch,
 		retention: { ...current.retention, ...(patch.retention ?? {}) },
 		selectedModels: { ...current.selectedModels, ...(patch.selectedModels ?? {}) },
-		weather: { ...current.weather, ...(patch.weather ?? {}) }
+		weather: { ...current.weather, ...(patch.weather ?? {}) },
+		poe2: { ...current.poe2, ...(patch.poe2 ?? {}) }
 	};
 	db.prepare(
 		`UPDATE global_settings SET
@@ -64,7 +71,8 @@ export function updateSettings(patch: Partial<GlobalSettings>): GlobalSettings {
 			storage_cap_enabled=?, storage_cap_value=?, storage_cap_unit=?,
 			weather_location_name=?, weather_latitude=?, weather_longitude=?, weather_unit=?,
 			weather_wind_unit=?, weather_pressure_unit=?,
-			weather_current=?, weather_hourly=?, weather_daily=?, weather_alerts=?, weather_updated_at=?
+			weather_current=?, weather_hourly=?, weather_daily=?, weather_alerts=?, weather_updated_at=?,
+			poe2_league_id=?, poe2_league_name=?, poe2_primary_currency_name=?, poe2_updated_at=?
 		 WHERE id = 1`
 	).run(
 		merged.mergeStrictness,
@@ -95,7 +103,11 @@ export function updateSettings(patch: Partial<GlobalSettings>): GlobalSettings {
 		JSON.stringify(merged.weather.hourly),
 		JSON.stringify(merged.weather.daily),
 		JSON.stringify(merged.weather.alerts),
-		merged.weather.updatedAt
+		merged.weather.updatedAt,
+		merged.poe2.leagueId,
+		merged.poe2.leagueName,
+		merged.poe2.primaryCurrencyName,
+		merged.poe2.updatedAt
 	);
 	return getSettings();
 }

backend/src/storage/db/types.ts

@@ -233,6 +233,21 @@ export interface StockTicker {
 	createdAt: string;
 }
 
+export interface Poe2WatchlistEntry {
+	id: string;
+	/** Opaque id from poe.ninja's exchange overview, e.g. "divine" — not a display name. */
+	currencyId: string;
+	name: string;
+	icon: string | null;
+	priorityRank: number;
+	lastValue: number | null;
+	/** Cumulative % change over poe.ninja's own sparkline window — confirmed to be 7 days (see poe2/client.ts). */
+	lastChangePercent: number | null;
+	lastPolledAt: string | null;
+	lastError: string | null;
+	createdAt: string;
+}
+
 export interface Bookmark {
 	id: string;
 	name: string;
@@ -299,6 +314,19 @@ export interface GlobalSettings {
 		alerts: WeatherAlert[];
 		updatedAt: string | null;
 	};
+	/**
+	 * Sidebar "PoE2" widget cache — see poe2/poller.ts. No admin-set config (unlike weather):
+	 * the league is always auto-detected as the current challenge league, so this is purely
+	 * a cache of what the last poll learned. Watchlist entries themselves live in the
+	 * poe2_watchlist table, not here — same split as stock_tickers vs. this settings row.
+	 */
+	poe2: {
+		leagueId: string | null;
+		leagueName: string | null;
+		/** e.g. "Divine Orb" — the unit every poe2_watchlist value is quoted in. */
+		primaryCurrencyName: string | null;
+		updatedAt: string | null;
+	};
 }
 
 export interface WeatherAlert {