velout/app/public/vmd.mjs

/**
 * Module for requesting VMD references from the server API.
 * Handles HTTP requests to retrieve and save reference data.
 *
 * @module vmd
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API}
 */

/**
 * Request a VMD reference from the server endpoint (GET).
 * Sends a GET request with the reference identifier and returns parsed JSON data.
 *
 * @async
 * @function reference2json
 *
 * @param {string} ref - The reference identifier to look up. Must be a non-empty string.
 *
 * @returns {Promise<Object>} Parsed JSON response containing the VMD reference data
 *
 * @throws {TypeError} When ref is not a valid string
 * @throws {Error} When network request fails or server returns non-success status
 */
export async function reference2json(ref) {
	if (typeof ref !== "string" || !ref.trim())
		throw new TypeError("Reference must be a non-empty string");

	const endpoint = `/api/vmd/reference/`;

	try {
		const response = await fetch(endpoint, {
			method: "POST",
			headers: {"Accept": "application/json", "Content-Type": "vmd/reference"},
			body: ref,
		});

		if (!response.ok)
			throw new Error(`Request failed: ${response.status} ${response.statusText}`);

		return await response.json();
	} catch (error) {
		if (error instanceof TypeError && error.message.includes("fetch"))
			throw new Error("Network error: Unable to reach server");
		throw error;
	}
}

// /**
//  * Save a VMD reference to the server endpoint (POST/PUT).
//  * Sends a POST request with the VMD data and returns the saved data.
//  *
//  * @async
//  * @function saveVMDReference
//  *
//  * @param {string} ref - The reference identifier. Must be a non-empty string.
//  * @param {Object} data - The VMD data object to save
//  *
//  * @returns {Promise<Object>} The saved VMD data
//  *
//  * @throws {TypeError} When ref is not a valid string or data is not an object
//  * @throws {Error} When network request fails or server returns non-success status
//  */
// export async function saveVMDReference(ref, data) {
// 	if (typeof ref !== "string" || !ref.trim())
// 		throw new TypeError("Reference must be a non-empty string");

// 	if (!data || typeof data !== "object") throw new TypeError("Data must be a valid object");

// 	const endpoint = "/api/vmd/reference";

// 	try {
// 		const response = await fetch(endpoint, {
// 			method: "POST",
// 			headers: {"Content-Type": "application/json"},
// 			body: JSON.stringify({reference: ref, data}),
// 		});

// 		if (!response.ok)
// 			throw new Error(`Request failed: ${response.status} ${response.statusText}`);

// 		return await response.json();
// 	} catch (error) {
// 		if (error instanceof TypeError && error.message.includes("fetch"))
// 			throw new Error("Network error: Unable to reach server");
// 		throw error;
// 	}
// }

/**
 * Save a VMD reference to the server endpoint (POST/PUT).
 * Sends a POST request with the VMD data and returns the saved data.
 *
 * @async
 * @function loadVMDFile
 *
 * @param {string} ref - The reference identifier. Must be a non-empty string.
 *
 * @returns {Promise<Object>} The saved VMD data
 *
 * @throws {TypeError} When ref is not a valid string or data is not an object
 * @throws {Error} When network request fails or server returns non-success status
 */
export async function loadVMDFile(ref) {
	if (typeof ref !== "string" || !ref.trim())
		throw new TypeError("Reference must be a non-empty string");

	const endpoint = "/api/vmd/entry";

	try {
		const response = await fetch(endpoint, {
			method: "POST",
			headers: {"Content-Type": "application/json"},
			body: ref,
		});

		if (!response.ok)
			throw new Error(`Request failed: ${response.status} ${response.statusText}`);

		return await response.json();
	} catch (error) {
		if (error instanceof TypeError && error.message.includes("fetch"))
			throw new Error("Network error: Unable to reach server");
		throw error;
	}
}

/**
 * Client-side wrapper for VMD API endpoints.
 * Exports functions that communicate with the server API.
 *
 * @module vmdAPI
 */

/**
 * List all countries with VMD entries.
 *
 * @async
 * @function listCountries
 *
 * @returns {Promise<Array>} Array of country codes
 */
export async function listCountries(type) {
	const url = new URL("/api/vmd/countries", window.location.origin);
	if (type) url.searchParams.set("type", type);

	const response = await fetch(url);
	if (!response.ok) throw new Error(`HTTP ${response.status}`);
	return response.json();
}

/**
 * List entries within a country.
 *
 * @async
 * @function listEntries
 *
 * @param {string} country - Country code
 * @param {string} [type] - Entry type filter
 *
 * @returns {Promise<Array>} Array of entry objects
 */
export async function listEntries(type, country) {
	const url = new URL("/api/vmd/entries", window.location.origin);
	url.searchParams.set("type", type);
	url.searchParams.set("country", country);

	const response = await fetch(url);
	if (!response.ok) throw new Error(`HTTP ${response.status}`);
	return response.json();
}

/**
 * List child entries under a parent.
 *
 * @async
 * @function listChildren
 *
 * @param {string} parent - Parent reference
 *
 * @returns {Promise<Array>} Array of child entry objects
 */
export async function listChildren(parent) {
	const response = await fetch(`/api/vmd/children/${encodeURIComponent(parent)}`);
	if (!response.ok) throw new Error(`HTTP ${response.status}`);
	return response.json();
}