jsq-ticket-type

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

npm install jsq-ticket-type

Import Types

// 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)

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

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

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

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:

// ✅ 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:

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

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

3. API Response Handling

Gunakan generic types untuk response handling:

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:

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:

• Enums: Update ketika ada penambahan/perubahan enum values
• Interfaces: Update ketika ada perubahan entity structure
• DTOs: Update ketika ada perubahan API request/response format
• Constants: Update ketika ada perubahan endpoint atau konfigurasi

Integration dengan Frontend Framework

React + 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

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

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

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

Debugging

// 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:

• Pastikan konsisten dengan backend
• Update dokumentasi jika diperlukan
• Test dengan frontend application
• 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