@openeo/js-client 2.3.1 → 2.5.0

package/src/connection.js

@@ -51,21 +51,21 @@ class Connection {
 		 * Auth Provider cache
 		 * 
 		 * @protected
-		 * @type {?Array.<AuthProvider>}
+		 * @type {Array.<AuthProvider> | null}
 		 */
 		this.authProviderList = null;
 		/**
 		 * Current auth provider
 		 * 
 		 * @protected
-		 * @type {?AuthProvider}
+		 * @type {AuthProvider | null}
 		 */
 		this.authProvider = null;
 		/**
 		 * Capability cache
 		 * 
 		 * @protected
-		 * @type {?Capabilities}
+		 * @type {Capabilities | null}
 		 */
 		this.capabilitiesObject = null;
 		/**
@@ -119,11 +119,12 @@ class Connection {
 		let promises = this.processes.namespaces().map(namespace => {
 			let fn = () => Promise.resolve();
 			if (namespace === 'user') {
+				let userProcesses = this.processes.namespace('user');
 				if (!this.isAuthenticated()) {
 					fn = () => (this.processes.remove(null, 'user') ? Promise.resolve() : Promise.reject(new Error("Can't clear user processes")));
 				}
 				else if (this.capabilities().hasFeature('listUserProcesses')) {
-					fn = () => this.listUserProcesses();
+					fn = () => this.listUserProcesses(userProcesses);
 				}
 			}
 			else if (this.capabilities().hasFeature('listProcesses')) {
@@ -244,7 +245,7 @@ class Connection {
 	 * 2. Lower left corner, coordinate axis 2
 	 * 3. Upper right corner, coordinate axis 1
 	 * 4. Upper right corner, coordinate axis 2
-	 * @param {?Array.<*>} [temporalExtent=null] - Limits the items to the specified temporal interval.
+	 * @param {?Array} [temporalExtent=null] - Limits the items to the specified temporal interval.
 	 * The interval has to be specified as an array with exactly two elements (start, end) and
 	 * each must be either an RFC 3339 compatible string or a Date object.
 	 * Also supports open intervals by setting one of the boundaries to `null`, but never both.
@@ -290,6 +291,25 @@ class Connection {
 		}
 	}
 
+	/**
+	 * Normalisation of the namespace to a value that is compatible with the OpenEO specs - EXPERIMENTAL.
+	 *
+	 * This is required to support UDP that are shared as public. These can only be executed with providing the full URL
+	 * (e.g. https://<backend>/processes/<namespace>/<process_id>) as the namespace value in the processing graph. For other
+	 * parts of the API (such as the listing of the processes, only the name of the namespace is required.
+	 *
+	 * This function will extract the short name of the namespace from a shareable URL.
+	 * 
+	 * @protected
+	 * @param {?string} namespace - Namespace of the process
+	 * @returns {?string}
+	 */
+	normalizeNamespace(namespace) {
+		// The pattern in https://github.com/Open-EO/openeo-api/pull/348 doesn't include the double colon yet - the regexp may change in the future
+		const matches = namespace.match( /^https?:\/\/.*\/processes\/(@?[\w\-.~:]+)\/?/i);
+		return matches && matches.length > 1 ? matches[1] : namespace;
+	}
+
 	/**
 	 * List processes available on the back-end.
 	 * 
@@ -308,7 +328,7 @@ class Connection {
 		if (!namespace) {
 			namespace = 'backend';
 		}
-		let path = (namespace === 'backend') ? '/processes' : `/processes/${namespace}`;
+		let path = (namespace === 'backend') ? '/processes' : `/processes/${this.normalizeNamespace(namespace)}`;
 		let response = await this._get(path);
 
 		if (!Utils.isObject(response.data) || !Array.isArray(response.data.processes)) {
@@ -340,7 +360,7 @@ class Connection {
 			await this.listProcesses();
 		}
 		else {
-			let response = await this._get(`/processes/${namespace}/${processId}`);
+			let response = await this._get(`/processes/${this.normalizeNamespace(namespace)}/${processId}`);
 			if (!Utils.isObject(response.data) || typeof response.data.id !== 'string') {
 				throw new Error('Invalid response received for process');
 			}
@@ -588,14 +608,15 @@ class Connection {
 	 * Lists all files from the user workspace. 
 	 * 
 	 * @async
-	 * @returns {Promise<Array.<UserFile>>} A list of files.
+	 * @returns {Promise<ResponseArray.<UserFile>>} A list of files.
 	 * @throws {Error}
 	 */
 	async listFiles() {
 		let response = await this._get('/files');
-		return response.data.files.map(
+		let files = response.data.files.map(
 			f => new UserFile(this, f.path).setAll(f)
 		);
+		return this._toResponseArray(files, response.data);
 	}
 
 	/**
@@ -689,23 +710,34 @@ class Connection {
 	 * Lists all user-defined processes of the authenticated user.
 	 * 
 	 * @async
-	 * @returns {Promise<Array.<UserProcess>>} A list of user-defined processes.
+	 * @param {Array.<UserProcess>} [oldProcesses=[]] - A list of existing user-defined processes to update.
+	 * @returns {Promise<ResponseArray.<UserProcess>>} A list of user-defined processes.
 	 * @throws {Error}
 	 */
-	async listUserProcesses() {
+	async listUserProcesses(oldProcesses = []) {
 		let response = await this._get('/process_graphs');
 
 		if (!Utils.isObject(response.data) || !Array.isArray(response.data.processes)) {
 			throw new Error('Invalid response received for processes');
 		}
 
-		// Store processes in cache
+		// Remove existing processes from cache
 		this.processes.remove(null, 'user');
-		this.processes.addAll(response.data.processes, 'user');
 
-		return response.data.processes.map(
-			pg => new UserProcess(this, pg.id).setAll(pg)
-		);
+		// Update existing processes if needed
+		let newProcesses = response.data.processes.map(newProcess => {
+			let process = oldProcesses.find(oldProcess => oldProcess.id === newProcess.id);
+			if (!process) {
+				process = new UserProcess(this, newProcess.id);
+			}
+			return process.setAll(newProcess);
+		});
+		
+		// Store plain JS variant (i.e. no Job objects involved) of processes in cache
+		let jsonProcesses = oldProcesses.length > 0 ? newProcesses.map(p => p.toJSON()) : response.data.processes;
+		this.processes.addAll(jsonProcesses, 'user');
+
+		return this._toResponseArray(newProcesses, response.data);
 	}
 
 	/**
@@ -819,14 +851,21 @@ class Connection {
 	 * Lists all batch jobs of the authenticated user.
 	 * 
 	 * @async
-	 * @returns {Promise<Array.<Job>>} A list of jobs.
+	 * @param {Array.<Job>} [oldJobs=[]] - A list of existing jobs to update.
+	 * @returns {Promise<ResponseArray.<Job>>} A list of jobs.
 	 * @throws {Error}
 	 */
-	async listJobs() {
+	async listJobs(oldJobs = []) {
 		let response = await this._get('/jobs');
-		return response.data.jobs.map(
-			j => new Job(this, j.id).setAll(j)
-		);
+		let newJobs = response.data.jobs.map(newJob => {
+			delete newJob.status;
+			let job = oldJobs.find(oldJob => oldJob.id === newJob.id);
+			if (!job) {
+				job = new Job(this, newJob.id);
+			}
+			return job.setAll(newJob);
+		});
+		return this._toResponseArray(newJobs, response.data);
 	}
 
 	/**
@@ -880,14 +919,20 @@ class Connection {
 	 * Lists all secondary web services of the authenticated user.
 	 * 
 	 * @async
-	 * @returns {Promise<Array.<Job>>} A list of services.
+	 * @param {Array.<Service>} [oldServices=[]] - A list of existing services to update.
+	 * @returns {Promise<ResponseArray.<Job>>} A list of services.
 	 * @throws {Error}
 	 */
-	async listServices() {
+	async listServices(oldServices = []) {
 		let response = await this._get('/services');
-		return response.data.services.map(
-			s => new Service(this, s.id).setAll(s)
-		);
+		let newServices = response.data.services.map(newService => {
+			let service = oldServices.find(oldService => oldService.id === newService.id);
+			if (!service) {
+				service = new Service(this, newService.id);
+			}
+			return service.setAll(newService);
+		});
+		return this._toResponseArray(newServices, response.data);
 	}
 
 	/**
@@ -942,9 +987,26 @@ class Connection {
 		return await service.describeService();
 	}
 
+	/**
+	 * Adds additional response details to the array.
+	 * 
+	 * Adds links and federation:missing.
+	 * 
+	 * @protected
+	 * @param {Array.<*>} arr 
+	 * @param {object.<string, *>} response 
+	 * @returns {ResponseArray}
+	 */
+	_toResponseArray(arr, response) {
+		arr.links = Array.isArray(response.links) ? response.links : [];
+		arr['federation:missing'] = Array.isArray(response['federation:missing']) ? response['federation:missing'] : [];
+		return arr;
+	}
+
 	/**
 	 * Get the a link with the given rel type.
 	 * 
+	 * @protected
 	 * @param {Array.<Link>} links - An array of links.
 	 * @param {string} rel - Relation type to find, defaults to `next`.
 	 * @returns {string | null}
@@ -963,6 +1025,7 @@ class Connection {
 	/**
 	 * Sends a GET request.
 	 * 
+	 * @protected
 	 * @async
 	 * @param {string} path 
 	 * @param {object.<string, *>} query 
@@ -986,6 +1049,7 @@ class Connection {
 	/**
 	 * Sends a POST request.
 	 * 
+	 * @protected
 	 * @async
 	 * @param {string} path 
 	 * @param {*} body 
@@ -1008,6 +1072,7 @@ class Connection {
 	/**
 	 * Sends a PUT request.
 	 * 
+	 * @protected
 	 * @async
 	 * @param {string} path 
 	 * @param {*} body 
@@ -1025,6 +1090,7 @@ class Connection {
 	/**
 	 * Sends a PATCH request.
 	 * 
+	 * @protected
 	 * @async
 	 * @param {string} path 
 	 * @param {*} body 
@@ -1042,6 +1108,7 @@ class Connection {
 	/**
 	 * Sends a DELETE request.
 	 * 
+	 * @protected
 	 * @async
 	 * @param {string} path 
 	 * @returns {Promise<AxiosResponse>}
@@ -1086,6 +1153,7 @@ class Connection {
 	 * Tries to smoothly handle error responses by providing an object for all response types,
 	 * instead of Streams or Blobs for non-JSON response types.
 	 * 
+	 * @protected
 	 * @async
 	 * @param {object.<string, *>} options 
 	 * @param {?AbortController} [abortController=null] - An AbortController object that can be used to cancel the request.

package/src/filetypes.js

@@ -12,6 +12,7 @@ class FileTypes {
 	 */
 	constructor(data) {
 		/**
+		 * @protected
 		 * @type {FileTypesAPI}
 		 */
 		this.data = {
@@ -29,6 +30,13 @@ class FileTypes {
 				this.data[io][type.toUpperCase()] = data[io][type];
 			}
 		}
+		/**
+		 * A list of backends from the federation that are missing in the response data.
+		 * 
+		 * @public
+		 * @type {Array.<string>}
+		 */
+		this['federation:missing'] = data['federation:missing'];
 	}
 
 	/**

package/src/job.js

@@ -44,7 +44,7 @@ class Job extends BaseEntity {
 		 * The process chain to be executed.
 		 * @public
 		 * @readonly
-		 * @type {Process}
+		 * @type {?Process}
 		 */
 		this.process = undefined;
 		/**
@@ -52,35 +52,35 @@ class Job extends BaseEntity {
 		 * One of "created", "queued", "running", "canceled", "finished" or "error".
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.status = undefined;
 		/**
 		 * Indicates the process of a running batch job in percent. 
 		 * @public
 		 * @readonly
-		 * @type {number}
+		 * @type {?number}
 		 */
 		this.progress = undefined;
 		/**
 		 * Date and time of creation, formatted as a RFC 3339 date-time.
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.created = undefined;
 		/**
 		 * Date and time of the last status change, formatted as a RFC 3339 date-time.
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.updated = undefined;
 		/**
 		 * The billing plan to process and charge the batch job with.
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.plan = undefined;
 		/**

package/src/oidcprovider.js

@@ -78,7 +78,7 @@ class OidcProvider extends AuthProvider {
 		/**
 		 * The client ID to use for authentication.
 		 * 
-		 * @type {?string}
+		 * @type {string | null}
 		 */
 		this.clientId = null;
 
@@ -105,6 +105,13 @@ class OidcProvider extends AuthProvider {
 		 */
 		this.scopes = Array.isArray(options.scopes) && options.scopes.length > 0 ? options.scopes : ['openid'];
 
+		/**
+		 * The scope that is used to request a refresh token.
+		 * 
+		 * @type {string}
+		 */
+		this.refreshTokenScope = "offline_access";
+
 		/**
 		 * Any additional links.
 		 * 
@@ -161,17 +168,20 @@ class OidcProvider extends AuthProvider {
 	 * 
 	 * Supported only in Browser environments.
 	 * 
+	 * @async
 	 * @param {object.<string, *>} [options={}] - Object with authentication options.
+	 * @param {boolean} [requestRefreshToken=false] - If set to `true`, adds a scope to request a refresh token.
 	 * @returns {Promise<void>}
 	 * @throws {Error}
 	 * @see https://github.com/IdentityModel/oidc-client-js/wiki#other-optional-settings
+	 * @see {OidcProvider#refreshTokenScope}
 	 */
-	async login(options = {}) {
+	async login(options = {}, requestRefreshToken = false) {
 		if (!this.issuer || typeof this.issuer !== 'string') {
 			throw new Error("No Issuer URL available for OpenID Connect");
 		}
 
-		this.manager = new Oidc.UserManager(this.getOptions(options));
+		this.manager = new Oidc.UserManager(this.getOptions(options, requestRefreshToken));
 		this.addListener('UserLoaded', async () => this.setUser(await this.manager.getUser()), 'js-client');
 		this.addListener('AccessTokenExpired', () => this.setUser(null), 'js-client');
 		if (OidcProvider.uiMethod === 'popup') {
@@ -216,15 +226,22 @@ class OidcProvider extends AuthProvider {
 	 * 
 	 * @protected
 	 * @param {object.<string, *>} options 
+	 * @param {boolean} [requestRefreshToken=false] - If set to `true`, adds a scope to request a refresh token.
 	 * @returns {object.<string, *>}
+	 * @see {OidcProvider#refreshTokenScope}
 	 */
-	getOptions(options = {}) {
+	getOptions(options = {}, requestRefreshToken = false) {
 		let response_type = this.getResponseType();
+		let scope = this.scopes.slice(0);
+		if (requestRefreshToken && !scope.includes(this.refreshTokenScope)) {
+			scope.push(this.refreshTokenScope);
+		}
+
 		return Object.assign({
 			client_id: this.clientId,
 			redirect_uri: OidcProvider.redirectUrl,
 			authority: this.issuer.replace('/.well-known/openid-configuration', ''),
-			scope: this.scopes.join(' '),
+			scope: scope.join(' '),
 			validateSubOnSilentRenew: true,
 			response_type,
 			response_mode: response_type.includes('code') ? 'query' : 'fragment'

package/src/openeo.js

@@ -110,7 +110,7 @@ class OpenEO {
 	 * @returns {string} Version number (according to SemVer).
 	 */
 	static clientVersion() {
-		return "2.3.1";
+		return "2.5.0";
 	}
 
 }

package/src/service.js

@@ -39,55 +39,55 @@ class Service extends BaseEntity {
 		 * The process chain to be executed.
 		 * @public
 		 * @readonly
-		 * @type {Process}
+		 * @type {?Process}
 		 */
 		this.process = undefined;
 		/**
 		 * URL at which the secondary web service is accessible
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.url = undefined;
 		/**
 		 * Web service type (protocol / standard) that is exposed.
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.type = undefined;
 		/**
 		 * @public
 		 * @readonly
-		 * @type {boolean}
+		 * @type {?boolean}
 		 */
 		this.enabled = undefined;
 		/**
 		 * Map of configuration settings, i.e. the setting names supported by the secondary web service combined with actual values. 
 		 * @public
 		 * @readonly
-		 * @type {object.<string, *>}
+		 * @type {?object.<string, *>}
 		 */
 		this.configuration = undefined;
 		/**
 		 * Additional attributes of the secondary web service, e.g. available layers for a WMS based on the bands in the underlying GeoTiff.
 		 * @public
 		 * @readonly
-		 * @type {object.<string, *>}
+		 * @type {?object.<string, *>}
 		 */
 		this.attributes = undefined;
 		/**
 		 * Date and time of creation, formatted as a RFC 3339 date-time.
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.created = undefined;
 		/**
 		 * The billing plan to process and charge the service with.
 		 * @public
 		 * @readonly
-		 * @type {string}
+		 * @type {?string}
 		 */
 		this.plan = undefined;
 		/**

package/src/typedefs.js

@@ -193,6 +193,18 @@
  * @type {object.<string, *>} 
  */
 
+/**
+ * An array, but enriched with additional details from an openEO API response.
+ * 
+ * Adds two properties: `links` and `federation:missing`.
+ * 
+ * @typedef ResponseArray
+ * @augments Array
+ * @type {Array.<*>}
+ * @property {Array.<Link>} links A list of related links.
+ * @property {Array.<string>} federation:missing A list of backends from the federation that are missing in the response data.
+ */
+
 /**
  * @typedef ServiceType
  * @type {object.<string, *>}

package/src/userprocess.js

@@ -52,7 +52,7 @@ class UserProcess extends BaseEntity {
 		 * A list of categories.
 		 * @public
 		 * @readonly
-		 * @type {Array.<string>}
+		 * @type {?Array.<string>}
 		 */
 		this.categories = undefined;
 		/**
@@ -74,40 +74,40 @@ class UserProcess extends BaseEntity {
 		 * Specifies that the process or parameter is deprecated with the potential to be removed in any of the next versions. 
 		 * @public
 		 * @readonly
-		 * @type {boolean}
+		 * @type {?boolean}
 		 */
 		this.deprecated = undefined;
 		/**
 		 * Declares the process or parameter to be experimental, which means that it is likely to change or may produce unpredictable behaviour. 
 		 * @public
 		 * @readonly
-		 * @type {boolean}
+		 * @type {?boolean}
 		 */
 		this.experimental = undefined;
 		/**
 		 * Declares any exceptions (errors) that might occur during execution of this process.
 		 * @public
 		 * @readonly
-		 * @type {object.<string, *>}
+		 * @type {?object.<string, *>}
 		 */
 		this.exceptions = undefined;
 		/**
 		 * @public
 		 * @readonly
-		 * @type {Array.<object.<string, *>>}
+		 * @type {?Array.<object.<string, *>>}
 		 */
 		this.examples = undefined;
 		/**
 		 * Links related to this process.
 		 * @public
 		 * @readonly
-		 * @type {Array.<Link>}
+		 * @type {?Array.<Link>}
 		 */
 		this.links = undefined;
 		/**
 		 * @public
 		 * @readonly
-		 * @type {object.<string, *>}
+		 * @type {?object.<string, *>}
 		 */
 		this.processGraph = undefined;
 	}