@openeo/js-client 2.6.0 → 2.8.0

package/README.md

@@ -4,7 +4,7 @@ JavaScript/TypeScript client for the openEO API.
 
 * [Documentation](https://open-eo.github.io/openeo-js-client/latest/).
 
-The version of this client is **2.6.0** and supports **openEO API versions 1.x.x**.
+The version of this client is **2.8.0** and supports **openEO API versions 1.x.x**.
 Legacy versions are available as releases.
 See the [CHANGELOG](CHANGELOG.md) for recent changes.
 
@@ -18,7 +18,7 @@ An *experimental* Typescript declaration file is available so that you can use t
 
 To use it in a browser environment simply add the following code to your HTML file:
 ```html
-<script src="https://cdn.jsdelivr.net/npm/axios@0.21/dist/axios.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/axios@1/dist/axios.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/oidc-client@1/dist/oidc-client.min.js"></script> <!-- Only required if you'd like to enable authentication via OpenID Connect -->
 <script src="https://cdn.jsdelivr.net/npm/multihashes@3/src/index.min.js"></script> <!-- Only required if you have checksums in the STAC metadata -->
 <script src="https://cdn.jsdelivr.net/npm/@openeo/js-client@2/openeo.min.js"></script>
@@ -32,7 +32,7 @@ To install it in a NodeJS environment run:
 Afterwards, you can import the package:
 `const { OpenEO } = require('@openeo/js-client');`
 
-### TypeScript 
+### TypeScript
 
 Warning: The TypeScript integration is still **experimental**! Please help us improve it by opening issues or pull requests.
 
@@ -91,4 +91,4 @@ This package received major contributions from the following organizations:
 
 There is an interactive web-based editor for coding using the openEO API,
 which is based on the JavaScript client.
-See [https://github.com/Open-EO/openeo-web-editor](https://github.com/Open-EO/openeo-web-editor) for more details.
+See [https://github.com/Open-EO/openeo-web-editor](https://github.com/Open-EO/openeo-web-editor) for more details.

package/openeo.d.ts

@@ -3,6 +3,7 @@
 import { User, UserManager } from 'oidc-client';
 import { ProcessRegistry } from '@openeo/js-commons';
 import { Readable } from 'stream';
+import axios from 'axios';
 
 declare module OpenEO {
     /**
@@ -197,6 +198,14 @@ declare module OpenEO {
      * @hideconstructor
      */
     export class Environment {
+        /**
+         * The axios instance to use for HTTP requests.
+         *
+         * 
+         * @type {object}
+         * @static
+         */
+        static axios: axios;
         /**
          * Returns the name of the Environment, `Node` or `Browser`.
          *
@@ -241,7 +250,7 @@ declare module OpenEO {
          * @param {string|Buffer} str - String to encode.
          * @returns {string} String encoded in Base64.
          */
-        static base64encode(str: string|Buffer): string;
+        static base64encode(str: string | Buffer): string;
         /**
          * Detect the file name for the given data source.
          *
@@ -302,14 +311,14 @@ declare module OpenEO {
         username: string;
         /**
          * Authenticate with HTTP Basic.
-         * 
+         *
          * @async
-         * @param {string} username 
-         * @param {string} password 
+         * @param {string} username
+         * @param {string} password
          * @returns {Promise<void>}
          * @throws {Error}
          */
-        login(username: string, password: string) : Promise<void>;
+        login(username: string, password: string): Promise<void>;
     }
     /**
      * Capabilities of a back-end.
@@ -395,6 +404,26 @@ declare module OpenEO {
          * @returns {Array.<Link>} Array of link objects (href, title, rel, type)
          */
         links(): Array<Link>;
+        /**
+         * Returns list of backends in the federation.
+         *
+         * @returns {Array.<FederationBackend>} Array of backends
+         */
+        listFederation(): Array<FederationBackend>;
+        /**
+         * Given just the string ID of a backend within the federation, returns that backend's full details as a FederationBackend object.
+         *
+         * @param {string} backendId - The ID of a backend within the federation
+         * @returns {FederationBackend} The full details of the backend
+         */
+        getFederationBackend(backendId: string): FederationBackend;
+        /**
+         * Given a list of string IDs of backends within the federation, returns those backends' full details as FederationBackend objects.
+         *
+         * @param {Array<string>} backendIds - The IDs of backends within the federation
+         * @returns {Array<FederationBackend>} An array in the same order as the input, containing for each position the full details of the backend
+         */
+        getFederationBackends(backendIds: Array<string>): Array<FederationBackend>;
         /**
          * Lists all supported features.
          *
@@ -806,9 +835,26 @@ declare module OpenEO {
          * @type {Connection}
          */
         protected connection: Connection;
-        endpoint: string;
-        lastId: string;
-        level: string;
+        /**
+         * @protected
+         * @type {string}
+         */
+        protected endpoint: string;
+        /**
+         * @protected
+         * @type {string}
+         */
+        protected lastId: string;
+        /**
+         * @protected
+         * @type {?string}
+         */
+        protected level: string | null;
+        /**
+         * @protected
+         * @type {Set<string>}
+         */
+        protected missing: Set<string>;
         /**
          * Retrieves the next log entries since the last request.
          *
@@ -819,6 +865,16 @@ declare module OpenEO {
          * @returns {Promise<Array.<Log>>}
          */
         nextLogs(limit?: number): Promise<Array<Log>>;
+        /**
+         * Retrieves the backend identifiers that are (partially) missing in the logs.
+         *
+         * This is only filled after the first request using `nextLogs` or `next`.
+         *
+         * @returns {Array.<string>}
+         * @see {Logs#nextLogs}
+         * @see {Logs#next}
+         */
+        getMissingBackends(): Array<string>;
         /**
          * Retrieves the next log entries since the last request.
          *
@@ -1846,6 +1902,158 @@ declare module OpenEO {
          */
         generateId(prefix?: string): string;
     }
+    /**
+     * A class to handle pagination of resources.
+     *
+     * @abstract
+     */
+    export class Pages {
+        /**
+         * Creates an instance of Pages.
+         *
+         * @param {Connection} connection
+         * @param {string} endpoint
+         * @param {string} key
+         * @param {Constructor} cls - Class
+         * @param {object} [params={}]
+         * @param {string} primaryKey
+         */
+        constructor(connection: Connection, endpoint: string, key: string, cls: Constructor, params?: object, primaryKey?: string);
+        connection: Connection;
+        nextUrl: string;
+        key: string;
+        primaryKey: string;
+        cls: Constructor;
+        params: any;
+        /**
+         * Returns true if there are more pages to fetch.
+         *
+         * @returns {boolean}
+         */
+        hasNextPage(): boolean;
+        /**
+         * Returns the next page of resources.
+         *
+         * @async
+         * @param {Array.<object>} oldObjects - Existing objects to update, if any.
+         * @param {boolean} [toArray=true] - Whether to return the objects as a simplified array or as an object with all information.
+         * @returns {Array.<object>}
+         * @throws {Error}
+         */
+        nextPage(oldObjects?: Array<object>, toArray?: boolean): Array<object>;
+        /**
+         * Ensures a variable is an array.
+         *
+         * @protected
+         * @param {*} x
+         * @returns {Array}
+         */
+        protected _ensureArray(x: any): any[];
+        /**
+         * Creates a facade for the object, if needed.
+         *
+         * @protected
+         * @param {object} obj
+         * @returns {object}
+         */
+        protected _createObject(obj: object): object;
+        /**
+         * Caches the plain objects if needed.
+         *
+         * @param {Array.<object>} objects
+         * @returns {Array.<object>}
+         */
+        _cache(objects: Array<object>): Array<object>;
+        /**
+         * Get the URL of the next page from a response.
+         *
+         * @protected
+         * @param {AxiosResponse} response
+         * @returns {string | null}
+         */
+        protected _getNextLink(response: AxiosResponse): string | null;
+        /**
+         * Makes this class asynchronously iterable.
+         *
+         * @returns {AsyncIterator}
+         */
+        [Symbol.asyncIterator](): AsyncIterator<any, any, any>;
+    }
+    /**
+     * Paginate through collections.
+     */
+    export class CollectionPages extends Pages {
+        /**
+         * Paginate through collections.
+         *
+         * @param {Connection} connection
+         * @param {?number} limit
+         */
+        constructor(connection: Connection, limit?: number | null);
+    }
+    /**
+     * Paginate through collection items.
+     */
+    export class ItemPages extends Pages {
+        /**
+         * Paginate through collection items.
+         *
+         * @param {Connection} connection
+         * @param {string} collectionId
+         * @param {object} params
+         */
+        constructor(connection: Connection, collectionId: string, params: object);
+    }
+    /**
+     * Paginate through jobs.
+     */
+    export class JobPages extends Pages {
+        /**
+         * Paginate through jobs.
+         *
+         * @param {Connection} connection
+         * @param {?number} limit
+         */
+        constructor(connection: Connection, limit?: number | null);
+    }
+    /**
+     * Paginate through processes.
+     */
+    export class ProcessPages extends Pages {
+        /**
+         * Paginate through processes.
+         *
+         * @param {Connection} connection
+         * @param {?number} limit
+         * @param {?string} namespace
+         */
+        constructor(connection: Connection, limit?: number | null, namespace?: string | null);
+        namespace: string;
+    }
+    /**
+     * Paginate through services.
+     */
+    export class ServicePages extends Pages {
+        /**
+         * Paginate through services.
+         *
+         * @param {Connection} connection
+         * @param {?number} limit
+         */
+        constructor(connection: Connection, limit?: number | null);
+    }
+    /**
+     * Paginate through user files.
+     */
+    export class UserFilePages extends Pages {
+        /**
+         * Paginate through user files.
+         *
+         * @param {Connection} connection
+         * @param {?number} limit
+         */
+        constructor(connection: Connection, limit?: number | null);
+    }
     /**
      * A connection to a back-end.
      */
@@ -1979,12 +2187,22 @@ declare module OpenEO {
          * List all collections available on the back-end.
          *
          * The collections returned always comply to the latest STAC version (currently 1.0.0).
+         * This function adds a self link to the response if not present.
          *
          * @async
          * @returns {Promise<Collections>} A response compatible to the API specification.
          * @throws {Error}
          */
         listCollections(): Promise<Collections>;
+        /**
+         * Paginate through the collections available on the back-end.
+         *
+         * The collections returned always comply to the latest STAC version (currently 1.0.0).
+         *
+         * @param {?number} [limit=50] - The number of collections per request/page as integer. If `null`, requests all collections.
+         * @returns {CollectionPages} A paged list of collections.
+         */
+        paginateCollections(limit?: number | null): CollectionPages;
         /**
          * Get further information about a single collection.
          *
@@ -1997,13 +2215,12 @@ declare module OpenEO {
          */
         describeCollection(collectionId: string): Promise<Collection>;
         /**
-         * Loads items for a specific image collection.
+         * Paginate through items for a specific collection.
+         *
          * May not be available for all collections.
          *
          * The items returned always comply to the latest STAC version (currently 1.0.0).
          *
-         * This is an experimental API and is subject to change.
-         *
          * @async
          * @param {string} collectionId - Collection ID to request items for.
          * @param {?Array.<number>} [spatialExtent=null] - Limits the items to the given bounding box in WGS84:
@@ -2016,10 +2233,10 @@ declare module OpenEO {
          * 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.
          * @param {?number} [limit=null] - The amount of items per request/page as integer. If `null` (default), the back-end decides.
-         * @yields {Promise<ItemCollection>} A response compatible to the API specification.
+         * @returns {Promise<ItemPages>} A response compatible to the API specification.
          * @throws {Error}
          */
-        listCollectionItems(collectionId: string, spatialExtent?: Array<number> | null, temporalExtent?: any[] | null, limit?: number | null): AsyncGenerator<any, void, unknown>;
+        listCollectionItems(collectionId: string, spatialExtent?: Array<number> | null, temporalExtent?: any[] | null, limit?: number | null): Promise<ItemPages>;
         /**
          * Normalisation of the namespace to a value that is compatible with the OpenEO specs - EXPERIMENTAL.
          *
@@ -2035,7 +2252,7 @@ declare module OpenEO {
          */
         protected normalizeNamespace(namespace: string | null): string | null;
         /**
-         * List processes available on the back-end.
+         * List all processes available on the back-end.
          *
          * Requests pre-defined processes by default.
          * Set the namespace parameter to request processes from a specific namespace.
@@ -2043,12 +2260,28 @@ declare module OpenEO {
          * Note: The list of namespaces can be retrieved by calling `listProcesses` without a namespace given.
          * The namespaces are then listed in the property `namespaces`.
          *
+         * This function adds a self link to the response if not present.
+         *
          * @async
          * @param {?string} [namespace=null] - Namespace of the processes (default to `null`, i.e. pre-defined processes). EXPERIMENTAL!
          * @returns {Promise<Processes>} - A response compatible to the API specification.
          * @throws {Error}
          */
         listProcesses(namespace?: string | null): Promise<Processes>;
+        /**
+         * Paginate through the processes available on the back-end.
+         *
+         * Requests pre-defined processes by default.
+         * Set the namespace parameter to request processes from a specific namespace.
+         *
+         * Note: The list of namespaces can be retrieved by calling `listProcesses` without a namespace given.
+         * The namespaces are then listed in the property `namespaces`.
+         *
+         * @param {?string} [namespace=null] - Namespace of the processes (default to `null`, i.e. pre-defined processes). EXPERIMENTAL!
+         * @param {?number} [limit=50] - The number of processes per request/page as integer. If `null`, requests all processes.
+         * @returns {ProcessPages} A paged list of processes.
+         */
+        paginateProcesses(namespace?: string | null, limit?: number | null): ProcessPages;
         /**
          * Get information about a single process.
          *
@@ -2198,13 +2431,20 @@ declare module OpenEO {
          */
         describeAccount(): Promise<UserAccount>;
         /**
-         * Lists all files from the user workspace.
+         * List all files from the user workspace.
          *
          * @async
          * @returns {Promise<ResponseArray.<UserFile>>} A list of files.
          * @throws {Error}
          */
         listFiles(): Promise<ResponseArray<UserFile>>;
+        /**
+         * Paginate through the files from the user workspace.
+         *
+         * @param {?number} [limit=50] - The number of files per request/page as integer. If `null`, requests all files.
+         * @returns {ServicePages} A paged list of files.
+         */
+        paginateFiles(limit?: number | null): ServicePages;
         /**
          * A callback that is executed on upload progress updates.
          *
@@ -2253,12 +2493,12 @@ declare module OpenEO {
          *
          * @async
          * @param {Process} process - User-defined process to validate.
-         * @returns {Promise<Array.<ApiError>>} errors - A list of API compatible error objects. A valid process returns an empty list.
+         * @returns {Promise<ValidationResult>} errors - A list of API compatible error objects. A valid process returns an empty list.
          * @throws {Error}
          */
-        validateProcess(process: Process): Promise<Array<ApiError>>;
+        validateProcess(process: Process): Promise<ValidationResult>;
         /**
-         * Lists all user-defined processes of the authenticated user.
+         * List all user-defined processes of the authenticated user.
          *
          * @async
          * @param {Array.<UserProcess>} [oldProcesses=[]] - A list of existing user-defined processes to update.
@@ -2266,6 +2506,13 @@ declare module OpenEO {
          * @throws {Error}
          */
         listUserProcesses(oldProcesses?: Array<UserProcess>): Promise<ResponseArray<UserProcess>>;
+        /**
+         * Paginates through the user-defined processes of the authenticated user.
+         *
+         * @param {?number} [limit=50] - The number of processes per request/page as integer. If `null`, requests all processes.
+         * @returns {ProcessPages} A paged list of user-defined processes.
+         */
+        paginateUserProcesses(limit?: number | null): ProcessPages;
         /**
          * Creates a new stored user-defined process at the back-end.
          *
@@ -2318,7 +2565,7 @@ declare module OpenEO {
          */
         downloadResult(process: Process, targetPath: string, plan?: string | null, budget?: number | null, abortController?: AbortController | null): Promise<void>;
         /**
-         * Lists all batch jobs of the authenticated user.
+         * List all batch jobs of the authenticated user.
          *
          * @async
          * @param {Array.<Job>} [oldJobs=[]] - A list of existing jobs to update.
@@ -2326,6 +2573,13 @@ declare module OpenEO {
          * @throws {Error}
          */
         listJobs(oldJobs?: Array<Job>): Promise<ResponseArray<Job>>;
+        /**
+         * Paginate through the batch jobs of the authenticated user.
+         *
+         * @param {?number} [limit=50] - The number of jobs per request/page as integer. If `null`, requests all jobs.
+         * @returns {JobPages} A paged list of jobs.
+         */
+        paginateJobs(limit?: number | null): JobPages;
         /**
          * Creates a new batch job at the back-end.
          *
@@ -2350,7 +2604,7 @@ declare module OpenEO {
          */
         getJob(id: string): Promise<Job>;
         /**
-         * Lists all secondary web services of the authenticated user.
+         * List all secondary web services of the authenticated user.
          *
          * @async
          * @param {Array.<Service>} [oldServices=[]] - A list of existing services to update.
@@ -2358,6 +2612,13 @@ declare module OpenEO {
          * @throws {Error}
          */
         listServices(oldServices?: Array<Service>): Promise<ResponseArray<Job>>;
+        /**
+         * Paginate through the secondary web services of the authenticated user.
+         *
+         * @param {?number} [limit=50] - The number of services per request/page as integer. If `null` (default), requests all services.
+         * @returns {ServicePages} A paged list of services.
+         */
+        paginateServices(limit?: number | null): ServicePages;
         /**
          * Creates a new secondary web service at the back-end.
          *
@@ -2384,17 +2645,6 @@ declare module OpenEO {
          * @throws {Error}
          */
         getService(id: string): Promise<Service>;
-        /**
-         * Adds additional response details to the array.
-         *
-         * Adds links and federation:missing.
-         *
-         * @protected
-         * @param {Array.<*>} arr
-         * @param {object.<string, *>} response
-         * @returns {ResponseArray}
-         */
-        protected _toResponseArray(arr: Array<any>, response: object<string, any>): ResponseArray;
         /**
          * Get the a link with the given rel type.
          *
@@ -2407,7 +2657,7 @@ declare module OpenEO {
         protected _getLinkHref(links: Array<Link>, rel: string | Array<string>): string | null;
         /**
          * Makes all links in the list absolute.
-         * 
+         *
          * @param {Array.<Link>} links - An array of links.
          * @param {?string|AxiosResponse} [base=null] - The base url to use for relative links, or an response to derive the url from.
          * @returns {Array.<Link>}
@@ -2486,11 +2736,11 @@ declare module OpenEO {
         download(url: string, authorize: boolean): Promise<Readable | Blob>;
         /**
          * Get the authorization header for requests.
-         * 
+         *
          * @protected
          * @returns {object.<string, string>}
          */
-        protected _getAuthHeaders() : object<string, string>;
+        protected _getAuthHeaders(): object<string, string>;
         /**
          * Sends a HTTP request.
          *
@@ -2635,6 +2885,10 @@ declare module OpenEO {
     export type Collections = {
         collections: Array<Collection>;
         links: Array<Link>;
+        /**
+         * "federation:missing"] A list of backends from the federation that are missing in the response data.
+         */
+	"federation:missing": Array<string>;
     };
     export type Collection = object<string, any>;
     export type FileTypesAPI = {
@@ -2815,17 +3069,62 @@ declare module OpenEO {
          * EXPERIMENTAL!
          */
         namespaces: Array<string> | null;
+        /**
+         * "federation:missing"] A list of backends from the federation that are missing in the response data.
+         */
+	"federation:missing": Array<string>;
     };
     /**
      * An openEO processing chain.
      */
     export type Process = object<string, any>;
+    /**
+     * A back-end in the federation.
+     */
+    export type FederationBackend = {
+        /**
+         * ID of the back-end within the federation.
+         */
+        id: string;
+        /**
+         * URL to the versioned API endpoint of the back-end.
+         */
+        url: string;
+        /**
+         * Name of the back-end.
+         */
+        title: string;
+        /**
+         * A description of the back-end and its specifics.
+         */
+        description: string;
+        /**
+         * Current status of the back-end (online or offline).
+         */
+        status: string;
+        /**
+         * The time at which the status of the back-end was checked last, formatted as a RFC 3339 date-time.
+         */
+        last_status_check: string;
+        /**
+         * If the `status` is `offline`: The time at which the back-end was checked and available the last time. Otherwise, this is equal to the property `last_status_check`. Formatted as a RFC 3339 date-time.
+         */
+        last_successful_check: string;
+        /**
+         * Declares the back-end to be experimental.
+         */
+        experimental: boolean;
+        /**
+         * Declares the back-end to be deprecated.
+         */
+        deprecated: boolean;
+    };
     /**
      * An array, but enriched with additional details from an openEO API response.
      *
      * Adds two properties: `links` and `federation:missing`.
      */
-    export type ResponseArray = Array;
+    export type ResponseArray = any;
     export type ServiceType = object<string, any>;
     export type SyncResult = {
         /**
@@ -2864,7 +3163,12 @@ declare module OpenEO {
         budget: number | null;
         links: Array<Link> | null;
     };
-
+    /**
+     * An array, but enriched with additional details from an openEO API response.
+     *
+     * Adds the property `federation:backends`.
+     */
+    export type ValidationResult = any;
 }
 
 export = OpenEO;