@warriorteam/zalo-webhook-types/CHANGELOG.md

TypeScript types for Zalo Personal webhook events from automation-web

# Changelog

All notable changes to @warriorteam/zalo-webhook-types 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).

## [1.0.0] - 2024-01-XX

### Added
- **Complete type system** for all 57 Zalo Personal webhook event types
- **4 main event categories**:
  - Message Events (44 types) - Text, media, file, and social messages
  - Interaction Events (5 types) - Typing, seen, delivered, reaction, undo
  - Social Events (2 types) - Friend and group events
  - System Events (6 types) - Connection, error, and other system events

### Features
- **Comprehensive enums** for all event types and constants
- **Specific content types** for different message types:
  - `ZaloImageContent` - Image attachments with dimensions
  - `ZaloVideoContent` - Video attachments with duration
  - `ZaloVoiceContent` - Voice recordings
  - `ZaloFileContent` - File attachments
  - `ZaloLocationContent` - Location sharing
  - `ZaloStickerContent` - Sticker messages
- **Type guards** for runtime type checking:
  - Category-level guards (`isMessageEvent`, `isInteractionEvent`, etc.)
  - Specific type guards (`isTextMessage`, `isImageMessage`, etc.)
  - Content type guards (`isAttachmentContent`, `isLocationContent`, etc.)
- **Utility functions** for common operations:
  - `detectMessageType()` - Detect message type from SDK msgType
  - `getMessageCategory()` - Get category from message type
  - `createDetailedMessageEventType()` - Create specific event type
  - `formatFileSize()` - Human readable file sizes
  - `formatDuration()` - Human readable durations
  - `sanitizeContentForLogging()` - Safe content logging

### Type Safety
- **Strict TypeScript types** for all interfaces
- **Union types** for convenient grouping
- **Generic interfaces** where appropriate
- **JSDoc documentation** for all public APIs

### Developer Experience
- **IntelliSense support** in all major IDEs
- **Auto-completion** for all properties and methods
- **Compile-time error checking**
- **Runtime type validation**

### Documentation
- Comprehensive README with examples
- Usage examples for automation-web integration
- Migration guide from existing code
- API documentation with JSDoc

### Build System
- TypeScript compilation to CommonJS
- Declaration files (.d.ts) generation
- Clean build process with rimraf
- ESLint configuration for code quality

### Testing
- Basic SDK functionality test
- Type guard validation
- Utility function testing
- Export verification

## [Unreleased]

### Planned
- Jest test suite with comprehensive coverage
- Additional utility functions based on usage feedback
- Performance optimizations for type guards
- Extended JSDoc documentation
- Examples for other frameworks (Express, Fastify, etc.)

---

## Migration from Local Types

If you're migrating from local type definitions:

1. **Install the SDK**:
   ```bash
   npm install @warriorteam/zalo-webhook-types
   ```

2. **Replace imports**:
   ```typescript
   // Before
   import { ZaloWebhookEvent } from '../types/zalo-webhook-events.types';
   
   // After
   import { ZaloWebhookEvent } from '@warriorteam/zalo-webhook-types';
   ```

3. **Use type guards**:
   ```typescript
   // Before
   if (event.eventType === 'text-message-received-from-user') {
     // manual type checking
   }
   
   // After
   if (isTextMessage(event)) {
     // TypeScript knows this is ZaloTextMessageEvent
   }
   ```

4. **Use utilities**:
   ```typescript
   // Before
   const fileSize = `${Math.round(bytes / 1024)} KB`;
   
   // After
   const fileSize = formatFileSize(bytes); // "2 MB"
   ```

## Breaking Changes

None in v1.0.0 as this is the initial release.

## Support

- **GitHub Issues**: Report bugs and request features
- **Documentation**: Comprehensive README and examples
- **TypeScript**: Full type safety and IntelliSense support