// [DEF:storageService:Module]
/**
 * @purpose Frontend API client for file storage management.
 * @layer   Service
 * @relation DEPENDS_ON -> backend.api.storage
 * @SEMANTICS: storage, api, client
 */

const API_BASE = '/api/storage';

// [DEF:listFiles:Function]
/**
 * @purpose Fetches the list of files for a given category and subpath.
 * @param   {string} [category] - Optional category filter.
 * @param   {string} [path] - Optional subpath filter.
 * @returns {Promise<Array>}
 * @PRE     category and path should be valid strings if provided.
 * @POST    Returns a promise resolving to an array of StoredFile objects.
 */
export async function listFiles(category, path) {
    const params = new URLSearchParams();
    if (category) {
        params.append('category', category);
    }
    if (path) {
        params.append('path', path);
    }
    const response = await fetch(`${API_BASE}/files?${params.toString()}`);
    if (!response.ok) {
        throw new Error(`Failed to fetch files: ${response.statusText}`);
    }
    return await response.json();
}
// [/DEF:listFiles:Function]

// [DEF:uploadFile:Function]
/**
 * @purpose Uploads a file to the storage system.
 * @param   {File} file - The file to upload.
 * @param   {string} category - Target category.
 * @param   {string} [path] - Target subpath.
 * @returns {Promise<Object>}
 * @PRE     file must be a valid File object; category must be specified.
 * @POST    Returns a promise resolving to the metadata of the uploaded file.
 */
export async function uploadFile(file, category, path) {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('category', category);
    if (path) {
        formData.append('path', path);
    }

    const response = await fetch(`${API_BASE}/upload`, {
        method: 'POST',
        body: formData
    });

    if (!response.ok) {
        const errorData = await response.json().catch(() => ({}));
        throw new Error(errorData.detail || `Failed to upload file: ${response.statusText}`);
    }
    return await response.json();
}
// [/DEF:uploadFile:Function]

// [DEF:deleteFile:Function]
/**
 * @purpose Deletes a file or directory from storage.
 * @param   {string} category - File category.
 * @param   {string} path - Relative path of the item.
 * @returns {Promise<void>}
 * @PRE     category and path must identify an existing file or directory.
 * @POST    The specified file or directory is removed from storage.
 */
export async function deleteFile(category, path) {
    const response = await fetch(`${API_BASE}/files/${category}/${path}`, {
        method: 'DELETE'
    });

    if (!response.ok) {
        const errorData = await response.json().catch(() => ({}));
        throw new Error(errorData.detail || `Failed to delete: ${response.statusText}`);
    }
}
// [/DEF:deleteFile:Function]

// [DEF:downloadFileUrl:Function]
/**
 * @purpose Returns the URL for downloading a file.
 * @param   {string} category - File category.
 * @param   {string} path - Relative path of the file.
 * @returns {string}
 * @PRE     category and path must identify an existing file.
 * @POST    Returns a valid API URL for file download.
 */
export function downloadFileUrl(category, path) {
    return `${API_BASE}/download/${category}/${path}`;
}
// [/DEF:downloadFileUrl:Function]

export default {
    listFiles,
    uploadFile,
    deleteFile,
    downloadFileUrl
};

// [/DEF:storageService:Module]