mail_manager/src/services/transceive.ts

/**
 * API Client for Mail Manager
 * Provides a centralized way to make API calls with envelope wrapping/unwrapping
 */

import { createFetchWrapper } from '@KTXC';
import type { ApiRequest, ApiResponse, ApiStreamResponse } from '../types/common';

const fetchWrapper = createFetchWrapper();
const API_URL = '/m/mail_manager/v1';
const API_VERSION = 1;

/**
 * Generate a unique transaction ID
 */
export function generateTransactionId(): string {
  return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
}

/**
 * Make an API call with automatic envelope wrapping and unwrapping
 * 
 * @param operation - Operation name (e.g., 'provider.list', 'service.autodiscover')
 * @param data - Operation-specific request data
 * @param user - Optional user identifier override
 * @returns Promise with unwrapped response data
 * @throws Error if the API returns an error status
 */
export async function transceivePost<TRequest, TResponse>(
  operation: string,
  data: TRequest,
  user?: string
): Promise<TResponse> {
  const request: ApiRequest<TRequest> = {
    version: API_VERSION,
    transaction: generateTransactionId(),
    operation,
    data,
    user
  };
  
  const response: ApiResponse<TResponse> = await fetchWrapper.post(API_URL, request);
  
  if (response.status === 'error') {
    const errorMessage = `[${operation}] ${response.data.message}${response.data.code ? ` (code: ${response.data.code})` : ''}`;
    throw new Error(errorMessage);
  }
  
  return response.data;
}

/**
 * Stream an NDJSON API response, unwrapping data frames for the caller.
 *
 * 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 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, TData>(
  operation: string,
  data: TRequest,
  onData: (data: TData) => void,
  user?: string
): Promise<{ total: number }> {
  const request: ApiRequest<TRequest> = {
    version: API_VERSION,
    transaction: generateTransactionId(),
    operation,
    data,
    user,
  };

  let total = 0;

  await fetchWrapper.post(API_URL, request, {
    //headers: { 'Accept': 'application/x-ndjson' },
    headers: { 'Accept': 'application/json' },
    onStream: async (response: 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;
            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()) {
          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 };
}

/**
 * Submit a browser-native file download request via a top-level form POST.
 *
 * This avoids buffering the response body in application-managed JavaScript
 * memory. The backend is expected to accept form fields where `data` contains
 * the serialized operation payload and to return an attachment response.
 */
export function transceiveDownload<TRequest>(
  operation: string,
  data: TRequest,
  user?: string,
): { transaction: string } {
  if (typeof document === 'undefined' || typeof window === 'undefined') {
    throw new Error('Browser window is not available for download submission');
  }

  const request: ApiRequest<TRequest> = {
    version: API_VERSION,
    transaction: generateTransactionId(),
    operation,
    data,
    user,
  };

  const form = document.createElement('form');
  form.method = 'POST';
  form.action = API_URL;
  form.target = '_blank';
  form.style.display = 'none';

  appendHiddenField(form, 'version', String(request.version));
  appendHiddenField(form, 'transaction', request.transaction);
  appendHiddenField(form, 'operation', request.operation);
  appendFormValue(form, 'data', request.data);

  if (request.user) {
    appendHiddenField(form, 'user', request.user);
  }

  document.body.appendChild(form);
  form.submit();
  form.remove();

  return { transaction: request.transaction };
}

function appendHiddenField(form: HTMLFormElement, name: string, value: string): void {
  const input = document.createElement('input');
  input.type = 'hidden';
  input.name = name;
  input.value = value;
  form.appendChild(input);
}

function appendFormValue(form: HTMLFormElement, name: string, value: unknown): void {
  if (value === undefined) {
    return;
  }

  if (value === null) {
    appendHiddenField(form, name, '');
    return;
  }

  if (Array.isArray(value)) {
    value.forEach((item, index) => {
      appendFormValue(form, `${name}[${index}]`, item);
    });
    return;
  }

  if (typeof value === 'object') {
    Object.entries(value as Record<string, unknown>).forEach(([key, nestedValue]) => {
      appendFormValue(form, `${name}[${key}]`, nestedValue);
    });
    return;
  }

  appendHiddenField(form, name, String(value));
}