feat: implement billing history CSV export functionality

- Added `useBillingCsvExport` hook to manage the export of billing history to CSV format.
- Introduced utility functions for CSV generation and file download in `csv-export.ts`.
- Updated `BillingBlock` component to include a button for exporting billing history, displaying export status and count.
- Enhanced the overall billing model by integrating new export features, improving user experience for billing data management.

Author: mois-ilya

src/features/billing/model/billing-export.ts

@@ -0,0 +1,120 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useToast } from '@chakra-ui/react';
+import { getProjectBillingHistory } from 'src/shared/api';
+import { mapDTOTransactionToBillingHistoryItem } from 'src/shared/hooks/useBillingHistoryQuery';
+import { useProjectId, useMaybeProject } from 'src/shared/contexts/ProjectContext';
+import {
+    buildBillingHistoryCsv,
+    buildBillingHistoryFilename,
+    delay,
+    downloadCsvFile,
+    EXPORT_PAGE_SIZE,
+    MIN_REQUEST_INTERVAL_MS
+} from './csv-export';
+
+export interface UseBillingExportReturn {
+    isExporting: boolean;
+    exportedCount: number;
+    exportFullHistory: () => Promise<void>;
+}
+
+export function useBillingCsvExport(): UseBillingExportReturn {
+    const [isExporting, setIsExporting] = useState(false);
+    const [exportedCount, setExportedCount] = useState(0);
+    const projectId = useProjectId();
+    const project = useMaybeProject();
+    const toast = useToast();
+    const isMountedRef = useRef(true);
+
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            isMountedRef.current = false;
+        };
+    }, []);
+
+    const exportFullHistory = useCallback(async () => {
+        if (!projectId || isExporting) {
+            return;
+        }
+
+        setIsExporting(true);
+        setExportedCount(0);
+
+        const allItems = [];
+        let beforeTx: string | undefined;
+        let lastRequestTime = 0;
+
+        try {
+            while (true) {
+                const now = Date.now();
+                if (lastRequestTime) {
+                    const elapsed = now - lastRequestTime;
+                    if (elapsed < MIN_REQUEST_INTERVAL_MS) {
+                        await delay(MIN_REQUEST_INTERVAL_MS - elapsed);
+                    }
+                }
+                lastRequestTime = Date.now();
+
+                const { data, error } = await getProjectBillingHistory({
+                    path: { id: projectId },
+                    query: { before_tx: beforeTx, limit: EXPORT_PAGE_SIZE }
+                });
+
+                if (error) {
+                    throw error;
+                }
+
+                const currentPage = data.history;
+
+                if (!currentPage.length) {
+                    break;
+                }
+
+                const mappedPage = currentPage.map(mapDTOTransactionToBillingHistoryItem);
+                allItems.push(...mappedPage);
+
+                setExportedCount(prev => prev + currentPage.length);
+
+                if (currentPage.length < EXPORT_PAGE_SIZE) {
+                    break;
+                }
+
+                beforeTx = currentPage[currentPage.length - 1].id;
+            }
+
+            const csvContent = buildBillingHistoryCsv(allItems);
+            const projectName = project?.name || 'unknown';
+            const filename = buildBillingHistoryFilename(projectName, projectId);
+            downloadCsvFile(csvContent, filename);
+
+            if (isMountedRef.current) {
+                toast({
+                    title: 'Billing history exported',
+                    status: 'success',
+                    duration: 4000,
+                    isClosable: true
+                });
+            }
+        } catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            if (isMountedRef.current) {
+                toast({
+                    title: 'Failed to export billing history',
+                    description: message,
+                    status: 'error',
+                    duration: 6000,
+                    isClosable: true
+                });
+            }
+        } finally {
+            setIsExporting(false);
+        }
+    }, [projectId, isExporting, toast]);
+
+    return {
+        isExporting,
+        exportedCount,
+        exportFullHistory
+    };
+}

src/features/billing/model/csv-export.ts

@@ -0,0 +1,70 @@
+import { BillingHistoryItem } from 'src/shared/hooks/useBillingHistoryQuery';
+
+export const EXPORT_PAGE_SIZE = 100;
+export const MIN_REQUEST_INTERVAL_MS = Math.ceil(1000 / 3);
+
+const CSV_HEADERS = [
+    'Transaction ID',
+    'Created At (ISO)',
+    'Type',
+    'Reason',
+    'Description',
+    'Signed Amount',
+    'Currency',
+    'Metadata'
+] as const;
+
+export const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+export const escapeCsvValue = (value: string): string => {
+    const stringValue = String(value ?? '');
+    const escapedValue = stringValue.replace(/"/g, '""');
+    return `"${escapedValue}"`;
+};
+
+export const serializeCsvRow = (row: string[]): string => row.map(escapeCsvValue).join(',');
+
+export const formatBillingHistoryCsvRow = (item: BillingHistoryItem): string[] => {
+    const amount = item.amount.toStringAmount({ decimalPlaces: null, thousandSeparators: false });
+    const sign = item.type === 'charge' ? '-' : '+';
+    const reason = item.info.reason ?? '';
+
+    // Extract metadata without 'reason' field
+    const { reason: _, ...metadata } = item.info as Record<string, unknown>;
+    const metadataJson = Object.keys(metadata).length > 0 ? JSON.stringify(metadata) : '';
+
+    return [
+        item.id,
+        item.date.toISOString(),
+        item.type,
+        reason,
+        item.description,
+        `${sign}${amount}`,
+        item.amount.stringCurrency,
+        metadataJson
+    ];
+};
+
+export const buildBillingHistoryCsv = (items: BillingHistoryItem[]): string => {
+    const header = serializeCsvRow([...CSV_HEADERS]);
+    const rows = items.map(item => serializeCsvRow(formatBillingHistoryCsvRow(item)));
+    return [header, ...rows].join('\n');
+};
+
+export const buildBillingHistoryFilename = (projectName: string, projectId: number): string => {
+    const timestamp = new Date().toISOString().replace(/:/g, '-');
+    const sanitizedProjectName = projectName.replace(/[^a-zA-Z0-9-_]/g, '-').toLowerCase();
+    return `ton-console-billing-history-${sanitizedProjectName}-${projectId}-${timestamp}.csv`;
+};
+
+export const downloadCsvFile = (content: string, filename: string): void => {
+    const blob = new Blob([content], { type: 'text/csv;charset=utf-8;' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+};

src/features/billing/model/index.ts

@@ -1,2 +1,4 @@
 export * from './interfaces';
 export * from './queries';
+export * from './csv-export';
+export { useBillingCsvExport } from './billing-export';

src/pages/balance/BillingBlock.tsx

@@ -1,8 +1,13 @@
 import { FC, useEffect, useState } from 'react';
-import { Box, Button, HStack, Select } from '@chakra-ui/react';
+import {
+    Box,
+    Button,
+    HStack,
+    Select
+} from '@chakra-ui/react';
 import { H4, useBillingHistoryQuery } from 'src/shared';
 import { useProjectId } from 'src/shared/contexts/ProjectContext';
-import { BillingHistoryTable } from 'src/features/billing';
+import { BillingHistoryTable, useBillingCsvExport } from 'src/features/billing';
 
 const DEFAULT_PAGE_SIZE = 10;
 const PAGE_SIZE_OPTIONS = [10, 20, 50, 100] as const;
@@ -14,6 +19,7 @@ const BillingBlock: FC = () => {
     const [cursorStack, setCursorStack] = useState<string[]>([]);
     const [currentCursor, setCurrentCursor] = useState<string | undefined>(undefined);
     const projectId = useProjectId();
+    const { isExporting, exportedCount, exportFullHistory } = useBillingCsvExport();
 
     const { data: billingHistory = [], isLoading } = useBillingHistoryQuery({
         before_tx: currentCursor,
@@ -67,9 +73,23 @@ const BillingBlock: FC = () => {
         setPageNumber(1);
     };
 
+    const handleExportFullHistory = async () => {
+        await exportFullHistory();
+    };
+
     return (
         <Box px="6" py="5">
-            <H4 mb="5">Billing History</H4>
+            <HStack align="center" justify="space-between" mb="5">
+                <H4 m="0">Billing History</H4>
+                <Button
+                    isDisabled={!projectId || isExporting}
+                    onClick={handleExportFullHistory}
+                    size="sm"
+                    variant="secondary"
+                >
+                    {isExporting ? `Exporting (${exportedCount})...` : 'Download CSV'}
+                </Button>
+            </HStack>
             <BillingHistoryTable
                 billingHistory={billingHistory}
                 isLoading={isLoading}

src/shared/hooks/useBillingHistoryQuery.ts

@@ -47,7 +47,9 @@ export function useBillingHistoryQuery(options: UseBillingHistoryQueryOptions =
     });
 }
 
-function mapDTOTransactionToBillingHistoryItem(dtoTx: DTOBillingTransaction): BillingHistoryItem {
+export function mapDTOTransactionToBillingHistoryItem(
+    dtoTx: DTOBillingTransaction
+): BillingHistoryItem {
     const date = new Date(dtoTx.created_at * 1000);
     const amount = mapDTOCurrencyToAmount(dtoTx.currency, dtoTx.amount);