wealth-alpha-chat-widget 1.0.1

package/docs/DEPLOY.md

@@ -0,0 +1,283 @@
+# Deployment guide
+
+Production rollout for the full stack:
+- **Backend** — FastAPI + `chat_widget.py` + `chat_formatters.py`
+- **Library** — published to npm
+- **Frontend** — Next.js consuming the library
+
+---
+
+## 1. Backend (`WealthAlpha-Backend`)
+
+### 1.1 Files that must ship
+
+The chat router introduces two new files on top of the team's existing backend:
+
+```
+app/api_v1/chat_widget.py          ← chip router, multi-step state, intent routing
+app/api_v1/chat_formatters.py      ← 18 template formatters
+```
+
+And `app/api_v1/router.py` must include the widget:
+
+```python
+from app.api_v1 import ..., chat_widget
+
+api_v1_router.include_router(
+    chat_widget.chat_widget_router,
+    prefix="/chat-widget",
+    tags=["chat-widget"],
+)
+```
+
+### 1.2 Dependencies
+
+`requirements.txt` already includes `httpx`, `fastapi`, `pydantic`, `asyncpg`. No extra dependencies needed for the chat widget — `chat_widget.py` reuses what's there.
+
+### 1.3 Environment variables
+
+Reuses the team's existing env vars (`SECRET_KEY`, `DATABASE_URL`, etc.). The widget doesn't introduce new env vars.
+
+### 1.4 Run with uvicorn (single instance)
+
+```bash
+cd WealthAlpha-Backend
+source venv/bin/activate
+pip install -r requirements.txt
+
+uvicorn main:app \
+  --host 0.0.0.0 \
+  --port 8013 \
+  --proxy-headers \
+  --forwarded-allow-ips='*' \
+  --workers 4
+```
+
+- `--proxy-headers` — trusts `X-Forwarded-Proto`/`X-Forwarded-Host` from the reverse proxy so `_base_url_from_request()` returns the correct `https://` URL for the httpx loopback.
+- `--forwarded-allow-ips='*'` — accepts forwarded headers from any upstream proxy IP. Lock down to your specific reverse proxy IP in production.
+- `--workers 4` — fork worker processes. Each has its own `_SessionStore` dict (see §1.6).
+
+### 1.5 Reverse proxy (Nginx)
+
+```nginx
+upstream wealth_backend {
+    server 127.0.0.1:8013;
+}
+
+server {
+    server_name api.your-domain.com;
+    listen 443 ssl http2;
+
+    location /api/v1/chat-widget/ {
+        proxy_pass http://wealth_backend;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_read_timeout 60s;
+    }
+
+    # All other /api/v1/* routes
+    location /api/v1/ {
+        proxy_pass http://wealth_backend;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+### 1.6 Scaling beyond one process
+
+`chat_widget.py` uses an **in-memory `_SessionStore` dict** for multi-step state (`{action, collected, awaiting}` per `sessionId`). This is single-process only.
+
+For multi-worker / multi-instance deploys, swap `_SessionStore` for a Redis-backed implementation:
+
+```python
+import redis.asyncio as redis
+
+class _SessionStore:
+    _TTL_SECONDS = 1800
+    def __init__(self):
+        self._r = redis.from_url(os.environ["REDIS_URL"])
+
+    async def get(self, session_id):
+        raw = await self._r.get(f"wac:{session_id}")
+        return json.loads(raw) if raw else None
+
+    async def set(self, session_id, action, collected, awaiting):
+        await self._r.setex(
+            f"wac:{session_id}",
+            self._TTL_SECONDS,
+            json.dumps({"action": action, "collected": collected, "awaiting": awaiting}),
+        )
+
+    async def clear(self, session_id):
+        await self._r.delete(f"wac:{session_id}")
+```
+
+Update all `sessions.get(...)` / `sessions.set(...)` / `sessions.clear(...)` calls to `await ...`. The TTL stays at 30 min.
+
+### 1.7 Systemd unit (optional)
+
+```ini
+# /etc/systemd/system/wealth-alpha-backend.service
+[Unit]
+Description=Wealth Alpha FastAPI
+After=network.target postgresql.service redis.service
+
+[Service]
+WorkingDirectory=/srv/wealth-alpha/backend
+ExecStart=/srv/wealth-alpha/backend/venv/bin/uvicorn main:app \
+  --host 0.0.0.0 --port 8013 \
+  --proxy-headers --forwarded-allow-ips='*' \
+  --workers 4
+EnvironmentFile=/etc/wealth-alpha/backend.env
+Restart=always
+User=wealth
+Group=wealth
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable wealth-alpha-backend
+sudo systemctl start wealth-alpha-backend
+sudo journalctl -u wealth-alpha-backend -f   # tail logs
+```
+
+---
+
+## 2. Library (npm)
+
+See **[PUBLISH.md](./PUBLISH.md)** — full release flow.
+
+Short version for an existing published library:
+
+```bash
+cd Wealth-alpha-chat-UI
+npm version patch          # or minor / major
+npm run build
+npm publish --access public
+git push --follow-tags
+```
+
+---
+
+## 3. Frontend (Next.js host app)
+
+### 3.1 Install the published library
+
+```bash
+cd WealthAlpha-Frontend
+npm install wealth-alpha-chat@latest
+```
+
+### 3.2 Environment variables
+
+In `.env.production` (or your platform's dashboard — Vercel, Netlify, etc.):
+
+```env
+NEXT_PUBLIC_API_BASE=https://api.your-domain.com/api/v1/chat-widget
+```
+
+The library uses this as `apiBase`. No other env vars are required by the widget itself.
+
+### 3.3 Build & deploy
+
+#### Vercel
+
+```bash
+vercel --prod
+```
+
+Vercel auto-detects Next.js, builds with `next build`, and serves the static + serverless output.
+
+#### Self-hosted
+
+```bash
+cd WealthAlpha-Frontend
+npm ci
+npm run build
+npm run start    # serves on PORT (default 3000)
+```
+
+Behind Nginx:
+
+```nginx
+server {
+    server_name app.your-domain.com;
+    listen 443 ssl http2;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+---
+
+## 4. End-to-end smoke test after deploy
+
+```bash
+# 1. Backend up?
+curl -s https://api.your-domain.com/api/v1/chat-widget/me
+# → {"detail":"Not authenticated"}   ✓ route exists, auth-gated
+
+# 2. Frontend serves the bundled library?
+curl -s https://app.your-domain.com/ | grep -oE "wealth-alpha-chat" | head -1
+# → some occurrence of the package name in the HTML or chunk references
+
+# 3. CORS allows your frontend domain?
+curl -s -I -X OPTIONS https://api.your-domain.com/api/v1/chat-widget/me \
+  -H "Origin: https://app.your-domain.com" \
+  -H "Access-Control-Request-Method: GET"
+# → Access-Control-Allow-Origin: *  (or your specific origin)
+
+# 4. Open https://app.your-domain.com in browser
+# 5. Log in normally
+# 6. Click 💬 → confirm welcome with your name + chips
+# 7. Click any chip → confirm result renders with bold/italic/bullets
+```
+
+---
+
+## 5. Common production issues
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `httpx.ConnectError: SSL` when chat calls upstream | Backend behind reverse proxy but `--proxy-headers` not set | Add `--proxy-headers --forwarded-allow-ips='*'` to uvicorn |
+| `401` on `/chat-widget/me` for all users | Different JWT secret in prod vs the one issuing tokens | Verify `SECRET_KEY` env var matches across services |
+| `403 premium required` on every chip | `telegram_id` not linked for users | Check that `users.telegram_id` is populated. Widget extracts from `current_user.telegram_id`. |
+| Multi-step flow loses state between requests | Multiple uvicorn workers, in-memory `_SessionStore` | Swap to Redis-backed store (§1.6) |
+| Chat history endpoint returns nothing | `ChatService` DB writes failing silently | Check uvicorn logs for "chat_widget: persist_turn failed" errors |
+| Bold rendering doesn't work | Library cached at CDN | Bust CDN cache; verify `wealth-alpha-chat` version in `node_modules` is current |
+
+---
+
+## 6. Monitoring
+
+Recommended log lines to alert on:
+
+- `chat_widget: persist_turn failed` — DB write failed
+- `upstream … unreachable` — telegram-api endpoint down
+- `intent unavailable for user=` — intent classifier down
+- HTTP 5xx on `/chat-widget/*` — chat router crashed
+
+`logger = logging.getLogger("wealth_alpha.chat_widget")` namespace is used throughout. Pipe it to your aggregator (Datadog, Loki, CloudWatch).
+
+For per-request tracing, the library sends `X-Request-Id` header on every chat call. Match it in backend logs:
+
+```python
+# In chat_widget.py — add at the top of each endpoint
+logger.info("chat_widget %s %s req_id=%s",
+            request.method, request.url.path,
+            request.headers.get("x-request-id"))
+```

package/docs/PUBLISH.md

@@ -0,0 +1,202 @@
+# Publishing `wealth-alpha-chat` to npm
+
+How to cut a new version of the library, build it, and push it to the npm registry.
+
+---
+
+## 1. Pre-flight checklist
+
+Run before every publish. Any failure → fix before continuing.
+
+```bash
+# 1. Clean working tree
+git status
+# (should show nothing besides files you intend to publish)
+
+# 2. Typecheck clean
+npm run typecheck
+
+# 3. Build produces dist/ with ESM + CJS + types + CSS
+npm run build
+ls -la dist/
+# Expect: index.mjs, index.cjs, index.d.ts, index.d.cts, index.css
+
+# 4. "use client" directive is preserved at top of both JS outputs (required for Next.js App Router)
+head -1 dist/index.mjs   # "use client";
+head -1 dist/index.cjs   # "use client";
+
+# 5. Bundle size sanity check (< 60 KB total uncompressed is healthy)
+du -sh dist/
+```
+
+---
+
+## 2. Version bump
+
+Follow [semver](https://semver.org/):
+
+| Change | Bump |
+|---|---|
+| Bug fix, no API change | patch (0.1.0 → 0.1.1) |
+| New prop / new export / chip tree extension | minor (0.1.0 → 0.2.0) |
+| Removed/renamed prop, breaking chat-widget protocol | major (0.1.0 → 1.0.0) |
+
+```bash
+npm version patch    # → 0.1.1
+npm version minor    # → 0.2.0
+npm version major    # → 1.0.0
+```
+
+This automatically updates `package.json` and creates a `vX.Y.Z` git tag.
+
+---
+
+## 3. Dry-run with `npm pack`
+
+Always pack first to inspect what npm will publish:
+
+```bash
+npm pack
+# → wealth-alpha-chat-0.1.0.tgz
+
+tar -tzf wealth-alpha-chat-0.1.0.tgz | head -30
+```
+
+The tarball should contain:
+- `package/package.json`
+- `package/README.md`
+- `package/dist/index.mjs`, `dist/index.cjs`, `dist/index.d.ts`, `dist/index.d.cts`, `dist/index.css`
+- `dist/*.map` (source maps)
+
+It should **NOT** contain:
+- `src/` (we ship compiled output only — `.npmignore` blocks it)
+- `node_modules/`
+- `examples/`
+- `*.config.ts`, `tsconfig.json`
+- internal docs `WEALTH_ALPHA_CHAT_PLAN.md`, `api_response.md`
+
+---
+
+## 4. Test the tarball locally in a fresh project
+
+Before pushing to npm, sanity-check by installing the tarball into a real consumer:
+
+```bash
+cd ~/test-project
+npm install /abs/path/to/wealth-alpha-chat-0.1.0.tgz --force
+npm run dev
+# manually click through chat flows
+```
+
+---
+
+## 5. Login to npm
+
+First time only:
+
+```bash
+npm login
+# Enter username, password, email, OTP
+```
+
+Verify:
+
+```bash
+npm whoami
+# → your-npm-username
+```
+
+---
+
+## 6. Publish
+
+```bash
+npm publish --access public
+```
+
+`--access public` is required for scoped packages and any package on a new account. For an unscoped public package it's still safe to include.
+
+You should see:
+
+```
++ wealth-alpha-chat@0.1.0
+```
+
+Confirm on npmjs.com:
+
+```bash
+npm view wealth-alpha-chat
+```
+
+---
+
+## 7. Push the git tag
+
+```bash
+git push --follow-tags
+```
+
+This pushes both the version bump commit and the `vX.Y.Z` tag.
+
+---
+
+## 8. Post-publish smoke test
+
+Spin up an empty Next.js project, install from npm (not the tarball), and verify the widget mounts:
+
+```bash
+npx create-next-app@latest test-app --typescript --app
+cd test-app
+npm install wealth-alpha-chat
+# Add <WealthChat /> to src/app/layout.tsx per SETUP.md
+npm run dev
+# Open http://localhost:3000, confirm 💬 appears, click → AuthGate renders
+```
+
+---
+
+## 9. Handling failures
+
+| Failure | Fix |
+|---|---|
+| `403 Forbidden — version already exists` | Bump the version (`npm version patch`) and try again — npm doesn't allow republishing the same version. |
+| `EPUBLISHCONFLICT` | Same as above. |
+| `EINVALIDTAGNAME` | `npm version` couldn't create the git tag — usually because the working tree has uncommitted changes. Commit or stash, retry. |
+| `ENEEDAUTH` | Re-run `npm login`. |
+| `Bundle size unexpectedly grew` | Check `package.json` `dependencies` — only `markdown-it` should be there. React/React-DOM must stay in `peerDependencies`. |
+| `Next.js App Router consumers see "Cannot use React Hook"` | The `"use client"` directive got stripped. Re-run `npm run build` and verify with `head -1 dist/index.mjs` that the directive is still there. The `scripts/add-use-client.mjs` post-build script re-injects it. |
+
+---
+
+## 10. Rollback / deprecate
+
+If a version is broken in the wild:
+
+```bash
+# Mark a version as deprecated (doesn't unpublish, but warns on install)
+npm deprecate wealth-alpha-chat@0.1.0 "Use 0.1.1 instead — fixes critical chip-routing bug"
+
+# Within 72 hours of publish, you CAN unpublish
+npm unpublish wealth-alpha-chat@0.1.0
+```
+
+After 72 hours npm doesn't allow unpublish. Always prefer deprecate + push a patch.
+
+---
+
+## 11. Release notes
+
+Write release notes in `CHANGELOG.md` (one section per version) and tag the GitHub release with them:
+
+```md
+## 0.1.1 — 2026-05-28
+
+### Fixed
+- Chip path no longer doubles when apiBase ends with `/chat-widget`.
+- Library reads `localStorage["token"]` as a fallback when `wac_session` is empty.
+
+### Added
+- markdown-it rendering for bot bubbles (bold, italic, bullets, links).
+- Drill-down chips on list results (Smart Money Picks, Discovery, Crypto List, Peer).
+- Telegram-style chip flows for Stock Analysis, Portfolio Risk, Crypto, Market Forecast.
+```

package/docs/SETUP.md

@@ -0,0 +1,180 @@
+# Setup guide — integrating `wealth-alpha-chat` into a host app
+
+This is what a consumer (React or Next.js project) needs to do to mount the chat widget.
+
+---
+
+## 1. Install
+
+```bash
+npm install wealth-alpha-chat
+# or
+yarn add wealth-alpha-chat
+# or
+pnpm add wealth-alpha-chat
+```
+
+**Peer requirements**: React ≥ 17, React DOM ≥ 17. No other peers.
+
+---
+
+## 2. Import the CSS once
+
+The library ships scoped CSS Modules, but the consumer must include the stylesheet once globally.
+
+### Next.js App Router (`src/app/layout.tsx`)
+
+```tsx
+import "wealth-alpha-chat/styles.css";
+```
+
+### Vite / CRA (`src/main.tsx` or `src/index.tsx`)
+
+```tsx
+import "wealth-alpha-chat/styles.css";
+```
+
+---
+
+## 3. Mount the widget
+
+Add `<WealthChat />` somewhere it stays mounted on every page — typically the root layout, outside the page content. The widget renders a floating button that opens a chat panel.
+
+```tsx
+import { WealthChat } from "wealth-alpha-chat";
+
+<WealthChat
+  apiBase="https://api.your-domain.com/api/v1/chat-widget"
+  authCheck="/me"
+  loginUrl="/login"
+  sessionTTL={1800}
+  brandName="Wealth Alpha AI"
+  brandColor="#1a2d5a"
+  position="bottom-right"
+/>
+```
+
+### Props
+
+| Prop | Type | Required | Default | Purpose |
+|---|---|---|---|---|
+| `apiBase` | string | ✅ | — | Base URL of the chat-widget backend. Library appends `/me`, `/chip/{id}`, `/message`. **Do not include `/chat/`** in the suffix or the path doubles. |
+| `authCheck` | string | ❌ | `"/me"` | Path appended to `apiBase` for the auth check. |
+| `loginUrl` | string | ✅ | — | Where the AuthGate's "Sign in" button redirects. |
+| `sessionTTL` | number (seconds) | ❌ | `1800` | Sliding-window session expiry. Resets on each chip/message. |
+| `welcomeMessage` | string | ❌ | uses backend's `/me` `welcomeMessage` | Override the welcome bubble text. |
+| `brandName` | string | ❌ | `"Wealth Alpha AI"` | Shown in the chat header and AuthGate. |
+| `brandColor` | string (CSS color) | ❌ | `"#1a2d5a"` | Header background, floating button, primary buttons. Exposed as `--wac-brand` CSS variable. |
+| `position` | `"bottom-right"` \| `"bottom-left"` | ❌ | `"bottom-right"` | Floating button + panel anchor. |
+| `defaultOpen` | boolean | ❌ | `false` | Open the chat panel on mount instead of just showing the floating button. |
+| `showCountdown` | boolean | ❌ | `true` | Show "Session: 23m left" in the header. |
+| `onLogin` | `() => void` | ❌ | — | Fires when the chat detects a valid JWT and shows the welcome message. |
+| `onLogout` | `() => void` | ❌ | — | Fires when the session is cleared. |
+| `onSessionExpire` | `() => void` | ❌ | — | Fires when the sliding-window TTL expires. |
+| `onError` | `(err: Error) => void` | ❌ | — | Fires on auth or network errors. |
+
+---
+
+## 4. Authentication — automatic JWT pickup
+
+The library auto-discovers a JWT from `localStorage`. It checks these keys in order:
+
+1. `wac_session.token` (full session object — set by the library itself or a bridge)
+2. `token` ← **your normal login key**
+3. `access_token`
+4. `auth_token`
+5. `jwt`
+
+So if your existing login already stores the JWT under `localStorage["token"]`, **no bridge code is needed**. The widget will pick it up on next render or `storage` event.
+
+### Auto-logout
+
+When the chat adopts a JWT from a fallback key it stamps the session with `bootSource: "fallback"`. On every read, if the fallback key is gone, the cached `wac_session` is cleared too — so when the host app calls `localStorage.removeItem("token")` on logout, the chat falls back to the AuthGate within one tick. No `onLogout` plumbing required.
+
+If you set `wac_session` directly (not via a fallback key), the auto-logout doesn't apply — you control its lifecycle.
+
+### What if my token is in a different key?
+
+Either rename your storage key to one of the above, or set `wac_session` directly:
+
+```ts
+localStorage.setItem("wac_session", JSON.stringify({
+  token: yourJwtString,
+  userId: "u_xxx",
+  sessionId: crypto.randomUUID(),
+  expiresAt: Date.now() + 30 * 60 * 1000,
+  lastActive: Date.now(),
+  history: [],
+}));
+```
+
+### What if my token is in an httpOnly cookie?
+
+The library only reads JWTs from `localStorage`. For cookie-based auth, you need to either:
+- Set `credentials: "include"` in your fetch wrapper (would require library change), or
+- Expose a small endpoint that returns the JWT for the logged-in user and write it to `localStorage` on login.
+
+---
+
+## 5. Environment variables
+
+| Variable | Where | Purpose |
+|---|---|---|
+| `NEXT_PUBLIC_API_BASE` | Next.js host app | Override the default `apiBase`. Recommended pattern: `process.env.NEXT_PUBLIC_API_BASE ?? "http://localhost:8013/api/v1/chat-widget"` |
+
+You can also wire `brandColor`, `brandName`, etc. from env vars if you want them per-environment.
+
+---
+
+## 6. Hiding the widget on auth pages
+
+Don't render `<WealthChat />` on `/login`, `/register`, or admin pages:
+
+```tsx
+const AUTH_PATHS = ["/login", "/register"];
+const isAuthPage = AUTH_PATHS.includes(pathname);
+const isAdmin = pathname.startsWith("/admin");
+
+{!isAuthPage && !isAdmin && <WealthChat ... />}
+```
+
+---
+
+## 7. Theming
+
+Override the brand color via prop **or** with a CSS variable in your global styles:
+
+```css
+.landing-theme {
+  --wac-brand: #1a2d5a;            /* default */
+  --wac-brand-contrast: #ffffff;
+  --wac-bg: #ffffff;
+  --wac-fg: #1f2937;
+  --wac-muted: #6b7280;
+  --wac-border: #e5e7eb;
+  --wac-bot-bg: #f3f4f6;
+  --wac-user-bg: var(--wac-brand);
+  --wac-chip-bg: #eef2ff;
+  --wac-chip-fg: #1e293b;
+  --wac-radius: 14px;
+  --wac-shadow: 0 12px 40px rgba(0, 0, 0, 0.18);
+}
+```
+
+All chat colors are CSS-variable-driven so dark mode can be added by toggling a class on `<html>`.
+
+---
+
+## 8. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| 💬 button doesn't appear | Library not bundled, or `<WealthChat>` not mounted | Verify import compiles; check the layout actually renders it |
+| Clicking 💬 shows AuthGate even when logged in | JWT not in `localStorage` under one of the auto-discovered keys (`token`, `access_token`, `auth_token`, `jwt`) | DevTools → Application → Local Storage → rename your key, or write `wac_session` directly (see §3) |
+| `401 Unauthorized` on `/chat-widget/me` | JWT invalid / expired / wrong issuer | Re-login; verify your backend's `get_current_user` accepts the JWT format |
+| `404 /chat-widget/chat/chip/...` (path doubled) | `apiBase` already includes `/chat-widget` AND old library version | Update to library ≥ 0.1.0 which uses `/chip/{id}` not `/chat/chip/{id}` |
+| Stuck "compiling" on first chat open | Next.js dev cold-start | Wait ~5 s for first compile, subsequent loads are instant |
+| Bold text shows as literal `*asterisks*` | Library not rebuilt after markdown-it added | Update to library ≥ 0.1.0 |
+| Floating button + dark area visible behind chat panel | Page background bleeding through | Library widget is positioned correctly; check that no global CSS overrides `position: fixed` on the widget div |
+
+For backend-side issues (chip not routing, wrong endpoint called, `telegram_id` missing) see **[BACKEND_CHAT_WIDGET.md](./BACKEND_CHAT_WIDGET.md)**.