feat: mail entity download

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

src/services/transceive.ts

@@ -141,3 +141,84 @@ export async function transceiveStream<TRequest, TData>(
 
   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));
+}