Routstr Chat Frontend

This repository contains the Next.js frontend for the Routstr Chat application.

Features

• Chat UI with conversation history and model selection
• Cashu Lightning wallet integration (deposit, balance, invoice history)
• Nostr support and relay connectivity
• Configurable models and providers
• Persistent storage via localStorage and Zustand stores

Tech Stack

• Next.js 15, React 19, TypeScript 5
• Tailwind CSS 4
• Zustand for state management
• TanStack Query for data fetching/caching
• Cashu TS, Nostr tools

Getting Started

1. Install dependencies

npm install

1. Run the development server

npm run dev

The app will be available at http://localhost:3000.

Scripts

# Start dev server (Turbopack)
npm run dev

# Build production assets
npm run build

# Start production server
npm run start

# Lint
npm run lint

# Invoice-related tests (see Testing below)
npm run test:invoices
npm run test:invoices:integration

# Helper: set up local regtest Cashu mint
npm run test:setup

Testing

This project includes invoice persistence and Lightning integration tests.

• Overview and quick usage: test/README.md
• Full local regtest setup: test/LIGHTNING_TESTING_SETUP.md

Quick start:

# Start Cashu regtest environment (see the guide for details)
cd ~ && git clone https://github.com/callebtc/cashu-regtest.git
cd ~/cashu-regtest && ./start.sh

# From the project root, start mint and run tests
npm run test:setup
npm run test:invoices

When running the app against local regtest:

npm run dev

Then in your browser console set the mint URL (first run):

localStorage.clear();
localStorage.setItem('mint_url', 'http://localhost:3338');
location.reload();

See test/LIGHTNING_TESTING_SETUP.md for a full end-to-end walkthrough and troubleshooting.

Production

Build and run a production server:

npm run build
npm run start

You can deploy using any platform that supports Next.js 15 (Node.js 18+). Ensure required environment variables are set in your hosting provider.

Troubleshooting

• Port conflicts: If 3000 is in use, Next.js will prompt or choose another port.
• Regtest not detected: Verify the mint is running: curl http://localhost:3338/v1/info.
• Invoices not updating:
  • Check that mint_url is set in localStorage
  • Ensure the regtest containers and the mint are up (see test guide)
• Node version: Use Node.js 18 or newer.

Project Structure

Key directories:

• app/: Next.js App Router entry points
• components/: UI components (chat UI, settings, wallet, etc.)
• context/: React context providers
• hooks/: Custom React hooks
• stores/: Zustand stores for wallet and transactions
• utils/ and lib/: Utilities and integrations (Cashu, Nostr)
• test/: Scripts and docs for Lightning/regtest testing

API Mocking with MSW

This project uses Mock Service Worker (MSW) for API mocking in development. This allows you to test error scenarios and edge cases without hitting the real backend.

Testing the 413 Payload Too Large Error

To test the 413 error scenario:

1. Start the development server:

   npm run dev

2. Open the app in your browser and wait for the service worker to initialize (check Network tab for mockServiceWorker.js).

3. Enable the 413 mock scenario in your browser console:

   localStorage.setItem('msw:scenario', '413');
   // Optional: add latency delay
   localStorage.setItem('msw:latency', '1500'); // milliseconds

4. Refresh the page and trigger a chat request. The API call to v1/chat/completions will return a 413 error with the payload:

   {
     "error": {
       "message": "Payload Too Large",
       "code": "PAYLOAD_TOO_LARGE",
       "status": 413
     }
   }

5. Disable the mock when done:

   localStorage.removeItem('msw:scenario');
   localStorage.removeItem('msw:latency');

The mock handler is configured in mocks/handlers.ts and automatically starts in development mode via components/ClientProviders.tsx.

Minibits Mint Mock Data

⚠️ Warning: If you encounter unusual mint errors for Minibits in development mode (e.g., keyset errors, unexpected responses), the cached mock data in mocks/handlers.ts may be outdated. The mock responses for /v1/keysets and /v1/info endpoints should be updated periodically to match the current Minibits mint state.

To update the mock data:

1. Fetch the latest data from the real mint:

   curl https://mint.minibits.cash/Bitcoin/v1/keysets
   curl https://mint.minibits.cash/Bitcoin/v1/info

2. Update the corresponding handlers in mocks/handlers.ts with the fresh responses.

License

MIT