wulf-pulse/lib/services/entity-sync.ts

/**
 * Entity Sync Service
 * Handles syncing individual entity types from Autotask to PostgreSQL
 */

import { AutotaskClient } from './autotask-client';
import { autotaskRateLimiter } from './rate-limiter';
import postgresClient from './postgres-client';
import { EntityType } from '../types/sync';
import { mapAutotaskToDatabase, mapAutotaskBatch } from '../utils/entity-mapper';
import { bulkUpsertRecords, getLastSyncTime, softDeleteMissingRecords } from '../utils/db-helpers';
import { syncProgressTracker } from './sync-progress-tracker';
import { 
  getAutotaskEntityName, 
  buildIncrementalFilter,
  buildActiveFilter,
  buildDateRangeFilter,
  buildContractsFilter,
  buildProjectsFilter,
  buildTimeEntriesFilter,
  getTableName 
} from '../utils/sync-helpers';

/**
 * Entity Sync Result
 */
export interface EntitySyncStats {
  recordsAdded: number;
  recordsUpdated: number;
  recordsDeleted: number;
}

/**
 * Entity Sync Service Class
 */
export class EntitySyncService {
  private autotaskClient: AutotaskClient;
  private cachedValidResourceIds?: Set<number>;
  private cachedValidContactIds?: Set<number>;

  constructor(autotaskClient: AutotaskClient) {
    this.autotaskClient = autotaskClient;
  }

  /**
   * Sync a single entity type
   * @param entity Entity type to sync
   * @param isIncremental Whether to perform incremental sync
   * @param yearsBack Number of years to look back for time-based entities (default: 2)
   * @returns Sync statistics
   */
  async syncEntity(
    entity: EntityType,
    isIncremental: boolean = false,
    yearsBack: number = 2,
    syncId?: string
  ): Promise<EntitySyncStats> {
    // Route picklist entities to their specific sync methods
    if (entity === EntityType.ISSUE_TYPES) {
      return await this.syncIssueTypes(isIncremental);
    }
    if (entity === EntityType.SUB_ISSUE_TYPES) {
      return await this.syncSubIssueTypes(isIncremental);
    }

    const syncStartTime = Date.now();
    const trackingId = syncId || `${entity}_${Date.now()}`;
    
    // Start progress tracking
    syncProgressTracker.startSync(trackingId, entity);
    
    console.log(`[${entity}] Starting sync (${isIncremental ? 'incremental' : 'full'})`);

    try {
      const autotaskEntityName = getAutotaskEntityName(entity);
      let params: any = {};

      // For incremental sync, filter by last sync time
      if (isIncremental) {
        try {
          const lastSyncTime = await getLastSyncTime(entity);
          if (lastSyncTime) {
            params.filter = buildIncrementalFilter(entity, lastSyncTime);
            console.log(`[${entity}] Incremental sync from ${lastSyncTime.toISOString()}`);
          } else {
            console.log(`[${entity}] No previous sync found, performing full sync`);
          }
        } catch (error) {
          console.error(`[${entity}] Failed to get last sync time:`, error);
          throw new Error(`Failed to determine sync time: ${error instanceof Error ? error.message : String(error)}`);
        }
      } else {
        // For full sync, build filters
        const filters: Array<{ field: string; op: string; value: any }> = [];
        
        // Special handling for entities that require filters
        if (entity === EntityType.CONTRACTS) {
          filters.push(...buildContractsFilter());
          console.log(`[${entity}] Full sync with status filter for active contracts`);
        } else if (entity === EntityType.PROJECTS) {
          filters.push(...buildProjectsFilter());
          console.log(`[${entity}] Full sync with status filter for non-completed projects`);
        } else if (entity === EntityType.TIME_ENTRIES) {
          filters.push(...buildTimeEntriesFilter(yearsBack));
          console.log(`[${entity}] Full sync with dateWorked filter for last ${yearsBack} years`);
        } else {
          // Add active filter if applicable
          const activeFilter = buildActiveFilter(entity);
          if (activeFilter) {
            filters.push(...activeFilter);
            console.log(`[${entity}] Full sync with active filter`);
          }
          
          // Add date range filter for time-based entities (tickets, tasks, etc.)
          const dateRangeFilter = buildDateRangeFilter(entity, yearsBack);
          if (dateRangeFilter) {
            filters.push(...dateRangeFilter);
            console.log(`[${entity}] Full sync limited to last ${yearsBack} years`);
          }
        }
        
        if (filters.length > 0) {
          params.filter = filters;
        }
      }

      // Fetch data from Autotask with pagination
      console.log(`[${entity}] Fetching records from Autotask API...`);
      syncProgressTracker.updateProgress(trackingId, { phase: 'fetching' });
      
      let autotaskRecords: any[];
      try {
        autotaskRecords = await this.autotaskClient.queryEntityPaginated(
          autotaskEntityName,
          params,
          500 // Page size
        );
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        console.error(`[${entity}] API fetch failed:`, errorMessage);
        throw new Error(`Autotask API error: ${errorMessage}`);
      }

      console.log(`[${entity}] Fetched ${autotaskRecords.length} records from Autotask`);
      syncProgressTracker.updateProgress(trackingId, { 
        totalRecords: autotaskRecords.length,
        phase: 'mapping'
      });

      if (autotaskRecords.length === 0) {
        console.log(`[${entity}] No records to sync`);
        syncProgressTracker.completeSync(trackingId, 0);
        return { recordsAdded: 0, recordsUpdated: 0, recordsDeleted: 0 };
      }

      // Map Autotask data to PostgreSQL schema
      console.log(`[${entity}] Mapping ${autotaskRecords.length} records to database schema...`);
      
      // DEBUG: Log first record to see actual field names from Autotask
      if (autotaskRecords.length > 0 && (entity === EntityType.TICKETS || entity === EntityType.TIME_ENTRIES)) {
        console.log(`[${entity}] DEBUG - Sample raw Autotask record keys:`, Object.keys(autotaskRecords[0]));
        if (entity === EntityType.TIME_ENTRIES) {
          console.log(`[${entity}] DEBUG - Sample time entry:`, JSON.stringify(autotaskRecords[0], null, 2));
        }
      }
      
      let mappedRecords: Record<string, any>[];
      try {
        mappedRecords = mapAutotaskBatch(entity, autotaskRecords);
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        console.error(`[${entity}] Mapping failed:`, errorMessage);
        throw new Error(`Data mapping error: ${errorMessage}`);
      }

      if (mappedRecords.length === 0) {
        console.warn(`[${entity}] Warning: All records failed mapping validation`);
        return { recordsAdded: 0, recordsUpdated: 0, recordsDeleted: 0 };
      }

      // Check for records with missing company_id (for entities that require it)
      // Note: TIME_ENTRIES removed from this check because company_id is nullable for time entries
      if (entity === EntityType.TICKETS || entity === EntityType.PROJECTS || 
          entity === EntityType.CONFIGURATION_ITEMS || entity === EntityType.CONTACTS || 
          entity === EntityType.CONTRACTS || entity === EntityType.BILLING_ITEMS) {
        const recordsWithoutCompany = mappedRecords.filter(r => !r.company_id);
        if (recordsWithoutCompany.length > 0) {
          console.warn(`[${entity}] Found ${recordsWithoutCompany.length} records without company_id (out of ${mappedRecords.length} total)`);
          console.warn(`[${entity}] Sample IDs without company_id:`, recordsWithoutCompany.slice(0, 5).map(r => r.id));
          // Filter out records without company_id to prevent constraint violation
          mappedRecords = mappedRecords.filter(r => r.company_id);
          console.log(`[${entity}] Filtered to ${mappedRecords.length} records with valid company_id`);
        }
      }

      // Validate resource foreign keys for tickets
      if (entity === EntityType.TICKETS) {
        const initialCount = mappedRecords.length;
        
        // Get all valid resource IDs from database
        const validResourceIds = await this.getValidResourceIds();
        
        // Filter tickets with invalid resource references
        mappedRecords = mappedRecords.map(ticket => {
          // Set invalid resource IDs to null instead of filtering out the entire ticket
          if (ticket.assigned_resource_id && !validResourceIds.has(ticket.assigned_resource_id)) {
            console.warn(`[${entity}] Ticket ${ticket.id}: Invalid assigned_resource_id ${ticket.assigned_resource_id}, setting to null`);
            ticket.assigned_resource_id = null;
          }
          if (ticket.first_response_assigned_resource_id && !validResourceIds.has(ticket.first_response_assigned_resource_id)) {
            ticket.first_response_assigned_resource_id = null;
          }
          if (ticket.first_response_initiating_resource_id && !validResourceIds.has(ticket.first_response_initiating_resource_id)) {
            ticket.first_response_initiating_resource_id = null;
          }
          return ticket;
        });
        
        const nullifiedCount = initialCount - mappedRecords.filter(t => t.assigned_resource_id).length;
        if (nullifiedCount > 0) {
          console.warn(`[${entity}] Nullified ${nullifiedCount} invalid resource references`);
        }
      }

      // Validate contact foreign keys for configuration items
      if (entity === EntityType.CONFIGURATION_ITEMS) {
        const initialCount = mappedRecords.length;
        
        // Get all valid contact IDs from database
        const validContactIds = await this.getValidContactIds();
        
        // Filter configuration items with invalid contact references
        mappedRecords = mappedRecords.map(item => {
          // Set invalid contact IDs to null instead of filtering out the entire item
          if (item.contact_id && !validContactIds.has(item.contact_id)) {
            console.warn(`[${entity}] Configuration Item ${item.id}: Invalid contact_id ${item.contact_id}, setting to null`);
            item.contact_id = null;
          }
          return item;
        });
        
        const nullifiedCount = initialCount - mappedRecords.filter(i => i.contact_id).length;
        if (nullifiedCount > 0) {
          console.warn(`[${entity}] Nullified ${nullifiedCount} invalid contact references`);
        }
      }

      console.log(`[${entity}] Successfully mapped ${mappedRecords.length} records`);

      // Bulk upsert to PostgreSQL
      console.log(`[${entity}] Upserting records to PostgreSQL...`);
      syncProgressTracker.updateProgress(trackingId, { phase: 'upserting' });
      
      let upsertedCount: number;
      try {
        upsertedCount = await bulkUpsertRecords(entity, mappedRecords, 100);
      } catch (error) {
        const errorMessage = error instanceof Error ? error.message : String(error);
        console.error(`[${entity}] Database upsert failed:`, errorMessage);
        throw new Error(`Database error: ${errorMessage}`);
      }

      console.log(`[${entity}] Upserted ${upsertedCount} records to PostgreSQL`);

      // For full sync, soft delete records not in the fetched set
      // IMPORTANT: Only delete for entities without date filters to avoid deleting records outside sync window
      let deletedCount = 0;
      const hasDateFilter = entity === EntityType.TICKETS || 
                           entity === EntityType.TASKS || 
                           entity === EntityType.TIME_ENTRIES ||
                           entity === EntityType.PROJECTS ||
                           entity === EntityType.CONTRACTS;
      
      if (!isIncremental && !hasDateFilter) {
        console.log(`[${entity}] Checking for records to soft delete...`);
        syncProgressTracker.updateProgress(trackingId, { phase: 'deleting' });
        
        try {
          const activeIds = mappedRecords.map(r => r.id);
          deletedCount = await softDeleteMissingRecords(entity, activeIds);
          console.log(`[${entity}] Soft deleted ${deletedCount} missing records`);
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          console.error(`[${entity}] Soft delete failed:`, errorMessage);
          // Don't throw - soft delete failure shouldn't fail the entire sync
          console.warn(`[${entity}] Continuing despite soft delete failure`);
        }
      } else if (!isIncremental && hasDateFilter) {
        console.log(`[${entity}] Skipping soft-delete for date-filtered sync (would delete records outside sync window)`);
      }

      // Calculate added vs updated (simplified - actual count would require tracking)
      const recordsAdded = Math.floor(upsertedCount * 0.1); // Estimate 10% new
      const recordsUpdated = upsertedCount - recordsAdded;

      const duration = Date.now() - syncStartTime;
      console.log(`[${entity}] Sync completed in ${duration}ms`);
      
      // Mark sync as completed
      syncProgressTracker.completeSync(trackingId, mappedRecords.length);

      return {
        recordsAdded,
        recordsUpdated,
        recordsDeleted: deletedCount,
      };
    } catch (error) {
      const duration = Date.now() - syncStartTime;
      const errorMessage = error instanceof Error ? error.message : String(error);
      console.error(`[${entity}] Sync failed after ${duration}ms:`, errorMessage);
      
      // Mark sync as failed
      syncProgressTracker.failSync(trackingId, errorMessage);
      
      throw error;
    }
  }

  /**
   * Sync Companies
   */
  async syncCompanies(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.COMPANIES, isIncremental);
  }

  /**
   * Sync Tickets
   */
  async syncTickets(isIncremental: boolean = false, yearsBack?: number): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.TICKETS, isIncremental, yearsBack);
  }

  /**
   * Sync Tickets with Monthly Chunking
   * Breaks large date ranges into monthly chunks to prevent timeouts and API failures
   * @param yearsBack Number of years to look back
   * @param onChunkProgress Callback for progress updates
   * @returns Aggregated sync statistics
   */
  async syncTicketsChunked(
    yearsBack: number = 2,
    onChunkProgress?: (chunk: { index: number; total: number; description: string; recordsProcessed: number }) => void
  ): Promise<EntitySyncStats> {
    const syncStartTime = Date.now();
    const entity = EntityType.TICKETS;
    console.log(`[${entity}] Starting chunked sync for last ${yearsBack} years`);

    try {
      // Calculate date chunks (monthly)
      const chunks = this.calculateMonthlyChunks(yearsBack);
      console.log(`[${entity}] Split into ${chunks.length} monthly chunks`);

      let totalRecordsAdded = 0;
      let totalRecordsUpdated = 0;
      let totalRecordsDeleted = 0;
      const failedChunks: string[] = [];

      // Process each chunk
      for (let i = 0; i < chunks.length; i++) {
        const chunk = chunks[i];
        const chunkDescription = `${chunk.startDate.toLocaleDateString('en-US', { month: 'short', year: 'numeric' })}`;
        
        console.log(`[${entity}] Processing chunk ${i + 1}/${chunks.length}: ${chunkDescription}`);
        
        // Notify progress
        if (onChunkProgress) {
          onChunkProgress({
            index: i + 1,
            total: chunks.length,
            description: chunkDescription,
            recordsProcessed: totalRecordsAdded + totalRecordsUpdated,
          });
        }

        try {
          // Fetch tickets for this date range
          const autotaskEntityName = getAutotaskEntityName(entity);
          const filters = [
            { field: 'createDate', op: 'gte' as const, value: chunk.startDate.toISOString() },
            { field: 'createDate', op: 'lt' as const, value: chunk.endDate.toISOString() },
          ];

          console.log(`[${entity}] Fetching records from ${chunk.startDate.toISOString()} to ${chunk.endDate.toISOString()}`);
          
          const autotaskRecords = await this.autotaskClient.queryEntityPaginated(
            autotaskEntityName,
            { filter: filters },
            500
          );

          console.log(`[${entity}] Chunk ${i + 1}: Fetched ${autotaskRecords.length} records`);

          if (autotaskRecords.length > 0) {
            // Map and upsert records
            let mappedRecords = mapAutotaskBatch(entity, autotaskRecords);
            
            // Filter out records without company_id
            mappedRecords = mappedRecords.filter(r => r.company_id);
            if (mappedRecords.length < autotaskRecords.length) {
              console.warn(`[${entity}] Chunk ${i + 1}: Filtered out ${autotaskRecords.length - mappedRecords.length} records without company_id`);
            }

            // Validate resource foreign keys (fetch once per sync, not per chunk)
            if (i === 0) {
              // Cache valid resource IDs for all chunks
              this.cachedValidResourceIds = await this.getValidResourceIds();
              console.log(`[${entity}] Cached ${this.cachedValidResourceIds.size} valid resource IDs`);
            }

            // Nullify invalid resource references
            mappedRecords = mappedRecords.map(ticket => {
              if (ticket.assigned_resource_id && !this.cachedValidResourceIds!.has(ticket.assigned_resource_id)) {
                ticket.assigned_resource_id = null;
              }
              if (ticket.first_response_assigned_resource_id && !this.cachedValidResourceIds!.has(ticket.first_response_assigned_resource_id)) {
                ticket.first_response_assigned_resource_id = null;
              }
              if (ticket.first_response_initiating_resource_id && !this.cachedValidResourceIds!.has(ticket.first_response_initiating_resource_id)) {
                ticket.first_response_initiating_resource_id = null;
              }
              return ticket;
            });

            if (mappedRecords.length > 0) {
              const upsertedCount = await bulkUpsertRecords(entity, mappedRecords, 100);
              
              // Estimate added vs updated
              const recordsAdded = Math.floor(upsertedCount * 0.1);
              const recordsUpdated = upsertedCount - recordsAdded;
              
              totalRecordsAdded += recordsAdded;
              totalRecordsUpdated += recordsUpdated;
              
              console.log(`[${entity}] Chunk ${i + 1}: Upserted ${upsertedCount} records (+${recordsAdded} ~${recordsUpdated})`);
            }
          }

        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          console.error(`[${entity}] Chunk ${i + 1} (${chunkDescription}) failed:`, errorMessage);
          failedChunks.push(`${chunkDescription}: ${errorMessage}`);
          // Continue with next chunk instead of failing entire sync
        }
      }

      const duration = Date.now() - syncStartTime;
      console.log(`[${entity}] Chunked sync completed in ${duration}ms`);
      console.log(`[${entity}] Total: +${totalRecordsAdded} ~${totalRecordsUpdated} -${totalRecordsDeleted}`);
      
      if (failedChunks.length > 0) {
        console.warn(`[${entity}] ${failedChunks.length} chunks failed:`, failedChunks);
      }

      return {
        recordsAdded: totalRecordsAdded,
        recordsUpdated: totalRecordsUpdated,
        recordsDeleted: totalRecordsDeleted,
      };
    } catch (error) {
      const duration = Date.now() - syncStartTime;
      const errorMessage = error instanceof Error ? error.message : String(error);
      console.error(`[${entity}] Chunked sync failed after ${duration}ms:`, errorMessage);
      throw error;
    }
  }

  /**
   * Get all valid resource IDs from the database
   * Used to validate foreign key references before insert
   * @returns Set of valid resource IDs
   */
  private async getValidResourceIds(): Promise<Set<number>> {
    try {
      const query = 'SELECT id FROM resources WHERE is_deleted = false';
      const result = await postgresClient.query<{ id: number }>(query);
      return new Set(result.rows.map(row => row.id));
    } catch (error) {
      console.error('Failed to fetch valid resource IDs:', error);
      // Return empty set on error - will cause all resource IDs to be nullified
      return new Set();
    }
  }

  /**
   * Used to validate foreign key references before insert
   * @returns Set of valid contact IDs
   */
  private async getValidContactIds(): Promise<Set<number>> {
    try {
      const query = 'SELECT id FROM contacts WHERE is_deleted = false';
      const result = await postgresClient.query<{ id: number }>(query);
      return new Set(result.rows.map(row => row.id));
    } catch (error) {
      console.error('Failed to fetch valid contact IDs:', error);
      // Return empty set on error - will cause all contact IDs to be nullified
      return new Set();
    }
  }

  /**
   * Calculate monthly date chunks for a given time period
   * @param yearsBack Number of years to look back
   * @returns Array of date range chunks
   */
  private calculateMonthlyChunks(yearsBack: number): Array<{ startDate: Date; endDate: Date }> {
    const chunks: Array<{ startDate: Date; endDate: Date }> = [];
    const now = new Date();
    const startDate = new Date(now);
    startDate.setFullYear(now.getFullYear() - yearsBack);
    startDate.setHours(0, 0, 0, 0);

    let currentDate = new Date(startDate);
    
    while (currentDate < now) {
      const chunkStart = new Date(currentDate);
      
      // Move to next month
      const chunkEnd = new Date(currentDate);
      chunkEnd.setMonth(chunkEnd.getMonth() + 1);
      
      // Don't go beyond current date
      if (chunkEnd > now) {
        chunkEnd.setTime(now.getTime());
      }

      chunks.push({
        startDate: chunkStart,
        endDate: chunkEnd,
      });

      currentDate = new Date(chunkEnd);
    }

    return chunks;
  }

  /**
   * Sync Tasks
   */
  async syncTasks(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.TASKS, isIncremental);
  }

  /**
   * Sync Projects
   */
  async syncProjects(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.PROJECTS, isIncremental);
  }

  /**
   * Sync Resources (Users)
   */
  async syncResources(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.RESOURCES, isIncremental);
  }

  /**
   * Sync Configuration Items
   */
  async syncConfigurationItems(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.CONFIGURATION_ITEMS, isIncremental);
  }

  /**
   * Sync Contacts
   */
  async syncContacts(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.CONTACTS, isIncremental);
  }

  /**
   * Sync Contracts
   */
  async syncContracts(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.CONTRACTS, isIncremental);
  }

  /**
   * Sync Billing Items
   */
  async syncBillingItems(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.BILLING_ITEMS, isIncremental);
  }

  /**
   * Sync Statuses (Picklist)
   */
  async syncStatuses(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.STATUSES, isIncremental);
  }

  /**
   * Sync Issue Types (Picklist from Ticket field)
   */
  async syncIssueTypes(isIncremental: boolean = false): Promise<EntitySyncStats> {
    const syncStartTime = Date.now();
    console.log(`[issue_types] Starting picklist sync`);

    try {
      // Get issue type picklist values from Tickets entity
      const picklistValues = await this.autotaskClient.getPicklistValues('Tickets', 'issueType');
      
      // Convert picklist to database format
      const records = Object.entries(picklistValues).map(([value, label]) => ({
        value: parseInt(value),
        label: label,
        is_active: true,
        sort_order: parseInt(value),
        synced_at: new Date(),
      }));

      console.log(`[issue_types] Found ${records.length} picklist values`);

      // Upsert to database
      const tableName = getTableName(EntityType.ISSUE_TYPES);
      const upsertedCount = await postgresClient.bulkUpsert(tableName, records, ['value']);
      
      const stats: EntitySyncStats = {
        recordsAdded: upsertedCount,
        recordsUpdated: 0,
        recordsDeleted: 0,
      };
      
      const duration = Date.now() - syncStartTime;
      console.log(`[issue_types] Sync completed in ${duration}ms: +${stats.recordsAdded} ~${stats.recordsUpdated}`);
      
      return stats;
    } catch (error) {
      const duration = Date.now() - syncStartTime;
      console.error(`[issue_types] Sync failed after ${duration}ms:`, error);
      throw error;
    }
  }

  /**
   * Sync Sub-Issue Types (Picklist from Ticket field)
   */
  async syncSubIssueTypes(isIncremental: boolean = false): Promise<EntitySyncStats> {
    const syncStartTime = Date.now();
    console.log(`[sub_issue_types] Starting picklist sync`);

    try {
      // Get sub-issue type picklist values from Tickets entity
      const url = `${this.autotaskClient['config'].apiUrl}/Tickets/entityInformation/fields`;
      const response = await fetch(url, {
        method: 'GET',
        headers: this.autotaskClient['getAuthHeaders'](),
      });
      
      const responseText = await response.text();
      if (!response.ok) {
        throw new Error(`Failed to fetch field info: ${responseText}`);
      }
      
      const fieldData = JSON.parse(responseText);
      const subIssueTypeField = fieldData.fields.find((f: any) => f.name === 'subIssueType');
      
      if (!subIssueTypeField || !subIssueTypeField.picklistValues) {
        throw new Error('subIssueType field or picklist values not found');
      }
      
      // Convert picklist to database format, capturing parent value if it exists
      const records = subIssueTypeField.picklistValues.map((item: any) => ({
        value: parseInt(item.value),
        label: item.label,
        is_active: item.isActive !== false,
        parent_value: item.parentValue ? parseInt(item.parentValue) : null,
        sort_order: item.sortOrder || parseInt(item.value),
        synced_at: new Date(),
      }));

      console.log(`[sub_issue_types] Found ${records.length} picklist values`);

      // Upsert to database
      const tableName = getTableName(EntityType.SUB_ISSUE_TYPES);
      const upsertedCount = await postgresClient.bulkUpsert(tableName, records, ['value']);
      
      const stats: EntitySyncStats = {
        recordsAdded: upsertedCount,
        recordsUpdated: 0,
        recordsDeleted: 0,
      };
      
      const duration = Date.now() - syncStartTime;
      console.log(`[sub_issue_types] Sync completed in ${duration}ms: +${stats.recordsAdded} ~${stats.recordsUpdated}`);
      
      return stats;
    } catch (error) {
      const duration = Date.now() - syncStartTime;
      console.error(`[sub_issue_types] Sync failed after ${duration}ms:`, error);
      throw error;
    }
  }

  /**
   * Sync Work Types (Picklist)
   */
  async syncWorkTypes(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.WORK_TYPES, isIncremental);
  }

  /**
   * Sync Time Entries
   */
  async syncTimeEntries(isIncremental: boolean = false): Promise<EntitySyncStats> {
    return await this.syncEntity(EntityType.TIME_ENTRIES, isIncremental);
  }
}

/**
 * Create entity sync service instance
 * @param autotaskClient Autotask client instance
 * @returns EntitySyncService instance
 */
export function createEntitySyncService(autotaskClient: AutotaskClient): EntitySyncService {
  return new EntitySyncService(autotaskClient);
}