Feat/finance finviz fundamentals (#114)

* feat(finance): Finviz fundamentals snapshot on ticker page

Scrape the full Finviz quote-page snapshot (valuation, performance,
technical, fund and dividend metrics) plus the company/fund description
and render it as a generic Fundamentals grid on /finance/ticker/:ticker.

- finviz.ts: getFinvizFundamentals() + testable parseFinvizSnapshot()
  (linkedom; browser UA since Finviz blocks the default undici UA)
- Fundamentals/FundamentalMetric types (ordered label/value/tone pairs,
  rendered generically so new source rows appear without code changes)
- GET /api/finance/fundamentals: paid-gated, soft-fails to null,
  read-through cached at FUNDAMENTALS_TTL_SECONDS=6h (reuses
  finance_quotes_cache — no migration)
- Stat gains an optional up/down tone prop
- Tests: parser + route

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(file-transcoding): skip streaming tests when ffmpeg is absent

The stream-as-available tests spawn the real ffmpeg binary; on runners
without ffmpeg, spawn('ffmpeg') ENOENT crashes the whole vitest process.
Guard those tests behind a HAS_FFMPEG check instead.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: ralyodio

src/app/api/finance/fundamentals/route.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Tests for GET /api/finance/fundamentals
+ *
+ * Verifies paid gating runs first, symbol validation, and that a fetch/parse
+ * failure soft-fails to `{ fundamentals: null }` rather than breaking the page.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { NextRequest, NextResponse } from 'next/server';
+import { GET } from './route';
+
+const mockRequireActiveSubscription = vi.fn();
+vi.mock('@/lib/subscription/guard', () => ({
+  requireActiveSubscription: (req: NextRequest) => mockRequireActiveSubscription(req),
+}));
+
+const mockGetFinvizFundamentals = vi.fn();
+vi.mock('@/lib/finance/market-data', () => ({
+  getFinvizFundamentals: (symbol: string) => mockGetFinvizFundamentals(symbol),
+}));
+
+// Read-through cache: pass through to the fetcher so we exercise the provider.
+vi.mock('@/lib/finance/market-data/cache', () => ({
+  FUNDAMENTALS_TTL_SECONDS: 21600,
+  readThrough: <T,>(_s: string, _k: string, _ttl: number, fetcher: () => Promise<T>) => fetcher(),
+}));
+
+function req(symbol?: string): NextRequest {
+  const url = symbol
+    ? `http://localhost/api/finance/fundamentals?symbol=${symbol}`
+    : 'http://localhost/api/finance/fundamentals';
+  return new NextRequest(url);
+}
+
+describe('GET /api/finance/fundamentals', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('returns the gate response when the subscription check fails (paid-gated)', async () => {
+    mockRequireActiveSubscription.mockResolvedValueOnce(
+      NextResponse.json({ error: 'unauthorized' }, { status: 401 }),
+    );
+    const res = await GET(req('SPY'));
+    expect(res.status).toBe(401);
+    expect(mockGetFinvizFundamentals).not.toHaveBeenCalled();
+  });
+
+  it('400s on an invalid symbol', async () => {
+    mockRequireActiveSubscription.mockResolvedValueOnce(null);
+    const res = await GET(req('!!!'));
+    expect(res.status).toBe(400);
+  });
+
+  it('returns the fundamentals for a paid user', async () => {
+    mockRequireActiveSubscription.mockResolvedValueOnce(null);
+    mockGetFinvizFundamentals.mockResolvedValueOnce({
+      symbol: 'SPY',
+      source: 'finviz',
+      metrics: [{ label: 'Beta', value: '1.01', tone: null }],
+      description: null,
+      asOf: 1,
+    });
+    const res = await GET(req('spy'));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.fundamentals.symbol).toBe('SPY');
+    expect(mockGetFinvizFundamentals).toHaveBeenCalledWith('SPY');
+  });
+
+  it('soft-fails to null when the source throws (never breaks the page)', async () => {
+    mockRequireActiveSubscription.mockResolvedValueOnce(null);
+    mockGetFinvizFundamentals.mockRejectedValueOnce(new Error('403'));
+    const res = await GET(req('SPY'));
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.fundamentals).toBeNull();
+  });
+});

src/app/api/finance/fundamentals/route.ts

@@ -0,0 +1,43 @@
+/**
+ * GET /api/finance/fundamentals?symbol=SPY
+ *
+ * Finviz snapshot for the ticker page: the full valuation / performance /
+ * technical / fund / dividend table plus the company description. Paid-gated
+ * and read-through cached (fundamentals move slowly). This is public market
+ * data, sourced independently of the user's broker, so the cache key is fixed.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireActiveSubscription } from '@/lib/subscription/guard';
+import { getFinvizFundamentals } from '@/lib/finance/market-data';
+import { normalizeSymbol } from '@/lib/finance/market-data/stooq';
+import { readThrough, FUNDAMENTALS_TTL_SECONDS } from '@/lib/finance/market-data/cache';
+import type { Fundamentals } from '@/lib/finance/market-data/types';
+
+export const dynamic = 'force-dynamic';
+
+const SYMBOL_RE = /^[A-Z][A-Z0-9.\-]{0,9}$/;
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const gate = await requireActiveSubscription(request);
+  if (gate) return gate;
+
+  const symbol = normalizeSymbol(request.nextUrl.searchParams.get('symbol') ?? '');
+  if (!SYMBOL_RE.test(symbol)) {
+    return NextResponse.json({ error: 'invalid symbol' }, { status: 400 });
+  }
+
+  try {
+    const fundamentals = await readThrough<Fundamentals | null>(
+      symbol,
+      'fundamentals:finviz',
+      FUNDAMENTALS_TTL_SECONDS,
+      () => getFinvizFundamentals(symbol),
+    );
+    return NextResponse.json({ fundamentals });
+  } catch (error) {
+    console.error('[finance/fundamentals] error:', error);
+    // Soft-fail: the section is supplementary, so never break the page.
+    return NextResponse.json({ fundamentals: null });
+  }
+}

src/app/finance/ticker/[ticker]/ticker-view.tsx

@@ -15,7 +15,7 @@ import { ReportPanel } from './report-panel';
 import { NewsSection } from '@/components/news';
 // Import from the SDK-free `types` module (not the index) so the Alpaca SDK is
 // never pulled into the client bundle.
-import { TICKER_RANGES, type AssetInfo, type Candle, type Quote, type TickerRange } from '@/lib/finance/market-data/types';
+import { TICKER_RANGES, type AssetInfo, type Candle, type Fundamentals, type Quote, type TickerRange } from '@/lib/finance/market-data/types';
 import type { WatchlistChanges } from '@/lib/finance/performance';
 
 const RECENT_KEY = 'finance:recent';
@@ -62,6 +62,7 @@ export function TickerView({ symbol }: { symbol: string }): React.ReactElement {
   const [holding, setHolding] = useState<Holding | null>(null);
   const [changes, setChanges] = useState<WatchlistChanges | null>(null);
   const [asset, setAsset] = useState<AssetInfo | null>(null);
+  const [fundamentals, setFundamentals] = useState<Fundamentals | null>(null);
 
   useEffect(() => {
     rememberRecent(symbol);
@@ -166,6 +167,21 @@ export function TickerView({ symbol }: { symbol: string }): React.ReactElement {
     };
   }, [symbol]);
 
+  // Fundamentals / snapshot (Finviz: valuation, performance, technicals, etc.).
+  useEffect(() => {
+    let cancelled = false;
+    setFundamentals(null);
+    fetch(`/api/finance/fundamentals?symbol=${encodeURIComponent(symbol)}`, { cache: 'no-store' })
+      .then((res) => (res.ok ? res.json() : { fundamentals: null }))
+      .then((body: { fundamentals?: Fundamentals | null }) => {
+        if (!cancelled) setFundamentals(body.fundamentals ?? null);
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, [symbol]);
+
   const toggleWatchlist = useCallback(async () => {
     const next = !inWatchlist;
     setInWatchlist(next);
@@ -287,6 +303,25 @@ export function TickerView({ symbol }: { symbol: string }): React.ReactElement {
         </section>
       ) : null}
 
+      {/* Fundamentals snapshot (Finviz): full valuation / performance /
+          technical / fund / dividend table, rendered generically. */}
+      {fundamentals && fundamentals.metrics.length > 0 ? (
+        <section className="mt-8">
+          <div className="mb-3 flex items-baseline justify-between">
+            <h2 className="text-lg font-semibold text-text-primary">Fundamentals</h2>
+            <span className="text-xs text-text-muted">via Finviz</span>
+          </div>
+          <div className="grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-4">
+            {fundamentals.metrics.map((m) => (
+              <Stat key={m.label} label={m.label} value={m.value} tone={m.tone} />
+            ))}
+          </div>
+          {fundamentals.description ? (
+            <p className="mt-4 text-sm leading-relaxed text-text-secondary">{fundamentals.description}</p>
+          ) : null}
+        </section>
+      ) : null}
+
       {/* AI report area — never auto-runs; the Analyze button is the cost boundary. */}
       <ReportPanel symbol={symbol} />
 
@@ -301,11 +336,21 @@ export function TickerView({ symbol }: { symbol: string }): React.ReactElement {
   );
 }
 
-function Stat({ label, value }: { label: string; value: string }): React.ReactElement {
+function Stat({
+  label,
+  value,
+  tone = null,
+}: {
+  label: string;
+  value: string;
+  tone?: 'positive' | 'negative' | null;
+}): React.ReactElement {
+  const valueColor =
+    tone === 'positive' ? 'text-green-400' : tone === 'negative' ? 'text-red-400' : 'text-text-primary';
   return (
     <div className="card p-3">
       <div className="text-xs uppercase tracking-wider text-text-muted">{label}</div>
-      <div className="mt-1 text-base font-semibold text-text-primary">{value}</div>
+      <div className={`mt-1 text-base font-semibold ${valueColor}`}>{value}</div>
     </div>
   );
 }

src/lib/file-transcoding/file-transcoding.test.ts

@@ -7,6 +7,7 @@
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { createWriteStream } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { Readable } from 'node:stream';
 import { mkdir, rm, access } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -19,6 +20,12 @@ import {
   TEMP_DIR,
 } from './file-transcoding';
 
+// The streaming-transcode tests below spawn the real `ffmpeg` binary. CI runners
+// don't have ffmpeg installed, so a `spawn('ffmpeg')` ENOENT crashes the whole
+// vitest process with an uncaught exception. Skip those tests when ffmpeg is
+// unavailable instead of failing the entire suite.
+const HAS_FFMPEG = spawnSync('ffmpeg', ['-version']).status === 0;
+
 describe('File-based Transcoding Service', () => {
   describe('getTempFilePath', () => {
     it('should generate correct temp file path', () => {
@@ -175,7 +182,7 @@ describe('File-based Transcoding Service', () => {
     });
   });
 
-  describe('FileTranscodingService - downloadAndTranscode (stream-as-available)', () => {
+  describe.skipIf(!HAS_FFMPEG)('FileTranscodingService - downloadAndTranscode (stream-as-available)', () => {
     let service: FileTranscodingService;
 
     afterEach(async () => {

src/lib/finance/market-data/cache.ts

@@ -14,6 +14,8 @@ const CACHE_TABLE = 'finance_quotes_cache';
 /** Default freshness windows (seconds). EOD data changes at most daily. */
 export const QUOTE_TTL_SECONDS = 5 * 60;
 export const CANDLES_TTL_SECONDS = 60 * 60;
+/** Fundamentals (valuation/perf/technicals) move slowly — cache for hours. */
+export const FUNDAMENTALS_TTL_SECONDS = 6 * 60 * 60;
 
 interface CacheRow<T> {
   payload: T;

src/lib/finance/market-data/finviz.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Tests for the Finviz fundamentals parser.
+ *
+ * Uses a trimmed fixture that mirrors the real quote-page markup
+ * (table.snapshot-table2 with .snapshot-td-label / .snapshot-td-content cells
+ * and .is-positive / .is-negative color spans, plus .quote_profile-bio).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { parseFinvizSnapshot, getFinvizFundamentals } from './finviz';
+
+const FIXTURE = `
+<html><body>
+<table class="js-snapshot-table snapshot-table2 screener_snapshot-table-body">
+  <tr>
+    <td class="snapshot-td2"><div class="snapshot-td-label">P/E</div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-content"><b>24.50</b></div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-label">Perf Year</div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-content"><b><span class="color-text is-positive">24.00%</span></b></div></td>
+  </tr>
+  <tr>
+    <td class="snapshot-td2"><div class="snapshot-td-label">Perf Week</div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-content"><b><span class="color-text is-negative">-1.25%</span></b></div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-label">Beta</div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-content"><b>1.01</b></div></td>
+  </tr>
+  <tr>
+    <td class="snapshot-td2"><div class="snapshot-td-label">Short Float</div></td>
+    <td class="snapshot-td2"><div class="snapshot-td-content"><b>-</b></div></td>
+  </tr>
+</table>
+<div class="quote_profile-bio">The fund seeks to provide investment results
+  that correspond to the S&amp;P 500 Index.</div>
+</body></html>
+`;
+
+describe('parseFinvizSnapshot', () => {
+  it('extracts ordered label/value metrics with tone and description', () => {
+    const result = parseFinvizSnapshot(FIXTURE, 'spy');
+    expect(result).not.toBeNull();
+    const f = result!;
+
+    expect(f.symbol).toBe('SPY');
+    expect(f.source).toBe('finviz');
+    expect(typeof f.asOf).toBe('number');
+
+    // Order is preserved; the "-" placeholder row is dropped.
+    expect(f.metrics).toEqual([
+      { label: 'P/E', value: '24.50', tone: null },
+      { label: 'Perf Year', value: '24.00%', tone: 'positive' },
+      { label: 'Perf Week', value: '-1.25%', tone: 'negative' },
+      { label: 'Beta', value: '1.01', tone: null },
+    ]);
+
+    expect(f.description).toContain('S&P 500 Index');
+    // Whitespace is collapsed.
+    expect(f.description).not.toMatch(/\s{2,}/);
+  });
+
+  it('returns null when the snapshot table is missing', () => {
+    expect(parseFinvizSnapshot('<html><body>no table</body></html>', 'SPY')).toBeNull();
+  });
+});
+
+describe('getFinvizFundamentals', () => {
+  it('sends a browser UA and parses the response', async () => {
+    const fetchFn = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () => FIXTURE,
+    });
+
+    const result = await getFinvizFundamentals('spy', { fetchFn });
+    expect(result?.symbol).toBe('SPY');
+    expect(result?.metrics.length).toBe(4);
+
+    const [url, init] = fetchFn.mock.calls[0];
+    expect(url).toContain('t=SPY');
+    expect(init.headers['User-Agent']).toMatch(/Mozilla/);
+  });
+
+  it('throws on a non-ok response (caller renders defensively)', async () => {
+    const fetchFn = vi.fn().mockResolvedValue({ ok: false, status: 403, text: async () => '' });
+    await expect(getFinvizFundamentals('SPY', { fetchFn })).rejects.toThrow(/403/);
+  });
+});