@hestia-earth/caching-api 0.1.1 → 0.1.4

package/README.md

@@ -2,4 +2,68 @@
 
 ## Getting started
 
-TODO
+To use this API and querying the raster files, you need to download the assets first:
+
+### 1. Download the HESTIA assets (~1.9 GB, required)
+
+```bash
+mkdir -p assets
+curl -O https://hestia.earth/data/hestia-geospatial-assets.zip
+unzip hestia-geospatial-assets.zip -d assets
+```
+
+### 2. Download GADM boundaries (only for `gadm-ids` queries)
+
+**HESTIA cannot redistribute GADM**, so it comes from the source. Below is a script to run in your terminal to download the files:
+```bash
+mkdir -p assets/gadm
+
+for country in \
+  ABW AFG AGO AIA ALA ALB AND ARE ARG ARM ASM ATA ATF ATG AUS AUT AZE \
+  BDI BEL BEN BES BFA BGD BGR BHR BHS BIH BLM BLR BLZ BMU BOL BRA BRB \
+  BRN BTN BVT BWA CAF CAN CCK CHE CHL CHN CIV CMR COD COG COK COL COM \
+  CPV CRI CUB CUW CXR CYM CYP CZE DEU DJI DMA DNK DOM DZA ECU EGY ERI \
+  ESH ESP EST ETH FIN FJI FLK FRA FRO FSM GAB GBR GEO GGY GHA GIB GIN \
+  GLP GMB GNB GNQ GRC GRD GRL GTM GUF GUM GUY HKG HMD HND HRV HTI HUN \
+  IDN IMN IND IOT IRL IRN IRQ ISL ISR ITA JAM JEY JOR JPN KAZ KEN KGZ \
+  KHM KIR KNA KOR KWT LAO LBN LBR LBY LCA LIE LKA LSO LTU LUX LVA MAC \
+  MAF MAR MCO MDA MDG MDV MEX MHL MKD MLI MLT MMR MNE MNG MNP MOZ MRT \
+  MSR MTQ MUS MWI MYS MYT NAM NCL NER NFK NGA NIC NIU NLD NOR NPL NRU \
+  NZL OMN PAK PAN PCN PER PHL PLW PNG POL PRI PRK PRT PRY PSE PYF QAT \
+  REU ROU RUS RWA SAU SDN SEN SGP SGS SHN SJM SLB SLE SLV SMR SOM SPM \
+  SRB SSD STP SUR SVK SVN SWE SWZ SXM SYC SYR TCA TCD TGO THA TJK TKL \
+  TKM TLS TON TTO TUN TUR TUV TWN TZA UGA UKR UMI URY USA UZB VAT VCT \
+  VEN VGB VIR VNM VUT WLF WSM XAD XCA XCL XKO XNC XPI XSP YEM ZAF ZMB \
+  ZWE
+do
+  archive="assets/gadm/gadm36_${country}_shp.zip"
+  [ -f "$archive" ] && continue
+  curl -fsS -o "$archive" \
+    "https://geodata.ucdavis.edu/gadm/gadm3.6/shp/gadm36_${country}_shp.zip" \
+    || echo "failed: $country"
+done
+```
+
+You can also download the files on https://gadm.org/download_country36.html (the "Shapefile").
+
+### 3. Run the container
+
+```bash
+docker run -p 8000:80 \
+  -e API_TOKEN=<token> \
+  -e DATABASE_URL=<postgres-url> \
+  -v "$(pwd)/assets:/app/assets:ro" \
+  hestiae/hestia-caching-api
+```
+
+Allow ~800 MB of memory.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `API_TOKEN` | — | Admin token. Used to limit access to the whole API. Sent as the `X-API-KEY` header |
+| `DATABASE_URL` | — | PostgreSQL connection string |
+| `GEOSPATIAL_FOLDER` | `assets/ee` | Where the rasters are |
+| `GADM_FOLDER` | `assets/gadm` | Where the GADM archives are |
+| `GDAL_CACHEMAX` | `64` | Tile cache, MB. Left unset, GDAL takes 5% of *host* RAM and ignores the container limit |
+
+Note: the `docker-compose.yml` file is available to get started locally quicker.

package/index.d.ts

@@ -102,6 +102,136 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/tokens": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read All
+         * @description Lists all API tokens. Secrets are never returned.
+         */
+        get: operations["read_all_tokens_get"];
+        put?: never;
+        /**
+         * Create
+         * @description Creates a new API token. The plaintext token is returned once and is not
+         *     stored — save it now, it cannot be retrieved later.
+         */
+        post: operations["create_tokens_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/tokens/{token_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read One
+         * @description Retrieves a single API token by its id.
+         */
+        get: operations["read_one_tokens__token_id__get"];
+        put?: never;
+        post?: never;
+        /**
+         * Remove
+         * @description Deletes an API token.
+         */
+        delete: operations["remove_tokens__token_id__delete"];
+        options?: never;
+        head?: never;
+        /**
+         * Update
+         * @description Updates a token: rename, re-scope, renew (change expiry) or (de)activate it.
+         *     Does not rotate the secret.
+         */
+        patch: operations["update_tokens__token_id__patch"];
+        trace?: never;
+    };
+    "/tokens/{token_id}/reactivate": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Reactivate
+         * @description Reactivates a token, rotating its secret and returning the new plaintext.
+         *     The previous secret is invalidated immediately.
+         */
+        post: operations["reactivate_tokens__token_id__reactivate_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/geospatial/collections": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List Collections
+         * @description The collections this API can answer for.
+         *
+         *     Callers hold a mix: the ones HESTIA owns are served here, the public Earth
+         *     Engine ones are not. Since `/run` rejects a query it cannot answer *in
+         *     full*, a caller batching collections together needs to know the split up
+         *     front rather than discovering it from a 422.
+         */
+        get: operations["list_collections_geospatial_collections_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/geospatial/run": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run Query
+         * @description Samples the exported geospatial assets at coordinates, or reduces them over
+         *     boundaries or GADM regions.
+         *
+         *     Accepts the same payload as ``hestia_earth.earth_engine.run`` so the models
+         *     can call this instead, and returns the values in the same order:
+         *     geometry-major, one value per collection.
+         *
+         *     Only collections HESTIA owns are served here. Public Earth Engine
+         *     collections (ERA5, TERRACLIMATE, GMTED2010) are rejected rather than
+         *     silently returning nothing -- the caller is expected to route those to
+         *     Earth Engine.
+         */
+        post: operations["run_query_geospatial_run_post"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/version": {
         parameters: {
             query?: never;
@@ -140,6 +270,61 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /**
+         * Collection
+         * @description One collection to sample.
+         *
+         *     Mirrors the payload ``hestia_earth.earth_engine`` accepts so the models can
+         *     swap one for the other without reshaping the query. Fields beyond
+         *     ``collection`` (``band_name``, ``reducer``, ``name``, depth bounds) are
+         *     carried for compatibility and ignored when sampling by coordinates -- a
+         *     point needs no reduction, and the soil depth is already encoded in the
+         *     collection name.
+         */
+        Collection: {
+            /** Collection */
+            collection: string;
+        } & {
+            [key: string]: unknown;
+        };
+        /** Coordinate */
+        Coordinate: {
+            /** Latitude */
+            latitude: number;
+            /** Longitude */
+            longitude: number;
+        };
+        /**
+         * GeospatialQuery
+         * @description One of ``coordinates``, ``boundaries`` or ``gadm-ids``.
+         *
+         *     ``hestia_earth.earth_engine.run`` picks its mode from whichever key is
+         *     present, so the same payload works against either backend.
+         */
+        GeospatialQuery: {
+            /** Ee Type */
+            ee_type?: string | null;
+            /** Collections */
+            collections: components["schemas"]["Collection"][];
+            /** Coordinates */
+            coordinates?: components["schemas"]["Coordinate"][] | null;
+            /** Boundaries */
+            boundaries?: {
+                [key: string]: unknown;
+            }[] | null;
+            /** Gadm-Ids */
+            "gadm-ids"?: string[] | null;
+            /** Scale */
+            scale?: number | null;
+        };
+        /**
+         * GeospatialResults
+         * @description Values ordered coordinate-major: per coordinate, one per collection.
+         */
+        GeospatialResults: {
+            /** Results */
+            results: (number | null)[];
+        };
         /** HTTPValidationError */
         HTTPValidationError: {
             /** Detail */
@@ -190,6 +375,98 @@ export interface components {
             /** Offset */
             offset: number;
         };
+        /** TokenCreate */
+        TokenCreate: {
+            /** Name */
+            name: string;
+            /** Scopes */
+            scopes: string[];
+            /** Expires At */
+            expires_at?: string | null;
+        };
+        /** TokenOut */
+        TokenOut: {
+            /** Id */
+            id: string;
+            /** Name */
+            name: string;
+            /** Prefix */
+            prefix: string;
+            /** Scopes */
+            scopes: string[];
+            /** Is Active */
+            is_active: boolean;
+            /** Active */
+            active: boolean;
+            /** Expires At */
+            expires_at?: string | null;
+            /** Last Used At */
+            last_used_at?: string | null;
+            /**
+             * Created At
+             * Format: date-time
+             */
+            created_at: string;
+            /** Updated At */
+            updated_at?: string | null;
+        };
+        /**
+         * TokenReactivate
+         * @description Reactivation rotates the secret; an optional new expiry may be set
+         *     (null clears the expiry so the token never expires).
+         */
+        TokenReactivate: {
+            /** Expires At */
+            expires_at?: string | null;
+        };
+        /**
+         * TokenUpdate
+         * @description Partial update (rename, re-scope, renew expiry, (de)activate).
+         *
+         *     Does not rotate the secret; use the reactivate endpoint for that.
+         */
+        TokenUpdate: {
+            /** Name */
+            name?: string | null;
+            /** Scopes */
+            scopes?: string[] | null;
+            /** Expires At */
+            expires_at?: string | null;
+            /** Is Active */
+            is_active?: boolean | null;
+        };
+        /**
+         * TokenWithSecret
+         * @description Returned only on creation and reactivation: carries the plaintext token,
+         *     which is never stored and cannot be retrieved again.
+         */
+        TokenWithSecret: {
+            /** Id */
+            id: string;
+            /** Name */
+            name: string;
+            /** Prefix */
+            prefix: string;
+            /** Scopes */
+            scopes: string[];
+            /** Is Active */
+            is_active: boolean;
+            /** Active */
+            active: boolean;
+            /** Expires At */
+            expires_at?: string | null;
+            /** Last Used At */
+            last_used_at?: string | null;
+            /**
+             * Created At
+             * Format: date-time
+             */
+            created_at: string;
+            /** Updated At */
+            updated_at?: string | null;
+            /** Token */
+            token: string;
+        };
         /** ValidationError */
         ValidationError: {
             /** Location */
@@ -470,6 +747,244 @@ export interface operations {
             };
         };
     };
+    read_all_tokens_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenOut"][];
+                };
+            };
+        };
+    };
+    create_tokens_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TokenCreate"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenWithSecret"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    read_one_tokens__token_id__get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenOut"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    remove_tokens__token_id__delete: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    update_tokens__token_id__patch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["TokenUpdate"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenOut"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    reactivate_tokens__token_id__reactivate_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["TokenReactivate"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TokenWithSecret"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    list_collections_geospatial_collections_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
+        };
+    };
+    run_query_geospatial_run_post: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GeospatialQuery"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GeospatialResults"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     version_version_get: {
         parameters: {
             query?: never;