@epilot/sdk 2.4.4 → 2.5.0

package/definitions/customer-portal.json

@@ -733,8 +733,8 @@
             "schema": {
               "type": "string"
             },
-            "required": true,
-            "description": "Hook ID for consumption data."
+            "required": false,
+            "description": "Optional Hook ID. If omitted, the only matching hook on the extension is used; if the extension has multiple hooks of the relevant type, this becomes required."
           },
           {
             "in": "query",
@@ -818,17 +818,6 @@
                             "description": "Optional type of the consumption, such as 'nt' (night time) and 'ht' (high time) or 'feed-in' and 'feed-out'. Can be any string.",
                             "example": "nt"
                           },
-                          "aggregation_method": {
-                            "type": "string",
-                            "description": "The method used to aggregate the consumption data. Assumed default is 'sum'.",
-                            "enum": [
-                              "sum",
-                              "average",
-                              "max",
-                              "min"
-                            ],
-                            "example": "sum"
-                          },
                           "unit": {
                             "type": "string",
                             "description": "Optional unit of the consumption value. Defaults to unit present on the relevant Meter Counter.",
@@ -861,6 +850,178 @@
         }
       }
     },
+    "/v2/portal/visualization:export": {
+      "post": {
+        "operationId": "prepareVisualizationExport",
+        "summary": "Prepare Visualization Export",
+        "description": "Asks an installed App to prepare a downloadable export of a visualization (consumption chart, dynamic tariff chart, etc.). The export is produced by the third-party App via a configured portal extension hook of type `dataExport` — this endpoint does not generate the file itself, it forwards the request to the configured hook and returns the descriptor the App provides (typically a `download_url`).\n",
+        "tags": [
+          "ECP"
+        ],
+        "security": [
+          {
+            "PortalAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "app_id": {
+                    "type": "string",
+                    "description": "App ID providing the dataExport hook."
+                  },
+                  "extension_id": {
+                    "type": "string",
+                    "description": "Extension ID providing the dataExport hook."
+                  },
+                  "hook_id": {
+                    "type": "string",
+                    "description": "Optional Hook ID. If omitted, the only `dataExport` hook on the extension is used; if the extension has multiple `dataExport` hooks, this becomes required."
+                  },
+                  "from": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "Optional start date for the export window (ISO 8601 format)."
+                  },
+                  "to": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "Optional end date for the export window (ISO 8601 format)."
+                  },
+                  "context_entities": {
+                    "$ref": "#/components/schemas/ContextEntities"
+                  }
+                },
+                "required": [
+                  "app_id",
+                  "extension_id"
+                ],
+                "additionalProperties": false
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Export descriptor returned by the App.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "download_url": {
+                      "type": "string",
+                      "description": "URL the client can use to download the exported file. May be a pre-signed or short-lived URL."
+                    },
+                    "filename": {
+                      "type": "string",
+                      "description": "Suggested filename for the exported file."
+                    },
+                    "content_type": {
+                      "type": "string",
+                      "description": "MIME type of the exported file.",
+                      "example": "text/csv"
+                    },
+                    "expires_at": {
+                      "type": "string",
+                      "format": "date-time",
+                      "description": "Optional expiration timestamp for the download URL."
+                    }
+                  },
+                  "required": [
+                    "download_url"
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/portal/visualization/metadata": {
+      "get": {
+        "operationId": "getVisualizationMetadata",
+        "summary": "Get Visualization Metadata",
+        "description": "Returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). Resolves the extension's `visualizationMetadata` hook implicitly from `app_id` + `extensionId` and invokes it. Supplies the response as a structured payload that the portal uses to configure type/aggregation options, supported intervals, and the available data range.\n",
+        "tags": [
+          "ECP"
+        ],
+        "security": [
+          {
+            "PortalAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "app_id",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "App ID providing the visualizationMetadata hook."
+          },
+          {
+            "in": "query",
+            "name": "extensionId",
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "description": "Extension ID providing the visualizationMetadata hook."
+          },
+          {
+            "in": "query",
+            "name": "context_entities",
+            "required": false,
+            "description": "Entities to include in the context for variable interpolation in the hook (typically the meter and any other entities that scope the visualization).",
+            "schema": {
+              "$ref": "#/components/schemas/ContextEntities"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Visualization metadata returned successfully.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/VisualizationMetadata"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v2/portal/costs": {
       "get": {
         "operationId": "getCosts",
@@ -899,8 +1060,8 @@
             "schema": {
               "type": "string"
             },
-            "required": true,
-            "description": "Hook ID for cost data."
+            "required": false,
+            "description": "Optional Hook ID. If omitted, the only matching hook on the extension is used; if the extension has multiple hooks of the relevant type, this becomes required."
           },
           {
             "in": "query",
@@ -1073,8 +1234,8 @@
             "schema": {
               "type": "string"
             },
-            "required": true,
-            "description": "Hook ID for price data."
+            "required": false,
+            "description": "Optional Hook ID. If omitted, the only matching hook on the extension is used; if the extension has multiple hooks of the relevant type, this becomes required."
           },
           {
             "in": "query",
@@ -13492,6 +13653,12 @@
               "$ref": "#/components/schemas/DataRetrievalItem"
             }
           },
+          "dataExport": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DataRetrievalItem"
+            }
+          },
           "priceDataRetrieval": {
             "type": "array",
             "items": {
@@ -13531,6 +13698,9 @@
       "DataRetrievalItem": {
         "type": "object",
         "properties": {
+          "app": {
+            "$ref": "#/components/schemas/PublicAppDetails"
+          },
           "extension": {
             "$ref": "#/components/schemas/PublicExtensionDetails"
           },
@@ -13539,6 +13709,31 @@
           }
         }
       },
+      "PublicAppDetails": {
+        "type": "object",
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "description": "Identifier of the app."
+          },
+          "name": {
+            "type": "object",
+            "properties": {
+              "en": {
+                "type": "string",
+                "description": "Name of the app in English."
+              }
+            },
+            "additionalProperties": {
+              "type": "string",
+              "description": "Name of the app in some other language denoted by ISO 3166-1 alpha-2 code."
+            },
+            "required": [
+              "en"
+            ]
+          }
+        }
+      },
       "PublicExtensionDetails": {
         "type": "object",
         "properties": {
@@ -13589,10 +13784,121 @@
           },
           "intervals": {
             "type": "array",
+            "deprecated": true,
             "items": {
               "type": "string"
             },
-            "description": "The intervals associated with the hook."
+            "description": "Deprecated. Prefer fetching `intervals` from the `visualizationMetadata` endpoint\n(`GET /v2/portal/visualization/metadata`) so the supported intervals can vary per\nmeter/contract. Still emitted as a fallback for clients that have not migrated yet.\n"
+          },
+          "block_types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional list of portal block types the hook supports. Empty/missing means the hook is usable on any export-capable block."
+          }
+        }
+      },
+      "VisualizationMetadata": {
+        "type": "object",
+        "description": "Runtime metadata describing how a visualization should be rendered for a given portal context. Returned by `GET /v2/portal/visualization/metadata`.\n",
+        "properties": {
+          "type_options": {
+            "type": "array",
+            "description": "Types advertised for the current context (e.g. `ht`/`nt`, `feed-in`/`feed-out`). The `id` matches the `type` field returned by the data hook.\n",
+            "items": {
+              "$ref": "#/components/schemas/VisualizationTypeOption"
+            }
+          },
+          "intervals": {
+            "type": "array",
+            "description": "Intervals supported for the current context. If omitted, all intervals are assumed supported.",
+            "items": {
+              "type": "string",
+              "enum": [
+                "PT15M",
+                "PT1H",
+                "P1D",
+                "P1M"
+              ]
+            }
+          },
+          "data_range": {
+            "$ref": "#/components/schemas/VisualizationDataRange"
+          }
+        }
+      },
+      "VisualizationTypeOption": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Identifier of the type. Matches the `type` field on the data hook response."
+          },
+          "label": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Localized label for the type, keyed by ISO 3166-1 alpha-2 language code."
+          },
+          "aggregation_group": {
+            "type": "string",
+            "description": "Optional grouping key. Types in the same `aggregation_group` are visually combined; types in different groups (or without a group) render separately. How they combine depends on each type's `statistical_method`:\n  - bar chart (`sum`): same-group types are stacked into a single bar (e.g. ht/nt\n    summed into total consumption); different-group types render side-by-side.\n  - line chart (`min` / `average` / `max`): same-group types are rendered as an\n    area chart; different-group types render as separate lines.\n"
+          },
+          "statistical_method": {
+            "type": "string",
+            "enum": [
+              "sum",
+              "average",
+              "min",
+              "max"
+            ],
+            "description": "Statistical method already applied to this type's data. Determines the chart shape used to render the type's values: `sum` is shown as a bar chart; `min`, `average`, and `max` are shown as a line chart. Each type advertises its own method, so a single visualization can mix bar-shaped types with line-shaped types. Defaults to `sum` when omitted.\n"
+          },
+          "unit": {
+            "type": "string",
+            "description": "Unit shared by all values of this type (e.g. \"kWh\")."
+          },
+          "color": {
+            "type": "string",
+            "enum": [
+              "primary",
+              "slate",
+              "mauve",
+              "orange",
+              "red",
+              "tomato",
+              "amber",
+              "green",
+              "blue"
+            ],
+            "description": "Optional Spark color token used to render this type in the visualization. Maps onto the portal's Spark palette (`primary` is the org's primary brand color). When omitted the consumer falls back to its own per-type default.\n"
+          },
+          "precision": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10,
+            "description": "Optional number of decimal places to show when rendering values of this type in the visualization (axis labels, tooltips, summaries). When omitted the consumer falls back to its own default precision.\n"
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "VisualizationDataRange": {
+        "type": "object",
+        "description": "Earliest / latest timestamps for which data is available in the current context.",
+        "properties": {
+          "from": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the earliest available data point."
+          },
+          "to": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO 8601 timestamp of the latest available data point."
           }
         }
       },
@@ -13787,11 +14093,17 @@
                     {
                       "$ref": "#/components/schemas/ExtensionHookConsumptionDataRetrieval"
                     },
+                    {
+                      "$ref": "#/components/schemas/ExtensionHookDataExport"
+                    },
                     {
                       "$ref": "#/components/schemas/ExtensionHookCostDataRetrieval"
                     },
                     {
                       "$ref": "#/components/schemas/ExtensionHookMeterReadingPlausibilityCheck"
+                    },
+                    {
+                      "$ref": "#/components/schemas/ExtensionHookVisualizationMetadata"
                     }
                   ]
                 }
@@ -13950,7 +14262,8 @@
           },
           "use_static_ips": {
             "type": "boolean",
-            "description": "If true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
             "default": false
           },
           "secure_proxy": {
@@ -14052,7 +14365,8 @@
           },
           "use_static_ips": {
             "type": "boolean",
-            "description": "If true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
             "default": false
           },
           "secure_proxy": {
@@ -14162,7 +14476,8 @@
           },
           "use_static_ips": {
             "type": "boolean",
-            "description": "If true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
             "default": false
           },
           "secure_proxy": {
@@ -14240,7 +14555,8 @@
           },
           "use_static_ips": {
             "type": "boolean",
-            "description": "If true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
             "default": false
           },
           "secure_proxy": {
@@ -14317,7 +14633,162 @@
           },
           "use_static_ips": {
             "type": "boolean",
-            "description": "If true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
+            "default": false
+          },
+          "secure_proxy": {
+            "$ref": "#/components/schemas/SecureProxyConfig"
+          }
+        },
+        "required": [
+          "type",
+          "call"
+        ]
+      },
+      "ExtensionHookDataExport": {
+        "description": "Generic data export hook. When configured on a visualization block, the portal delegates the export action (e.g. CSV/Excel/PDF download) to the configured external source instead of generating the file itself. Can be used by any block that supports export — consumption charts, dynamic tariff charts, etc. The expected response to the call is:\n  - 200 with a JSON body describing the exported file (download_url, optional filename, content_type, expires_at)\n",
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "dataExport"
+            ]
+          },
+          "block_types": {
+            "type": "array",
+            "description": "Optional list of portal block types this hook supports. If omitted,\nthe hook is usable on any export-capable block. Allowed values match\nthe block type identifiers used by the portal builder\n(e.g. `consumption_visualization`, `dynamic_tariff`).\n",
+            "items": {
+              "type": "string"
+            }
+          },
+          "auth": {
+            "$ref": "#/components/schemas/ExtensionAuthBlock"
+          },
+          "call": {
+            "type": "object",
+            "properties": {
+              "method": {
+                "type": "string",
+                "description": "HTTP method to use for the call",
+                "default": "GET"
+              },
+              "url": {
+                "type": "string",
+                "description": "URL to call. Supports variable interpolation."
+              },
+              "params": {
+                "type": "object",
+                "description": "Parameters to append to the URL. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              },
+              "headers": {
+                "type": "object",
+                "description": "Headers to use. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              },
+              "body": {
+                "type": "object",
+                "description": "Request body to send. Supports variable interpolation. Content format is determined by Content-Type header.",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              }
+            },
+            "required": [
+              "url"
+            ]
+          },
+          "use_static_ips": {
+            "type": "boolean",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
+            "default": false
+          },
+          "secure_proxy": {
+            "$ref": "#/components/schemas/SecureProxyConfig"
+          }
+        },
+        "required": [
+          "type",
+          "call"
+        ]
+      },
+      "ExtensionHookVisualizationMetadata": {
+        "description": "Hook that returns runtime metadata describing how a visualization should be rendered for a given portal context. Invoked by the portal before fetching data, with the same context the data hook receives.\n",
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "visualizationMetadata"
+            ]
+          },
+          "auth": {
+            "$ref": "#/components/schemas/ExtensionAuthBlock"
+          },
+          "call": {
+            "type": "object",
+            "properties": {
+              "method": {
+                "type": "string",
+                "description": "HTTP method to use for the call",
+                "default": "GET"
+              },
+              "url": {
+                "type": "string",
+                "description": "URL to call. Supports variable interpolation."
+              },
+              "params": {
+                "type": "object",
+                "description": "Parameters to append to the URL. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              },
+              "headers": {
+                "type": "object",
+                "description": "Headers to use. Supports variable interpolation.",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              },
+              "body": {
+                "type": "object",
+                "description": "Request body to send. Supports variable interpolation. Content format is determined by Content-Type header.",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "default": {}
+              }
+            },
+            "required": [
+              "url"
+            ]
+          },
+          "resolved": {
+            "type": "object",
+            "properties": {
+              "dataPath": {
+                "type": "string",
+                "description": "Optional path to the metadata object in the response. If omitted, the metadata is assumed to be on the top level."
+              }
+            }
+          },
+          "use_static_ips": {
+            "type": "boolean",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
             "default": false
           },
           "secure_proxy": {
@@ -14394,7 +14865,8 @@
           },
           "use_static_ips": {
             "type": "boolean",
-            "description": "If true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.",
+            "deprecated": true,
+            "description": "Deprecated. Prefer `secure_proxy` instead.\nIf true, requests are made from a set of static IP addresses and only allow connections to a set of allowed IP addresses. Get in touch with us to add your IP addresses.\n",
             "default": false
           },
           "secure_proxy": {