wealth-alpha-chat

Drop-in React / Next.js chat widget for Wealth Alpha AI — chip-driven flows, JWT auth, 30-minute sliding session, full markdown rendering, AI free-text routing via /intent/detect + /ama/follow-up.

The library is one component (<WealthChat />) plus a backend chat router (chat_widget.py) that proxies your 20 telegram-api endpoints, persists every turn, and returns chip + message responses ready to render.

What you get

8 root chips matching the Telegram bot: Stock Analysis, Stock Discovery, New Listings, Portfolio Risk, Market Forecast, Crypto, Tradable Picks, Peer Comparison
Multi-step flows with chip + free-text inputs (symbol → date → price → result)
Drill-down chips on every list result — click a stock row to dive into its analysis
AI free-text — typed queries get classified by /intent/detect and routed to the right chip flow, with /ama/follow-up for ambiguous queries
30-minute sliding session stored in localStorage["wac_session"]
Auto-discovers JWT from localStorage["token"] (or access_token / auth_token / jwt) — no bridge code required in the host app
Auto-logout — when the host app removes its token (user signs out), the chat clears its session on next render and shows the AuthGate
Server-side history — every turn saved to chat_messages via the team's ChatService
Markdown rendering with markdown-it — bold, italic, bullets, links, code, headings

Repo layout

Wealth-alpha-chat-UI/                         ← the npm library
├── src/
│   ├── components/    WealthChat, AuthGate, ChatBody, MessageBubble, ChipRow, …
│   ├── hooks/         useAuth, useSession, useChat, useChip
│   ├── api/           chatApi.ts (fetch wrapper: timeout, retry, abort, X-Request-Id)
│   ├── utils/         session.ts (JWT auto-discover), markdown.ts (markdown-it)
│   └── styles/        chat.module.css (CSS Modules, brand color via --wac-brand)
├── dist/              tsup build output (ESM + CJS + .d.ts + .css)
├── tsup.config.ts     bundler (preserves "use client" for Next.js App Router)
├── scripts/add-use-client.mjs   post-build directive injector
└── docs/              SETUP.md · PUBLISH.md · DEPLOY.md · BACKEND_CHAT_WIDGET.md

WealthAlpha-Backend/app/api_v1/   ← team's FastAPI backend
├── chat_widget.py     chat router + chip tree + multi-step state + intent routing
├── chat_formatters.py 18 template formatters (LONG_TERM, CRYPTO_ANALYSIS, …)
├── chat.py            team's chat persistence (CRUD)
├── intent.py          team's intent classifier
└── ama.py             team's clarifying-question LLM

Quick install

npm install wealth-alpha-chat

In your app's root (e.g. src/app/layout.tsx for Next.js App Router):

import { WealthChat } from "wealth-alpha-chat";
import "wealth-alpha-chat/styles.css";

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <WealthChat
          apiBase={process.env.NEXT_PUBLIC_API_BASE ?? "http://localhost:8013/api/v1/chat-widget"}
          authCheck="/me"
          loginUrl="/login"
          sessionTTL={1800}
          brandName="Wealth Alpha AI"
          brandColor="#1a2d5a"
          position="bottom-right"
        />
      </body>
    </html>
  );
}

Your existing JWT login (stored under localStorage["token"]) is automatically picked up — no bridge component needed.

For the full integration walkthrough see docs/SETUP.md.

Documentation

Doc	Audience	What it covers
SETUP.md	App developers integrating the widget	Install, mount, env vars, auth bridging, customization
PUBLISH.md	Library maintainers	Version bump, build, npm pack, npm publish, pre-flight checklist
DEPLOY.md	Ops / DevOps	Backend deploy (uvicorn + reverse proxy), frontend deploy, env config, scaling notes
BACKEND_CHAT_WIDGET.md	Backend developers extending the chip tree	How `chat_widget.py` works, chip kinds, multi-step state, formatters, intent routing, drill-down chips

Tech stack

Layer	Tool
UI	React 18 + TypeScript
Bundler	tsup (esbuild) → ESM + CJS + .d.ts + scoped CSS
Styles	CSS Modules — no global pollution
Markdown	markdown-it (XSS-safe, +27 KB)
HTTP	native `fetch` with retry/timeout/abort wrapper
Auth	JWT in `localStorage` (host app key — auto-discovered)
Backend	FastAPI + httpx (loopback to upstream telegram-api endpoints)
State	React Context-less — local hooks per component
Session storage	`localStorage` + in-memory dict per `sessionId` server-side

Development

# Library
cd Wealth-alpha-chat-UI
npm install
npm run dev          # tsup --watch (rebuilds on save)
npm run typecheck    # tsc --noEmit
npm run build        # production bundle to dist/

# Backend (separate terminal)
cd ../WealthAlpha-Backend
source venv/bin/activate
uvicorn main:app --reload --port 8013

# Frontend (separate terminal)
cd ../WealthAlpha-Frontend
npm install ../Wealth-alpha-chat-UI/wealth-alpha-chat-0.1.0.tgz --force
npm run dev          # http://localhost:3000

License

MIT

wealth-alpha-chat-widget