From 2a14de7420b3a9c4d8d02fe8f5b00a9502c52da0 Mon Sep 17 00:00:00 2001
From: Matthias Mohr <webmaster@mamo-net.de>
Date: Wed, 28 Aug 2024 14:38:00 +0200
Subject: [PATCH] Better support for the federation extension

---
 openeo.d.ts         | 53 ++++++++++++++++++++++++++++++++++++++++++++-
 src/capabilities.js |  9 ++++++++
 src/typedefs.js     | 17 +++++++++++++++
 3 files changed, 78 insertions(+), 1 deletion(-)

diff --git a/openeo.d.ts b/openeo.d.ts
index 08af765..2aaee0f 100644
--- a/openeo.d.ts
+++ b/openeo.d.ts
@@ -395,6 +395,12 @@ 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>;
         /**
          * Lists all supported features.
          *
@@ -646,7 +652,7 @@ declare module OpenEO {
          * @public
          * @type {Array.<string>}
          */
-        public 'federation:missing': Array<string>;
+        public "federation:missing": Array<string>;
         /**
          * Returns the file types response as a JSON serializable representation of the data that is API compliant.
          *
@@ -2635,6 +2641,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,11 +2825,52 @@ 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>;
+    /**
+     * An array of backends in the federation.
+     */
+    export type FederationBackend = {
+        /**
+         * 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-ends (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.
      *
diff --git a/src/capabilities.js b/src/capabilities.js
index 41b6f8c..cd7cd0c 100644
--- a/src/capabilities.js
+++ b/src/capabilities.js
@@ -192,6 +192,15 @@ class Capabilities {
 		return Array.isArray(this.data.links) ? this.data.links : [];
 	}
 
+	/**
+	 * Returns list of backends in the federation.
+	 * 
+	 * @returns {Array.<FederationBackend>} Array of backends
+	 */
+	listFederation() {
+		return Array.isArray(this.data.federation) ? this.data.federation : [];
+	}
+
 	/**
 	 * Lists all supported features.
 	 * 
diff --git a/src/typedefs.js b/src/typedefs.js
index 93314b9..fb0d39f 100644
--- a/src/typedefs.js
+++ b/src/typedefs.js
@@ -47,6 +47,7 @@
  * @type {object}
  * @property {Array.<Collection>} collections
  * @property {Array.<Link>} links
+ * @property {Array.<string>} ["federation:missing"] A list of backends from the federation that are missing in the response data.
  */
 
 /**
@@ -184,6 +185,7 @@
  * @property {Array.<Process>} processes
  * @property {Array.<Link>} links
  * @property {?Array.<string>} namespaces EXPERIMENTAL!
+ * @property {Array.<string>} ["federation:missing"] A list of backends from the federation that are missing in the response data.
  */
 
 /**
@@ -193,6 +195,21 @@
  * @type {object.<string, *>} 
  */
 
+/**
+ * An array of backends in the federation.
+ * 
+ * @typedef FederationBackend
+ * @type {Object}
+ * @property {string} url URL to the versioned API endpoint of the back-end.
+ * @property {string} title Name of the back-end.
+ * @property {string} description A description of the back-end and its specifics.
+ * @property {string} status Current status of the back-ends (online or offline).
+ * @property {string} last_status_check The time at which the status of the back-end was checked last, formatted as a RFC 3339 date-time.
+ * @property {string} last_successful_check 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.
+ * @property {boolean} experimental Declares the back-end to be experimental.
+ * @property {boolean} deprecated Declares the back-end to be deprecated.
+ */
+
 /**
  * An array, but enriched with additional details from an openEO API response.
  *