chore: standardize protocol

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

src/services/serviceService.ts

@@ -18,13 +18,15 @@ import type {
   ServiceCreateRequest,
   ServiceUpdateResponse,
   ServiceUpdateRequest,
+  ServiceDeleteResponse,
+  ServiceDeleteRequest,
 } from '../types/service';
+import { useIntegrationStore } from '@KTXC/stores/integrationStore';
 import { transceivePost } from './transceive';
 import { ServiceObject } from '../models/service';
-import { useIntegrationStore } from '@KTXC/stores/integrationStore';
 
 /**
- * Helper to create the right service model class based on provider
+ * Helper to create the right service model class based on provider identifier
  * Uses provider-specific factory if available, otherwise returns base ServiceObject
  */
 function createServiceObject(data: ServiceInterface): ServiceObject {
@@ -39,9 +41,9 @@ function createServiceObject(data: ServiceInterface): ServiceObject {
 export const serviceService = {
 
   /**
-   * List available services
+   * Retrieve list of services, optionally filtered by source selector
    * 
-   * @param request - Service list request parameters
+   * @param request - list request parameters
    * 
    * @returns Promise with service object list grouped by provider and keyed by service identifier
    */
@@ -49,31 +51,23 @@ export const serviceService = {
     const response = await transceivePost<ServiceListRequest, ServiceListResponse>('service.list', request);
     
     // Convert nested response to ServiceObject instances
-    const list: Record<string, Record<string, ServiceObject>> = {};
+    const providerList: Record<string, Record<string, ServiceObject>> = {};
     Object.entries(response).forEach(([providerId, providerServices]) => {
-      list[providerId] = {};
+      const serviceList: Record<string, ServiceObject> = {};
       Object.entries(providerServices).forEach(([serviceId, serviceData]) => {
-        list[providerId][serviceId] = createServiceObject(serviceData);
+        serviceList[serviceId] = createServiceObject(serviceData);
       });
+      providerList[providerId] = serviceList;
     });
     
-    return list;
+    return providerList;
   },
 
   /**
-   * Check which services exist/are available
+   * Retrieve a specific service by provider and identifier
    * 
-   * @param request - Service extant request with source selector
-   * @returns Promise with service availability status
-   */
-  async extant(request: ServiceExtantRequest): Promise<ServiceExtantResponse> {
-    return await transceivePost<ServiceExtantRequest, ServiceExtantResponse>('service.extant', request);
-  },
-
-  /**
-   * Fetch a specific service
+   * @param request - fetch request parameters
    * 
-   * @param request - Service fetch request with provider and service IDs
    * @returns Promise with service object
    */
   async fetch(request: ServiceFetchRequest): Promise<ServiceObject> {
@@ -82,9 +76,21 @@ export const serviceService = {
   },
 
   /**
-   * Discover mail service configuration from identity
+   * Retrieve service availability status for a given source selector
+   * 
+   * @param request - extant request parameters
+   * 
+   * @returns Promise with service availability status
+   */
+  async extant(request: ServiceExtantRequest): Promise<ServiceExtantResponse> {
+    return await transceivePost<ServiceExtantRequest, ServiceExtantResponse>('service.extant', request);
+  },
+
+  /**
+   * Retrieve discoverable services for a given source selector, sorted by provider
+   * 
+   * @param request - discover request parameters
    * 
-   * @param request - Discovery request with identity and optional hints
    * @returns Promise with array of discovered services sorted by provider
    */
   async discover(request: ServiceDiscoverRequest): Promise<ServiceObject[]> {
@@ -109,7 +115,7 @@ export const serviceService = {
   },
 
   /**
-   * Test a mail service connection
+   * Test service connectivity and configuration
    * 
    * @param request - Service test request
    * @returns Promise with test results
@@ -121,7 +127,8 @@ export const serviceService = {
   /**
    * Create a new service
    * 
-   * @param request - Service create request with provider ID and service data
+   * @param request - create request parameters
+   * 
    * @returns Promise with created service object
    */
   async create(request: ServiceCreateRequest): Promise<ServiceObject> {
@@ -132,7 +139,8 @@ export const serviceService = {
   /**
    * Update a existing service
    * 
-   * @param request - Service update request with provider ID, service ID, and updated data
+   * @param request - update request parameters
+   * 
    * @returns Promise with updated service object
    */
   async update(request: ServiceUpdateRequest): Promise<ServiceObject> {
@@ -143,11 +151,12 @@ export const serviceService = {
   /**
    * Delete a service
    * 
-   * @param request - Service delete request with provider ID and service ID
+   * @param request - delete request parameters
+   * 
    * @returns Promise with deletion result
    */
   async delete(request: { provider: string; identifier: string | number }): Promise<any> {
-    return await transceivePost('service.delete', request);
+    return await transceivePost<ServiceDeleteRequest, ServiceDeleteResponse>('service.delete', request);
   },
 };