typescript-chatbot-types

name	typescript-chatbot-types
description	TypeScript type safety patterns for chatbot applications with Zod runtime validation. Use when defining API schemas, creating type-safe components, validating user input, or working with LLM responses.
license	MIT
metadata	{"author":"camaral-team","version":"1.0.0","language":"typescript","validation":"zod"}

TypeScript Chatbot Types

Type-safe patterns for building chatbot applications with runtime validation using Zod.

When to Apply

Use this skill when:

• Defining API request/response schemas
• Creating type-safe React components
• Validating user input at runtime
• Working with LLM responses and structured data
• Building type-safe database queries
• Ensuring end-to-end type safety

Key Patterns

1. Core Domain Types (CRITICAL)

Pattern: Define strict types for your chatbot domain

// lib/types/chat.ts

/**
 * Message roles in conversation
 */
export type MessageRole = 'user' | 'assistant' | 'system'

/**
 * A single message in the chat history
 */
export interface Message {
  role: MessageRole
  content: string
  sources?: string[]
  timestamp?: Date
  id?: string
}

/**
 * Request payload for chat API
 */
export interface ChatRequest {
  message: string
  history?: Message[]
  sessionId?: string
}

/**
 * Response from chat API
 */
export interface ChatResponse {
  response: string
  sources: string[]
  metadata?: {
    model: string
    chunks_used?: number
    avg_similarity?: number
    tokens?: number
  }
}

/**
 * Error response structure
 */
export interface ErrorResponse {
  error: string
  code: string
  details?: Record<string, unknown>
}

2. Zod Schemas for Runtime Validation (CRITICAL)

Pattern: Mirror TypeScript types with Zod for runtime safety

// lib/validation/schemas.ts
import { z } from 'zod'

/**
 * Message schema with validation rules
 */
export const messageSchema = z.object({
  role: z.enum(['user', 'assistant', 'system']),
  content: z.string()
    .min(1, 'Message cannot be empty')
    .max(10000, 'Message too long'),
  sources: z.array(z.string()).optional(),
  timestamp: z.date().optional(),
  id: z.string().uuid().optional()
})

/**
 * Chat request schema
 */
export const chatRequestSchema = z.object({
  message: z.string()
    .min(1, 'Message is required')
    .max(1000, 'Message must be less than 1000 characters')
    .trim(),
  history: z.array(messageSchema)
    .max(20, 'History limited to 20 messages')
    .()
    .([]),
  : z.().().()
})


  chatResponseSchema = z.({
  : z.(),
  : z.(z.()),
  : z.({
    : z.(),
    : z.().(),
    : z.().(),
    : z.().()
  }).()
})


   = z.< messageSchema>
   = z.< chatRequestSchema>
   = z.< chatResponseSchema>

3. API Route Type Safety (HIGH)

Pattern: Validate and parse requests with detailed error handling

// app/api/chat/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { chatRequestSchema, type ChatResponse } from '@/lib/validation/schemas'
import { ZodError } from 'zod'

export async function POST(req: NextRequest) {
  try {
    // Parse and validate request body
    const body = await req.json()
    const validatedData = chatRequestSchema.parse(body)
    
    // TypeScript now knows the exact shape
    const { message, history, sessionId } = validatedData
    
    // Generate response (type-safe)
    const response: ChatResponse = await generateChatResponse({
      message,
      history
    })
    
    // Return validated response
    return NextResponse.json(response)
    
  } catch (error) {
    // Handle Zod validation errors
    if (error instanceof ZodError) {
      return NextResponse.(
        {
          : ,
          : ,
          : error..( ({
            : err..(),
            : err.
          }))
        },
        { :  }
      )
    }
    
    
    .(, error)
     .(
      { : , :  },
      { :  }
    )
  }
}

4. Type-Safe Component Props (HIGH)

Pattern: Strictly typed React components with defaults

// components/MessageBubble.tsx
import { type Message } from '@/lib/types/chat'
import { cn } from '@/lib/utils'

interface MessageBubbleProps {
  message: Message
  className?: string
  showSources?: boolean
  onSourceClick?: (source: string) => void
}

export function MessageBubble({
  message,
  className,
  showSources = true,
  onSourceClick
}: MessageBubbleProps) {
  const isUser = message.role === 'user'
  
  return (
    <div className={cn(
      'message-bubble',
      isUser ? 'user-message' : 'assistant-message',
      className
    )}>
      <p>{message.content}</p>
      
      {showSources && message.sources && message.sources.length > 0 && (
        <div className="sources">
          <span =>📚 Basado en:
          
            {message.sources.map((source, i) => (
               onSourceClick?.(source)}
                className={onSourceClick ? 'cursor-pointer hover:underline' : ''}
              >
                {source}
              
            ))}
          
        
      )}
    
  )
}

5. Type-Safe Hooks (MEDIUM)

Pattern: Generic hooks with proper typing

// hooks/useChat.ts
import { useState, useCallback } from 'react'
import { type Message, type ChatRequest, type ChatResponse } from '@/lib/types/chat'

interface UseChatOptions {
  initialMessages?: Message[]
  onError?: (error: Error) => void
}

interface UseChatReturn {
  messages: Message[]
  isLoading: boolean
  error: Error | null
  sendMessage: (content: string) => Promise<void>
  clearMessages: () => void
}

export function useChat(options: UseChatOptions = {}): UseChatReturn {
  const [messages, setMessages] = useState<Message[]>(options.initialMessages || [])
  const [isLoading, setIsLoading] = ()
   [error, setError] = useState< | >()
  
   sendMessage = ( (: ) => {
    ()
    ()
    
    
     :  = {
      : ,
      content,
      :  ()
    }
    ( [...prev, userMessage])
    
     {
      
       :  = {
        : content,
        : messages
      }
      
      
       response =  (, {
        : ,
        : { :  },
        : .(request)
      })
      
       (!response.) {
          ()
      }
      
      
       :  =  response.()
      
      
       :  = {
        : ,
        : data.,
        : data.,
        :  ()
      }
      ( [...prev, assistantMessage])
      
    }  (err) {
       error = err   ? err :  ()
      (error)
      options.?.(error)
      
      
      ( prev.(, -))
    }  {
      ()
    }
  }, [messages, options])
  
   clearMessages = ( {
    ([])
  }, [])
  
   {
    messages,
    isLoading,
    error,
    sendMessage,
    clearMessages
  }
}


 () {
   { messages, isLoading, sendMessage } = ({
    :  .(, error)
  })
  
  
   
}

6. RAG-Specific Types (MEDIUM)

Pattern: Types for vector search and embeddings

// lib/types/rag.ts

/**
 * A chunk of text from the knowledge base
 */
export interface Chunk {
  id: string
  text: string
  source_file: string
  metadata: ChunkMetadata
}

/**
 * Metadata associated with a chunk
 */
export interface ChunkMetadata {
  section?: string
  title?: string
  wordCount?: number
  [key: string]: unknown // Allow additional metadata
}

/**
 * A chunk with its embedding vector
 */
export interface ChunkWithEmbedding extends Chunk {
  embedding: number[] // 1536 dimensions for text-embedding-3-small
}

/**
 * Result from semantic search
 */
export interface RetrievalResult {
  text: string
  source_file: string
  similarity: number
  metadata?: ChunkMetadata
}

/**
 * Options for chunking documents
 */
export   {
  : 
  : 
  : 
}


 { z }  

  chunkMetadataSchema = z.(z.()).(
  z.({
    : z.().(),
    : z.().(),
    : z.().()
  })
)

  chunkSchema = z.({
  : z.().(),
  : z.().(),
  : z.(),
  : chunkMetadataSchema
})

  retrievalResultSchema = z.({
  : z.(),
  : z.(),
  : z.().().(),
  : chunkMetadataSchema.()
})

7. Environment Variables (MEDIUM)

Pattern: Type-safe environment variables with validation

// lib/env.ts
import { z } from 'zod'

/**
 * Environment variables schema
 */
const envSchema = z.object({
  OPENAI_API_KEY: z.string().min(1, 'OpenAI API key is required'),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  DATABASE_PATH: z.string().optional().default('./data/vector_store.db')
})

/**
 * Validated environment variables
 */
export const env = envSchema.parse({
  OPENAI_API_KEY: process.env.OPENAI_API_KEY,
  NODE_ENV: process.env.NODE_ENV,
  DATABASE_PATH: process.env.DATABASE_PATH
})

// Usage: Always use `env` instead of `process.env`
import { env } from '@/lib/env'

const openai = new OpenAI({
  apiKey: env.OPENAI_API_KEY // Type-safe, guaranteed to exist
})

Anti-Patterns

❌ Don't: Use any or skip validation

// BAD: No type safety
async function POST(req: Request) {
  const body: any = await req.json()
  const message = body.message // Could be undefined, wrong type, etc.
}

✅ Do: Validate with Zod

// GOOD: Full type safety
async function POST(req: Request) {
  const body = await req.json()
  const { message } = chatRequestSchema.parse(body) // Throws if invalid
}

❌ Don't: Use loose types

// BAD: Too permissive
interface Message {
  role: string // Should be literal union
  content: any  // Should be string
}

✅ Do: Use strict types

// GOOD: Precise types
interface Message {
  role: 'user' | 'assistant' | 'system'
  content: string
}

Performance Tips

1. Use type inference - type User = z.infer<typeof userSchema>
2. Validate once - Don't re-validate the same data
3. Use discriminated unions - For variant types (user vs assistant messages)
4. Enable strict mode - In tsconfig.json
5. Use const assertions - For immutable data

Testing

// Test Zod schemas
import { describe, it, expect } from 'vitest'
import { chatRequestSchema } from '@/lib/validation/schemas'

describe('chatRequestSchema', () => {
  it('should accept valid request', () => {
    const validRequest = {
      message: 'Hello',
      history: []
    }
    
    expect(() => chatRequestSchema.parse(validRequest)).not.toThrow()
  })
  
  it('should reject empty message', () => {
    const invalidRequest = {
      message: '',
      history: []
    }
    
    expect(() => chatRequestSchema.parse(invalidRequest)).toThrow()
  })
  
  it('should reject too long message', () => {
    const invalidRequest = {
      message: 'a'.repeat(1001),
      history: []
    }
    
    expect(() => chatRequestSchema.parse(invalidRequest)).toThrow()
  })
})

TypeScript Config

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}

References

• Zod Documentation
• TypeScript Handbook
• Next.js with TypeScript
• Total TypeScript Course