jsq-ticket-type/README.md

TypeScript type definitions for ticket system - microservices types with comprehensive settings management

# jsq-ticket-type

TypeScript type definitions for ticket system - microservices types with comprehensive settings management. This package provides type definitions, interfaces, enums, and constants for consistent data structures between backend and frontend.

## Latest Features (v2.3.0)

🎉 **New Settings Management System**
- **System Settings**: Complete configuration management with categories, validation, and encryption
- **Feature Flags**: Advanced feature flag system with smart targeting and gradual rollouts
- **Email Templates**: Professional email template engine with versioning and localization
- **Settings History**: Complete audit trail for all configuration changes

## Struktur File

```
types/
├── index.ts          # Main export file
├── enums.ts          # All enums from backend (includes settings enums)
├── interfaces.ts     # Entity interfaces and common types (includes settings interfaces)
├── dtos.ts           # Data Transfer Objects for API calls (includes settings DTOs)
├── constants.ts      # Constants and configuration values (includes settings constants)
└── README.md         # This documentation
```

## Penggunaan

## Installation

```bash
npm install jsq-ticket-type
```

### Import Types

```typescript
// Import semua types
import * as TicketTypes from 'jsq-ticket-type';

// Import spesifik
import { UserRole, EventStatus, CreateEventDto } from 'jsq-ticket-type';

// Import dari file tertentu (jika diperlukan)
import { UserRole } from 'jsq-ticket-type/types/enums';
import { User, Event } from 'jsq-ticket-type/types/interfaces';
import { CreateUserDto } from 'jsq-ticket-type/types/dtos';
import { API_ENDPOINTS } from 'jsq-ticket-type/types/constants';
```

### Contoh Penggunaan

#### 1. Menggunakan Enums (Including Settings)

```typescript
import { 
  UserRole, 
  EventStatus, 
  SettingCategory, 
  FeatureFlagStatus, 
  EmailTemplateType 
} from 'jsq-ticket-type';

// Basic enums
const userRole = UserRole.ADMIN;
const eventStatus = EventStatus.PUBLISHED;

// Settings enums
const settingCategory = SettingCategory.SECURITY;
const flagStatus = FeatureFlagStatus.ACTIVE;
const templateType = EmailTemplateType.WELCOME;

// For dropdown options
const categoryOptions = Object.values(SettingCategory).map(category => ({
  value: category,
  label: category.charAt(0) + category.slice(1).toLowerCase()
}));
```

#### 2. Menggunakan Settings Interfaces

```typescript
import { 
  SystemSetting, 
  FeatureFlag, 
  EmailTemplate, 
  SettingsHistory 
} from 'jsq-ticket-type';

// Settings state management
interface SettingsState {
  systemSettings: SystemSetting[];
  featureFlags: FeatureFlag[];
  emailTemplates: EmailTemplate[];
  settingsHistory: SettingsHistory[];
  loading: boolean;
}

// Settings component props
interface SettingsCardProps {
  setting: SystemSetting;
  onEdit: (setting: SystemSetting) => void;
  onDelete: (id: string) => void;
}

// Feature flag evaluation
interface FlagEvaluationContext {
  userId?: string;
  userRole?: string;
  country?: string;
  deviceType?: string;
}
```

#### 3. Menggunakan Settings DTOs

```typescript
import { 
  CreateSystemSettingDto, 
  CreateFeatureFlagDto, 
  CreateEmailTemplateDto,
  EvaluateFeatureFlagDto,
  RenderTemplateDto 
} from 'jsq-ticket-type';

// Create system setting
const createSetting = async (data: CreateSystemSettingDto) => {
  const response = await api.post('/settings', data);
  return response.data;
};

// Evaluate feature flag
const evaluateFlag = async (data: EvaluateFeatureFlagDto) => {
  const response = await api.post('/feature-flags/evaluate', data);
  return response.data;
};

// Render email template
const renderTemplate = async (data: RenderTemplateDto) => {
  const response = await api.post('/email-templates/render', data);
  return response.data;
};

// Settings form validation
const validateSettingForm = (data: Partial<CreateSystemSettingDto>) => {
  const errors: Partial<Record<keyof CreateSystemSettingDto, string>> = {};
  
  if (!data.category) {
    errors.category = 'Category is required';
  }
  
  if (!data.key) {
    errors.key = 'Key is required';
  }
  
  if (data.value === undefined) {
    errors.value = 'Value is required';
  }
  
  return errors;
};
```

#### 4. Menggunakan Settings Constants

```typescript
import { API_ENDPOINTS, STATUS_COLORS, DEFAULTS } from 'jsq-ticket-type';

// Settings API calls
const fetchSettings = () => {
  return api.get(API_ENDPOINTS.SETTINGS.BASE);
};

const fetchFeatureFlags = () => {
  return api.get(API_ENDPOINTS.FEATURE_FLAGS.BASE);
};

const fetchEmailTemplates = () => {
  return api.get(API_ENDPOINTS.EMAIL_TEMPLATES.BASE);
};

// Settings UI styling
const getSettingStatusColor = (setting: SystemSetting) => {
  if (!setting.isActive) return STATUS_COLORS.INACTIVE_SETTING;
  if (setting.isEncrypted) return STATUS_COLORS.ENCRYPTED;
  if (setting.requiresRestart) return STATUS_COLORS.REQUIRES_RESTART;
  return STATUS_COLORS.ACTIVE_SETTING;
};

const getFlagStatusColor = (flag: FeatureFlag) => {
  switch (flag.status) {
    case 'ACTIVE': return STATUS_COLORS.ACTIVE_FLAG;
    case 'TESTING': return STATUS_COLORS.TESTING_FLAG;
    case 'DEPRECATED': return STATUS_COLORS.DEPRECATED_FLAG;
    case 'ARCHIVED': return STATUS_COLORS.ARCHIVED_FLAG;
    default: return STATUS_COLORS.INACTIVE_FLAG;
  }
};

// Default values for forms
const getDefaultSetting = (): Partial<CreateSystemSettingDto> => ({
  category: DEFAULTS.SETTINGS.CATEGORY,
  dataType: DEFAULTS.SETTINGS.DATA_TYPE,
  environment: DEFAULTS.SETTINGS.ENVIRONMENT,
  isActive: DEFAULTS.SETTINGS.IS_ACTIVE,
  isEncrypted: DEFAULTS.SETTINGS.IS_ENCRYPTED,
  requiresRestart: DEFAULTS.SETTINGS.REQUIRES_RESTART,
});

const getDefaultFeatureFlag = (): Partial<CreateFeatureFlagDto> => ({
  type: DEFAULTS.FEATURE_FLAG.TYPE,
  status: DEFAULTS.FEATURE_FLAG.STATUS,
  scope: DEFAULTS.FEATURE_FLAG.SCOPE,
  isEnabled: DEFAULTS.FEATURE_FLAG.IS_ENABLED,
  rolloutPercentage: DEFAULTS.FEATURE_FLAG.ROLLOUT_PERCENTAGE,
  isPermanent: DEFAULTS.FEATURE_FLAG.IS_PERMANENT,
});
```

## File Descriptions

### enums.ts
Berisi semua enum yang digunakan di backend:
- `UserRole` - Role pengguna (admin, promotor, artist, user)
- `EventStatus` - Status event (draft, published, cancelled, dll)
- `OrderStatus` - Status pesanan
- `PaymentStatus` - Status pembayaran
- `NotificationType` - Tipe notifikasi
- **`SettingCategory`** - Kategori pengaturan sistem (SECURITY, EMAIL, PAYMENT, dll)
- **`SettingDataType`** - Tipe data pengaturan (STRING, NUMBER, BOOLEAN, JSON, dll)
- **`SettingEnvironment`** - Environment pengaturan (DEVELOPMENT, STAGING, PRODUCTION, ALL)
- **`FeatureFlagStatus`** - Status feature flag (ACTIVE, INACTIVE, TESTING, dll)
- **`FeatureFlagType`** - Tipe feature flag (BOOLEAN, PERCENTAGE, USER_LIST, dll)
- **`EmailTemplateType`** - Tipe template email (SYSTEM, MARKETING, TRANSACTIONAL, dll)
- Dan lain-lain

### interfaces.ts
Berisi interface untuk entitas dan tipe data umum:
- `User`, `Event`, `Ticket`, `Order`, `Payment` - Entitas utama
- **`SystemSetting`** - Interface pengaturan sistem dengan validasi dan enkripsi
- **`FeatureFlag`** - Interface feature flag dengan targeting dan rollout
- **`EmailTemplate`** - Interface template email dengan versioning dan lokalisasi
- **`SettingsHistory`** - Interface riwayat perubahan pengaturan
- `PaginatedResult<T>` - Hasil dengan pagination
- `ApiResponse<T>` - Response API standar
- `JwtPayload` - Payload JWT token
- Dan lain-lain

### dtos.ts
Berisi Data Transfer Objects untuk API calls:
- `CreateUserDto`, `UpdateUserDto` - DTO untuk user operations
- `CreateEventDto`, `UpdateEventDto` - DTO untuk event operations
- `CreateOrderDto` - DTO untuk membuat pesanan
- `LoginDto` - DTO untuk login
- **`CreateSystemSettingDto`, `UpdateSystemSettingDto`** - DTO untuk pengaturan sistem
- **`CreateFeatureFlagDto`, `UpdateFeatureFlagDto`** - DTO untuk feature flags
- **`CreateEmailTemplateDto`, `UpdateEmailTemplateDto`** - DTO untuk template email
- **`EvaluateFeatureFlagDto`** - DTO untuk evaluasi feature flag
- **`RenderTemplateDto`** - DTO untuk render template email
- **`BulkUpdateSettingsDto`** - DTO untuk update batch pengaturan
- **`SettingsExportDto`, `SettingsImportDto`** - DTO untuk export/import pengaturan
- Dan lain-lain

### constants.ts
Berisi konstanta dan konfigurasi:
- `API_ENDPOINTS` - Endpoint API (termasuk settings endpoints)
- `PAGINATION` - Konfigurasi pagination
- `VALIDATION` - Aturan validasi
- `STATUS_COLORS` - Warna untuk status (termasuk settings status colors)
- `ERROR_MESSAGES` - Pesan error
- `SUCCESS_MESSAGES` - Pesan sukses
- **`DEFAULTS.SETTINGS`** - Default values untuk pengaturan sistem
- **`DEFAULTS.FEATURE_FLAG`** - Default values untuk feature flags
- **`DEFAULTS.EMAIL_TEMPLATE`** - Default values untuk template email
- **`FEATURES`** - Feature toggles (termasuk settings features)
- Dan lain-lain

## Best Practices

### 1. Konsistensi Type
Selalu gunakan types yang sudah didefinisikan daripada membuat type baru:

```typescript
// ✅ Good
import { User } from './scripts/frontend/types';
const user: User = { ... };

// ❌ Bad
interface MyUser {
  id: string;
  name: string;
  // ...
}
```

### 2. Validasi Form
Gunakan DTO types untuk validasi form:

```typescript
import { CreateEventDto } from './scripts/frontend/types';

const validateForm = (data: Partial<CreateEventDto>): boolean => {
  // Validation logic
};
```

### 3. API Response Handling
Gunakan generic types untuk response handling:

```typescript
import { ApiResponse, PaginatedResult, Event } from './scripts/frontend/types';

const fetchEvents = async (): Promise<ApiResponse<PaginatedResult<Event>>> => {
  // API call
};
```

### 4. Enum Usage
Gunakan enum values daripada string literals:

```typescript
import { UserRole } from './scripts/frontend/types';

// ✅ Good
if (user.role === UserRole.ADMIN) { ... }

// ❌ Bad
if (user.role === 'admin') { ... }
```

## Update Process

File-file ini harus diupdate setiap kali ada perubahan struktur data di backend:

1. **Enums**: Update ketika ada penambahan/perubahan enum values
2. **Interfaces**: Update ketika ada perubahan entity structure
3. **DTOs**: Update ketika ada perubahan API request/response format
4. **Constants**: Update ketika ada perubahan endpoint atau konfigurasi

## Integration dengan Frontend Framework

### React + TypeScript
```typescript
import React from 'react';
import { Event, EventStatus } from './scripts/frontend/types';

interface EventListProps {
  events: Event[];
  onStatusChange: (id: string, status: EventStatus) => void;
}

const EventList: React.FC<EventListProps> = ({ events, onStatusChange }) => {
  // Component implementation
};
```

### Vue 3 + TypeScript
```typescript
import { defineComponent, PropType } from 'vue';
import { Event } from './scripts/frontend/types';

export default defineComponent({
  props: {
    event: {
      type: Object as PropType<Event>,
      required: true
    }
  },
  // Component implementation
});
```

### Angular
```typescript
import { Component, Input } from '@angular/core';
import { Event } from './scripts/frontend/types';

@Component({
  selector: 'app-event-card',
  templateUrl: './event-card.component.html'
})
export class EventCardComponent {
  @Input() event!: Event;
}
```

## Troubleshooting

### Common Issues

1. **Import Errors**: Pastikan path import sudah benar
2. **Type Mismatch**: Periksa apakah backend sudah update dengan struktur terbaru
3. **Missing Types**: Tambahkan type yang hilang ke file yang sesuai

### Debugging

```typescript
// Type checking
const user: User = {
  // TypeScript akan memberikan error jika ada field yang hilang
};

// Runtime validation (optional)
const isValidUser = (obj: any): obj is User => {
  return typeof obj.id === 'string' &&
         typeof obj.username === 'string' &&
         typeof obj.email === 'string';
};
```

## Contributing

Ketika menambah atau mengubah types:

1. Pastikan konsisten dengan backend
2. Update dokumentasi jika diperlukan
3. Test dengan frontend application
4. Commit dengan pesan yang jelas

## Version History

- **v2.3.0** - Comprehensive Settings Management System
  - Added complete settings management types (SystemSetting, FeatureFlag, EmailTemplate, SettingsHistory)
  - Added settings-specific enums (SettingCategory, FeatureFlagStatus, EmailTemplateType, etc.)
  - Added comprehensive DTOs for all settings operations
  - Added API endpoints for settings management
  - Added status colors and default values for settings UI
  - Added feature toggles for settings functionality
  - Enhanced documentation with settings examples
- **v2.2.0** - Enhanced user profile management, merchandise system, payment improvements
- **v2.1.0** - Event management system, ticket types, order management
- **v2.0.0** - Initial microservices type definitions
- **v1.1.0** - Updated enum values untuk konsistensi dengan database
  - UserRole: Updated ke UPPERCASE values ('ADMIN', 'PROMOTOR', 'ARTIST', 'USER')
  - ArtistGenre: Updated sesuai database enum (POP, ROCK, JAZZ, dll)
  - Fixes enum mismatch antara TypeScript dan database
- **v1.0.0** - Initial export dari backend microservices
- Includes: User, Event, Ticket, Order, Payment, Notification, Merchandise modules
- Support untuk semua enum, interface, DTO, dan constants