feat(finance): AI Opportunities screen + multiple watchlists (CRUD)

Opportunities: a "Find opportunities" button on the finance hub takes
free-text parameters (default: top 10 stocks under $10 with 6-12mo
potential), feeds them to the AI, and renders a ranked candidate list
(each ticker links to its page) plus copyable markdown. New
lib/finance/opportunities module reuses the report OpenAI adapter, cost
helper, and shares the report rolling-24h rate limit + run ledger
(sentinel symbol). Each run spends tokens; no auto-run, no DB cache.

Multiple watchlists: new finance_watchlists table + watchlist_id FK on
items (migration backfills a default list per profile so nothing is
lost; uniqueness moves to (watchlist_id, symbol)). New
GET/POST /api/finance/watchlists and PATCH/DELETE /[id]; the items route
now takes a watchlistId, defaulting to the profile's first list so the
ticker page add/remove keeps working. UI extracted to
watchlist-section.tsx with list tabs (+counts), New/Rename/Delete, and
per-card remove.

Tests: opportunities parser/pipeline + watchlist name sanitizer (103
finance tests pass). types.ts gains finance_watchlists + the
watchlist_id FK relationship so the count-embed type-checks.

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

Author: ralyodio

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

@@ -0,0 +1,101 @@
+/**
+ * Finance AI "Opportunities" stock screen (token-spending route).
+ *
+ * POST /api/finance/opportunities { prompt? } — generate a ranked candidate
+ * list from free-text parameters. Enforces auth + active paid subscription
+ * FIRST, then the shared per-user/global daily caps (same rolling-24h ledger as
+ * reports) before any LLM call. Logs tokens + cost to the run ledger.
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireActiveSubscription } from '@/lib/subscription/guard';
+import { getActiveProfileId } from '@/lib/profiles/profile-utils';
+import {
+  countRunsSince,
+  createOpenAIReportLLM,
+  evaluateRateLimit,
+  getRateLimitConfig,
+  getReportModel,
+  logRun,
+  rollingWindowStart,
+} from '@/lib/finance/analysis';
+import {
+  DEFAULT_OPPORTUNITIES_PROMPT,
+  MAX_PROMPT_LENGTH,
+  OPPORTUNITIES_PROMPT_VERSION,
+  generateOpportunities,
+} from '@/lib/finance/opportunities';
+
+export const dynamic = 'force-dynamic';
+
+/** Sentinel `symbol` for ledger rows so opportunities share the report cap. */
+const LEDGER_SYMBOL = '*OPPORTUNITIES*';
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const gate = await requireActiveSubscription(request);
+  if (gate) return gate;
+
+  const profileId = await getActiveProfileId();
+  if (!profileId) {
+    return NextResponse.json({ error: 'No active profile' }, { status: 400 });
+  }
+
+  const body = (await request.json().catch(() => null)) as { prompt?: string } | null;
+  const prompt = (typeof body?.prompt === 'string' ? body.prompt.trim() : '').slice(0, MAX_PROMPT_LENGTH)
+    || DEFAULT_OPPORTUNITIES_PROMPT;
+
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    return NextResponse.json({ error: 'AI service not configured' }, { status: 503 });
+  }
+
+  const model = getReportModel();
+
+  // Rate limit (rolling 24h) — shared with reports; defends against LLM spend.
+  const config = getRateLimitConfig();
+  const counts = await countRunsSince(profileId, rollingWindowStart());
+  const decision = evaluateRateLimit(counts, config);
+  if (!decision.allowed) {
+    await logRun({
+      profileId,
+      symbol: LEDGER_SYMBOL,
+      model,
+      promptVersion: OPPORTUNITIES_PROMPT_VERSION,
+      status: 'rate_limited',
+    });
+    return NextResponse.json(
+      { error: 'rate_limited', message: decision.reason, scope: decision.scope },
+      { status: 429 },
+    );
+  }
+
+  try {
+    const llm = createOpenAIReportLLM(apiKey);
+    const result = await generateOpportunities({ prompt, llm, model });
+
+    await logRun({
+      profileId,
+      symbol: LEDGER_SYMBOL,
+      model,
+      promptVersion: OPPORTUNITIES_PROMPT_VERSION,
+      status: 'success',
+      promptTokens: result.usage.promptTokens,
+      completionTokens: result.usage.completionTokens,
+      totalTokens: result.usage.totalTokens,
+      costUsd: result.usage.costUsd,
+    });
+
+    return NextResponse.json({ opportunities: result });
+  } catch (error) {
+    console.error('[finance/opportunities] generation failed:', error);
+    await logRun({
+      profileId,
+      symbol: LEDGER_SYMBOL,
+      model,
+      promptVersion: OPPORTUNITIES_PROMPT_VERSION,
+      status: 'failure',
+      error: error instanceof Error ? error.message : 'unknown',
+    });
+    return NextResponse.json({ error: 'generation_failed' }, { status: 502 });
+  }
+}

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

@@ -1,12 +1,13 @@
 /**
- * Finance watchlist (PRD §3.1, §5) — profile-scoped tickers.
+ * Finance watchlist items (PRD §3.1, §5) — tickers within a named list.
  *
- * GET    /api/finance/watchlist          — list the active profile's tickers
- * POST   /api/finance/watchlist {symbol} — add a ticker
- * DELETE /api/finance/watchlist?symbol=  — remove a ticker
+ * GET    /api/finance/watchlist?watchlistId=        — list a list's tickers
+ * POST   /api/finance/watchlist {symbol|symbols, watchlistId?} — add ticker(s)
+ * DELETE /api/finance/watchlist?symbol=&watchlistId= — remove a ticker
  *
- * Paid-gated. Rows are filtered by the active profile id; the table also has
- * RLS as defense in depth.
+ * Paid-gated. When `watchlistId` is omitted we fall back to the profile's
+ * default (oldest) list, creating one if needed — so legacy single-list callers
+ * keep working. Every query is scoped to the active profile (RLS in depth).
  */
 
 import { NextRequest, NextResponse } from 'next/server';
@@ -15,11 +16,23 @@ import { getActiveProfileId } from '@/lib/profiles/profile-utils';
 import { getServerClient } from '@/lib/supabase';
 import { normalizeSymbol } from '@/lib/finance/market-data/stooq';
 import { parseSymbolList } from '@/lib/finance/watchlist';
+import { getOrCreateDefaultWatchlistId, ownsWatchlist } from '@/lib/finance/watchlist-db';
 
 export const dynamic = 'force-dynamic';
 
 const SYMBOL_RE = /^[A-Z][A-Z0-9.\-]{0,9}$/;
 
+/**
+ * Resolve the target list for a profile. Returns the verified list id, or null
+ * when an explicit (but unowned/unknown) id was supplied.
+ */
+async function resolveWatchlistId(profileId: string, requested: string | null): Promise<string | null> {
+  if (requested) {
+    return (await ownsWatchlist(profileId, requested)) ? requested : null;
+  }
+  return getOrCreateDefaultWatchlistId(profileId);
+}
+
 export async function GET(request: NextRequest): Promise<NextResponse> {
   const gate = await requireActiveSubscription(request);
   if (gate) return gate;
@@ -29,18 +42,23 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
     return NextResponse.json({ error: 'No active profile' }, { status: 400 });
   }
 
+  const watchlistId = await resolveWatchlistId(profileId, request.nextUrl.searchParams.get('watchlistId'));
+  if (!watchlistId) {
+    return NextResponse.json({ error: 'watchlist not found' }, { status: 404 });
+  }
+
   const { data, error } = await getServerClient()
     .from('finance_watchlist')
     .select('id, symbol, exchange, added_at')
-    .eq('profile_id', profileId)
+    .eq('watchlist_id', watchlistId)
     .order('added_at', { ascending: false });
 
   if (error) {
     console.error('[finance/watchlist] list error:', error);
     return NextResponse.json({ error: 'failed to load watchlist' }, { status: 500 });
   }
 
-  return NextResponse.json({ watchlist: data ?? [] });
+  return NextResponse.json({ watchlistId, watchlist: data ?? [] });
 }
 
 export async function POST(request: NextRequest): Promise<NextResponse> {
@@ -53,21 +71,28 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
   }
 
   const body = (await request.json().catch(() => null)) as
-    | { symbol?: string; symbols?: string | string[]; exchange?: string }
+    | { symbol?: string; symbols?: string | string[]; exchange?: string; watchlistId?: string }
     | null;
 
+  const watchlistId = await resolveWatchlistId(profileId, body?.watchlistId ?? null);
+  if (!watchlistId) {
+    return NextResponse.json({ error: 'watchlist not found' }, { status: 404 });
+  }
+
+  const supabase = getServerClient();
+
   // Bulk add: `symbols` may be a comma/space/newline-separated string or array.
   if (body?.symbols !== undefined) {
     const { valid, invalid } = parseSymbolList(body.symbols);
     if (valid.length === 0) {
       return NextResponse.json({ error: 'no valid symbols', invalid }, { status: 400 });
     }
 
-    const { data, error } = await getServerClient()
+    const { data, error } = await supabase
       .from('finance_watchlist')
       .upsert(
-        valid.map((symbol) => ({ profile_id: profileId, symbol, exchange: null })),
-        { onConflict: 'profile_id,symbol' },
+        valid.map((symbol) => ({ profile_id: profileId, watchlist_id: watchlistId, symbol, exchange: null })),
+        { onConflict: 'watchlist_id,symbol' },
       )
       .select('id, symbol, exchange, added_at');
 
@@ -76,7 +101,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
       return NextResponse.json({ error: 'failed to add symbols' }, { status: 500 });
     }
 
-    return NextResponse.json({ added: data ?? [], count: data?.length ?? 0, invalid }, { status: 201 });
+    return NextResponse.json({ watchlistId, added: data ?? [], count: data?.length ?? 0, invalid }, { status: 201 });
   }
 
   // Single add.
@@ -85,11 +110,11 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     return NextResponse.json({ error: 'invalid symbol' }, { status: 400 });
   }
 
-  const { data, error } = await getServerClient()
+  const { data, error } = await supabase
     .from('finance_watchlist')
     .upsert(
-      { profile_id: profileId, symbol, exchange: body?.exchange ?? null },
-      { onConflict: 'profile_id,symbol' },
+      { profile_id: profileId, watchlist_id: watchlistId, symbol, exchange: body?.exchange ?? null },
+      { onConflict: 'watchlist_id,symbol' },
     )
     .select('id, symbol, exchange, added_at')
     .single();
@@ -99,7 +124,7 @@ export async function POST(request: NextRequest): Promise<NextResponse> {
     return NextResponse.json({ error: 'failed to add symbol' }, { status: 500 });
   }
 
-  return NextResponse.json({ item: data }, { status: 201 });
+  return NextResponse.json({ watchlistId, item: data }, { status: 201 });
 }
 
 export async function DELETE(request: NextRequest): Promise<NextResponse> {
@@ -116,10 +141,15 @@ export async function DELETE(request: NextRequest): Promise<NextResponse> {
     return NextResponse.json({ error: 'invalid symbol' }, { status: 400 });
   }
 
+  const watchlistId = await resolveWatchlistId(profileId, request.nextUrl.searchParams.get('watchlistId'));
+  if (!watchlistId) {
+    return NextResponse.json({ error: 'watchlist not found' }, { status: 404 });
+  }
+
   const { error } = await getServerClient()
     .from('finance_watchlist')
     .delete()
-    .eq('profile_id', profileId)
+    .eq('watchlist_id', watchlistId)
     .eq('symbol', symbol);
 
   if (error) {

src/app/api/finance/watchlists/[id]/route.ts

@@ -0,0 +1,77 @@
+/**
+ * Finance watchlists (named lists) — single-list routes.
+ *
+ * PATCH  /api/finance/watchlists/:id {name} — rename
+ * DELETE /api/finance/watchlists/:id          — delete (cascades its items)
+ *
+ * Paid-gated; every query is filtered by the active profile so a caller can
+ * only mutate its own lists (RLS as defense in depth).
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireActiveSubscription } from '@/lib/subscription/guard';
+import { getActiveProfileId } from '@/lib/profiles/profile-utils';
+import { getServerClient } from '@/lib/supabase';
+import { sanitizeWatchlistName } from '@/lib/finance/watchlist';
+
+export const dynamic = 'force-dynamic';
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const gate = await requireActiveSubscription(request);
+  if (gate) return gate;
+
+  const profileId = await getActiveProfileId();
+  if (!profileId) return NextResponse.json({ error: 'No active profile' }, { status: 400 });
+
+  const { id } = await params;
+  const body = (await request.json().catch(() => null)) as { name?: string } | null;
+  const name = sanitizeWatchlistName(body?.name);
+  if (!name) return NextResponse.json({ error: 'invalid name' }, { status: 400 });
+
+  const { data, error } = await getServerClient()
+    .from('finance_watchlists')
+    .update({ name })
+    .eq('id', id)
+    .eq('profile_id', profileId)
+    .select('id, name, created_at')
+    .maybeSingle();
+
+  if (error) {
+    console.error('[finance/watchlists] rename error:', error);
+    return NextResponse.json({ error: 'failed to rename watchlist' }, { status: 500 });
+  }
+  if (!data) return NextResponse.json({ error: 'not found' }, { status: 404 });
+
+  return NextResponse.json({ watchlist: { id: data.id, name: data.name, createdAt: data.created_at } });
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+): Promise<NextResponse> {
+  const gate = await requireActiveSubscription(request);
+  if (gate) return gate;
+
+  const profileId = await getActiveProfileId();
+  if (!profileId) return NextResponse.json({ error: 'No active profile' }, { status: 400 });
+
+  const { id } = await params;
+  const { data, error } = await getServerClient()
+    .from('finance_watchlists')
+    .delete()
+    .eq('id', id)
+    .eq('profile_id', profileId)
+    .select('id')
+    .maybeSingle();
+
+  if (error) {
+    console.error('[finance/watchlists] delete error:', error);
+    return NextResponse.json({ error: 'failed to delete watchlist' }, { status: 500 });
+  }
+  if (!data) return NextResponse.json({ error: 'not found' }, { status: 404 });
+
+  return NextResponse.json({ ok: true });
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Finance watchlists (named lists) — collection routes.
+ *
+ * GET  /api/finance/watchlists           — the active profile's lists (+counts)
+ * POST /api/finance/watchlists {name}     — create a new list
+ *
+ * Paid-gated; profile-scoped (RLS as defense in depth).
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { requireActiveSubscription } from '@/lib/subscription/guard';
+import { getActiveProfileId } from '@/lib/profiles/profile-utils';
+import { sanitizeWatchlistName } from '@/lib/finance/watchlist';
+import { createWatchlist, listWatchlists } from '@/lib/finance/watchlist-db';
+
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: NextRequest): Promise<NextResponse> {
+  const gate = await requireActiveSubscription(request);
+  if (gate) return gate;
+
+  const profileId = await getActiveProfileId();
+  if (!profileId) return NextResponse.json({ error: 'No active profile' }, { status: 400 });
+
+  try {
+    const watchlists = await listWatchlists(profileId);
+    return NextResponse.json({ watchlists });
+  } catch (error) {
+    console.error('[finance/watchlists] list error:', error);
+    return NextResponse.json({ error: 'failed to load watchlists' }, { status: 500 });
+  }
+}
+
+export async function POST(request: NextRequest): Promise<NextResponse> {
+  const gate = await requireActiveSubscription(request);
+  if (gate) return gate;
+
+  const profileId = await getActiveProfileId();
+  if (!profileId) return NextResponse.json({ error: 'No active profile' }, { status: 400 });
+
+  const body = (await request.json().catch(() => null)) as { name?: string } | null;
+  const name = sanitizeWatchlistName(body?.name);
+  if (!name) return NextResponse.json({ error: 'invalid name' }, { status: 400 });
+
+  try {
+    const watchlist = await createWatchlist(profileId, name);
+    return NextResponse.json({ watchlist: { ...watchlist, count: 0 } }, { status: 201 });
+  } catch (error) {
+    console.error('[finance/watchlists] create error:', error);
+    return NextResponse.json({ error: 'failed to create watchlist' }, { status: 500 });
+  }
+}