# Changelog

All notable changes to the Lilith API will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- Enhanced documentation search capabilities
- Interactive API testing improvements
- Additional code generation languages

### Changed

- Improved error message clarity
- Updated SDK documentation structure

### Deprecated

- Legacy authentication endpoints (will be removed in v2.0.0)

### Fixed

- Minor documentation formatting issues
- Code example syntax highlighting

## [1.0.0] - 2023-12-01

### Added

- **Complete AI Chat API** with five distinct personas (Zen Master, Philosopher,
  Stoic, Mystic, Teacher)
- **Advanced Text-to-Speech Synthesis** with multiple high-quality voices and
  SSML support
- **Real-time WebSocket API** for bidirectional communication and streaming
  responses
- **Audio Streaming Capabilities** with HLS and direct streaming support
- **Content Ingestion System** for processing wisdom texts and educational
  materials
- **Push Notification Service** for user engagement and system alerts
- **Comprehensive SDK Support** for TypeScript/JavaScript, Kotlin (Android), and
  Swift (iOS)
- **Interactive Documentation Portal** with "Try It Out" functionality
- **Advanced Citation System** with source attribution and confidence scoring
- **Multi-language Support** for international developers
- **Rate Limiting and Security** with JWT authentication and API key management
- **Developer Dashboard** for API key management and usage analytics

### Security

- JWT-based authentication with automatic token refresh
- Rate limiting to prevent API abuse
- Input validation and sanitization
- HTTPS enforcement with TLS 1.2+
- CORS configuration for web applications

### Documentation

- Complete API reference with OpenAPI 3.1 specification
- Step-by-step integration guides for all supported platforms
- Real-world code examples in multiple programming languages
- WebSocket integration documentation with message format specifications
- Audio streaming implementation guides
- Authentication flow examples with security best practices
- SDK documentation with installation and configuration instructions
- Migration guides for developers upgrading from beta versions

### Performance

- Optimized response times for chat interactions
- Efficient streaming protocols for real-time communication
- CDN integration for global content delivery
- Caching strategies for improved API performance
- Compressed audio formats for bandwidth efficiency

## [0.9.0] - 2023-10-15

### Added

- Beta release of Chat API with basic AI persona support
- Experimental text-to-speech functionality
- WebSocket connection support (limited features)
- Basic authentication system
- Developer documentation portal
- Initial SDK for TypeScript/JavaScript

### Changed

- Improved API response consistency
- Enhanced error handling mechanisms
- Updated authentication flow

### Fixed

- Resolved connection stability issues
- Fixed audio encoding problems
- Corrected documentation examples

### Known Issues

- Limited voice options for TTS
- WebSocket message delivery delays under high load
- Incomplete error code documentation

## [0.8.0] - 2023-09-01

### Added

- Alpha release of core chat functionality
- Basic text-to-speech capabilities
- Simple REST API endpoints
- Preliminary documentation

### Changed

- Initial API structure definition
- Basic error response format

### Fixed

- Core functionality stabilization
- Basic security implementations

---

## Migration Guides

### Upgrading from v0.9 to v1.0

#### Breaking Changes

1. **Chat Request Format**

   ```diff
   // Old format (v0.9)
   {
   -  "message": "Hello",
   -  "ai_type": "zen"
   +  "input": { "text": "Hello" },
   +  "persona": "zen_master",
   +  "mode": "text"
   }
   ```

2. **Authentication Headers**

   ```diff
   // Old format (v0.9)
   - Authorization: Token abc123
   + Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
   ```

3. **WebSocket Message Format**
   ```diff
   // Old format (v0.9)
   {
   -  "type": "message",
   -  "content": "Hello"
   +  "type": "chat",
   +  "data": {
   +    "persona": "zen_master",
   +    "input": { "text": "Hello" }
   +  }
   }
   ```

#### New Features Available

1. **Enhanced AI Personas**: Five distinct personalities with specialized
   training
2. **Advanced Audio**: High-quality TTS with SSML support and multiple voices
3. **Real-time Streaming**: Improved WebSocket API with comprehensive message
   types
4. **Better SDKs**: Native mobile SDKs and enhanced web SDK

#### Migration Steps

1. **Update Authentication**
   - Replace API tokens with JWT tokens
   - Implement token refresh logic
   - Update SDK to v1.0

2. **Migrate Chat Requests**
   - Update request format to new structure
   - Choose appropriate AI persona
   - Handle new response format

3. **Update WebSocket Integration**
   - Implement new message format
   - Handle additional message types
   - Update connection authentication

4. **Test Thoroughly**
   - Test all API integrations in staging
   - Verify audio functionality
   - Validate WebSocket connections

### Upgrading SDKs

#### TypeScript/JavaScript SDK

```bash
# Update to v1.0
npm update @lilith/sdk

# Update import statements
import { LilithClient } from '@lilith/sdk'; // No change needed

// Update initialization
const client = new LilithClient({
  apiKey: 'your-jwt-token', // Changed from 'your-api-token'
  baseURL: 'https://api.lilith.app' // Updated endpoint
});
```

#### Android Kotlin SDK

```kotlin
// Update dependency in build.gradle
implementation 'app.lilith:sdk-kotlin:1.0.0'

// Update initialization
val client = LilithClient.builder()
    .setApiKey("your-jwt-token") // Changed from setToken
    .setBaseUrl("https://api.lilith.app")
    .build()
```

#### iOS Swift SDK

```swift
// Update in Package.swift or CocoaPods
.package(url: "https://github.com/lilith/lilith-swift-sdk", .upToNextMajor(from: "1.0.0"))

// Update initialization
let client = LilithClient(
    apiKey: "your-jwt-token", // Changed from token
    baseURL: "https://api.lilith.app"
)
```

---

## Support Information

### Version Support Policy

- **Current Version (1.0.x)**: Full support with new features, bug fixes, and
  security updates
- **Previous Major (0.x)**: Security updates only until March 2024
- **Beta Versions**: Limited support, deprecated

### Getting Help

- **Documentation**: [https://docs.lilith.app](https://docs.lilith.app)
- **Community Forum**:
  [https://community.lilith.app](https://community.lilith.app)
- **GitHub Issues**:
  [https://github.com/lilith/platform/issues](https://github.com/lilith/platform/issues)
- **Email Support**: [api-support@lilith.app](mailto:api-support@lilith.app)
- **Discord Server**:
  [https://discord.gg/lilith-dev](https://discord.gg/lilith-dev)

### Feature Requests

We welcome feature requests! Please:

1. Check existing requests in our
   [GitHub Issues](https://github.com/lilith/platform/issues)
2. Provide detailed use cases and expected behavior
3. Include code examples when relevant
4. Consider contributing to the discussion on similar requests

### Reporting Issues

When reporting issues, please include:

- API version being used
- SDK version (if applicable)
- Complete error messages and stack traces
- Minimal code example reproducing the issue
- Expected vs. actual behavior
- Environment details (OS, language version, etc.)

---

## Deprecation Notices

### Scheduled for Removal in v2.0.0

- Legacy authentication endpoints (`/v1/auth/token`)
- Old chat message format support
- WebSocket legacy message types
- Deprecated TTS voice IDs

### Timeline

- **90 days before removal**: Deprecation headers added to responses
- **60 days before removal**: Documentation updated with migration guides
- **30 days before removal**: Final warning notifications sent
- **Removal date**: Features completely removed from API

---

## Links

- [Compare v0.9.0...v1.0.0](https://github.com/lilith/platform/compare/v0.9.0...v1.0.0)
- [v1.0.0 Release Notes](https://docs.lilith.app/releases/v1.0.0)
- [Migration Guide v0.9 to v1.0](https://docs.lilith.app/migration/v0.9-to-v1.0)
- [SDK Compatibility Matrix](https://docs.lilith.app/sdk-guides/compatibility)