@panoramax/web-viewer 3.2.3 → 4.0.0-develop-39167b4d

package/src/utils/API.js

@@ -1,22 +1,29 @@
-import { TILES_PICTURES_ZOOM } from "./Map";
-import { BASE_PANORAMA_ID } from "./Utils";
+import { TILES_PICTURES_ZOOM } from "./map";
+import { isNullId } from "./utils";
 
 /**
- * API contains various utility functions to communicate with the backend
+ * API contains various utility functions to communicate with Panoramax/STAC API
  *
- * @param {string} endpoint The API endpoint. It corresponds to the <a href="https://github.com/radiantearth/stac-api-spec/blob/main/overview.md#example-landing-page">STAC landing page</a>, with all links describing the API capabilites.
- * @param {object} [options] Options received from viewer that may change API behaviour
+ * @class Panoramax.utils.API
+ * @typicalname api
+ * @fires Panoramax.utils.API#ready
+ * @fires Panoramax.utils.API#broken
+ * @param {string} endpoint The endpoint. It corresponds to the <a href="https://github.com/radiantearth/stac-api-spec/blob/main/overview.md#example-landing-page">STAC landing page</a>, with all links describing the API capabilites.
+ * @param {object} [options] Options
  * @param {string|object} [options.style] General map style
  * @param {string} [options.tiles] API route serving pictures & sequences vector tiles
- * @param {boolean} [options.skipReadLanding] True to not call API landing page automatically (defaults to false)
+ * @param {boolean} [options.skipReadLanding=false] True to not call API landing page automatically
  * @param {object} [options.fetch] Set custom options for fetch calls made against API ([same syntax as fetch options parameter](https://developer.mozilla.org/en-US/docs/Web/API/fetch#parameters))
- * @param {string[]} [options.users] List of initial user IDs to load map styles for.
- * @private
+ * @param {string[]} [options.users] List of initial user IDs to load map styles for
  */
-export default class API {
+export default class API extends EventTarget {
 	constructor(endpoint, options = {}) {
+		super();
+		
 		if(endpoint === null || endpoint === undefined || typeof endpoint !== "string") {
-			throw new Error("endpoint parameter is empty or not a valid string");
+			const e = new Error("endpoint parameter is empty or not a valid string");
+			this.dispatchEvent(new CustomEvent("broken", {detail: {error: e}}));
+			throw e;
 		}
 
 		// Parse local endpoints
@@ -26,7 +33,9 @@ export default class API {
 
 		// Check endpoint
 		if(!API.isValidHttpUrl(endpoint)) {
-			throw new Error(`endpoint parameter is not a valid URL: ${endpoint}`);
+			const e = new Error(`endpoint parameter is not a valid URL: ${endpoint}`);
+			this.dispatchEvent(new CustomEvent("broken", {detail: {error: e}}));
+			throw e;
 		}
 
 		this._endpoint = endpoint;
@@ -42,19 +51,40 @@ export default class API {
 			.catch(e => {
 				this._isReady = -1;
 				console.error(e);
+
+				/**
+				 * Event when API is broken.
+				 * This happens on any API loading or map styling issue.
+				 * @event Panoramax.utils.API#broken
+				 * @type {CustomEvent}
+				 * @property {Error} detail.error The original error
+				 */
+				this.dispatchEvent(new CustomEvent("broken", {detail: {error: e}}));
+
 				return Promise.reject("Viewer failed to communicate with API");
 			})
 			.then(() => this._loadMapStyles(options.style, options.users))
 			.then(() => {
 				this._isReady = 1;
+
+				/**
+				 * Event when API is ready to use.
+				 * This happens after initial API read and map styles load.
+				 * @event Panoramax.utils.API#ready
+				 * @type {Event}
+				 */
+				this.dispatchEvent(new Event("ready"));
+
 				return "API is ready";
 			});
 	}
 
 	/**
-	 * This function resolves when API is ready to be used
-	 *
-	 * @returns {Promise} Resolves when API is ready
+	 * Resolves when the API is ready to be used.
+	 * @memberOf Panoramax.utils.API#
+	 * @returns {Promise}
+	 * @fulfil {string} "API is ready" when initialization is complete.
+	 * @reject {string} Error message
 	 */
 	onceReady() {
 		if(this._isReady == -1) {
@@ -69,9 +99,9 @@ export default class API {
 	}
 
 	/**
-	 * Check if API is ready to be used
-	 *
-	 * @returns {boolean} True if ready
+	 * Checks if the API is ready to be used.
+	 * @memberOf Panoramax.utils.API#
+	 * @returns {boolean} True if the API is ready, false otherwise.
 	 */
 	isReady() {
 		return this._isReady == 1;
@@ -79,6 +109,7 @@ export default class API {
 
 	/**
 	 * List of available features offered by API
+	 * @memberOf Panoramax.utils.API#
 	 * @returns {string[]} Keywords of enabled features
 	 */
 	getAvailableFeatures() {
@@ -87,6 +118,7 @@ export default class API {
 
 	/**
 	 * List of unavailable features on API
+	 * @memberOf Panoramax.utils.API#
 	 * @returns {string[]} Keywords of disabled features
 	 */
 	getUnavailableFeatures() {
@@ -95,7 +127,7 @@ export default class API {
 
 	/**
 	 * Interprets JSON landing page and store important information
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @private
 	 */
 	_parseLanding(landing, options) {
@@ -252,9 +284,12 @@ export default class API {
 
 	/**
 	 * Loads all MapLibre Styles JSON needed at start.
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string|object} style General map style
 	 * @param {string[]} users List of user IDs to handle. Should include special user "geovisio" for general tiles loading.
-	 * @returns {Promise} Resolves when style is ready.
+	 * @returns {Promise} 
+	 * @fulfil {null} When style is ready.
+	 * @private
 	 */
 	_loadMapStyles(style, users) {
 		const mapUsers = new Set(users || []);
@@ -298,19 +333,20 @@ export default class API {
 
 	/**
 	 * Get the defaults fetch options to pass during API calls
-	 *
+	 * @memberOf Panoramax.utils.API#
+	 * @param {boolean} [noTimeout=false] Set to true to avoid default timeout
 	 * @private
 	 * @returns {object} The fetch options
 	 */
-	_getFetchOptions() {
+	_getFetchOptions(noTimeout=false) {
 		return Object.assign({
-			signal: AbortSignal.timeout(15000)
+			signal: noTimeout ? undefined : AbortSignal.timeout(15000)
 		}, this._fetchOpts);
 	}
 
 	/**
 	 * Get the RequestTransformFunction for MapLibre to handle fetch options
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @private
 	 * @returns {function} The RequestTransformFunction
 	 */
@@ -335,11 +371,13 @@ export default class API {
 
 	/**
 	 * Get sequence GeoJSON representation
-	 * 
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} seqId The sequence ID
 	 * @param {string} [next] The next link URL (only for internals)
 	 * @param {object} [data] The previous dataset (only for internals)
-	 * @returns {Promise} Resolves on sequence GeoJSON
+	 * @returns {Promise}
+	 * @fulfil {object} Sequence GeoJSON
+	 * @reject {Error} If API is not ready or for any network issue
 	 */
 	async getSequenceItems(seqId, next = null, data = null) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -347,7 +385,7 @@ export default class API {
 			API.isIdValid(seqId);
 			return fetch(
 				next || `${this._endpoints.collections}/${seqId}/items`,
-				this._getFetchOptions()
+				this._getFetchOptions(true)
 			)
 				.then(res => res.json())
 				.then(res => {
@@ -368,7 +406,7 @@ export default class API {
 
 	/**
 	 * Get full URL for listing pictures around a specific location
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {number} lat Latitude
 	 * @param {number} lon Longitude
 	 * @param {number} [factor] The radius to search around (in degrees)
@@ -391,13 +429,14 @@ export default class API {
 
 	/**
 	 * Get list of pictures around a specific location
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {number} lat Latitude
 	 * @param {number} lon Longitude
 	 * @param {number} [factor] The radius to search around (in degrees)
 	 * @param {number} [limit] Max amount of pictures to retrieve
 	 * @param {string} [seqId] The sequence ID to filter on (by default, no filter)
-	 * @returns {object} The GeoJSON feature collection
+	 * @returns {Promise}
+	 * @fulfil {object} The GeoJSON feature collection
 	 */
 	getPicturesAroundCoordinates(lat, lon, factor, limit, seqId) {
 		return fetch(this.getPicturesAroundCoordinatesUrl(lat, lon, factor, limit, seqId), this._getFetchOptions())
@@ -406,10 +445,11 @@ export default class API {
 
 	/**
 	 * Get full URL for retrieving a specific picture metadata
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} picId The picture unique identifier
 	 * @param {string} [seqId] The sequence ID
 	 * @returns {string} The corresponding URL
+	 * @throws {Error} If API is not ready
 	 */
 	getPictureMetadataUrl(picId, seqId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -422,8 +462,10 @@ export default class API {
 
 	/**
 	 * Get JSON style for general vector tiles
-	 * @return {Promise} The MapLibre JSON style
-	 * @fires Error If API is not ready, or no style defined.
+	 * @memberOf Panoramax.utils.API#
+	 * @return {Promise|object} Promise if first load, MapLibre JSON style otherwise
+	 * @fulfil {object} The MapLibre JSON style
+	 * @reject {Error} If API is not ready, or no style defined.
 	 */
 	getMapStyle() {
 		if(this.isReady()) { return this.mapStyle; }
@@ -471,10 +513,12 @@ export default class API {
 
 	/**
 	 * Get JSON style for specific-user vector tiles
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} userId The user UUID
 	 * @param {boolean} [skipReadyCheck=false] Skip check for API readyness
-	 * @return {Promise} The MapLibre JSON style
-	 * @fires Error If API is not ready, or no style defined.
+	 * @return {Promise}
+	 * @fulfil {object} The MapLibre JSON style
+	 * @reject {Error} If API is not ready, or no style defined.
 	 */
 	getUserMapStyle(userId, skipReadyCheck = false) {
 		if(!skipReadyCheck && !this.isReady()) { return Promise.reject(new Error("API is not ready to use")); }
@@ -515,9 +559,10 @@ export default class API {
 
 	/**
 	 * Find the thumbnail URL for a given picture
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {object} picture The picture GeoJSON feature
 	 * @returns {string} The thumbnail URL, or null if not found
+	 * @throws {Error} If API is not ready
 	 * @private
 	 */
 	findThumbnailInPictureFeature(picture) {
@@ -538,10 +583,12 @@ export default class API {
 
 	/**
 	 * Get a picture thumbnail URL for a given sequence
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} seqId The sequence ID
 	 * @param {object} [seq] The sequence metadata (with links) if already loaded
-	 * @returns {Promise} Promise resolving on the picture thumbnail URL, or null if not found
+	 * @returns {Promise}
+	 * @fulfil {string|null} Promise resolving on the picture thumbnail URL, or null if not found
+	 * @throws {Error} If API is not ready
 	 */
 	getPictureThumbnailURLForSequence(seqId, seq) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -575,10 +622,12 @@ export default class API {
 
 	/**
 	 * Get thumbnail URL for a specific picture
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} picId The picture unique identifier
 	 * @param {string} [seqId] The sequence ID
-	 * @returns {Promise} The corresponding URL on resolve, or undefined if no thumbnail could be found
+	 * @returns {Promise}
+	 * @fulfil {string|null} The corresponding URL on resolve, or null if no thumbnail could be found
+	 * @throws {Error} If API is not ready
 	 */
 	getPictureThumbnailURL(picId, seqId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -610,9 +659,10 @@ export default class API {
 
 	/**
 	 * Get the RSS feed URL with map parameters (if map is enabled)
-	 * 
+	 * @memberOf Panoramax.utils.API#
 	 * @param {LngLatBounds} [bbox] The map current bounding box, or null if not available
-	 * @returns {string} The URL, or null if no RSS feed is available
+	 * @returns {string|null} The URL, or null if no RSS feed is available
+	 * @throws {Error} If API is not ready
 	 */
 	getRSSURL(bbox) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -632,9 +682,10 @@ export default class API {
 
 	/**
 	 * Get full URL for retrieving a specific sequence metadata
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} seqId The sequence ID
 	 * @returns {string} The corresponding URL
+	 * @throws {Error} If API is not ready
 	 */
 	getSequenceMetadataUrl(seqId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -643,8 +694,9 @@ export default class API {
 
 	/**
 	 * Get available data bounding box
-	 *
+	 * @memberOf Panoramax.utils.API#
 	 * @returns {LngLatBoundsLike} The bounding box or null if not available
+	 * @throws {Error} If API is not ready
 	 */
 	getDataBbox() {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -654,8 +706,11 @@ export default class API {
 
 	/**
 	 * Look for user ID based on user name query
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} query The user name to look for
-	 * @returns {Promise} Resolves on list of potential users
+	 * @returns {Promise}
+	 * @fulfil {object|null} List of potential users
+	 * @throws {Error} If API is not ready or user search not available
 	 */
 	searchUsers(query) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -670,8 +725,11 @@ export default class API {
 
 	/**
 	 * Get user name based on its ID
+	 * @memberOf Panoramax.utils.API#
 	 * @param {string} userId The user UUID
-	 * @returns {Promise} Resolves on user name
+	 * @returns {Promise}
+	 * @throws {Error} If API is not ready
+	 * @fulfil {string|null} The user name (or null if not found)
 	 */
 	getUserName(userId) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -686,8 +744,10 @@ export default class API {
 
 	/**
 	 * Send a report to API
+	 * @memberOf Panoramax.utils.API#
 	 * @param {object} data The input form data
-	 * @returns {Promise} Resolves on report sent
+	 * @returns {Promise}
+	 * @fulfil {object} The JSON API response
 	 */
 	sendReport(data) {
 		if(!this.isReady()) { throw new Error("API is not ready to use"); }
@@ -715,7 +775,7 @@ export default class API {
 
 	/**
 	 * Checks URL string validity
-	 *
+	 * @memberOf Panoramax.utils.API
 	 * @param {string} str The URL to check
 	 * @returns {boolean} True if valid
 	 */
@@ -733,13 +793,13 @@ export default class API {
 
 	/**
 	 * Checks picture or sequence ID validity
-	 *
+	 * @memberOf Panoramax.utils.API
 	 * @param {string} id The ID to check
 	 * @returns {boolean} True if valid
 	 * @throws {Error} If not valid
 	 */
 	static isIdValid(id) {
-		if(!id || typeof id !== "string" || id.length === 0 || id === BASE_PANORAMA_ID) {
+		if(isNullId(id)) {
 			throw new Error("id should be a valid picture unique identifier");
 		}
 		return true;