import { useChat } from './src/index'

function MyCustomUI() {
  const { messages, isLoading, error, sendMessage, clearMessages } = useChat({
    proxyUrl: 'https://your-backend.com/api/chat',
    systemPrompt: 'You are a concise assistant.',
  })

  return (
    <div>
      {messages.map((m) => (
        <p key={m.id}><strong>{m.role}:</strong> {m.content}</p>
      ))}
      <button onClick={() => sendMessage('Hello!')}>Send</button>
    </div>
  )
}

Environment Variables

Create a .env file in the project root:

# Option A — direct key (dev only)
VITE_OPENAI_API_KEY=sk-your-key-here

# Option B — proxy (production)
VITE_PROXY_URL=https://your-backend.com/api/chat

# Option C — mock mode (no key needed)
VITE_MOCK_OPENAI=true

Mock Mode

When VITE_MOCK_OPENAI=true (or when VITE_OPENAI_API_KEY is the placeholder sk-your-key-here), the widget streams a canned response locally — no network request is made. This is ideal for:

• UI development without burning API credits
• CI/CD preview environments
• Demos and screenshots

API Reference

<ChatWidget />

useChat(config)

const { messages, isLoading, error, sendMessage, clearMessages } = useChat({
  proxyUrl?: string
  apiKey?: string
  model?: string
  systemPrompt?: string
})

Returns the full chat state and action dispatchers. Use this hook to build a fully custom UI while keeping the streaming logic.

streamChat(options)

Low-level streaming function. Calls OpenAI (or your proxy) and yields StreamChunk objects via an async generator.

import { streamChat } from './src/feature/api/openai'

for await (const chunk of streamChat({ messages, apiKey, model })) {
  if (!chunk.done) process.stdout.write(chunk.delta)
}

withRetry(fn, options?)

Wraps any async function with exponential back-off retry logic.

import { withRetry } from './src/index'

const result = await withRetry(() => fetch('/api/chat'), { retries: 3, delay: 500 })

ChatError

Custom error class thrown by streamChat. Carries a status code for programmatic handling.

import { ChatError, isRateLimitError, isAuthError } from './src/index'

try {
  // ...
} catch (err) {
  if (isRateLimitError(err)) console.warn('Rate limited — slow down')
  if (isAuthError(err)) console.error('Invalid API key')
}

Directory Structure

src/
├── index.ts                  # Public API entry point
├── App.tsx                   # Demo application
└── feature/
    ├── index.ts              # Feature-level re-exports
    ├── api/
    │   ├── openai.ts         # streamChat — real OpenAI SSE streaming
    │   ├── openai.mock.ts    # Mock streaming for dev/demo
    │   └── stream-parser.ts  # SSE response parser
    ├── components/
    │   ├── ChatWidget.tsx    # Main widget component
    │   ├── MessageList.tsx   # Scrollable message history
    │   ├── MessageBubble.tsx # Individual message bubble
    │   └── InputBar.tsx      # Text input + send button
    ├── hooks/
    │   ├── useChat.ts        # Primary chat state hook
    │   └── useStreamingReply.ts # Streaming token accumulator
    ├── types/
    │   └── index.ts          # Shared TypeScript types
    └── utils/
        ├── errors.ts         # ChatError + type guards
        ├── retry.ts          # withRetry utility
        └── sanitize.ts       # Content sanitization

Development

# Start dev server with mock mode (no API key needed)
VITE_MOCK_OPENAI=true npm run dev

# Build for production
npm run build

# Type-check
npm run typecheck

This React web app completed archive review with strong static results. Structure, dependency manifests, documentation, functional source, and common risk patterns were checked by the Tetrees verification pipeline; runtime phases are stated separately. Final verified scores after isolated runtime evidence: overall 8.8 and security 9.