TypeScript Packages

Table of Contents

• Overview
• Status
• Components
  • Common Utils (@kaido/utils)
  • OpenAI Utils (@kaido/openai-utils)
  • Auth Utils (@kaido/utils)
  • Types (@kaido/types)
• Technical Implementation
  • Package Structure
  • Build Process
• Configuration
• Development Guidelines

Overview

Shared TypeScript packages used across TON Arcana applications. These packages provide common functionality, utilities, and integrations.

Status

• ✅ Common Utils Package
  • Environment utilities
  • Admin utilities
  • Formatting utilities
  • Hash utilities
• ✅ OpenAI Utils Package
  • Chat completion
  • Image generation
  • Embeddings
  • Function calling
  • Cost tracking

NEXT_TASK: Enhance OpenAI Utils cost tracking with detailed usage analytics, budget alerts, and model-specific cost optimization recommendations

• ✅ Auth Utils Package
  • Basic auth middleware
  • Auth utilities
• ✅ Types Package
  • Shared type definitions
  • Common constants
  • Server configurations
• ✅ Ollama Utils Package
  • LLM integration
  • Model management
  • Performance profiling
  • Server statistics

Components

Common Utils (@kaido/utils)

Core utilities package providing:

• Environment checks (production, development, test)
• Admin management and middleware
• Text formatting (HTML, Markdown)
• Hash utilities
• Welcome message generation with:
  • Changelog formatting
  • Recent docs tracking
  • Developer inspiration quotes

OpenAI Utils (@kaido/openai-utils)

OpenAI integration package with:

• Chat completion with retry logic
• Image generation
• Embeddings generation
• Function calling support
• Cost tracking

Auth Utils (@kaido/utils)

Authentication utilities package with:

• Basic auth middleware
• Auth helper functions

Types (@kaido/types)

Shared type definitions and constants:

• Common interfaces
• Type definitions
• Server configurations
• Shared constants

Technical Implementation

Package Structure

packages/
├── common-utils/
│   ├── src/
│   │   ├── admin-utils.ts
│   │   ├── env-utils.ts
│   │   ├── formatting-utils.ts
│   │   └── hash-utils.ts
├── openai-utils/
│   ├── src/
│   │   ├── openai-utils.service.ts
│   │   └── pricing.ts
├── auth-utils/
│   └── src/
│       └── auth-utils.ts
├── types/
│   └── src/
│       ├── constants.ts
│       └── types.ts

Build Process

Packages are built using:

pnpm build:libs

This builds all packages in the correct order.

Configuration

Each package has its own:

• package.json with dependencies
• tsconfig.lib.json for TypeScript configuration
• Jest configuration for tests

Development Guidelines

1. Package Development:

   • Keep packages focused and single-purpose
   • Maintain backward compatibility
   • Include comprehensive tests
   • Document all public APIs

2. Version Management:

   • Use semantic versioning
   • Update CHANGELOG.md
   • Tag releases appropriately

3. Testing:

   • Write unit tests for all functionality
   • Include integration tests where needed
   • Test in both development and production modes

4. Documentation:

   • Document all exports
   • Include usage examples
   • Keep README.md up to date