refactor: unify streaming

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

src/services/transceive.ts

@@ -4,7 +4,7 @@
  */
 
 import { createFetchWrapper } from '@KTXC';
-import type { ApiRequest, ApiResponse } from '../types/common';
+import type { ApiRequest, ApiResponse, ApiStreamResponse } from '../types/common';
 
 const fetchWrapper = createFetchWrapper();
 const API_URL = '/m/mail_manager/v1';
@@ -50,24 +50,25 @@ export async function transceivePost<TRequest, TResponse>(
 }
 
 /**
- * Stream an NDJSON API response, calling onLine for each parsed line.
+ * Stream an NDJSON API response, unwrapping data frames for the caller.
  *
- * The server emits one JSON object per line with a `type` discriminant
- * (meta / entity / done / error). The caller interprets each line via onLine.
- * Throwing inside onLine aborts the stream.
+ * The server emits one JSON object per line with a transport-level `type`
+ * discriminant. This helper consumes control and error frames, forwards only
+ * unwrapped `data` payloads to the caller, and returns the final stream total.
  *
  * @param operation - Operation name, e.g. 'entity.stream'
  * @param data      - Operation-specific request data
- * @param onLine    - Synchronous callback invoked for every parsed line.
+ * @param onData    - Synchronous callback invoked for every unwrapped data payload.
  *                    May throw to abort the stream.
  * @param user      - Optional user identifier override
+ * @returns Promise resolving to the final stream total from the control/end frame
  */
-export async function transceiveStream<TRequest, TLine = any>(
+export async function transceiveStream<TRequest, TData>(
   operation: string,
   data: TRequest,
-  onLine: (line: TLine) => void,
+  onData: (data: TData) => void,
   user?: string
-): Promise<void> {
+): Promise<{ total: number }> {
   const request: ApiRequest<TRequest> = {
     version: API_VERSION,
     transaction: generateTransactionId(),
@@ -76,10 +77,12 @@ export async function transceiveStream<TRequest, TLine = any>(
     user,
   };
 
+  let total = 0;
+
   await fetchWrapper.post(API_URL, request, {
     //headers: { 'Accept': 'application/x-ndjson' },
     headers: { 'Accept': 'application/json' },
-    onStream: async (response) => {
+    onStream: async (response: Response) => {
       if (!response.body) {
         throw new Error(`[${operation}] Response body is not readable`);
       }
@@ -99,17 +102,42 @@ export async function transceiveStream<TRequest, TLine = any>(
 
           for (const line of lines) {
             if (!line.trim()) continue;
-            onLine(JSON.parse(line) as TLine);
+            const message = JSON.parse(line) as ApiStreamResponse<TData>;
+
+            if (message.type === 'control') {
+              if (message.status === 'end') {
+                total = message.total;
+              }
+              continue;
+            }
+
+            if (message.type === 'error') {
+              throw new Error(`[${operation}] ${message.message}`);
+            }
+
+            onData(message.data);
           }
         }
 
         // flush any remaining bytes still in the buffer
         if (buffer.trim()) {
-          onLine(JSON.parse(buffer) as TLine);
+          const message = JSON.parse(buffer) as ApiStreamResponse<TData>;
+
+          if (message.type === 'control') {
+            if (message.status === 'end') {
+              total = message.total;
+            }
+          } else if (message.type === 'error') {
+            throw new Error(`[${operation}] ${message.message}`);
+          } else {
+            onData(message.data);
+          }
         }
       } finally {
         reader.releaseLock();
       }
     },
   });
+
+  return { total };
 }