feat: streaming entities

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

src/services/transceive.ts

@@ -48,3 +48,68 @@ export async function transceivePost<TRequest, TResponse>(
   
   return response.data;
 }
+
+/**
+ * Stream an NDJSON API response, calling onLine for each parsed line.
+ *
+ * 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.
+ *
+ * @param operation - Operation name, e.g. 'entity.stream'
+ * @param data      - Operation-specific request data
+ * @param onLine    - Synchronous callback invoked for every parsed line.
+ *                    May throw to abort the stream.
+ * @param user      - Optional user identifier override
+ */
+export async function transceiveStream<TRequest, TLine = any>(
+  operation: string,
+  data: TRequest,
+  onLine: (line: TLine) => void,
+  user?: string
+): Promise<void> {
+  const request: ApiRequest<TRequest> = {
+    version: API_VERSION,
+    transaction: generateTransactionId(),
+    operation,
+    data,
+    user,
+  };
+
+  await fetchWrapper.post(API_URL, request, {
+    //headers: { 'Accept': 'application/x-ndjson' },
+    headers: { 'Accept': 'application/json' },
+    onStream: async (response) => {
+      if (!response.body) {
+        throw new Error(`[${operation}] Response body is not readable`);
+      }
+
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop()!; // retain any incomplete trailing chunk
+
+          for (const line of lines) {
+            if (!line.trim()) continue;
+            onLine(JSON.parse(line) as TLine);
+          }
+        }
+
+        // flush any remaining bytes still in the buffer
+        if (buffer.trim()) {
+          onLine(JSON.parse(buffer) as TLine);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    },
+  });
+}