people_manager/src/services/entityService.ts

/**
 * Entity management service
 */

import { transceivePost, transceiveStream } from './transceive';
import type {
  EntityListBulkRequest,
  EntityListBulkResponse,
  EntityListStreamRequest,
  EntityListStreamResponse,
  EntityFetchRequest,
  EntityFetchResponse,
  EntityExtantRequest,
  EntityExtantResponse,
  EntityCreateRequest,
  EntityCreateResponse,
  EntityUpdateRequest,
  EntityUpdateResponse,
  EntityDeleteRequest,
  EntityDeleteResponse,
  EntityDeltaRequest,
  EntityDeltaResponse,
  EntityMoveRequest,
  EntityMoveResponse,
  EntityImportRequest,
  EntityImportResponse,
  EntityInterface,
} from '../types/entity';
import { useIntegrationStore } from '@KTXC/stores/integrationStore';
import { EntityObject } from '../models';

/**
 * Helper to create the right entity model class based on provider identifier
 * Uses provider-specific factory if available, otherwise returns base EntityObject
 */
function createEntityObject(data: EntityInterface): EntityObject {
  const integrationStore = useIntegrationStore();
  const factoryItem = integrationStore.getItemById('people_entity_factory', data.provider) as any;
  const factory = factoryItem?.factory;

  // Use provider factory if available, otherwise base class
  return factory ? factory(data) : new EntityObject().fromJson(data);
}

export const entityService = {

  /**
   * Retrieve list of entities, optionally filtered by source collection identifiers
   *
   * @param request - list request parameters
   *
   * @returns Promise with entity object list grouped by provider, service, collection, and entity identifier
   */
  async listBulk(request: EntityListBulkRequest = {}): Promise<Record<string, Record<string, Record<string, Record<string, EntityObject>>>>> {
    const response = await transceivePost<EntityListBulkRequest, EntityListBulkResponse>('entity.listBulk', request);

    // Convert nested response to EntityObject instances
    const providerList: Record<string, Record<string, Record<string, Record<string, EntityObject>>>> = {};
    Object.entries(response).forEach(([providerId, providerServices]) => {
      const serviceList: Record<string, Record<string, Record<string, EntityObject>>> = {};
      Object.entries(providerServices).forEach(([serviceId, serviceCollections]) => {
        const collectionList: Record<string, Record<string, EntityObject>> = {};
        Object.entries(serviceCollections).forEach(([collectionId, collectionEntities]) => {
          const entityList: Record<string, EntityObject> = {};
          Object.entries(collectionEntities).forEach(([entityId, entityData]) => {
            entityList[entityId] = createEntityObject(entityData);
          });
          collectionList[collectionId] = entityList;
        });
        serviceList[serviceId] = collectionList;
      });
      providerList[providerId] = serviceList;
    });

    return providerList;
  },

  /**
   * Stream entities as NDJSON, invoking onEntity for each entity as it arrives.
   *
   * The server emits one entity per line so the caller receives entities
   * progressively rather than waiting for the full collection to load.
   *
   * @param request  - stream request parameters (same shape as list)
   * @param onEntity - called synchronously for each entity as it is received
   *
   * @returns Promise resolving to { total } when the stream completes
   */
  async listStream(request: EntityListStreamRequest, onEntity: (entity: EntityObject) => void): Promise<{ total: number }> {
    return await transceiveStream<EntityListStreamRequest, EntityListStreamResponse>(
      'entity.listStream',
      request,
      (entity) => {
        onEntity(createEntityObject(entity));
      }
    );
  },

  /**
   * Retrieve a specific entity by provider and identifier
   *
   * @param request - fetch request parameters
   *
   * @returns Promise with entity objects keyed by identifier
   */
  async fetch(request: EntityFetchRequest): Promise<Record<string, EntityObject>> {
    const response = await transceivePost<EntityFetchRequest, EntityFetchResponse>('entity.fetch', request);

    // Convert response to EntityObject instances
    const list: Record<string, EntityObject> = {};
    Object.entries(response).forEach(([, entity]) => {
      list[entity.identifier] = createEntityObject(entity);
    });

    return list;
  },

  /**
   * Retrieve entity availability status for a given set of entity identifiers
   *
   * @param request - extant request parameters
   *
   * @returns Promise with entity availability status
   */
  async extant(request: EntityExtantRequest): Promise<EntityExtantResponse> {
    return await transceivePost<EntityExtantRequest, EntityExtantResponse>('entity.extant', request);
  },

  /**
   * Create a new entity
   *
   * @param request - create request parameters
   *
   * @returns Promise with created entity object
   */
  async create(request: EntityCreateRequest): Promise<EntityObject> {
    const response = await transceivePost<EntityCreateRequest, EntityCreateResponse>('entity.create', request);
    return createEntityObject(response);
  },

  /**
   * Update an existing entity
   *
   * @param request - update request parameters
   *
   * @returns Promise with updated entity object
   */
  async update(request: EntityUpdateRequest): Promise<EntityObject> {
    const response = await transceivePost<EntityUpdateRequest, EntityUpdateResponse>('entity.update', request);
    return createEntityObject(response);
  },

  /**
   * Delete entities by their identifiers
   *
   * @param request - delete request parameters
   *
   * @returns Promise with deletion results keyed by source entity identifier
   */
  async delete(request: EntityDeleteRequest): Promise<EntityDeleteResponse> {
    return await transceivePost<EntityDeleteRequest, EntityDeleteResponse>('entity.delete', request);
  },

  /**
   * Retrieve delta changes for entities
   *
   * @param request - delta request parameters
   *
   * @returns Promise with delta changes (additions, modifications, deletions)
   */
  async delta(request: EntityDeltaRequest): Promise<EntityDeltaResponse> {
    return await transceivePost<EntityDeltaRequest, EntityDeltaResponse>('entity.delta', request);
  },

  /**
   * Move entities to a target collection
   *
   * @param request - move request parameters
   *
   * @returns Promise with move results keyed by source entity identifier
   */
  async move(request: EntityMoveRequest): Promise<EntityMoveResponse> {
    return await transceivePost<EntityMoveRequest, EntityMoveResponse>('entity.move', request);
  },

  /**
   * Import vCards into a collection, streaming progress as it arrives.
   *
   * @param request      - import request (target collection, raw data, options)
   * @param onObject     - called synchronously for each per-contact result frame
   * @param onDiscovered - called once with the discovered total (progress denominator)
   *
   * @returns Promise resolving to { total } (objects processed) when the stream completes
   */
  async import(
    request: EntityImportRequest,
    onObject: (object: EntityImportResponse) => void,
    onDiscovered: (expected: number) => void,
  ): Promise<{ total: number }> {
    return await transceiveStream<EntityImportRequest, EntityImportResponse>(
      'entity.import',
      request,
      onObject,
      { onStart: (expected) => { if (expected !== undefined) onDiscovered(expected); } },
    );
  },

};

export default entityService;